> 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).

# 动作执行器

按包分组的全部 21 个内置动作执行器组件参考，包括每个 Inspector 字段、默认值和所需的配套组件。

执行器是在调度器运行某个动作步骤时执行场景内行为的组件——例如行走、指点、改变情绪或播放声音的 NPC。Convai SDK 附带 21 个执行器组件，分为六个套件。每个组件都带有 `ConvaiActionArchetype` 属性，因此从 Actions Editor 的 **+ Add Action ▾** 目录中添加组件时，会自动填入动作名称、描述、目标要求和所有参数——无需手动编写即可获得可用的动作。

这 21 个组件都继承自 `ConvaiActionExecutorBase` (`Convai.Runtime.Actions`），大多数继承自 `ConvaiTargetedActionExecutor` 或泛型类 `ConvaiCharacterActionExecutor<TPeer>`。基于 `ConvaiCharacterActionExecutor<TPeer>` 构建的执行器除了下文列出的字段外，还会在 Inspector 中额外显示一个字段—— **Character Component**，用于引用其依赖的同伴组件（例如 `ConvaiGazeController`）。留空时，执行器会自动查找同伴组件：先搜索此 `GameObject`的父对象，再搜索子对象；只有当角色包含多个该类型的同伴组件时，才需要明确指定。

### 流程与实用工具套件（`Convai.Runtime`)

此套件无需依赖任何模块，位于 `SDK/Runtime/Actions/Executors/` ——其中的所有行为都可用于任何项目中的任何角色，无需 Convai 模块。

#### 触发 Unity 事件

执行你绑定到该事件的内容，然后始终返回成功。对于场景中已有按钮即可触发的功能，这是无需编写代码的便捷方案——例如打开门、启动时间轴或奖励积分。

| 属性         | 值                                                      |
| ---------- | ------------------------------------------------------ |
| **类**      | `ConvaiUnityEventActionExecutor`                       |
| **菜单路径**   | `Add Component → Convai → Actions → Raise Unity Event` |
| **原型动作名称** | `Raise Unity Event`                                    |
| **目标要求**   | 无                                                      |
| **必需的同伴**  | 无                                                      |

**检查器字段：**

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

此执行器永远不会失败——即使事件没有绑定任何内容，也仍会报告成功；在编写动作时，Actions Editor 会提示事件尚未绑定。若动作需要读取参数、耗费时间、支持取消或说明无法运行的原因，请编写自定义执行器。

#### 等待

暂停几秒钟，不做其他操作。单独使用的场景不多；在 **按顺序运行** 中，它可以为表演安排节奏——先指向门，稍等片刻，再走过去。

| 属性         | 值                                         |
| ---------- | ----------------------------------------- |
| **类**      | `ConvaiWaitActionExecutor`                |
| **菜单路径**   | `Add Component → Convai → Actions → Wait` |
| **原型动作名称** | `Wait`                                    |
| **目标要求**   | 无                                         |
| **必需的同伴**  | 无                                         |

**检查器字段：**

| 字段            | 类型      | 默认值  | 说明                                                 |
| ------------- | ------- | ---- | -------------------------------------------------- |
| `_seconds`    | `float` | `1`  | 等待时长。角色可通过 `seconds` 参数请求不同的等待时长。                  |
| `_maxSeconds` | `float` | `30` | 允许的最长等待时间。会限制 Inspector 中的值以及角色请求的任何时长，避免错误数值卡住场景。 |

等待按帧进行，并且可以取消——它从不使用 `Task.Delay` ——因此会以正常的游戏速度运行，遵循暂停和时间缩放设置，并在操作取消时正确清理。

#### 按顺序运行

将多个 Action Behavior 作为单个操作依次运行——“向访客问好”可以包含注视、点头和打招呼，无需编写代码即可配置。每个步骤都会收到相同的目标和参数。

| 属性         | 值                                                 |
| ---------- | ------------------------------------------------- |
| **类**      | `ConvaiSequenceActionExecutor`                    |
| **菜单路径**   | `Add Component → Convai → Actions → Run In Order` |
| **原型动作名称** | `Run In Order`                                    |
| **目标要求**   | 无（传递给每个步骤）                                        |
| **必需的同伴**  | 无                                                 |

**检查器字段：**

| 字段       | 类型                    | 默认值 | 说明                                                                 |
| -------- | --------------------- | --- | ------------------------------------------------------------------ |
| `_steps` | `List<MonoBehaviour>` | 空   | 要运行的 Action Behavior，按从上到下的顺序排列。每个条目都必须实现 `IConvaiActionExecutor`. |

在第一个未成功的步骤处停止，并报告该步骤自身的结果，同时附上其位置——失败信息会指出失败的是哪一步以及原因。条目为空、不是 Action Behavior，或引用了此同一组件时，会立即失败并返回 `ConvaiActionFailureReason.InvalidState`.

#### 显示或隐藏对象

开启或关闭目标对象——无需在对象本身添加额外组件，即可让“把地图给他们看”转化为最直接的可见效果。

| 属性         | 值                                                        |
| ---------- | -------------------------------------------------------- |
| **类**      | `ConvaiSetActiveActionExecutor`                          |
| **菜单路径**   | `Add Component → Convai → Actions → Show Or Hide Object` |
| **原型动作名称** | `Show Or Hide Object`                                    |
| **目标要求**   | 对象                                                       |
| **必需的同伴**  | 无                                                        |

**检查器字段：**

| 字段      | 类型                                              | 默认值    | 说明                                |
| ------- | ----------------------------------------------- | ------ | --------------------------------- |
| `_mode` | `ConvaiShowHideMode` (`Show`, `Hide`, `Toggle`) | `Show` | 对对象执行的操作。角色可以通过 `mode` 参数请求不同的模式。 |

如果请求的状态与对象当前状态相同，操作仍会成功并给出提示（“已经显示。”），而不会失败——请求已得到满足，就不算失败。未能解析目标时返回 `Unhandled`.

#### 播放 Animator 状态

**适用于使用自身 Animator Controller 动画的角色，而非 Body Animation 模块。** 设置与操作名称对应的 Trigger 参数，并可选择等待动画状态播放完毕。

| 属性         | 值                                                                                  |
| ---------- | ---------------------------------------------------------------------------------- |
| **类**      | `ConvaiAnimatorStateActionExecutor`                                                |
| **菜单路径**   | `Add Component → Convai → Actions → Play Animator State (own Animator Controller)` |
| **原型动作名称** | `Play Animator State`                                                              |
| **目标要求**   | 无                                                                                  |
| **必需的同伴**  | `Animator`                                                                         |

**检查器字段：**

| 字段          | 类型                                  | 默认值 | 说明                                 |
| ----------- | ----------------------------------- | --- | ---------------------------------- |
| `_bindings` | `List<ConvaiAnimatorActionBinding>` | 空   | 每个操作占一行，用于定义此角色可通过 Animator 执行的操作。 |

**绑定行字段。** 每行都在 Inspector 中配置；行类型属于 SDK 内部类型，因此脚本无法创建此类型的实例。

| 字段                   | 类型       | 默认值    | 说明                                                            |
| -------------------- | -------- | ------ | ------------------------------------------------------------- |
| `ActionName`         | `string` | —      | 要响应的操作名称，匹配时不区分大小写。                                           |
| `TriggerName`        | `string` | —      | 运行该操作时要设置的 Animator Trigger 参数。                               |
| `WaitForStateTag`    | `string` | 空      | 可选。为 Animator 状态添加相同的标签，以便在操作结束前等待该状态完成。留空则在设置 Trigger 后立即结束。 |
| `NormalizedExitTime` | `float`  | `0.95` | 标记状态推进到什么程度才算完成（`0`–`1`）。仅在 `WaitForStateTag` 已设置时使用。         |

没有匹配行的动作名称会被拒绝，并标记为 `Unhandled` 而不是失败，因此角色上的其他 Action Behavior 仍有机会响应。如果角色上有 `ConvaiBodyAnimationController`，拒绝消息会改为提及 **播放手势** ——这两种行为会驱动同一个 Animator，同时使用会相互冲突。

#### 播放声音

通过普通的 `AudioSource`播放声音。无论是否指定目标对象均可使用——在创建动作时选择：不指定目标对象并指定 `AudioSource` 时直接播放声音；指定目标对象但未指定 `AudioSource` 时，则从角色被要求操作的对象播放声音。

| 属性         | 值                                               |
| ---------- | ----------------------------------------------- |
| **类**      | `ConvaiPlaySoundActionExecutor`                 |
| **菜单路径**   | `Add Component → Convai → Actions → Play Sound` |
| **原型动作名称** | `Play Sound`                                    |
| **目标要求**   | 二选一                                             |
| **必需的同伴**  | 无                                               |

**检查器字段：**

| 字段                      | 类型            | 默认值     | 说明                                       |
| ----------------------- | ------------- | ------- | ---------------------------------------- |
| `_audioSource`          | `AudioSource` | `null`  | 用于播放声音的音频源。留空则使用目标对象上的音频源。               |
| `_clip`                 | `AudioClip`   | `null`  | 要播放的声音。留空则播放 `AudioSource` 上已有的音频片段。     |
| `_volume`               | `float`       | `1`     | 播放音量， `0`–`1`。角色可以通过 `volume` 参数请求不同的音量。 |
| `_waitForSoundToFinish` | `bool`        | `false` | 保持动作运行，直到音频片段播放完毕。                       |

绝不会通过角色自己的语音 `AudioSource` 播放声音——借用它会导致角色说话说到一半就被打断。如果既未指定音频源，目标对象上也没有音频源，则动作会拒绝执行，并提示需要指定什么。未解析到音频片段时，结果为 `Failed`.

### 注意力模块（`Convai.Modules.Gaze`)

`SDK/Modules/Gaze/Executors/` ——此处的每种行为都需要一个 `ConvaiGazeController` 同级组件。

#### 注视目标

将角色的注意力转向目标——先转动眼睛，再转动头部；如果目标位于头部无法触及的位置，则转动身体。一旦视线明显到达目标就结束，而不是等保持时间结束，因此后续步骤不会因等待而排队。

| 属性         | 值                                                   |
| ---------- | --------------------------------------------------- |
| **类**      | `ConvaiLookAtActionExecutor`                        |
| **菜单路径**   | `Add Component → Convai → Actions → Look At Target` |
| **原型动作名称** | `Look At`                                           |
| **目标要求**   | 二选一                                                 |
| **必需的同伴**  | `ConvaiGazeController`                              |
| **超时**     | 10s（原型默认值）                                          |

**检查器字段：**

| 字段             | 类型                                           | 默认值         | 说明                                                                             |
| -------------- | -------------------------------------------- | ----------- | ------------------------------------------------------------------------------ |
| `_mode`        | `ConvaiGazeLookMode` (`Glance`, `Sustained`) | `Sustained` | Glance 表示快速看一眼后移开视线；Sustained 表示持续注视，角色会保持注视，必要时转动身体。角色可以通过 `mode` 参数请求其中一种模式。 |
| `_holdSeconds` | `float`                                      | `2.5`       | 视线到达目标后，继续注视的时长。 `0` 会持续注视，直到其他事物吸引了角色的注意力。                                    |
| `_engagement`  | `float`                                      | `1`         | 注视的专注程度， `0`–`1`.                                                              |

如果角色为了继续与交谈对象保持眼神交流而拒绝了这次快速注视，请求会报告 `Unhandled` （眼神交流锁定按预期工作），而非失败。

#### 注视玩家

持续与玩家保持眼神交流，直到收到停止指令——这是一个有作用范围且可取消的请求，与角色自身的对话眼神交流设置相互独立；此操作不会更改该设置。

| 属性         | 值                                                     |
| ---------- | ----------------------------------------------------- |
| **类**      | `ConvaiWatchPlayerActionExecutor`                     |
| **菜单路径**   | `Add Component → Convai → Actions → Watch The Player` |
| **原型动作名称** | `Watch The Player`                                    |
| **目标要求**   | 无（默认指向玩家）                                             |
| **必需的同伴**  | `ConvaiGazeController`                                |

**检查器字段：**

| 字段            | 类型                                                | 默认值     | 说明                                                   |
| ------------- | ------------------------------------------------- | ------- | ---------------------------------------------------- |
| `_mode`       | `ConvaiWatchPlayerMode` (`Watch`, `StopWatching`) | `Watch` | 确定此调用是开始注视还是停止注视。角色可以通过 `mode` 参数（`watch` 或 `stop`). |
| `_engagement` | `float`                                           | `1`     | 注视的专注程度， `0`–`1`.                                    |

