配置角色动作

ConvaiActionConfigSource 的参考——动作定义、目标对象、可执行角色以及脚本化连接时覆盖。

ConvaiActionConfigSource 这是 Inspector 中的配置界面，用于填写 Convai 在连接时需要了解的 NPC 动作能力：允许哪些动作、后端可引用哪些场景对象、哪些角色可作为目标，以及 NPC 最初关注哪个对象。将它添加到任何 GameObject 上，且该对象已经具有 ConvaiCharacter.

组件概览

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

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

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

ConvaiActionConfigSource Inspector——四个部分均已显示。每个部分对应发送给 Convai 的连接时载荷中的一个独立部分。

动作定义

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

动作定义字段

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

目标要求值

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

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

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

一个已配置的动作定义——Action Name 绑定到后端命令字符串；Executor 指向在运行时执行该行为的 Unity 组件。

可执行对象

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

对象定义字段

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

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

有效描述的写法：

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

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

带有已注册目标的“可执行对象”列表——只有 Name 和 Description 会序列化到连接载荷中；GameObject Reference 仅在本地使用，绝不会发送给 Convai。

可执行角色

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

角色定义字段

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

带有已注册 NPC 的“可执行角色”列表——Bio 字段帮助后端解析诸如“主管”或“出口附近的工程师”之类的自然语言角色引用。

初始关注对象

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

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

会话生命周期

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

对 ConvaiActionConfigSource 在 Play Mode 中所做的更改，直到结束会话并重新连接后才会生效。

连接时的动态配置

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

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

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

两个覆盖都使用

当后端能力配置和本地执行器绑定都需要与 Inspector 配置不同时时使用：

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);
    }
}

仅配置覆盖

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

使用示例

示例 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——程序化关卡（脚本覆盖）

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

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.

下一步

动作执行器分发器与批处理策略