> 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.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)` — `Unhandled` ，默认情况下——不会调用 `ExecuteCoreAsync`。将 `RequiresTarget => false` 用于无目标动作（例如脚本化的头部动作）。

| 成员                                              | 类型                                              | 描述                                                                                                             |
| ----------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `MissingTargetResult(invocation)`               | `protected virtual ConvaiActionExecutionResult` | 当所需目标缺失时返回的结果。可重写为返回 `Failed(..., ConvaiActionFailureReason.TargetMissing)` 而不是默认的 `Unhandled`                 |
| `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`         | 构建一个 `Unhandled` 类型为 `T`的缺失同伴结果，并且每个组件实例只记录一次日志                                                                |
| `GetOverride(invocation, name, defaultValue)`   | `protected static float`/`bool`/`string`        | 读取一个调用参数覆盖值；当其缺失或 `调用` 为 `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` 的公共字段和属性按参数名绑定（支持的成员类型： `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`.

#### 属性

| 属性              | 类型                            | 描述                                                        |
| --------------- | ----------------------------- | --------------------------------------------------------- |
| `Status`        | `ConvaiActionExecutionStatus` | 本次执行步骤的结果                                                 |
| `消息`            | `string`                      | 可选诊断详情。会显示在控制台、Actions Editor 以及你的游戏代码中——绝不会显示给 Convai 角色 |
| `Answer`        | `string`                      | 此动作发现的内容，写成一句角色可以大声说出的普通句子。对于执行可见动作而不是回答问题的动作留空           |
| `HasAnswer`     | `bool`                        | 此结果是否携带非空的 `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` 为 `Interrupted`      |
| `TimedOut`  | `static ConvaiActionExecutionResult TimedOut(string message = null)`                                                      | **请勿手动调用。** 当 `TimeoutSeconds` 过期时，分发器会自动返回此结果。 `FailureReason` 为 `Timeout` |
| `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`        | 执行器或其某个依赖项处于无法处理该请求的状态                                                                   |
| `Timeout`             | 该步骤超过了其定义的超时时间                                                                           |
| `Interrupted`         | 该步骤在完成前被中断（取消、替换或被覆盖）                                                                    |
| `Custom`              | 任何其他仅通过 `消息`                                                                             |
| `TargetNotActionable` | 目标已解析，但缺少此动作需要对其执行操作的组件（参见 `RequiredTargetComponent` 在 `ConvaiActionArchetypeAttribute`) |
| `Busy`                | 角色现在无法接受该请求，因为它正在执行会占用其同一部分的事情；稍后同样的请求通常会成功                                              |

### `ConvaiActionDefinition`

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

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

#### 字段和属性

| 成员                           | 类型                                      | 描述                                                                                                                    |
| ---------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `ActionName`                 | `string`                                | 用于与后端命令匹配的动作名称（不区分大小写）                                                                                                |
| `描述`                         | `string`                                | 发送给 Convai 以用于 grounding 的可选描述                                                                                        |
| `Parameters`                 | `List<ConvaiActionParameterDefinition>` | 按顺序排列的类型化参数，渲染到传输模板中                                                                                                  |
| `TargetRequirement`          | `ConvaiActionTargetRequirement`         | 此动作需要哪种类型的目标                                                                                                          |
| `Executor`                   | `MonoBehaviour`                         | 执行该行为的组件。必须实现 `IConvaiActionExecutor`。这里的显式引用始终优先于 `ExecutorTypeHint`                                                 |
| `ExecutorTypeHint`           | `string`                                | 可选的执行器简短或完整类型名 `IConvaiActionExecutor` ，在角色层级中自动绑定 `Executor` 为 `null` ——用于编写在 `ConvaiActionSet` 资源内部的定义，因为资源无法保存场景引用 |
| `TimeoutSeconds`             | `float`                                 | 以秒为单位的最大执行时间。 `0` 或更小则会禁用超时                                                                                           |
| `FailurePolicyOverride`      | `ConvaiActionFailurePolicyOverride`     | 按动作覆盖分发器的批处理失败策略                                                                                                      |
| `AnswerDelivery`             | `ConvaiActionAnswerDelivery`            | 角色如何处理一个 `Answered(...)` 结果。仅用于编写——绝不会发送给 Convai                                                                      |
| `WaitForBotSpeech`           | `bool`                                  | 新批次的第一步是否等待角色说话                                                                                                       |
| `DelayAfterBotSpeechSeconds` | `float`                                 | 在语音门控释放后的可选延迟                                                                                                         |
| `类别`                         | `string` (property)                     | 在 Actions Editor 中该动作所属的可选编写标签。仅用于组织——不发送给 Convai                                                                     |
| `Enabled`                    | `bool` (property)                       | 编写时的可用性。被禁用的动作会从 `action_config` 发送给 Convai。默认为 `true`                                                                |

#### 方法

| 方法                     | 签名                              | 描述                       |
| ---------------------- | ------------------------------- | ------------------------ |
| `ToActionConfigString` | `string ToActionConfigString()` | 渲染发送给 Convai 的此定义传输模板字符串 |

### `ConvaiActionAnswerDelivery`

`Convai.Runtime.Actions`

Convai 角色对 `Answer` 执行后返回的 **完成时**.

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

### `ConvaiActionParameterDefinition`

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

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

| 字段          | 类型                          | 描述                                     |
| ----------- | --------------------------- | -------------------------------------- |
| `Name`      | `string`                    | 作为传输键和模板锚点的参数名                         |
| `描述`        | `string`                    | 发送给 Convai 以用于 grounding 的可选描述         |
| `类型`        | `ConvaiActionParameterType` | 声明的参数类型。 `自动` 从值中推断。默认 `自动`            |
| `Connector` | `string`                    | 在传输模板中出现在参数前的可选连接词（例如 `“on”` 或 `“in”`) |
| `Choices`   | `List<string>`              | 允许的值，当 `类型` 为 `Choice`                 |

### `ConvaiActionInvocation`

`Convai.Runtime.Actions` — 密封类

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

#### 属性

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

#### 方法

| 方法                | 签名                                                                        | 描述                                          |
| ----------------- | ------------------------------------------------------------------------- | ------------------------------------------- |
| `TryGetParameter` | `bool TryGetParameter(string name, out ConvaiActionParameterValue value)` | 尝试按名称读取一个有类型的参数（不区分大小写）                     |
| `GetString`       | `string GetString(string name, string fallback = "")`                     | 读取字符串参数，并在缺失时返回 `回退值` 时                     |
| `GetNumber`       | `float GetNumber(string name, float fallback = 0f)`                       | 读取数值参数，并在以下情况下返回 `回退值` 时                    |
| `GetBool`         | `bool GetBool(string name, bool fallback = false)`                        | 读取布尔参数，并在以下情况下返回 `回退值` 时                    |
| `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                                                                                           |
| `Name`                | `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` — 可序列化的密封类

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

