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

# 叙事触发器

叙事触发器会将角色的故事图从一个章节推进到下一个章节。 `UConvaiChatbotComponent` 提供两个用于触发触发器的 Blueprint 函数，以及一个用于响应章节变化的事件。如果你之前还没有调用过触发器，请先完成 [叙事设计快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/narrative-design-quick-start.md) 第一步。

### 选择合适的函数

| 目标              | 函数            | 它发送什么                       |
| --------------- | ------------- | --------------------------- |
| 使用仪表板触发器名称推进图表  | **调用叙事设计触发器** | `触发消息` 其带有 `trigger_name`   |
| 将运行时消息作为对话上下文暂存 | **调用语音**      | 通过动态上下文事件 `AddContextEvent` |

使用 **调用叙事设计触发器** 当过渡目标在设计时已知，并且触发器名称是仪表板中的固定字符串时使用。使用 **调用语音** 当消息在运行时组装、当角色应说出脚本台词，或者当你希望 Convai 将游戏状态文本作为对话上下文处理，而不是匹配仪表板触发器名称时使用。

**收到叙事章节时** 仅在 Convai 通过一个 `BTResponse` 数据包。调用任一函数时都不会触发。

### 调用命名触发器

**调用叙事设计触发器** (`InvokeNarrativeDesignTrigger`) 发送一个 `TriggerName` 字符串通过 `SendTriggerMessage`发送给 Convai。Convai 会将该名称与仪表板中为当前章节配置的外发触发器进行匹配。

| 输入                     | 类型        | 说明                             |
| ---------------------- | --------- | ------------------------------ |
| `TriggerName`          | `FString` | 触发器名称。必须与仪表板配置完全一致（区分大小写）。     |
| `InGenerateActions`    | `bool`    | 存在于 Blueprint 签名中。当前插件源代码中未应用。 |
| `InReplicateOnNetwork` | `bool`    | 存在于 Blueprint 签名中。当前插件源代码中未应用。 |

如果 `TriggerName` 为空时，插件会记录 `调用叙事设计触发器：缺少 TriggerName` 并返回，不发送触发器。

{% hint style="warning" %}
从仪表板逐字符复制触发器名称。Blueprint 字符串与仪表板之间的不匹配 `trigger_name` 不会产生章节更改。
{% endhint %}

### 调用动态上下文消息

**调用语音** (`ExecuteNarrativeTrigger`) 通过动态上下文事件暂存 `AddContextEvent` 其带有 `EC_RunLLMOption::Always`。它不会发送一个 `触发消息` 数据包，也不会在 `PendingTriggers`.

| 输入                     | 类型        | 说明                             |
| ---------------------- | --------- | ------------------------------ |
| `TriggerMessage`       | `FString` | 作为上下文事件暂存的消息字符串。               |
| `InGenerateActions`    | `bool`    | 存在于 Blueprint 签名中。当前插件源代码中未应用。 |
| `InReplicateOnNetwork` | `bool`    | 存在于 Blueprint 签名中。当前插件源代码中未应用。 |

使用普通的 `TriggerMessage` 当角色应将消息作为上下文处理时，例如 `玩家以 82% 的准确率完成了疏散演练`。将消息包裹在 `<speak>` 标签中，当角色应直接说出文本时，例如 `<speak>注意：疏散路线现已开放。</speak>`.

如果 Convai 判定需要进行章节更改， **收到叙事章节时** 仍会通过相同的 `BTResponse` 路径触发。

如果 `TriggerMessage` 为空时，插件会记录 `调用语音：缺少 TriggerMessage` 并返回，不暂存事件。

### 处理章节更改事件

Bind **收到叙事章节时** (`OnNarrativeSectionReceivedEvent`) 在聊天机器人组件上，以便在 Convai 进入新章节时作出响应。

| 输出引脚                 | 类型                         | 说明                     |
| -------------------- | -------------------------- | ---------------------- |
| `ChatbotComponent`   | `UConvaiChatbotComponent*` | 接收到章节更新的组件。            |
| `NarrativeSectionID` | `FString`                  | 该 `section_id` 新活动章节的。 |

在 Blueprint 中绑定：将 `UConvaiChatbotComponent` 引用拖到事件图中，然后选择 **分配“收到叙事章节时”** 从上下文菜单中。

当某个特定章节应运行自定义 Blueprint 逻辑时，复制该章节的 `section_id` 来自 **叙事设计** 在 Convai 仪表板中。使用 ID 值，而不是图中显示的章节名称。在绑定的事件中，比较传入的 `NarrativeSectionID` 与复制的值。如果字符串匹配，则运行该章节的 Blueprint 逻辑，例如打开门、启用小部件或启动评估计时器。

### 待处理的命名触发器

当 **调用叙事设计触发器** 被调用且会话未连接时，插件会将该调用存储在 `PendingTriggers`。待处理触发器会在会话连接且动态上下文刷新完成后按顺序重新执行。

{% hint style="warning" %}
调用 `重置动态上下文` 清除 `PendingTriggers`。如果组件在会话重新连接之前被销毁，排队的触发器也会被丢弃。 **调用语音** 不使用待处理触发器队列。
{% endhint %}

### 会话就绪

`bAutoInitializeSession` on `UConvaiChatbotComponent` 默认为 `true`。启用后，组件会调用 `StartSession` on **开始游戏**。在会话连接之前调用的命名触发器会排队到 `PendingTriggers` 中，并在连接打开后重新执行。

如果 `bAutoInitializeSession` 为 `false`，则调用 `StartSession` 请在预期触发器立即发送之前显式执行。你也可以绑定 **角色数据加载完成时** (`OnCharacterDataLoadEvent_V2`) 并在该事件中调用触发器，当你需要确认角色数据已加载时。

### 下一步

{% content-ref url="/pages/453cd3ea71434b9c4a8a7da307779eeb39996f99" %}
[模板键](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/template-keys.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 %}


---

# 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-triggers.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.