叙事设计如何工作

了解叙事设计管线——分段、触发器和模板键如何在运行时连接，从而推进故事图谱。

Narrative Design 为 Convai 角色提供一条结构化的故事线供其遵循。你在 Convai 仪表板中编写由各个 section 和 trigger 组成的图；运行时，SDK 监听来自 Convai 的 section 变更信号，并触发你配置的 Unity Events——无需轮询，无需自定义状态机。本页解释其底层模型：原语是什么、trigger 如何推进图，以及 SDK 的哪个组件负责流程中的每一部分。

运行时流水线如何工作

当玩家激活一个 trigger 时，SDK 会向 Convai 后端发送一个命名信号。后端推进故事图，并返回一个 behavior-tree-response 携带新 section ID 的 NarrativeSectionChanged 域事件，并将其交付给 ConvaiNarrativeDesignManager，它会触发你在 Inspector 中连接的按 section Unity Events。

如果角色的实时会话尚未打开，Triggers 会自动排队，并在连接建立后被刷新发送。你无需在调用之前检查会话状态 InvokeTrigger().

章节与触发器

章节 是在 Convai 仪表板中定义的带名称的故事节点。角色的目标、知识和对话行为会适配当前激活的 section。一个角色可以在开场 section 中扮演中性的接待员，在考核 section 中扮演严格的考官——全都在一次会话中完成——因为当前激活的 section 会决定后端返回什么。

触发器 是故事图中的有向边。按名称发送一个 trigger 会沿着匹配的边将图从一个 section 推进到下一个 section。trigger 可以携带一个可选的消息负载，用于提供转换上下文——例如， “Player completed the safety checklist” ——角色可以将其纳入下一次回应中。

Template key 是运行时的键值对，用于填充仪表板叙事目标中的占位符。设置 {PlayerName} 到 “Alex” ，那么所有引用 {PlayerName} 的 section 都会使用当前值，而无需更改图。

SDK 的三个组件

组件	所在位置	作用
ConvaiNarrativeDesignManager	在角色的 GameObject 上	监听 section 变更，触发按 section 的 OnSectionStart / OnSectionEnd Unity Events，并管理 template key
ConvaiNarrativeDesignTrigger	在任意世界 GameObject 上	在被激活时向角色发送一个命名 trigger（碰撞、接近、计时器或手动）
IConvaiNarrativeDesign	通过以下方式访问： convaiCharacter.NarrativeDesign	角色作用域的 C# API，用于调用 trigger、控制 template key，以及异步数据获取

你可以任意组合使用。大多数项目会用到全部三个。简单的线性叙事可能只需要 Manager 和一两个 Triggers。

核心概念

术语	定义
部分	Convai 仪表板中的一个带名称的故事节点。角色的目标和行为会随激活的 section 调整。
触发器	故事图中的一个带名称的边。发送一个 trigger 会将图从一个 section 推进到下一个 section。
Template key	一个运行时键值对（例如， PlayerName = "Alex"）用于填充 {placeholder} 仪表板叙事目标中的文本。
孤立的 section	在本地同步后又从仪表板中删除的 section。其 Unity Events 会被保留，但在该 section 恢复并重新同步之前都不会触发。
行为树响应	携带新的 SectionId 以及可选的 BehaviorTreeCode 和 BehaviorTreeConstants 供高级集成使用。

组件放置

了解哪个组件应该放在哪个 GameObject 上，可以避免最常见的设置错误。

组件	放置位置	每个场景的典型数量
ConvaiNarrativeDesignManager	在 角色的 GameObject，连同 ConvaiCharacter	每个角色一个
ConvaiNarrativeDesignTrigger	在 任意世界 GameObject ——比如一扇门、一个展品或一个 UI 事件目标	每个图转换点一个
IConvaiNarrativeDesign	不放置——通过以下方式访问： convaiCharacter.NarrativeDesign 在代码中	不适用

下一步

叙事设计快速开始配置叙事设计管理器配置叙事设计触发器