> 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/actions-scripting-reference.md).

# 角色动作脚本参考

Convai 角色动作系统的 API 参考——执行器基类、调度器、配置类型、调用对象和枚举。

Convai 角色动作系统中公开类型的完整 API 参考。类型位于 `Convai.Runtime.Actions`, `Convai.Runtime.Components`, `Convai.Shared.Actions`，或 `Convai.Shared.Types` 命名空间中，除非另有说明。

### `IConvaiActionExecutor`

`Convai.Runtime.Actions` — 接口

所有动作行为的扩展点。在任何 `MonoBehaviour`上实现，或改为派生自 `ConvaiActionExecutorBase` —— 参见 [编写自定义动作执行器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/writing-custom-executors.md).

```csharp
public interface IConvaiActionExecutor
{
    Task<ConvaiActionExecutionResult> ExecuteAsync(
        ConvaiActionInvocation invocation,
        CancellationToken cancellationToken);
}
```

返回 `ConvaiActionExecutionResult.Unhandled` 当组件无法处理该调用（例如缺少骨架或同伴）时，以便分发器能够将其单独报告。请遵守 `cancellationToken` 用于批量替换和超时。

### 执行器基类

`Convai.Runtime.Actions` — 抽象 `MonoBehaviour` 类

每个随产品发布的执行器都派生自这些基类之一，而不是直接实现 `IConvaiActionExecutor` 。派生后，组件会自动获得 Convai 检视器——分节字段、工具提示以及动作绑定状态块——无需编辑器代码。

| 类                                      | 派生自                                      | 新增                                                                 |
| -------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------ |
| `ConvaiActionExecutorBase`             | `MonoBehaviour`, `IConvaiActionExecutor` | `CharacterTransform`, `ResolvePlayer()`, `DeclaredButNotSent(...)` |
| `ConvaiTargetedActionExecutor`         | `ConvaiActionExecutorBase`               | 目标验证、同伴解析/缓存、缺少同伴诊断、参数覆盖辅助方法                                       |
| `ConvaiCharacterActionExecutor<TPeer>` | `ConvaiTargetedActionExecutor`           | 解析一个特定的角色侧组件（`TPeer`）并将其交给 `ExecuteCoreAsync`                      |
| `ConvaiActionExecutor<TParameters>`    | `ConvaiActionExecutorBase`               | 在执行前按名称将调用参数绑定到一个类型化的 `TParameters` 对象上                            |

#### `ConvaiActionExecutorBase`

```csharp
public abstract class ConvaiActionExecutorBase : MonoBehaviour, IConvaiActionExecutor
{
    public abstract Task<ConvaiActionExecutionResult> ExecuteAsync(
        ConvaiActionInvocation invocation,
        CancellationToken cancellationToken);
}
```

| 成员                                              | 类型                            | 说明                                                                 |
| ----------------------------------------------- | ----------------------------- | ------------------------------------------------------------------ |
| `CharacterTransform`                            | `Transform` （受保护）             | Convai 角色的变换，首次使用时通过向上搜索解析并缓存。若在其上方未找到角色，则回退到此组件自身的变换（不缓存）。        |
| `ResolvePlayer()`                               | `protected virtual Transform` | 玩家实际所在的位置；参见 `ConvaiPlayerBody` 下文。可为分屏、多套骨架或过场镜头相机重写              |
| `DeclaredButNotSent(invocation, parameterName)` | `protected static bool`       | 动作是否声明了 `parameterName` 且 Convai 角色未为其发送任何值——区分“对此未提及任何内容”与恰好为空的值。 |

#### `ConvaiTargetedActionExecutor`

```csharp
public abstract class ConvaiTargetedActionExecutor : ConvaiActionExecutorBase
{
    protected virtual bool RequiresTarget => true;

    protected abstract Task<ConvaiActionExecutionResult> ExecuteCoreAsync(
        ConvaiActionInvocation invocation,
        CancellationToken cancellationToken);
}
```

`ExecuteAsync` 已密封：当 `RequiresTarget` 是 `是` （默认值）且调用没有解析到目标时 `游戏对象`，它将返回 `MissingTargetResult(invocation)` — `Unhandled` ，默认如此——不会调用 `ExecuteCoreAsync`。设置 `RequiresTarget => false` 可用于不需要目标的动作（例如编排好的头部动作）。

| 成员                                              | 类型                                              | 说明                                                                                                              |
| ----------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `MissingTargetResult(invocation)`               | `protected virtual ConvaiActionExecutionResult` | 当缺少必需目标时返回的结果。可重写以返回 `Failed(..., ConvaiActionFailureReason.TargetMissing)` 而不是默认的 `Unhandled`                  |
| `ResolveTargetGameObject(invocation)`           | `protected static GameObject`                   | 已解析的目标 `游戏对象`，或 `null`                                                                                          |
| `ResolveTargetInteractionPoint(invocation)`     | `protected static Transform`                    | 已解析目标的 `InteractionPoint`，回退到其 `GameObjectReference`的变换                                                         |
| `TryResolvePeer<T>(ref T authored, out T peer)` | `protected bool`                                | 解析一个必需的同伴：显式的 `authored` 字段始终优先；否则查找 `GetComponentInParent<T>()` 然后 `GetComponentInChildren<T>()` 并在组件生命周期内记住结果 |
| `UnhandledMissingPeer<T>()`                     | `protected ConvaiActionExecutionResult`         | 为类型为 `Unhandled` 的缺失同伴构建一个 `T`结果，并为每个组件实例只记录一次日志                                                                |
| `GetOverride(invocation, name, defaultValue)`   | `protected static float`/`布尔值`/`字符串`            | 读取调用参数覆盖；若缺失或 `invocation` 是 `null`                                                                             |

#### `ConvaiCharacterActionExecutor<TPeer>`

