> 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["分发器解析目标和定义"]
    D --> E["分发器检查语音门禁（仅第一步）"]
    E --> F["执行器运行场景内行为"]
```

Convai 会从当前的动作可供性中选择动作名称和可选目标——这些动作、对象和角色是在连接时注册的，或在会话中途更改的。 `ConvaiActionDispatcher` 将目标解析到场景中的对象 `GameObject` 并首先查找匹配的动作定义。在新的批次的第一步运行之前，它会检查该步骤是否启用了语音门禁。如果启用了，分发器会等待角色开始说话、停止说话或完成轮次——以先发生者为准——这样物理动作就不会跑到角色的语音台词前面。只有在门禁释放后，绑定的执行器组件才会运行。

语音门禁只适用于批次的第一步，而且仅在 `WaitForBotSpeech` 已在命令或其动作定义上设置时。分发器的 `_speechGateTimeoutSeconds` 字段会限制其等待时长——默认 2 秒——因此如果没有触发语音事件，批次不会无限期卡住。可选的 `DelayAfterBotSpeechSeconds` 值会在门禁释放后再额外保持该步骤一段固定时间。

动作可供性和目标并不会在整个会话中保持固定。通过 `ConvaiCharacter.DynamicContext` 在会话中途发送的更改会由 Convai 确认：Unity 会先将更改排队，并且只有在 Convai 确认后才在本地应用，且会按发送顺序提交队列中的更改。Convai 从未确认的更新，或带有错误的确认，会被丢弃且不会重试。如果某个确认报告该更改需要重新连接， `ConvaiCharacter` 则会记录警告而不会自动重新连接——你的代码负责触发重连。

### 关键概念

| 概念        | 含义                                                                                                    |
| --------- | ----------------------------------------------------------------------------------------------------- |
| **动作可供性** | Convai 允许请求的动作名称。可在 `ConvaiActionConfigSource` 中编写，或在连接时覆盖。                                           |
| **动作目标**  | Convai 允许引用的对象和角色。同样在 `ConvaiActionConfigSource`.                                                     |
| **操作事件**  | Convai 在一次轮次中返回的有序命令批次。通过 `ConvaiCharacter.OnActionsReceived`.                                        |
| **本地执行**  | 通过 `ConvaiActionDispatcher` 和 `IConvaiActionExecutor`在 Unity 侧执行的可选功能。如果你想自己处理它们，可以直接接收原始动作事件，而无需分发器。 |
| **动作集**   | 可复用 `ConvaiActionSet` 资源，让多个角色共享同一套已编写好的动作定义，而不是为每个角色重复编写。                                            |

### 所需组件

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

代码、场景和预制体通过上表中的类名引用这些组件；Inspector 会在 **Inspector 名称** 列中显示更友好的名称。

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

### 执行器

Convai SDK 附带 21 个内置执行器组件，按角色上所需内容分为六个套件：

| 套件           | 包含                                               | 角色所需的组件                                                                                             |
| ------------ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| 流程与工具        | 触发 Unity 事件、等待、按顺序运行、显示或隐藏对象、播放 Animator 状态、播放声音 | 除基础动作组件外无需其他内容——适用于任何角色                                                                             |
| 观察           | 计数目标组、测量距离                                       | 角色上无需额外内容；Count Target Group 需要一个 `ConvaiActionTargetGroup` 在目标上                                    |
| 注意力（Gaze 模块） | 看向目标、观察玩家、扫描环境                                   | `ConvaiGazeController`                                                                              |
| 表情           | 设置情绪、反应、点头或摇头                                    | `ConvaiEmotionController` （设置情绪、反应）或 `ConvaiBodyLanguageController` （点头或摇头）                         |
| 手势           | 播放手势、指向目标                                        | `ConvaiBodyAnimationController` （身体动画模块）                                                            |
| 移动           | 走向目标、带领玩家前往目标、转身面向目标、跟随玩家、返回起始点                  | `ConvaiNavMeshLocomotion` 适用于除 Turn To Face Target 之外的每个执行器，后者需要 `ConvaiBodyAnimationController` 改为 |

注意力、手势和移动套件通过 Gaze 和 Body Animation 具身模块运行——见 [具身](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment.md) ——因此角色在这些动作可用之前必须先安装匹配的模块。通过 Actions Editor 的目录添加执行器时，如果缺少所需的模块组件，会自动将其添加；见 [Actions Editor](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-editor.md).

参见 [动作执行器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md) 了解每个执行器的 Inspector 字段和失败模式。

### 下一步

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

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

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

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

{% content-ref url="/pages/1398e3302b345ef93934a0e6c93b4d8e576ab00e" %}
[排查角色动作问题](/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.