配置叙事设计管理器

在角色上添加并配置 ConvaiNarrativeDesignManager，从 Convai 同步章节，并在 Inspector 中为每个章节连接 Unity Event。

ConvaiNarrativeDesignManager 是角色上的常驻监听点。它订阅来自 Convai 的章节变更信号，并将其转发到你在 Inspector 中配置的 Unity Events。每个角色一个 Manager 是标准设置；它在场景生命周期内驻留于角色的 GameObject 上。

添加该组件

1

选择角色的 GameObject

选择具有你的 ConvaiCharacter 组件的 GameObject。如果这两个组件都在同一个 GameObject 上，Manager 会自动检测该角色。

2

添加该组件

在 Inspector 中，点击 添加组件 并导航到 Convai > Narrative Design Manager.

该 角色 字段会自动填充，如果 ConvaiCharacter 在同一个 GameObject 上。否则，请手动将你的角色拖入该字段。

角色 GameObject 上的 ConvaiNarrativeDesignManager 中。

3

与后端同步

点击 与后端同步 Inspector 中的按钮。Manager 会调用 FetchAndSyncFromBackend()，它会从 Convai 仪表板获取你角色的分节并填充 叙事章节 列表中。

只有当你在仪表板上更改了分节列表时，才需要执行此操作。分节 ID 和 Unity Event 绑定会保留在场景文件中，跨会话持续存在。

成功同步后的 Narrative Sections 列表。

同步状态

该 同步状态 Inspector 中的标题显示上一次获取操作的当前状态。所有字段均为只读。

字段	说明
正在获取	true 当获取操作正在进行时。此时 Sync 按钮会被禁用。
上次同步时间	上一次成功同步的时间戳（格式： yyyy-MM-dd HH:mm:ss).
上次同步的角色 ID	上一次成功同步所使用的角色 ID。用于验证是否配置了正确的角色。
上一次获取错误	最近一次失败获取的错误消息（如果有）。当上一次获取成功时为空。

如果 上一次获取错误 不为空时，最常见的原因是缺少或无效的 API 密钥——请参见 配置 API 密钥 或者角色 ID 为空，位于 ConvaiCharacter 组件。

同步结果也会通过 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.

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

孤立章节

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

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

清除所有分节 会永久移除所有 UnitySectionEventConfig 条目，包括所有 OnSectionStart / OnSectionEnd 接线。此操作无法撤销。仅在切换到其他角色且不再需要现有接线时使用。等效的运行时调用是 ClearAllSectionConfigs().

全局事件

该 事件 折叠项会暴露三个全局 Unity Event，它们会在无论当前激活的是哪个具体分节时都触发。

事件	签名	触发时机
OnAnySectionChanged	UnityEvent<string>	每当当前激活的分节发生变化时触发。接收新的分节 ID 作为字符串。
OnSectionDataReceived	UnityEvent<NarrativeSectionData>	每次分节切换时触发。携带完整的 NarrativeSectionData 负载，包括 BehaviorTreeCode 是位于 BehaviorTreeConstants.
OnSectionsSynced	UnityEvent<SectionSyncResult>	在每次成功调用 FetchAndSyncFromBackend() 或 FetchAndSyncFromBackendAsync().

OnAnySectionChanged 后触发，这对于需要反映当前故事状态、但又事先不知道分节 ID 的 UI 很有用——例如一个在分节变化时递增的进度指示器。

OnSectionDataReceived 提供原始的行为树负载。大多数项目不需要直接使用它；它 предназнач用于解析 BehaviorTreeCode 或 BehaviorTreeConstants.

检查器参考

角色引用标题

字段	默认值	说明
角色	自动检测到的	该 ConvaiCharacter （或任何 IConvaiCharacterAgent）以便监听。如果留空，会在同一个 GameObject 上自动找到。

叙事章节标题

字段	默认值	说明
Section Configs	空	条目列表。由 UnitySectionEventConfig 填充。 与后端同步.
当前分节数量	计算得出	非孤立条目的数量（只读，显示在 Inspector 标题中）。
孤立分节数量	计算得出	孤立条目的数量（只读，显示在 Inspector 标题中）。

模板键标题

字段	默认值	说明
模板键	空	条目列表。由 UnityTemplateKeyConfig 条目（键/值对）。请参见 配置叙事模板键 以获取完整文档。

同步状态标题

字段	默认值	说明
正在获取	false	只读。 true 在活动获取期间。
上次同步时间	空	只读。上次成功同步的时间戳。
上次同步的角色 ID	空	只读。上次同步时使用的角色 ID。
上一次获取错误	空	只读。上次错误消息；成功时为空。

ConvaiNarrativeDesignManager 的完整 Inspector 视图。

下一步

配置叙事设计触发器配置叙事模板键