> 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-usage-examples.md).

# 注视注意力使用示例

用于注视事件、自定义高亮视觉、组件作用域目标、手动注意力锁定以及构建自定义光标小部件的 Blueprint 方案。

这些蓝图示例展示了最常见的 `UConvaiPlayerComponent` 和 `UConvaiObjectComponent` 注视注意模式。每个示例都说明其场景、所需设置以及预期的运行时结果。

完整 [注视注意快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-quick-start.md) 如果尚未启用注视注意，或尚未为世界对象添加标签，请先完成。

### 在蓝图中响应注视事件

**场景：** 在安全演练模拟中，当玩家看向危险设备时，系统会突出显示该设备并播放警告音。

**设置：** 在玩家 Pawn 的事件图表中，绑定到 `OnGazeBegin` （属于） `UConvaiPlayerComponent`.

```
// 蓝图伪代码 — 在事件图表中连接这些节点
事件 BeginPlay
  → 获取组件 (UConvaiPlayerComponent)
  → 将事件绑定到 OnGazeBegin
      → 自定义事件：OnPlayerGazeBegin(PlayerComponent, ObjectComponent)
          → 在位置播放声音 (WarningCue)
```

事件中的 `ObjectComponent` 参数包含被进入对象的 `UConvaiObjectComponent` 。读取其 `ObjectEntry.Name` 即可识别触发事件的对象。在蓝图中， `ObjectEntry` 以结构体引脚的形式公开 — 展开该引脚即可访问 `Name` 字段。

`OnGazeEnd` 当注视离开对象时触发，无论注意力是否曾达到提升条件。可用它停止在 `OnGazeBegin`.

**结果：** 当准星移入带标签的对象时，警告音会立即播放 — 无需等待达到注意力阈值。

### 按对象类型更改高亮颜色

**场景：** 企业入职体验使用绿色高亮表示可安全交互的物品，使用红色高亮表示受限区域。

**设置：** 绑定到 `OnGazeBegin` 并在高亮下一个对象之前，设置玩家组件上的 `GazeHighlightColor` 。

```
// 蓝图伪代码
事件 OnPlayerGazeBegin(PlayerComponent, ObjectComponent)
  → 分支：ObjectComponent.ObjectEntry.Name == "RestrictedPanel"
      True  → Set GazeHighlightColor (1.0, 0.1, 0.1, 1.0)   // 红色
      False → Set GazeHighlightColor (0.1, 1.0, 0.1, 1.0)   // 绿色
```

`GazeHighlightColor` 在 `BlueprintReadWrite` 已启用 `UConvaiPlayerComponent`中。玩家组件会在广播 `OnGazeBegin`之前应用高亮效果，因此在此事件中更改颜色只会影响下一个被高亮的目标，除非通过自定义高亮 Actor 刷新高亮效果。

**效果：** 每种对象类型都会显示独特的轮廓颜色，无需额外资源。

### 使用自定义高亮 Actor

**场景：** 医疗培训模拟需要脉冲发光效果，而不是静态轮廓。

**设置：**

1. 在内容浏览器中，创建一个新的蓝图类，并将其父类设为 `AConvaiGazeHighlightActor`。将其命名为 `BP_PulsingGazeHighlight`.
2. 在蓝图类默认值中，启用 **允许始终 Tick** （UE 5.3 及更高版本中，基础 C++ 类会禁用 Tick）。重写 `Tick` 以随时间使用正弦曲线为 `EmissiveIntensity` 设置动画。
3. 在 `UConvaiPlayerComponent`中，将 `GazeHighlightActorClass` 设为 `BP_PulsingGazeHighlight`.

玩家组件会自动生成和销毁高亮 Actor。 `GetTarget()` 和 `GetTargetComponent()` 在蓝图子类中提供对当前目标的读取权限，以便自定义效果需要附加到目标上时使用。

**效果：** 所有被注视的对象都会显示动画脉冲发光效果，而不是静态的菲涅耳轮廓。

### 手动锁定对某个对象的注意力

**场景：** 叙事环节必须让角色始终关注简报屏幕，无论玩家看向何处。

