注意力与引用锚定

在运行时更新 NPC 的关注焦点，以便 Convai 将“捡起那个”或“去那里”之类模糊的玩家引用解析为正确的已注册场景对象。

参考锚定是 Convai 如何将含糊的玩家语言——“抓住那个”、“去那个地方”、“看看左边那个”——解析为某个已注册的特定对象或角色的方式。锚定由两个输入驱动：你为 ConvaiActionConfigSource中每个目标编写的详细描述，以及你在运行时随着玩家注意力变化而更新的当前注意对象。

锚定的工作原理

当玩家说“捡起那个圆柱体”时，Convai 会评估两件事：

1. 对象描述 ——你在连接时注册的名称和描述文本。Convai 使用它们将“圆柱体”匹配到你注册的对象。
2. 当前注意对象 ——NPC 当前“关注”的对象。设置后，Convai 会在处理“那个”或“它”这类歧义引用时赋予其很高权重。

描述在连接时固定，且无法在会话中途更新。当前注意对象可以在活动对话中的任何时刻更改。

编写有效的对象描述

该 描述 中每个 ConvaiActionObjectDefinition 上的字段是决定锚定准确性的最重要文本。请将每个描述写成一个包含以下内容的单句自然语言：

• 对象类型 ——它是什么种类的东西
• 识别属性 ——颜色、材质、大小或标签
• 位置 ——它相对于场景中地标的位置
• 用途 ——它的用途

	示例
太模糊——请避免	场景中的一个对象
没有位置——请避免	一个灭火器
良好	一个红色便携式 CO2 灭火器，安装在主泵控制面板左侧的墙壁支架上
良好	一个黄色安全帽，放在场地入口闸门右侧紧挨着的设备架上

模糊的描述会导致 Convai 选错目标，或无法解析歧义引用。

描述会在连接时发送给 Convai，且在会话激活期间不能更改。如果你的场景在运行时发生变化（对象被移动、更换或销毁），请结束会话并使用更新后的描述重新连接，或者在连接时使用 ActionConfigOverride 以编程方式构建描述。参见 配置角色动作 — 动态配置.

运行时注意力 API

在活动对话期间，可随时使用 ConvaiCharacter:

// 按对象名称设置
character.SetCurrentAttentionObject("Extinguisher");

// 按定义引用设置
character.SetCurrentAttentionObject(myObjectDefinition);

// 清除 — NPC 没有特定关注点
character.ClearCurrentAttentionObject();

方法签名

void SetCurrentAttentionObject(string objectName, string runLlm = "false")
void SetCurrentAttentionObject(ConvaiActionObjectDefinition actionObject, string runLlm = "false")
void ClearCurrentAttentionObject(string runLlm = "false")

runLlm 参数

可选的 runLlm 参数用于控制注意力变化是否会立即触发一次新的 LLM 回合。默认 "false" 会静默更新锚定上下文。传入 "true" ，如果你希望 Convai 以自然语言响应来对焦点变化作出反应。

// 静默更新 — NPC 不会口头反应
character.SetCurrentAttentionObject("GasValve");

// NPC 可能会口头回应焦点变化
character.SetCurrentAttentionObject("GasValve", runLlm: "true");

静默失败条件

如果前置条件未满足，这些调用会被静默忽略。每种情况下都会在 Console 中记录一条警告。

条件	结果
不在活动对话中	调用被忽略。警告： 无法设置注意对象：不在对话中
对象名称为空或仅包含空白字符	调用被忽略。警告： 无法设置空的注意对象
对象名称不在活动的 action-config 中	调用被忽略。警告： 无法设置注意对象 'X'：它不在当前活跃的 action_config objects 中

对象名称必须与 ConvaiActionConfigSource.Objects 中的某一项匹配（不区分大小写）。它不需要与 GameObjectReference 名称匹配——它必须与对象定义中的 名称 字段匹配。

注意范围

注意对象只会影响 后端对未来回合的引用解析。设置注意对象不会：

• 创建一个新的可操作目标
• 更改 action config 中包含哪些对象
• 让 NPC 在物理上看向或移动到该对象
• 影响任何正在进行中的动作步骤

连接时的初始注意力

要在玩家第一轮发言前预先设置 NPC 的关注点，请将 初始注意力 字段 ConvaiActionConfigSource 设置为你的 可操作对象 列表中某个对象的名称。这等同于在连接时调用 SetCurrentAttentionObject 。

初始注意对象必须与 可操作对象 中的一项完全匹配（不区分大小写）。如果不匹配，该字段会被静默省略，不会包含在连接负载中，并会记录警告。

用法示例

示例 1——训练模拟中的基于光标选择

场景： 一个工业检查模拟。当学员的光标悬停在某个设备上时，更新指导 NPC 的注意力，以便“指向它”能够正确解析。

using Convai.Runtime.Components;
using Convai.Shared.Actions;
using UnityEngine;
using UnityEngine.EventSystems;

public sealed class EquipmentFocusTracker : MonoBehaviour, IPointerEnterHandler, IPointerExitHandler
{
    [SerializeField] private ConvaiCharacter _instructor;
    [SerializeField] private ConvaiActionObjectDefinition _objectDefinition;

    public void OnPointerEnter(PointerEventData eventData)
    {
        _instructor.SetCurrentAttentionObject(_objectDefinition);
    }

    public void OnPointerExit(PointerEventData eventData)
    {
        _instructor.ClearCurrentAttentionObject();
    }
}

预期结果： 当学员将光标悬停在气阀上时，指导者的锚定会切换到该气阀。“指向它”现在会稳定地解析为悬停的对象。

示例 2——基于物理接近的注意力

场景： 一个医疗培训场景。NPC 指导者会自动聚焦到学生站在附近的那件设备上。

using Convai.Runtime.Components;
using UnityEngine;

public sealed class ProximityAttentionTrigger : MonoBehaviour
{
    [SerializeField] private ConvaiCharacter _instructor;
    [SerializeField] private string _objectName;

    private void OnTriggerEnter(Collider other)
    {
        if (!other.CompareTag("Player")) return;
        _instructor.SetCurrentAttentionObject(_objectName);
    }

    private void OnTriggerExit(Collider other)
    {
        if (!other.CompareTag("Player")) return;
        _instructor.ClearCurrentAttentionObject();
    }
}

将此组件放在每件设备周围的触发区域上。设置 _objectName 以匹配该对象的 名称 在 ConvaiActionConfigSource。当学生进入触发区域时，NPC 的锚定会自动切换到该设备。

预期结果： 当学生走到除颤器站旁边时，“告诉我怎么使用它”会稳定地解析为除颤器，而无需学生明确说出它的名称。

下一步

配置角色动作角色动作脚本参考