> 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 角色的 Transform：首次使用时通过向上搜索解析并缓存。若其上方未找到角色，则回退到此组件自身的 Transform（不缓存） |
| `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` 是 `true` （默认值）且调用没有已解析的目标 `GameObject`时，它默认返回 `MissingTargetResult(invocation)` — `未处理` ——而不调用 `ExecuteCoreAsync`。将 `RequiresTarget => false` 用于无目标动作（例如脚本化的点头动作）。

| 成员                                              | 类型                                              | 说明                                                                                                               |
| ----------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `MissingTargetResult(invocation)`               | `protected virtual ConvaiActionExecutionResult` | 缺少必需目标时返回的结果。重写以返回 `Failed(..., ConvaiActionFailureReason.TargetMissing)` 而非默认值 `未处理`                            |
| `ResolveTargetGameObject(invocation)`           | `protected static GameObject`                   | 已解析的目标 `GameObject`，或 `null`                                                                                     |
| `ResolveTargetInteractionPoint(invocation)`     | `protected static Transform`                    | 已解析目标的 `InteractionPoint`，回退到其 `GameObjectReference`的 Transform                                                  |
| `TryResolvePeer<T>(ref T authored, out T peer)` | `protected bool`                                | 解析必需的对等组件：显式的 `authored` 字段始终优先；否则查找 `GetComponentInParent<T>()` 然后 `GetComponentInChildren<T>()` 并在组件的生命周期内记住结果 |
| `UnhandledMissingPeer<T>()`                     | `protected ConvaiActionExecutionResult`         | 构建一个 `未处理` 类型的缺失对等组件结果 `T`，每个组件实例仅记录一次日志                                                                         |
| `GetOverride(invocation, name, defaultValue)`   | `protected static float`/`bool`/`string`        | 读取调用参数覆盖值；若不存在或 `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`；缺失组件会返回 `未处理` ，通过 `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` 按参数名称（支持的成员类型： `string`, `float`, `double`, `int`, `bool`, `ConvaiResolvedActionTarget`, `ConvaiActionParameterValue`）。使用 `[ConvaiActionParameter("name")]` 当 DTO 成员名称与创作的参数名称不同时。

### `ConvaiPlayerBody`

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

对于不是执行器的场景代码，玩家实际所在的位置。 `ConvaiActionExecutorBase.ResolvePlayer()` （protected virtual， `ConvaiActionExecutorBase.cs:113`）是执行器端对此的简写。

| 方法                        | 签名                                                                             | 说明                                                                                                                                                                    |
| ------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Resolve`                 | `static Transform Resolve()`                                                   | 用于衡量玩家位置的 Transform：优先使用场景中的 `ConvaiPlayer`，并解析为其绑定组件实际移动的 Transform（其中的 `CharacterController` 或 `Rigidbody` ，而不是预制体根节点）；如果两者均不存在，则回退到 `Camera.main`; `null` 如果两者都不存在 |
| `TryResolveFloorPosition` | `static bool TryResolveFloorPosition(float floorHeight, out Vector3 position)` | 玩家站立的位置，平铺到 `floorHeight`。返回 `false` 当没有人可供测量时                                                                                                                        |

### `ConvaiActionExecutionResult`

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

以下项的返回类型： `IConvaiActionExecutor.ExecuteAsync`.

#### 属性

| 属性              | 类型                            | 说明                                             |
| --------------- | ----------------------------- | ---------------------------------------------- |
| `状态`            | `ConvaiActionExecutionStatus` | 此执行步骤的结果                                       |
| `Message`       | `string`                      | 可选诊断详情。会传至控制台、动作编辑器和你自己的游戏代码——绝不会传给 Convai 角色  |
| `答案`            | `string`                      | 此动作发现的内容，以角色可以大声说出的一句普通话写成。对于执行可见动作而非回答问题的动作为空 |
| `HasAnswer`     | `bool`                        | 此结果是否包含非空的 `答案`                                |
| `异常`            | `异常`                          | 执行器抛出异常时捕获的异常                                  |
| `FailureReason` | `ConvaiActionFailureReason`   | 机器可读的失败原因； `无` 用于非失败情况                         |

#### 工厂方法

| 方法         | 签名                                                                                                                        | 适用于                                                                    |
| ---------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `成功`       | `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` 是 `被打断`           |
| `超时`       | `static ConvaiActionExecutionResult TimedOut(string message = null)`                                                      | **请勿手动调用。** 当 `TimeoutSeconds` 到期时，调度器会自动返回此结果。 `FailureReason` 是 `超时` |
| `未处理`      | `static ConvaiActionExecutionResult Unhandled(string message = null)`                                                     | 此执行器有意拒绝该调用。 `FailureReason` 是 `无`                                     |

`Answered(...)` 是区分查询动作与其他所有类型的依据：它是唯一会填充 `答案`，以及 `答案` 的工厂方法。它是 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`