```csharp
public abstract class ConvaiCharacterActionExecutor<TPeer> : ConvaiTargetedActionExecutor
    where TPeer : Component
{
    protected abstract Task<ConvaiActionExecutionResult> ExecuteCoreAsync(
        TPeer characterComponent,
        ConvaiActionInvocation invocation,
        CancellationToken cancellationToken);
}
```

解析 `TPeer` 一次，通过 `TryResolvePeer` 并直接交给 `ExecuteCoreAsync`；缺少组件时在方法运行前返回 `Unhandled` 通过 `UnhandledMissingPeer<TPeer>()` 这是那些只需要一个角色侧控制器的执行器背后的共享基类——例如 `ConvaiScanEnvironmentActionExecutor` （需要一个 `ConvaiGazeController`）和 `ConvaiLeadPlayerActionExecutor` （需要一个 `ConvaiNavMeshLocomotion`).

#### `ConvaiActionExecutor<TParameters>`

```csharp
public abstract class ConvaiActionExecutor<TParameters> : ConvaiActionExecutorBase
    where TParameters : new()
{
    protected abstract Task<ConvaiActionExecutionResult> ExecuteAsync(
        ConvaiActionInvocation invocation,
        TParameters parameters,
        CancellationToken cancellationToken);

    protected virtual TParameters BindParameters(ConvaiActionInvocation invocation);
}
```

按参数名称将 `TParameters` 的公共字段和属性绑定起来（支持的成员类型： `字符串`, `float`, `double`, `整数`, `布尔值`, `ConvaiResolvedActionTarget`, `ConvaiActionParameterValue`）。当 DTO 成员名与已编写的参数名不一致时，请使用 `[ConvaiActionParameter("name")]` 。

### `ConvaiPlayerBody`

`Convai.Runtime.Actions` — `public static class`

对于不是执行器的场景代码，玩家实际所在的位置。 `ConvaiActionExecutorBase.ResolvePlayer()` （受保护、可重写， `ConvaiActionExecutorBase.cs:113`）是执行器侧对此的简写。

| 方法                        | 签名                                                                             | 说明                                                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `Resolve`                 | `static Transform Resolve()`                                                   | 用于测量玩家位置的变换：优先使用场景中的 `ConvaiPlayer`，解析到其骨架实际移动的变换（一个 `CharacterController` 或 `Rigidbody` 在其内部，而不是预制体根节点）；若两者都不存在，则回退到 `Camera.main`; `null` 。 |
| `TryResolveFloorPosition` | `static bool TryResolveFloorPosition(float floorHeight, out Vector3 position)` | 玩家站立的位置，平铺到 `floorHeight`。当没有可测量对象时返回 `否` 。                                                                                                   |

### `ConvaiActionExecutionResult`

`Convai.Runtime.Actions` — 只读结构体

的返回类型 `IConvaiActionExecutor.ExecuteAsync`.

#### 属性

| 属性              | 类型                            | 说明                                                      |
| --------------- | ----------------------------- | ------------------------------------------------------- |
| `状态`            | `ConvaiActionExecutionStatus` | 此执行步骤的结果                                                |
| `消息`            | `字符串`                         | 可选诊断详情。会到达控制台、Actions Editor 和你自己的游戏代码——绝不会到达 Convai 角色 |
| `Answer`        | `字符串`                         | 此动作发现了什么，写成一句角色可以大声说出的普通句子。对于执行可见动作而非回答问题的动作则留空         |
| `HasAnswer`     | `布尔值`                         | 此结果是否携带非空的 `Answer`                                     |
| `异常`            | `异常`                          | 执行器抛出异常时捕获到的异常                                          |
| `FailureReason` | `ConvaiActionFailureReason`   | 机器可读的失败原因； `无` 用于非失败                                    |

#### 工厂方法

| 方法          | 签名                                                                                                                        | 在以下情况下使用                                                                 |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `Succeeded` | `static ConvaiActionExecutionResult Succeeded(string message = null)`                                                     | 行为已成功完成，并且没有玩家需要听到的内容                                                    |
| `Answered`  | `static ConvaiActionExecutionResult Answered(string answer, string message = null)`                                       | 该行为发现了玩家询问的内容——读取仪表、计数、测量距离。 `message` 默认为 `answer`                      |
| `Failed`    | `static ConvaiActionExecutionResult Failed(string message = null, Exception exception = null)`                            | 发生了未分类的错误。映射到 `ConvaiActionFailureReason.Custom` 当 `message` 如果非空，则为 `无` |
| `Failed`    | `static ConvaiActionExecutionResult Failed(string message, ConvaiActionFailureReason reason, Exception exception = null)` | 发生了具有已知结构化原因的错误。在新代码中优先于未分类重载                                            |
| `已取消`       | `static ConvaiActionExecutionResult Canceled()`                                                                           | “ `CancellationToken` 被触发，原因不是超时。 `FailureReason` 是 `被打断`                |
| `TimedOut`  | `static ConvaiActionExecutionResult TimedOut(string message = null)`                                                      | **不要手动调用。** 当 `TimeoutSeconds` 到期时，分发器会自动返回此结果。 `FailureReason` 是 `超时`   |
| `Unhandled` | `static ConvaiActionExecutionResult Unhandled(string message = null)`                                                     | 此执行器有意拒绝该调用。 `FailureReason` 是 `无`                                       |

