> 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/action-executors.md).

# 动作执行器

Executor 是在分发器运行一个动作步骤时执行场景内行为的组件。Convai SDK 随附六个 executor 组件。本页记录每个 Inspector 字段，并说明何时使用各个 executor。

#### LookAtTargetActionExecutor

可在可配置的持续时间内平滑旋转 NPC 使其面向已解析的目标。使用 `Quaternion.Slerp` 并支持取消。

| 属性       | 值                                                     |
| -------- | ----------------------------------------------------- |
| **菜单路径** | `添加组件 → Convai → 动作 → Look At Target Action Executor` |
| **命名空间** | `Convai.Runtime.Actions`                              |
| **需要目标** | 是——返回 `未处理` 如果未解析到目标                                  |

**Inspector 字段：**

| 字段            | 类型          | 默认值    | 说明                                        |
| ------------- | ----------- | ------ | ----------------------------------------- |
| `_rotateRoot` | `Transform` | `null` | 要旋转的 Transform。若未指定，则使用组件自身的 `transform`. |
| `_duration`   | `float`     | `0.5`  | 完成旋转所需的秒数。 `0` 会立即瞬移到位。                   |

**行为：** 该 executor 会在 `_duration` 秒内从当前旋转插值到目标位置朝向。如果根对象或目标在执行过程中被销毁，则返回 `失败`.

#### UnityEventActionExecutor

触发一个 `UnityEvent` 并立即返回 `成功`。不需要解析目标。可用它将任何后端动作连接到 Inspector 绑定的回调，而无需编写代码——切换门、播放声音、打开 UI 面板。

| 属性       | 值                                                  |
| -------- | -------------------------------------------------- |
| **菜单路径** | `添加组件 → Convai → 动作 → Unity Event Action Executor` |
| **命名空间** | `Convai.Runtime.Actions`                           |
| **需要目标** | 没有                                                 |

**Inspector 字段：**

| 字段           | 类型           | 说明                                     |
| ------------ | ------------ | -------------------------------------- |
| `_onExecute` | `UnityEvent` | 每次动作步骤运行时都会调用。可在 Inspector 中绑定任意数量的回调。 |

{% hint style="danger" %}
**`TransformMoveToActionExecutor` 仅用于原型阶段。** 它会立即将角色传送到位，不会有动画或路径寻路。发布给用户之前，请将其替换为 `NavMeshMoveToActionExecutor` 或自定义 executor。
{% endhint %}

#### TransformMoveToActionExecutor

会立即将 NPC 的 Transform 瞬移到解析后的目标位置，并可附加可选偏移。同步执行——在一帧内完成。

| 属性       | 值                                                        |
| -------- | -------------------------------------------------------- |
| **菜单路径** | `添加组件 → Convai → 示例 → Transform Move To Action Executor` |
| **命名空间** | `Convai.Sample.Behaviors`                                |
| **需要目标** | 是——返回 `失败` 如果未解析到目标                                      |

**Inspector 字段：**

| 字段          | 类型          | 默认值         | 说明                                        |
| ----------- | ----------- | ----------- | ----------------------------------------- |
| `_moveRoot` | `Transform` | `null`      | 要移动的 Transform。若未指定，则使用组件自身的 `transform`. |
| `_offset`   | `Vector3`   | `(0, 0, 0)` | 应用到目标位置的世界空间偏移。可用于停在目标前方一点。               |

#### NavMeshMoveToActionExecutor

驱动一个 `NavMeshAgent` 移动到解析后的目标位置，并等待代理到达停止距离。该动作步骤会一直保持激活直到抵达，这意味着分发器会在导航完成前暂停下一步。

| 属性       | 值                                                      |
| -------- | ------------------------------------------------------ |
| **菜单路径** | `添加组件 → Convai → 示例 → NavMesh Move To Action Executor` |
| **命名空间** | `Convai.Sample.Behaviors`                              |
| **需要目标** | 是——返回 `失败` 如果未解析到目标                                    |

**Inspector 字段：**

