> 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/how-gaze-attention-works.md).

# 注视注意力的工作原理

了解注视追踪管道、注意力提升计时器、组件作用域目标、高亮渲染以及注意力源锁定规则。

凝视注意力是 `UConvaiPlayerComponent` 中的一个子系统，可将玩家的视线方向转换为 AI 角色的上下文焦点。启用后，它会在每个 Tick 中运行，通过高亮显示 Actor 和光标 Widget 管理视觉反馈，并在经过可配置的注视时长后写入聊天机器人的“关注对象”槽位。

如果尚未启用凝视注意力，请先阅读 [凝视注意力快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-quick-start.md)。本页将说明该设置背后的思路。

### 三个核心概念

在了解逐 Tick 处理流程前，请先记住以下三个阶段：

| 阶段         | 发生的情况                                                                           | 玩家看到的效果                                    |
| ---------- | ------------------------------------------------------------------------------- | ------------------------------------------ |
| **凝视检测**   | 线性追踪（以及可选的角度回退机制）会找到准星下方可被注视的 `UConvaiObjectComponent` 。                        | 高亮和光标会立即激活。                                |
| **注视时长达标** | 在同一目标上注视 `GazeAttentionDelay` 秒后，该对象会被提升为“关注对象”。                                | 视觉效果不会发生变化； `OnAttentionGained` 会触发。       |
| **注意力归属**  | 每个聊天机器人都会通过 `AttentionSource`记录是谁设置了其注意力槽位。只有当该槽位为 `None` 或当前已归属于凝视时，凝视才能更新该槽位。 | 角色可能会说话，也可能保持沉默，具体取决于 `GazeShouldRespond`. |

带标签的对象来自场景元数据，详见 [场景元数据的工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/how-scene-metadata-works.md)。注意力归属和代词指代解析也与 [注意力与指代解析](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/attention-and-reference-grounding.md).

### Tick 处理流程

每个 Tick 中， `UConvaiPlayerComponent` 会在 `bEnableGazeAttention` 为 `true` 时调用 `TickGazeAttention`。下图展示了完整的决策路径；后续编号列表会详细说明各个阶段。

```mermaid
flowchart TD
    A([TickGazeAttention]) --> B{bEnableGazeAttention?}
    B -- No --> Z([Skip])
    B -- Yes --> C[Line trace along GazeTraceChannel\nup to GazeMaxDistance]
    C --> F[GatherMatchingObjects]
    F --> D{Valid gaze target?}
    D -- Yes --> I[Spawn / update\nAConvaiGazeHighlightActor]
    D -- 否 --> E{AngleTolerance > 0\n且追踪未被\n非 Convai 几何体阻挡？}
    E -- 是 --> G[点积回退：\n遍历子系统对象池]
    E -- 否 --> H([本帧没有注视目标])
    G --> Q{存在回退目标？}
    Q -- 是 --> I
    Q -- 否 --> H
    I --> J[更新 UConvaiGazeCursorWidget\n状态：Active 或 Idle]
    J --> K[更新 GazeAccumulator\n或 NoGazeAccumulator]
    K --> L{GazeAccumulator >=\nGazeAttentionDelay？}
    L -- 是 --> M([提升为注意目标\n触发 OnAttentionGained])
    L -- 否 --> N{NoGazeAccumulator >=\nGazeAttentionLossDelay？}
    N -- 是 --> O([解除注意状态\n触发 OnAttentionLost])
    N -- 否 --> P([继续累积 — 状态不变])
```

