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

### 组件概览

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

该组件在 Inspector 中分为四个部分：

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

<figure><img src="/files/ba72139f2b0dc839a3de9312a2318c2a06a17204" alt="ConvaiActionConfigSource in the Unity Inspector showing all four sections: Action Definitions, Actionable Objects, Actionable Characters, and Initial Attention"><figcaption><p>ConvaiActionConfigSource Inspector——四个部分均已显示。每个部分对应发送给 Convai 的连接时载荷中的一个独立部分。</p></figcaption></figure>

### 动作定义

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

#### 动作定义字段

| 字段                  | 类型                              | 描述                                         |
| ------------------- | ------------------------------- | ------------------------------------------ |
| `ActionName`        | `字符串`                           | Convai 在选择此动作时发送的名称。运行时不区分大小写；空格会被保留并计入匹配。 |
| `TargetRequirement` | `ConvaiActionTargetRequirement` | 该动作是否需要目标，以及需要哪种目标。                        |
| `Executor`          | `MonoBehaviour`                 | 执行该行为的组件。必须实现 `IConvaiActionExecutor`.     |
| `TimeoutSeconds`    | `float`                         | 执行器在被自动取消之前可运行的最大秒数。 `0` = 无超时。            |

#### 目标要求值

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

{% hint style="info" %}
一个执行器组件可以服务多个动作定义。为多个后端命令添加独立条目，并使用不同的 `ActionName` 值，但使用相同的 `Executor` 引用，当同一行为适用于多个后端命令时。
{% endhint %}

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

<figure><img src="/files/513a7d6af96a36aafd58e8af123a1ee6c2a40132" alt="Unity Inspector showing a ConvaiActionConfigSource action definition entry with Action Name, Target Requirement, Executor, and Timeout Seconds fields filled in"><figcaption><p>一个已配置的动作定义——Action Name 绑定到后端命令字符串；Executor 指向在运行时执行该行为的 Unity 组件。</p></figcaption></figure>

### 可执行对象

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

#### 对象定义字段

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

{% hint style="info" %}
`GameObjectReference` 被标记为 `[JsonIgnore]`。只有 `名称` 和 `描述` 会序列化到连接载荷中。Convai 会按名称解析目标；Unity 会将该名称映射到本地的 `GameObject` 。
{% endhint %}

**有效描述的写法：**

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

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

<figure><img src="/files/45fee64bf677b55de942b4eb2ddd3c8ae440df9f" alt="Unity Inspector showing the Actionable Objects list on ConvaiActionConfigSource with a registered scene object entry including Name, Description, and GameObject Reference fields"><figcaption><p>带有已注册目标的“可执行对象”列表——只有 Name 和 Description 会序列化到连接载荷中；GameObject Reference 仅在本地使用，绝不会发送给 Convai。</p></figcaption></figure>

### 可执行角色

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

#### 角色定义字段

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

<figure><img src="/files/99b07a91b8f70311ca6d8da3213d52300ef812fa" alt="Unity Inspector showing the Actionable Characters list on ConvaiActionConfigSource with a registered NPC entry including Name, Bio, and GameObject Reference fields"><figcaption><p>带有已注册 NPC 的“可执行角色”列表——Bio 字段帮助后端解析诸如“主管”或“出口附近的工程师”之类的自然语言角色引用。</p></figcaption></figure>

### 初始关注对象

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

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

### 会话生命周期

动作配置会在会话开始时一次性发送给 Convai，并且在会话处于活动状态时无法修改。

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

### 连接时的动态配置

对于程序生成的场景或多关卡游戏，如果动作目标在会话之间会变化，请在调用 `RoomSessionConnectOptions` 时，通过 `ConnectAsync`.

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

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

{% tabs %}
{% tab title="两个覆盖都使用" %}
当后端能力配置和本地执行器绑定都需要与 Inspector 配置不同时时使用：

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

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

await _manager.ConnectAsync(options);
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`ActionDefinitionsOverride` 会根据 `ActionConfigOverride.Actions`进行过滤。只有其 `ActionName` 出现在配置的动作列表中的定义才会在该会话中生效。未列出的动作名称对应的定义会被静默忽略。
{% endhint %}

### 使用示例

#### 示例 1——工业安全演练（Inspector 设置）

**场景：** 一场消防安全培训模拟，NPC 教官在被要求时可以取用设备。

**在 Inspector 中的设置：**

动作定义：

* `ActionName = Retrieve`, `TargetRequirement = Object`, `Executor = NavMeshMoveToActionExecutor`
* `ActionName = Point At`, `TargetRequirement = Either`, `Executor = LookAtTargetActionExecutor`

可执行对象：

* `Name = Extinguisher`, `Description = 墙上支架上的红色 CO2 灭火器，位于泵站旁边`
* `Name = Alarm Panel`, `Description = 主入口附近带红色拉手的紧急报警面板`

**预期结果：** 当学员说“取来灭火器”时，NPC 会前往它；当学员说“指向报警器”时，NPC 会面向它。

#### 示例 2——程序化关卡（脚本覆盖）

**场景：** 每个关卡加载不同的设备。对象目标在运行时根据关卡数据构建。

```csharp
private List<ConvaiActionObjectDefinition> BuildObjectsFromLevel(LevelData level)
{
    var objects = new List<ConvaiActionObjectDefinition>();
    foreach (EquipmentEntry entry in level.Equipment)
    {
        objects.Add(new ConvaiActionObjectDefinition
        {
            Name = entry.Id,
            Description = entry.Description,
            GameObjectReference = entry.SceneObject
        });
    }
    return objects;
}
```

将生成的列表传入 `ActionConfigOverride.Objects` 时，通过 `ConnectAsync`.

### 下一步

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


---

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