步骤失败时的机器可读原因，以及自由文本 `Message`.

| 值                     | 说明                                                                                        |
| --------------------- | ----------------------------------------------------------------------------------------- |
| `无`                   | 无失败，或原因未分类（以下项的默认值： `成功`/`未处理`)                                                           |
| `TargetMissing`       | 调用需要一个已解析目标，但不存在该目标                                                                       |
| `TargetUnreachable`   | 目标已解析，但无法到达                                                                               |
| `PathBlocked`         | 在概念上存在通往目标的路径，但该路径被阻塞（例如没有有效的 NavMesh 路径）                                                 |
| `PeerMissing`         | 未在角色上找到必需的对等组件（控制器、移动组件、绑定组件）                                                             |
| `InvalidState`        | 执行器或依赖项处于无法处理请求的状态                                                                        |
| `超时`                  | 该步骤超过了其定义的超时时间                                                                            |
| `被打断`                 | 该步骤在完成前被中断（取消、替换或取代）                                                                      |
| `Custom`              | 仅通过以下项传达的任何其他执行器特定失败： `Message`                                                           |
| `TargetNotActionable` | 目标已解析，但缺少此动作对其执行操作所需的组件（请参阅 `RequiredTargetComponent` 在 `ConvaiActionArchetypeAttribute`) |
| `Busy`                | 角色当前无法接受请求，因为它正在执行占用相同部分的任务；稍后再次提出相同请求通常会成功                                               |

### `ConvaiActionDefinition`

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

将后端动作名称绑定到本地执行器、其强类型参数及其调度行为的创作定义。仅渲染后的线缆模板（来自 `ToActionConfigString`）会发送给 Convai。

#### 字段和属性

| 成员                           | 类型                                      | 说明                                                                                                                              |
| ---------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `ActionName`                 | `string`                                | 与后端命令匹配的动作名称（不区分大小写）                                                                                                            |
| `说明`                         | `string`                                | 发送给 Convai 以提供上下文的可选描述                                                                                                          |
| `参数`                         | `List<ConvaiActionParameterDefinition>` | 渲染到线缆模板中的有序强类型参数                                                                                                                |
| `TargetRequirement`          | `ConvaiActionTargetRequirement`         | 此动作所需的目标类型                                                                                                                      |
| `执行器`                        | `MonoBehaviour`                         | 执行行为的组件。必须实现 `IConvaiActionExecutor`。此处的显式引用始终优先于 `ExecutorTypeHint`                                                            |
| `ExecutorTypeHint`           | `string`                                | 以下项的可选短类型名称或完整类型名称： `IConvaiActionExecutor` 当以下条件满足时，在角色层级结构上自动绑定 `执行器` 是 `null` — 由在以下项内创作的定义使用： `ConvaiActionSet` 资源，无法保存场景引用 |
| `TimeoutSeconds`             | `float`                                 | 最长执行时间（秒）。 `0` 或更小的值会禁用超时                                                                                                       |
| `FailurePolicyOverride`      | `ConvaiActionFailurePolicyOverride`     | 对调度器批次失败策略的每动作覆盖                                                                                                                |
| `AnswerDelivery`             | `ConvaiActionAnswerDelivery`            | 角色如何处理一个 `Answered(...)` 结果。仅用于创作——绝不会发送给 Convai                                                                                |
| `WaitForBotSpeech`           | `bool`                                  | 新批次的第一步是否等待角色语音                                                                                                                 |
| `DelayAfterBotSpeechSeconds` | `float`                                 | 语音门控解除后的可选延迟                                                                                                                    |
| `类别`                         | `string` （属性）                           | 在动作编辑器中为动作归档所用的可选创作标签。仅用于组织——不会发送给 Convai                                                                                       |
| `已启用`                        | `bool` （属性）                             | 创作时的可用性。已禁用的动作不包含在 `action_config` 发送给 Convai 的内容中。默认值为 `true`                                                                  |

