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

# 视线注意力参考

凝视注意系统中每个属性、事件、方法和类的权威参考。本 [Convai 玩家组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-player-component.md) 和 [Convai 对象组件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-object-component.md) 这些页面只总结各自组件局部的凝视表面；请使用此页面查看完整的跨组件 API、默认值以及特定版本行为。

权威来源： `Source/Convai/Public/ConvaiPlayerComponent.h`, `Source/Convai/Public/ConvaiObjectComponent.h`, `Source/Convai/Public/Gaze/ConvaiGazeHighlightActor.h`, `Source/Convai/Public/Gaze/ConvaiGazeCursorWidget.h`，以及 `Source/Convai/Public/ConvaiChatbotComponent.h`.

### `UConvaiPlayerComponent` — 凝视注意属性

所有属性都位于 **Convai | Gaze Attention** Details 面板中的类别，除非另有说明。

#### 核心开关

| 属性                     | 类型     | 默认值     | 描述                            |
| ---------------------- | ------ | ------- | ----------------------------- |
| `bEnableGazeAttention` | `bool` | `false` | 主开关。其他所有凝视属性都会置灰，直到此项 `true`. |

#### 注意行为

| 属性                       | 类型                | 默认值   | 描述                                                                                   |
| ------------------------ | ----------------- | ----- | ------------------------------------------------------------------------------------ |
| `GazeShouldRespond`      | `EC_RunLLMOption` | `从不`  | 当凝视目标被提升为注意对象时会发生什么。 `Always` — 聊天机器人会立即生成回复。 `自动` — 由 Convai 决定。 `从不` — 仅进行静默状态更新。  |
| `GazeAttentionText`      | `FString`         | `""`  | 随注意提升一并发送的叙事事件文本（例如 `“玩家正在看着阀门。”`）。仅在以下情况下生效： `GazeShouldRespond` 为 `自动` 或 `Always`. |
| `GazeAttentionDelay`     | `float` （秒）       | `1.0` | 高亮对象在被提升为“在注意中”之前的持续注视时长。                                                            |
| `GazeAttentionLossDelay` | `float` （秒）       | `5.0` | 当前注意槽被释放之前的移开注视时长。                                                                   |

#### 射线检测设置

| 属性                   | 类型                                    | 默认值              | 描述                                                                                                                       |
| -------------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `GazeMaxDistance`    | `float` （厘米，AdvancedDisplay）          | `5000.0`         | 从玩家摄像机或 VR HMD 发出的线性射线最大距离。                                                                                              |
| `GazeAngleTolerance` | `float` （度）                           | `5.0`            | 点积回退锥体的半角。当严格射线未能锁定有效凝视目标且未被非 Convai 几何体阻挡时，系统会遍历所有 `UConvaiObjectComponent` 子系统池中的实例，并选取该锥体内与视线方向最对齐的那个。设置为 `0` 即可禁用回退。 |
| `GazeTraceChannel`   | `ECollisionChannel` （AdvancedDisplay） | `ECC_Visibility` | 凝视射线使用的碰撞通道。                                                                                                             |

#### 高亮属性（类别：Convai | Gaze Attention | Highlight）

| 属性                               | 类型                                       | 默认值                          | 描述                                                                                                  |
| -------------------------------- | ---------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------- |
| `GazeHighlightActorClass`        | `TSubclassOf<AConvaiGazeHighlightActor>` | 插件默认值                        | 在被注视对象上生成的高亮演员类。分配子类以自定义视觉效果。                                                                       |
| `GazeHighlightColor`             | `FLinearColor`                           | `(1.0, 0.9, 0.2, 1.0)` （浅黄色） | 传递给高亮演员的 `HighlightColor` 属性后 `SetTarget` 被调用时。                                                     |
| `GazeOverlayMaterial`            | `TSoftObjectPtr<UMaterialInterface>`     | 未设置                          | 覆盖材质。未设置时，插件使用 `/ConvAI/Highlights/M_ConvaiGazeOverlay` （菲涅耳边缘轮廓）。可替换为任何暴露 `EmissiveColor` 向量参数的材质。 |
| `GazeHighlightEmissiveIntensity` | `float` （AdvancedDisplay）                | `2.5`                        | 传递给高亮演员的 `EmissiveIntensity` 标量参数。插件的覆盖材质会将 `EmissiveColor` 在内部乘以该值。                                |

