> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/troubleshooting.md). # 排查视线问题 修复 Convai Gaze 角色中静止的眼睛、不会转动的头部、未选中的视线目标以及被拒绝的脚本视线。 从角色本身开始诊断： `ConvaiGazeController` 检查器的 **设置** 部分和 **Convai > 凝视编辑器**的 **设置** 选项卡会报告相同的骨架结果——哪些骨骼已解析、当前启用的是哪种眼部后端，以及朝向检查——而且是在你按下 Play 之前。本页覆盖报告未能解释的症状，以及下面列出的运行时行为。 ### 症状、原因与修复 | 症状 | 可能原因 | 修复方法 | 验证 | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | 眼睛从不移动；只有头在转 | 没有解析出眼骨，也没有完整的 `EyeLook*` 表情混合形集合，因此凝视回退为仅头部运动 | 映射 `左眼`/`右眼` 骨骼到骨架上，或者提供全部四个水平 `EyeLook*` 形状（`EyeLookInLeft`, `EyeLookOutLeft`, `EyeLookInRight`, `EyeLookOutRight`) | 设置选项卡的 **眼部后端** 行报告的是骨骼数量或表情混合形数量，而不是仅头部警告 | | 头和眼睛停留在动画将它们放置的位置 | 否 `ConvaiGazeController` 在角色上，或者未解析出语义上的 Head 骨骼 | 添加 `ConvaiGazeController` (**Add Component > Convai > Embodiment > Gaze**）；对于 Generic 或无需动画师的骨架，请添加 **Convai > Embodiment > Character Rig** 并分配 Head | 缺失 Head 骨骼的控制台警告会消失，并且检查器会显示 **就绪** | | 世界物体从不被选为凝视目标 | 该物体没有 `ConvaiGazeTarget`，或者它的优先级（默认 `5`）从未超过玩家锚点的 `10` | 添加 `ConvaiGazeTarget` (**Add Component > Convai > Gaze > Target**）；提高 **优先级** 高于 `10` 以超过玩家 | 该物体在选中时会显示线框手柄，并且会作为当前目标出现在 Gaze Editor 的 **实时** 选项卡 | | `GazeAt`/`GlanceAt` 调用没有可见效果 | `GazeFocusFidelity.Exact` 处于激活状态，且 `AllowScriptedOverridesDuringExactFocus` 关闭，或者 `LockBlocksGlances` 在眼神接触锁定期间吸收了一次瞥视 | 启用 `AllowScriptedOverridesDuringExactFocus` 如果脚本请求必须抢先于 Exact 聚焦，请在控制器上开启 `LockBlocksGlances` 如果希望瞥视打断锁定，而不是被并入锁定，请关闭 | `GazeHandle.Outcome` 显示 `Taken` 中调用的，而不是在 `被打断` 或 `HeldEyeContactInstead`以及 `Settled` 完成 `是` | | 当它应该匹配某个已知约定时，骨架却报告为 Custom 或 Generic | ARKit/CC3/CC4 Extended/MetaHuman 命名未能匹配，因此骨骼被解析为基于名称的候选，而不是一个已编制的映射 | 添加 `StandardRigBinding` (**Convai > Embodiment > Character Rig**）并验证 Head/Eye 分配，或者为非标准约定编写一个 `CustomRigConventionMap` 用于非标准约定 | 设置选项卡显示的映射是已编制的，而不是信息级别的“Candidate”结果 | | 角色从背后面对玩家时从不转身 | Head & Body 阶梯的脚部阶段从未激活，或者重复的骨架绑定阻止了解析 | 确认恰好存在一个 `StandardRigBinding` 存在于角色的 `EmbodimentContext` 根节点下；检查配置文件的 **头部与身体** 脚部设置 | 当从其头/眼可达范围之外发言时，角色会转身面对玩家 | ### 眼睛保持静止，而头在转动 眼动取决于已解析的眼部后端，而后端的选择是确定性的：成对的 `左眼`/`右眼` 骨骼映射优先，其次是完整的双眼 `EyeLook*` 表情混合形集合（全部四个 `EyeLookInLeft`, `EyeLookOutLeft`, `EyeLookInRight`, `EyeLookOutRight`），否则凝视会优雅地降级为仅头部运动。单个眼骨或不完整的方向集合绝不会单独驱动——设置选项卡会报告 `只有一个眼骨被解析，且未找到完整的双眼 EyeLook* 后端，因此凝视安全地使用仅头部后端` 在这种情况下，或者 `未找到任何眼骨和 EyeLook* 混合形——眼部阶段将优雅地使用仅头部凝视` 当两者都完全未解析时。映射缺失的眼骨，或编写完整的四形集合，并重新检查设置选项卡。 如果配置文件的 **眼部驱动模式** 被强制为某个特定后端，而不是保持为 **自动**，那么该强制模式与骨架实际提供内容之间的不匹配会记录 `强制为 Bones 的眼部后端，但未解析出 LeftEye/RightEye 骨骼对` 或 `强制为 Blendshapes 的眼部后端，但未解析出 EyeLook* 形状` ——将模式切回 **自动** 或修正骨架映射。 ### 头部不会朝目标转动 当完全没有语义化骨架绑定被解析时， `ConvaiGazeController` 会记录 `未能解析出任何语义化骨架绑定。向角色根节点添加 StandardRigBinding 并映射 Head（以及可选的 Neck/Eyes）；在存在绑定之前，凝视保持静默。` 如果一个 `StandardRigBinding` 存在，但它的 Head 字段为空，则消息改为 `骨架绑定没有语义化的 Head 映射。在 StandardRigBinding 中分配 Head，或使用可识别的骨骼名称；在 Head 解析之前，头/眼凝视保持静默。` Gaze Inspector 的设置选项卡在进入 Play 模式之前会报告同样的状态，如 `没有映射 Head 骨骼——在其存在之前，头/眼凝视保持静默`。无论哪种情况，都在 **Convai > Embodiment > Character Rig**中分配 Head，或确认该骨架使用可识别的骨骼名称，以便基于名称的回退能够找到它。缺失 Neck 骨骼不会阻塞——头部会独自承担完整摆动，只是会稍微僵硬一些——并且只会产生一条信息提示。 ### 从不选择目标 在考虑相关性或距离之前，目标会先在优先级层级中竞争：玩家锚点的发布优先级为 `10`，其他 Convai 角色为 `7`以及 `ConvaiGazeTarget`/`WorldObjectGazeTargetProvider` ，世界物体默认为 `5`。当角色处于对话中时，低于玩家层级的世界物体永远不会胜出——这是预期行为，不是 bug。确认该物体确实携带 `ConvaiGazeTarget` （拖放即可，无需其他设置），它位于其配置的 **最大距离**内部，并且它的 **基础相关度** 大于零。仅当该物体应完全优先于玩家（一个“就看这里”的场景）时才提高 **优先级** 高于 `10` 。如果角色根本没有任何目标提供器，并且 **自动创建玩家锚点** 关闭，设置选项卡会报告 `不存在目标提供器且自动创建已关闭——角色只会显示环境式的静态待机生命表现`；启用该开关，或手动添加一个目标提供器。 ### 脚本化凝视被拒绝或吸收 `GazeAt` 和 `GlanceAt` 请求会刻意以不同方式与眼神接触锁定交互。在 `GazeFocusFidelity.Exact`时，显式的 `GazeAt` 会被直接拒绝，其 `GazeHandle` 会立即完成，结果为 `结果 == Interrupted` 除非 `AllowScriptedOverridesDuringExactFocus` 已启用——这对 kiosk 和演示者设置是有意为之，它们绝不能打断聚焦。在 `GazeFocusFidelity.Social`, `GazeAt` 仍然会抢先于锁定，因此在那里被拒绝的请求指向另一个原因（目标从未解析，或者请求被立即取代）。 `GlanceAt` 遵循另一项标志：当眼神接触锁定处于激活状态且 `LockBlocksGlances` 开启（默认）时，该瞥视会被吸收——其句柄完成时为 `结果 == 改为保持眼神接触` 并且实际上永远不会真正落定，因为角色选择保持与那个人的眼神接触，而不是看向那个东西。若希望瞥视改为打断锁定，请关闭 `LockBlocksGlances` 。 ### 未检测到骨架约定 `ConvaiGazeController` 通过 `StandardRigBinding`解析骨骼，回退到 Humanoid Avatar 映射，然后回退到内置的通用名称列表。当既没有已编制的绑定也没有 Humanoid avatar 时，设置选项卡会将解析出的骨骼报告为 **候选** ，而不是已验证的映射——找到了可识别的名称，但尚未有任何内容确认它们。添加 **Convai > Embodiment > Character Rig**，使用 **捕获已解析的映射** 作为起点，并在发布前验证每一个 Head/Eye 分配。保持恰好一个 `StandardRigBinding` 在角色的 `EmbodimentContext` 根节点下：重复项会被拒绝，并显示 `此角色下存在多个 Character Rig 组件。请在 Embodiment Context 根节点下仅保留一个`，因为根绑定具有权威性，含糊的编制会被拒绝，而不是被猜测。 如果骨架的头骨骼没有本地 +Z 作为角色视觉前方、+Y 作为上方，那么无论匹配到哪种约定，角色都会朝侧面瞄准。使用设置选项卡的骨架报告测量角度，并在编辑模式下用场景视图的前向射线手柄确认修复后再发布。 ### 身体转身不会发生 全身转身是 Head & Body 阶梯的最后阶段——只有在头和胸已承担了它们所能承担的全部份额之后，脚部才会激活，所以位于头/眼/胸可达范围之内的目标根本不会动用身体；这是预期行为。如果目标确实需要身体转身却没有发生，请确认角色当前没有处于行走中：在移动期间，移动系统拥有角色的朝向，基于凝视的身体转身会被刻意暂停，以免两个系统争夺同一旋转。若存在 Body Animation 模块，身体转身会使用动画化的原地转身剪辑，并且需要 **启用原地转身** 在其配置中；如果没有该模块，或者它拒绝执行，则会自动改用程序化根部转身，并且回退只记录一次。如果目标即使在身体转身后仍位于头和眼睛物理可达之外，则跟踪会记录 `凝视无法完全触及“”——持续的 N° 残余（目标位于头/眼范围之外）` 于 `状态` 详细级别，这属于可诊断的不可达目标情况，而不是静默失败。 ### 找出角色正在看谁 “ `ConvaiGazeController` 检查器的 **实时** 部分， **实时** 的 **Convai > 凝视编辑器**，以及 `Convai.DiagnoseGaze` MCP 工具选项卡都会报告同样的两个事实，因此任意一种都能回答“为什么它不看我？”： * **偏离目标** 是眼睛实际指向的位置与当前目标之间的角度，单位为度。几度以内的小数值属于正常的扫视和注视噪声；如果数值一直很大，说明目标角色实际上无法触及，或者目标从未解析。 * **跟随对话** 因为 `AttendToSpeaker`，或者命名那个把潜在发言者挡在外面的门槛——例如“超出注意距离”、“离这个角色太远在后方”，或者“他们不发布凝视目标”。一个本该转向正在说话的同事却没有转向的角色，会说明到底是哪道门槛在阻挡它，而不是对失败保持沉默。 ### 下一步 {% content-ref url="/pages/9c0e7e779a031a76bbc0834723ae50337d8d6836" %} [视线](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze.md) {% endcontent-ref %} {% content-ref url="/pages/864133eda5776302d8f8f9afeef2de62388e08bc" %} [视线目标与提供器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/targets-and-providers.md) {% endcontent-ref %} {% content-ref url="/pages/0c6914a280e6fc584ecfe676625883fc201033e3" %} [脚本控制的视线](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/scripted-gaze.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.