`Answered(...)` 它是将查询动作与其他所有类型区分开的要素：它是唯一会填充 `Answer`以及 `Answer` 是 Convai 角色唯一会被告知的结果部分。它是会被说出来、静默记住，还是交由角色自行判断，需由该动作的 `ConvaiActionAnswerDelivery` 设置决定，而不是执行器。参见 [回答问题而不是执行动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/writing-custom-executors.md#answer-a-question-instead-of-acting) 以了解完整模式。

### `ConvaiActionFailureReason`

`Convai.Runtime.Actions`

步骤失败的机器可读原因，与自由文本 `消息`.

| 值                     | 说明                                                                                        |
| --------------------- | ----------------------------------------------------------------------------------------- |
| `无`                   | 无失败，或原因未分类（以下情况的默认值： `Succeeded`/`Unhandled`)                                             |
| `TargetMissing`       | 该调用需要一个已解析的目标，但未提供任何目标                                                                    |
| `TargetUnreachable`   | 已解析到目标，但无法到达                                                                              |
| `PathBlocked`         | 概念上存在通往目标的路径，但已被阻塞（例如没有有效的 NavMesh 路径）                                                    |
| `PeerMissing`         | 在角色上未找到所需的同伴组件（控制器、运动、骨架）                                                                 |
| `InvalidState`        | 执行器或某个依赖项处于无法处理该请求的状态                                                                     |
| `超时`                  | 该步骤超过了其定义的超时时间                                                                            |
| `被打断`                 | 该步骤在完成前被中断（已取消、被替换或被取代）                                                                   |
| `Custom`              | 任何其他仅通过以下方式传达的执行器特定失败： `消息`                                                               |
| `TargetNotActionable` | 已解析到目标，但缺少此动作需要对其执行操作的组件（参见 `RequiredTargetComponent` 时 `ConvaiActionArchetypeAttribute`) |
| `忙碌`                  | 角色现在无法接受该请求，因为它正在执行某件会使用同一部分的事情；同样的请求在稍后片刻通常会成功                                           |

### `ConvaiActionDefinition`

`Convai.Runtime.Actions` — 可序列化的密封类

一种编辑定义，将后端动作名称绑定到本地执行器、其类型化参数及其分发行为。只有渲染后的 wire 模板（来自 `ToActionConfigString`）会发送到 Convai。

#### 字段和属性

| 成员                      | 类型                                      | 说明                                                                                                                         |
| ----------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `ActionName`            | `字符串`                                   | 与后端命令匹配的动作名称（不区分大小写）                                                                                                       |
| `说明`                    | `字符串`                                   | 发送给 Convai 以用于 grounding 的可选描述                                                                                             |
| `参数`                    | `List<ConvaiActionParameterDefinition>` | 按顺序排列的类型化参数，渲染到 wire 模板中                                                                                                   |
| `TargetRequirement`     | `ConvaiActionTargetRequirement`         | 此动作需要哪种类型的目标                                                                                                               |
| `执行器`                   | `MonoBehaviour`                         | 执行该行为的组件。必须实现 `IConvaiActionExecutor`。此处的显式引用始终优先于 `ExecutorTypeHint`                                                      |
| `ExecutorTypeHint`      | `字符串`                                   | 一个的可选简短或完整类型名 `IConvaiActionExecutor` ，用于在以下情况下在角色层级上自动绑定 `执行器` 是 `null` ——供在以下对象内编写的定义使用 `ConvaiActionSet` 资源，因为它不能持有场景引用 |
| `TimeoutSeconds`        | `float`                                 | 最大执行时间（秒）。 `0` 或更少会禁用超时                                                                                                    |
| `FailurePolicyOverride` | `ConvaiActionFailurePolicyOverride`     | 对分发器批处理失败策略的按动作覆盖                                                                                                          |
| `回答传递`                  | `ConvaiActionAnswerDelivery`            | 角色如何处理一个 `Answered(...)` 结果。仅用于编写——绝不会发送到 Convai                                                                           |
| `等待机器人发言`               | `布尔值`                                   | 新批次的第一步是否等待角色发言                                                                                                            |
| `机器人发言后延迟秒数`            | `float`                                 | 在发言门打开后的可选延迟                                                                                                               |
| `类别`                    | `字符串` （属性）                              | 动作在 Actions Editor 中归档所用的可选编写标签。仅用于组织——不会发送到 Convai                                                                        |
| `已启用`                   | `布尔值` （属性）                              | 编写时的可用性。已禁用的动作会从 `action_config` 发送给 Convai。默认值为 `是`                                                                       |

#### 方法

| 方法                     | 签名                              | 说明                           |
| ---------------------- | ------------------------------- | ---------------------------- |
| `ToActionConfigString` | `string ToActionConfigString()` | 渲染此定义发送给 Convai 的 wire 模板字符串 |

### `ConvaiActionAnswerDelivery`

`Convai.Runtime.Actions`

Convai 角色如何处理 `Answer` 所返回的动作。作为每个动作在 Actions Editor 中编写的 **完成时**.

| 值        | 整数  | 说明                                   |
| -------- | --- | ------------------------------------ |
| `使用角色设置` | `0` | 遵循角色的 `ConvaiActionFeedbackRelay`。默认 |
| `仅记住`    | `1` | 角色会保留答案而不会大声说出。它仍会进入角色的记忆            |
| `如相关则提及` | `2` | 角色自行决定答案是否值得提及                       |
| `告诉玩家`   | `3` | 角色说出该动作发现的内容。用于回答直接问题的动作             |

### `ConvaiActionParameterDefinition`

`Convai.Runtime.Actions` — 可序列化的密封类

单个类型化动作参数的编写定义，由以下项引用 `ConvaiActionDefinition.Parameters`.

| 字段    | 类型                          | 说明                                          |
| ----- | --------------------------- | ------------------------------------------- |
| `名称`  | `字符串`                       | 作为 wire 键和模板锚点使用的参数名称                       |
| `说明`  | `字符串`                       | 发送给 Convai 以用于 grounding 的可选描述              |
| `类型`  | `ConvaiActionParameterType` | 声明的参数类型。 `自动` 从值推断。默认 `自动`                  |
| `连接词` | `字符串`                       | 在 wire 模板中渲染到参数前面的可选连接词（例如 `"on"` 或 `"in"`) |
| `选项`  | `List<string>`              | 允许的值，当 `类型` 是 `选项`                          |

