> 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 字段—— **角色组件**，一个对同级组件的引用（例如 `ConvaiGazeController`）它通过该组件来工作。留空则执行器会自动查找同级组件，先搜索该 `GameObject`的父级，然后再搜索其子级；仅当角色携带该同级类型的多个实例时才显式指定。

### 流程与工具包（`Convai.Runtime`)

无模块包，位于 `SDK/Runtime/Actions/Executors/` ——这里的每种行为都可用于任何项目中的任何角色，无需 Convai 模块。

#### Raise Unity Event

运行你接到其事件上的任何内容，然后总是成功。用于场景里已经能通过按钮完成的一切的无代码捷径——开门、启动时间轴、加一分。

| 属性                 | 值                                                      |
| ------------------ | ------------------------------------------------------ |
| **类**              | `ConvaiUnityEventActionExecutor`                       |
| **菜单路径**           | `Add Component → Convai → Actions → Raise Unity Event` |
| **Archetype 动作名称** | `Raise Unity Event`                                    |
| **目标要求**           | 无                                                      |
| **所需同级组件**         | 无                                                      |

**检视器字段：**

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

绝不会失败——即使没有连接任何内容的事件也会报告成功；Actions Editor 会在创作时将未连接的事件标记出来。若动作需要读取参数、耗时、可被取消，或需要报告为何无法运行，请编写自定义执行器。

#### 等待

暂停几秒钟，除此之外什么也不做。单独使用很少有用；在 **按顺序运行** 中，它赋予表演节奏——先指向门，停顿一下，然后走向它。

| 属性                 | 值                                         |
| ------------------ | ----------------------------------------- |
| **类**              | `ConvaiWaitActionExecutor`                |
| **菜单路径**           | `Add Component → Convai → Actions → Wait` |
| **Archetype 动作名称** | `等待`                                      |
| **目标要求**           | 无                                         |
| **所需同级组件**         | 无                                         |

**检视器字段：**

| 字段            | 类型      | 默认   | 说明                                                     |
| ------------- | ------- | ---- | ------------------------------------------------------ |
| `_seconds`    | `float` | `1`  | 等待多久。角色可以通过 `秒` 参数。                                    |
| `_maxSeconds` | `float` | `30` | 允许等待的最长时间。会同时钳制 Inspector 值和角色要求的任何值，因此一个错误的数字不会让场景停住。 |

等待是逐帧且可取消的——它从不使用 `Task.Delay` ——因此它以正常游戏节奏运行，遵守暂停和时间缩放，并在动作被取消时正确展开。

#### 按顺序运行

将多个动作行为作为一个单独动作依次运行——“欢迎访客”可以表示看向对方、点头并问好，完全无需代码即可编写。每一步都接收相同的目标和参数。

| 属性                 | 值                                                 |
| ------------------ | ------------------------------------------------- |
| **类**              | `ConvaiSequenceActionExecutor`                    |
| **菜单路径**           | `Add Component → Convai → Actions → Run In Order` |
| **Archetype 动作名称** | `按顺序运行`                                           |
| **目标要求**           | 无（传递给每一步）                                         |
| **所需同级组件**         | 无                                                 |

**检视器字段：**

| 字段       | 类型                    | 默认 | 说明                                               |
| -------- | --------------------- | -- | ------------------------------------------------ |
| `_steps` | `List<MonoBehaviour>` | 空  | 要运行的动作行为，自上而下。每个条目都必须实现 `IConvaiActionExecutor`. |

在第一个不成功的步骤处停止，并返回该步骤自身的结果，前面带上其位置——失败会说明是哪一步失败以及原因。空条目、不是动作行为的条目，或引用同一组件的条目会立即以 `ConvaiActionFailureReason.InvalidState`.

#### 显示或隐藏对象

将目标对象打开或关闭——从“把地图给他们看”到某个可见变化发生的最短路径，而且对象本身无需额外组件。

