> 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` 是 Inspector 中的配置入口，用于设定 NPC 在连接时需要告知 Convai 的所有动作能力：允许执行哪些动作、后端可以引用哪些场景对象、哪些角色可以作为目标，以及 NPC 初始关注哪个对象。将其添加到任何已有 `GameObject` 的对象上，只要该对象已附加 `ConvaiCharacter` ——或者使用 [Actions Editor](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/actions-editor.md)，通过专用窗口配置同一组件。使用 `ConvaiActionConfigPatch` 可在会话开始后更改这些能力。

### 组件概览

| 属性       | 值                                                                |
| -------- | ---------------------------------------------------------------- |
| **菜单路径** | `Add Component → Convai → Convai Actions`                        |
| **命名空间** | `Convai.Runtime.Components`                                      |
| **限制**   | `DisallowMultipleComponent`, `RequireComponent(ConvaiCharacter)` |

该组件包含以下 Inspector 分区：

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

另外两个设置—— **动作由谁执行** 以及动作行为对象——是在 Actions Editor 的 **角色设置** 选项卡中配置的，而不是在原始 Inspector 中通过 `Header` 显示；请参阅下文的 [动作行为所在位置](#where-action-behaviors-live) 。

### 动作定义

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

#### 动作定义字段

| 字段                      | 类型                                  | 说明                                                                                                                                                                                                   |
| ----------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ActionName`            | `string`                            | Convai 选择此动作时发送的名称。运行时不区分大小写；空格有意义。                                                                                                                                                                  |
| `Description`           | `string`                            | 发送给 Convai 的简短句子，用于帮助角色理解该动作的功能及使用时机。                                                                                                                                                                |
| `TargetRequirement`     | `ConvaiActionTargetRequirement`     | 此操作是否需要目标，以及需要哪种目标。                                                                                                                                                                                  |
| `Executor`              | `MonoBehaviour`                     | 执行行为的组件。必须实现 `IConvaiActionExecutor`.                                                                                                                                                                |
| `TimeoutSeconds`        | `float`                             | 执行器在自动取消前允许运行的最长秒数。 `0` = 无超时。                                                                                                                                                                       |
| `FailurePolicyOverride` | `ConvaiActionFailurePolicyOverride` | 针对单个操作覆盖分发器的批处理失败策略。默认为 `UseDispatcherDefault`.                                                                                                                                                      |
| `AnswerDelivery`        | `ConvaiActionAnswerDelivery`        | 角色如何处理此操作返回的答案（参见 [操作执行器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md)）。仅当执行器返回 `ConvaiActionExecutionResult.Answered`. |
| `Enabled`               | `bool`                              | 是否将此操作告知 Convai。默认为 `true`。已禁用的操作不会包含在连接载荷或会话中的任何重新同步中；如果后端发送了该操作的过时命令，系统会将其报告为未处理，而不会执行。                                                                                                            |

#### 目标要求值

| 值           | 含义             |
| ----------- | -------------- |
| `None`      | 操作不引用目标对象或角色   |
| `Object`    | 操作需要一个已解析的对象目标 |
| `Character` | 操作需要一个已解析的角色目标 |
| `Either`    | 操作接受对象目标或角色目标  |

一个执行器组件可以用于多个操作定义。如果相同的行为适用于多个后端命令，请添加多个条目，为它们设置不同的 `ActionName` 值，但使用相同的 `Executor` 引用。

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

### 操作行为的存放位置

