> 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 仪表板中编写由各个 section 和 trigger 组成的图；运行时，SDK 监听来自 Convai 的 section 变更信号，并触发你配置的 Unity Events——无需轮询，无需自定义状态机。本页解释其底层模型：原语是什么、trigger 如何推进图，以及 SDK 的哪个组件负责流程中的每一部分。

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

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

```mermaid
sequenceDiagram
    参与者 Player
    参与者 Trigger 作为 ConvaiNarrativeDesignTrigger
    参与者 Char 作为 ConvaiCharacter (RTVI)
    参与者 Backend 作为 Convai Backend
    参与者 Manager 作为 ConvaiNarrativeDesignManager
    参与者 Scene 作为你的场景

    Player->>Trigger：进入区域 / 调用 InvokeTrigger()
    Trigger->>Char：InvokeTrigger(triggerName, message)
    Char->>Backend：trigger-message (RTVI)
    Backend-->>Char：behavior-tree-response (sectionId, btCode)
    Char-->>Manager：NarrativeSectionChanged 事件
    Manager->>Scene：UnitySectionEventConfig.OnSectionStart.Invoke()
```

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

### 章节与触发器

**章节** 是在 Convai 仪表板中定义的带名称的故事节点。角色的目标、知识和对话行为会适配当前激活的 section。一个角色可以在开场 section 中扮演中性的接待员，在考核 section 中扮演严格的考官——全都在一次会话中完成——因为当前激活的 section 会决定后端返回什么。

**触发器** 是故事图中的有向边。按名称发送一个 trigger 会沿着匹配的边将图从一个 section 推进到下一个 section。trigger 可以携带一个可选的消息负载，用于提供转换上下文——例如， `“Player completed the safety checklist”` ——角色可以将其纳入下一次回应中。

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

### SDK 的三个组件

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

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

### 核心概念

| 术语               | 定义                                                                           |
| ---------------- | ---------------------------------------------------------------------------- |
| **部分**           | Convai 仪表板中的一个带名称的故事节点。角色的目标和行为会随激活的 section 调整。                             |
| **触发器**          | 故事图中的一个带名称的边。发送一个 trigger 会将图从一个 section 推进到下一个 section。                     |
| **Template key** | 一个运行时键值对（例如， `PlayerName = "Alex"`）用于填充 `{placeholder}` 仪表板叙事目标中的文本。         |
| **孤立的 section**  | 在本地同步后又从仪表板中删除的 section。其 Unity Events 会被保留，但在该 section 恢复并重新同步之前都不会触发。      |
| **行为树响应**        | 携带新的 `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 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-unity-sdk/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.