> 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/narrative-design-usage-examples.md).

# 叙事设计使用示例

以下示例涵盖了培训模拟和交互式体验中常见的叙事设计模式。每个示例都假设角色 Actor Blueprint 具有一个 `UConvaiChatbotComponent` 其 `CharacterID` 引用了一个在 Convai 仪表板中配置了叙事图的角色。

有关触发器调用基础，请参见 [叙事设计快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-quick-start.md)。有关 API 详情，请参见 [叙事设计 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-blueprint-reference.md).

### 线性场景推进

**场景：** 玩家进入工业安全模拟中的限制区域。进入该区域会触发仪表板触发器，从而激活下一叙事章节。

**设置：**

1. 添加一个 `Box 碰撞` 将组件添加到区域 Actor。绑定 **组件开始重叠时**.
2. 在重叠事件中，获取 `UConvaiChatbotComponent` 来自角色 Actor 引用的
3. 在 Convai 仪表板中，复制离开当前章节的边上的触发器名称。
4. 调用 **Invoke Narrative Design Trigger** 使用该触发器名称，例如 `enter_zone`.
5. Bind **On Narrative Section Received** 在 chatbot 组件上，这样你的 Blueprint 就能在 Convai 确认目标章节时看到它。

**预期结果：** 当玩家进入区域时，Convai 会激活目标章节，角色会遵循新章节的目标。玩家的回答随后可以满足该章节的决策，并将图推进到后续章节。

***

### 为特定章节运行 Blueprint 逻辑

**场景：** 安全模拟应仅在图到达名为以下内容的章节时解锁出口门 `疏散路线开放`.

**设置：**

1. 在 Convai 仪表板中打开该角色并转到 **Narrative Design**.
2. 选择目标章节并复制其 `section_id`。使用 ID 值，不要使用图中显示的章节名称。
3. 在角色 Blueprint 中，绑定 **On Narrative Section Received** 在 `UConvaiChatbotComponent`.
4. 将复制的 ID 存储在 Blueprint 字符串变量中，例如 `EvacuationRouteOpenSectionID`.
5. 添加一个 **Equal (String)** 对传入的内容进行比较 `NarrativeSectionID` 和 `EvacuationRouteOpenSectionID`.
6. 将比较结果连接到 **Branch** 节点。
7. 在 **True**，则运行该章节的 Blueprint 逻辑，例如打开出口门、启用目标标记或启动计时器。

```
// Blueprint 伪代码
On Narrative Section Received (NarrativeSectionID)
  → Equal String (NarrativeSectionID == EvacuationRouteOpenSectionID)
      True  → 打开出口门
      False → 什么都不做
```

**预期结果：** 无关的章节变更不会有任何作用。当 Convai 发送复制的 `section_id`时，你的 Blueprint 会运行与该章节关联的逻辑。

***

### 运行时消息或脚本化语音

**场景：** 医疗培训模拟允许玩家在汇报阶段自由发言。讲师角色应对玩家的回答做出回应，如果章节决策与该回答匹配，叙事可能会推进。

**设置：**

1. 从音频管线接收玩家的语音转文本字符串。
2. 组装一个上下文字符串，将语音与相关游戏状态结合起来，例如 `玩家说：` + `SpeechText` + `。评估分数：` + `ScoreString`.
3. 调用 **Invoke Speech** 在 `UConvaiChatbotComponent` 并将组装好的字符串作为 `TriggerMessage`.
4. 使用 `<speak>` 当角色应说出某句特定台词，而不是将消息视为通用上下文时，使用标签，例如 `<speak>Please proceed to the debrief station.</speak>`.
5. Bind **On Narrative Section Received** 如果该回应应触发特定章节的 Blueprint 逻辑。

**预期结果：** 角色会处理已分段的运行时消息。如果内容满足当前章节中的某个决策，Convai 会推进故事图并 **On Narrative Section Received** 会随新的 `section_id`.

有关何时选择 **Invoke Speech** 而不是 **Invoke Narrative Design Trigger**，请参见 [叙事触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-triggers.md).

