> 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/setting-up-the-narrative-design-manager.md). # 配置叙事设计管理器 `ConvaiNarrativeDesignManager` 是角色上的常驻监听点。它订阅来自 Convai 的章节变更信号，并将其转发到你在 Inspector 中配置的 Unity Events。每个角色一个 Manager 是标准设置；它在场景生命周期内驻留于角色的 GameObject 上。 ### 添加该组件 {% stepper %} {% step %} #### 选择角色的 GameObject 选择具有你的 `ConvaiCharacter` 组件的 GameObject。如果这两个组件都在同一个 GameObject 上，Manager 会自动检测该角色。 {% endstep %} {% step %} #### 添加该组件 在 Inspector 中，点击 **添加组件** 并导航到 **Convai > Narrative Design Manager**. 该 **角色** 字段会自动填充，如果 `ConvaiCharacter` 在同一个 GameObject 上。否则，请手动将你的角色拖入该字段。
ConvaiNarrativeDesignManager added to the character GameObject with Character field auto-populated

角色 GameObject 上的 ConvaiNarrativeDesignManager 中。

{% endstep %} {% step %} #### 与后端同步 点击 **与后端同步** Inspector 中的按钮。Manager 会调用 `FetchAndSyncFromBackend()`，它会从 Convai 仪表板获取你角色的分节并填充 **叙事章节** 列表中。 只有当你在仪表板上更改了分节列表时，才需要执行此操作。分节 ID 和 Unity Event 绑定会保留在场景文件中，跨会话持续存在。
Narrative Sections list populated after Sync with Backend

成功同步后的 Narrative Sections 列表。

{% endstep %} {% endstepper %} ```mermaid flowchart TD A[点击 Sync with Backend] --> B[FetchSectionsAsync] B --> C{成功？} C -- 是 --> D[SyncSectionConfigs] D --> E[更新 _sectionConfigs 列表] E --> F[OnSectionsSynced.Invoke] C -- 否 --> G[_lastFetchError 被设置] G --> H[错误显示在 Inspector 中] ``` ### 同步状态 该 **同步状态** Inspector 中的标题显示上一次获取操作的当前状态。所有字段均为只读。 | 字段 | 说明 | | -------------- | --------------------------------------- | | **正在获取** | `true` 当获取操作正在进行时。此时 Sync 按钮会被禁用。 | | **上次同步时间** | 上一次成功同步的时间戳（格式： `yyyy-MM-dd HH:mm:ss`). | | **上次同步的角色 ID** | 上一次成功同步所使用的角色 ID。用于验证是否配置了正确的角色。 | | **上一次获取错误** | 最近一次失败获取的错误消息（如果有）。当上一次获取成功时为空。 | {% hint style="warning" %} 如果 **上一次获取错误** 不为空时，最常见的原因是缺少或无效的 API 密钥——请参见 [配置 API 密钥](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-api-key.md) 或者角色 ID 为空，位于 `ConvaiCharacter` 组件。 {% endhint %} 同步结果也会通过 `OnSectionsSynced` 事件（参见下面的全局事件）。 `SectionSyncResult` 所携带的内容会准确告诉你发生了什么变化： | 字段 | 说明 | | --------------------- | --------------------- | | `SectionsAdded` | 本地列表中新加入的分节（之前未同步过）。 | | `SectionsUpdated` | 在仪表板上名称发生变化的分节。 | | `SectionsOrphaned` | 自上次同步以来已从仪表板移除的分节。 | | `SectionsReactivated` | 之前已变为孤立，但已在仪表板上恢复的分节。 | ### 叙事章节 中的角色 ID 为空。同步完成后，每个仪表板分节都会显示为 **叙事章节** 列表中的一项。每一项都是一个 `UnitySectionEventConfig` ，包含以下字段： | 字段 | 类型 | 说明 | | ---------------- | ------------- | ------------------------------------------- | | **Section ID** | `string` （只读） | 与仪表板上的分节相匹配的唯一标识符。切勿手动编辑。 | | **Section Name** | `string` （只读） | 来自仪表板的显示名称。如果名称发生变化，会在下一次同步时自动更新。 | | **是否孤立** | `bool` （只读） | `true` 如果该分节已不再存在于仪表板上。孤立分节会显示警告徽标，其事件不会触发。 | | **章节开始时** | `UnityEvent` | 当角色切换 **进入** 该分节时触发。 | | **章节结束时** | `UnityEvent` | 当角色切换 **离开** 该分节时触发。 | #### 连接章节事件 点击 **+** 按钮位于 **章节开始时** 或 **章节结束时** 上以添加监听器。你可以调用场景中任何 GameObject 上的任何公共方法——Animator 参数、AudioSource 播放、UI 面板激活等等。 **例如：** 要在角色进入“Access Granted”章节时解锁一扇门，请拖动该门的 `DoorController` 组件拖到监听器字段中，并选择 `DoorController.Unlock`.
On Section Start Unity Event wired to a DoorController Unlock method

