配置叙事模板键

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

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

在 Inspector 中定义键

打开 ConvaiNarrativeDesignManager 在 Inspector 中并展开 Template Keys 折叠面板。

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

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

ConvaiNarrativeDesignManager 中的 Template Keys 折叠面板。

在 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 内部调用。你可以在同一项目中使用任一路径，但应避免在同一帧内对同一个键同时调用两条路径，因为这可能会发送重复更新。

下一步

叙事设计脚本参考