#### 光标属性（类别：Convai | Gaze Attention | Cursor）

| 属性                      | 类型                                     | 默认值              | 描述                                         |
| ----------------------- | -------------------------------------- | ---------------- | ------------------------------------------ |
| `bShowGazeCursor`       | `bool`                                 | `true`           | 在凝视跟踪处于激活状态时显示屏幕中心准星。                      |
| `bAlwaysShowGazeCursor` | `bool`                                 | `false`          | 即使凝视不在 Convai 对象上，也让光标保持 Active 视觉状态。      |
| `GazeCursorWidgetClass` | `TSubclassOf<UConvaiGazeCursorWidget>` | 插件默认值            | 用于光标的小部件类。可用 Blueprint 子类覆盖以自定义准星视觉。       |
| `GazeCursorActiveColor` | `FLinearColor`                         | 白色 `(1,1,1,1)`   | 当凝视位于 Convai 对象上时的光标颜色。                    |
| `GazeCursorIdleColor`   | `FLinearColor` （AdvancedDisplay）       | `(1,1,1,0)` （透明） | 当凝视未指向任何东西时的光标颜色。默认 alpha 为 0 时，光标在空闲时不可见。 |
| `GazeCursorDotSize`     | `float` （Slate 单位，AdvancedDisplay）     | `6.0`            | 光标方块在未缩放 Slate 单位下的边长。                     |
| `GazeCursorFadeInTime`  | `float` （秒，AdvancedDisplay）            | `0.1`            | 从 Idle 到 Active 状态的淡入时长。 `0` 会立即切换。        |
| `GazeCursorFadeOutTime` | `float` （秒，AdvancedDisplay）            | `0.25`           | 从 Active 到 Idle 状态的淡出时长。 `0` 会立即切换。        |

### `UConvaiPlayerComponent` — 凝视事件

所有事件都位于 **Convai | 凝视注意 | 事件** 类别，并使用委托类型 `FConvaiPlayerGazeEvent`.

**委托签名：** `(UConvaiPlayerComponent* PlayerComponent, UConvaiObjectComponent* ObjectComponent)`

| 事件                  | 触发时机                                                                                                                             |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `OnGazeBegin`       | 玩家的凝视进入 Convai 对象的瞬间触发。会在达到任何注意阈值之前触发。                                                                                           |
| `OnGazeEnd`         | 玩家的凝视离开 Convai 对象的瞬间触发，无论注意状态如何。                                                                                                 |
| `OnAttentionGained` | 当被注视对象在经过以下时间后被提升为“在注意中”时： `GazeAttentionDelay` 秒。即使所有聊天机器人都拒绝该更新也会触发（例如当 **启用动作** 关闭或 `AttentionSource` 为 `显式（Blueprint/C++）`). |
| `OnAttentionLost`   | 当“在注意中”槽位被释放时——例如丢失计时器到期、凝视切换到其他对象，或目标演员被销毁。 `ObjectComponent` 可能为 `nullptr` 当注意目标已被销毁时。                                         |

{% hint style="warning" %}
`OnAttentionGained` 在玩家组件上的 `AttentionSource` 在聊天机器人上的 **启用动作** 处于开启状态，以便角色应答。
{% endhint %}

### `AConvaiGazeHighlightActor`

由……生成的轻量级演员 `UConvaiPlayerComponent` ，用于为当前凝视目标提供视觉反馈。

**UE 版本行为：**

* UE 5.3 及更高版本：会向每个 `UMeshComponent` 目标上的 `SetOverlayMaterial`.
* UE 5.0–5.2：回退为 `DrawDebugBox` 围绕目标边界的 `FallbackBoxThickness` 和 `FallbackBoxPadding` 仅在这些版本中控制线框外观。

**Blueprint 方法：**

| 方法                   | 签名                                                                 | 描述                                                                              |
| -------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `SetTarget`          | `(AActor* InTarget, USceneComponent* InTargetComponent = nullptr)` | 应用或清除高亮。传入 `nullptr` 以清除。当 `InTargetComponent` 是一个 `UMeshComponent`时，覆盖层仅限于该组件。 |
| `GetTarget`          | `() → AActor*`                                                     | 对当前目标的只读访问。                                                                     |
| `GetTargetComponent` | `() → USceneComponent*`                                            | 可选的子组件范围。 `nullptr` 当高亮覆盖整个演员时。                                                 |