| 字段                  | 类型             | 默认值   | 说明                                                          |
| ------------------- | -------------- | ----- | ----------------------------------------------------------- |
| `_agent`            | `NavMeshAgent` | 自动解析  | 该 `NavMeshAgent` 要驱动的对象。若未指定，则从同一个 `GameObject` on `Awake`. |
| `_stoppingDistance` | `float`        | `0.5` | 以世界单位表示、代理被视为已到达的距离。                                        |

{% hint style="warning" %}
场景中必须先烘焙 NavMesh，此 executor 才能导航。打开 **窗口 → AI → 导航** 并在进入播放模式前进行烘焙。若代理起始时不在 NavMesh 上， `SetDestination` 会静默失败，而 executor 会一直循环，直到 `TimeoutSeconds` 超时。
{% endhint %}

#### AnimatorTriggerActionExecutor

通过可配置的绑定列表，将后端动作名称映射到 Animator 触发器参数。触发该参数并立即返回 `成功` ——它不会等待动画结束。

| 属性       | 值                                                       |
| -------- | ------------------------------------------------------- |
| **菜单路径** | `添加组件 → Convai → 示例 → Animator Trigger Action Executor` |
| **命名空间** | `Convai.Sample.Behaviors`                               |
| **需要目标** | 没有                                                      |

**Inspector 字段：**

| 字段          | 类型                                   | 默认值  | 说明                                                      |
| ----------- | ------------------------------------ | ---- | ------------------------------------------------------- |
| `_animator` | `Animator`                           | 自动解析 | 该 `Animator` 要驱动的对象。若未指定，则从同一个 `GameObject` on `Awake`. |
| `_bindings` | `List<AnimatorTriggerActionBinding>` | 空    | 将动作名称映射到触发器名称。每个条目都有两个字符串字段（见下文）。                       |

**AnimatorTriggerActionBinding 字段：**

| 字段            | 类型       | 说明                                                            |
| ------------- | -------- | ------------------------------------------------------------- |
| `动作名称`        | `string` | 要匹配的动作名称（不区分大小写）。必须与 `ConvaiActionConfigSource`的动作定义中的某个条目匹配。 |
| `TriggerName` | `string` | 动作匹配时要触发的 Animator 触发器参数。必须与 Animator Controller 中的确切触发器名称一致。 |

**示例绑定列表：**

| 动作名称 | TriggerName     |
| ---- | --------------- |
| `挥手` | `TriggerWave`   |
| `敬礼` | `TriggerSalute` |
| `指向` | `TriggerPoint`  |

如果没有任何绑定与传入的动作名称匹配，executor 会返回 `失败` 并带有消息 `没有匹配 '<action name>' 的绑定`.

#### PickUpActionExecutor

复合 executor，串联三种行为：导航到目标 → 触发动画触发器 → 等待动画 → 将对象附加到手部 Transform。该步骤会一直保持激活，直到三阶段全部完成。

| 属性       | 值                                              |
| -------- | ---------------------------------------------- |
| **菜单路径** | `添加组件 → Convai → 示例 → Pick Up Action Executor` |
| **命名空间** | `Convai.Sample.Behaviors`                      |
| **需要目标** | 是——返回 `失败` 如果未解析到目标                            |

**Inspector 字段：**

| 字段                   | 类型                            | 默认值        | 说明                                                   |
| -------------------- | ----------------------------- | ---------- | ---------------------------------------------------- |
| `_mover`             | `NavMeshMoveToActionExecutor` | 所需         | 驱动到目标的导航。必须赋值——若为 null，则返回 `失败` 如果为 null。            |
| `_animator`          | `Animator`                    | `null`     | 要驱动的 Animator。可选——如果为 null 则跳过。                      |
| `_pickUpTrigger`     | `string`                      | `"PickUp"` | 到达目标后要触发的 Animator 触发器参数。                            |
| `_attachPoint`       | `Transform`                   | `null`     | 被拾取对象要重新父级到的 Transform（例如手部骨骼）。可选——如果为 null，则不会重新父级。 |
| `_animationDuration` | `float`                       | `1.0`      | 触发动画后，等待多少秒再将对象重新父级。                                 |