如果场景中找不到玩家，则操作会失败，并返回 `ConvaiActionFailureReason.TargetMissing`。如果组件在注视期间被禁用，注视会自动结束。

#### 扫描环境

检查周围环境中的多个不同位置：优先选择搜索半径内的场景对象；如果没有，则改为检查均匀分布的世界坐标点。

| 属性         | 值                                                     |
| ---------- | ----------------------------------------------------- |
| **类**      | `ConvaiScanEnvironmentActionExecutor`                 |
| **菜单路径**   | `Add Component → Convai → Actions → Scan Environment` |
| **原型动作名称** | `Scan Environment`                                    |
| **目标要求**   | 无                                                     |
| **必需的同伴**  | `ConvaiGazeController`                                |
| **超时**     | 15s（原型默认值）                                            |

**检查器字段：**

| 字段                  | 类型          | 默认值     | 说明                              |
| ------------------- | ----------- | ------- | ------------------------------- |
| `_durationSeconds`  | `float`     | `3.5`   | 扫描总时长。角色可以通过 `duration` 参数覆盖此值。 |
| `_stopCount`        | `int`       | `4`     | 视线停留的不同位置数量， `2`–`8`.           |
| `_arcDegrees`       | `float`     | `150`   | 以角色朝向为中心覆盖的水平视野范围， `20`–`320`.  |
| `_allowBodyTurn`    | `bool`      | `false` | 宽范围扫描点是否可以带动身体转动（而不只是头部和眼睛）。    |
| `_searchRadius`     | `float`     | `7`     | 用于查找值得检查的场景碰撞体的半径。 `0` 仅使用生成的点。 |
| `_targetLayers`     | `LayerMask` | 所有      | 包含可选为扫描点的对象的层。                  |
| `_fallbackDistance` | `float`     | `4`     | 当没有场景对象适合该扫描范围时，生成的扫描点与角色之间的距离。 |
| `_fallbackHeight`   | `float`     | `1.5`   | 生成的扫描点高于角色原点的高度。                |