1. 从玩家摄像机或 VR HMD 沿前方发起一条线性追踪，追踪通道为 `GazeTraceChannel` （默认值为 `ECC_Visibility`），最大距离为 `GazeMaxDistance` （默认值为 5000 cm）。
2. 系统会检查追踪结果命中的 Actor 上是否存在可注视的 `UConvaiObjectComponent` 。只有当对象作用范围为整个 Actor，或命中的 Primitive 与对象配置的组件作用范围相匹配时，才会接受该注视目标。
3. 如果严格追踪未命中有效的注视目标，那么当 `GazeAngleTolerance` 大于零且主追踪未被非 Convai 几何体阻挡时，会执行点积回退。该回退会遍历子系统中注册的所有 `UConvaiObjectComponent` ，排除超出范围、位于摄像机后方或处于锥形半角范围之外的对象，然后选取与视线方向点积最高的对象。这样无需执行球形追踪物理查询，且判定不受距离影响——远处对象与近处对象所需的屏幕注视容差相同。
4. 注视目标发生任何切换（进入或离开）时，都会在玩家组件上触发 `OnGazeBegin` 或 `OnGazeEnd` ，并更新光标小组件的状态。
5. 两个累加器并行运行： `GazeAccumulator` 统计当前目标被持续注视的时长，而 `NoGazeAccumulator` 统计玩家没有注视任何 Convai 对象的时长。

### 提升注意状态与解除注意状态

当 `GazeAccumulator` 达到 `GazeAttentionDelay` 秒（默认值为 1.0）时，该注视目标会被提升为“处于注意状态”：

* 玩家组件会调用聊天机器人组件的内部方法，并传入该目标对应的 `FConvaiObjectEntry` 以及以下值： `GazeAttentionText` 和 `GazeShouldRespond`。此过程会自动处理，无需连接蓝图节点。
* `OnAttentionGained` 在玩家组件上触发。
* 聊天机器人的 `AttentionSource` 属性被设置为 `EConvaiAttentionSource::Gaze`.

当 `NoGazeAccumulator` 达到 `GazeAttentionLossDelay` 秒（默认为 5.0），且玩家不再注视当前注意力 Actor/Primitive 对时，注意力槽位将被释放：

* 玩家组件调用聊天机器人组件上的内部方法来清除注意力槽位。此过程同样是自动的。
* `OnAttentionLost` 在玩家组件上触发。
* 聊天机器人的 `AttentionSource` 重置为 `EConvaiAttentionSource::None`.

### 注意力来源锁定规则