#### 方法

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

### `ConvaiActionAnswerDelivery`

`Convai.Runtime.Actions`

Convai 角色如何处理动作返回的 `答案` 。在动作编辑器中按动作创作，名称为 **完成时**.

| 值                     | 整数  | 说明                                    |
| --------------------- | --- | ------------------------------------- |
| `UseCharacterSetting` | `0` | 遵从角色的 `ConvaiActionFeedbackRelay`。默认值 |
| `RememberOnly`        | `1` | 角色保留答案而不大声说出。它仍会传入角色的记忆               |
| `MentionIfRelevant`   | `2` | 角色自行决定该答案是否值得提及                       |
| `TellThePlayer`       | `3` | 角色会说出动作发现的内容。用于回答直接问题的动作              |

### `ConvaiActionParameterDefinition`

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

单个强类型动作参数的创作定义，由以下项引用： `ConvaiActionDefinition.Parameters`.

| 字段    | 类型                          | 说明                                         |
| ----- | --------------------------- | ------------------------------------------ |
| `名称`  | `string`                    | 用作线缆键和模板锚点的参数名称                            |
| `说明`  | `string`                    | 发送给 Convai 以提供上下文的可选描述                     |
| `类型`  | `ConvaiActionParameterType` | 声明的参数类型。 `自动` 会从值中推断。默认值 `自动`              |
| `连接词` | `string`                    | 在线缆模板中参数之前渲染的可选连接词（例如 `“在……上”` 或 `“在……中”`) |
| `选项`  | `List<string>`              | 当以下项为 `类型` 是 `Choice`                      |

### `ConvaiActionInvocation`

`Convai.Runtime.Actions` — 密封类

传递给执行器和所有调度器事件的强类型执行上下文。

#### 属性

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

#### 方法