仅在播放模式下运行——它会驱动实时视线绑定，因此在编辑模式下会以 `Unhandled` 拒绝执行。操作完成、取消、禁用或销毁时，会释放保持的视线。

### 表情包（`Convai.Modules.Emotion`, `Convai.Modules.BodyLanguage`)

Set Mood 和 React 位于 `SDK/Modules/Emotion/Executors/` ，并需要一个 `ConvaiEmotionController` 同级组件。Nod Or Shake Head 位于 `SDK/Modules/BodyLanguage/Executors/` ，并需要一个 `ConvaiBodyLanguageController` 同级组件。

#### 设置心情

持续生效的心情：让角色逐渐切换到新心情，并保持该心情，直到其他操作改变它。适用于会影响后续对话氛围的心情变化。

| 属性         | 值                                    |
| ---------- | ------------------------------------ |
| **类**      | `ConvaiSetMoodActionExecutor`        |
| **菜单路径**   | `添加组件 → Convai → Actions → Set Mood` |
| **原型动作名称** | `设置心情`                               |
| **目标要求**   | 无                                    |
| **必需的同伴**  | `ConvaiEmotionController`            |

**检查器字段：**

| 字段                   | 类型              | 默认值   | 说明                                        |
| -------------------- | --------------- | ----- | ----------------------------------------- |
| `_defaultMood`       | `string` （情绪标签） | 空     | 角色未指定心情时使用的心情。通常由 `mood` 参数指定。            |
| `_defaultIntensity`  | `float`         | `0.6` | 强度， `0`–`1`。角色可以通过 `intensity` 参数请求不同的强度。 |
| `_transitionSeconds` | `float`         | `1.5` | 变化所需的时间。                                  |

