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

# 配置角色动作

`ConvaiActionConfigSource` 是 Inspector 的编写界面，用于配置 Convai 在连接时需要了解的有关你的 NPC 动作能力的一切：允许哪些动作、后端可引用哪些场景对象、哪些角色可被选为目标，以及哪个对象是 NPC 的初始关注点。将它添加到任何 `GameObject` 已经具有 `ConvaiCharacter` ——或者使用 [Actions 编辑器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-editor.md)，它通过专用窗口编写同一组件。使用 `ConvaiActionConfigPatch` 在会话已经开始后更改这些可供性。

### 组件概览

| 属性       | 值                                                                |
| -------- | ---------------------------------------------------------------- |
| **菜单路径** | `添加组件 → Convai → Convai Actions`                                 |
| **命名空间** | `Convai.Runtime.Components`                                      |
| **约束**   | `DisallowMultipleComponent`, `RequireComponent(ConvaiCharacter)` |

该组件包含以下 Inspector 部分：

| 部分        | 目的                              |
| --------- | ------------------------------- |
| **动作定义**  | 可复用的动作集，与将后端动作名称映射到执行器组件的内联定义合并 |
| **可操作对象** | 后端可将其引用为动作目标的场景对象               |
| **可操作角色** | 后端可将其引用为动作目标的其他角色               |
| **初始注意力** | NPC 在每次会话开始时聚焦的对象名称             |

