> 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/character-actions/how-character-actions-work.md).

# 角色动作的工作原理

了解 Convai 角色动作如何从会话设置进入排队的 Blueprint 处理器执行，并完成报告。

角色动作将 Convai 的话语与角色在关卡中的行为联系起来。玩家发言时，Convai 可以同时返回语音回复和一系列已命名的动作，例如移动到某个位置、跟随玩家或与物体互动。插件会将这些动作分发给 NPC Actor 上对应的蓝图处理程序事件，并按顺序逐个执行。

### 所需设置

| 组件 / 资源                        | 适用范围                      | 备注                                                    |
| ------------------------------ | ------------------------- | ----------------------------------------------------- |
| `Convai Chatbot` 组件            | 所有动作                      | 承载 `Environment` 属性（动作模板、物体、角色）以及 `ActionsQueue`.     |
| `Convai Player` 组件             | 所有动作                      | 玩家 Pawn 上必须具备此组件，才能输入语音。                              |
| 蓝图处理函数                         | 所有需要执行的动作                 | 每个动作名称对应一个函数，接收 `FConvaiResultAction`.                |
| NPC Actor 上的 AI Controller     | 移动动作（`Move To`, `Follow`) | 适用范围 `AI Move To` 正常工作。请使用 Unreal 内置的 `AIController`. |
| `Nav Mesh Bounds Volume` （已构建） | 移动动作                      | 必须覆盖 NPC 的生成点和所有导航目标。关卡发生变化后，请重新构建。                   |

对于非移动动作（自定义行为、动画、状态更改），只需 chatbot 组件和蓝图处理程序。

### 关键概念

系统的运行基于六个概念。下文各节会逐一详细介绍，先快速了解一下：

| 概念         | 含义                                                              |
| ---------- | --------------------------------------------------------------- |
| **动作约定**   | 会话开始前发送给 Convai 的动作、物体和角色列表，用于定义角色可以执行哪些操作以及可以引用哪些内容。           |
| **动作流水线**  | 分为两条并行通道：一条播放语音音频，另一条存储并按顺序执行一系列动作。                             |
| **队列与分发**  | 插件会维护一个待处理动作队列。每当处理程序报告完成，队列就前进一项，并运行下一个处理程序。                   |
| **完成模型**   | 每个处理程序完成时都必须调用 `HandleActionCompletion` 。若未调用，队列就会停滞，后续动作也不会执行。 |
| **等待语音门控** | 一个可选的逐动作标志，可将动作延迟到角色开始或结束说话时才触发，从而使移动与语音保持同步。                   |
| **运行时修改**  | 会话进行期间可以添加或移除物体和角色；本地环境会立即更新。                                   |

### 动作约定

会话开始前，chatbot 组件会读取 `Environment` 属性中的操作模板、已注册对象和角色列表，并将这些信息发送给 Convai。Convai 利用这些信息，在响应玩家语音选择操作时，了解角色可以执行哪些操作以及可以引用哪些对象。

该契约包含三个部分：

* **操作** ——有序的 `FConvaiAction` 模板列表，每个模板都有名称、可选描述和可选的类型化参数。该列表定义在 `Environment` 属性中，该属性属于 `UConvaiChatbotComponent`，列表位于其 `Actions` 字段下。
* **对象** ——由 `FConvaiObjectEntry` 值组成的数组，用于描述场景中可交互的对象。每个条目都有一个 `Name`、一个可选的 `Description`以及导航目标字段。
* **角色** ——由 `FConvaiObjectEntry` 值组成的数组，用于描述场景中的其他角色。

“ **启用操作** ”开关位于 `Convai Chatbot` 组件的 `Environment` 属性中，充当总开关。每个新组件的默认值都是 `true` ，因此该功能开箱即用。禁用后，系统不会在会话开始时发送契约，角色将表现为纯对话型 NPC。

{% hint style="info" %}
操作集在会话开始时固定。运行时通过 `AddAction` / `RemoveAction` 添加或删除操作只会影响下一次会话，当前会话仍保留连接时的操作集。
{% endhint %}

### 动作流水线

当玩家与 Convai 角色交谈时，插件通过两条并行通道处理响应：

1. **语音通道** ——音频流发送到角色的音频组件进行播放。随着语音播放的进展，聊天机器人会触发 `On Actions Received` 和 `OnStartedTalking` / `OnFinishedTalking` 事件。
2. **操作通道** ——Convai 根据 `action_config` 契约解析响应，并返回一个序列，包含 `FConvaiResultAction` 结构体。插件会将此序列存储在 `ActionsQueue` 上 `UConvaiChatbotComponent`.

这两条通道相互独立。语音播放的同时，动作队列也会执行。

### 队列与分发

插件会维护一个队列，其中包含 `FConvaiResultAction` 项，存储在 `ActionsQueue`中。收到新的动作序列时，插件会：

1. 如果队列中已有正在执行的动作，则保留该动作，并用新收到的序列替换其余排队动作。如果队列为空，则按原样存储新收到的序列。
2. 调用 `StartFirstAction`，该函数会读取队列中的第一个条目并调用 `TriggerNamedBlueprintAction`.
3. `TriggerNamedBlueprintAction` 会查找名称与结果的 `Action` 字段相匹配的蓝图函数或事件。它会先检查所属的 Actor，再检查聊天机器人组件。处理程序可以接受一个 `FConvaiResultAction` 参数，也可以不接受参数。

