> 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-unity-sdk/features/narrative-design/how-narrative-design-works.md).

# 叙事设计的工作原理

了解 Narrative Design 管线——各部分、触发器和模板键在运行时如何连接以推进故事图。

Narrative Design 为 Convai 角色提供一条结构化的故事线供其遵循。你在 Convai 仪表板中编写一个由各节和触发器组成的图；在运行时，SDK 会监听来自 Convai 的节变更信号，并触发你配置的 Unity Events——无需轮询，无需自定义状态机。本页解释其底层模型：原语是什么，触发器如何推进图，以及 SDK 的哪个组件负责流水线的每一部分。

### 运行时流水线如何工作

当玩家激活触发器时，SDK 会向 Convai 发送一个命名信号。Convai 推进故事图，并返回一个 `behavior-tree-response` 携带新的 section ID 的 `NarrativeSectionChanged` 域事件，并将其传递给 `ConvaiNarrativeDesignManager`，后者会触发你在 Inspector 中连接的按节 Unity 事件。

```mermaid
sequenceDiagram
    参与者 Player
    参与者 Trigger 作为 ConvaiNarrativeDesignTrigger
    参与者 Char 作为 ConvaiCharacter（RTVI）
    参与者 Backend 作为 Convai
    参与者 Hub 作为事件中心
    参与者 Manager 作为 ConvaiNarrativeDesignManager
    参与者 Scene 作为你的场景

    Player->>Trigger: 进入区域 / 调用 InvokeTrigger()
    Trigger->>Char: InvokeTrigger(triggerName, message)
    Char->>Backend: 触发器消息（RTVI）
    Backend-->>Char: 行为树响应（sectionId, btCode）
    Char->>Hub: 发布 NarrativeSectionChanged
    Hub-->>Manager: NarrativeSectionChanged 事件
    Manager->>Scene: UnitySectionEventConfig.OnSectionStart.Invoke()
```

`ConvaiCharacter` 也会订阅 `NarrativeSectionChanged` 通过同一个事件中心独立地处理，并与 `ConvaiNarrativeDesignManager` —— 上方图示仅展示到达你的场景 Unity 事件的路径。

如果角色的实时会话尚未打开，触发器会自动排队，并在连接建立时刷新。你无需在调用前检查会话状态 `InvokeTrigger()`.

### 节与触发器

**节** 是在 Convai 仪表板中定义的命名故事节点。角色的目标、知识和对话行为会适应当前激活的节。一个角色可以在开场节中扮演中性的接待员，并在评估节中扮演严格的考官——全部都在同一个会话内——因为当前激活的节决定了后端返回的内容。

**触发器** 是故事图中的有向边。发送一个同名触发器会沿着匹配的边，将图从一个节推进到下一个节。触发器可携带一个可选的消息负载，为转换提供上下文——例如， `“玩家已完成安全检查清单”` —— 角色可以将其纳入下一次回复。

模板键是运行时键值对，用于填充仪表板叙事目标中的占位符。设置 `{PlayerName}` 到 `“Alex”` ，则所有引用 `{PlayerName}` 的节都会使用当前值，无需任何图更改。

### 三个 SDK 组件

| 组件                             | 所在位置                                       | 它的作用                                                         |
| ------------------------------ | ------------------------------------------ | ------------------------------------------------------------ |
| `ConvaiNarrativeDesignManager` | 位于角色的 GameObject 上                         | 监听节变更，触发按节 `OnSectionStart` / `OnSectionEnd` Unity 事件，并管理模板键 |
| `ConvaiNarrativeDesignTrigger` | 位于任意场景 GameObject 上                        | 在激活时向角色发送命名触发器（碰撞、接近、计时器或手动）                                 |
| `IConvaiNarrativeDesign`       | 通过以下方式访问 `convaiCharacter.NarrativeDesign` | 角色作用域的 C# API，用于触发器调用、模板键控制和异步数据获取                           |

你可以任意组合使用。大多数项目会三者都用。简单的线性叙事可能只需要 Manager 和一两个 Trigger。

### 关键概念

| 术语        | 定义                                                                          |
| --------- | --------------------------------------------------------------------------- |
| **部分**    | Convai 仪表板中的一个命名故事节点。角色的目标和行为会适应当前激活的节。                                     |
| **触发器**   | 故事图中的一个命名边。发送触发器会将图从一个节推进到下一个节。                                             |
| **模板键**   | 运行时键值对（例如， `PlayerName = "Alex"`）用于填充 `{placeholder}` 仪表板叙事目标中的文本。          |
| **孤立章节**  | 在本地同步后从仪表板中删除的章节。其 Unity Events 会被保留，但在该章节恢复并重新同步之前不会触发。                    |
| **行为树响应** | 携带新 `SectionId` 以及可选的 `BehaviorTreeCode` 和 `BehaviorTreeConstants` 供高级集成使用。 |

### 组件放置

了解哪个组件该放在哪个 GameObject 上，可避免最常见的设置错误。

| 组件                             | 放置位置                                                 | 每个场景的典型数量 |
| ------------------------------ | ---------------------------------------------------- | --------- |
| `ConvaiNarrativeDesignManager` | 在 **角色的** GameObject，以及 `ConvaiCharacter`            | 每个角色一个    |
| `ConvaiNarrativeDesignTrigger` | 当 **任意场景 GameObject** —— 一个门口、一个展品或一个 UI 事件目标        | 每个图转换点一个  |
| `IConvaiNarrativeDesign`       | 不放置——通过以下方式访问 `convaiCharacter.NarrativeDesign` 在代码中 | 不适用       |

### 下一步

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

{% content-ref url="/pages/59d31b624a51d8790cd9e50732a32794dcfd69f1" %}
[配置叙事设计管理器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/setting-up-the-narrative-design-manager.md)
{% endcontent-ref %}

{% content-ref url="/pages/87ddb3e30dd1b009eb7bf39b583b5a654f486dbb" %}
[配置叙事设计触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/setting-up-narrative-design-triggers.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-unity-sdk/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.