### `ConvaiActionInvocation`

`Convai.Runtime.Actions` — 密封类

传递给执行器和所有分发器事件的类型化执行上下文。

#### 属性

| 属性               | 类型                           | 说明                                |
| ---------------- | ---------------------------- | --------------------------------- |
| `命令`             | `ConvaiActionCommand`        | 此步骤的原始后端命令                        |
| `定义`             | `ConvaiActionDefinition`     | 匹配到的本地动作定义。 `null` 如果未找到定义（步骤将失败） |
| `ResolvedTarget` | `ConvaiResolvedActionTarget` | 已解析的目标绑定。 `null` 如果动作没有目标或解析失败    |
| `角色`             | `ConvaiCharacter`            | 执行此动作的 NPC                        |
| `BatchIndex`     | `整数`                         | 调度器生命周期内该批次的顺序索引                  |
| `StepIndex`      | `整数`                         | 当前批次中此步骤的从 0 开始的索引                |

#### 方法

| 方法                | 签名                                                                        | 说明                                      |
| ----------------- | ------------------------------------------------------------------------- | --------------------------------------- |
| `TryGetParameter` | `bool TryGetParameter(string name, out ConvaiActionParameterValue value)` | 尝试按名称读取一个带类型的参数（不区分大小写）                 |
| `GetString`       | `string GetString(string name, string fallback = "")`                     | 读取字符串参数，返回 `fallback` 当不存在时             |
| `GetNumber`       | `float GetNumber(string name, float fallback = 0f)`                       | 读取数值参数，返回 `fallback` 当不存在时              |
| `GetBool`         | `bool GetBool(string name, bool fallback = false)`                        | 读取布尔参数，返回 `fallback` 当不存在时              |
| `GetReference`    | `ConvaiResolvedActionTarget GetReference(string name)`                    | 将引用参数与角色的动作配置进行解析；当参数没有显式种类时，回退到定义的目标要求 |

### `ConvaiResolvedActionTarget`

`Convai.Runtime.Actions` — 可序列化的密封类

通过中描述的解析阶梯生成的单个动作步骤的已解析目标。 [动作目标解析的工作方式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/attention-and-reference-grounding.md).

| 属性                    | 类型                                | 说明                                                                                                            |
| --------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `类型`                  | `ConvaiActionTargetKind`          | 解析后的目标是 Object、Character 还是 None                                                                              |
| `名称`                  | `字符串`                             | 解析后的名称（来自后端命令）                                                                                                |
| `ObjectBinding`       | `ConvaiActionObjectDefinition`    | 匹配到的对象定义。 `null` 如果 `Kind != Object`                                                                          |
| `CharacterBinding`    | `ConvaiActionCharacterDefinition` | 匹配到的角色定义。 `null` 如果 `Kind != Character`                                                                       |
| `GameObjectReference` | `游戏对象`                            | 场景 `游戏对象` 来自匹配绑定的                                                                                             |
| `InteractionPoint`    | `Transform`                       | 绑定显式的交互点（如果已设置），否则为 `GameObjectReference`的变换，否则为 `null`。每个已发布的定向执行器都会移动到或朝向此处，而不是原始的 `GameObjectReference` 变换 |

### `ConvaiActionCommand`

`Convai.Shared.Types` — 可序列化的密封类

后端返回的单步结构化动作命令。

#### 属性

| 属性             | 类型                                               | 说明                                        |
| -------------- | ------------------------------------------------ | ----------------------------------------- |
| `名称`           | `字符串`                                            | 必需。后端选择的动作名称（例如， `"Move To"`)             |
| `目标`           | `字符串`                                            | 可选。后端解析为目标的对象或角色名称。 `null` 如果没有目标         |
| `ActionString` | `字符串`                                            | 从后端重建的原始动作字符串 `名称` 和 `目标`                 |
| `参数`           | `Dictionary<string, ConvaiActionParameterValue>` | 从后端响应和当前 Unity 模板解析出的带类型参数。按不区分大小写的键索引    |
| `等待机器人发言`      | `布尔值`                                            | 在新批次中，第一个动作是否应等待角色说话后再运行                  |
| `机器人发言后延迟秒数`   | `float`                                          | 在语音门控释放后应用的可选延迟                           |
| `已丰富`          | `布尔值`                                            | `是` 一旦命令根据当前动作模板完成丰富。调度器会在分发前仅对未标记的命令丰富一次 |
| `HasTarget`    | `布尔值`                                            | `是` 当 `目标` 非空                             |

#### 构造函数

```csharp
new ConvaiActionCommand("Move To", "Crate")  // 名称 + 目标
new ConvaiActionCommand("Wave")              // 仅名称
```

构造函数会规范化 `名称` 和 `目标` 并从中派生 `ActionString` 。 `参数`, `等待机器人发言`, `机器人发言后延迟秒数`以及 `已丰富` 默认值为其空值，并由后端响应或丰富过程填充。

### `ConvaiActionParameterValue`

`Convai.Shared.Types` — 可序列化的密封类

丰富后得到的一个带类型动作参数。每种表示都会尽最大努力从原始文本填充； `类型` 指明所编写的模板意图使用哪一种。

