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

# 叙事设计使用示例

用于线性场景推进、动态上下文事件、模板键注入以及叙事设计中触发器名称验证的 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 详细信息，请参见 [叙事设计蓝图参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-blueprint-reference.md).

### 线性场景推进

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

**设置：**

1. 添加一个 `Box Collision` 组件添加到区域 Actor。绑定 **On Component Begin Overlap**.
2. 在重叠事件中，获取 `UConvaiChatbotComponent` 来自角色 Actor 引用。
3. 在 Convai 仪表板中，复制离开当前部分的边缘上的触发器名称。
4. 调用 **Invoke Narrative Design Trigger** 与该触发器名称对应的内容，例如 `enter_zone`.
5. Bind **叙事章节已接收** 到 chatbot 组件，这样你的蓝图就能看到 Convai 何时确认目标部分。

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

***

### 为特定部分运行蓝图逻辑

**场景：** 安全模拟应仅在图到达名为 `疏散路线已开启`.

**设置：**

1. 在 Convai 仪表板中打开角色并转到 **叙事设计**.
2. 选择目标部分并复制其 `section_id`。使用 ID 值，而不是图中显示的部分名称。
3. 在角色蓝图中，绑定 **叙事章节已接收** 在 `UConvaiChatbotComponent`.
4. 将复制的 ID 存储到一个蓝图字符串变量中，例如 `EvacuationRouteOpenSectionID`.
5. 添加一个 **Equal (String)** 比较，比较输入的 `NarrativeSectionID` 和 `EvacuationRouteOpenSectionID`.
6. 将比较结果连接到一个 **Branch** 节点。
7. 当 **True**时，运行该部分的蓝图逻辑，例如打开出口门、启用目标标记或启动计时器。

```
// Blueprint 伪代码
On Narrative Section Received (NarrativeSectionID)
  → Equal String (NarrativeSectionID == EvacuationRouteOpenSectionID)
      True  → Open Exit Door
      False → Do Nothing
```

**预期结果：** 无关的部分更改不会产生任何作用。当 Convai 发送复制的 `section_id`时，你的蓝图会运行与该部分关联的逻辑。

***

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

**场景：** 在医疗保健培训模拟中，玩家可以在汇报阶段自由发言。讲师角色应回应玩家的回答，如果该回答匹配部分决策，叙事可能会推进。

**设置：**

1. 从你的音频管道接收玩家的语音转文本字符串。
2. 构建一个上下文字符串，将语音与相关游戏状态结合起来，例如 `玩家说：` + `SpeechText` + `。评估得分：` + `ScoreString`.
3. 调用 **Invoke Speech** 在 `UConvaiChatbotComponent` 并将组装好的字符串作为 `TriggerMessage`.
4. 使用 `<speak>` 标签，当角色应当说出特定台词而不是将消息视为一般上下文时使用，例如 `<speak>请前往汇报站。</speak>`.
5. Bind **叙事章节已接收** 如果响应应触发特定于部分的蓝图逻辑。

**预期结果：** 角色会处理已构建的运行时消息。如果内容满足当前部分中的某个决策，Convai 会推进故事图并 **叙事章节已接收** 以新的 `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`的 **叙事模板键** 映射表，在任何触发器触发之前：

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

3. 在 Convai 仪表板中，编写引用 `{PlayerName}` 和 `{Department}`.

**预期结果：** 的部分目标。Convai 为本次会话评估的每个部分目标都会使用正确的玩家姓名和部门。在连接状态下更新映射表会将新值发送给 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` 显式地，或者绑定 **在角色数据加载完成时** (`OnCharacterDataLoadEvent_V2`）并从该事件中调用触发器。

```
// Blueprint 伪代码
事件：On Character Data Loaded (Success = true)
  → Invoke Narrative Design Trigger (TriggerName = "start_briefing")
```

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

有关待处理队列行为和 `重置动态上下文`，请参见 [叙事触发器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-triggers.md).

***

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

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

**设置：**

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

```
// Blueprint 伪代码
Begin Play
  → Convai Fetch Narrative Triggers (CharacterId = CharacterID)
      On Success → For Each (Narrative Triggers)
                      → Add trigger_name to ValidTriggerNames
      On Failure → Print "Fetch triggers failed — validation skipped"

在调用 Invoke Narrative Design Trigger 之前：
  → Branch: ValidTriggerNames Contains TriggerName
      True  → Invoke Narrative Design Trigger
      False → Print "Unknown trigger: " + 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 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/narrative-design-usage-examples.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.