> 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/quick-start.md). # 叙事设计快速开始向 Convai 角色添加 Narrative Design Manager 和碰撞触发器，并在播放模式下确认章节切换——无需代码。本指南将带你走完搭建可用的 Narrative Design 的最快路径。到最后，当玩家穿过触发区域时，角色会对章节切换作出反应——完全通过检查器完成，无需代码。 ### 前置条件开始之前，请确认： * [ ] 一个 `ConvaiCharacter` 位于场景中，并且其 Character ID 已在检查器中设置 * [ ] 该角色在……上至少定义了一个 section 和一个 trigger [Convai 仪表板](https://convai.com) ### 设置管理器和触发器 {% stepper %} {% step %} #### 添加 Narrative Design Manager 选择拥有你的 `ConvaiCharacter` 组件的 GameObject。在检查器中，点击 **添加组件** 中搜索 **Narrative Design Manager** （路径： **Convai > Narrative Design Manager**). 管理器会自动检测 `ConvaiCharacter` 位于同一个 GameObject 上。如果你的角色位于不同的 GameObject 上，请将它拖到 **Character** 字段。

ConvaiNarrativeDesignManager added to the character GameObject in the Unity Inspector — 角色的 GameObject 上的 ConvaiNarrativeDesignManager。

{% endstep %} {% step %} #### 从仪表板同步章节在管理器的检查器中，点击 **与后端同步**。SDK 会获取你的叙事章节并填充 **叙事章节** 列表。每个条目都会显示仪表板中的章节名称。如果列表仍然为空，请确认角色 ID 已设置在 `ConvaiCharacter` 上，并且你的 API 密钥有效——参见 [配置 API 密钥](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-api-key.md)。 **上次获取错误** 字段会在出错时显示具体错误。

Narrative Sections list populated after clicking Sync with Backend — 成功同步后的 Narrative Sections 列表。

{% endstep %} {% step %} #### 连接章节事件展开 **叙事章节** 列表中的第一个章节条目。你会看到两个 Unity 事件： **On Section Start** 和 **On Section End**. 点击 **+** 在 **On Section Start**，将任意 GameObject 拖到对象字段中，并选择要调用的方法。测试时最简单的选项是 `NarrativeDesignDebugLogger` 下面的辅助器——把它添加到任意 GameObject 中，将该 GameObject 拖到监听器字段里，并选择 `NarrativeDesignDebugLogger.LogSectionStarted`.

NarrativeDesignDebugLogger.cs

```csharp using UnityEngine; public class NarrativeDesignDebugLogger : MonoBehaviour { [SerializeField] private string _label = "Section"; /// 绑定到 UnitySectionEventConfig.OnSectionStart Unity 事件。 public void LogSectionStarted() { Debug.Log($"[NarrativeDesign] {_label} started.", this); } /// 绑定到 ConvaiNarrativeDesignManager.OnAnySectionChanged Unity 事件。 /// 接收新的 section ID，类型为字符串。 public void LogSectionChanged(string sectionId) { Debug.Log($"[NarrativeDesign] Section changed → {sectionId}", this); } } ```

On Section Start Unity Event wired to a debug logger component — On Section Start 已绑定到 NarrativeDesignDebugLogger。

{% endstep %} {% step %} #### 添加 Narrative Design Trigger 在场景中创建一个新的空 GameObject，并将其放置在玩家会经过的位置。点击 **添加组件** 中搜索 **Convai Narrative Design Trigger** （路径： **Convai > Convai Narrative Design Trigger**). 将你的 `ConvaiCharacter` 到 **Character** 字段中，或者将其留空以让 **自动查找角色** 自动定位它。

ConvaiNarrativeDesignTrigger added to an empty GameObject in the scene — 世界空间触发器 GameObject 上的 ConvaiNarrativeDesignTrigger。

{% endstep %} {% step %} #### 获取并选择一个触发器在触发器组件的检查器中，点击 **获取** 以从仪表板加载已命名的触发器。随后会出现一个下拉菜单——选择应将图表推进到第一个章节的触发器。

Trigger Selection dropdown populated after clicking Fetch — 从 Convai 仪表板填充后的触发器下拉菜单。

{% endstep %} {% step %} #### 添加碰撞体默认的激活模式是 **碰撞**，它使用 Unity 的 `OnTriggerEnter`。在同一个触发器 GameObject 上，点击 **添加组件 > Box Collider**。在 Box Collider 的设置中，启用 **Is Trigger**. 调整碰撞体大小以覆盖你希望触发器生效的区域。在场景视图中，绿色线框框显示检测区域。

Box Collider with Is Trigger enabled on the trigger zone GameObject — 启用 Is Trigger 的 Box Collider。

{% endstep %} {% step %} #### 按下 Play 并穿过 {% hint style="warning" %} **玩家设置清单——在按下 Play 之前请先确认这三项：** * **标签：** 玩家 GameObject 的标签必须设置为 `Player`。触发器组件会通过标签匹配来识别玩家。 * **碰撞体：** 玩家必须有一个 Collider 组件。没有它， `OnTriggerEnter` 将永远不会触发。 * **刚体：** 触发区域或玩家必须有一个 `Rigidbody`。把它添加到玩家上——如果你把它添加到触发区域上，那么场景中的每个触发器对象都必须重复这样做。缺少其中任何一项，都是 Play Mode 中看起来毫无反应的最常见原因。 {% endhint %} 进入 Play Mode，并让玩家穿过碰撞区域。 {% hint style="success" %} 当玩家进入该区域时，section ID 会显示在控制台中。角色的下一条回复会反映新章节的目标。 {% endhint %} {% endstep %} {% endstepper %} ### 这个设置最终产生了什么穿过碰撞区域后，完整的 Narrative Design 流程被激活：该 `ConvaiNarrativeDesignTrigger` 通过以下方式检测到了玩家 `OnTriggerEnter` 并调用了 `InvokeTrigger()` ，使用你选择的触发器名称。SDK 会在角色的实时会话开启前先将该触发器排队，然后发送一个 `trigger-message` 通过 RTVI 连接发送到 Convai。Convai 沿匹配的边推进叙事图，并返回一个 `behavior-tree-response` ，其中包含新的 section ID。 `ConvaiNarrativeDesignManager` 将该 section ID 与本地列表进行匹配，并在 `OnSectionStart` 对应条目上触发。如需了解该流程的完整说明，请参见 [叙事设计如何工作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/how-narrative-design-works.md). ### 下一步 {% 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 %} {% content-ref url="/pages/630c1743293b81e62f2237b571dcf928c0d73285" %} [配置叙事模板键](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/template-keys-dynamic-narrative-variables.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/quick-start.md?ask=&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.