| 属性                  | 类型                               | 说明                                |
| ------------------- | -------------------------------- | --------------------------------- |
| `类型`                | `ConvaiActionParameterType`      | 强制转换后的有效类型。一个编写时的 `自动` 解析为具体类型    |
| `RawValue`          | `字符串`                            | 此值解析自的修剪后原始文本                     |
| `StringValue`       | `字符串`                            | 该值的文本形式（与 `RawValue` 修剪后相同）       |
| `NumberValue`       | `float`                          | 解析得到的浮点数，或 `0` 当文本不是数字时           |
| `BoolValue`         | `布尔值`                            | 解析得到的布尔值，或 `否` 当文本不是可识别的布尔值时      |
| `ResolvedReference` | `ConvaiActionParameterReference` | 当文本命名了某个编写时目标时，匹配到的目标； `null` 否则为 |
| `IsConstraintMatch` | `布尔值`                            | `否` 仅当 `选项` 参数文本不属于其编写时选项之一时      |
| `Presence`          | `ConvaiActionParameterPresence`  | Convai 角色是否为此参数提供了任何值             |

通过读取参数 `ConvaiActionInvocation.TryGetParameter`, `GetString`, `GetNumber`, `GetBool`，或 `GetReference` ，而不是直接索引 `ConvaiActionCommand.Parameters` 。

### `ConvaiActionParameterPresence`

`Convai.Shared.Types`

参数的值是否确实来自 Convai 角色。一个声明了三个参数的动作总会返回三个，因为未填充的位置会被补齐，以保持值与编写顺序对齐—— `Presence` 是执行器区分补齐槽位和已回答槽位的方式。

| 值     | 整数  | 说明                       |
| ----- | --- | ------------------------ |
| `已提供` | `0` | 为此槽位提供了值。默认              |
| `缺失`  | `1` | 没有值到达此槽位；该参数仅因为动作声明了它而存在 |

在处理空值之前先检查这一点： `缺失` 表示没有提到该参数，执行器应自行决定——拒绝、询问或应用自己的默认值——而不是把空值视为指令。 `缺失` 也会通过 `动作` 日志类别记录一次。

### `ConvaiActionParameterReference`

`Convai.Shared.Types` — 可序列化的密封类

名称和种类处理一个 `引用` 参数在丰富过程中被解析为的值。

| 属性   | 类型                       | 说明                             |
| ---- | ------------------------ | ------------------------------ |
| `名称` | `字符串`                    | 原始值匹配到的编写时目标名称（已修剪，绝不为 `null`) |
| `类型` | `ConvaiActionTargetKind` | 该名称是否匹配到编写时的对象或角色              |

`ConvaiActionParameterReference` 是一个查找键，而不是场景绑定——它不携带 `GameObjectReference`。将其解析为一个活动的 `游戏对象` 通过 `ConvaiActionInvocation.GetReference(name)`，它返回一个 `ConvaiResolvedActionTarget`.

### `ConvaiActionConfig`

`Convai.Shared.Actions` — 可序列化的密封类

在连接时序列化到会话连接负载中的动作能力。

| 属性                       | 类型                                      | 说明                                        |
| ------------------------ | --------------------------------------- | ----------------------------------------- |
| `动作`                     | `List<string>`                          | 此会话允许的动作名称。只发送名称——执行器绑定保持在本地              |
| `Objects`                | `List<ConvaiActionObjectDefinition>`    | 后端可引用为目标的对象。 `GameObjectReference` 从不被序列化 |
| `角色`                     | `List<ConvaiActionCharacterDefinition>` | 后端可引用为目标的角色。 `GameObjectReference` 从不被序列化 |
| `CurrentAttentionObject` | `字符串`                                   | 初始关注对象名称。必须匹配 `Objects`                   |

### `ConvaiActionConfigPatch`

`Convai.Shared.Actions` — 可序列化的密封类

当前会话动作能力的运行时补丁，通过 `character.DynamicContext.Apply(...)`.

| 属性                       | 类型                                      | 说明             |
| ------------------------ | --------------------------------------- | -------------- |
| `动作`                     | `List<string>`                          | 替换动作列表         |
| `角色`                     | `List<ConvaiActionCharacterDefinition>` | 替换角色目标列表       |
| `Objects`                | `List<ConvaiActionObjectDefinition>`    | 替换对象目标列表       |
| `CurrentAttentionObject` | `字符串`                                   | 列表替换后解析出的注意力更新 |

{% hint style="warning" %}
每个字段都遵循省略与空值语义： `null` 列表或字符串会保留当前值，而空列表或空字符串会显式清除该值。仅在你打算更改它时才设置字段。
{% endhint %}

### `ConvaiActionObjectDefinition`

`Convai.Shared.Actions` — 可序列化的密封类

| 属性                    | 类型             | 已序列化                   | 说明                                                   |
| --------------------- | -------------- | ---------------------- | ---------------------------------------------------- |
| `名称`                  | `字符串`          | 是（`"name"`)            | 用于动作命令的标识符。按大小写不敏感匹配                                 |
| `说明`                  | `字符串`          | 是（`"description"`)     | 发送给 Convai 以用于引用解析的自然语言描述                            |
| `GameObjectReference` | `游戏对象`         | **否** (`[JsonIgnore]`) | 本地场景引用。绝不会发送给 Convai                                 |
| `仅文本`                 | `布尔值`          | **否** (`[JsonIgnore]`) | 声明此条目有意没有 `GameObjectReference`。如果没有它，缺失的引用会被报告为设置错误 |
| `别名`                  | `List<string>` | **否** (`[JsonIgnore]`) | 解析阶梯在回退到规范化/包含匹配之前，精确匹配的备用名称（步骤 2）                   |
| `InteractionPoint`    | `Transform`    | **否** (`[JsonIgnore]`) | 明确指定的移动或瞄准点。回退到 `GameObjectReference`的变换，当 `null`    |
| `可用`                  | `布尔值`          | **否** (`[JsonIgnore]`) | 本地解析开关， `是` 默认开启。不可用条目会被解析阶梯跳过                       |

### `ConvaiActionCharacterDefinition`

`Convai.Shared.Actions` — 可序列化的密封类

