> 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-unreal-engine-plugin/features/gaze-attention/troubleshoot-gaze-attention.md).

# 排查注视注意力问题

使用此页面来诊断并修复最常见的注视注意力问题。每条内容都遵循“症状 / 原因 / 修复 / 验证”结构。

{% hint style="info" %}
如果你还没有完成基础设置，请先从 [视线注意快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-quick-start.md) 开始，只有在某个特定症状仍然存在时再回到这里。
{% endhint %}

### 注视时对象不高亮

**症状：** 玩家直接看向某个世界中的 Actor，但没有出现轮廓或线框。

**原因（最可能）：** 以下条件之一：

* 该 Actor 没有 `UConvaiObjectComponent`.
* `bEnableGazeAttention` 为 `false` 在玩家组件上。
* `bGazeable` 为 `false` 位于对象的 `UConvaiObjectComponent` （在 **Convai | Object | Gaze**).

**修复：**

1. 在关卡中选择该 Actor。在 **详细信息** 面板中，确认 `UConvaiObjectComponent` 列在 **Components**.
2. 在该对象组件上，展开 **Convai | Object | Gaze** 并确认 **Gazeable** (`bGazeable`）已勾选。
3. 选择 `UConvaiPlayerComponent` 在玩家 Pawn 上。在 **Convai | Gaze Attention**，确认 **启用注视注意力** 已勾选。
4. 如果该 Actor 使用自定义网格，并且 **无碰撞** 被设置在该原语组件上，射线检测会穿透它。将碰撞通道至少设置为 **可见性** 并确认上的检测通道 `UConvaiPlayerComponent` 与之匹配（`GazeTraceChannel`，默认 `ECC_Visibility`).
5. 如果该 Actor 超出了检测范围，请增大 `GazeMaxDistance` （默认 5000 厘米）。

**验证：** 进入播放模式。将准星对准该 Actor。应立即出现高亮（UE 5.3 及以上为淡黄色覆盖层，UE 5.0–5.2 为线框框），而且光标点应变为白色。

***

### 对象已高亮，但注意力从未提升

**症状：** 看向对象时轮廓会出现，但 `OnAttentionGained` 从未在……上触发 `UConvaiPlayerComponent`.

**原因：** 以下三个条件之一：

* 玩家没有持续注视同一个 Actor/原语组件足够长的时间以达到 `GazeAttentionDelay`.
* `GazeAttentionDelay` 被设置得比预期更高。
* Blueprint 事件绑定到了不同的 `UConvaiPlayerComponent` 而不是运行注视注意力的那个。

**修复：**

1. 将准星保持在同一个已高亮对象上，直到完整的 `GazeAttentionDelay` 持续时间结束。
2. 确认 `GazeAttentionDelay` 没有被设置为意外偏高的值。
3. 将诊断打印绑定到 `OnAttentionGained` 在同一个 `UConvaiPlayerComponent` 上，该对象已 **启用注视注意力** 勾选。

**验证：** 添加一个 Blueprint 绑定到 `OnAttentionGained` 在 `UConvaiPlayerComponent` 并打印一条屏幕消息。进入播放模式并将视线保持在对象上 `GazeAttentionDelay` 秒。消息应会出现。

***

### 注意力已提升，但角色没有说话

**症状：** `OnAttentionGained` 会触发（可通过 Blueprint 打印验证），但角色保持沉默。

**原因：** 以下条件之一：

| 原因                                      | 如何识别                                            |
| --------------------------------------- | ----------------------------------------------- |
| `GazeShouldRespond` 为 `从不`              | 注意力会静默更新；不会请求 LLM 回复。新建玩家组件默认如此。                |
| **启用动作** 已关闭                            | `SetObjectInAttention` ，且注视分发对聊天机器人没有影响。        |
| `AttentionSource` 为 `显式（Blueprint/C++）` | 一次直接的 `SetObjectInAttention` 调用会占用该槽位；注视更新会被拒绝。 |
| 会话未激活                                   | 本地注意力状态可能会更新，但不会有请求到达 Convai。                   |