| 属性                 | 值                                                        |
| ------------------ | -------------------------------------------------------- |
| **类**              | `ConvaiSetActiveActionExecutor`                          |
| **菜单路径**           | `Add Component → Convai → Actions → Show Or Hide Object` |
| **Archetype 动作名称** | `显示或隐藏对象`                                                |
| **目标要求**           | 对象                                                       |
| **所需同级组件**         | 无                                                        |

**检视器字段：**

| 字段      | 类型                                      | 默认   | 说明                      |
| ------- | --------------------------------------- | ---- | ----------------------- |
| `_mode` | `ConvaiShowHideMode` (`显示`, `隐藏`, `开关`) | `显示` | 要对对象做什么。角色可以通过 `模式` 参数。 |

请求对象已经处于的状态会成功并明确说明（“已经显示。”），而不是失败——已满足的请求是被执行，而不是失败。没有解析到目标则返回 `未处理`.

#### 播放 Animator 状态

**适用于使用自己的 Animator Controller 进行动画的角色，而不是 Body Animation 模块。** 设置一个从动作名称映射而来的 Trigger 参数，并可选择等待结果状态结束。

| 属性                 | 值                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------- |
| **类**              | `ConvaiAnimatorStateActionExecutor`                                                |
| **菜单路径**           | `Add Component → Convai → Actions → Play Animator State (own Animator Controller)` |
| **Archetype 动作名称** | `播放 Animator 状态`                                                                   |
| **目标要求**           | 无                                                                                  |
| **所需同级组件**         | `Animator`                                                                         |

**检视器字段：**

| 字段          | 类型                                  | 默认 | 说明                           |
| ----------- | ----------------------------------- | -- | ---------------------------- |
| `_bindings` | `List<ConvaiAnimatorActionBinding>` | 空  | 每个该角色可通过 Animator 执行的动作对应一行。 |

**绑定行字段。** 每一行都在 Inspector 中配置；该行类型是 SDK 内部类型，因此脚本无法构造它。

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

没有匹配行的动作名称会被拒绝为 `未处理` ，而不是失败，因此该角色上的另一个动作行为仍有机会响应它。如果该角色有一个 `ConvaiBodyAnimationController`，则拒绝消息会指出 **播放手势** 而不是它——这两个行为驱动的是同一个 Animator，如果同时使用会相互冲突。

#### 播放声音

通过一个普通的 `AudioSource`AudioSource 播放声音。无论有无目标都可使用——这个选择在编写动作时确定：无目标加上一个已分配的 `AudioSource` 会直接播放声音；带有目标但没有 `AudioSource` 分配的，则从角色被要求作用的对象上播放。

| 属性                 | 值                                               |
| ------------------ | ----------------------------------------------- |
| **类**              | `ConvaiPlaySoundActionExecutor`                 |
| **菜单路径**           | `Add Component → Convai → Actions → Play Sound` |
| **Archetype 动作名称** | `播放声音`                                          |
| **目标要求**           | 二选一                                             |
| **所需同级组件**         | 无                                               |

**检视器字段：**

| 字段                      | 类型            | 默认      | 说明                                    |
| ----------------------- | ------------- | ------- | ------------------------------------- |
| `_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` |
| **Archetype 动作名称** | `看向对象`                                              |
| **目标要求**           | 二选一                                                 |
| **所需同级组件**         | `ConvaiGazeController`                              |
| **超时**             | 10秒（archetype 默认值）                                  |

**检视器字段：**

| 字段             | 类型                                  | 默认     | 说明                                                             |
| -------------- | ----------------------------------- | ------ | -------------------------------------------------------------- |
| `_mode`        | `ConvaiGazeLookMode` (`一瞥`, `持续凝视`) | `持续凝视` | Glance 是快速看一眼再移开；Sustained 是角色持续保持的凝视，必要时会转动身体。角色可以通过 `模式` 参数。 |
| `_holdSeconds` | `float`                             | `2.5`  | 当视线到达后要持续看多久。 `0` 会一直看着，直到有别的东西吸引角色的注意力。                       |
| `_engagement`  | `float`                             | `1`    | 注视得多专注， `0`–`1`.                                               |