**执行顺序：**

1. `NavMeshMoveToActionExecutor.ExecuteAsync` 导航到目标。如果失败或被取消， `PickUpActionExecutor` 会立即返回该结果。
2. `_animator.SetTrigger(_pickUpTrigger)` 被调用。
3. 等待 `_animationDuration` 秒（可取消）。
4. 目标 `GameObject` 会重新父级到 `_attachPoint` 并将本地位置/旋转设为零。
5. 返回 `成功`.

{% hint style="info" %}
`PickUpActionExecutor` 通过 `NavMeshMoveToActionExecutor` 直接调用 `ExecuteAsync`。这两个组件必须位于同一个 `GameObject` ，且场景中必须存在已烘焙的 NavMesh。
{% endhint %}

### 选择合适的 executor

| 使用场景                | 推荐的 executor                                                                                                                  |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| NPC 平滑地面向目标         | `LookAtTargetActionExecutor`                                                                                                  |
| 任何无需目标、绑定到游戏玩法回调的动作 | `UnityEventActionExecutor`                                                                                                    |
| 无需 NavMesh 的快速原型开发  | `TransformMoveToActionExecutor`                                                                                               |
| 带路径寻路的生产级 NPC 移动    | `NavMeshMoveToActionExecutor`                                                                                                 |
| 针对不同动作播放不同动画        | `AnimatorTriggerActionExecutor`                                                                                               |
| 一个命令完成导航 + 拾取 + 附加  | `PickUpActionExecutor`                                                                                                        |
| 自定义移动栈、物品栏、UI、物理    | [编写自定义动作 executor](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/writing-custom-executors.md) |

### 使用示例

#### 示例 1——带手势和移动的安全讲师

**场景：** 一个工作场所安全培训模拟。讲师 NPC 使用两个始终可用的 executor 来指向危险源并演示设备位置。

**NPC 上的 Inspector 设置：**

* `LookAtTargetActionExecutor` — `_duration = 0.8`
* `UnityEventActionExecutor` — `_onExecute` → 调用 `HazardHighlightManager.HighlightActive()`

**ConvaiActionConfigSource 定义：**

| 动作名称   | 目标要求 | 执行器                          |
| ------ | ---- | ---------------------------- |
| `指向`   | `任一` | `LookAtTargetActionExecutor` |
| `标记危险` | `无`  | `UnityEventActionExecutor`   |

**预期结果：** “指向燃气阀”→ NPC 会在 0.8 秒内转身面向燃气阀。“标记危险”→ `UnityEvent` 会触发并在 UI 中高亮当前危险。

#### 示例 2——带动画的设备取回

**场景：** 一个医疗培训场景。讲师取回一个除颤器并将其递交出去。

**Inspector 设置：**

* `NavMeshMoveToActionExecutor` — `_stoppingDistance = 0.6`
* `PickUpActionExecutor` — `_mover = NavMeshMoveToActionExecutor`, `_pickUpTrigger = "GrabItem"`, `_attachPoint = RightHandBone`, `_animationDuration = 1.2`

**ConvaiActionConfigSource 定义：**

| 动作名称 | 目标要求 | 执行器                    |
| ---- | ---- | ---------------------- |
| `取回` | `对象` | `PickUpActionExecutor` |

**预期结果：** “取回除颤器”→ NPC 导航到除颤器，播放 1.2 秒的抓取动画，然后除颤器附加到右手骨骼上。

### 下一步

{% content-ref url="/pages/6e3c85bad169c9c2c755b38be39008ef3ce023cf" %}
[分发器和批处理策略](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/dispatcher-and-batch-policies.md)
{% endcontent-ref %}

{% content-ref url="/pages/c5598abd0ddd72fa75a0989ad602a5b4d12e16d7" %}
[编写自定义动作执行器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/writing-custom-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/action-executors.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.