| 属性                    | 类型             | 已序列化                   | 说明                                         |
| --------------------- | -------------- | ---------------------- | ------------------------------------------ |
| `名称`                  | `字符串`          | 是（`"name"`)            | 此角色目标的标识符                                  |
| `简介`                  | `字符串`          | 是（`"bio"`)             | 发送给 Convai 的简短描述（例如，“站点安全主管”）              |
| `GameObjectReference` | `游戏对象`         | **否** (`[JsonIgnore]`) | 本地场景引用。绝不会发送给 Convai                       |
| `仅文本`                 | `布尔值`          | **否** (`[JsonIgnore]`) | 与上面相同的仅本地含义 `ConvaiActionObjectDefinition` |
| `别名`                  | `List<string>` | **否** (`[JsonIgnore]`) | 与上面相同的仅本地含义 `ConvaiActionObjectDefinition` |
| `InteractionPoint`    | `Transform`    | **否** (`[JsonIgnore]`) | 与上面相同的仅本地含义 `ConvaiActionObjectDefinition` |
| `可用`                  | `布尔值`          | **否** (`[JsonIgnore]`) | 与上面相同的仅本地含义 `ConvaiActionObjectDefinition` |

### `ConvaiActionTarget`

`Convai.Runtime.Actions` — `MonoBehaviour`

菜单路径： `添加组件 → Convai → Actions → Convai Action Target`

将任何 `游戏对象` 标记为无需代码的运行时动作锚定目标。启用后，它对所选角色的合并动作配置可见，并且像编写时对象或角色一样参与解析阶梯，唯一不同是同名的编写时条目始终优先。

| 属性                 | 类型                             | 说明                             |
| ------------------ | ------------------------------ | ------------------------------ |
| `TargetName`       | `字符串`                          | 解析阶梯匹配的目标名称。若为空则默认为此 `游戏对象`的名称 |
| `类型`               | `ConvaiActionTargetKind`       | 这是一个可执行对象还是角色                  |
| `说明`               | `字符串`                          | 发送给 Convai 以用于锚定（对象种类）         |
| `简介`               | `字符串`                          | 发送给 Convai 以用于锚定（角色种类）         |
| `别名`               | `List<string>`                 | 解析阶梯精确匹配的备用名称（步骤 2）            |
| `InteractionPoint` | `Transform`                    | 可选的显式移动或瞄准点                    |
| `ApplyTo`          | `ConvaiActionTargetApplyScope` | 启用时哪些角色会注册此目标： `所有角色` 或 `特定角色` |
| `特定角色`             | `List<ConvaiCharacter>`        | 要注册到的角色，当 `ApplyTo` 是 `特定角色`   |
| `RegisterOnEnable` | `布尔值`                          | 目标是否在启用时注册、在禁用时注销。默认 `是`       |

### 内置执行器类型

每个执行器的完整字段级参考都位于 [动作执行器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md)。从该目录中选取的一部分：

| 执行器                                    | 菜单路径                                   | 备注                                                            |
| -------------------------------------- | -------------------------------------- | ------------------------------------------------------------- |
| `ConvaiLeadPlayerActionExecutor`       | `Convai/Actions/Lead Player To Target` | 身体动画包；需要一个 `ConvaiNavMeshLocomotion` 同伴                       |
| `ConvaiScanEnvironmentActionExecutor`  | `Convai/Actions/Scan Environment`      | 目光包；需要一个 `ConvaiGazeController` 同伴                            |
| `ConvaiCountTargetGroupActionExecutor` | `Convai/Actions/Count Target Group`    | 观察包；需要一个 `ConvaiActionTargetGroup` 在已解析目标上；返回 `Answered(...)` |
| `ConvaiMeasureDistanceActionExecutor`  | `Convai/Actions/Measure Distance`      | 观察包；不需要必需的同伴；返回 `Answered(...)`                               |

观察包的执行器回答一个问题，而不是执行可见动作，使用 `ConvaiActionExecutionResult.Answered(...)` 中调用的，而不是在 `Succeeded(...)`.

### `ConvaiActionDispatcher`

`MonoBehaviour` — `Convai.Runtime.Actions`

菜单路径： `添加组件 → Convai → Convai Action Runner`

约束： `DisallowMultipleComponent`, `RequireComponent(ConvaiCharacter)`

#### 属性

| 属性                           | 类型                                 | 说明                                                            |
| ---------------------------- | ---------------------------------- | ------------------------------------------------------------- |
| `BatchPolicy`                | `ConvaiActionBatchPolicy`          | 当前批次策略（代码中只读；在 Inspector 中设置）                                 |
| `FailurePolicy`              | `ConvaiActionBatchFailurePolicy`   | 当前失败策略（代码中只读；在 Inspector 中设置）                                 |
| `IsBusy`                     | `布尔值`                              | 当前是否有批次正在执行                                                   |
| `PendingBatchCount`          | `整数`                               | 排在当前批次后面的待处理批次数量                                              |
| `CurrentActionName`          | `字符串`                              | 当前正在执行的动作显示名称，或为空                                             |
| `CancelOnUserSpeech`         | `布尔值`                              | 启用后，调度器会在玩家开始说话的瞬间取消正在执行的批次并清空队列。默认关闭                         |
| `EnablePerformanceReactions` | `布尔值`                              | 批次/步骤生命周期是否通知 `IActionPerformanceReactor` 同伴（目光、肢体语言、情绪）。默认开启 |
| `OnBatchStarted`             | `UnityEvent`                       | 当批次开始执行时触发                                                    |
| `OnStepStarted`              | `ConvaiActionInvocationUnityEvent` | 每个动作步骤开始时触发                                                   |
| `OnStepSucceeded`            | `ConvaiActionInvocationUnityEvent` | 当执行器返回时触发 `Succeeded` 或 `Answered`                            |
| `OnStepFailed`               | `ConvaiActionInvocationUnityEvent` | 当步骤失败时触发（Failed、Canceled 或 TimedOut）                          |
| `OnStepUnhandled`            | `ConvaiActionInvocationUnityEvent` | 当执行器返回时触发 `Unhandled`                                         |
| `OnStepCompleted`            | `ConvaiActionStepReportUnityEvent` | 每一步结束后都会触发，无论成功与否，并携带完整的 `ConvaiActionStepReport`             |
| `OnBatchCompleted`           | `UnityEvent`                       | 当批次中的所有步骤完成且批次未被中止时触发                                         |
| `OnBatchAborted`             | `UnityEvent`                       | 当 `StopBatch` 策略在失败后提前终止批次时触发                                 |
| `OnCancelledByUserSpeech`    | `event Action<string>`             | 当 `CancelOnUserSpeech` 取消正在执行的动作，并携带其显示名称                     |