***

### 驱动章节目标的模板键

**场景：** 企业入职模拟会在整个章节目标中使用玩家姓名和部门。同一张图可供所有员工使用，无需为每位员工单独设置章节。

**设置：**

1. 在 **Begin Play**，请从你的游戏状态或存档系统中检索玩家姓名和部门。
2. 将二者都赋值给 `UConvaiChatbotComponent`的 **Narrative Template Keys** map，然后再触发任何触发器：

```
// Blueprint 伪代码
NarrativeTemplateKeys["PlayerName"]   = "Rivera"
NarrativeTemplateKeys["Department"]   = "Electrical"
```

3. 在 Convai 仪表板中，编写引用以下内容的章节目标 `{PlayerName}` 和 `{Department}`.

**预期结果：** 本次会话中 Convai 评估的每个章节目标都会使用正确的玩家姓名和部门。连接状态下更新 map 会将新值发送给 Convai，用于下一次目标评估。

参见 [模板键](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/template-keys.md) 用于验证步骤。

***

### 在会话就绪前保护触发器

**场景：** 你的角色的 **Begin Play** 逻辑会立即触发，并且在会话打开前不能丢失已命名的触发器。

**设置：**

`bAutoInitializeSession` 默认为 `true` 在 `UConvaiChatbotComponent`，因此该组件会调用 `StartSession` 在 **Begin Play**。在会话连接之前调用的命名触发器会排队于 `PendingTriggers` 中，并在连接打开后自动重放。

如果 `bAutoInitializeSession` 为 `false`，调用 `StartSession` 显式地，或绑定 **On Character Data Loaded** (`OnCharacterDataLoadEvent_V2`）并从该事件中调用触发器。

```
// Blueprint 伪代码
事件：On Character Data Loaded（Success = true）
  → 调用 Narrative Design Trigger（TriggerName = "start_briefing"）
```

**预期结果：** 命名触发器会在会话打开后到达 Convai。提前调用时会排队，而不是失败，前提是 `bAutoInitializeSession` 为 `true`.

有关待处理队列行为以及 `Reset Dynamic Context`，请参见 [叙事触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-triggers.md).

***

### 在调用前先获取触发器以验证名称

**场景：** 你的 Blueprint 包含许多硬编码的触发器名称字符串。仪表板更新后，其中一个名称发生变化，导致静默失败。你希望在加载时捕获名称不匹配。

**设置：**

1. 在 **Begin Play**，调用 **Convai Fetch Narrative Triggers** 与角色的 `CharacterID`.
2. 在 **成功时** 引脚，遍历 `Narrative Triggers` 数组。对每个元素，提取 `trigger_name` 并将其添加到一个 `TSet<FString>` 名为以下内容的 Blueprint 变量 `ValidTriggerNames`.
3. 在 **On Failure** 引脚，打印警告并继续——如果数据不可用，则跳过触发器验证。
4. 无论你在何处调用 **Invoke Narrative Design Trigger**，都先检查目标 `TriggerName` 是否在 `ValidTriggerNames`中。如果不在，则将名称打印到 **输出日志**.

```
// Blueprint 伪代码
Begin Play
  → Convai Fetch Narrative Triggers（CharacterId = CharacterID）
      On Success → For Each（Narrative Triggers）
                      → 将 trigger_name 添加到 ValidTriggerNames
      On Failure → 打印“获取触发器失败——已跳过验证”

在调用 Narrative Design Trigger 之前：
  → Branch：ValidTriggerNames 包含 TriggerName
      True  → 调用 Narrative Design Trigger
      False → 打印“未知触发器：” + TriggerName
```

**预期结果：** 触发器名称不匹配会在加载时以清晰的日志消息显现。仪表板重命名后，不匹配会显示在 **Begin Play** 上，而不是静默地不产生任何章节变化。

有关获取前提条件和验证，请参见 [获取叙事数据](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/fetching-narrative-data.md).

***

### 下一步

{% 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 %}

{% 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 %}


---

# 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/narrative-design-usage-examples.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.