{% hint style="info" %}
`SetObjectInAttention` 在以下条件下不会生效： **启用操作** (`EnvironmentData.bEnableActions`）在聊天机器人上为 `false` 。使用此方案前，请确认已启用操作。
{% endhint %}

**设置：** 调用 `SetObjectInAttention` 在叙事片段开始时直接从蓝图调用。

```
// 蓝图伪代码
事件 NarrativeBriefingStart
  → 获取组件 (UConvaiChatbotComponent)
  → SetObjectInAttention
      AttentionObject:（针对 "BriefingScreen" 的 FConvaiObjectEntry）
      Text: "玩家正在查看任务简报。"
      ShouldRespond: Always
      bFlushImmediately: false
```

调用后， `AttentionSource` 在聊天机器人组件上会变为 `Explicit (Blueprint/C++)`。在解除锁定之前，基于注视的注意力更新都会被拒绝——拒绝操作会在注视玩家组件上记录一条警告，说明对象名称和拒绝原因。

要在叙事片段结束时解除锁定：

```
// 蓝图伪代码
事件 NarrativeBriefingEnd
  → SetObjectInAttention
      AttentionObject:（空的 FConvaiObjectEntry——Name 留空）
      Text: ""
      ShouldRespond: Never
```

传入一个空的 `FConvaiObjectEntry` 会清除注意力槽位，并将 `AttentionSource` 重置为 `None`，从而让注视重新接管注意力。

**结果：** 在过场动画期间，角色会一直关注简报屏幕，之后恢复正常的注视驱动注意力。

### 构建自定义光标控件

**场景：** 第一人称模拟游戏需要一个准星图像：当玩家看向 Convai 对象时，图像会从圆点变为目标瞄准标记。

**设置：**

1. 创建一个新的蓝图类，并将其父类设为 `UConvaiGazeCursorWidget`。将其命名为 `BP_TargetReticleCursor`.
2. 添加一个 `Image` 控件到蓝图控件树中。默认将其画刷设为圆点图像。
3. 实现 `OnGazeStateChanged`:

```
// 蓝图伪代码 — 位于 BP_TargetReticleCursor 内部
事件 OnGazeStateChanged(bInGazeActive)
  → 分支：bInGazeActive
      True  → 设置图像画刷 (TargetReticleBrush)
      False → 设置图像画刷 (DotBrush)
```

4. 在 `UConvaiPlayerComponent`上，设置 `GazeCursorWidgetClass` 到 `BP_TargetReticleCursor`.

`SetGazeActive` 仍会在运行时由玩家组件对自定义类调用。 `IsGazeActive()` 可作为 Blueprint 纯函数使用，方便小部件在其他位置轮询状态。

**结果：** 每当视线进入或离开 Convai 对象时，准星都会切换图像，无需更改玩家 Pawn Blueprint。

### 调整时序，以适应近距离对象较多的模拟场景

**场景：** 某工厂车间模拟场景中的 Convai 对象彼此相距 1–2 米。默认的 1 秒注视时间和 5 秒释放时间会导致角色对无意间扫过的视线做出反应。

**设置：** 在 `UConvaiPlayerComponent`中，在 **细节** 面板中调整时序属性，或在运行时调整：

```
// Blueprint 伪代码 — 在 BeginPlay 期间调用
获取组件 (UConvaiPlayerComponent)
  → 设置 GazeAttentionDelay    = 2.0   // 要求更长时间的专注注视
  → 设置 GazeAttentionLossDelay = 2.0  // 移开视线后更快释放注意力
```

这两个属性均为 `BlueprintReadWrite` ，可以在运行时更改，例如在评估阶段收紧容差，在自由探索阶段放宽容差。

**结果：** 角色只有在玩家有意注视两秒后才会提升注意力；玩家移开视线时，角色会迅速释放注意力。

### 公开复杂 Actor 的各个子组件

**场景：** 某工业安全模拟场景使用一个 `BP_ControlPanel` Actor，其中有两个可独立交互的部分：一个 `EmergencyStop` 按钮和一个 `FuelGauge` 旋钮。注视每个部分时都应触发不同的 AI 响应。

**设置：**

1. 在关卡中选择 `BP_ControlPanel` 。在 **细节** 面板中，点击两次 **添加组件** ，添加两个 `UConvaiObjectComponent` 实例。将它们命名为 `ConvaiObject_EmergencyStop` 和 `ConvaiObject_FuelGauge` （组件标签仅用于方便在编辑器中辨识；视线筛选器使用 `ObjectEntry.ComponentName`).
2. 进行配置 `ConvaiObject_EmergencyStop` 位于 **Convai | 对象** → **对象条目**:
   * **名称** — `"EmergencyStop"`
   * **描述** — `"A red mushroom button that cuts power to the whole line."`
   * **对象类型** — `Specific Component` （子网格作用域必填）
   * **组件名称** — `"SM_EmergencyStopButton"` （Actor 上静态网格组件的确切名称）
3. 配置 `ConvaiObject_FuelGauge` 位于 **Convai | 对象** → **对象条目**:
   * **名称** — `"FuelGauge"`
   * **描述** — `"A dial showing current fuel pressure in bar."`
   * **对象类型** — `Specific Component`
   * **组件名称** — `"SM_FuelGaugeDial"`
4. 在 `UConvaiPlayerComponent`上，确保 **注视注意力文本** (`GazeAttentionText`）和 **注视应有响应** (`GazeShouldRespond`）已按需配置。

`ObjectEntry.ComponentName` 匹配采用不区分大小写的子字符串查找，且仅在 **对象类型** 为 `特定组件`。在默认 **整个 Actor** 模式下，非空的 **组件名称** 不会限定注视范围。如果无法解析名称，该组件将被排除在限定范围的注视检测之外，并且首次尝试解析时会记录一条警告。运行时调用 `GetResolvedComponent()` 来 `UConvaiObjectComponent` 确认匹配结果——该方法会自动重新验证，因此无需单独调用刷新方法。

**结果：** 注视 `SM_EmergencyStopButton` 时，仅突出显示该网格体，并提升 `"EmergencyStop"` 的注意优先级。注视 `SM_FuelGaugeDial` 时，仅突出显示该网格体，并提升 `"FuelGauge"`。注视面板框架不会提升任一受限对象的注意优先级，因为没有配置的组件范围与该命中对象匹配。

### 后续步骤

{% 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/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/gaze-attention-usage-examples.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.
