> 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 所说与角色在关卡中的行为连接起来。当玩家发言时，Convai 可以同时返回一段口语回复和一系列命名动作——前往某个位置、跟随玩家、与某个对象交互。插件会将这些动作分发到 NPC Actor 上匹配的 Blueprint 处理函数事件，并按顺序逐个执行。

### 必需设置

| 组件 / 资源                        | 用于                    | 说明                                               |
| ------------------------------ | --------------------- | ------------------------------------------------ |
| `Convai 聊天机器人` 组件              | 所有动作                  | 包含 `环境` 属性（动作模板、对象、角色）以及 `ActionsQueue`.         |
| `Convai 玩家` 组件                 | 所有动作                  | 玩家 Pawn 上进行语音输入所必需。                              |
| Blueprint 处理函数                 | 每个应执行的动作              | 每个动作名称对应一个函数，接收 `FConvaiResultAction`.           |
| NPC Actor 上的 AI Controller     | 移动动作（`Move To`, `跟随`) | 用于 `AI 移动到` 才能正常工作。使用 Unreal 内置的 `AIController`. |
| `Nav Mesh Bounds Volume` （已构建） | 移动动作                  | 必须覆盖 NPC 生成点和所有导航目标。场景更改后请重新构建。                  |

对于非移动动作（自定义行为、动画、状态变化），只需要 chatbot 组件和 Blueprint 处理函数。

### 关键概念

六个概念构成了该系统的工作基础。下面每一节都会详细介绍其中一个，但先给出一个快速概览：

| 概念         | 其含义                                                                |
| ---------- | ------------------------------------------------------------------ |
| **动作契约**   | 会话开始前发送给 Convai 的动作、对象和角色列表——定义了角色被允许执行和引用的内容。                     |
| **动作管线**   | 两条并行通道：一条播放语音音频，另一条按顺序存储并执行一系列动作。                                  |
| **队列与分发**  | 插件维护一个待处理动作队列。每次处理函数报告完成后，队列前进一项，下一个处理函数运行。                        |
| **完成模型**   | 每个处理函数都必须调用 `HandleActionCompletion` 在完成时调用。若不调用，队列将停滞，后续动作永远不会执行。 |
| **等待语音门控** | 一个可选的按动作设置的标志，它会延迟该动作的触发，直到角色开始或结束说话，从而使移动与语音保持同步。                 |
| **运行时变更**  | 会话进行时可以添加或移除对象和角色；本地环境会立即更新。                                       |

### 动作契约

会话开始前，chatbot 组件会读取 `环境` 属性——其动作模板、已注册对象和角色列表——并将这些信息发送给 Convai。Convai 会据此知道角色可以执行哪些动作，以及在根据玩家语音选择动作时可以引用哪些对象。

该契约由三部分组成：

* **动作** ——一个有序列表，包含 `FConvaiAction` 模板，每个模板都有一个名称、一个可选描述和可选的类型参数。该列表定义在 `环境` 属性的 `UConvaiChatbotComponent`中，位于 `动作` 字段中。
* **Objects** ——一个数组，包含 `FConvaiObjectEntry` 描述可交互场景对象的值。每个条目都有一个 `名称`，一个可选的 `说明`，以及导航目标字段。
* **Characters** ——一个数组，包含 `FConvaiObjectEntry` 描述场景中其他角色的值。

该 **启用操作** 在 `Convai 聊天机器人` 组件的 `环境` 属性上切换启用可作为总开关。其默认值为 `true` 在每个新组件上，因此该功能开箱即用即处于开启状态。禁用后，会话开始时不会发送该契约，角色将仅作为纯对话型 NPC 行为。

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

### 动作管线

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

1. **语音通道** ——音频流传送到角色的音频组件进行播放。chatbot 会触发 `On Actions Received` 是位于 `OnStartedTalking` / `OnFinishedTalking` 事件，随着语音进展而触发。
2. **动作通道** ——Convai 根据 `action_config` 契约解析响应并返回一个 `FConvaiResultAction` 结构体序列。插件将该序列存储在 `ActionsQueue` on `UConvaiChatbotComponent`.

