设置叙事设计管理器

ConvaiNarrativeDesignManager 控制的一切——部分同步、每部分 Unity 事件、全局转换回调，以及确认仪表板返回内容的同步状态字段。

ConvaiNarrativeDesignManager 组件

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

添加该组件

1

选择角色的 GameObject

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

2

添加该组件

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

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

3

与后端同步

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

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

同步状态面板

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

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

同步结果也会通过 OnSectionsSynced 事件报告（见下方 Global Events）。该 SectionSyncResult 所携带的内容会准确告诉你发生了什么变化：

字段	说明
SectionsAdded	本地列表中新加入的分节（之前未同步过）。
SectionsUpdated	在仪表板上名称发生变化的分节。
SectionsOrphaned	自上次同步以来已从仪表板移除的分节。
SectionsReactivated	之前已变为孤立，但已在仪表板上恢复的分节。

如果 上一次获取错误 不为空时，最常见的原因是 API key 缺失或无效（编辑 > 项目设置 > Convai SDK）或 ConvaiCharacter 组件。

叙事章节

中的角色 ID 为空。同步完成后，每个仪表板分节都会显示为 叙事章节 列表中的一项。每一项都是一个 UnitySectionEventConfig ，包含以下字段：

字段	类型	说明
Section ID	string （只读）	与仪表板上的分节相匹配的唯一标识符。切勿手动编辑。
Section Name	string （只读）	来自仪表板的显示名称。如果名称发生变化，会在下一次同步时自动更新。
是否孤立	bool （只读）	true 如果该分节已不再存在于仪表板上。孤立分节会显示警告徽标，其事件不会触发。
章节开始时	UnityEvent	当角色切换 进入 该分节时触发。
章节结束时	UnityEvent	当角色切换 离开 该分节时触发。

配置分节事件

点击 + 按钮位于 章节开始时 或 章节结束时 上以添加监听器。你可以调用场景中任何 GameObject 上的任何公共方法——Animator 参数、AudioSource 播放、UI 面板激活等等。

例如： 要在角色进入“Access Granted”分节时打开锁住的门，请将门的 DoorController 组件拖到监听器字段中，并选择 DoorController.Unlock.

孤立分节

当某个分节从仪表板中删除，但仍存在于你的本地列表中时，它就会变为孤立。保留孤立条目是为了不丢失你的 Unity Event 绑定。

孤立分节在运行时绝不会触发它们的 OnSectionStart 或 OnSectionEnd 事件。如果你在仪表板上恢复了该分节，请再次点击 与后端同步 以重新激活它。

点击 清除所有分节 （可通过 ClearAllSectionConfigs() 在运行时访问，并且在切换角色时会在 Inspector 中显示）会永久移除所有 UnitySectionEventConfig 条目，包括所有 OnSectionStart / OnSectionEnd 绑定。此操作无法撤销。仅当你有意切换到其他角色且不再需要现有绑定时才使用。

全局事件

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

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

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

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

Inspector 参考

角色引用标题

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

Narrative Sections 标题

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

模板键标题

字段	默认值	说明
模板键	空	条目列表。由 UnityTemplateKeyConfig 条目（键 / 值对）。完整文档请参阅 Template Keys。

同步状态标题

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

结论

ConvaiNarrativeDesignManager 是永久监听器，将 Convai 后端的分节切换桥接到你场景中的 Unity Events。一旦同步完成，每次分节变化都会自动到达正确的 OnSectionStart 或 OnSectionEnd 处理器，而无需任何轮询或手动状态跟踪。继续到 设置 Narrative Design 触发器 以放置那些真正推进故事图谱的世界空间组件。