> 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 角色动作系统让 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`.                                         |
| **本地执行**  | 通过 Unity 侧的可选执行，借助 `ConvaiActionDispatcher` 和 `IConvaiActionExecutor`。如果你想自己处理它们，可以直接接收原始动作事件，而无需调度器。 |
| **动作集**   | 可复用的 `ConvaiActionSet` 资源，使多个角色能够共享同一套已编写的动作定义，而无需为每个角色重复编写。                                          |

### 所需组件

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

类名称与早期 SDK 版本保持不变；仅检查器标签发生了变化，因此现有脚本、场景和预制体无需迁移。

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

### 执行器

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

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

注意力、手势和移动套件通过 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) 以查看每个执行器的检查器字段和失败模式。

### 下一步

要在你的场景中搭建一个可工作的动作设置，先从快速入门指南开始。等你的第一个动作端到端运行后，再阅读配置参考以了解完整的 `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 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.