> 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_name` 在你的 Blueprint 中必须与仪表板完全一致。                                                  | Convai 仪表板                 |
| 模板键 | 运行时键值对，位于 `NarrativeTemplateKeys` 聊天机器人组件上。插件通过 `update-template-keys`将映射发送到 Convai。仪表板目标可以引用 `{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_name` 发送给 Convai。如果已断开连接，该调用会排队到 `PendingTriggers` 中，并在连接后重放。
3. Convai 会根据当前章节的外向触发器来评估该触发器。匹配后，Convai 会激活目标章节。
4. 激活章节的 `目标` 会塑造角色接下来的行为。
5. 当对话继续时，玩家的回答会根据章节的 `决策` 进行评估。
6. Convai 会返回一个 `BTResponse` 数据包，其中包含 `narrative_section_id` ，当章节更新被传递时。
7. **收到叙事章节时触发** 会在聊天机器人组件上触发，并带有 `NarrativeSectionID`.

```mermaid
graph TD
    A["Blueprint 调用叙事设计触发器"] --> B{"会话已连接？"}
    B -->|否| C["排队到 PendingTriggers"]
    C --> D["在会话连接后重放"]
    D --> E["向 Convai 发送 trigger_name"]
    B -->|是| E
    E --> F["Convai 根据当前章节评估触发器"]
    F --> G["目标章节变为激活状态"]
    G --> H["章节目标塑造角色响应"]
    H --> I["根据决策评估玩家回答"]
    I --> J["Convai 返回带有 narrative_section_id 的 BTResponse"]
    J --> K["收到叙事章节时触发"]
```

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

### 两个 Blueprint 函数

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

| 函数            | 发送给 Convai                  | 何时使用                                           |
| ------------- | --------------------------- | ---------------------------------------------- |
| **调用叙事设计触发器** | `触发消息` 其带有 `trigger_name`   | 当过渡目标在设计时已知，并且仪表板中的触发器名称是固定的时。                 |
| **调用语音**      | 通过动态上下文事件 `AddContextEvent` | 消息在运行时组装，你希望 Convai 将其作为对话上下文处理，而不是匹配仪表板触发器名称。 |

命名触发器会在 `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>` on `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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.