**修复：**

1. 设置 `GazeShouldRespond` 到 `始终` 在 `UConvaiPlayerComponent`.
2. 填入 `GazeAttentionText` 一条描述性句子。没有文本时，注意力事件不包含叙事上下文，即使 `ShouldRespond` 为 `始终`.
3. 在聊天机器人上，展开 **Convai | Actions** → **环境** 并确认 **启用动作** (`EnvironmentData.bEnableActions`）已勾选。
4. 在播放模式下，读取 `AttentionSource` 在 `UConvaiChatbotComponent` （在 **Convai | Actions**）。如果显示 `显式（Blueprint/C++）`，找到设置了 `SetObjectInAttention` 的 Blueprint 调用，并用一个空的 `FConvaiObjectEntry`.
5. 确认聊天机器人会话已连接。请参阅 [会话生命周期](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md) 以获取连接诊断。

**验证：** 设置 `GazeShouldRespond` 到 `始终`，进入播放模式，并看向该对象 `GazeAttentionDelay` 秒。角色应该开始说话。

***

### 光标未出现

**症状：** 当注视跟踪开启时，屏幕中央没有可见的点。

**原因：** `bShowGazeCursor` 为 `false`，或者光标小部件类引用无效，或者光标 `IdleColor` 的 alpha 值为 `0` ，且当前视线并未落在 Convai 对象上。

**修复：**

1. 确认 **显示注视光标** (`bShowGazeCursor`）为 `true` 在 `UConvaiPlayerComponent`.
2. 在播放模式下，将准星直接对准一个带标签的 Convai 对象。光标会切换为 `GazeCursorActiveColor` （默认白色）。如果只有在对准 Convai 对象时才出现，则说明工作正常——空闲状态按设计是透明的。
3. 要使光标始终可见，请将 **始终显示注视光标** (`bAlwaysShowGazeCursor`）设置为 `true`.
4. 如果光标仍未出现，请检查 `GazeCursorWidgetClass` 没有被设置为已删除或重命名的类。

**验证：** 设置 `bAlwaysShowGazeCursor` 到 `true`，进入播放模式。屏幕中央应始终可见一个白点。

***

### 高亮颜色与配置值不一致

**症状：** 轮廓出现了，但呈白色或与中设置的颜色不同 `GazeHighlightColor`.

**原因（UE 5.3+）：** 自定义的 `GazeOverlayMaterial` 未暴露一个 `EmissiveColor` 向量参数，因此无法应用颜色。

**原因（UE 5.0–5.2）：** 线框回退（`DrawDebugBox`）使用 `GazeHighlightColor`，但不使用 `GazeOverlayMaterial` 或 `GazeHighlightEmissiveIntensity`。仅修改材质对回退路径没有影响。

**修复：**

1. 如果使用自定义的 `GazeOverlayMaterial`，请确认该材质暴露了一个名为 `EmissiveColor`的向量参数。只有这个参数名会被高亮系统驱动。
2. 在 UE 5.0–5.2 中，请直接设置 `GazeHighlightColor` ，因为高亮外观仅限于线框框。升级到 UE 5.3 或更高版本以使用覆盖层材质系统。
3. 如果 `GazeOverlayMaterial` 未设置，且 UE 5.3+ 的轮廓为白色（而不是淡黄色），则插件资源 `/ConvAI/Highlights/M_ConvaiGazeOverlay` 可能已从烘焙构建中被剥离。回退材质 `/Engine/EngineMaterials/EmissiveMeshMaterial` 没有参数。请重新打包插件内容。

**验证：** 设置 `GazeHighlightColor` 为饱和红色 `(1.0, 0.0, 0.0, 1.0)` 并进入播放模式。看向带标签的对象时，轮廓应显示为红色。

***

### 注视会选中薄墙后方的对象

**症状：** 当玩家朝那个方向看时，墙或地板另一侧的对象会被高亮。

**原因：** 世界几何体没有阻挡 `GazeTraceChannel` ——通常是因为该网格使用了 **无碰撞** 或者通道被设置为 **忽略**.

**修复：**

1. 选择墙体或地板网格。在 **详细信息** 面板中的 **碰撞**，确认 `GazeTraceChannel` （默认 `ECC_Visibility`）已设置为 **阻挡**.
2. 或者，将 `GazeTraceChannel` 在 `UConvaiPlayerComponent` 更改为仅让可交互对象和阻挡几何体响应的自定义通道。

**验证：** 进入播放模式并看向墙面。另一侧的对象应该不再高亮。

***

### 角度容差导致错误对象被高亮

**症状：** 玩家看向一个对象，但却高亮了附近的另一个对象。

**原因：** `GazeAngleTolerance` 设置得过高，导致点积回退更偏向于一个更大或位置不同、与视线方向更对齐的对象。

**修复：** 降低 `GazeAngleTolerance` （默认 5 度，高级显示）。如果对象需要精确瞄准，请将 `GazeAngleTolerance` 到 `0` 设为关闭回退，并要求必须直接命中射线检测。

**验证：** 设置 `GazeAngleTolerance` 到 `0` 并进入播放模式。只有当准星直接位于对象上方时，对象才应高亮。

***

### 组件范围高亮出现在错误的子网格或整个 Actor 上

**症状：** 一个 `UConvaiObjectComponent` 与 `ObjectEntry.ComponentName` 将高亮设置为整个 Actor，而不是仅命名的子网格，或者在看向目标部分时根本不出现高亮。

**原因：** 以下四种条件之一：

* `ObjectEntry.MoveTargetMode` 仍然是 `以 Actor 为目标` （默认值）。注视会忽略 `ComponentName` 直到 **移动目标模式** 为 `以组件为目标`.
* 该 `ComponentName` 值与该 Actor 上的任何组件都不匹配（拼写错误、组件重命名或子字符串不匹配）。
* 组件树在运行时发生了变化，缓存的解析结果已过期。
* 目标子网格在 `GazeTraceChannel`上没有碰撞，因此射线检测永远不会命中它。

**修复：**

1. 在 `UConvaiObjectComponent`，展开 **对象条目** 并设置 **移动目标模式** 到 `以组件为目标`.
2. 在播放模式下，调用 `GetResolvedComponent(true)` 在 `UConvaiObjectComponent` 在 Blueprint 中并打印返回值。一个 `nullptr` 结果表示名称未解析——请检查 Details 面板层级中的确切组件名称。
3. 确认 `ObjectEntry.ComponentName` 是目标组件标签中的子字符串，如 **Components** 面板中所示（例如， `"Handle"` 匹配 `SM_DoorHandle` 但不匹配 `SM_Knob`).
4. 如果该 Actor 的组件树是在运行时构建的（程序生成、动态附加），请在 `GetResolvedComponent(true)` 在树完全构建后再调用，而不是依赖加载时的缓存结果。
5. 确认目标组件在 `GazeTraceChannel`上已启用碰撞。没有碰撞的组件永远不会被射线检测命中，因此即使名称正确解析，范围匹配也不会触发。

**验证：** 修正 **移动目标模式** 和 `ComponentName`后，进入播放模式并将准星对准特定子网格。只有该网格应高亮；Actor 的其他部分应保持不受影响。 `GetResolvedComponent(false)` 应返回正确的组件引用。

***

### 下一步

{% content-ref url="/pages/c5d49eeda517161a96ea3016fa123bc1694b506f" %}
[视线注意快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/d8a57f062e27764c8ec780df8b4e07d5b4d4282b" %}
[注视注意力的工作方式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/how-gaze-attention-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/797ae18ef94bcef2ec7816f079c7a35fb212a26c" %}
[视线注意力参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/2f301cf695f654f0b6dc66672ff9462854021237" %}
[注视注意力使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-usage-examples.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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/troubleshoot-gaze-attention.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.