> 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).

# 配置角色动作

配置 Convai NPC 可以使用哪些动作、对象和角色，然后在活动会话期间更新这些可供性。

`ConvaiActionConfigSource` 这是用于在检查器中配置 Convai 在连接时需要了解的 NPC 动作能力的界面：允许哪些动作、后端可引用哪些场景对象、哪些角色可作为目标，以及哪个对象是 NPC 的初始关注对象。将其添加到任何 `GameObject` 已拥有 `ConvaiCharacter` ——或者使用 [动作编辑器](/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)` |

该组件包含以下检查器部分：

| 部分                     | 作用                                |
| ---------------------- | --------------------------------- |
| **Action Definitions** | 可复用的动作集，与内联定义合并，用于将后端动作名称映射到执行器组件 |
| **Actionable Objects** | 后端可引用为动作目标的场景对象                   |
| **可执行动作的角色**           | 后端可引用为动作目标的其他角色                   |
| **Initial Attention**  | NPC 在每次会话开始时关注的对象名称               |

另外还有两个设置—— **动作由谁运行** 以及动作行为对象——都在动作编辑器的 **角色设置** 选项卡中配置，而不是以 `标题` 原始检查器中的 [形式显示；参见](#where-action-behaviors-live) 下文。

### 动作行为所在位置

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

#### 动作定义字段

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

#### 目标要求值

| 值           | 含义           |
| ----------- | ------------ |
| `None`      | 动作不引用目标对象或角色 |
| `Object`    | 动作需要已解析的对象目标 |
| `Character` | 动作需要已解析的角色目标 |
| `二者之一`      | 动作可接受对象或角色目标 |

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

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

### 形式显示；参见

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

若要采用子级布局，请将子级 `Transform` 分配给 `ConvaiActionConfigSource` 上动作行为对象字段（在动作编辑器的 **角色设置** 选项卡中配置）。Convai 无论哪种方式都能找到行为——两种布局，以及在两个位置都放有部分行为的角色，运行表现完全相同，因为行为是通过搜索整个角色层级来定位的。

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

### 可执行动作的对象

中的每一项都会 **Actionable Objects** 将一个场景对象注册为后端的有效目标。

#### 对象定义字段

| 字段                    | 类型             | 说明                                                                                             |
| --------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| `名称`                  | `string`       | Convai 在动作命令中用来引用此对象的标识符。运行时匹配不区分大小写。                                                          |
| `说明`                  | `string`       | 发送给 Convai 的自然语言描述。用于自然语言引用解析（"靠墙的盒子"）。请写成完整句子，描述类型、颜色、位置和用途。                                  |
| `GameObjectReference` | `GameObject`   | 运行时要交互的场景对象。 **仅本地使用——绝不会发送给 Convai。**                                                         |
| `TextOnly`            | `bool`         | 当场景中没有任何内容对应此条目时勾选。Convai 仍然知道该名称并可以谈论它，但绝不会尝试对它执行操作。 **仅本地使用。**                               |
| `Aliases`             | `List<string>` | 额外的本地表述，也应匹配此条目（例如 `lamp` 用于名为 `Lantern`）。名称和近似表述本身已经可以匹配。 **仅本地使用——绝不会发送给 Convai。**           |
| `InteractionPoint`    | `Transform`    | 角色对该对象执行动作后最终到达的位置。留空则使用对象自身的 transform；请将其指向一个小的空 `Transform` 对象以提高精度（例如在门前而不是门内）。 **仅本地使用。** |

`GameObjectReference`, `TextOnly`, `Aliases`，以及 `InteractionPoint` 被标记为 `[JsonIgnore]`。只有 `名称` 和 `说明` 会序列化到连接负载中。Convai 按名称解析目标；Unity 会将该名称映射到你的 `GameObject` 以及其本地交互点。

**撰写有效描述：**

|         | 示例                            |
| ------- | ----------------------------- |
| **太笼统** | `场景中的一个对象`                    |
| **良好**  | `一只红色便携式二氧化碳灭火器，安装在主工作台左侧的墙上` |
| **良好**  | `位于工地入口附近设备架上的黄色安全帽`          |

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

### 可执行动作的角色

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

#### 角色定义字段

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

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

### 初始关注

该 **Initial Attention** 字段接受一个对象名称。会话开始时，Convai 会将该对象视为 NPC 当前关注的焦点——它会在玩家首次回合之前预先建立引用锚定。

{% hint style="warning" %}
如果中的名称 **Initial Attention** 与中的任何条目 **Actionable Objects** （不区分大小写），该字段会被静默地从连接负载中省略，并在控制台记录警告。请确认名称完全匹配。
{% endhint %}

### 会话生命周期

检查器中的动作配置会在会话开始时发送给 Convai 一次，且在会话进行中无法通过编辑组件来修改。若要在连接后更改可供性，请在会话开始前使用连接时覆盖，或在会话进行时使用运行时补丁（见下文）。

{% hint style="warning" %}
对所做的更改 `ConvaiActionConfigSource` 在播放模式下不会生效，直到你结束会话并重新连接。
{% endhint %}

### 连接时的动态配置

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

可用两个独立的覆盖字段：

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

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

```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="仅配置覆盖" %}
当后端可供性需要更改，但检查器中的本地执行器绑定仍然正确时使用：

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