> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/template-keys.md).

# 模板键

模板键是存储在……中的键值对 `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。

{% hint style="info" %}
`UpdateNarrativeTemplateKeys` 被标记为 `BlueprintInternalUseOnly` ，并且不能作为可调用的 Blueprint 节点使用。分配该 **Narrative Template Keys** 属性本身。
{% endhint %}

### 键何时生效

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

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

### 验证模板键

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

1. 打印或检查 `NarrativeTemplateKeys` 在 Blueprint 中或在 **详细信息** 面板——确认所需的键值对已存在。
2. 将每个键字符串逐字符与 `{key}` 仪表板目标中的标记。
3. 触发器触发后，确认角色的行为反映了替换后的值。如果 `{key}` 标记在回复中以字面形式出现，那么最可能的原因是键名不匹配或映射为空。参见 [排查叙事设计问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/troubleshoot-narrative-design.md).

### 下一步

{% content-ref url="/pages/ff19704aac20f7d6e4bf5c3214636ccbe4248151" %}
[叙事触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-triggers.md)
{% endcontent-ref %}

{% content-ref url="/pages/579f95b35d1b473357f37588e6fc915a03231497" %}
[叙事设计 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-blueprint-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/78fce7020677f54bda05ede0262a6996390ed909" %}
[叙事设计使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-usage-examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/609986e3902c22d2027f232e5ffaaa507011c8a0" %}
[排查叙事设计问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/troubleshoot-narrative-design.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/template-keys.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.