> 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/unity-plugin-beta-overview/features/actions/action-executors.md).

# 动作执行器

## 什么是执行器？

执行器是一个 **MonoBehaviour 组件** 它会在接收到动作命令时执行游戏中的实际行为。当 `ConvaiActionDispatcher` 收到类似 `移动到` 将目标指向 `Crate`这样的命令时，它会调用你为该动作定义分配的执行器——然后由执行器来完成工作。

Convai SDK 自带六个可直接使用的执行器，覆盖常见场景：

| Executor             | 作用                       | 需要目标 |
| -------------------- | ------------------------ | :--: |
| `Unity Event 动作执行器`  | 触发一个 UnityEvent——可挂接任意回调 |   否  |
| `看向目标动作执行器`          | 平滑地让 NPC 旋转并面向目标         |   是  |
| `Animator 触发器动作执行器`  | 按动作名称设置 Animator 触发器     |   否  |
| `Transform 移动到动作执行器` | 将 NPC 传送到目标位置（仅限原型）      |   是  |
| `NavMesh 移动到动作执行器`   | 通过 NavMesh 引导 NPC 移动到目标  |   是  |
| `拾取动作执行器`            | 移动到目标、播放动画，并将目标对象重新设为子物体 |   是  |

{% hint style="info" %}
一个执行器组件可以被 **多个动作定义**引用。对于共享相同行为逻辑的动作，无需添加重复组件。
{% endhint %}

***

## Unity Event 动作执行器

**添加组件：** `Convai/Actions/Unity Event Action Executor`

最简单的执行器。被触发时，它会触发一个标准的 Unity `UnityEvent` 并立即返回 `Succeeded`.

### 检查器字段

| 字段             | 描述                                       |
| -------------- | ---------------------------------------- |
| **On Execute** | 在动作运行时触发的 UnityEvent。将其连接到场景中任意组件上的任意方法。 |

### 何时使用

对于任何不需要目标、并且可直接映射到简单回调的动作，都可以使用此执行器：

* 播放音效
* 触发 UI 通知或面板
* 设置任务标记或游戏状态变量
* 调用另一个组件上的自定义方法

### 示例

在消防安全培训模拟中，一个 `报告危险` 动作可以使用 `Unity Event 动作执行器` 来调用一个方法，将危险报告记录到培训系统，触发确认音效，并更新分数显示——ทั้งหมด都通过一个 UnityEvent 来连接。

{% hint style="info" %}
`Unity Event 动作执行器` 同步执行并立即返回。如果你需要异步行为（等待动画、协程或任务），请改为编写自定义执行器。
{% endhint %}

***

## 看向目标动作执行器

**添加组件：** `Convai/Actions/Look At Target Action Executor`

在可配置的持续时间内，平滑地将某个 Transform 旋转朝向目标对象或角色。

### 检查器字段

| 字段        | 类型        | 默认值   | 描述                                       |
| --------- | --------- | ----- | ---------------------------------------- |
| **旋转根节点** | Transform | 自身    | 要旋转的 Transform。如果留空，默认为执行器自身的 Transform。 |
| **持续时间**  | float（秒）  | `0.5` | 旋转所需的时间。数值越大，转身越慢、越自然。                   |

### 何时使用

* NPC 在描述或与某个物体互动时转向它
* 角色看向玩家提到的另一个 NPC
* 博物馆导览员、讲解员或演示者转身面向讨论对象

### 要求

需要一个已解析的目标——在 **目标要求** 到 `对象`, `角色`，或 `两者皆可` 中进行设置。如果没有解析到目标，动作将失败。

### 示例

一位博物馆导览员有一个 `看向` 动作。当玩家问“你后面那幅画是什么？”时，AI 会选择 `看向` ，将 `文艺复兴绘画` 对象作为目标。NPC 的头部会在 0.5 秒内平滑转向那幅画。

***

## Animator 触发器动作执行器

**添加组件：** `Convai/Samples/Animator Trigger Action Executor`

使用可配置的绑定列表，将后端动作名称映射到 Animator 触发器。

### 检查器字段

| 字段           | 类型       | 描述                                                  |
| ------------ | -------- | --------------------------------------------------- |
| **Animator** | Animator | 要设置触发器的 Animator 组件。将其从同一个或子 GameObject 上拖入。        |
| **绑定**       | 列表       | 每个绑定将一个 **动作名称** 映射到 Animator 中的一个 **触发器名称** 触发器参数。 |

其中的每一项 **绑定**:

| 子字段       | 描述                                     |
| --------- | -------------------------------------- |
| **动作名称**  | 此绑定处理的动作名称（例如， `Wave`)                 |
| **触发器名称** | 要设置的 Animator 触发器参数（例如， `WaveTrigger`) |

### 何时使用

* 将对话动作映射到动画状态
* 播放问候、告别或情绪动画
* 触发手势动画（点头、指向、挥手）

### 示例设置

| 动作名称       | 触发器名称          |
| ---------- | -------------- |
| `Wave`     | `WaveTrigger`  |
| `Sit Down` | `SitTrigger`   |
| `Nod`      | `NodTrigger`   |
| `Point`    | `PointTrigger` |

### 失败情况

执行器返回 `失败` 如果：