默认情况下，操作执行器组件与 `GameObject` 位于同一个 `ConvaiCharacter` 上——设置流程和所有示例均采用这种布局，而且无论有多少种行为都适用。如果角色使用了大量随附的 [操作执行器](https://docs.convai.com/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 Action Runner` （默认）会让 SDK 的设置检查预期此角色上存在 `ConvaiActionDispatcher` ； `Custom Code` 则会告知检查程序，动作由你自己的脚本处理，例如通过 `ConvaiCharacter.OnActionsReceived` 或 `ConvaiManager.Events.OnCharacterActionReceived` 处理。此设置仅用于声明——不会改变运行时的任何行为——因此它的唯一作用是告知设置检查程序：缺少 dispatcher 是配置错误，还是你的有意设置。

### 可执行动作的对象

「 **可执行动作的对象** 」中的每个条目都会将场景对象注册为后端认可的有效目标。

#### 对象定义字段

| 字段                    | 类型             | 说明                                                                                                         |
| --------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
| `Name`                | `string`       | Convai 在动作命令中用于引用此对象的标识符。运行时匹配时不区分大小写。                                                                     |
| `Description`         | `string`       | 发送给 Convai 的通俗描述。用于解析自然语言指代（“墙边的箱子”）。请写成完整句子，描述对象的类型、颜色、位置和用途。                                             |
| `GameObjectReference` | `GameObject`   | 运行时要与之交互的场景对象。 **仅在本地使用——绝不会发送给 Convai。**                                                                  |
| `TextOnly`            | `bool`         | 如果场景中没有对应此条目的对象，请勾选此项。Convai 仍会记住其名称并能谈论它，但绝不会尝试对其执行动作。 **仅在本地使用。**                                        |
| `Aliases`             | `List<string>` | 其他也应匹配此条目的本地用语（例如，名为 `灯具` 的灯笼也可以称为 `Lantern`）。对象名称及相近用语本身已经可以匹配。 **仅在本地使用——绝不会发送给 Convai。**                |
| `InteractionPoint`    | `Transform`    | 角色对该对象执行动作时最终到达的位置。留空则使用对象自身的 Transform；若需更精确地指定位置，可将其指向一个较小的空 `Transform` （例如，将位置设在门前，而不是门内）。 **仅在本地使用。** |

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

**撰写有效描述：**

|          | 示例                         |
| -------- | -------------------------- |
| **过于含糊** | `场景中的一个物体`                 |
| **良好示例** | `安装在主工作台左侧墙上的红色便携式二氧化碳灭火器` |
| **良好示例** | `场地入口附近设备架上的黄色安全帽`         |

描述在连接时确定。如果场景对象的状态在会话期间发生变化（例如被移动或替换），Convai 中的描述不会自动更新。对于动态场景，请使用连接时覆盖设置或运行时补丁（见下文）。

### 可操作角色

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

#### 角色定义字段

| 字段                    | 类型             | 说明                                                                             |
| --------------------- | -------------- | ------------------------------------------------------------------------------ |
| `Name`                | `string`       | Convai 用于引用此角色的标识符。                                                            |
| `Bio`                 | `string`       | 发送给 Convai 的简短描述，帮助后端了解角色身份，以便进行目标选择（例如：“负责设备检查的现场安全主管”）。                      |
| `GameObjectReference` | `GameObject`   | 该角色的 `GameObject`. **仅限本地使用 — 永远不会发送给 Convai。**                                |
| `TextOnly`            | `bool`         | 如果场景中没有对应此条目的对象，请勾选此项。Convai 仍会记住其名称并能谈论它，但绝不会尝试对其执行动作。 **仅在本地使用。**            |
| `Aliases`             | `List<string>` | 应与此条目匹配的其他本地措辞（例如 `the shopkeeper` 用于名为 `Mira的角色`). **仅限本地使用 — 从不发送给 Convai。** |
| `InteractionPoint`    | `Transform`    | 角色对该角色执行操作时的最终位置。留空则使用目标角色自身的变换。 **仅限本地使用。**                                   |

两者 `ConvaiActionObjectDefinition` 和 `ConvaiActionCharacterDefinition` 还会公开一个运行时 `Available` 标志，供目标解析时查询，且从不发送给后端 — 请参阅 [在运行时更新角色动作](https://docs.convai.com/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` 不会立即生效；必须结束会话并重新连接。
{% endhint %}

### 在连接时动态配置

对于程序化生成的场景或操作目标会随会话变化的多关卡游戏，可在调用 `RoomSessionConnectOptions` 时覆盖 Inspector 配置， `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 = "Yellow hard hat on the equipment shelf" },
                    new() { Name = "Locker", Description = "Green metal locker near the exit" }
                },
                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 确认后，补丁才会生效。

请参阅 [运行时更新角色操作](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/update-actions-at-runtime.md) ，了解补丁字段的完整语义、完整代码示例，以及如何读取后端的确认信息。

### 后续步骤

{% content-ref url="/pages/4001c6ae3c6d4603942748007a37a67812bb7e9a" %}
[在运行时更新角色动作](https://docs.convai.com/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" %}
[动作目标解析的工作方式](https://docs.convai.com/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" %}
[动作执行器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/character-actions/action-executors.md)
{% endcontent-ref %}

{% content-ref url="/pages/6e3c85bad169c9c2c755b38be39008ef3ce023cf" %}
[分发器和批处理策略](https://docs.convai.com/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" %}
[角色动作示例](https://docs.convai.com/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.
