> 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 管线——各部分、触发器和模板键在运行时如何连接以推进故事图。

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

### 运行时管线如何工作

当玩家激活触发器时，SDK 会向 Convai 发送一个带名称的信号。Convai 推进故事图并返回一个 `behavior-tree-response` 携带新章节 ID 的消息。SDK 将其转换为一个 `NarrativeSectionChanged` 领域事件，并将其传递给 `ConvaiNarrativeDesignManager`，并触发你在 Inspector 中接好的按章节 Unity Events。

```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 Events 的路径。

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

### 章节与触发器

**章节** 是在 Convai 仪表板中定义的命名故事节点。角色的目标、知识和对话行为会随当前活动章节而变化。单个角色可以在开场章节中扮演一名中立接待员，在考核章节中扮演一名严格的考官——都在同一个会话中——因为当前活动章节决定了后端返回的内容。

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

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

### SDK 的三个组件

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

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

### 关键概念

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

### 组件放置

了解哪个组件应放在哪个 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 dynamically by asking a question.

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

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.