**属性：**

| 属性                     | 类型                                   | 默认值                    | 描述                                                                                                                                                                  |
| ---------------------- | ------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HighlightColor`       | `FLinearColor`                       | `(1.0, 0.9, 0.2, 1.0)` | 覆盖层的 `EmissiveColor` 参数。转发自 `UConvaiPlayerComponent::GazeHighlightColor`.                                                                                           |
| `EmissiveIntensity`    | `float`                              | `2.5`                  | 写入覆盖材质的标量 `EmissiveIntensity` 参数。插件材质会将 `EmissiveColor` 在内部乘以该值。                                                                                                    |
| `OverlayMaterial`      | `TSoftObjectPtr<UMaterialInterface>` | 未设置                    | 覆盖材质。默认值为 `/ConvAI/Highlights/M_ConvaiGazeOverlay`。回退到 `/Engine/EngineMaterials/EmissiveMeshMaterial` 仅当插件资源在打包构建中缺失时才会使用（注意：该回退材质没有任何参数，因此 `HighlightColor` 不会生效）。 |
| `FallbackBoxThickness` | `float` （AdvancedDisplay）            | `2.0`                  | UE 5.0–5.2 线框盒的线条粗细。                                                                                                                                                |
| `FallbackBoxPadding`   | `float` （AdvancedDisplay）            | `1.05`                 | UE 5.0–5.2 线框盒的范围乘数。                                                                                                                                                |

若要使用自定义高亮视觉效果，请在 Blueprint 中继承 `AConvaiGazeHighlightActor` 并将该子类分配给 `UConvaiPlayerComponent::GazeHighlightActorClass`.

### `UConvaiGazeCursorWidget`

由……绘制的屏幕中心准星小部件 `UConvaiPlayerComponent` 在凝视跟踪激活时。它是一个纯 C++ 小部件，使用 Unreal 的 `FCoreStyle::WhiteBrush` — 插件不附带任何纹理资源。

**Blueprint 方法：**

| 方法                   | 签名                                                   | 描述                                               |
| -------------------- | ---------------------------------------------------- | ------------------------------------------------ |
| `SetGazeActive`      | `(bool bInGazeActive)`                               | 当凝视进入或离开 Convai 对象时由玩家组件调用。                      |
| `IsGazeActive`       | `() → bool`                                          | 返回当前凝视状态。在 `OnGazeStateChanged` 实现中很有用。          |
| `OnGazeStateChanged` | `(bool bInGazeActive)` (BlueprintImplementableEvent) | 在 Blueprint 子类中重写，可在每次状态变化时运行自定义过渡——替换图像画刷或播放动画。 |

**属性：**

| 属性            | 类型                          | 默认值              | 描述                                        |
| ------------- | --------------------------- | ---------------- | ----------------------------------------- |
| `ActiveColor` | `FLinearColor`              | 白色 `(1,1,1,1)`   | 当凝视位于 Convai 对象上时的点颜色。                    |
| `IdleColor`   | `FLinearColor`              | `(1,1,1,0)` （透明） | 当凝视未指向任何东西时的点颜色。默认 alpha 为 0 时，光标在空闲时不可见。 |
| `DotSize`     | `float` （Slate 单位）          | `6.0`            | 光标方块在未缩放 Slate 单位下的边长。                    |
| `FadeInTime`  | `float` （秒，AdvancedDisplay） | `0.1`            | 从 Idle 到 Active 的淡入时长。 `0` 会立即切换。         |
| `FadeOutTime` | `float` （秒，AdvancedDisplay） | `0.25`           | 从 Active 到 Idle 的淡出时长。 `0` 会立即切换。         |

Override `GazeCursorWidgetClass` 在 `UConvaiPlayerComponent` 以切换为 Blueprint 子类。 `SetGazeActive` 在运行时仍会调用重写项。

### `UConvaiObjectComponent` — 凝视表面

标记为 `UConvaiObjectComponent` 的对象会暴露凝视属性、方法和事件（Details 面板类别 **Convai | Object | Gaze**).

#### 属性

| 属性            | 类型                   | 默认值    | 描述                                                                                                                                                                                                                                                                                                              |
| ------------- | -------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bGazeable`   | `bool`               | `true` | 此对象是否参与凝视检测。当 `false`时，该对象将同时从线射线匹配和点积回退中排除。                                                                                                                                                                                                                                                                    |
| `ObjectEntry` | `FConvaiObjectEntry` | —      | 此对象的标识和目标数据。凝视作用域的子网格过滤使用 `ObjectEntry.ComponentName` 当 `ObjectEntry.MoveTargetMode` 为 `以组件为目标` (`Vector`）。参见 [组件范围的视线](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/how-gaze-attention-works.md#component-scoped-gaze) 和 [`FConvaiObjectEntry`](#fconvaiobjectentry). |

#### Blueprint 方法

| 方法                         | 签名                                                                                     | 描述                                                                                                                                                                                         |
| -------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GetResolvedComponent`     | `(bool bForceRefresh = false) → USceneComponent*`                                      | 返回从缓存中解析的子组件 `ObjectEntry.ComponentName`后，在聊天机器人组件上执行。 `true` 以强制重新查找，例如在运行时演员的组件树发生变化后。返回 `nullptr` 当 `ObjectEntry.MoveTargetMode` 不是 `以组件为目标`，当 `ObjectEntry.ComponentName` 为空，或名称无法解析时。 |
| `NotifyGazeBegin`          | `(UConvaiPlayerComponent* Player)`                                                     | 由……调用 `UConvaiPlayerComponent` 当玩家的凝视进入此对象时。也会触发 `OnGazedIn`。可从 Blueprint 调用以模拟该组件上的凝视进入事件。                                                                                                |
| `NotifyGazeEnd`            | `(UConvaiPlayerComponent* Player)`                                                     | 由……调用 `UConvaiPlayerComponent` 当玩家的凝视离开此对象时。也会触发 `OnGazedOut`。可从 Blueprint 调用以模拟凝视离开事件。                                                                                                    |
| `NotifyGazeAttentionBegin` | `(UConvaiPlayerComponent* Player, const FString& Text, EC_RunLLMOption ShouldRespond)` | 由……调用 `UConvaiPlayerComponent` 当此对象被提升为“在注意中”时。也会触发 `OnAttentionGained`。可从 Blueprint 调用，以手动将此对象在任意聊天机器人上提升为注意对象。                                                                           |
| `NotifyGazeAttentionEnd`   | `(UConvaiPlayerComponent* Player = nullptr)`                                           | 由……调用 `UConvaiPlayerComponent` 当此对象从注意状态释放时。也会触发 `OnAttentionLost`后，在聊天机器人组件上执行。 `nullptr` 以在没有特定玩家上下文的情况下释放。                                                                              |

#### 事件

**委托签名：** `FConvaiObjectGazeEvent` — `(UConvaiObjectComponent* ObjectComponent, UConvaiPlayerComponent* PlayerComponent)`

| 事件                  | 触发时机                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| `OnGazedIn`         | 玩家的凝视进入此对象的瞬间触发，在达到任何注意阈值之前。                                                                            |
| `OnGazedOut`        | 玩家的凝视离开此对象的瞬间触发。                                                                                        |
| `OnAttentionGained` | 当凝视系统在持续凝视阈值后提升此对象时触发。聊天机器人接受是单独的步骤，并且在以下情况下可能失败： **启用动作** 关闭或 `AttentionSource` 为 `显式（Blueprint/C++）`. |
| `OnAttentionLost`   | 当此对象从“在注意中”槽位释放时触发。 `PlayerComponent` 可能为 `nullptr` 在目标已销毁的路径上——使用前请先进行空值检查。                            |

### `UConvaiChatbotComponent` — 注意 API

| 成员                     | 签名                                                                                                                                     | 描述                                                                                                                                                                             |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SetObjectInAttention` | `(FConvaiObjectEntry AttentionObject, FString Text = "", EC_RunLLMOption ShouldRespond = Auto, bool bFlushImmediately = false) → void` | 设置聊天机器人当前的注意对象，可选附带叙事上下文文本和 LLM 响应选项。当 `EnvironmentData.bEnableActions` 为 `false` (**启用动作** （在 Details 面板中）。会标记 `AttentionSource` 到 `显式`. `bFlushImmediately` ，并立即发送更新，而不是批处理。 |
| `AttentionSource`      | `EConvaiAttentionSource` (BlueprintReadOnly, Transient)                                                                                | 最后设置注意槽位的是谁。 `无`, `视线`，或 `显式（Blueprint/C++）`。读取此属性可诊断注意锁定。                                                                                                                     |

#### 凝视门控方法

以下方法由凝视系统内部调用，但也可从 Blueprint 调用，用于自定义凝视集成。

| 方法                                  | 签名                                                                                                                                     | 返回                         | 描述                                                                                                                                                                                                                                        |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TrySetObjectInAttentionFromGaze`   | `(FConvaiObjectEntry AttentionObject, FString Text = "", EC_RunLLMOption ShouldRespond = Auto, bool bFlushImmediately = false) → bool` | `true` 如果接受， `false` 如果拒绝， | 仅在以下情况下设置注意槽位： `EnvironmentData.bEnableActions` 为 `true` 和 `AttentionSource` 为 `无` 或 `视线`。成功时，标记 `AttentionSource = Gaze`。静默返回 `false` 当操作被禁用，或者槽位被以下对象锁定时： `显式` 调用者。内部由……使用 `UConvaiPlayerComponent`；对 Blueprint 暴露，用于必须遵守所有权协议的自定义凝视集成。 |
| `TryClearObjectInAttentionFromGaze` | `(FConvaiObjectEntry ExpectedObject) → bool`                                                                                           | `true` 如果已清除， `false` 如果跳过 | 仅在以下情况下清除注意槽位： `AttentionSource == Gaze` 并且当前注意对象匹配 `ExpectedObject`。防止过时或延迟的凝视丢失调用清除已经被其他玩家或系统占用的注意槽位。                                                                                                                                   |

#### `EConvaiAttentionSource`

| 值    | 显示名称              | 含义                                                                 |
| ---- | ----------------- | ------------------------------------------------------------------ |
| `无`  | 无                 | 注意槽位为空。凝视可以占用它。                                                    |
| `视线` | 视线                | 槽位由凝视系统拥有。凝视可以更新或释放它。                                              |
| `显式` | 显式（Blueprint/C++） | 槽位被直接 `SetObjectInAttention` 调用锁定。直到调用者用空的 `SetObjectInAttention`. |

#### `EC_RunLLMOption`

| 值        | 显示名称   | 含义                    |
| -------- | ------ | --------------------- |
| `自动`     | 自动     | 由 Convai 决定是否生成语音回复。  |
| `Always` | Always | 聊天机器人始终生成语音回复。        |
| `从不`     | 从不     | 注意更新静默进行；不会触发 LLM 调用。 |

### `FConvaiObjectEntry`

承载于以下结构体： `UConvaiObjectComponent::ObjectEntry`。凝视注意会读取身份字段，并在组件作用域目标情况下读取下面的移动模式字段。

| 字段               | 类型                       | 默认值           | 凝视相关性                                                                                                         |
| ---------------- | ------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------- |
| `引用`             | `TWeakObjectPtr<AActor>` | `nullptr`     | 此对象条目的演员引用。                                                                                                   |
| `名称`             | `FString`                | `""`          | 发送给 Convai 的对象名称为 `current_attention_object`。对象注册时必须非空。                                                       |
| `描述`             | `FString`                | `""`          | Convai 用于理解该对象的自然语言描述。                                                                                        |
| `MoveTargetMode` | `EConvaiMoveTarget`      | `以 Actor 为目标` | 必须为 `以组件为目标` (`Vector`）用于 `ComponentName` 以将凝视限定到子网格。使用默认 `以 Actor 为目标`时，凝视会将该条目视为整个演员范围，而不管 `ComponentName`. |
| `ComponentName`  | `FString`                | `""`          | 对子组件名称的不区分大小写的子串过滤。凝视仅在以下情况下使用此字段： `MoveTargetMode` 为 `以组件为目标` 并且名称解析为某个组件位于 `引用`.                            |

仅移动字段（`AcceptanceRadius`, `SocketOrBoneName`, `bStepOntoBounds`以及相关输出）记录于 [角色动作参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.md).

### 下一步

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

{% content-ref url="/pages/ca4f4235151ab1fee69bb58487611f1c6ec30cc6" %}
[排查注视注意力问题](/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 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/gaze-attention-reference.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.