> 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).

# 模板键

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

模板键是存储在其中的键值对 `NarrativeTemplateKeys` 的属性中 `UConvaiChatbotComponent`。插件通过……将该映射发送到 Convai `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。在 **组件** 面板中，选择 **Convai Chatbot**，然后展开 **Convai|NarrativeDesign** 在 **详情** 面板。该 `叙事模板键` 字段是一个 `TMap<FString, FString>`。为在设计时已知其值的键添加条目。

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

将 `叙事模板键` 属性赋给 `UConvaiChatbotComponent` 在 Blueprint 中的引用。像写入任何 `TMap` 一样——可在游戏过程中随时添加、移除或替换条目。

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

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

{% hint style="info" %}
`UpdateNarrativeTemplateKeys` 被标记为 `BlueprintInternalUseOnly` 且不可作为可调用的 Blueprint 节点使用。请直接赋值该 **叙事模板键** 属性。
{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.