如果角色没有指定的情绪，操作会失败并列出角色已有的情绪——否则，情绪系统会将未知情绪视为中性，导致操作看似成功，实际上却什么都没做。若要触发短暂反应，请使用 **React** ；短暂情绪若使用 Set Mood，角色会一直停留在该情绪中。

#### React

用于短暂反应：呈现一个瞬间，保持片刻，然后恢复到角色之前的感受——例如一阵惊跳、瞬间的欣喜或一声痛苦的抽气。即使操作在这一瞬间中途取消，也会确保恢复原状。

| 属性         | 值                                          |
| ---------- | ------------------------------------------ |
| **类**      | `ConvaiReactActionExecutor`                |
| **菜单路径**   | `Add Component → Convai → Actions → React` |
| **原型动作名称** | `React`                                    |
| **目标要求**   | 无                                          |
| **必需的同伴**  | `ConvaiEmotionController`                  |

**检查器字段：**

| 字段                  | 类型              | 默认值    | 说明                                     |
| ------------------- | --------------- | ------ | -------------------------------------- |
| `_defaultReaction`  | `string` （情绪标签） | 空      | 角色未指定反应时使用的默认反应。通常由 `reaction` 参数指定反应。 |
| `_defaultIntensity` | `float`         | `0.85` | 强度， `0`–`1`.                           |
| `_holdSeconds`      | `float`         | `1.5`  | 反应保持多久后恢复原状。                           |

如果角色没有指定的反应，操作会失败并列出角色已有的反应——原因与 Set Mood 相同。

