叙事设计如何工作

了解叙事设计故事图、推进章节的运行时管线，以及触发器和模板键如何塑造角色行为。

叙事设计为 Convai 角色提供一个结构化的故事图——包含命名章节以及在它们之间切换的触发器——这些内容在 Convai 仪表板中编写，并在运行时通过 UConvaiChatbotComponent。本页解释心智模型和运行时流程。要进行动手设置，请从 叙事设计快速开始.

故事图模型

一个叙事设计图由三个构建块组成，你可以在 Unreal Engine 中使用它们。

概念	它是什么	在哪里配置
章节	一个带有 目标 的命名故事节点，用于塑造角色行为。每个章节都有一个 section_id.	Convai 仪表板
触发器	一个命名边，用于激活目标章节。 trigger_name 在你的 Blueprint 中必须与仪表板完全一致。	Convai 仪表板
模板键	运行时键值对，位于 NarrativeTemplateKeys 聊天机器人组件上。插件通过 update-template-keys将映射发送到 Convai。仪表板目标可以引用 {key} 占位符。	Blueprint 或 Details 面板

角色会停留在当前章节，直到 调用叙事设计触发器 激活另一个章节。该章节变为激活后，玩家的回答和章节的决策会引导下一次在图中的切换。参见 FNarrativeDecision 在 叙事设计 Blueprint 参考 查看决策结构体字段。

在 Convai 仪表板中编写章节、触发器和进入行为。参见 叙事设计 | Playground 了解图编写指南。

命名触发器的运行时流程

从命名触发调用到章节切换的标准路径：

1. Blueprint 调用 调用叙事设计触发器 ，其参数为从你的凭据来源构造的 TriggerName 字符串。
2. 如果会话已连接，组件会发送一个 触发消息 数据包，其中包含 trigger_name 发送给 Convai。如果已断开连接，该调用会排队到 PendingTriggers 中，并在连接后重放。
3. Convai 会根据当前章节的外向触发器来评估该触发器。匹配后，Convai 会激活目标章节。
4. 激活章节的 目标 会塑造角色接下来的行为。
5. 当对话继续时，玩家的回答会根据章节的 决策 进行评估。
6. Convai 会返回一个 BTResponse 数据包，其中包含 narrative_section_id ，当章节更新被传递时。
7. 收到叙事章节时触发 会在聊天机器人组件上触发，并带有 NarrativeSectionID.

收到叙事章节时触发 仅在 Convai 通过以下方式确认章节变更时才触发 BTResponse。调用触发函数时不会触发。有关逐步触发调用，请参见 叙事触发器.

两个 Blueprint 函数

UConvaiChatbotComponent 提供两个相关函数，它们使用不同的运行时路径。

函数	发送给 Convai	何时使用
调用叙事设计触发器	触发消息 其带有 trigger_name	当过渡目标在设计时已知，并且仪表板中的触发器名称是固定的时。
调用语音	通过动态上下文事件 AddContextEvent	消息在运行时组装，你希望 Convai 将其作为对话上下文处理，而不是匹配仪表板触发器名称。

命名触发器会在 PendingTriggers 时排队。 调用语音 不会使用该队列。如果 Convai 返回一个，则两条路径都可以产生章节切换 BTResponse ，其参数为从你的凭据来源构造的 narrative_section_id.

请参见 叙事触发器 了解输入参数、待处理队列行为，以及何时选择每个函数。

模板键

NarrativeTemplateKeys 是一个 TMap<FString, FString> on UConvaiChatbotComponent 位于 Convai|NarrativeDesign下。添加其键与 {key} 仪表板目标中的占位符相匹配的条目。

例如，如果仪表板目标写着 引导 {PlayerName} 完成安全检查，则添加 PlayerName = "Rivera" 到 NarrativeTemplateKeys ，在推进到该章节的触发器之前。

插件会在会话连接时以及你分配 NarrativeTemplateKeys 时发送模板键。先设置键，再调用会推进到其目标引用这些键的章节的触发器。参见 模板键 进行设置和验证。

在仪表板中验证触发器名称

在 Blueprint 中硬编码触发器名称之前，先在 Convai 仪表板中打开角色的叙事图，并逐个复制每个 trigger_name ，确保与作者编写的一致。确认该触发器是角色起始章节的一个外向边。参见 叙事设计 | Playground.

在运行时查询叙事数据

角色的章节和触发器完整列表可通过以下方式查询： Convai 获取叙事章节 是位于 Convai 获取叙事触发器 位于 Convai|REST API。使用这些节点来验证触发器名称或填充游戏内 UI——不要将其作为主要剧情推进路径。参见 获取叙事数据.

下一步

叙事设计快速入门叙事触发器叙事设计 Blueprint 参考