> 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 | 对象 | 凝视**).

**修复：**

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

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

***

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

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

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

* 玩家没有在同一个 actor/primitive 上持续凝视足够长时间以达到 `GazeAttentionDelay`.
* `GazeAttentionDelay` 设置得高于预期。
* Blueprint 事件绑定到了另一个 `UConvaiPlayerComponent` 而不是正在运行凝视注意力的那个。

**修复：**

1. 将准星保持在同一个高亮对象上，直到完整的 `GazeAttentionDelay` 持续时间结束。
2. 确认 `GazeAttentionDelay` 未被设置为异常高的值。
3. 将诊断打印绑定到 `OnAttentionGained` 放在同一 `UConvaiPlayerComponent` 且其 **启用注视关注** 已勾选。

**验证：** 添加一个 Blueprint 绑定到 `OnAttentionGained` 位于 `UConvaiPlayerComponent` 并打印屏幕消息。进入 Play 模式并持续凝视该对象 `GazeAttentionDelay` 秒。消息应当出现。

***

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

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

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

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

**修复：**

1. 设置 `GazeShouldRespond` 到 `Always` 位于 `UConvaiPlayerComponent`.
2. 填写 `GazeAttentionText` 并附上一句描述性句子。如果没有文本，注意力事件就没有叙事上下文，即使 `ShouldRespond` 是 `Always`.
3. 在聊天机器人上展开 **Convai | 操作** → **环境** 并确认 **启用操作** (`EnvironmentData.bEnableActions`）已勾选。
4. 在 Play 模式下读取 `AttentionSource` 位于 `UConvaiChatbotComponent` （在 **Convai | 操作**）。如果它显示 `显式（Blueprint/C++）`，找到设置 `SetObjectInAttention` 并使用空的 `FConvaiObjectEntry`.
5. 确认聊天机器人会话已连接。请参阅 [会话生命周期](/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 显示一条 `警告`级别消息，开头为 `SetObjectInAttention('<name>')` （或者，对于凝视， `[Gaze] TrySetObjectInAttentionFromGaze rejected on '<name>'`).

**原因：** 该警告会指出调用无效的确切原因。它总是以下三种之一：

| 原因              | 如何识别                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------- |
| 动作已禁用           | 警告文本： `此聊天机器人的 Environment 中 bEnableActions = false`。注意力在服务器端根据 `action_config`进行解析，而它只会在启用动作时发送。 |
| 对象不在聊天机器人的环境列表中 | 警告文本： `对象不在此聊天机器人的环境对象列表中——现已自动注册`。该调用仍会为下次自动注册该对象，但这次尝试无法解析它。                                    |
| 对象未在连接时发送       | 警告文本： `对象不在连接时发送到服务器的对象之列`。会话进行中的 `AddObject` 调用到达服务器时仅作为场景元数据更新——只有在下次重新连接后才会成为可解析的注意力目标。        |

**修复：**

1. 请在 Output Log 中阅读完整警告文本——它会说明适用的是哪一种条件。
2. 对于已禁用的动作，展开 **Convai | 操作** → **环境** 在聊天机器人上并检查 **启用操作** (`EnvironmentData.bEnableActions`).
3. 对于缺失或尚未连接的对象，请注册该对象（通过聊天机器人的 `AddObject` 或一个 `UConvaiObjectComponent` 在关卡中）在会话开始前完成，这样它就会包含在 `action_config` 连接时发送的对象中。
4. 对于会话进行中的新增，请重新连接一次会话，或者接受该对象只会在重新连接后成为注意力目标。

**验证：** 修复所报告的条件，进入 Play 模式，并重复之前记录警告的调用。Output Log 中不应再出现 `SetObjectInAttention` 或 `TrySetObjectInAttentionFromGaze` 警告，且注意力更改应当生效。

***

### 光标未出现

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

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

**修复：**

1. 确认 **显示凝视光标** (`bShowGazeCursor`) 为 `true` 位于 `UConvaiPlayerComponent`.
2. 在 Play 模式下，将准星直接对准一个带标签的 Convai 对象。光标会切换为 `凝视光标激活颜色` （默认白色）。如果只有在对准 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)` ，并进入 Play 模式。看向带标签的对象时，轮廓应显示为红色。

***

### 凝视会穿透薄墙使后方对象被激活

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

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

**修复：**

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

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

***

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

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

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

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

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

***

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

**症状：** 一个 `UConvaiObjectComponent` 并将 `ObjectEntry.ComponentName` 设置后会高亮整个 actor，而不是只高亮指定的子网格；或者在看向目标部位时根本不出现高亮。

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

* `ObjectEntry.ObjectReference` （Details 面板标签 **对象为**）仍然是 `整个 Actor` （默认值）。凝视会忽略 `组件名称` 直到 **对象为** 是 `特定组件`.
* 该 `组件名称` 值与 actor 上的任何组件都不匹配（拼写错误、组件已重命名，或子字符串不匹配）。
* 组件树在运行时发生了变化，而缓存解析不再适用（罕见—— `GetResolvedComponent()` 会在每次调用时重新验证缓存，并在失败时自动重新扫描）。
* 目标子网格在 `GazeTraceChannel`上没有碰撞，因此射线检测永远不会命中它。

**修复：**

1. 在 `UConvaiObjectComponent`，展开 **对象条目** 并设置 **对象为** 到 `特定组件`.
2. 在 Play 模式下调用 `GetResolvedComponent()` 在 `UConvaiObjectComponent` ，并打印返回值。一个 `nullptr` 结果表示名称未能解析——请检查 Details 面板层级中的确切组件名称。
3. 确认 `ObjectEntry.ComponentName` 是目标组件标签的子字符串，如 **组件** 面板所示（例如 `“Handle”` 匹配 `SM_DoorHandle` 但不匹配 `SM_Knob`).
4. 如果 actor 的组件树是在运行时构建的（程序化生成、动态附加），请在 `GetResolvedComponent()` 组件树完全构建后再次调用——它总会将缓存匹配与实时组件树重新检查，因此加载时的过期结果会在下一次调用时被修正。
5. 确认目标组件在 `GazeTraceChannel`上启用了碰撞。没有碰撞的组件永远不会被射线检测命中，因此即使名称解析正确，范围限定匹配也无法触发。

**验证：** 在修正 **对象为** 和 `组件名称`后，进入 Play 模式并将准星对准特定子网格。只有该网格应高亮；actor 的其他部分应保持不受影响。 `GetResolvedComponent()` 应返回正确的组件引用。

***

### 下一步

{% 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 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.