模板键

在 chatbot 组件上填充 Narrative Template Keys 映射，使区段目标通过占位符替换引用实时游戏值。

模板键是存储在……中的键值对 NarrativeTemplateKeys 的属性中 UConvaiChatbotComponent。插件通过 update-template-keys 当会话连接时。仪表板章节目标可以引用 {key} 占位符——在……中填充匹配的键 NarrativeTemplateKeys 这样 Convai 就会接收到你的图表所期望的运行时值。

替换的工作原理

在 Convai 仪表板中，使用 {key} 占位符（例如 {PlayerName}）。在 Unreal Engine 中，将匹配的键添加到 NarrativeTemplateKeys 在 Convai 评估该章节的目标之前。

例如，如果某个章节目标是：

引导 {PlayerName} 完成 {QuestName} 安全检查。

并且 NarrativeTemplateKeys 包含：

键	值
PlayerName	Rivera
QuestName	电气

Convai 接收到：

引导 Rivera 完成电气安全检查。

将 NarrativeTemplateKeys 中的每个键字符串与仪表板目标中的占位符名称逐字符匹配。

在 Details 面板中设置模板键

在关卡中选择角色 Actor，或打开角色 Blueprint。在 Components 面板中，选择 Convai 聊天机器人，然后展开 Convai|NarrativeDesign 在 详细信息 面板。The Narrative Template Keys 字段是一个 TMap<FString, FString>。为在设计时已知其值的键添加条目。

在 Blueprint 中于运行时设置模板键

分配 Narrative Template Keys 属性到 UConvaiChatbotComponent Blueprint 中的引用。像写入任何 TMap 一样，可在游戏过程中随时添加、移除或替换条目。

// Blueprint 伪代码 — 通过 NarrativeTemplateKeys 属性上的 Set 节点赋值
NarrativeTemplateKeys["PlayerName"] = "Rivera"
NarrativeTemplateKeys["QuestStatus"] = "completed"

为该属性赋值会调用 UpdateNarrativeTemplateKeys 在内部。如果聊天机器人会话已连接，插件会发送一条 update-template-keys 带有当前映射的消息给 Convai。

UpdateNarrativeTemplateKeys 被标记为 BlueprintInternalUseOnly ，并且不能作为可调用的 Blueprint 节点使用。分配该 Narrative Template Keys 属性本身。

键何时生效

模板键会在 Convai 评估当前活动章节的目标时应用——而不是在触发器触发时。请在调用 Invoke Narrative Design Trigger 之前为新章节设置键，以便在目标章节的目标被评估时它们已经就位。

插件还会发送 NarrativeTemplateKeys 在会话连接时（OnAttendeeConnected）。在 Begin Play 中填充该映射，如果你需要从第一个章节开始就可用的值，请在触发器触发之前完成。

验证模板键

在调用会推进到包含 {key} 标记的章节的触发器之前：

1. 打印或检查 NarrativeTemplateKeys 在 Blueprint 中或在 详细信息 面板——确认所需的键值对已存在。
2. 将每个键字符串逐字符与 {key} 仪表板目标中的标记。
3. 触发器触发后，确认角色的行为反映了替换后的值。如果 {key} 标记在回复中以字面形式出现，那么最可能的原因是键名不匹配或映射为空。参见 排查叙事设计问题.

下一步

叙事触发器叙事设计 Blueprint 参考叙事设计使用示例排查叙事设计问题