* 没有为传入的动作名称找到绑定
* 该 **Animator** 字段未分配

***

## Transform 移动到动作执行器

**添加组件：** `Convai/Samples/Transform Move To Action Executor`

以可选偏移量将一个 Transform 立即移动到已解析目标的位置。

### 检查器字段

| 字段         | 类型        | 描述                                       |
| ---------- | --------- | ---------------------------------------- |
| **移动根节点**  | Transform | 要移动的 Transform。如果为空，默认为执行器自身的 Transform。 |
| **Offset** | Vector3   | 相对于目标位置应用的位置偏移。                          |

### 何时使用

{% hint style="danger" %}
**仅用于原型和测试。** 此执行器会将角色瞬间传送到目标——没有移动动画、没有寻路，也没有物理过渡。它提供了一种在添加真正的移动系统之前快速验证动作连接是否正确的方法。

用于生产环境时，请将此执行器替换为 `NavMesh 移动到动作执行器` ，或替换为使用你游戏自身移动系统的自定义执行器（角色控制器、物理或自定义移动方式）。
{% endhint %}

* 验证动作名称、目标名称和执行器分配是否正确
* 在 NavMesh 烘焙之前进行早期原型制作
* 简单的非游戏应用场景，只要接受即时位置变化即可

***

## NavMesh 移动到动作执行器

**添加组件：** `Convai/Samples/NavMesh Move To Action Executor`

将 NavMeshAgent 移动到已解析目标的位置，并异步等待，直到代理到达。

### 检查器字段

| 字段        | 类型           | 默认值   | 描述                                       |
| --------- | ------------ | ----- | ---------------------------------------- |
| **Agent** | NavMeshAgent | —     | 要控制的 NavMeshAgent。将其从同一个 GameObject 上拖入。 |
| **停止距离**  | float（单位）    | `0.5` | 代理需要靠得多近，才算动作完成。                         |

### 何时使用

* 任何 NPC 需要走到物体或位置的场景
* 讲师演示设备使用方法的培训模拟
* 角色跟随玩家指示进行导航请求的游戏

### 要求

* NavMesh 必须在场景中 **烘焙** （Window → AI → Navigation → Bake）。
* 目标对象必须具有可在 NavMesh 上到达的位置。
* 该 **Agent** 字段必须已分配。

### 示例

在消防安全模拟中，一名讲师角色有一个 `前往` 动作。当受训者说“带我看看灭火器”时，AI 会选择 `前往` 与 `灭火器` 作为目标。NavMeshAgent 会在场景中导航，并在距离灭火器 0.5 个单位以内停下。

### 行为

1. 执行器会将代理的目的地设置为目标的世界坐标。
2. 然后它会异步循环，每帧检查剩余路径距离。
3. 当代理距离在 **停止距离**以内时，它返回 `Succeeded`.
4. 如果目标 GameObject 在导航过程中被销毁，它返回 `失败`.
5. 如果批次被取消（例如，带有 `ReplaceCurrent` 策略的新批次到达），它返回 `已取消`.

***

## 拾取动作执行器

**添加组件：** `Convai/Samples/Pick Up Action Executor`

一个复合执行器，按顺序串联三种行为：导航到目标、播放拾取动画，然后将目标重新设为某个附加点（角色的手或携带槽）的子物体。

### 检查器字段

| 字段           | 类型                          | 描述                                   |
| ------------ | --------------------------- | ------------------------------------ |
| **Mover**    | NavMeshMoveToActionExecutor | 用于导航的移动执行器。必须已分配。                    |
| **Animator** | Animator                    | 用于触发拾取动画的 Animator。                  |
| **拾取触发器**    | 字符串                         | 要设置的 Animator 触发器参数名称（默认： `PickUp`). |
| **附加点**      | Transform                   | 拾取的对象会重新设为其子物体的 Transform（例如角色的手骨骼）。 |
| **动画持续时间**   | float（秒）                    | 触发动画后，在将对象重新设为子物体之前等待多长时间（默认： `1`).  |

### 执行顺序

```mermaid
flowchart LR
    A[开始] --> B[通过 Mover\n导航到目标]
    B -->|到达| C[设置 Animator 触发器\n拾取触发器]
    C --> D[等待\n动画持续时间秒]
    D --> E[将目标对象重新设为\n附加点的子物体]
    E --> F([成功])
    B -->|失败| G([失败])
```

### 何时使用

* 拾取并携带物体的角色
* 讲师取回设备的培训模拟
* NPC 收集或处理道具的游戏场景

### 示例

在仓库安全模拟中，一名主管角色有一个 `拾取` 动作。当受训者说“你能拿一下安全帽吗？”时，主管会导航到安全帽架，播放拾取动画，然后安全帽会成为主管手部 Transform 的子物体——从视觉上被角色携带着。

### 要求

* NavMesh 必须已烘焙（由 `Mover`).
* **Mover**, **Animator**，以及 **附加点** 都必须分配。

***

## 结论

这六个执行器开箱即用，覆盖了广泛的常见 NPC 行为。对于此处未涵盖的行为——自定义移动系统、UI 交互、物理交互，或任何特定于你项目的内容——请参阅 [编写自定义执行器](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/actions/writing-custom-executors.md).


---

# 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/unity-plugin-beta-overview/features/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.