#### 方法

| 方法               | 签名                                                                | 说明                             |
| ---------------- | ----------------------------------------------------------------- | ------------------------------ |
| `EnqueueActions` | `void EnqueueActions(IReadOnlyList<ConvaiActionCommand> actions)` | 向调度器提交一个批次。遵守当前的 `BatchPolicy` |

参见 [调度器与批次策略](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/dispatcher-and-batch-policies.md) 以了解批次/失败策略行为和调优指导。

### `ConvaiActionConfigSource`

`MonoBehaviour` — `Convai.Runtime.Components`

菜单路径： `添加组件 → Convai → Convai Actions`

约束： `DisallowMultipleComponent`, `RequireComponent(ConvaiCharacter)`

#### 属性

| 属性                       | 类型                                               | 说明                                                                      |
| ------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------- |
| `定义`                     | `IReadOnlyList<ConvaiActionDefinition>`          | 编写时的内联动作定义列表                                                            |
| `ActionSets`             | `IReadOnlyList<ConvaiActionSet>`                 | 可复用的动作集资源，优先于 `定义`进行合并；内联定义在与任何集合发生名称冲突时始终优先                            |
| `Objects`                | `IReadOnlyList<ConvaiActionObjectDefinition>`    | 编写时的可执行对象列表                                                             |
| `角色`                     | `IReadOnlyList<ConvaiActionCharacterDefinition>` | 编写时的可执行角色列表                                                             |
| `InitialAttentionObject` | `字符串`                                            | 在连接时预先设定为 NPC 关注焦点的对象名称                                                 |
| `ActionExecutionMode`    | `ConvaiActionExecutionMode`                      | 声明 `ConvaiActionDispatcher` 或自定义代码是否执行此角色的动作。不会改变运行时任何内容；用于 SDK 自身的设置检查 |
| `BehaviorHost`           | `游戏对象`                                           | 新编写的动作行为会添加到的对象：分配的子对象，若未分配则为角色自身                                       |

#### 方法

| 方法                  | 签名                                       | 说明                             |
| ------------------- | ---------------------------------------- | ------------------------------ |
| `BuildActionConfig` | `ConvaiActionConfig BuildActionConfig()` | 构建并返回连接时负载。返回 `null` 如果不存在有效定义 |

### `ConvaiActionExecutionMode`

`Convai.Runtime.Components`

| 值                        | 整数  | 说明                                                                                                  |
| ------------------------ | --- | --------------------------------------------------------------------------------------------------- |
| `ConvaiActionDispatcher` | `0` | 已发布的 `ConvaiActionDispatcher` 在此角色上运行这些命令。默认；设置检查在此模式下期望存在一个调度器组件                                   |
| `CustomCode`             | `1` | 你自己的代码订阅 `ConvaiCharacter.OnActionsReceived` 或 `ConvaiManager.Events.OnCharacterActionReceived` 而不是 |

### `ConvaiCharacter` ——与动作相关的成员

`MonoBehaviour` — `Convai.Runtime.Components`

#### 事件

| 事件                  | 类型                                                 | 说明                                    |
| ------------------- | -------------------------------------------------- | ------------------------------------- |
| `OnActionsReceived` | `event Action<IReadOnlyList<ConvaiActionCommand>>` | 当 Convai 为此角色返回一个动作批次时触发。早于调度器处理它之前触发 |

#### 属性

| 属性             | 类型                   | 说明                             |
| -------------- | -------------------- | ------------------------------ |
| `ActionConfig` | `ConvaiActionConfig` | 返回当前会话动作配置的克隆。可能为 `null` 在连接之前 |

#### 方法

| 方法                      | 签名                                                 | 说明                                               |
| ----------------------- | -------------------------------------------------- | ------------------------------------------------ |
| `GetActionConfigSource` | `ConvaiActionConfigSource GetActionConfigSource()` | 返回 `ConvaiActionConfigSource` 在此 `游戏对象`，或 `null` |

