排查凝视注意力问题
诊断并修复凝视注意力问题——对象未高亮、注意力从不提升、光标不出现,以及组件范围内的凝视不匹配。
使用此页面诊断并修复最常见的凝视注意力问题。每个条目都遵循“症状 / 原因 / 修复 / 验证”的结构。
凝视时对象不会高亮
症状: 玩家直接看向一个世界 actor,但没有出现轮廓或线框。
原因(最可能): 以下条件之一:
该 actor 没有
UConvaiObjectComponent.bEnableGazeAttention是false到玩家组件上的bGazeable是false在对象的UConvaiObjectComponent(在 Convai | 对象 | 凝视).
修复:
在关卡中选中该 actor。在 详情 面板中,确认
UConvaiObjectComponent列在 组件.在该对象组件上,展开 Convai | 对象 | 凝视 并确认 可凝视 (
bGazeable)已勾选。选择
UConvaiPlayerComponent在玩家 Pawn 上。在 Convai | 凝视注意力,确认 启用注视关注 已勾选。如果该 actor 使用自定义网格,并且 无碰撞 设置在该 primitive 上,则射线检测会穿透它。将碰撞通道至少设置为 可见性 并确认
UConvaiPlayerComponent上的检测通道匹配(GazeTraceChannel,默认ECC_Visibility).如果该 actor 超出检测范围,请增大
GazeMaxDistance(默认 5000 cm)。
验证: 进入 Play 模式。将准星对准该 actor。高亮应立即出现(UE 5.3 及更高版本显示淡黄色叠加层,UE 5.0–5.2 显示线框框),并且光标点应变为白色。
对象已高亮,但注意力从未被提升
症状: 看向对象时轮廓会出现,但 OnAttentionGained 从未在 UConvaiPlayerComponent.
原因: 以下三个条件之一:
玩家没有在同一个 actor/primitive 上持续凝视足够长时间以达到
GazeAttentionDelay.GazeAttentionDelay设置得高于预期。Blueprint 事件绑定到了另一个
UConvaiPlayerComponent而不是正在运行凝视注意力的那个。
修复:
将准星保持在同一个高亮对象上,直到完整的
GazeAttentionDelay持续时间结束。确认
GazeAttentionDelay未被设置为异常高的值。将诊断打印绑定到
OnAttentionGained放在同一UConvaiPlayerComponent且其 启用注视关注 已勾选。
验证: 添加一个 Blueprint 绑定到 OnAttentionGained 位于 UConvaiPlayerComponent 并打印屏幕消息。进入 Play 模式并持续凝视该对象 GazeAttentionDelay 秒。消息应当出现。
注意力已提升,但角色没有说话
症状: OnAttentionGained 已触发(可通过 Blueprint 打印验证),但角色保持沉默。
原因: 以下条件之一:
GazeShouldRespond 是 Never
注意力会静默更新;不会请求 LLM 回复。新建的玩家组件默认如此。
启用操作 已关闭
SetObjectInAttention 并且凝视分发对聊天机器人没有影响。
AttentionSource 是 显式(Blueprint/C++)
直接的 SetObjectInAttention 调用会占用该槽位;凝视更新会被拒绝。
会话未激活
本地注意力状态可能会更新,但不会有请求到达 Convai。
修复:
设置
GazeShouldRespond到Always位于UConvaiPlayerComponent.填写
GazeAttentionText并附上一句描述性句子。如果没有文本,注意力事件就没有叙事上下文,即使ShouldRespond是Always.在聊天机器人上展开 Convai | 操作 → 环境 并确认 启用操作 (
EnvironmentData.bEnableActions)已勾选。在 Play 模式下读取
AttentionSource位于UConvaiChatbotComponent(在 Convai | 操作)。如果它显示显式(Blueprint/C++),找到设置SetObjectInAttention并使用空的FConvaiObjectEntry.确认聊天机器人会话已连接。请参阅 会话生命周期 以查看连接诊断。
验证: 设置 GazeShouldRespond 到 Always,进入 Play 模式,并看向该对象 GazeAttentionDelay 秒。角色应开始说话。
诊断来自 SetObjectInAttention 的“无效果”警告
症状: 一次凝视提升或一次直接的 SetObjectInAttention 调用都不会改变角色的注意力,并且 Output Log 显示一条 警告级别消息,开头为 SetObjectInAttention('<name>') (或者,对于凝视, [Gaze] TrySetObjectInAttentionFromGaze rejected on '<name>').
原因: 该警告会指出调用无效的确切原因。它总是以下三种之一:
动作已禁用
警告文本: 此聊天机器人的 Environment 中 bEnableActions = false。注意力在服务器端根据 action_config进行解析,而它只会在启用动作时发送。
对象不在聊天机器人的环境列表中
警告文本: 对象不在此聊天机器人的环境对象列表中——现已自动注册。该调用仍会为下次自动注册该对象,但这次尝试无法解析它。
对象未在连接时发送
警告文本: 对象不在连接时发送到服务器的对象之列。会话进行中的 AddObject 调用到达服务器时仅作为场景元数据更新——只有在下次重新连接后才会成为可解析的注意力目标。
修复:
请在 Output Log 中阅读完整警告文本——它会说明适用的是哪一种条件。
对于已禁用的动作,展开 Convai | 操作 → 环境 在聊天机器人上并检查 启用操作 (
EnvironmentData.bEnableActions).对于缺失或尚未连接的对象,请注册该对象(通过聊天机器人的
AddObject或一个UConvaiObjectComponent在关卡中)在会话开始前完成,这样它就会包含在action_config连接时发送的对象中。对于会话进行中的新增,请重新连接一次会话,或者接受该对象只会在重新连接后成为注意力目标。
验证: 修复所报告的条件,进入 Play 模式,并重复之前记录警告的调用。Output Log 中不应再出现 SetObjectInAttention 或 TrySetObjectInAttentionFromGaze 警告,且注意力更改应当生效。
光标未出现
症状: 开启凝视跟踪时,屏幕中心没有可见的点。
原因: bShowGazeCursor 是 false,或者光标小部件类引用无效,或者光标 IdleColor alpha 为 0 ,并且当前凝视没有落在 Convai 对象上。
修复:
确认 显示凝视光标 (
bShowGazeCursor) 为true位于UConvaiPlayerComponent.在 Play 模式下,将准星直接对准一个带标签的 Convai 对象。光标会切换为
凝视光标激活颜色(默认白色)。如果只有在对准 Convai 对象时才出现,则说明它工作正常——空闲状态按设计是透明的。要让光标始终可见,请将 始终显示凝视光标 (
bAlwaysShowGazeCursor)为true.如果光标仍未出现,请检查
GazeCursorWidgetClass是否未被设置为已删除或重命名的类。
验证: 设置 bAlwaysShowGazeCursor 到 true,进入 Play 模式。屏幕中心应始终可见一个白点。
高亮颜色与配置值不一致
症状: 轮廓已出现,但呈白色或与在其中设置的颜色不同 GazeHighlightColor.
原因(UE 5.3+): 自定义的 GazeOverlayMaterial 未公开一个 EmissiveColor 向量参数,因此无法应用颜色。
原因(UE 5.0–5.2): 线框回退(DrawDebugBox)使用 GazeHighlightColor,但不使用 GazeOverlayMaterial 或 GazeHighlightEmissiveIntensity。仅修改材质对回退路径没有影响。
修复:
如果使用自定义的
GazeOverlayMaterial,请确认该材质公开了名为EmissiveColor的向量参数。高亮系统只驱动这个参数名。在 UE 5.0–5.2 中,将
GazeHighlightColor直接设置,因为高亮外观仅限于线框框。升级到 UE 5.3 或更高版本即可使用叠加材质系统。如果
GazeOverlayMaterial未设置,并且 UE 5.3+ 的轮廓是白色(不是淡黄色),则插件资源/ConvAI/Highlights/M_ConvaiGazeOverlay可能已从打包构建中被剔除。回退材质/Engine/EngineMaterials/EmissiveMeshMaterial没有参数。请重新打包插件内容。
验证: 设置 GazeHighlightColor 为饱和红色 (1.0, 0.0, 0.0, 1.0) ,并进入 Play 模式。看向带标签的对象时,轮廓应显示为红色。
凝视会穿透薄墙使后方对象被激活
症状: 当玩家朝那个方向看时,墙或地板另一侧的对象会被高亮。
原因: 世界几何体没有阻挡 GazeTraceChannel ——通常是因为该网格使用 无碰撞 或者将通道设置为 忽略.
修复:
选中墙或地板网格。在 详情 面板中的 Collision中,确认该
GazeTraceChannel(默认ECC_Visibility)设置为 阻挡.或者,将
GazeTraceChannel位于UConvaiPlayerComponent改为仅让可交互对象和阻挡几何体响应的自定义通道。
验证: 进入 Play 模式并看向墙体。另一侧的对象不应再高亮。
角度容差导致错误对象被高亮
症状: 玩家看向一个对象,但却高亮了附近的另一个对象。
原因: GazeAngleTolerance 设置得过高,导致点积回退更偏向于一个更大或位置不同、但与视线方向更对齐的对象。
修复: 降低 GazeAngleTolerance (默认 5 度,高级显示)。如果对象需要精确瞄准,请将 GazeAngleTolerance 到 0 设置为关闭回退机制,并要求必须直接命中射线检测。
验证: 设置 GazeAngleTolerance 到 0 ,并进入 Play 模式。只有当准星直接位于对象上方时,对象才应高亮。
组件范围高亮出现在错误的子网格或整个 actor 上
症状: 一个 UConvaiObjectComponent 并将 ObjectEntry.ComponentName 设置后会高亮整个 actor,而不是只高亮指定的子网格;或者在看向目标部位时根本不出现高亮。
原因: 以下四种条件之一:
ObjectEntry.ObjectReference(Details 面板标签 对象为)仍然是整个 Actor(默认值)。凝视会忽略组件名称直到 对象为 是特定组件.该
组件名称值与 actor 上的任何组件都不匹配(拼写错误、组件已重命名,或子字符串不匹配)。组件树在运行时发生了变化,而缓存解析不再适用(罕见——
GetResolvedComponent()会在每次调用时重新验证缓存,并在失败时自动重新扫描)。目标子网格在
GazeTraceChannel上没有碰撞,因此射线检测永远不会命中它。
修复:
在
UConvaiObjectComponent,展开 对象条目 并设置 对象为 到特定组件.在 Play 模式下调用
GetResolvedComponent()在UConvaiObjectComponent,并打印返回值。一个nullptr结果表示名称未能解析——请检查 Details 面板层级中的确切组件名称。确认
ObjectEntry.ComponentName是目标组件标签的子字符串,如 组件 面板所示(例如“Handle”匹配SM_DoorHandle但不匹配SM_Knob).如果 actor 的组件树是在运行时构建的(程序化生成、动态附加),请在
GetResolvedComponent()组件树完全构建后再次调用——它总会将缓存匹配与实时组件树重新检查,因此加载时的过期结果会在下一次调用时被修正。确认目标组件在
GazeTraceChannel上启用了碰撞。没有碰撞的组件永远不会被射线检测命中,因此即使名称解析正确,范围限定匹配也无法触发。
验证: 在修正 对象为 和 组件名称后,进入 Play 模式并将准星对准特定子网格。只有该网格应高亮;actor 的其他部分应保持不受影响。 GetResolvedComponent() 应返回正确的组件引用。
下一步
注视注意力快速开始注视注意力的工作原理注视注意力参考注视注意力使用示例最后更新于
这有帮助吗?