| 方法                | 签名                                                                        | 说明                                     |
| ----------------- | ------------------------------------------------------------------------- | -------------------------------------- |
| `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).

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

### `ConvaiActionCommand`

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

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

#### 属性

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

#### 构造函数

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

构造函数会规范化 `名称` 和 `目标` 并从中推导出 `ActionString` 。 `参数`, `WaitForBotSpeech`, `DelayAfterBotSpeechSeconds`，以及 `已增强` 默认值为其空值，并由后端响应或增强过程填充。

### `ConvaiActionParameterValue`

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

增强后的一个强类型动作参数。每种表示都会尽力从原始文本中填充； `类型` 指示作者模板意图使用哪一种。

| 属性                  | 类型                               | 说明                                   |
| ------------------- | -------------------------------- | ------------------------------------ |
| `类型`                | `ConvaiActionParameterType`      | 类型转换后的有效类型。一个作者定义的 `自动` 解析为一个具体类型    |
| `RawValue`          | `string`                         | 解析此值所依据的修剪后原始文本                      |
| `StringValue`       | `string`                         | 作为文本的值（与 `RawValue` 相同，已修剪）          |
| `NumberValue`       | `float`                          | 解析后的浮点数，或 `0` 当文本不是数值时               |
| `BoolValue`         | `bool`                           | 解析后的布尔值，或 `false` 当文本不是可识别的布尔值时      |
| `ResolvedReference` | `ConvaiActionParameterReference` | 当文本命名了一个目标时，匹配到的作者定义目标； `null` 否则返回  |
| `IsConstraintMatch` | `bool`                           | `false` 仅当 `Choice` 参数文本不是其作者定义选项之一时 |
| `Presence`          | `ConvaiActionParameterPresence`  | Convai Character 是否为此参数提供了值          |

通过以下方式读取参数 `ConvaiActionInvocation.TryGetParameter`, `GetString`, `GetNumber`, `GetBool`，或 `GetReference` 而不是索引访问 `ConvaiActionCommand.Parameters` 。

### `ConvaiActionParameterPresence`

`Convai.Shared.Types`

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

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

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

### `ConvaiActionParameterReference`

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

名称和值类型共同构成一个 `引用` 参数在增强过程中被解析为的内容。

| 属性     | 类型                       | 说明                              |
| ------ | ------------------------ | ------------------------------- |
| `名称`   | `string`                 | 原始值匹配到的作者定义目标名称（已修剪，绝不为 `null`) |
| `Kind` | `ConvaiActionTargetKind` | 名称是否匹配到作者定义的对象或角色               |

`ConvaiActionParameterReference` 是查找键，不是场景绑定——它不包含 `GameObjectReference`。将其解析为一个活动的 `GameObject` 到 `ConvaiActionInvocation.GetReference(name)`，它返回一个 `ConvaiResolvedActionTarget`.

### `ConvaiActionConfig`

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

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

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

### `ConvaiActionConfigPatch`

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

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

| 属性                       | 类型                                      | 说明              |
| ------------------------ | --------------------------------------- | --------------- |
| `动作`                     | `List<string>`                          | 替换动作列表          |
| `角色`                     | `List<ConvaiActionCharacterDefinition>` | 替换角色目标列表        |
| `对象`                     | `List<ConvaiActionObjectDefinition>`    | 替换对象目标列表        |
| `CurrentAttentionObject` | `string`                                | 在列表替换后解析得到的关注更新 |

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

### `ConvaiActionObjectDefinition`

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

| 属性                    | 类型             | 已序列化                    | 说明                                                  |
| --------------------- | -------------- | ----------------------- | --------------------------------------------------- |
| `名称`                  | `string`       | 是（`"name"`)             | 在动作命令中使用的标识符。大小写不敏感匹配                               |
| `说明`                  | `string`       | 是（`"description"`)      | 发送给 Convai 以用于引用解析的自然语言描述                           |
| `GameObjectReference` | `GameObject`   | **没有** (`[JsonIgnore]`) | 本地场景引用。绝不发送给 Convai                                 |
| `仅文本`                 | `bool`         | **没有** (`[JsonIgnore]`) | 声明此条目有意没有 `GameObjectReference`。如果没有它，缺失引用会被报告为设置错误 |
| `别名`                  | `List<string>` | **没有** (`[JsonIgnore]`) | 解析层级会精确匹配的备用名称（第 2 步），然后才进入规范化/包含式匹配                |
| `InteractionPoint`    | `Transform`    | **没有** (`[JsonIgnore]`) | 要移动到或瞄准的显式点。当 `GameObjectReference`时，回退到 `null`     |
| `可用`                  | `bool`         | **没有** (`[JsonIgnore]`) | 本地解析开关， `true` 默认开启。不可用条目会被解析层级跳过                   |

### `ConvaiActionCharacterDefinition`

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

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

### `ConvaiActionTarget`

`Convai.Runtime.Actions` — `MonoBehaviour`

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

将任何 `GameObject` 标记为运行时动作锚定目标，无需代码。启用后，它对所选角色的合并动作配置可见，并会像作者定义的对象或角色一样参与解析层级，区别只是同名的作者定义条目总是优先。

| 属性                   | 类型                             | 说明                                                    |
| -------------------- | ------------------------------ | ----------------------------------------------------- |
| `TargetName`         | `string`                       | 解析层级匹配的目标名称。空白时默认为此 `GameObject`的名称                   |
| `Kind`               | `ConvaiActionTargetKind`       | 这是否是一个可执行的对象或角色                                       |
| `说明`                 | `string`                       | 发送给 Convai 用于锚定（Object 类型）                            |
| `简介`                 | `string`                       | 发送给 Convai 用于锚定（Character 类型）                         |
| `别名`                 | `List<string>`                 | 解析层级精确匹配的备用名称（第 2 步）                                  |
| `InteractionPoint`   | `Transform`                    | 可选的显式移动或瞄准点                                           |
| `ApplyTo`            | `ConvaiActionTargetApplyScope` | 启用时哪些角色会注册此目标： `AllCharacters` 或 `SpecificCharacters` |
| `SpecificCharacters` | `List<ConvaiCharacter>`        | 要注册到的角色，当 `ApplyTo` 是 `SpecificCharacters`            |
| `RegisterOnEnable`   | `bool`                         | 目标是否在启用时注册、在禁用时注销。默认 `true`                           |

### 内置执行器类型

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

| 执行器                                    | 菜单路径                                   | 备注                                                                       |
| -------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
| `ConvaiLeadPlayerActionExecutor`       | `Convai/Actions/Lead Player To Target` | Body Animation 包；需要一个 `ConvaiNavMeshLocomotion` peer                     |
| `ConvaiScanEnvironmentActionExecutor`  | `Convai/Actions/Scan Environment`      | Gaze 包；需要一个 `ConvaiGazeController` peer                                  |
| `ConvaiCountTargetGroupActionExecutor` | `Convai/Actions/Count Target Group`    | Observation 包；需要一个 `ConvaiActionTargetGroup` 在解析后的目标上；返回 `Answered(...)` |
| `ConvaiMeasureDistanceActionExecutor`  | `Convai/Actions/Measure Distance`      | Observation 包；不需要配对对象；返回 `Answered(...)`                                 |

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

### `ConvaiActionDispatcher`

`MonoBehaviour` — `Convai.Runtime.Actions`

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

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

#### 属性

| 属性                           | 类型                                 | 说明                                                                            |
| ---------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
| `BatchPolicy`                | `ConvaiActionBatchPolicy`          | 当前批处理策略（代码中只读；在 Inspector 中设置）                                                |
| `FailurePolicy`              | `ConvaiActionBatchFailurePolicy`   | 当前失败策略（代码中只读；在 Inspector 中设置）                                                 |
| `IsBusy`                     | `bool`                             | 当前是否有批次正在执行                                                                   |
| `PendingBatchCount`          | `int`                              | 排在当前批次后面的批次数量                                                                 |
| `CurrentActionName`          | `string`                           | 当前正在执行的动作显示名称，或为空                                                             |
| `CancelOnUserSpeech`         | `bool`                             | 启用后，当玩家开始说话时，调度器会立即取消正在执行的批次并清空队列。默认关闭                                        |
| `EnablePerformanceReactions` | `bool`                             | 批次/步骤生命周期是否通知 `IActionPerformanceReactor` 同伴（Gaze、Body Language、Emotion）。默认开启 |
| `OnBatchStarted`             | `UnityEvent`                       | 当一个批次开始执行时触发                                                                  |
| `OnStepStarted`              | `ConvaiActionInvocationUnityEvent` | 每个动作步骤开始时触发                                                                   |
| `OnStepSucceeded`            | `ConvaiActionInvocationUnityEvent` | 当执行器返回时触发 `成功` 或 `Answered`                                                   |
| `OnStepFailed`               | `ConvaiActionInvocationUnityEvent` | 当某一步失败时触发（Failed、Canceled 或 TimedOut）                                         |
| `OnStepUnhandled`            | `ConvaiActionInvocationUnityEvent` | 当执行器返回时触发 `未处理`                                                               |
| `OnStepCompleted`            | `ConvaiActionStepReportUnityEvent` | 每一步结束后触发，无论成功与否，附带完整的 `ConvaiActionStepReport`                                |
| `OnBatchCompleted`           | `UnityEvent`                       | 当所有批次步骤都完成且批次未被中止时触发                                                          |
| `OnBatchAborted`             | `UnityEvent`                       | 触发条件： `StopBatch` 策略会在失败后提前结束批次                                               |
| `OnCancelledByUserSpeech`    | `事件 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)`

#### 属性

| 属性                       | 类型                                               | 说明                                                                      |
| ------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------- |
| `Definitions`            | `IReadOnlyList<ConvaiActionDefinition>`          | 作者定义的内联动作定义列表                                                           |
| `ActionSets`             | `IReadOnlyList<ConvaiActionSet>`                 | 可复用的动作集资源，优先合并到 `Definitions`之前；内联定义在与任何集合名称冲突时总是获胜                     |
| `对象`                     | `IReadOnlyList<ConvaiActionObjectDefinition>`    | 作者定义的可执行对象列表                                                            |
| `角色`                     | `IReadOnlyList<ConvaiActionCharacterDefinition>` | 作者定义的可执行角色列表                                                            |
| `InitialAttentionObject` | `string`                                         | 在连接时预先设为 NPC 关注点的对象名称                                                   |
| `ActionExecutionMode`    | `ConvaiActionExecutionMode`                      | 声明由 `ConvaiActionDispatcher` 或自定义代码来运行此角色的动作。运行时不改变任何内容；供 SDK 自身的设置检查使用 |
| `BehaviorHost`           | `GameObject`                                     | 新建作者动作行为被添加到的对象：分配的子对象，或在未分配时添加到角色本身                                    |

#### 方法

| 方法                  | 签名                                       | 说明                                                                |
| ------------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| `BuildActionConfig` | `ConvaiActionConfig BuildActionConfig()` | 构建并返回连接时载荷。如果不存在有效定义，则返回 `null` 在此角色上运行命令。默认；设置检查在此模式下会期望有一个调度器组件 |

### `ConvaiActionExecutionMode`

`Convai.Runtime.Components`

| 值                        | 整数  | 说明                                                                                                                                 |
| ------------------------ | --- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `ConvaiActionDispatcher` | `0` | 随附的 `ConvaiActionDispatcher` on this character runs the commands. Default; setup checks expect a dispatcher component in this mode |
| `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` 上的 `GameObject`，或 `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`.

| 属性               | 类型                            | 说明                         |
| ---------------- | ----------------------------- | -------------------------- |
| `Invocation`     | `ConvaiActionInvocation`      | 报告所描述的调用                   |
| `Result`         | `ConvaiActionExecutionResult` | 该步骤的原始执行器结果                |
| `FailureReason`  | `ConvaiActionFailureReason`   | 透传给 `Result.FailureReason` |
| `BatchAborted`   | `bool`                        | 此步骤是否中止了剩余批次               |
| `Message`        | `string`                      | 成功详情，或非成功状态下的失败消息          |
| `FailureMessage` | `string`                      | 包含批次后果的失败详情。成功时为空          |

### 枚举

动作系统的其余枚举，按此处分组供参考。

#### `ConvaiActionBatchPolicy`

`Convai.Runtime.Actions`

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

#### `ConvaiActionBatchFailurePolicy`

`Convai.Runtime.Actions`

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

#### `ConvaiActionTargetRequirement`

`Convai.Runtime.Actions`

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

#### `ConvaiActionFailurePolicyOverride`

`Convai.Runtime.Actions`

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

#### `ConvaiActionTargetKind`

`Convai.Shared.Types`

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

#### `ConvaiActionParameterType`

`Convai.Shared.Types`

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

#### `ConvaiActionExecutionStatus`

`Convai.Runtime.Actions`

| 值        | 整数  | 调度器事件已触发          |
| -------- | --- | ----------------- |
| `成功`     | `0` | `OnStepSucceeded` |
| `Failed` | `1` | `OnStepFailed`    |
| `已取消`    | `2` | `OnStepFailed`    |
| `超时`     | `3` | `OnStepFailed`    |
| `未处理`    | `4` | `OnStepUnhandled` |

### `ConvaiActionInvocationUnityEvent`

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

使其可序列化的包装类型 `ConvaiActionInvocation` 可作为 UnityEvent 参数进行序列化。在 Inspector 中像标准 UnityEvent 一样分配处理程序。该事件的唯一参数是 `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 字段参考和使用指南。

#### 上下文菜单操作

| 命令       | 效果                                              |
| -------- | ----------------------------------------------- |
| `注入测试批次` | 提交一个 `移动到` 将针对第一个已注册对象的命令提交给调度器。在没有实时对话的情况下测试管道 |
| `重置探针状态` | 将所有计数器和文本字段重置为零/空                               |

### 下一步

{% 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 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/actions-scripting-reference.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.