#### 点头或摇头

用头部动作作答：点头表示是，摇头表示否，歪头表示“让我想想”。该动作会叠加在身体当前的动作上，因此看起来不会像木偶般突然抽动。

| 属性         | 值                                                      |
| ---------- | ------------------------------------------------------ |
| **类**      | `ConvaiHeadResponseActionExecutor`                     |
| **菜单路径**   | `Add Component → Convai → Actions → Nod Or Shake Head` |
| **原型动作名称** | `Nod Or Shake Head`                                    |
| **目标要求**   | 无                                                      |
| **必需的同伴**  | `ConvaiBodyLanguageController`                         |

**检查器字段：**

| 字段           | 类型                                         | 默认值   | 说明                                                                   |
| ------------ | ------------------------------------------ | ----- | -------------------------------------------------------------------- |
| `_response`  | `HeadGestureKind` (`Nod`, `Shake`, `Tilt`) | `Nod` | 角色未指定回应时使用的默认回应。角色可以通过 `yes`, `no`或 `maybe` 以及 `response` 参数来请求相应动作。 |
| `_intensity` | `float`                                    | `1`   | 动作幅度， `0`–`1`.                                                       |

操作会一直保持打开状态，直到动作完成，因此序列可以先点头再说话。如果头部仍在完成上一个动作，执行器会重试，最长等待 1.5 秒；之后若仍未完成，则会因 `ConvaiActionFailureReason.Busy`.

### 动作包（`Convai.Modules.BodyAnimation`)

`SDK/Modules/BodyAnimation/Executors/` — 由内容驱动：这两种行为都会播放角色 Animation Set 中制作的动画片段，因此没有这些内容的角色无法执行。

#### 播放动作

按名称播放角色的某个手势——挥手、耸肩、鞠躬等——在当前姿势上平滑过渡，并在结束时平滑过渡回去。

| 属性         | 值                                                 |
| ---------- | ------------------------------------------------- |
| **类**      | `ConvaiPlayGestureActionExecutor`                 |
| **菜单路径**   | `Add Component → Convai → Actions → Play Gesture` |
| **原型动作名称** | `Play Gesture`                                    |
| **目标要求**   | 无                                                 |
| **必需的同伴**  | `ConvaiBodyAnimationController`                   |
| **超时**     | 15s（原型默认值）                                        |

**检查器字段：**

| 字段                | 类型       | 默认值 | 说明                                                        |
| ----------------- | -------- | --- | --------------------------------------------------------- |
| `_defaultGesture` | `string` | 空   | 角色未指定手势时要播放的手势。与 Animation Set 中的手势名称和别名进行匹配。             |
| `_holdSeconds`    | `float`  | `8` | 设置手势的持续时间上限，用于原本会无限持续的手势（如跳舞、思考姿势）。 `0` 会一直保持，直到其他操作将其停止。 |

未知手势名称会以 `Unhandled`的状态拒绝处理；Animation Set 中实际的手势名称只会在 Detail 跟踪详细级别下记录一次。使用普通 Animator Controller 而非 Body Animation 模块的角色应改用 **Play Animator State** 。

#### 指向目标

指向动作名称所指定的目标，并根据目标的实际位置选择手臂；身体其他部分则继续执行当前动作。

| 属性         | 值                                                    |
| ---------- | ---------------------------------------------------- |
| **类**      | `ConvaiPointAtActionExecutor`                        |
| **菜单路径**   | `Add Component → Convai → Actions → Point At Target` |
| **原型动作名称** | `Point At`                                           |
| **目标要求**   | 二选一                                                  |
| **必需的同伴**  | `ConvaiBodyAnimationController`                      |
| **超时**     | 15s（原型默认值）                                           |

**检查器字段：**

| 字段              | 类型                                           | 默认值        | 说明                                                                           |
| --------------- | -------------------------------------------- | ---------- | ---------------------------------------------------------------------------- |
| `_holdSeconds`  | `float`                                      | `3`        | 保持指向的时长 **（手臂完全伸展时）** ——仅指手势中间的停顿。                                           |
| `_gestureSpeed` | `float`                                      | `1`        | 手臂抬起和放下的速度，相对于动画自身速度的倍数， `0.25`–`3`。不会影响 `_holdSeconds`.                     |
| `_release`      | `PointingReleaseStyle` (`PlayTail`, `Blend`) | `PlayTail` | 指向保持结束时的处理方式。 `PlayTail` 会在动画片段剩余部分中放下手臂； `Blend` 则会直接淡出该姿势，使手势大致在保持时间结束时结束。 |

