> 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" %}
如果尚未完成基础设置，请先参阅 [注视注意快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-quick-start.md) 只有在某个具体症状仍然存在时，才返回此处。
{% endhint %}

### 注视对象时对象未高亮显示

**症状：** 玩家直视场景中的 Actor，但未出现轮廓或线框。

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

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

**修复方法：**

1. 在关卡中选择该 Actor。在 **详细信息** 面板中，确认已列出 `UConvaiObjectComponent` ，且其位于 **组件**.
2. 在该对象组件上，展开 **Convai | Object | Gaze** 并确认 **可注视** (`bGazeable`）已勾选。
3. 在玩家 Pawn 上选择 `UConvaiPlayerComponent` 。在 **Convai | Gaze Attention**下，确认 **启用注视注意** 已勾选。
4. 如果该 Actor 使用的自定义网格体将原始组件的碰撞设置为 **无碰撞** ，线条追踪将会穿过它。将碰撞通道至少设置为 **可视性** ，并确认 `UConvaiPlayerComponent` 上的追踪通道与之匹配（`GazeTraceChannel`，默认值 `ECC_Visibility`).
5. 如果角色位于追踪范围之外，请增大 `GazeMaxDistance` （默认值为 5000 cm）。

**验证：** 进入 Play 模式。将准星对准角色。应立即出现高亮效果（UE 5.3 及更高版本中为淡黄色叠加层，UE 5.0–5.2 中为线框框），光标点也应变为白色。

***

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

**症状：** 注视对象时会出现其轮廓，但 `OnAttentionGained` 从未在 `UConvaiPlayerComponent`.

**上触发。** 原因：

* 以下三种情况之一： `玩家未能持续注视同一角色/图元，达到`.
* `GazeAttentionDelay` 设定的时长。
* GazeAttentionDelay `的设置值高于预期。` 蓝图事件绑定到了与运行注视注意力功能不同的

**修复方法：**

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

**验证：** 添加蓝图绑定到 `OnAttentionGained` ，绑定对象为 `UConvaiPlayerComponent` ，并打印屏幕消息。进入 Play 模式，持续注视对象 `GazeAttentionDelay` 秒。此时应显示消息。

***

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

**症状：** `OnAttentionGained` 已触发（通过蓝图打印验证），但角色没有声音。

**原因：** 以下情况之一：

| 原因                                             | 识别方法                                         |
| ---------------------------------------------- | -------------------------------------------- |
| `GazeShouldRespond` 是 `Never`                  | 注意力状态会静默更新；不会请求 LLM 回复。新建的玩家组件默认使用此设置。       |
| **启用操作** 处于关闭状态                                | `SetObjectInAttention` 以及注视分发都不会影响聊天机器人。     |
| `AttentionSource` 为 `Explicit (Blueprint/C++)` | 直接调用 `SetObjectInAttention` 会占用该槽位；注视更新将被拒绝。 |
| 会话未处于活动状态                                      | 本地注意力状态可能会更新，但不会向 Convai 发送请求。               |

**修复方法：**

1. 将 `GazeShouldRespond` 设为 `Always` 在 `UConvaiPlayerComponent`.
2. 在 `GazeAttentionText` 中填写一条描述性语句。如果不填写文本，注意力事件就不包含叙事背景；即使 `ShouldRespond` 设为 `Always`.
3. 在聊天机器人上展开 **Convai | Actions** → **Environment** 并确认 **启用操作** (`EnvironmentData.bEnableActions`) 已勾选。
4. 在运行模式下，查看 `AttentionSource` （位于 `UConvaiChatbotComponent` 的 **Convai | Actions**下）。如果显示 `Explicit (Blueprint/C++)`，请找到设置了 `SetObjectInAttention` 的蓝图调用，并使用空的 `FConvaiObjectEntry`.
5. 确认聊天机器人会话已连接。连接诊断请参阅 [会话生命周期](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md) 。

**验证：** 将 `GazeShouldRespond` 设为 `Always`，进入 Play 模式并注视该对象 `GazeAttentionDelay` 秒。角色应该开始说话。

***

### 诊断 SetObjectInAttention 发出的“无效果”警告

**症状：** 注视提升或直接调用 `SetObjectInAttention` 都不会改变角色的注意对象，并且 Output Log 中会显示一条以 `Warning`级别开头的消息，消息以 `SetObjectInAttention('<name>')` 开头（注视相关警告则以 `[Gaze] TrySetObjectInAttentionFromGaze rejected on '<name>'`).

**原因：** 警告会明确说明调用无效的具体原因，原因总共只有三种：

