凝视故障排查

修复 Convai Gaze 角色中的静止眼睛、不会转动的头部、未选择的凝视目标以及被拒绝的脚本化凝视。

从角色本体开始诊断： ConvaiGazeController 检查器的 设置 部分和 Convai > Gaze Editor的 设置 选项卡会报告相同的装配结果——哪些骨骼已解析、当前启用的是哪种眼睛后端，以及朝向方向检查——然后你才按下 Play。本页涵盖报告未能解释的症状，以及下面列出的运行时行为。

症状、原因和修复方法

症状	可能原因	修复方法	验证
眼睛从不移动；只有头部转动	没有眼部骨骼，也没有完整的 EyeLook* BlendShape 集合被解析，因此凝视退回到仅头部运动	映射 LeftEye/RightEye 骨骼到装配上，或提供全部四个水平 EyeLook* 形状（EyeLookInLeft, EyeLookOutLeft, EyeLookInRight, EyeLookOutRight)	设置选项卡的 眼睛后端 这一行报告的是骨骼或 BlendShape 数量，而不是仅头部警告
头部和眼睛会停留在动画放置它们的位置	没有 ConvaiGazeController 在角色上，或者没有解析出语义 Head 骨骼	添加 ConvaiGazeController (添加组件 > Convai > 具身 > Gaze); 对于 Generic 或无动画器的装配，请添加 Convai > 具身化 > Character Rig 并分配 Head	缺失 Head 骨骼的控制台警告会消失，检查器显示为 Ready
从不会选择世界对象作为凝视目标	该对象没有 ConvaiGazeTarget，或者其优先级（默认 5）从未超过玩家锚点的 10	添加 ConvaiGazeTarget (添加组件 > Convai > 凝视 > 目标；将 优先级 提高到 10 之上，以压过玩家	对象在被选中时会显示线框小工具，并且在 Gaze Editor 的当前目标上显示为 Live 选项卡中
GazeAt/GlanceAt 调用不会产生可见效果	GazeFocusFidelity.Exact 处于活动状态，并且 AllowScriptedOverridesDuringExactFocus 关闭，或者 LockBlocksGlances 在眼神交流锁定期间吸收了一次瞥视	启用 AllowScriptedOverridesDuringExactFocus 如果脚本请求必须抢占 Exact 焦点，请在控制器上启用；若希望瞥视打断锁定而不是并入其中，则将 LockBlocksGlances 关闭	GazeHandle.Outcome 显示为 Taken 而不是 Interrupted 或 HeldEyeContactInstead，以及 Settled 完成时 true
当它本应匹配某个已知约定时，装配报告为 Custom 或 Generic	没有匹配 ARKit/CC3/CC4 Extended/MetaHuman 命名，因此骨骼被解析为基于名称的候选项，而不是已编写的映射	添加 StandardRigBinding (Convai > 具身化 > Character Rig) 并验证 Head/Eye 分配，或者为一种 CustomRigConventionMap 非标准约定编写一个	设置选项卡会将映射显示为已编写，而不是信息级别的“候选项”发现
角色从背后面对玩家时，从不转动身体	Head & Body 阶梯的脚部阶段从未激活，或者重复的装配绑定阻止了解析	确认只有一个 StandardRigBinding 存在于角色的 EmbodimentContext 根节点下；检查配置文件的 头部与身体 脚部设置	当角色从其头/眼可达范围之外被呼叫时，会转身面对玩家

眼睛保持静止，而头部转动

眼部运动取决于已解析的眼睛后端，而后端的选择是确定性的：先看成对的 LeftEye/RightEye 骨骼映射胜出，然后是完整的双眼 EyeLook* BlendShape 集合（全部四个 EyeLookInLeft, EyeLookOutLeft, EyeLookInRight, EyeLookOutRight） 只解析出一个眼部骨骼，而且没有找到完整的双眼 EyeLook* 后端，因此凝视安全地使用仅头部后端 在这种情况下，或者 没有找到任何眼部骨骼，也没有找到 EyeLook* BlendShape——眼部阶段将优雅地使用仅头部凝视 当两者都完全未解析时。映射缺失的眼部骨骼，或编写完整的四形状集合，并重新检查设置选项卡。

如果配置文件的 眼部驱动模式 被强制为某个特定后端，而不是保持为 自动，那么该强制模式与装配实际提供内容不匹配时会记录 眼部后端被强制为 Bones，但未解析出 LeftEye/RightEye 骨骼对 或 眼部后端被强制为 Blendshapes，但未解析出 EyeLook* 形状 ——请将模式切回 自动 ，或者修复装配映射。

头部不会转向目标

ConvaiGazeController 会记录日志 没有映射 Head 骨骼——在它存在之前，头部/眼部凝视会保持不动 当完全没有语义 Head 骨骼解析出来时；在有一个之前，头部和眼部凝视都会保持不动。如果 StandardRigBinding 存在但其 Head 字段为空，则消息改为 装配绑定没有语义 Head 映射。无论哪种情况，都请在 Convai > 具身化 > Character Rig中分配 Head，或者确认装配使用的是可识别的骨骼名称，这样基于名称的回退才能找到它。缺失 Neck 骨骼并不会阻挡——头部会独自承担完整摆动，只是略微更僵硬——而且只会产生一条信息性备注。

目标从不会被选中

在考虑相关性或距离之前，目标会先在优先级层级中竞争：玩家锚点发布在 10，其他 Convai 角色在 7，以及 ConvaiGazeTarget/WorldObjectGazeTargetProvider ，世界对象默认为 5。当角色正在对话时，低于玩家层级的世界对象永远不会获胜——这是预期行为，不是 bug。确认该对象确实携带 ConvaiGazeTarget （拖放即可，无需其他设置），它位于其配置的 最大距离内，并且其 基础相关性 大于零。仅当该对象应完全压过玩家时才提高 优先级 提高到 10 （一个“关注这里”的剧情）。如果角色上完全没有目标提供器，并且 自动创建玩家锚点 关闭，则设置选项卡会报告 不存在目标提供器且自动创建已关闭——角色只会显示环境式静态待机生命感；启用该开关，或手动添加一个目标提供器。

脚本化凝视被拒绝或被吸收

GazeAt 和 GlanceAt 请求会故意以不同方式与眼神交流锁定交互。在 GazeFocusFidelity.Exact时，一个显式的 GazeAt 下会被直接拒绝，而其 GazeHandle 会立即完成，并带有 Outcome == Interrupted ，除非 AllowScriptedOverridesDuringExactFocus 已启用——这对绝不会打破焦点的自助终端和演示者设置是刻意如此。在 GazeFocusFidelity.Social, GazeAt 下它仍然会抢占锁定，因此在那里被拒绝的请求指向另一个原因（一个从未解析出的目标，或者请求立即被更高优先级覆盖）。

GlanceAt 遵循一个单独的标志：当眼神交流锁定处于活动状态且 LockBlocksGlances 开启时（默认），瞥视会被吸收——其句柄完成时带有 Outcome == HeldEyeContactInstead 并且永远不会真正完成，因为角色选择与人保持眼神交流，而不是看向那个东西。若希望瞥视改为打断锁定，请将 LockBlocksGlances 关闭。

未检测到装配约定

ConvaiGazeController 通过 StandardRigBinding解析骨骼，回退到 Humanoid Avatar 映射，然后再回退到内置的通用名称列表。当既没有已编写的绑定也没有 Humanoid avatar 时，设置选项卡会将解析出的骨骼报告为一个 候选项 ，而不是已验证的映射——找到了已识别的名称，但尚未有任何内容确认它们。添加 Convai > 具身化 > Character Rig，使用 捕获已解析的映射 作为起点，并在发布前验证每个 Head/Eye 分配。请保持只有一个 StandardRigBinding 位于角色的 EmbodimentContext 根节点下：重复项会被拒绝，并显示 此角色下存在多个 Character Rig 组件。请在 Embodiment Context 根节点上只保留一个，因为根绑定具有权威性，含糊的编写会被拒绝，而不是被猜测。

如果装配的头部骨骼没有以本地 +Z 作为角色视觉前方、以 +Y 作为上方，那么无论匹配到了哪种约定，角色都会横着瞄准。使用设置选项卡中的装配报告来测量角度，并在编辑模式下使用场景视图的前向射线小工具，在发布前确认修复。

身体转向不会发生

全身转向是 Head & Body 阶梯的最后阶段——只有在头部和胸部已经用尽它们能承担的份额后，脚部才会激活，因此位于头/眼/胸可达范围内的目标根本不会调用身体；这是正常的。如果目标确实需要身体转向却没有发生，请确认角色此时没有在行走：在移动过程中，移动系统掌控角色朝向，而由凝视驱动的身体转向会被刻意停用，这样两个系统就不会争夺同一个旋转。若存在 Body Animation 模块，身体转向会使用动画化的原地转身片段，并要求 启用原地转身 在其配置中；没有该模块，或者它拒绝时，则会自动改用程序化的根部转向，并且只记录一次该回退。如果目标在身体转向之后仍超出了头部和眼睛的物理可达范围，则追踪日志会记录 凝视无法完全到达“<target>”——持续的 N° 残差（目标位于头/眼包络之外） 中声明所需权限，位置为 State 详细程度，这属于无法到达目标的可诊断情况，而不是静默失败。

下一步

Gaze凝视目标与提供器脚本化凝视