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

# 叙事触发器

在 Convai chatbot 组件上调用命名叙事触发器或动态上下文消息，以推进故事图并处理区段变化事件。

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

### 选择正确的函数

| 目标                | 函数            | 发送内容                                |
| ----------------- | ------------- | ----------------------------------- |
| 使用控制面板中的触发器名称推进图  | **调用叙事设计触发器** | `trigger-message` 使用 `trigger_name` |
| 将运行时消息作为对话上下文进行暂存 | **调用语音**      | 通过……的动态上下文事件 `AddContextEvent`      |

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

**收到叙事章节时** 仅在 Convai 通过……确认章节变更后才会触发 `BTResponse` 数据包。无论调用哪个函数，它都不会触发。

### 调用命名触发器

**调用叙事设计触发器** (`InvokeNarrativeDesignTrigger`）发送一个 `TriggerName` 字符串到 Convai，通过 `SendTriggerMessage`。Convai 会将该名称与控制面板中为当前章节配置的出站触发器进行匹配。

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

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

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

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

**调用语音** (`ExecuteNarrativeTrigger`）通过……暂存一个动态上下文事件 `AddContextEvent` 使用 `EC_RunLLMOption::Always`。它不会发送 `trigger-message` 数据包，也不会排入 `PendingTriggers`.

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

使用纯文本 `TriggerMessage` 当角色应将消息作为上下文处理时，例如 `玩家以 82% 的准确率完成了疏散演练`。将消息用 `<speak>` 标记包裹起来，当角色应直接说出文本时，例如 `<speak>Attention: the evacuation route is now open.</speak>`.

如果 Convai 判断适合进行章节变更， **收到叙事章节时** 仍会通过相同的 `BTResponse` 路径。

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

### 处理章节变更事件

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

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

要在 Blueprint 中绑定：将 `UConvaiChatbotComponent` 引用拖到事件图中，然后选择 **分配 On Narrative Section Received** 从上下文菜单中。

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

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

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

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

### 会话就绪

`bAutoInitializeSession` 在 `UConvaiChatbotComponent` 默认为 `true`。启用后，组件会调用 `StartSession` 在 **开始运行**。在会话连接前调用的命名触发器会排入 `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 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-triggers.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.