角色为保持与正在交谈对象的眼神接触而拒绝的一次瞥视会报告 `未处理` （眼神锁按预期工作），而不是失败。

#### 注视玩家

与玩家保持眼神接触，直到被要求停止——这是一个有范围、可取消的请求，区别于角色自身的对话眼神接触设置，而此行为绝不会改变它。

| 属性                 | 值                                                     |
| ------------------ | ----------------------------------------------------- |
| **类**              | `ConvaiWatchPlayerActionExecutor`                     |
| **菜单路径**           | `Add Component → Convai → Actions → Watch The Player` |
| **Archetype 动作名称** | `注视玩家`                                                |
| **目标要求**           | 无（默认指玩家）                                              |
| **所需同级组件**         | `ConvaiGazeController`                                |

**检视器字段：**

| 字段            | 类型                                     | 默认   | 说明                                               |
| ------------- | -------------------------------------- | ---- | ------------------------------------------------ |
| `_mode`       | `ConvaiWatchPlayerMode` (`注视`, `停止注视`) | `注视` | 此调用是开始观看还是停止观看。角色可以通过 `模式` 参数（`watch` 或 `stop`). |
| `_engagement` | `float`                                | `1`  | 观看得多专注， `0`–`1`.                                 |

场景中未找到玩家会以 `ConvaiActionFailureReason.TargetMissing`失败。如果在观看中途禁用该组件，观看会自动释放。

#### 扫描环境

检查周围环境中的多个不同点，优先选择搜索半径内的场景对象，否则回退到等间距的世界点。

| 属性                 | 值                                                     |
| ------------------ | ----------------------------------------------------- |
| **类**              | `ConvaiScanEnvironmentActionExecutor`                 |
| **菜单路径**           | `Add Component → Convai → Actions → Scan Environment` |
| **Archetype 动作名称** | `扫描环境`                                                |
| **目标要求**           | 无                                                     |
| **所需同级组件**         | `ConvaiGazeController`                                |
| **超时**             | 15秒（archetype 默认值）                                    |

**检视器字段：**

| 字段                  | 类型          | 默认      | 说明                              |
| ------------------- | ----------- | ------- | ------------------------------- |
| `_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`   | 生成扫描点相对于角色原点的高度。                |

仅在 Play 模式下运行——它驱动实时视线装置，因此在 `未处理` Edit 模式下会拒绝。保持的视线会在完成、取消、禁用或销毁时释放。

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

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

#### 设置心情

持久型：让角色逐渐进入一种新情绪，并一直保持，直到有别的东西改变它。用于应影响对话后续部分的情绪变化。

| 属性                 | 值                                             |
| ------------------ | --------------------------------------------- |
| **类**              | `ConvaiSetMoodActionExecutor`                 |
| **菜单路径**           | `Add Component → Convai → Actions → Set Mood` |
| **Archetype 动作名称** | `设置心情`                                        |
| **目标要求**           | 无                                             |
| **所需同级组件**         | `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` |
| **Archetype 动作名称** | `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` |
| **Archetype 动作名称** | `点头或摇头`                                                |
| **目标要求**           | 无                                                      |
| **所需同级组件**         | `ConvaiBodyLanguageController`                         |

**检视器字段：**

| 字段           | 类型                                   | 默认   | 说明                                                      |
| ------------ | ------------------------------------ | ---- | ------------------------------------------------------- |
| `_response`  | `HeadGestureKind` (`点头`, `摇头`, `倾头`) | `点头` | 当角色没有指定时要给出的响应。角色可以请求 `是`, `否`，或 `也许` 通过 `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` |
| **Archetype 动作名称** | `播放手势`                                            |
| **目标要求**           | 无                                                 |
| **所需同级组件**         | `ConvaiBodyAnimationController`                   |
| **超时**             | 15秒（archetype 默认值）                                |