{% hint style="warning" %}
**`_holdSeconds` 仅表示手臂完全伸展时的停顿时间，而不是整个手势的时长。** 手臂的抬起和放下按动画片段自身的时间安排进行；使用随附的指向动画片段时，抬起和放下各约需 2.5 秒，因此即使 `_holdSeconds` 设为 `1` ，整个手势仍约持续 6 秒。 `_gestureSpeed` 和 `_release` 可直接控制抬起和放下。将 `_release` 设为 `Blend` 即可获得尽可能短的指向动作。
{% endhint %}

Animation Set 中没有指向动画片段时，会以 `Unhandled`。未解析到目标时也会以相同方式失败——指向操作始终需要目标。

### 移动模块包（`Convai.Modules.BodyAnimation`)

`SDK/Modules/BodyAnimation/Executors/` ——此处的每种行为都需要一个 `ConvaiNavMeshLocomotion` 组件，除了 **转向面向目标**，它不需要 NavMesh。

#### 走向目标

走向目标，绕开障碍物，并在距离目标一段舒适距离时停下，而不是直接走到物体上。

| 属性         | 值                                                   |
| ---------- | --------------------------------------------------- |
| **类**      | `ConvaiWalkToActionExecutor`                        |
| **菜单路径**   | `Add Component → Convai → Actions → Walk To Target` |
| **原型动作名称** | `Walk To`                                           |
| **目标要求**   | 二选一                                                 |
| **必需的同伴**  | `ConvaiNavMeshLocomotion`                           |
| **超时**     | 45 秒（原型默认值）                                         |

**检查器字段：**

| 字段                | 类型      | 默认值 | 说明                                             |
| ----------------- | ------- | --- | ---------------------------------------------- |
| `_arriveDistance` | `float` | `1` | 距离目标多远时停止，单位为米。角色可以通过 `arriveDistance` 参数覆盖此值。 |

未烘焙 NavMesh，或目标位于网格之外时，操作会失败并返回 `ConvaiActionFailureReason.PathBlocked` ，同时指出目的地。需要烘焙好的 NavMesh。

#### 引导玩家前往目标

引导玩家前往目的地：角色走在前面，玩家落后时暂停，玩家赶上后继续前进。

| 属性         | 值                                                          |
| ---------- | ---------------------------------------------------------- |
| **类**      | `ConvaiLeadPlayerActionExecutor`                           |
| **菜单路径**   | `Add Component → Convai → Actions → Lead Player To Target` |
| **原型动作名称** | `Lead Player`                                              |
| **目标要求**   | 二选一                                                        |
| **必需的同伴**  | `ConvaiNavMeshLocomotion`                                  |
| **超时**     | 120 秒（原型默认值）                                               |

**检查器字段：**

| 字段                      | 类型      | 默认值   | 说明                            |
| ----------------------- | ------- | ----- | ----------------------------- |
| `_arriveDistance`       | `float` | `1.4` | 角色距离目的地多远时停止。                 |
| `_waitWhenFartherThan`  | `float` | `4.5` | 玩家距离超过此值时，暂停行进。               |
| `_resumeWhenCloserThan` | `float` | `2.8` | 玩家回到此距离范围内后，继续行进。             |
| `_maximumWaitSeconds`   | `float` | `12`  | 等待的最长时间；超过后即使玩家未跟上，也会继续前往目的地。 |

场景中没有玩家时，操作会失败并返回 `ConvaiActionFailureReason.TargetMissing`。没有通往目的地的路径时，操作会失败并返回 `PathBlocked`.

#### 转向面向目标

原地转身面向目标，而不会朝目标走去——“看着顾客”通常指的就是这个，而不是穿过整个房间。无需 NavMesh。

| 属性         | 值                                                        |
| ---------- | -------------------------------------------------------- |
| **类**      | `ConvaiTurnToFaceActionExecutor`                         |
| **菜单路径**   | `Add Component → Convai → Actions → Turn To Face Target` |
| **原型动作名称** | `Turn To Face`                                           |
| **目标要求**   | 二选一                                                      |
| **必需的同伴**  | `ConvaiBodyAnimationController`                          |
| **超时**     | 10s（原型默认值）                                               |

**检查器字段：**

