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

# 角色动作的工作原理

了解 Convai 角色动作管线——Convai 如何选择动作、Unity 如何解析目标，以及需要哪些组件。

Convai 角色动作系统允许 NPC 角色通过在场景中执行物理行为来响应玩家请求。当学员说“拿取灭火器”时，角色会移动到灭火器旁；当学生说“指向示意图”时，角色会转身面向示意图。Convai 会识别要执行的操作以及目标对象；Unity 则通过简单且可扩展的管线执行该行为。

### 动作管线的工作原理

每个动作请求都会经过以下六个阶段：

```mermaid
graph LR
    A["玩家说话或输入文本"] --> B["Convai 识别动作和目标"]
    B --> C["ConvaiCharacter 接收命令批次"]
    C --> D["Dispatcher 解析目标和定义"]
    D --> E["Dispatcher 检查语音门控（仅限第一步）"]
    E --> F["Executor 执行场景内行为"]
```

Convai 会根据当前动作能力项选择动作名称和可选目标；这些能力项包括连接时注册或会话期间变更的动作、对象和角色。 `ConvaiActionDispatcher` 会将目标解析为场景中的 `GameObject` ，并首先查找匹配的动作定义。开始执行新批次的第一步之前，它会检查该步骤是否启用了语音门控。如果已启用，Dispatcher 会等待角色开始说话、停止说话或完成本轮发言——以最先发生的事件为准——以免物理动作先于角色的语音台词执行。只有门控解除后，绑定的执行器组件才会运行。

语音门控仅适用于批次中的第一步，且仅当命令或其动作定义设置了 `WaitForBotSpeech` 时才会启用。Dispatcher 的 `_speechGateTimeoutSeconds` 字段会限制等待时长（默认 2 秒），因此即使没有触发语音事件，批次也不会无限期停滞。可选的 `DelayAfterBotSpeechSeconds` 值会在门控解除后，让该步骤再等待一段固定时间。

动作能力项和目标在整个会话期间并非固定不变。通过 `ConvaiCharacter.DynamicContext` 在会话期间发送的变更会由 Convai 确认：Unity 会将变更排入队列，并且只有在 Convai 确认后才会在本地应用，按发送顺序提交排队的变更。Convai 未确认或以错误方式确认的更新会被丢弃，不会重试。如果确认信息指出该变更需要重新建立连接， `ConvaiCharacter` 会记录警告，而不会自动重新连接——触发重新连接由你的代码负责。

### 关键概念

| 概念        | 含义                                                                                                               |
| --------- | ---------------------------------------------------------------------------------------------------------------- |
| **动作能力项** | Convai 可以请求的动作名称。在 `ConvaiActionConfigSource` 中配置，或在连接时覆盖。                                                       |
| **动作目标**  | Convai 可以引用的对象和角色。同样在 `ConvaiActionConfigSource`.                                                                |
| **动作事件**  | 中配置。 `ConvaiCharacter.OnActionsReceived`.                                                                        |
| **本地执行**  | 可选的 Unity 端执行，通过 `ConvaiActionDispatcher` 和 `IConvaiActionExecutor`实现。如果你想自行处理原始动作事件，也可以不使用 Dispatcher，直接接收这些事件。 |
| **动作集**   | 可重复使用的 `ConvaiActionSet` 资源，让多个角色共享相同的已配置动作定义，而无需为每个角色重复配置。                                                      |

### 必需组件

| 组件                         | Inspector 中的名称       | 必填     | 用途                                               |
| -------------------------- | -------------------- | ------ | ------------------------------------------------ |
| `ConvaiCharacter`          | Convai Character     | 始终     | 接收来自 Convai 的动作命令批次                              |
| `ConvaiActionConfigSource` | Convai Actions       | 是      | 编写角色的动作定义和场景知识                                   |
| `ConvaiActionDispatcher`   | Convai Action Runner | 可选     | 通过绑定的执行器自动执行收到的批次                                |
| 一个或多个执行器组件                 | 因执行器而异               | 使用调度器时 | 执行实际的场景内行为；其中一些执行器依赖 Gaze 或 Body Animation 等具身模块 |

代码、场景和预制件通过上表中的类名引用这些组件；Inspector 中显示的易读名称位于 **Inspector 名称** 列。

{% hint style="info" %}
`ConvaiActionDispatcher` 是可选的。如果你希望在自己的游戏代码中处理动作批次，可以直接订阅 `ConvaiCharacter.OnActionsReceived` 并完全跳过调度器。
{% endhint %}

### 执行器

Convai SDK 内置了 21 个执行器组件，根据它们对角色的要求分为六个套件：

| 套件           | 涵盖内容                                             | 角色所需组件                                                                                     |
| ------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| 流程与实用工具      | 触发 Unity 事件、等待、按顺序运行、显示或隐藏对象、播放 Animator 状态、播放声音 | 除基础动作组件外无需其他组件——适用于任何角色                                                                    |
| 观察           | 统计目标组成员数量、测量距离                                   | 角色无需任何组件；统计目标组成员数量需要在目标上添加 `ConvaiActionTargetGroup` 组件                                    |
| 注意力（Gaze 模块） | 看向目标、注视玩家、扫描环境                                   | `ConvaiGazeController`                                                                     |
| 表情           | 设置情绪、做出反应、点头或摇头                                  | `ConvaiEmotionController` （设置情绪、做出反应）或 `ConvaiBodyLanguageController` （点头或摇头）              |
| 手势           | 播放手势、指向目标                                        | `ConvaiBodyAnimationController` （Body Animation 模块）                                        |
| 移动           | 走向目标、带领玩家前往目标、转向面对目标、跟随玩家、返回起点                   | `ConvaiNavMeshLocomotion` 适用于除“转向面对目标”之外的所有执行器；该执行器需要 `ConvaiBodyAnimationController` 而非前者 |

注意力、手势和移动套件通过 Gaze 和 Body Animation 具身模块运行——请参阅 [具身](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment.md) — 因此，角色必须先安装相应模块，这些动作才能生效。通过 Actions Editor 的目录添加执行器时，如果缺少所需模块组件，系统会自动添加；请参阅 [Actions Editor](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-editor.md).

请参阅 [操作执行器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md) 了解每个执行器的 Inspector 字段和故障模式。

### 后续步骤

要在场景中设置一个可正常运行的操作，请从快速入门指南开始。第一个操作端到端运行后，请阅读配置参考，了解完整的 `ConvaiActionConfigSource` 选项，然后为你的项目选择或构建合适的执行器。

{% content-ref url="/pages/7f0d213ddc809cfd39ab2bc41492ddf8e54b6c19" %}
[角色动作快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/b1d09b6e9430d66a69feaa877bc4844f6ed840d0" %}
[动作编辑器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-editor.md)
{% endcontent-ref %}

{% content-ref url="/pages/f592d9dc3ad261e175159690b86cdd4b50bb4d81" %}
[动作执行器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md)
{% endcontent-ref %}

{% content-ref url="/pages/1398e3302b345ef93934a0e6c93b4d8e576ab00e" %}
[排查角色动作问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/debugging-and-troubleshooting.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-unity-sdk/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.
