> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/how-narrative-design-works.md).

# 叙事设计的工作原理

了解叙事设计故事图、推进区段的运行时管道，以及触发器和模板键如何塑造角色行为。

叙事设计为 Convai 角色提供一个结构化的故事图——包含命名的章节以及在它们之间切换的触发器——这些内容在 Convai 仪表板中编写，并在运行时通过 `UConvaiChatbotComponent`。本页说明心智模型和运行时流水线。对于动手配置，请从 [叙事设计快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-quick-start.md).

### 故事图模型

叙事设计图有三个构建块，你会在 Unreal Engine 中使用它们。

| 概念      | 它是什么                                                                                        | 你在哪里配置它                    |
| ------- | ------------------------------------------------------------------------------------------- | -------------------------- |
| 章节      | 一个带有 `目标` 的命名故事节点，用于塑造角色行为。每个章节都有一个 `section_id`.                                           | Convai 仪表板                 |
| Trigger | 一个命名边，用于激活目标章节。 `trigger_name` 在你的 Blueprint 中必须与仪表板完全一致。                                   | Convai 仪表板                 |
| 模板键     | 运行时键值对，位于 `NarrativeTemplateKeys` 聊天机器人组件上的 `update-template-keys`。仪表板中的目标可以引用 `{key}` 占位符。 | Blueprint 或 **Details** 面板 |

角色会停留在当前章节，直到 **调用叙事设计触发器** 激活另一个章节。之后该章节成为活动章节后，玩家的回答和该章节的决策会引导下一次在图中的切换。参见 `FNarrativeDecision` 在 [叙事设计 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-blueprint-reference.md) 查看决策结构体字段。

在 Convai 仪表板中编写章节、触发器和进入行为。参见 [叙事设计 | Playground](/api-docs/zh/convai-playground/character-customization/narrative-design.md) 查看图编写指南。

### 命名触发器的运行时流水线

从调用命名触发器到章节变更的标准路径：

1. Blueprint 调用 **调用叙事设计触发器** 并传入一个 `TriggerName` 字符串。
2. 如果会话已连接，组件会发送一个 `trigger-message` 数据包，其中包含 `trigger_name` 发送给 Convai。若未连接，该调用会排入 `PendingTriggers` ，并在连接后重放。
3. Convai 会将该触发器与当前章节的外发触发器进行匹配。匹配成功后，Convai 会激活目标章节。
4. 活动章节的 `目标` 塑造角色的下一步行为。
5. 玩家的回答会在继续对话时依据该章节的 `决策` 进行评估。
6. Convai 返回一个 `BTResponse` 数据包，其中包含 `narrative_section_id` ，表示已传递章节更新时。
7. **收到叙事章节** 会在聊天机器人组件上触发，带有 `NarrativeSectionID`.

```mermaid
graph TD
    A["Blueprint 调用 Invoke Narrative Design Trigger"] --> B{"会话已连接？"}
    B -->|否| C["排入 PendingTriggers"]
    C --> D["会话连接后重放"]
    D --> E["将 trigger_name 发送给 Convai"]
    B -->|是| E
    E --> F["Convai 根据当前章节评估触发器"]
    F --> G["目标章节变为活动状态"]
    G --> H["章节目标塑造角色响应"]
    H --> I["根据决策评估玩家回答"]
    I --> J["Convai 返回带有 narrative_section_id 的 BTResponse"]
    J --> K["On Narrative Section Received 触发"]
```

**收到叙事章节** 仅在 Convai 通过 `BTResponse`。它不会在调用触发函数时触发。有关逐步触发调用，请参见 [叙事触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-triggers.md).

### 两个 Blueprint 函数

`UConvaiChatbotComponent` 提供两个相关函数，它们使用不同的运行时路径。

| 函数            | 发送到 Convai                          | 适用于                          |
| ------------- | ----------------------------------- | ---------------------------- |
| **调用叙事设计触发器** | `trigger-message` 使用 `trigger_name` | 过渡目标在设计时已知，并且触发器名称在仪表板中是固定的。 |
| **调用语音**      | 通过 `AddContextEvent`                | 动态上下文事件                      |

命名触发器会排入 `PendingTriggers` ，前提是处于断开连接状态。 **调用语音** 不使用该队列。如果 Convai 返回一个，则两条路径都可能产生章节变化 `BTResponse` 并传入一个 `narrative_section_id`.

参见 [叙事触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-triggers.md) ，用于输入参数、待处理队列行为，以及何时选择每个函数。

### 模板键

`NarrativeTemplateKeys` 是一个 `TMap<FString, FString>` 在 `UConvaiChatbotComponent` 位于 **Convai|NarrativeDesign**下。将键与 `{key}` 仪表板目标中的占位符匹配的条目分配进去。

例如，如果仪表板目标写着 `引导 {PlayerName} 完成安全检查`，请在 `PlayerName = "Rivera"` 为 `NarrativeTemplateKeys` 添加到推进到该章节的触发器之前。

插件会在会话连接时发送模板键，并且在你分配 `NarrativeTemplateKeys` 时只要处于连接状态也会发送。请在调用会推进到其目标引用这些键的章节的触发器之前设置键。参见 [模板键](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/template-keys.md) 进行设置和验证。

### 在仪表板中验证触发器名称

在 Blueprint 中硬编码触发器名称之前，请在 Convai 仪表板中打开角色的叙事图，并逐个复制每个 `trigger_name` ，确保其与作者定义完全一致。确认该触发器是角色起始章节的一个外发边。参见 [叙事设计 | Playground](/api-docs/zh/convai-playground/character-customization/narrative-design.md).

### 在运行时查询叙事数据

可通过查询角色的完整章节和触发器列表，使用 **Convai 获取叙事章节** 和 **Convai 获取叙事触发器** 位于 **Convai|REST API**。使用这些节点来验证触发器名称或填充游戏内 UI——不要把它们作为主要的故事推进路径。参见 [获取叙事数据](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/fetching-narrative-data.md).

### 下一步

{% content-ref url="/pages/fc5915683cbb3a9ae3782e4de53c3288e9e3b7cc" %}
[叙事设计快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/ff19704aac20f7d6e4bf5c3214636ccbe4248151" %}
[叙事触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-triggers.md)
{% endcontent-ref %}

{% content-ref url="/pages/579f95b35d1b473357f37588e6fc915a03231497" %}
[叙事设计 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-blueprint-reference.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/how-narrative-design-works.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.