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

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

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

会话中途通过 `ConvaiCharacter.DynamicContext` 发送的更改都由后端确认：Unity 会将更改排队，并且只会在 Convai 确认后在本地应用，且会按发送顺序提交队列中的更改。若某个更新从未被 Convai 确认，或被确认但带有错误，则会被丢弃且不会重试。如果某次确认报告该更改需要重新建立连接， `ConvaiCharacter` Unity 不会自动重新连接，而是会记录一条警告——由你的代码负责触发重连。

### 关键概念

| 概念        | 含义                                                                                                  |
| --------- | --------------------------------------------------------------------------------------------------- |
| **动作可供性** | 后端被允许请求哪些动作名称。在 `ConvaiActionConfigSource` 中编写，或在连接时覆盖。                                             |
| **动作目标**  | 后端被允许引用哪些对象和角色。同样在 `ConvaiActionConfigSource`.                                                      |
| **动作事件**  | 后端返回给某一回合的有序命令批次。通过 `ConvaiCharacter.OnActionsReceived`.                                            |
| **本地执行**  | 通过 `ConvaiActionDispatcher` 和 `IConvaiActionExecutor`进行可选的 Unity 端执行。如果你想自己处理它们，可以不通过分发器直接接收原始动作事件。 |

### 所需组件

| 组件                         | 必需      | 用途                  |
| -------------------------- | ------- | ------------------- |
| `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`          | 复合：导航到目标 → 触发动画 → 将对象附加到手部                         |
| `PutOnActionExecutor`           | 在可配置偏移量处将一个已解析的目标对象放置到另一个对象上                       |

{% 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 %}

{% 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.