**检视器字段：**

| 字段                | 类型       | 默认  | 说明                                                    |
| ----------------- | -------- | --- | ----------------------------------------------------- |
| `_defaultGesture` | `string` | 空   | 当角色没有指定时要播放的手势。与 Animation Set 的手势名称和别名匹配。            |
| `_holdSeconds`    | `float`  | `8` | 要持续保持一个原本会无限继续的手势多久（如跳舞、思考姿势）。 `0` 会一直保持，直到有别的东西将其停止。 |

未知的手势名称会拒绝为 `未处理`；Animation Set 的真实手势名称会在 Detail 追踪级别下记录一次。使用普通 Animator Controller 而不是 Body Animation 模块的角色应使用 **播放 Animator 状态** 替代。

#### 指向目标

指向动作所命名的东西，会根据目标实际所在位置选择使用哪只手臂；身体其余部分仍继续做原本在进行的动作。

| 属性                 | 值                                                    |
| ------------------ | ---------------------------------------------------- |
| **类**              | `ConvaiPointAtActionExecutor`                        |
| **菜单路径**           | `Add Component → Convai → Actions → Point At Target` |
| **Archetype 动作名称** | `指向`                                                 |
| **目标要求**           | 二选一                                                  |
| **所需同级组件**         | `ConvaiBodyAnimationController`                      |
| **超时**             | 15秒（archetype 默认值）                                   |

**检视器字段：**