另外两个设置—— **动作由以下方式运行** 以及动作行为对象——都在 Actions Editor 的 **角色设置** 选项卡中编写，而不是显示在 `请求头` 在原始 Inspector 中；参见 [动作行为所在位置](#where-action-behaviors-live) 如下。

### 动作定义

中的每一项 **动作定义** 列表将一个后端动作名称绑定到一个 Unity 执行器组件。定义来自两个来源，并按以下顺序合并：可复用的 **动作集** (`ConvaiActionSet` 资源，在 **动作集** 列表中分配）优先，然后是 **内联定义** 列表。内联定义在与任何动作集发生同名冲突时总是优先生效；较早的动作集优先于较晚的动作集。

#### 动作定义字段

| 字段                      | 类型                                  | 描述                                                                                                                                                                         |
| ----------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ActionName`            | `string`                            | Convai 选择此动作时发送的名称。运行时不区分大小写；空格有意义。                                                                                                                                        |
| `描述`                    | `string`                            | 发送给 Convai 的简短句子，以便角色理解该动作的作用以及何时使用它。                                                                                                                                      |
| `TargetRequirement`     | `ConvaiActionTargetRequirement`     | 此动作是否需要目标，以及需要哪种目标。                                                                                                                                                        |
| `执行器`                   | `MonoBehaviour`                     | 执行该行为的组件。必须实现 `IConvaiActionExecutor`.                                                                                                                                     |
| `TimeoutSeconds`        | `float`                             | 执行器在被自动取消前可运行的最长秒数。 `0` = 无超时。                                                                                                                                             |
| `FailurePolicyOverride` | `ConvaiActionFailurePolicyOverride` | 针对单个动作覆盖调度器的批处理失败策略。默认值为 `UseDispatcherDefault`.                                                                                                                           |
| `AnswerDelivery`        | `ConvaiActionAnswerDelivery`        | 角色如何处理此动作返回的答案（参见 [动作执行器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md)）。仅对返回 `ConvaiActionExecutionResult.Answered`. |
| `已启用`                   | `布尔值`                               | 是否将此动作告知 Convai。默认值为 `true`。禁用的动作会从连接载荷和任何会话中重新同步中排除；对应的过期后端命令会被报告为未处理，而不是执行。                                                                                              |

#### 目标要求值

| 值    | 含义             |
| ---- | -------------- |
| `无`  | 动作不引用目标对象或角色   |
| `对象` | 动作需要一个已解析的对象目标 |
| `角色` | 动作需要一个已解析的角色目标 |
| `任一` | 动作可接受对象或角色作为目标 |

一个执行器组件可以服务多个动作定义。添加具有不同 `ActionName` 值但相同的 `执行器` 引用，当相同行为适用于多个后端命令时。

重复 `ActionName` 同一列表中的值会在运行时静默去重。保留第一项；后续重复项会被丢弃，并在控制台发出警告。名称比较时不区分大小写。

### 动作行为所在位置

默认情况下，动作执行器 `GameObject` 当前 `ConvaiCharacter` ——设置流程和每个示例都使用这种布局，并且它适用于任意数量的行为。一个大量使用随附 [动作执行器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md) 库的角色可能会有二十个或更多组件，这时将它们移动到子对象可以让角色自己的 Inspector 保持可读。

若要采用子级布局，请将子级 `Transform` 分配给…上的动作行为对象字段 `ConvaiActionConfigSource` （在 Actions Editor 的 **角色设置** 选项卡中编写）。Convai 无论哪种方式都能找到行为——两种布局都可以，而且某个角色在两个位置各有一些行为时也会完全相同地运行，因为行为是通过搜索整个角色层级来定位的。

同一个 **角色设置** 选项卡还包含 **动作由以下方式运行** (`ConvaiActionExecutionMode`): `Convai 动作运行器` （默认）会告诉 SDK 的设置检查预期存在一个 `ConvaiActionDispatcher` 在此角色上； `自定义代码` 告诉它们由你自己的脚本处理 `ConvaiCharacter.OnActionsReceived` 或 `ConvaiManager.Events.OnCharacterActionReceived` 取而代之。该设置是声明式的——不会在运行时改变任何内容——因此它仅用于告诉设置检查，缺少调度器是错误还是你的刻意设计。

### 可操作对象

中的每一项 **可操作对象** 会将一个场景对象注册为后端的有效目标。

#### 对象定义字段

| 字段                    | 类型             | 描述                                                                                              |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `名称`                  | `string`       | Convai 在动作命令中用于引用该对象的标识符。运行时匹配不区分大小写。                                                           |
| `描述`                  | `string`       | 发送给 Convai 的自然语言描述。用于自然语言指代解析（“墙边的盒子”）。请写成完整句子，描述类型、颜色、位置和用途。                                   |
| `GameObjectReference` | `GameObject`   | 运行时要交互的场景对象。 **仅限本地——绝不会发送给 Convai。**                                                           |
| `仅文本`                 | `布尔值`          | 当场景中没有任何内容对应此项时勾选。Convai 仍然知道这个名称并可以谈论它，但永远不会尝试对它执行操作。 **仅限本地。**                                |
| `别名`                  | `List<string>` | 额外的本地措辞，也应匹配此项（例如 `lamp` 对于一个名为 `Lantern`）。名称和近似措辞本身已经能匹配。 **仅限本地——绝不会发送给 Convai。**             |
| `交互点`                 | `Transform`    | 角色在对该对象执行动作后最终到达的位置。留空则使用对象自身的 transform；将其指向一个小的空 `Transform` 以获得更精确的位置（例如在门前而不是门内）。 **仅限本地。** |

`GameObjectReference`, `仅文本`, `别名`，以及 `交互点` 被标记为 `[JsonIgnore]`。只有 `名称` 和 `描述` 会序列化到连接载荷中。Convai 通过名称解析目标；Unity 将该名称映射到你的 `GameObject` 以及其交互点到本地。

**撰写有效描述：**

|          | 示例                          |
| -------- | --------------------------- |
| **过于模糊** | `场景中的一个对象`                  |
| **好**    | `安装在主工作台左侧墙上的红色便携式 CO2 灭火器` |
| **好**    | `位于工地入口附近设备架上的黄色安全帽`        |

描述在连接时固定。如果场景对象的状态在会话中途发生变化（移动、替换），Convai 已持有的描述不会自动更新。对于动态场景，请使用连接时覆盖或运行时补丁（见下文）。

### 可操作角色

中的每一项 **可操作角色** 将另一个 NPC 注册为后端的有效目标。

#### 角色定义字段

| 字段                    | 类型             | 描述                                                               |
| --------------------- | -------------- | ---------------------------------------------------------------- |
| `名称`                  | `string`       | Convai 用于引用该角色的标识符。                                              |
| `简介`                  | `string`       | 发送给 Convai 的简短描述。帮助后端在做目标决策时理解该角色是谁（例如，“负责设备检查的工地安全主管”）。         |
| `GameObjectReference` | `GameObject`   | 该角色的 `GameObject`. **仅限本地——绝不会发送给 Convai。**                      |
| `仅文本`                 | `布尔值`          | 当场景中没有任何内容对应此项时勾选。Convai 仍然知道这个名称并可以谈论它，但永远不会尝试对它执行操作。 **仅限本地。** |
| `别名`                  | `List<string>` | 额外的本地措辞，也应匹配此项（例如 `店主` 用于一个名为 `Mira`). **仅限本地——绝不会发送给 Convai。**  |
| `交互点`                 | `Transform`    | 角色在对该角色执行动作后最终到达的位置。留空则使用目标角色自身的 transform。 **仅限本地。**            |

两个 `ConvaiActionObjectDefinition` 和 `ConvaiActionCharacterDefinition` 还暴露一个运行时 `可用` 标志，由目标解析时参考，绝不会发送到后端——参见 [在运行时更新角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/update-actions-at-runtime.md) 了解会话中途补丁如何撤销或恢复目标。

### 初始注意力

当前交互目标的 **初始注意力** 字段接受一个单独的对象名称。会话开始时，Convai 将该对象视为 NPC 当前关注的焦点——它会在玩家第一次发言前预先建立指代锚定。

{% hint style="warning" %}
如果其中的名称 **初始注意力** 与…中的任何条目都不匹配 **可操作对象** （不区分大小写），则该字段会被静默地从连接载荷中省略，并在控制台记录警告。请确认名称完全匹配。
{% endhint %}

### 会话生命周期

Inspector 中的动作配置会在会话开始时发送给 Convai 一次，并且在会话处于活动状态时不能通过编辑该组件来修改。若要在连接后更改可供性，请在会话开始前使用连接时覆盖，或在活动期间使用运行时补丁（见下文）。

{% hint style="warning" %}
对…所做的更改 `ConvaiActionConfigSource` 在 Play Mode 中不会生效，直到你结束会话并重新连接。
{% endhint %}

### 连接时的动态配置

对于程序生成场景或多层级游戏，如果动作目标在不同会话之间会变化，请通过以下方式覆盖 Inspector 配置： `RoomSessionConnectOptions` 在调用时 `ConnectAsync`.

提供两个独立的覆盖字段：

| 字段                          | 类型                             | 效果                                       |
| --------------------------- | ------------------------------ | ---------------------------------------- |
| `ActionConfigOverride`      | `ConvaiActionConfig`           | 替换发送给 Convai 的完整连接时可供性（动作名称、对象、角色、初始注意力） |
| `ActionDefinitionsOverride` | `List<ConvaiActionDefinition>` | 仅替换此会话的本地 Unity 执行器绑定                    |

{% tabs %}
{% tab title="两个覆盖项都" %}
当后端可供性和本地执行器绑定都应与 Inspector 配置不同时时使用：

```csharp
using System.Collections.Generic;
using Convai.Modules.BodyAnimation.Executors;
using Convai.Runtime.Actions;
using Convai.Runtime.Components;
using Convai.Runtime.Room;
using Convai.Shared.Actions;
using UnityEngine;

public sealed class DynamicActionSetup : MonoBehaviour
{
    [SerializeField] private ConvaiManager _manager;
    [SerializeField] private ConvaiWalkToActionExecutor _walkTo;

    public async void ConnectWithOverrides()
    {
        var options = new RoomSessionConnectOptions
        {
            ActionConfigOverride = new ConvaiActionConfig
            {
                Actions = new List<string> { "Walk To", "Pick Up" },
                Objects = new List<ConvaiActionObjectDefinition>
                {
                    new() { Name = "Helmet", Description = "设备架上的黄色安全帽" },
                    new() { Name = "Locker", Description = "出口附近的绿色金属储物柜" }
                },
                CurrentAttentionObject = "Helmet"
            },
            ActionDefinitionsOverride = new List<ConvaiActionDefinition>
            {
                new()
                {
                    ActionName = "Walk To",
                    TargetRequirement = ConvaiActionTargetRequirement.Object,
                    Executor = _walkTo
                }
            }
        };

        await _manager.ConnectAsync(options);
    }
}
```

{% endtab %}

{% tab title="仅配置覆盖" %}
当后端可供性需要更改但 Inspector 的本地执行器绑定仍然正确时使用：

```csharp
var options = new RoomSessionConnectOptions
{
    ActionConfigOverride = new ConvaiActionConfig
    {
        Actions = new List<string> { "Walk To" },
        Objects = BuildObjectListFromCurrentLevel()
    }
};

await _manager.ConnectAsync(options);
```

{% endtab %}
{% endtabs %}

`ActionDefinitionsOverride` 会依据 `ActionConfigOverride.Actions`。只有其 `ActionName` 出现在配置的动作列表中的定义才会在该会话中激活。未列出的动作名称对应的定义会被静默忽略。

### 在活动会话中更新动作

在会话已经开始后，要更改动作、对象、角色或当前注意对象，请应用一个 `ConvaiActionConfigPatch` 通过 `ConvaiCharacter.DynamicContext.Apply`。与连接时的 `ConvaiActionConfig`不同，补丁只会影响你设置的字段：被省略的（`null`）字段会保留会话当前值，而显式的空列表或空字符串会清除该字段。补丁在 Convai 确认之前不会生效。

参见 [在运行时更新角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/update-actions-at-runtime.md) 有关完整的补丁字段语义、一个完整代码示例以及如何读取后端的确认，请参见。

### 下一步

{% content-ref url="/pages/4001c6ae3c6d4603942748007a37a67812bb7e9a" %}
[在运行时更新角色动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/update-actions-at-runtime.md)
{% endcontent-ref %}

{% content-ref url="/pages/5b02ee57da9de48585f7ea92aa9e94714547d80a" %}
[动作目标解析的工作方式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/attention-and-reference-grounding.md)
{% endcontent-ref %}

{% 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/6e3c85bad169c9c2c755b38be39008ef3ce023cf" %}
[分发器和批处理策略](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/dispatcher-and-batch-policies.md)
{% endcontent-ref %}

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