| 字段                   | 类型                                                   | 默认值            | 说明                                                                                      |
| -------------------- | ---------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------- |
| `_turnStyle`         | `ConvaiTurnStyle` (`SteppingTurn`, `SmoothRotation`) | `SteppingTurn` | `SteppingTurn` 播放角色自身的转身动画； `SmoothRotation` 直接旋转，持续时间由 `_smoothTurnSeconds` 决定，无需动画片段。 |
| `_smoothTurnSeconds` | `float`                                              | `0.5`          | SmoothRotation `转身的持续时间。` 在 `SteppingTurn`.                                             |
| `_toleranceDegrees`  | `float`                                              | `8`            | 朝向目标的角度偏差小于多少时视为完成， `0`–`45`.                                                           |

`SteppingTurn` 如果动画集中没有转身动画片段，则会降级为 `Unhandled`，并将 `SmoothRotation` 指定为替代方案。

#### 跟随玩家

“跟我来。”与玩家保持舒适的距离；玩家走开时缩短距离，玩家停下时也跟着停下。

| 属性         | 值                                                      |
| ---------- | ------------------------------------------------------ |
| **类**      | `ConvaiFollowPlayerActionExecutor`                     |
| **菜单路径**   | `Add Component → Convai → Actions → Follow The Player` |
| **原型动作名称** | `Follow The Player`                                    |
| **目标要求**   | 无（默认指向玩家）                                              |
| **必需的同伴**  | `ConvaiNavMeshLocomotion`                              |

**检查器字段：**

| 字段                | 类型                                    | 默认值      | 说明                                                |
| ----------------- | ------------------------------------- | -------- | ------------------------------------------------- |
| `_mode`           | `ConvaiFollowMode` (`Follow`, `Stop`) | `Follow` | 此调用用于开始或停止跟随。角色可以通过 `mode` 参数（`follow` 或 `stop`). |
| `_followDistance` | `float`                               | `2.2`    | 角色尝试与玩家保持的距离。                                     |
| `_slack`          | `float`                               | `0.8`    | 玩家必须移动到超出 `_followDistance` 多远后，角色才会缩短距离。         |

{% hint style="info" %}
**跟随没有自然结束条件。** 角色一开始跟随，动作就会立即报告成功；跟随本身会在此后继续——否则动作会一直处于未完成状态，直到超时，并阻塞后续所有动作。再次发送动作并设置 `mode: stop`，或禁用角色，即可结束跟随。跟随中的角色仍会响应其他移动动作（走向目标、返回起点）：对于任何非自身发起的移动，跟随都会暂时停止，并在移动结束后恢复到玩家身边。
{% endhint %}

找不到玩家时，动作会以 `ConvaiActionFailureReason.TargetMissing`.

#### 返回起点

走回角色起始的位置，也可以走到你指定的位置；还可选择恢复原始朝向。这是本套功能中其他动作的撤销操作。

| 属性         | 值                                   |
| ---------- | ----------------------------------- |
| **类**      | `ConvaiReturnToStartActionExecutor` |
| **菜单路径**   | `添加组件 → Convai → 操作 → 返回起点`         |
| **原型动作名称** | `返回起点`                              |
| **目标要求**   | 无                                   |
| **必需的同伴**  | `ConvaiNavMeshLocomotion`           |

**检查器字段：**

| 字段                 | 类型          | 默认值    | 说明                         |
| ------------------ | ----------- | ------ | -------------------------- |
| `_homeSpot`        | `Transform` | `null` | “返回”到哪里。留空则使用场景开始时角色所站的位置。 |
| `_restoreFacing`   | `bool`      | `true` | 到达后转回原来的朝向。                |
| `_turnBackSeconds` | `float`     | `0.6`  | 最终转向所需的时间。                 |
| `_arriveDistance`  | `float`     | `0.2`  | 距离多近才算到家。                  |

起点位置记录于 `Awake`中，在角色上的其他任何内容移动它之前。没有可返回的路径时，会以 `PathBlocked`.

### 观察行为包（`Convai.Runtime`)

`SDK/Runtime/Actions/Executors/` 存放观察行为执行器。这两种行为都会通过 `ConvaiActionExecutionResult.Answered` 返回答案，且默认配置为 `AnswerDelivery = TellThePlayer` 因此角色会说出结果，除非你更改该操作的 **完成时** 设置。

#### 统计目标组

统计 `ConvaiActionTargetGroup` 中启用的成员，并回答结果——“还剩多少个箱子”。

| 属性          | 值                                            |
| ----------- | -------------------------------------------- |
| **类**       | `ConvaiCountTargetGroupActionExecutor`       |
| **菜单路径**    | `添加组件 → Convai → 操作 → 统计目标组`                 |
| **原型动作名称**  | `统计目标组`                                      |
| **目标要求**    | 对象                                           |
| **必需的目标组件** | `ConvaiActionTargetGroup`，位于解析出的目标对象上（而非角色上） |