| 字段              | 类型                                           | 默认         | 说明                                                                        |
| --------------- | -------------------------------------------- | ---------- | ------------------------------------------------------------------------- |
| `_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 中没有指向剪辑会拒绝为 `未处理`。没有解析到目标也会以同样方式拒绝——指向始终需要目标。

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

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

#### 走向目标

走向目标，会绕开障碍物，并在一个舒适距离外停下，而不是直接走进对象。

| 属性                 | 值                                                   |
| ------------------ | --------------------------------------------------- |
| **类**              | `ConvaiWalkToActionExecutor`                        |
| **菜单路径**           | `Add Component → Convai → Actions → Walk To Target` |
| **Archetype 动作名称** | `走向`                                                |
| **目标要求**           | 二选一                                                 |
| **所需同级组件**         | `ConvaiNavMeshLocomotion`                           |
| **超时**             | 45秒（archetype 默认值）                                  |

**检视器字段：**

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

没有烘焙好的 NavMesh，或目标不在网格上，会以 `ConvaiActionFailureReason.PathBlocked` 失败，并说明目的地。需要烘焙好的 NavMesh。

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

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

| 属性                 | 值                                                          |
| ------------------ | ---------------------------------------------------------- |
| **类**              | `ConvaiLeadPlayerActionExecutor`                           |
| **菜单路径**           | `Add Component → Convai → Actions → Lead Player To Target` |
| **Archetype 动作名称** | `引导玩家`                                                     |
| **目标要求**           | 二选一                                                        |
| **所需同级组件**         | `ConvaiNavMeshLocomotion`                                  |
| **超时**             | 120秒（archetype 默认值）                                        |

**检视器字段：**

| 字段                      | 类型      | 默认    | 说明                        |
| ----------------------- | ------- | ----- | ------------------------- |
| `_arriveDistance`       | `float` | `1.4` | 角色距离目的地多远时停下。             |
| `_waitWhenFartherThan`  | `float` | `4.5` | 当玩家距离超过此值时暂停行程。           |
| `_resumeWhenCloserThan` | `float` | `2.8` | 当玩家回到该距离内时恢复行程。           |
| `_maximumWaitSeconds`   | `float` | `12`  | 在没有玩家的情况下继续前往目的地前，最长等待时间。 |

场景中没有玩家会因……而失败 `ConvaiActionFailureReason.TargetMissing`。到达目标的路径不会因……而失败 `PathBlocked`.

#### 转向面向目标

原地转身面向目标，不会朝它走去——大多数时候，“看着顾客”指的是这个，而不是穿过房间。无需 NavMesh。

| 属性                 | 值                                               |
| ------------------ | ----------------------------------------------- |
| **类**              | `ConvaiTurnToFaceActionExecutor`                |
| **菜单路径**           | `添加组件 → Convai → Actions → Turn To Face Target` |
| **Archetype 动作名称** | `Turn To Face`                                  |
| **目标要求**           | 二选一                                             |
| **所需同级组件**         | `ConvaiBodyAnimationController`                 |
| **超时**             | 10秒（archetype 默认值）                              |

**检视器字段：**

| 字段                   | 类型                                                   | 默认             | 说明                                                                                  |
| -------------------- | ---------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------- |
| `_turnStyle`         | `ConvaiTurnStyle` (`SteppingTurn`, `SmoothRotation`) | `SteppingTurn` | `SteppingTurn` 播放角色自己的转身动画； `SmoothRotation` 直接旋转 `_smoothTurnSeconds` 并且不需要任何动画片段。 |
| `_smoothTurnSeconds` | `float`                                              | `0.5`          | 一个 `SmoothRotation` 转身的持续时间。被 `SteppingTurn`.                                       |
| `_toleranceDegrees`  | `float`                                              | `8`            | 与目标面对得多近才算完成， `0`–`45`.                                                             |

`SteppingTurn` 在 Animation Set 中没有转身片段时，其值会随着 `未处理`而下降，使用 `SmoothRotation` 作为替代名称。

#### Follow The Player

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

| 属性                 | 值                                             |
| ------------------ | --------------------------------------------- |
| **类**              | `ConvaiFollowPlayerActionExecutor`            |
| **菜单路径**           | `添加组件 → Convai → Actions → Follow The Player` |
| **Archetype 动作名称** | `Follow The Player`                           |
| **目标要求**           | 无（默认指玩家）                                      |
| **所需同级组件**         | `ConvaiNavMeshLocomotion`                     |

**检视器字段：**

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

{% hint style="info" %}
**跟随没有自然结束点。** 角色一开始跟随，动作就会立即报告成功，而跟随本身会继续进行——否则它会一直挂起直到超时，并阻塞后续所有动作。再次发送该动作，并将 `mode: stop`，或禁用该角色，即可结束。正在跟随的角色仍会响应其他移动动作（Walk To Target、Return To Start）：在任何它未发起的移动期间，跟随会暂时让位，并在该移动结束后重新回到玩家身边继续跟随。
{% endhint %}

未找到玩家时会以……失败 `ConvaiActionFailureReason.TargetMissing`.

#### Return To Start

走回角色开始的位置——或者你选择的位置——并可选择恢复原始朝向。这个包里其他所有内容的撤销操作。

| 属性                 | 值                                           |
| ------------------ | ------------------------------------------- |
| **类**              | `ConvaiReturnToStartActionExecutor`         |
| **菜单路径**           | `添加组件 → Convai → Actions → Return To Start` |
| **Archetype 动作名称** | `Return To Start`                           |
| **目标要求**           | 无                                           |
| **所需同级组件**         | `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` 编写，因此除非你更改动作的 **When It Finishes** 设置，否则角色会把结果说出来。

#### Count Target Group

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

| 属性                 | 值                                              |
| ------------------ | ---------------------------------------------- |
| **类**              | `ConvaiCountTargetGroupActionExecutor`         |
| **菜单路径**           | `添加组件 → Convai → Actions → Count Target Group` |
| **Archetype 动作名称** | `Count Target Group`                           |
| **目标要求**           | 对象                                             |
| **必需的目标组件**        | `ConvaiActionTargetGroup`，位于已解析的目标对象上（不在角色上）   |

**检视器字段：**

| 字段                      | 类型       | 默认     | 说明                                   |
| ----------------------- | -------- | ------ | ------------------------------------ |
| `_availableMembersOnly` | `bool`   | `true` | 计数时忽略被禁用的成员组件和非活动成员对象。               |
| `_includeMemberNames`   | `bool`   | `true` | 在答案中包含成员名称以及数量。                      |
| `_memberLabel`          | `string` | 空      | 可选的复数标签，例如 `“crates”`。留空则使用目标组自己的名称。 |

已解析的目标没有 `ConvaiActionTargetGroup` 组件，或者组为空时，会以……失败 `未处理` 而不是报告误导性的零。

#### Measure Distance

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

| 属性                 | 值                                            |
| ------------------ | -------------------------------------------- |
| **类**              | `ConvaiMeasureDistanceActionExecutor`        |
| **菜单路径**           | `添加组件 → Convai → Actions → Measure Distance` |
| **Archetype 动作名称** | `Measure Distance`                           |
| **目标要求**           | 二选一                                          |
| **所需同级组件**         | 无                                            |

**检视器字段：**

| 字段                   | 类型      | 默认     | 说明                               |
| -------------------- | ------- | ------ | -------------------------------- |
| `_withinReachMetres` | `float` | `1.2`  | 不超过此值的距离会描述为“伸手可及”。              |
| `_aFewStepsMetres`   | `float` | `3.5`  | 不超过此值的距离会描述为“几步之遥”。              |
| `_acrossAreaMetres`  | `float` | `9`    | 不超过此值的距离会描述为“横跨整个区域”。超过它则为：“很远。” |
| `_includeMetres`     | `bool`  | `true` | 在答案中包含以米为单位的测量值。                 |

没有目标且场景中没有玩家时会以……失败 `ConvaiActionFailureReason.TargetMissing`.

### 选择合适的执行器

| 使用场景                             | 推荐的执行器                                                                                                                  |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 无需代码即可接入现有玩法                     | Raise Unity Event                                                                                                       |
| 控制一段流程的节奏，或在步骤之间暂停               | 等待                                                                                                                      |
| 将多个行为串联为一个动作                     | 按顺序运行                                                                                                                   |
| 切换场景对象的可见性                       | 显示或隐藏对象                                                                                                                 |
| 角色使用自己的 Animator Controller 进行动画 | 播放 Animator 状态                                                                                                          |
| 播放一个一次性声音，可带或不带目标                | 播放声音                                                                                                                    |
| 让角色的视线转向目标                       | 看向目标                                                                                                                    |
| 按要求与玩家保持眼神接触                     | 注视玩家                                                                                                                    |
| 可见地观察周围区域                        | 扫描环境                                                                                                                    |
| 改变角色当前的情绪状态                      | 设置心情                                                                                                                    |
| 转瞬即逝的情绪片刻                        | React                                                                                                                   |
| 用头部回答“是”、“否”或“让我想想”              | 点头或摇头                                                                                                                   |
| 播放 Animation Set 中命名的手势          | 播放手势                                                                                                                    |
| 指向一个命名的人、地点或物体                   | 指向目标                                                                                                                    |
| 使用寻路导航到目标                        | 走向目标                                                                                                                    |
| 引导玩家前往某处                         | 引导玩家前往目标                                                                                                                |
| 原地转身面对目标                         | 转向面向目标                                                                                                                  |
| 在玩家移动时陪同玩家                       | Follow The Player                                                                                                       |
| 撤销移动——走回起点                       | Return To Start                                                                                                         |
| 统计有多少已知对象可用                      | Count Target Group                                                                                                      |
| 回答“离那有多远”                        | Measure Distance                                                                                                        |
| 现有玩法中没有已发布的执行器覆盖                 | [编写自定义动作执行器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/writing-custom-executors.md) |

### 下一步

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