> 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 角色通过在你的场景中执行物理行为来响应玩家请求。当学员说“取来灭火器”时，角色会导航到它旁边。当学生说“指向图表”时，角色会转身并面向它。后端会识别要做什么以及目标是谁；Unity 通过一个简单且可扩展的管道来执行该行为。

### 动作管道如何工作

每个动作请求都会经过四个阶段：

```mermaid
graph LR
    A["玩家说话或输入"] --> B["Convai 识别动作 + 目标"]
    B --> C["ConvaiCharacter 接收命令批次"]
    C --> D["ConvaiActionDispatcher 解析并执行"]
    D --> E["执行器运行场景中的行为"]
```

Convai 后端会从你在连接时注册的可供性中选择动作名称和可选目标。Unity 会将该目标解析为场景中的 `GameObject` 并运行绑定的执行器组件。

### 关键概念

| 概念        | 其含义                                                                                                   |
| --------- | ----------------------------------------------------------------------------------------------------- |
| **动作可供性** | 后端允许请求哪些动作名称。编写于 `ConvaiActionConfigSource` 或在连接时被覆盖。                                                 |
| **动作目标**  | 后端允许引用哪些对象和角色。也编写于 `ConvaiActionConfigSource`.                                                        |
| **动作事件**  | 后端在一次回合中返回的有序命令批次。通过以下方式公开： `ConvaiCharacter.OnActionsReceived`.                                      |
| **本地执行**  | 可选的 Unity 端执行，通过 `ConvaiActionDispatcher` 是位于 `IConvaiActionExecutor`。如果你想自行处理它们，可以不使用调度器而直接接收原始动作事件。 |

### 所需组件

| 组件                         | 必需      | 用途                  |
| -------------------------- | ------- | ------------------- |
| `ConvaiCharacter`          | 始终      | 接收来自 Convai 的动作命令批次 |
| `ConvaiActionConfigSource` | 是       | 编写连接时可供性（动作、对象、角色）  |
| `ConvaiActionDispatcher`   | 可选      | 通过绑定的执行器自动执行接收到的批次  |
| 一个或多个执行器组件                 | 如果使用调度器 | 执行实际的场景内行为          |

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

### 执行器

Convai SDK 随附六个执行器组件：

| 执行器                             | 行为                                                     |
| ------------------------------- | ------------------------------------------------------ |
| `LookAtTargetActionExecutor`    | 在可配置的时长内平滑旋转 NPC 以面向目标                                 |
| `UnityEventActionExecutor`      | 触发一个 `UnityEvent` — 无需编写脚本即可将任何动作连接到在 Inspector 中配置的回调 |
| `TransformMoveToActionExecutor` | 立即将 NPC 瞬移到目标位置 — 仅用于原型开发                              |
| `NavMeshMoveToActionExecutor`   | 驱动一个 `NavMeshAgent` 使用路径寻找到达目标                         |
| `AnimatorTriggerActionExecutor` | 通过可配置的绑定列表将动作名称映射为 Animator 触发器                        |
| `PickUpActionExecutor`          | 组合：导航到目标 → 触发动画 → 将对象附加到手上                             |

{% hint style="warning" %}
`TransformMoveToActionExecutor` 会立即将角色传送过去，不带动画或路径查找。仅用于快速原型开发。请将其替换为 `NavMeshMoveToActionExecutor` 或自定义执行器。
{% endhint %}

### 下一步

要在场景中设置一个可工作的动作，请先从快速入门指南开始。等你的第一个动作端到端运行后，请阅读配置参考，以了解完整的 `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/111bca064ba7041a987662d038af4d71d58a32cd" %}
[配置角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/configuring-actions.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 %}


---

# 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-unity-sdk/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.