> 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/unity-plugin-beta-overview/features/narrative-design.md).

# Narrative Design

## 什么是叙事设计？

叙事设计为你的 Convai AI 角色提供一个可遵循的结构化故事。你在 Convai 仪表板中编写一个由 **章节** （故事节拍）和 **触发器** （它们之间的边）组成的图。在运行时，SDK 会监听服务器的章节变更信号，并触发你配置的 Unity 事件——无需轮询，也无需手动状态机。

角色的行为、知识和对话目标会自动适应当前章节，因此同一个角色可以在开场章节中扮演一名中立的接待员，而在评估章节中扮演一名严厉的考官，全部都在同一次会话中完成。

## 运行时的工作方式

当玩家激活某个触发器时，SDK 会向 Convai 后端发送一个命名信号。后端推进故事图，并返回一个 `behavior-tree-response` 消息，其中携带新的章节 ID 和任何相关的行为树数据。SDK 会将此消息转换为一个 `NarrativeSectionChanged` 领域事件，并将其传递给 `ConvaiNarrativeDesignManager`，后者会触发你在 Inspector 中连接的按章节 Unity 事件。

```mermaid
sequenceDiagram
    participant Player
    participant Trigger as ConvaiNarrativeDesignTrigger
    participant Char as ConvaiCharacter (RTVI)
    participant Backend as Convai Backend
    participant Manager as ConvaiNarrativeDesignManager
    participant Scene as Your 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()
```

## 三个构建模块

<table><thead><tr><th width="267.6666259765625">组件</th><th width="240">所在位置</th><th>它的作用</th></tr></thead><tbody><tr><td><code>ConvaiNarrativeDesignManager</code></td><td>在角色 GameObject 上</td><td>监听章节变更，触发按章节的 <code>OnSectionStart</code> / <code>OnSectionEnd</code> Unity 事件，管理模板键</td></tr><tr><td><code>ConvaiNarrativeDesignTrigger</code></td><td>在任意世界 GameObject 上</td><td>在激活时向角色发送一个命名触发器（碰撞、接近、计时器或手动）</td></tr><tr><td><code>IConvaiNarrativeDesign</code></td><td>通过以下方式访问 <code>convaiCharacter.NarrativeDesign</code></td><td>面向角色作用域的 C# API，用于通过代码触发触发器、控制模板键以及异步获取数据</td></tr></tbody></table>

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

## 关键概念

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

## 先决条件

{% hint style="info" %}
在项目中使用叙事设计之前，请确保：

* 已导入 Convai Unity SDK，并且场景中存在一个 `ConvaiCharacter` 组件。
* 你已经在 [Convai 仪表板](https://convai.com) 中创建了一个叙事图，至少包含一个章节和一个触发器。
* 你的角色 ID 已设置在 `ConvaiCharacter` 组件上——没有它，SDK 无法获取或响应章节。
  {% endhint %}

## 放在哪里

弄清楚哪个组件该放在哪个 GameObject 上，可以避免最常见的设置错误。

| 组件                             | 放置位置                                           | 每个场景中的典型数量 |
| ------------------------------ | ---------------------------------------------- | ---------- |
| `ConvaiNarrativeDesignManager` | 在 **角色的** GameObject 上，旁边还有 `ConvaiCharacter`  | 每个角色一个     |
| `ConvaiNarrativeDesignTrigger` | 开启 **任何世界 GameObject** ——一扇门、一个展品、一个 UI 事件目标   | 每个图转换点一个   |
| `IConvaiNarrativeDesign`       | 不放置——通过 `convaiCharacter.NarrativeDesign` 在代码中 | 不适用        |

## 本节内容

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>快速入门</strong></td><td>只需几分钟，无需代码，即可让角色对章节变化做出响应。</td></tr><tr><td><strong>设置 Narrative Design Manager</strong></td><td>添加、同步并配置 Manager 组件——它是章节转换的监听站。</td></tr><tr><td><strong>设置 Narrative Design 触发器</strong></td><td>放置带有碰撞、接近、计时器或手动激活的世界触发器。</td></tr><tr><td><strong>模板键：动态叙事变量</strong></td><td>从 Inspector 或代码中将运行时值注入角色的叙事目标。</td></tr><tr><td><strong>编写 Narrative Design 脚本</strong></td><td>IConvaiNarrativeDesign、NarrativeDesignFetcher 以及程序化控制的完整 C# API 参考。</td></tr><tr><td><strong>使用示例</strong></td><td>四个随复杂度递增的示例——从简单的欢迎流程到自适应的多章节场景。</td></tr><tr><td><strong>故障排查与诊断</strong></td><td>诊断每一种 TriggerStatus 状态、常见配置错误以及获取失败。</td></tr></tbody></table>

## 结论

叙事设计为你的 Convai 角色提供一个结构化、可响应的故事，无需任何自定义状态机代码。三个组件——Manager、Trigger 和 `IConvaiNarrativeDesign` 接口——涵盖了从单按钮信息亭到完全自适应的多步骤场景的一切需求。先从快速开始入手，在几分钟内完成可用配置，然后随着需求增长再深入探索更详细的配置指南。


---

# 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/unity-plugin-beta-overview/features/narrative-design.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.