两条通道彼此独立。语音播放时，动作队列同时执行。

### 队列与分发

插件维护一个 `FConvaiResultAction` 项的队列，存放于 `ActionsQueue`。当一个新的动作序列到达时，插件：

1. 如果队列中已包含一个正在进行的动作，则保留该第一个动作，并用传入序列替换其余已排队的动作。如果队列为空，则按原样存储传入序列。
2. 调用 `StartFirstAction`，它会读取队列中的第一项并调用 `TriggerNamedBlueprintAction`.
3. `TriggerNamedBlueprintAction` 会查找一个 Blueprint 函数或事件，其名称与 `Action` 结果中的字段匹配。它先检查所属 Actor，然后检查 chatbot 组件。处理函数可以接受一个 `FConvaiResultAction` 参数，或不接受参数。

分发器基于名称。Unreal 解析处理函数名时不区分大小写，但空格和标点仍必须匹配。如果在任一目标上都找不到匹配的函数，插件会记录警告，不会调用处理函数，队列将停滞，直到 `HandleActionCompletion` 或 `AbortActionSequence` 被调用。

### 等待语音门控

`FConvaiAction` 具有一个 `bWaitForBotSpeech` 标志。当它设置在某个动作模板上，并且该动作作为新接收序列的第一个动作到达时（即序列到达时队列为空），插件会延迟启动该动作，直到 Convai 开始说话（`OnStartedTalking`）或说完话（`OnFinishedTalking`），以先触发者为准。每个角色都有一个超时（`ActionWaitForBotSpeechTimeoutSec`，默认 `2.0` 秒，不向 Blueprint 暴露），如果两种语音事件在时间内都未到达，仍会触发该动作。

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

### 完成模型

处理函数负责报告结果。处理函数完成工作后，必须调用 `HandleActionCompletion` 在 `UConvaiChatbotComponent`:

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

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

如果处理函数遇到不可恢复的错误，并希望 Convai 生成一份全新的动作计划，它会调用 `AbortActionSequence` 来代替，同时可选地传入一段对出错情况的文字说明。

下图展示了一个单动作从开始到完成的交互流程。当一个序列包含多个动作时，每次 `HandleActionCompletion(true)` 调用都会使队列前进一项。

```mermaid
sequenceDiagram
    参与者 Player
    参与者 Convai
    参与者 Plugin
    参与者 Handler

    Player->>Convai: 语音输入
    Convai-->>Plugin: 语音音频 + 动作序列
    Plugin->>Plugin: 更新 ActionsQueue
    Plugin->>Handler: TriggerNamedBlueprintAction(Action, ResultAction)
    Handler->>Handler: 执行行为
    Handler->>Plugin: HandleActionCompletion(IsSuccessful)
    Plugin->>Plugin: 出队并启动下一个动作
    Plugin->>Convai: 上下文事件（结果）
```

### 运行时环境变更

可以在运行时使用 `AddObject`, `RemoveObject`, `AddCharacter`，以及 `RemoveCharacter` 上的一组方法 `UConvaiChatbotComponent`从本地环境中添加或移除对象和角色。本地 `EnvironmentData` 镜像会立即更新，插件在解析后续动作结果时会使用它。

运行时变更不会改变动作集本身，动作集在下次重新连接前保持固定。对于实时会话，场景上下文更新会通过 `update-scene-metadata` 发送，但前提是该更改条目尚未包含在连接时的场景元数据快照中。

### 下一步

{% content-ref url="/pages/9d759a9e65c274645e91b88390d8bb2c4762bd80" %}
[配置动作](/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" %}
[内置动作处理器](/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" %}
[构建自定义动作处理器](/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" %}
[Actions Blueprint 参考](/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 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/character-actions/how-character-actions-work.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.