> 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` 这是用于在连接时向 Convai 说明你的 NPC 动作能力的检查器编辑界面：允许哪些动作、后端可以引用哪些场景对象、哪些角色可作为目标，以及哪个对象是 NPC 的初始注意焦点。将其添加到任何 `GameObject` 已经具有 `ConvaiCharacter`。请使用 `ConvaiActionConfigPatch` 以便在会话已开始后更改这些可用能力。

### 组件概览

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

该组件有四个检查器部分：

| 部分        | 用途                     |
| --------- | ---------------------- |
| **动作定义**  | 将后端动作名称映射到 Unity 执行器组件 |
| **可动作对象** | 后端可作为动作目标引用的场景对象       |
| **可动作角色** | 后端可作为动作目标引用的其他角色       |
| **初始注意力** | NPC 在每次会话开始时关注的对象名称    |

### 动作定义

其中的每个条目 **动作定义** 都会将一个后端动作名称绑定到一个 Unity 执行器组件。

#### 动作定义字段

| 字段           | 类型                              | 描述                                     |
| ------------ | ------------------------------- | -------------------------------------- |
| `ActionName` | `string`                        | Convai 选择此动作时发送的名称。运行时不区分大小写；空格有意义。    |
| `目标要求`       | `ConvaiActionTargetRequirement` | 此动作是否需要目标，以及需要哪种目标。                    |
| `执行器`        | `MonoBehaviour`                 | 执行该行为的组件。必须实现 `IConvaiActionExecutor`. |
| `超时时间（秒）`    | `float`                         | 执行器在被自动取消前最多可运行的秒数。 `0` = 无超时。         |

#### 目标要求值

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

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

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

### 可作为动作目标的对象

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

#### 对象定义字段

| 字段                    | 类型           | 描述                                                            |
| --------------------- | ------------ | ------------------------------------------------------------- |
| `名称`                  | `string`     | Convai 在动作命令中用于引用此对象的标识符。运行时匹配不区分大小写。                         |
| `描述`                  | `string`     | 发送给 Convai 的自然语言描述。用于自然语言引用解析（“墙边的盒子”）。请写成完整句子，描述类型、颜色、位置和用途。 |
| `GameObjectReference` | `GameObject` | 运行时要交互的场景对象。 **仅本地使用——绝不会发送给 Convai。**                        |

`GameObjectReference` 标记为 `[JsonIgnore]`。只有 `名称` 和 `描述` 会序列化到连接负载中。Convai 通过名称解析目标；Unity 会将该名称映射到你的 `GameObject` 本地对象。

**撰写有效描述：**

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

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

### 可作为动作目标的角色

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

#### 角色定义字段

| 字段                    | 类型           | 描述                                                         |
| --------------------- | ------------ | ---------------------------------------------------------- |
| `名称`                  | `string`     | Convai 用于引用此角色的标识符。                                        |
| `简介`                  | `string`     | 发送给 Convai 的简短描述。帮助后端在做目标选择决策时理解该角色是谁（例如，“负责设备检查的现场安全主管”）。 |
| `GameObjectReference` | `GameObject` | 角色的 `GameObject`. **仅本地使用——绝不会发送给 Convai。**                |

### 初始注意焦点

该 **初始注意力** 字段接受单个对象名称。会话开始时，Convai 会将该对象视为 NPC 当前关注的焦点——在玩家首次发言前预先建立引用锚定。

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

### 会话生命周期

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

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

### 连接时的动态配置

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

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

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

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

```csharp
using System.Collections.Generic;
using Convai.Runtime.Actions;
using Convai.Runtime.Room;
using Convai.Shared.Actions;
using UnityEngine;

public sealed class DynamicActionSetup : MonoBehaviour
{
    [SerializeField] private ConvaiManager _manager;
    [SerializeField] private NavMeshMoveToActionExecutor _mover;

    public async void ConnectWithOverrides()
    {
        var options = new RoomSessionConnectOptions
        {
            ActionConfigOverride = new ConvaiActionConfig
            {
                Actions = new List<string> { "Move 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 = "Move To",
                    TargetRequirement = ConvaiActionTargetRequirement.Object,
                    Executor = _mover
                }
            }
        };

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

{% endtab %}

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

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

await _manager.ConnectAsync(options);
```

{% endtab %}
{% endtabs %}

`动作定义覆盖` 会根据……进行筛选 `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.