#### 属性

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

#### 构造函数

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

构造函数会规范化 `Name` 和 `目标` 并从中派生 `ActionString` 。 `Parameters`, `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 角色是否为此参数提供了值                      |

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

### `ConvaiActionParameterPresence`

`Convai.Shared.Types`

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

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

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

### `ConvaiActionParameterReference`

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

名称和类型处理一个 `引用` 参数在增强过程中被解析成的结果。

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

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

### `ConvaiActionConfig`

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

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

| 属性           | 类型                                      | 描述                                            |
| ------------ | --------------------------------------- | --------------------------------------------- |
| `动作`         | `List<string>`                          | 此会话允许的动作名称。只发送名称——执行器绑定保持在本地                  |
| `对象`         | `List<ConvaiActionObjectDefinition>`    | 后端可将其作为目标引用的对象。 `GameObjectReference` 绝不会被序列化 |
| `Characters` | `List<ConvaiActionCharacterDefinition>` | 后端可将其作为目标引用的角色。 `GameObjectReference` 绝不会被序列化 |
| `当前注意对象`     | `string`                                | 初始注意对象名称。必须匹配 `对象`                            |

### `ConvaiActionConfigPatch`

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

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

| 属性           | 类型                                      | 描述              |
| ------------ | --------------------------------------- | --------------- |
| `动作`         | `List<string>`                          | 替换后的动作列表        |
| `Characters` | `List<ConvaiActionCharacterDefinition>` | 替换后的角色目标列表      |
| `对象`         | `List<ConvaiActionObjectDefinition>`    | 替换后的对象目标列表      |
| `当前注意对象`     | `string`                                | 列表替换后解析出的注意对象更新 |

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

### `ConvaiActionObjectDefinition`

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

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

### `ConvaiActionCharacterDefinition`

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

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

### `上的本地专用含义相同`

`Convai.Runtime.Actions` — `MonoBehaviour`

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

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

| 属性                 | 类型                             | 描述                                    |
| ------------------ | ------------------------------ | ------------------------------------- |
| `TargetName`       | `string`                       | 解析阶梯要匹配的目标名称。若为空，默认为此 `GameObject`的名称 |
| `类型`               | `ConvaiActionTargetKind`       | 这是否是一个可执行的对象或角色                       |
| `描述`               | `string`                       | 发送给 Convai 用于锚定（对象类型）                 |
| `简介`               | `string`                       | 发送给 Convai 用于锚定（角色类型）                 |
| `别名`               | `List<string>`                 | 解析阶梯精确匹配的备用名称（步骤 2）                   |
| `InteractionPoint` | `Transform`                    | 可选的显式点，用于移动到或朝向                       |
| `ApplyTo`          | `ConvaiActionTargetApplyScope` | 启用时，哪些角色会注册此目标： `所有角色` 或 `特定角色`       |
| `特定角色`             | `List<ConvaiCharacter>`        | 要注册到哪些角色上，当 `ApplyTo` 为 `特定角色`        |
| `启用时注册`            | `bool`                         | 目标是否在启用时注册、在禁用时注销。默认 `true`           |

### 内置执行器类型

此版本中已更改已发布的执行器目录。每个执行器的完整字段级参考请见 [动作执行器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md)；本节仅记录变更内容。

**新增：**

| Executor                               | 菜单路径                                   | 备注                                                            |
| -------------------------------------- | -------------------------------------- | ------------------------------------------------------------- |
| `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(...)`.

**移除：** `ConvaiGuidedTourActionExecutor`, `ConvaiAddressGroupActionExecutor`, `ConvaiPerformAtTargetActionExecutor` 已不再存在于 SDK 中。升级后，引用这些组件的场景会出现损坏引用；请将该动作重新绑定到内置或自定义替代项。参见 [将动作迁移到 v4.5.0](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/migrate-to-v4-5.md) 以了解升级路径。

### `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` 同伴（凝视、肢体语言、情绪）。默认开启 |
| `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>`                 | 可复用的动作集资源，在 `定义`之前合并；当名称冲突时，内联定义总是优先于任何集合                               |
| `对象`                     | `IReadOnlyList<ConvaiActionObjectDefinition>`    | 作者定义的可执行对象列表                                                            |
| `Characters`             | `IReadOnlyList<ConvaiActionCharacterDefinition>` | 作者定义的可执行角色列表                                                            |
| `InitialAttentionObject` | `string`                                         | 在连接时预先设为 NPC 关注点的对象名称                                                   |
| `ActionExecutionMode`    | `ConvaiActionExecutionMode`                      | 声明 `ConvaiActionDispatcher` 或自定义代码运行此角色的动作。运行时不会改变任何内容；仅供 SDK 自身的设置检查使用 |
| `BehaviorHost`           | `GameObject`                                     | 新增的动作行为被添加到的对象：分配的子对象，若未分配则为角色本身                                        |

#### 方法

| 方法                  | 签名                                       | 描述                                      |
| ------------------- | ---------------------------------------- | --------------------------------------- |
| `BuildActionConfig` | `ConvaiActionConfig BuildActionConfig()` | 构建并返回连接时载荷。若没有有效定义，则返回 `null` 如果不存在有效定义 |

### `ConvaiActionExecutionMode`

`Convai.Runtime.Components`

| 值                        | Integer | 描述                                                                                                |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
| `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` 在此 `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`.

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

### 枚举

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

#### `ConvaiActionBatchPolicy`

`Convai.Runtime.Actions`

| 值                | Integer | 描述                       |
| ---------------- | ------- | ------------------------ |
| `队列`             | `0`     | 新批次将等待当前批次完成。默认          |
| `ReplaceCurrent` | `1`     | 取消当前活动步骤和所有待处理批次；立即启动新批次 |
| `DropIncoming`   | `2`     | 在所有当前和排队的工作完成之前，丢弃新批次    |

#### `ConvaiActionBatchFailurePolicy`

`Convai.Runtime.Actions`

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

#### `ConvaiActionTargetRequirement`

`Convai.Runtime.Actions`

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

#### `ConvaiActionFailurePolicyOverride`

`Convai.Runtime.Actions`

| 值                      | Integer | 描述                                  |
| ---------------------- | ------- | ----------------------------------- |
| `UseDispatcherDefault` | `0`     | 遵循 `ConvaiActionDispatcher` 失败策略。默认 |
| `StopBatch`            | `1`     | 非成功结果会中止剩余批次                        |
| `ContinueBatch`        | `2`     | 非成功结果允许剩余批次继续                       |

#### `ConvaiActionTargetKind`

`Convai.Shared.Types`

| 值           | Integer | 描述       |
| ----------- | ------- | -------- |
| `无`         | `0`     | 未解析到目标   |
| `对象`        | `1`     | 目标是已注册对象 |
| `Character` | `2`     | 目标是已注册角色 |

#### `ConvaiActionParameterType`

`Convai.Shared.Types`

| 值        | Integer | 描述                                       |
| -------- | ------- | ---------------------------------------- |
| `自动`     | `0`     | 按顺序尽最大努力推断引用、数字、布尔值或字符串。默认               |
| `引用`     | `1`     | 按名称解析一个手工创建的对象或角色目标                      |
| `字符串`    | `2`     | 保留原始文本                                   |
| `数字`     | `3`     | 解析一个采用不变区域性格式的浮点数                        |
| `布尔值`    | `4`     | 解析 `true`/`是`/`1` 或 `false`/`否`/`0`      |
| `Choice` | `5`     | 必须是预设选项字符串之一。不匹配时会通过 `IsConstraintMatch` |

#### `ConvaiActionExecutionStatus`

`Convai.Runtime.Actions`

| 值           | Integer | 调度器事件已触发          |
| ----------- | ------- | ----------------- |
| `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 → 动作 → 诊断 → Convai 动作监视器`

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

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

#### 上下文菜单操作

| Command             | 效果                                                    |
| ------------------- | ----------------------------------------------------- |
| `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.