> 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` 将目标解析到场景中 `游戏对象` 并首先查找匹配的动作定义。然后，在新的批次的第一步运行之前，它会检查该步骤是否选择加入语音门控。如果是，Dispatcher 会等待角色开始说话、停止说话，或完成其轮次——以先发生者为准——这样物理动作就不会抢在角色的语音台词之前执行。只有在门控放行后，绑定的 executor 组件才会运行。

语音门控仅适用于批次的第一步，并且仅在 `等待机器人发言` 在命令或其动作定义上设置时才会生效。Dispatcher 的 `_speechGateTimeoutSeconds` 字段限制其等待时长——默认 2 秒——因此如果没有触发语音事件，批次不会无限期停滞。一个可选的 `机器人发言后延迟秒数` 值会在门控放行后再让该步骤保持固定时长。

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

### 关键概念

| 概念        | 含义                                                                                              |
| --------- | ----------------------------------------------------------------------------------------------- |
| **动作可供项** | Convai 被允许请求的动作名称。作者在 `ConvaiActionConfigSource` 中，或在连接时覆盖。                                     |
| **动作目标**  | Convai 被允许引用的对象和角色。同样作者在 `ConvaiActionConfigSource`.                                            |
| **动作事件**  | Convai 在一次回合中返回的有序命令批次。通过 `ConvaiCharacter.OnActionsReceived`.                                  |
| **本地执行**  | 通过 `ConvaiActionDispatcher` 和 `IConvaiActionExecutor`。如果你想自己处理它们，可以在没有 dispatcher 的情况下接收原始动作事件。 |
| **动作集**   | 可重复使用的 `ConvaiActionSet` 资源，允许多个角色共享相同的已编写动作定义，而无需为每个角色重复一遍。                                    |

### 所需组件

| 组件                         | 检查器名称                | 必需              | 用途                                                 |
| -------------------------- | -------------------- | --------------- | -------------------------------------------------- |
| `ConvaiCharacter`          | Convai Character     | 始终可用            | 接收来自 Convai 的动作命令批次                                |
| `ConvaiActionConfigSource` | Convai Actions       | 是               | 为角色的动作定义和场景知识编写内容                                  |
| `ConvaiActionDispatcher`   | Convai Action Runner | 可选              | 通过已绑定的 executor 自动执行接收到的批次                         |
| 一个或多个 executor 组件          | 因 executor 而异        | 如果使用 dispatcher | 执行实际的场景内行为；其中多个依赖于如 Gaze 或 Body Animation 之类的实体化模块 |

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

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

### 执行器

Convai SDK 随附 21 个内置 executor 组件，按角色上所需内容分成六个包：

| 包            | 覆盖                                               | 角色所需                                                                                       |
| ------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| 流程与工具        | 触发 Unity 事件、等待、按顺序运行、显示或隐藏对象、播放 Animator 状态、播放声音 | 除基础动作组件外无需其他内容——适用于任何角色                                                                    |
| 观察           | 统计目标组、测量距离                                       | 角色上无需任何组件；统计目标组需要目标上的一个 `ConvaiActionTargetGroup` 组件                                       |
| 注意力（Gaze 模块） | 注视目标、观察玩家、扫描环境                                   | `ConvaiGazeController`                                                                     |
| 表情           | 设置情绪、反应、点头或摇头                                    | `ConvaiEmotionController` （设置情绪、反应）或 `ConvaiBodyLanguageController` （点头或摇头）                |
| 手势           | 播放手势、指向目标                                        | `ConvaiBodyAnimationController` （Body Animation 模块）                                        |
| 移动           | 走向目标、引导玩家到目标、转身面向目标、跟随玩家、返回起点                    | `ConvaiNavMeshLocomotion` 适用于除转身面向目标外的每个 executor，后者需要 `ConvaiBodyAnimationController` 而不是 |

注意力、手势和移动包通过 Gaze 和 Body Animation 实体化模块运行——参见 [具身化](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment.md) ——因此角色在这些动作生效前需要安装匹配的模块。如果通过 Actions Editor 的目录添加 executor，而缺少所需模块组件，它会自动添加；参见 [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) 了解每个 executor 的检查器字段和失败模式。

### 下一步

要在场景中配置一个可工作的动作，先从快速入门指南开始。一旦你的第一个动作端到端运行起来，阅读配置参考以了解完整的 `ConvaiActionConfigSource` 选项，然后为你的项目选择或构建合适的 executor。

{% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.