聊天机器人通过以下属性跟踪最后设置其注意力槽位的来源： `AttentionSource` (`EConvaiAttentionSource`）。 `AttentionSource` 属性位于 `UConvaiChatbotComponent` 上，有三种状态：

```mermaid
stateDiagram-v2
    [*] --> None
    None --> Gaze : TrySetObjectInAttentionFromGaze()
    Gaze --> Gaze : 新的注视目标被提升为注意力目标
    Gaze --> None : TryClearObjectInAttentionFromGaze()\n或失去注意力计时器到期
    None --> Explicit : 从 Blueprint/C++\n调用 SetObjectInAttention()
    Gaze --> Explicit : 从 Blueprint/C++\n调用 SetObjectInAttention()
    Explicit --> None : 使用空的 FConvaiObjectEntry\n调用 SetObjectInAttention()
    Explicit --> Explicit : 使用新对象\n调用 SetObjectInAttention()
```

| 值                          | 含义                                    |
| -------------------------- | ------------------------------------- |
| `None`                     | 注意力槽位为空。                              |
| `Gaze`                     | 槽位最后由注视系统设置。                          |
| `Explicit (Blueprint/C++)` | 槽位最后通过直接调用 `SetObjectInAttention` 设置。 |

仅当 `AttentionSource` 为 `None` 或 `Gaze`时，注视驱动的更新才会成功。直接调用 `SetObjectInAttention` 从蓝图或 C++ 设置 `AttentionSource` 为 `Explicit`，从而锁定该槽位。槽位锁定期间，凝视调用会被拒绝，并记录一条警告日志，说明对象名称和拒绝原因。若要解除显式锁定，请调用 `SetObjectInAttention` 并传入一个空的 `FConvaiObjectEntry`.

{% hint style="warning" %}
如果角色的注意力槽始终锁定在同一个对象上，不随玩家视线变化，请检查是否有蓝图图表在调用 `SetObjectInAttention` 却从未清除该设置。聊天机器人上的 `AttentionSource` 只读属性会显示当前由哪个系统持有该槽位。
{% endhint %}

### 注意力与动作系统

`SetObjectInAttention` 在以下情况下不会生效： `Enable Actions` (`bEnableActions`）在聊天机器人上为 `false` 。只有在连接会话时包含了 `action_config` 区块，Convai 才会解析对象注意力；而包含该区块的前提是启用动作。因此，凝视注意力要求聊天机器人上的动作系统处于启用状态。如果调用因上述原因而无效，或者目标对象尚未列入聊天机器人的环境对象列表，或未包含在连接时发送的对象中，系统就会记录一条警告日志，指出对象名称和具体原因。请参阅 [诊断 SetObjectInAttention 发出的“无效果”警告](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/troubleshoot-gaze-attention.md#diagnose-a-no-effect-warning-from-setobjectinattention).

### 单次刷新的注意力提示

当凝视注意力提升成功（或显式调用 `SetObjectInAttention` 成功），且 `GazeShouldRespond`/`ShouldRespond` 为 `Auto` 或 `Always`时，聊天机器人会暂存一条一次性的事件，内容为 `"<observer> is paying attention to <object name>"` —— `<observer>` 是对话伙伴的名称；如果未设置，则为 "The user"。此提示不会保存在上下文中，并且每次注意力提升只触发一次；注意力持续停留在同一对象上时不会重复触发。默认情况下，此功能处于启用状态；每次调用时可传入 `bAddAttentionEvent = false` 以将其关闭。 `SetObjectInAttention`设置 `ShouldRespond`/`GazeShouldRespond` 以将其关闭。 `Never` 也会抑制该提示，但槽位仍会静默更新。

### 组件级凝视

`ObjectEntry.ObjectReference` (`EConvaiObjectReference`，Details 面板中的标签 **对象是**）会说明该对象对每个读取它的系统而言 *是什么* 。 `FConvaiObjectEntry` ——凝视、移动回退和视觉标记均使用此项。它有两个值：

* **整个 Actor** （默认）——整个 Actor 就是对象。凝视会匹配该 Actor 的任意基元。
* **特定组件** ——一个指定的子组件就是对象。凝视只会匹配该组件。将 `ObjectEntry.ComponentName` 设为目标组件名称中不区分大小写的子字符串；非空的 `ComponentName` 在 `ObjectReference` 仍为 **整个 Actor**.

`GatherMatchingObjects` 会将命中 Actor 上的 `UConvaiObjectComponent` 实例分为两组：

| 组           | 条件                                                                                              | 触发时机                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| 整个 Actor 范围 | `ObjectReference` 为 `Whole Actor`，或为 `ObjectReference` 为 `Specific Component` 且 `ComponentName` | 当该 Actor 没有已解析的组件范围对象时，命中该 Actor 的任意位置都会触发。如果同一 Actor 上有匹配的组件范围对象，则整个 Actor 范围的对象也会随之触发。 |
| 组件范围        | `ObjectReference` 为 `Specific Component` 且 `ComponentName` 解析为该 Actor 上的一个组件                    | 命中基元与已解析的组件匹配（或附加到该组件）                                                                   |

当组件范围对象匹配时，同一 Actor 上的任何整个 Actor 范围对象也会触发（“随带触发”规则）。如果该 Actor 上存在已解析的组件范围对象，但命中基元与其中任何对象都不匹配，则此次命中不会触发任何凝视对象。

**示例——一个包含两个 Convai 对象的门 Actor：**

```
BP_Door
├── ConvaiObjectComponent "Door"        → 对象范围：整个 Actor
└── ConvaiObjectComponent "DoorHandle"  → 对象范围：特定组件，组件名称："Handle"
    └── 指向该 Actor 上的 SM_Handle
```

* 玩家看向门框 → 不会触发凝视对象，因为该 Actor 上存在已解析的组件范围对象，而命中基元与之不匹配。
* 玩家看向把手 → `ConvaiObjectComponent "DoorHandle"` 触发； `ConvaiObjectComponent "Door"` 也会触发（随带触发）。高亮 Actor 的范围仅限于 `SM_Handle` 。

`ComponentName` 匹配采用不区分大小写的子字符串查找。 `GetResolvedComponent()` 每次调用时都会重新验证缓存的匹配项：如果缓存组件的所属对象或名称不再符合筛选条件，就会自动重新扫描，因此即使运行时 Actor 的组件树发生变化，也无需手动调用刷新。未解析的 `ComponentName` 首次尝试解析时会记录一条警告，并且在名称解析成功之前，该组件不会参与限定范围的注视检测。

{% hint style="info" %}
使用组件范围的 `UConvaiObjectComponent` 实例，让单个复杂道具公开多个彼此独立的交互点——每个交互点都有自己的 `Name`, `Description`和注视事件，而无需复制父 Actor。
{% endhint %}

### 视觉反馈

#### 高亮 Actor

识别到注视目标后， `UConvaiPlayerComponent` 会在目标上生成（或复用）一个 `AConvaiGazeHighlightActor` 。该高亮 Actor 使用 `UMeshComponent::SetOverlayMaterial` 为目标的网格着色，该方法适用于 UE 5.3 及更高版本。默认情况下，高亮 Actor 会加载 `/ConvAI/Highlights/M_ConvaiGazeOverlay`，这是一种菲涅耳边缘轮廓材质，由插件源代码引用。该 Actor 会将 `GazeHighlightColor` 写入材质的 `EmissiveColor` 和 `Color` 向量参数，然后将 `GazeHighlightEmissiveIntensity` 写入 `EmissiveIntensity` 标量参数。

在 UE 5.0–5.2 中， `SetOverlayMaterial` 在 `UMeshComponent`上不可用。此时 Actor 会退回使用 `DrawDebugBox` 在目标边界周围绘制线框，粗细和边距分别由 `FallbackBoxThickness` 和 `FallbackBoxPadding`.

控制。 `UConvaiObjectComponent` 匹配时，高亮范围仅限于该特定子网格，而非 Actor 上的所有网格。有关匹配规则，请参阅上文的 [组件范围的注视检测](#component-scoped-gaze) 部分。

#### 光标控件

当注视跟踪处于活动状态时， `UConvaiGazeCursorWidget` 会被添加到视口中，当 `bShowGazeCursor` 为 `true`。该控件有两种视觉状态：

* **空闲** —注视点未落在任何 Convai 对象上。使用 `GazeCursorIdleColor` 绘制（默认 alpha 值为 0，即完全透明）。
* **激活** —注视点落在某个 Convai 对象上。使用 `GazeCursorActiveColor` 绘制（默认为白色）。

状态之间的过渡会在以下时长内插值： `GazeCursorFadeInTime` 和 `GazeCursorFadeOutTime`。当 `bAlwaysShowGazeCursor` 为 `true`时，即使注视点未落在任何 Convai 对象上，光标也会保持激活状态。

该光标是一个纯 C++ 控件，使用 Unreal 的 `FCoreStyle::WhiteBrush`。插件不附带纹理资源。若要显示自定义准星，请在 Blueprint 中派生 `UConvaiGazeCursorWidget` ，重写 `OnGazeStateChanged`，并将该子类赋给玩家组件上的 `GazeCursorWidgetClass` 。

### 后续步骤

{% 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/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 %}

{% content-ref url="/pages/ca4f4235151ab1fee69bb58487611f1c6ec30cc6" %}
[排查凝视注意力问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/troubleshoot-gaze-attention.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/how-gaze-attention-works.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.