已连接到 DoorController 组件的 On Section Start。

#### 孤立章节 当某个章节已从仪表板中删除，但仍存在于你的本地列表中时，它就会成为孤立章节。保留这些孤立条目是为了让你不会丢失 Unity Event 接线。它们的 `OnSectionStart` 是位于 `OnSectionEnd` 这些事件在运行时永远不会触发。如果你在仪表板上恢复了该章节，请单击 **与后端同步** 以重新激活它。
Inspector showing an orphaned section entry with a warning badge

叙事章节列表中的一条孤立章节条目。

{% hint style="danger" %} **清除所有分节** 会永久移除所有 `UnitySectionEventConfig` 条目，包括所有 `OnSectionStart` / `OnSectionEnd` 接线。此操作无法撤销。仅在切换到其他角色且不再需要现有接线时使用。等效的运行时调用是 `ClearAllSectionConfigs()`. {% endhint %} ### 全局事件 该 **事件** 折叠项会暴露三个全局 Unity Event，它们会在无论当前激活的是哪个具体分节时都触发。 | 事件 | 签名 | 触发时机 | | ----------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------- | | `OnAnySectionChanged` | `UnityEvent` | 每当当前激活的分节发生变化时触发。接收新的分节 ID 作为字符串。 | | `OnSectionDataReceived` | `UnityEvent` | 每次分节切换时触发。携带完整的 `NarrativeSectionData` 负载，包括 `BehaviorTreeCode` 是位于 `BehaviorTreeConstants`. | | `OnSectionsSynced` | `UnityEvent` | 在每次成功调用 `FetchAndSyncFromBackend()` 或 `FetchAndSyncFromBackendAsync()`. | `OnAnySectionChanged` 后触发，这对于需要反映当前故事状态、但又事先不知道分节 ID 的 UI 很有用——例如一个在分节变化时递增的进度指示器。 `OnSectionDataReceived` 提供原始的行为树负载。大多数项目不需要直接使用它；它 предназнач用于解析 `BehaviorTreeCode` 或 `BehaviorTreeConstants`. ### 检查器参考 #### 角色引用标题 | 字段 | 默认值 | 说明 | | ------ | ------ | ---------------------------------------------------------------------------------- | | **角色** | 自动检测到的 | 该 `ConvaiCharacter` （或任何 `IConvaiCharacterAgent`）以便监听。如果留空，会在同一个 GameObject 上自动找到。 | #### 叙事章节标题 | 字段 | 默认值 | 说明 | | ------------------- | ---- | ----------------------------------------------- | | **Section Configs** | 空 | 条目列表。由 `UnitySectionEventConfig` 填充。 **与后端同步**. | | **当前分节数量** | 计算得出 | 非孤立条目的数量（只读，显示在 Inspector 标题中）。 | | **孤立分节数量** | 计算得出 | 孤立条目的数量（只读，显示在 Inspector 标题中）。 | #### 模板键标题 | 字段 | 默认值 | 说明 | | ------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **模板键** | 空 | 条目列表。由 `UnityTemplateKeyConfig` 条目（键/值对）。请参见 [配置叙事模板键](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/narrative-design/template-keys-dynamic-narrative-variables.md) 以获取完整文档。 | #### 同步状态标题 | 字段 | 默认值 | 说明 | | -------------- | ------- | ------------------- | | **正在获取** | `false` | 只读。 `true` 在活动获取期间。 | | **上次同步时间** | 空 | 只读。上次成功同步的时间戳。 | | **上次同步的角色 ID** | 空 | 只读。上次同步时使用的角色 ID。 | | **上一次获取错误** | 空 | 只读。上次错误消息；成功时为空。 |
ConvaiNarrativeDesignManager Inspector showing all header sections

ConvaiNarrativeDesignManager 的完整 Inspector 视图。

### 下一步 {% 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 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/setting-up-the-narrative-design-manager.md?ask= ``` 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.