{% hint style="info" %}
对当前关注对象的运行时更新由动态上下文系统处理，而不是由 `ConvaiCharacter` 直接。参见 [动作目标解析的工作方式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/attention-and-reference-grounding.md#runtime-attention-api).
{% endhint %}

### `RoomSessionConnectOptions` — 动作字段

`Convai.Runtime.Room`

| 字段                          | 类型                             | 说明                                                                              |
| --------------------------- | ------------------------------ | ------------------------------------------------------------------------------- |
| `ActionConfigOverride`      | `ConvaiActionConfig`           | 设置后，将替换 `ConvaiActionConfigSource.BuildActionConfig()` 用于此会话                    |
| `ActionDefinitionsOverride` | `List<ConvaiActionDefinition>` | 设置后，将替换此会话的 Inspector 动作定义。会根据以下内容进行筛选： `ActionConfigOverride.Actions` 如果两者都已设置 |

### `ConvaiActionStepReport`

`Convai.Runtime.Actions` — 可序列化的密封类

已完成步骤报告由以下项发出： `ConvaiActionDispatcher.OnStepCompleted`.

| 属性              | 类型                            | 说明                         |
| --------------- | ----------------------------- | -------------------------- |
| `调用`            | `ConvaiActionInvocation`      | 报告所描述的调用                   |
| `结果`            | `ConvaiActionExecutionResult` | 该步骤的原始执行结果                 |
| `FailureReason` | `ConvaiActionFailureReason`   | 透传给 `Result.FailureReason` |
| `批次已中止`         | `布尔值`                         | 此步骤是否中止了剩余批次               |
| `消息`            | `字符串`                         | 成功详情，或非成功状态下的失败消息          |
| `失败消息`          | `字符串`                         | 失败详情，包括批次影响。成功时为空          |

### 枚举

动作系统其余的枚举，汇总于此供参考。

#### `ConvaiActionBatchPolicy`

`Convai.Runtime.Actions`

| 值      | 整数  | 说明                       |
| ------ | --- | ------------------------ |
| `队列`   | `0` | 新批次会等待当前批次完成。默认          |
| `替换当前` | `1` | 取消当前活动步骤和所有待处理批次；立即开始新批次 |
| `丢弃传入` | `2` | 在所有当前和队列中的工作完成之前，丢弃新批次   |

#### `ConvaiActionBatchFailurePolicy`

`Convai.Runtime.Actions`

| 值           | 整数  | 说明                                    |
| ----------- | --- | ------------------------------------- |
| `StopBatch` | `0` | 失败的步骤会中止剩余批次。 `OnBatchAborted` 触发。默认  |
| `继续批次`      | `1` | 执行无论如何都会继续到下一步。 `OnBatchCompleted` 触发 |

#### `ConvaiActionTargetRequirement`

`Convai.Runtime.Actions`

| 值      | 整数  | 说明             |
| ------ | --- | -------------- |
| `无`    | `0` | 动作不需要目标        |
| `对象`   | `1` | 动作需要一个已解析的对象目标 |
| `角色`   | `2` | 动作需要一个已解析的角色目标 |
| `二者皆可` | `3` | 动作可接受对象或角色作为目标 |

#### `ConvaiActionFailurePolicyOverride`

`Convai.Runtime.Actions`

| 值           | 整数  | 说明                                  |
| ----------- | --- | ----------------------------------- |
| `使用调度器默认值`  | `0` | 遵循 `ConvaiActionDispatcher` 失败策略。默认 |
| `StopBatch` | `1` | 非成功结果会中止剩余批次                        |
| `继续批次`      | `2` | 非成功结果会让剩余批次继续                       |

#### `ConvaiActionTargetKind`

`Convai.Shared.Types`

| 值    | 整数  | 说明       |
| ---- | --- | -------- |
| `无`  | `0` | 未解析到目标   |
| `对象` | `1` | 目标是已注册对象 |
| `角色` | `2` | 目标是已注册角色 |

#### `ConvaiActionParameterType`

`Convai.Shared.Types`

| 值     | 整数  | 说明                                          |
| ----- | --- | ------------------------------------------- |
| `自动`  | `0` | 尽力按此顺序推断引用、数字、布尔值或字符串。默认                    |
| `引用`  | `1` | 按名称解析一个已创建的对象或角色目标                          |
| `字符串` | `2` | 保留原始文本                                      |
| `数字`  | `3` | 解析一个使用不变区域性格式的浮点数                           |
| `布尔值` | `4` | 解析 `是`/`是`/`1` 或 `否`/`否`/`0`                |
| `选项`  | `5` | 要求为已创建的选项字符串之一。若不匹配，将通过 `IsConstraintMatch` |

#### `ConvaiActionExecutionStatus`

`Convai.Runtime.Actions`

| 值           | 整数  | 调度器事件触发           |
| ----------- | --- | ----------------- |
| `Succeeded` | `0` | `OnStepSucceeded` |
| `Failed`    | `1` | `OnStepFailed`    |
| `已取消`       | `2` | `OnStepFailed`    |
| `TimedOut`  | `3` | `OnStepFailed`    |
| `Unhandled` | `4` | `OnStepUnhandled` |

### `ConvaiActionInvocationUnityEvent`

`Convai.Runtime.Actions` — 可序列化类，继承自 `UnityEvent<ConvaiActionInvocation>`

使……可序列化的包装类型 `ConvaiActionInvocation` 可作为 UnityEvent 参数进行序列化。像普通 UnityEvent 一样在 Inspector 中分配处理程序。该事件的唯一参数是 `ConvaiActionInvocation` 用于该步骤。

`ConvaiActionStepReportUnityEvent` 是以下内容的等效包装器： `ConvaiActionDispatcher.OnStepCompleted`；它继承自 `UnityEvent<ConvaiActionStepReport>` 并携带完整的 `ConvaiActionStepReport` 作为替代。

### `ConvaiActionDebugProbe`

`MonoBehaviour` — `Convai.Runtime.Actions`

菜单路径： `添加组件 → Convai → Actions → Diagnostics → Convai Action Monitor`

约束： `DisallowMultipleComponent`, `RequireComponent(ConvaiCharacter)`

参见 [排查角色动作问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/debugging-and-troubleshooting.md) 请参阅完整的 Inspector 字段参考和使用指南。

#### 上下文菜单操作

| 命令                  | 效果                                               |
| ------------------- | ------------------------------------------------ |
| `Inject Test Batch` | 提交一个 `Move To` 以第一个已注册对象为目标的命令到调度器。无需实时对话即可测试该管道 |
| `Reset Probe State` | 将所有计数器和文本字段重置为零/空                                |

### 下一步

{% 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/0e9ccbf7f8fa10ad65f6395315d82ba64412791c" %}
[角色动作示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/usage-examples.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/actions-scripting-reference.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.