> 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` 命名空间，除非另有说明。

### ConvaiActionDispatcher

`MonoBehaviour` — `Convai.Runtime.Actions`

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

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

#### 属性

| 属性                 | 类型                                 | 说明                                   |
| ------------------ | ---------------------------------- | ------------------------------------ |
| `BatchPolicy`      | `ConvaiActionBatchPolicy`          | 当前批处理策略（代码中只读；在 Inspector 中设置）       |
| `FailurePolicy`    | `ConvaiActionBatchFailurePolicy`   | 当前失败策略（代码中只读；在 Inspector 中设置）        |
| `OnBatchStarted`   | `UnityEvent`                       | 当一个批次开始执行时触发                         |
| `OnStepStarted`    | `ConvaiActionInvocationUnityEvent` | 在每个动作步骤开始时触发                         |
| `OnStepSucceeded`  | `ConvaiActionInvocationUnityEvent` | 当执行器返回时触发 `成功`                       |
| `OnStepFailed`     | `ConvaiActionInvocationUnityEvent` | 当步骤失败时触发（Failed、Canceled 或 TimedOut） |
| `OnStepUnhandled`  | `ConvaiActionInvocationUnityEvent` | 当执行器返回时触发 `未处理`                      |
| `OnBatchCompleted` | `UnityEvent`                       | 当所有批处理步骤完成且批次未被中止时触发                 |
| `OnBatchAborted`   | `UnityEvent`                       | 当 `StopBatch` 策略在失败后提前终止批次时          |

#### 方法

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

### ConvaiActionConfigSource

`MonoBehaviour` — `Convai.Runtime.Components`

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

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

#### 属性

| 属性                       | 类型                                               | 说明                   |
| ------------------------ | ------------------------------------------------ | -------------------- |
| `Definitions`            | `IReadOnlyList<ConvaiActionDefinition>`          | 已编写的动作定义列表           |
| `Objects`                | `IReadOnlyList<ConvaiActionObjectDefinition>`    | 已编写的可动作对象列表          |
| `Characters`             | `IReadOnlyList<ConvaiActionCharacterDefinition>` | 已编写的可动作角色列表          |
| `InitialAttentionObject` | `string`                                         | 在连接时预先设为 NPC 焦点的对象名称 |

#### 方法

| 方法                  | 签名                                                                                        | 说明                                  |
| ------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------- |
| `BuildActionConfig` | `ConvaiActionConfig BuildActionConfig()`                                                  | 构建并返回连接时的负载。如果没有有效定义，则返回 `null` 。   |
| `TryResolveObject`  | `bool TryResolveObject(string objectName, out ConvaiActionObjectDefinition actionObject)` | 按名称查找已注册对象（不区分大小写）。如果找到则返回 `true` 。 |

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

`MonoBehaviour` — `Convai.Runtime.Components`

#### 事件

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

#### 属性

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

#### 方法

| 方法                            | 签名                                                                                                   | 说明                                                      |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `GetActionConfigSource`       | `ConvaiActionConfigSource GetActionConfigSource()`                                                   | 返回 `ConvaiActionConfigSource` 在此 `GameObject`，或 `null`. |
| `SetCurrentAttentionObject`   | `void SetCurrentAttentionObject(string objectName, string runLlm = "false")`                         | 将后端的锚定更新为指定对象。需要处于活动对话中。如果对象名称不在当前活动动作配置中，则会被静默忽略。      |
| `SetCurrentAttentionObject`   | `void SetCurrentAttentionObject(ConvaiActionObjectDefinition actionObject, string runLlm = "false")` | 接受定义引用的重载。                                              |
| `ClearCurrentAttentionObject` | `void ClearCurrentAttentionObject(string runLlm = "false")`                                          | 清除当前注意对象。需要处于活动对话中。                                     |

### RoomSessionConnectOptions — 动作字段

`Convai.Runtime.Room`

| 字段                          | 类型                             | 说明                                                                          |
| --------------------------- | ------------------------------ | --------------------------------------------------------------------------- |
| `ActionConfigOverride`      | `ConvaiActionConfig`           | 设置后，将替换 `ConvaiActionConfigSource.BuildActionConfig()` 在此会话中的结果。            |
| `ActionDefinitionsOverride` | `List<ConvaiActionDefinition>` | 设置后，将替换此会话的 Inspector 动作定义。如果两者都设置，则会按 `ActionConfigOverride.Actions` 进行过滤。 |

### ConvaiActionCommand

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

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

#### 属性

| 属性          | 类型       | 说明                                 |
| ----------- | -------- | ---------------------------------- |
| `名称`        | `string` | 必需。由后端选择的动作名称（例如， `"Move To"`).    |
| `目标`        | `string` | 可选。后端解析为目标的对象或角色名称。 `null` 如果没有目标。 |
| `HasTarget` | `bool`   | `true` 当 `目标` 非空时。                 |

#### 构造函数

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

### ConvaiActionConfig

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

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

#### 属性

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

### ConvaiActionDefinition

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

后端动作名称与执行器组件之间的本地 Unity 绑定。只有 `动作名称` 会发送到后端。

#### 字段

| 字段               | 类型                              | 说明                                     |
| ---------------- | ------------------------------- | -------------------------------------- |
| `动作名称`           | `string`                        | 映射到此定义的动作名称。运行时不区分大小写匹配。               |
| `目标要求`           | `ConvaiActionTargetRequirement` | 此动作需要哪种目标。                             |
| `执行器`            | `MonoBehaviour`                 | 执行该行为的组件。必须实现 `IConvaiActionExecutor`. |
| `TimeoutSeconds` | `float`                         | 最大执行时间（秒）。 `0` = 无超时。                  |

### ConvaiActionObjectDefinition

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

#### 属性

| 属性                    | 类型           | 已序列化                    | 说明                        |
| --------------------- | ------------ | ----------------------- | ------------------------- |
| `名称`                  | `string`     | 是（`"name"`)             | 在动作命令中使用的标识符。匹配时不区分大小写。   |
| `说明`                  | `string`     | 是（`"description"`)      | 发送给 Convai 用于引用解析的自然语言描述。 |
| `GameObjectReference` | `GameObject` | **没有** (`[JsonIgnore]`) | 本地场景引用。绝不发送给 Convai。      |

### ConvaiActionCharacterDefinition

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

#### 属性

| 属性                    | 类型           | 已序列化                    | 说明                             |
| --------------------- | ------------ | ----------------------- | ------------------------------ |
| `名称`                  | `string`     | 是（`"name"`)             | 此角色目标的标识符。                     |
| `Bio`                 | `string`     | 是（`"bio"`)              | 发送给 Convai 的简短描述（例如，“场地安全主管”）。 |
| `GameObjectReference` | `GameObject` | **没有** (`[JsonIgnore]`) | 本地场景引用。绝不发送给 Convai。           |

### ConvaiActionInvocation

`Convai.Runtime.Actions` — 密封类

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

#### 属性

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

### ConvaiResolvedActionTarget

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

单个动作步骤的解析目标。

#### 属性

| 属性                    | 类型                                | 说明                                       |
| --------------------- | --------------------------------- | ---------------------------------------- |
| `种类`                  | `ConvaiActionTargetKind`          | 解析后的目标是 Object、Character 还是 None。        |
| `名称`                  | `string`                          | 解析出的名称（来自后端命令）。                          |
| `ObjectBinding`       | `ConvaiActionObjectDefinition`    | 匹配到的对象定义。 `null` 如果 `Kind != Object`.    |
| `CharacterBinding`    | `ConvaiActionCharacterDefinition` | 匹配到的角色定义。 `null` 如果 `Kind != Character`. |
| `GameObjectReference` | `GameObject`                      | 场景 `GameObject` 来自匹配绑定。在执行器中是主要访问点。      |

### ConvaiActionExecutionResult

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

返回类型，适用于 `IConvaiActionExecutor.ExecuteAsync`.

#### 属性

| 属性          | 类型                            | 说明                       |
| ----------- | ----------------------------- | ------------------------ |
| `Status`    | `ConvaiActionExecutionStatus` | 此执行步骤的结果。                |
| `消息`        | `string`                      | 可选的人类可读详情。在事件处理程序和日志中可用。 |
| `Exception` | `Exception`                   | 导致失败的异常（如果有）。            |

#### 工厂方法

| 方法         | 签名                                                                                             | 何时使用                               |
| ---------- | ---------------------------------------------------------------------------------------------- | ---------------------------------- |
| `成功`       | `static ConvaiActionExecutionResult Succeeded()`                                               | 行为已成功完成。                           |
| `失败`       | `static ConvaiActionExecutionResult Failed(string message = null, Exception exception = null)` | 发生了真实错误。                           |
| `Canceled` | `static ConvaiActionExecutionResult Canceled()`                                                | 该 `CancellationToken` 已发出信号。       |
| `超时`       | `static ConvaiActionExecutionResult TimedOut()`                                                | **不要手动调用。** 当 `TimeoutSeconds` 超时。 |
| `未处理`      | `static ConvaiActionExecutionResult Unhandled(string message = null)`                          | 此执行器有意拒绝该调用。                       |

### IConvaiActionExecutor

`Convai.Runtime.Actions` — 接口

所有动作行为的扩展点。实现于任何 `MonoBehaviour`.

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

### 枚举

#### ConvaiActionBatchPolicy

`Convai.Runtime.Actions`

| 值                | 整数  | 说明                        |
| ---------------- | --- | ------------------------- |
| `Queue`          | `0` | 新的批次会等待当前批次完成。默认。         |
| `ReplaceCurrent` | `1` | 取消当前活动步骤和所有待处理批次；立即开始新批次。 |
| `DropIncoming`   | `2` | 丢弃新批次，直到所有当前和排队中的工作完成。    |

#### ConvaiActionBatchFailurePolicy

`Convai.Runtime.Actions`

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

#### ConvaiActionTargetRequirement

`Convai.Runtime.Actions`

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

#### ConvaiActionTargetKind

`Convai.Runtime.Actions`

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

#### ConvaiActionExecutionStatus

`Convai.Runtime.Actions`

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

### ConvaiActionInvocationUnityEvent

`Convai.Runtime.Actions` — 扩展自的可序列化类 `UnityEvent<ConvaiActionInvocation>`

包装类型，使 `ConvaiActionInvocation` 可作为 UnityEvent 参数进行序列化。像任何标准 UnityEvent 一样在 Inspector 中分配处理程序。事件的单个参数是 `ConvaiActionInvocation` 用于该步骤的。

### ConvaiActionDebugProbe

`Convai.Runtime.Actions` — 密封 `MonoBehaviour`

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

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

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

#### 上下文菜单操作

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

### 下一步

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

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.