**检查器字段：**

| 字段                      | 类型       | 默认值    | 说明                                   |
| ----------------------- | -------- | ------ | ------------------------------------ |
| `_availableMembersOnly` | `bool`   | `true` | 统计时忽略已禁用的成员组件和未激活的成员对象。              |
| `_includeMemberNames`   | `bool`   | `true` | 在答案中同时包含成员名称和数量。                     |
| `_memberLabel`          | `string` | 空      | 可选的复数标签，例如 `"crates"`。留空则使用目标组自身的名称。 |

解析出的目标若没有 `ConvaiActionTargetGroup` 组件，或目标组为空，则会以 `Unhandled` 拒绝处理，而不是报告一个具有误导性的零。

#### 测量距离

测量角色到目标的地面平面距离；如果未指定目标，则测量到玩家的距离，并用通俗语言回答——“大约 3 米远”。

| 属性         | 值                                     |
| ---------- | ------------------------------------- |
| **类**      | `ConvaiMeasureDistanceActionExecutor` |
| **菜单路径**   | `添加组件 → Convai → Actions → 测量距离`      |
| **原型动作名称** | `测量距离`                                |
| **目标要求**   | 二选一                                   |
| **必需的同伴**  | 无                                     |

**检查器字段：**

| 字段                   | 类型      | 默认值    | 说明                                       |
| -------------------- | ------- | ------ | ---------------------------------------- |
| `_withinReachMetres` | `float` | `1.2`  | 距离不超过此值时，会描述为“触手可及”。                     |
| `_aFewStepsMetres`   | `float` | `3.5`  | 距离不超过此值时，会描述为“几步之遥”。                     |
| `_acrossAreaMetres`  | `float` | `9`    | 距离不超过此值时，会描述为“就在区域另一边”。超过此值时，会描述为“远在天边”。 |
| `_includeMetres`     | `bool`  | `true` | 在回答中包含以米为单位的测量值。                         |

场景中缺少目标和玩家时，会失败并返回 `ConvaiActionFailureReason.TargetMissing`.

### 选择合适的执行器

| 适用场景                             | 推荐的执行器                                                                                                                                         |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 以无代码方式接入现有游戏逻辑                   | 触发 Unity 事件                                                                                                                                    |
| 为一系列步骤控制节奏，或在步骤之间暂停              | 等待                                                                                                                                             |
| 将多个行为串联为一个动作                     | 按顺序运行                                                                                                                                          |
| 切换场景对象的可见性                       | 显示或隐藏对象                                                                                                                                        |
| 角色使用自己的 Animator Controller 播放动画 | 播放 Animator 状态                                                                                                                                 |
| 播放一次性音效，可指定目标，也可不指定              | 播放声音                                                                                                                                           |
| 让角色将视线转向目标                       | 注视目标                                                                                                                                           |
| 根据请求与玩家保持眼神接触                    | 注视玩家                                                                                                                                           |
| 明显地观察周围环境                        | 扫描环境                                                                                                                                           |
| 改变角色当前持续的情绪                      | 设置心情                                                                                                                                           |
| 一闪而过的情绪表现                        | React                                                                                                                                          |
| 用头部动作回答“是”“不是”或“让我想想”            | 点头或摇头                                                                                                                                          |
| 播放 Animation Set 中指定名称的手势        | 播放动作                                                                                                                                           |
| 指向指定名称的人、地点或物体                   | 指向目标                                                                                                                                           |
| 使用寻路功能前往目标                       | 走向目标                                                                                                                                           |
| 带玩家前往某处                          | 引导玩家前往目标                                                                                                                                       |
| 原地转身面向目标                         | 转向面向目标                                                                                                                                         |
| 陪伴玩家移动                           | 跟随玩家                                                                                                                                           |
| 撤销移动——走回起点                       | 返回起点                                                                                                                                           |
| 统计可用的已知对象数量                      | 统计目标组                                                                                                                                          |
| 回答“那个东西有多远”                      | 测量距离                                                                                                                                           |
| 没有现成执行器涵盖的游戏逻辑                   | [编写自定义动作执行器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/writing-custom-executors.md) |

### 后续步骤

{% content-ref url="/pages/6e3c85bad169c9c2c755b38be39008ef3ce023cf" %}
[分发器和批处理策略](https://docs.convai.com/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" %}
[编写自定义动作执行器](https://docs.convai.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
