注意力与引用锚定

了解 Convai Unreal Engine 插件如何解析代词引用和注意力目标，以便角色理解玩家所指的对象。

大多数字符动作在无需任何注意力设置的情况下即可工作——引用参数会自动从已注册对象列表中解析。当你希望角色理解像“it”、“that”和“there”这样的代词，或者需要控制角色当前聚焦于哪个对象时，请阅读本页。

当玩家说“Go to it”或“Pick that up”时，单词“it”或“that”必须解析到一个具体对象。该插件通过两个相互关联的机制来解决此问题：引用锚定（将 Convai 输出中的对象名称与已注册环境中的对象进行匹配解析）和注意力（跟踪角色或玩家当前聚焦的对象，以便代词引用能够可预测地解析）。

引用锚定

当 Convai 返回一个带有一个 Reference-类型参数时，原始值是从已注册对象和角色名称中选出的名称字符串。插件会将该字符串与 EnvironmentData.Objects 是位于 EnvironmentData.Characters 通过精确的已注册名称。

结果会存储在 FConvaiResultParam.RefValue 作为一个已填充的 FConvaiObjectEntry （包括实时的 Ref Actor 指针）。无法解析的值会产生一个空的 FConvaiObjectEntry 带有空的 Ref.

引用锚定作用于实时的 FConvaiEnvironmentData 在聊天机器人组件上。通过……添加的对象 AddObject 在运行时会立即更新本地环境，因此后续动作解析可以基于当前本地对象和角色列表进行解析。动作契约会固定角色在下一次重新连接之前可以执行哪些动作模板，而会话中途的场景上下文更新会刷新场景上下文，而不是扩展连接时的动作目标集。

注意力源优先级

注意力槽具有一个所有权模型，用于决定哪个来源可以写入它：

来源	优先级	由	可被以下内容覆盖
无	—	默认 / 已清除状态	任何来源
凝视	低	通过……的凝视管线 UConvaiObjectComponent	另一个凝视事件或显式
显式	高	Blueprint/C++ 对……的调用 SetObjectInAttention	仅另一个显式调用

显式优先。 一旦 SetObjectInAttention 设置了该槽后，凝视事件在发出显式清除之前都不能覆盖它。

注意力槽

注意力槽是一个单一的 FConvaiObjectEntry 存储为 CurrentAttentionObject 在 FConvaiEnvironmentData。插件会将此槽包含在动作配置和场景上下文中，以便 Convai 在解释诸如……之类的歧义引用时拥有当前聚焦对象 "this", "that", "it"，以及 “there”.

聊天机器人组件上的注意力槽具有一个关联的来源标志：

EConvaiAttentionSource 值	含义
无	没有对象处于注意力中。
显式	Blueprint 或 C++ 对……的调用 SetObjectInAttention 设置该槽。凝视无法覆盖它。
凝视	凝视管线设置了该槽。另一个凝视事件可以覆盖它。

从 Blueprint 设置注意力

调用 SetObjectInAttention 在 Convai 聊天机器人 组件可显式设置注意力对象：

// Blueprint 伪代码
SetObjectInAttention(
    AttentionObject: FConvaiObjectEntry,  // 要聚焦的对象
    Text: FString,                         // 可选的上下文事件文本
    ShouldRespond: EC_RunLLMOption,        // Convai 应如何响应
    bFlushImmediately: bool                // 如有紧急情况则绕过防抖
)

传入一个空的 FConvaiObjectEntry （默认构造，且包含一个空的 名称）即可清除该槽。

SetObjectInAttention 在 EnvironmentData.bEnableActions 为 false 在聊天机器人上——Convai 只会在……时解析注意力 action_config 在……时发送 /connect.

从凝视设置注意力

凝视管线使用 TrySetObjectInAttentionFromGaze 是位于 TryClearObjectInAttentionFromGaze。这些受所有权规则约束：

• TrySetObjectInAttentionFromGaze 在……时成功 AttentionSource 为 无 或 凝视。它返回 false 当槽处于……时 显式，从而保留显式所有者不变。
• TryClearObjectInAttentionFromGaze 仅当聊天机器人仍将凝视视为所有者时才清除该槽 是位于 且预期对象与当前正在关注的对象匹配。这样可防止过时的“gaze lost”事件清除较新的目标。

UConvaiObjectComponent 通过……自动驱动这些调用 NotifyGazeAttentionBegin 是位于 NotifyGazeAttentionEnd。除非你正在构建自定义聚焦系统，否则通常不需要直接调用凝视设置器。有关完整的追踪管线、高亮行为以及组件作用域的目标规则，请参见 凝视注意力的工作原理.

AttentionSource 属性

AttentionSource 是一个 瞬态，Blueprint 可读 EConvaiAttentionSource 属性，位于 UConvaiChatbotComponent。读取它以决定你的 Blueprint 逻辑应调用显式设置器还是受凝视门控的设置器：

// Blueprint 伪代码
// 在设置显式注意力之前，检查当前来源
Source = ChatbotComponent.AttentionSource
// Source == None 或 Gaze → 可以安全调用 SetObjectInAttention
// Source == Explicit → 检查你的调用是否应该覆盖现有的显式所有者

凝视如何将对象提升为注意力对象

凝视管线会自动通过……运行 UConvaiObjectComponent。你通常只需要读取 AttentionSource 或调用 SetObjectInAttention ；下面的步骤说明了自动路径如何工作。

当 UConvaiObjectComponent 被添加到场景 Actor 中，且玩家看向它时：

1. UConvaiPlayerComponent的凝视管线触发 NotifyGazeBegin 在对象组件上，从而触发 OnGazedIn.
2. 当玩家的凝视停留时间超过配置的阈值时， NotifyGazeAttentionBegin 会触发。
3. NotifyGazeAttentionBegin 会广播到子系统中的每个已注册聊天机器人，并调用 TrySetObjectInAttentionFromGaze.
4. 每个聊天机器人都会根据自身的……独立接受或拒绝该更新 AttentionSource.

当玩家移开视线时， NotifyGazeAttentionEnd 会广播 TryClearObjectInAttentionFromGaze 到每个聊天机器人。

与动作参数解析的关系

当 Convai 返回一个带有一个 Reference-类型参数时，该值会针对完整的 Objects 是位于 Characters 列表进行锚定——不只是当前注意力对象。注意力对象只会影响玩家使用歧义代词时 Convai 选择哪个对象。一旦选定，正常的引用锚定路径会将其解析为一个实时的 Ref 指针。

LookAtTarget 和 PointAtTarget

UConvaiChatbotComponent 为动画公开两个复制的 Actor 引用：

• LookAtTarget ——角色的 AnimBP 应将凝视/IK 驱动朝向的 Actor。
• PointAtTarget ——角色的手臂 IK 应指向的 Actor。

这些与注意力槽无关，并且不会影响对话或动作管线。可从 Blueprint 设置它们来驱动动画状态，而不影响 Convai 解析对象引用的方式。

下一步

配置动作动作 Blueprint 参考