| 原因                | 识别方法                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 已禁用动作             | 警告文本： `this chatbot's Environment has bEnableActions = false`。注意对象由服务器根据 `action_config`解析，该配置仅在启用动作时发送。                                   |
| 对象不在聊天机器人的环境对象列表中 | 警告文本： `object was not in this chatbot's environment object list — auto-registered it now`。调用仍会自动注册该对象，以供下次使用，但本次调用无法解析该对象。                 |
| 连接时未发送对象          | 警告文本： `object was not among the objects sent to the server at connect time`。会话中途调用 `AddObject` 时，服务器只会将其作为场景元数据更新；只有下次重新连接后，它才会成为可解析的注意目标。 |

**修复方法：**

1. 请在 Output Log 中查看完整警告文本，其中会指出具体适用上述哪种情况。
2. 若动作已禁用，请展开聊天机器人上的 **Convai | Actions** → **Environment** ，并检查 **Enable Actions** (`EnvironmentData.bEnableActions`).
3. 若对象缺失或尚未连接，请在会话开始前注册该对象（通过聊天机器人的 `AddObject` 或关卡中的 `UConvaiObjectComponent` ），使其包含在 `action_config` 在连接时发送。
4. 若要在会话中途添加，请重新连接一次会话；或者接受该对象只有在重新连接后才会成为注意力目标。

**验证：** 修复报告的问题，进入 Play 模式，然后重复之前会记录警告的调用。输出日志中不应再出现 `SetObjectInAttention` 或 `TrySetObjectInAttentionFromGaze` 警告，并且注意力状态应随之生效。

***

### 光标未显示

**症状：** 启用注视追踪时，屏幕中心没有显示圆点。

**原因：** `bShowGazeCursor` 为 `false`，或者光标控件类引用无效，或者光标的 `IdleColor` 透明度为 `0` 且当前注视的不是 Convai 对象。

**修复方法：**

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

**验证：** 将 `bAlwaysShowGazeCursor` 设为 `true`，然后进入 Play 模式。屏幕中心应始终显示一个白点。

***

### 高亮颜色与配置值不符

**症状：** 轮廓已显示，但呈白色，或颜色与 `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.ObjectReference` （Details 面板中的标签为 **对象为**）仍设为 `Whole Actor` （默认值）。在 `ComponentName` 设为 **对象为** 之前，凝视检测会忽略该值。 `Specific Component`.
* 该 `ComponentName` 值与 Actor 上的任何组件都不匹配（拼写错误、组件已重命名或子字符串不匹配）。
* 组件树在运行时发生变化，导致缓存的解析结果不再适用（罕见情况—— `GetResolvedComponent()` 会在每次调用时重新验证缓存，并在验证失败时自动重新扫描）。
* 目标子网格在 `GazeTraceChannel`上未启用碰撞，因此线迹检测永远不会命中它。

**修复方法：**

1. 在 `UConvaiObjectComponent`上，展开 **Object Entry** 并将 **Object Is** 设为 `Specific Component`.
2. 在 Play 模式下，从蓝图调用 `GetResolvedComponent()` ，目标为 `UConvaiObjectComponent` ，并打印返回值。返回 `nullptr` 表示名称未能解析——请在 Details 面板的层级视图中检查组件的准确名称。
3. 确认 `ObjectEntry.ComponentName` 是目标组件在 **Components** 面板中显示的标签的子字符串（例如， `"Handle"` 可匹配 `SM_DoorHandle` ，但无法匹配 `SM_Knob`).
4. 如果演员的组件树是在运行时构建的（程序化生成、动态附加），请在组件树完全构建后再次调用 `GetResolvedComponent()` ——它每次都会针对实时组件树重新检查缓存的匹配项，因此加载时产生的过期结果会在下次调用时得到修正。
5. 确认目标组件已在 `GazeTraceChannel`上启用碰撞。未启用碰撞的组件永远不会被线迹检测命中，因此即使名称解析正确，也不会触发范围限定的匹配。

**验证：** 修正 **Object Is** 和 `ComponentName`后，进入 Play 模式并将准星对准指定的子网格。只有该网格应当高亮显示；演员的其他部分不应受到影响。 `GetResolvedComponent()` 应返回正确的组件引用。

***

### 后续步骤

{% content-ref url="/pages/c5d49eeda517161a96ea3016fa123bc1694b506f" %}
[注视注意力快速开始](https://docs.convai.com/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" %}
[注视注意力的工作原理](https://docs.convai.com/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" %}
[注视注意力参考](https://docs.convai.com/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" %}
[注视注意力使用示例](https://docs.convai.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