分发器根据名称进行匹配。Unreal 会忽略处理程序名称的大小写，但空格和标点符号仍必须完全匹配。如果两个目标上都找不到匹配的函数，插件会记录一条警告，不会调用处理程序，并且队列会停滞，直到调用 `HandleActionCompletion` 或 `AbortActionSequence` 。

### 取消动作计划

角色在动作执行过程中可能会改变计划——玩家可能会改变其行动方向，也可能出现新情况，让当前计划失去意义。 `CancelCurrentActionPlan` （位于 `UConvaiChatbotComponent` ，蓝图显示名称为 **取消当前动作计划**）采用协作式取消，而不是强行从正在运行的处理程序下方抽走队列：排队中的动作会立即丢弃，但系统会向活动处理程序发送一个可选的蓝图事件，其名称必须恰好为 `Cancel <Action Name>`，并传入原始的 `FConvaiResultAction`，以便处理程序在替换计划开始前妥善停止计时器、委托或潜在任务。重复调用只会发出一次取消请求，并等待一次终止确认。

实现了可选取消事件的处理程序，必须在完全停止运行后调用 `HandleActionCancellation` ——也就是计时器、委托、任务和回调均已停止之后。此调用不会报告成功或失败，并会释放暂存的替换计划，让队列继续推进。未实现取消事件的处理程序会自行运行直至完成；无论哪种情况，自定义取消处理程序都必须且只能调用一个终止 API—— `HandleActionCancellation` 或使用现有的完成路径——绝不能两者都调用。

在聊天机器人组件上启用 `bEnableCancelActionPlanAction` （蓝图显示名称为 **启用取消动作计划**，类别为 `Convai|Actions|Experimental`）后，会添加一个保留的 `取消操作计划` 发送给 Convai 的契约中的控制操作，使角色本身能够在玩家转而执行其他操作或放弃当前操作时，决定是否调用取消。请参阅 [配置操作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/configuring-actions.md#experimental-built-in-actions) 了解该开关，以及 [操作蓝图参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.md) 查看完整的函数和事件列表。

### 等待语音门控

`FConvaiAction` 包含一个 `bWaitForBotSpeech` 标志。若在操作模板中启用此标志，且该操作作为新收到的序列中的第一个操作到达（即序列到达时队列为空），插件会延迟启动该操作，直到 Convai 开始说话（`OnStartedTalking`）或说完（`OnFinishedTalking`），以先触发者为准。若在设定时间内未触发任何语音事件，则每个角色各自的超时时间（`ActionWaitForBotSpeechTimeoutSec`，默认值为 `2.0` 秒，不会公开给蓝图）到期后仍会执行该操作。

可选的 `DelayAfterBotSpeechSec` 字段会在语音条件满足后额外增加一段延迟。

### 完成模型

处理程序负责报告执行结果。处理程序完成工作后，必须在 `UConvaiChatbotComponent` 上调用 `HandleActionCompletion`:

* `IsSuccessful = true` — 插件会将当前操作出队，并启动下一个操作。
* `IsSuccessful = false` — 插件会清空剩余队列。角色不会尝试执行下一个操作。

当 `bAutoReport` 为 `true` （默认值）时，插件还会向 Convai 发送一个描述执行结果的上下文事件。Convai 会在生成角色下一条语音回复时使用此信息。

如果处理程序遇到无法恢复的错误，并希望 Convai 生成一份全新的操作计划，则应改为调用 `AbortActionSequence` 并可选择传入对错误情况的文字说明。

下图展示了单个操作从开始到完成的交互过程。若一个序列包含多个操作，每次调用 `HandleActionCompletion(true)` 都会将队列推进一步。

```mermaid
sequenceDiagram
    participant Player
    participant Convai
    participant Plugin
    participant Handler

    Player->>Convai: Speech input
    Convai-->>Plugin: Speech audio + action sequence
    Plugin->>Plugin: Update ActionsQueue
    Plugin->>Handler: TriggerNamedBlueprintAction(Action, ResultAction)
    Handler->>Handler: Execute behavior
    Handler->>Plugin: HandleActionCompletion(IsSuccessful)
    Plugin->>Plugin: Dequeue and start next action
    Plugin->>Convai: Context event (outcome)
```

### 运行时环境变更

可以在运行时使用以下方法，在本地环境中添加或移除对象和角色： `AddObject`, `RemoveObject`, `AddCharacter`和 `RemoveCharacter` 这些方法属于 `UConvaiChatbotComponent`。本地的 `EnvironmentData` 镜像会立即反映这些变更，插件在解析后续操作结果时也会使用它。

运行时变更不会改变操作集；操作集会固定不变，直到下次重新连接。对于实时会话，如果变更条目不属于连接时场景元数据快照的一部分，则会通过 `update-scene-metadata` 发送场景上下文更新。

### 后续步骤

{% content-ref url="/pages/9d759a9e65c274645e91b88390d8bb2c4762bd80" %}
[配置动作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/configuring-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/d1aaea82f339a27b3ce67918aa343caebba0762c" %}
[内置动作处理器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/built-in-action-handlers.md)
{% endcontent-ref %}

{% content-ref url="/pages/4034933484ffa13478584311631f11ea8d503bb4" %}
[构建自定义动作处理器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/building-custom-action-handlers.md)
{% endcontent-ref %}

{% content-ref url="/pages/8e18d509947b40274dca96b384f432486348198f" %}
[动作 Blueprint 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-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/character-actions/how-character-actions-work.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.
