配置叙事模板键

设置叙事模板键，使 Convai 角色能够在目标中引用运行时值——玩家姓名、场景参数或会话状态。

模板键是运行时键值对，可填充角色叙事目标中的占位符。请在 Convai 仪表板 中使用花括号语法进行定义——例如， {PlayerName} 或 {CurrentTask} ——而 SDK 会在运行时从 Unity 发送实际值，因此角色可以在对话中自然地引用它们。这样，一个叙事图即可在不每次编辑图的情况下，为许多拥有不同参与者或动态状态的会话提供服务。

在 Inspector 中定义键

打开 ConvaiNarrativeDesignManager 在 Inspector 中并展开 模板键 折叠项。

单击 + 以添加一项。每项包含两个字段：

字段	说明
键	占位符名称，必须与叙事设计部分目标中写的一致（区分大小写，不含花括号）。
值	初始值。你可以在运行时通过代码覆盖它。

ConvaiNarrativeDesignManager 中的模板键折叠项。

在 Inspector 中定义的键会在 Awake 时同步到内部控制器，并在会话打开时自动发送到 Convai。你无需手动调用任何内容即可确保传递。

在播放模式下，Inspector 会显示一个 发送到服务器 按钮，它会立即调用 SendTemplateKeysUpdate()。这对于无需编写代码即可测试会话中途的值变化非常有用。

在运行时更新键

请在 ConvaiNarrativeDesignManager 上使用以下任一方法从代码更新键：

更新单个键：

narrativeManager.UpdateTemplateKey("PlayerName", "Alex");

立即更新并发送（一次调用）：

narrativeManager.UpdateAndSendTemplateKey("ScenarioPhase", "Handwashing");

使用 UpdateAndSendTemplateKey 当键更改应在角色的下一条回复中立即生效时。

一次更新多个键：

narrativeManager.UpdateTemplateKeys(new Dictionary<string, string>
{
    { "PlayerName", "Alex" },
    { "Department",  "Facilities" },
    { "CompletedSteps", "3" }
});
narrativeManager.SendTemplateKeysUpdate();

读取当前键字典：

Dictionary<string, string> current = narrativeManager.GetTemplateKeys();

键是如何发送的

如果角色断开并重新连接，SDK 会在内部调用 MarkPendingReplayAfterDisconnect ，这样最新的键值会在下一次连接时重新发送。重新连接后，你无需手动重新发送键。

键命名规则

规则	示例
必须与仪表板占位符完全一致（区分大小写）	仪表板： {playerName} → 键： playerName （不 PlayerName)
前后不能有空白字符	"PlayerName" ✓ — " PlayerName" ✗
键字符串不能为空	"" 会被静默忽略
值可以为空字符串	键 "OptionalField" 的值 "" 是有效的

良好的键名：

键	值示例
PlayerName	"Maria"
ScenarioLevel	"Advanced"
CompletedCheckpoints	"4"
SessionStartTime	"09:15"

有问题的键名：

键	问题
player name	名称中有空格 —— 将无法匹配 {player name} 占位符，如果仪表板使用 {playerName}
"PlayerName "	尾随空格 —— 静默不匹配
""	为空 —— 被忽略

模板键值以纯字符串形式在网络上传输，并可能出现在角色的对话中。请不要在模板键值中包含密码、个人识别号码、API 密钥或任何其他敏感数据。

直接在角色上设置键

如果你在没有一个……的情况下 ConvaiNarrativeDesignManager，则可以通过角色 API 直接设置模板键：

ConvaiCharacter character = GetComponent<ConvaiCharacter>();

// 单个键
character.NarrativeDesign.SetTemplateKey("PlayerName", "Alex");

// 多个键
character.NarrativeDesign.SetTemplateKeys(new Dictionary<string, string>
{
    { "PlayerName", "Alex" },
    { "Department", "Engineering" }
});

角色 API 和 Manager API 最终都会汇聚到同一个 ConnectionService.UpdateTemplateKeys 调用中。你可以在同一项目中使用任一路径，但避免在同一帧内对同一个键同时调用两种路径，因为这可能会发送冗余更新。

下一步

叙事设计脚本参考