> 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` 凝视注意力模式。每个示例都说明了其场景、所需设置以及预期的运行时结果。

完成 [凝视注意力快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-quick-start.md) 如果尚未启用凝视注意力，或者你还没有标记世界对象，请先执行。

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

**场景：** 在安全演练模拟中，当玩家注视危险设备时会高亮显示它，并播放警告音。

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

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

该 `ObjectComponent` 事件上的参数携带了 `UConvaiObjectComponent` 被输入的内容。读取其 `ObjectEntry.Name` 以识别是哪个对象触发了该事件。在蓝图中， `ObjectEntry` 作为结构体引脚暴露——展开它即可访问 `名称` 字段。

`OnGazeEnd` 当凝视离开对象时触发，无论注意力是否曾被提升。可用它来停止在以下位置启动的循环效果： `OnGazeBegin`.

**结果：** 准星一进入已标记对象，警告音就会立即播放——甚至在达到注意力阈值之前。

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

**场景：** 企业入职体验会对可安全交互的项目使用绿色高亮，对受限区域使用红色高亮。

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

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

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

**结果：** 每种对象类型都会获得不同的轮廓颜色，无需额外资源。

### 使用自定义高亮 Actor

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

**设置：**

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

玩家组件会自动生成并销毁高亮 Actor。 `GetTarget()` 和 `GetTargetComponent()` 在蓝图子类中，如果自定义效果需要附加到当前目标上，则可提供对当前目标的读取访问。

**结果：** 每个被凝视的对象都会显示动画化的脉冲光晕，而不是静态的 Fresnel 轮廓。

### 手动将注意力锁定到对象上

**场景：** 叙事段落必须将角色的注意力保持在简报屏幕上，不受玩家视线位置影响。

{% hint style="info" %}
`SetObjectInAttention` 在以下情况下无效： **启用操作** (`EnvironmentData.bEnableActions`）为 `false` 在聊天机器人上。请在连接此模式之前确认已启用动作。
{% endhint %}

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

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

执行此调用后， `AttentionSource` 在聊天机器人上的状态变为 `显式（蓝图/C++）`。在锁定解除之前，基于凝视的注意力更新会被拒绝——该拒绝会在凝视玩家组件上记录警告，说明对象名称和原因。

要在叙事节拍结束时释放锁定：

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

传入一个空的 `FConvaiObjectEntry` 会清空注意力槽并重置 `AttentionSource` 为 `无`，从而允许凝视重新接管。

**结果：** 角色会在过场动画期间专注于简报屏幕，然后恢复正常的基于凝视的注意力。

### 构建自定义光标小部件

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

**设置：**

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

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

4. 开启 `UConvaiPlayerComponent`，设置 `GazeCursorWidgetClass` 为 `BP_TargetReticleCursor`.

`SetGazeActive` 在运行时，玩家组件仍会在自定义类上调用。 `IsGazeActive()` 如果小部件需要在其他地方轮询状态，则可作为蓝图纯函数使用。

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

### 为包含许多近距离对象的模拟调整时序

**场景：** 工厂车间模拟将 Convai 对象放置在彼此相距 1–2 米的位置。默认的 1 秒驻留和 5 秒释放会导致角色对无意间的扫视作出反应。

**设置：** 开启 `UConvaiPlayerComponent`，请在 **Details** 面板中或运行时调整时序属性：

```
// 蓝图伪代码 — 在 BeginPlay 期间调用
获取组件（UConvaiPlayerComponent）
  → 设置 GazeAttentionDelay    = 2.0   // 需要更长时间的刻意凝视
  → 设置 GazeAttentionLossDelay = 2.0  // 离开视线后更快释放注意力
```

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

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

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

**场景：** 工业安全模拟使用一个单独的 `BP_ControlPanel` Actor，它有两个可独立交互的部分：一个 `EmergencyStop` 按钮，以及一个 `FuelGauge` 表盘。查看每个部分都应触发不同的 AI 响应。

**设置：**

1. 选择 `BP_ControlPanel` 在关卡中。在 **Details** 面板中，点击 **添加组件** 两次以添加两个 `UConvaiObjectComponent` 实例。将它们命名为 `ConvaiObject_EmergencyStop` 和 `ConvaiObject_FuelGauge` （组件标签仅用于编辑器中的清晰显示；凝视过滤使用 `ObjectEntry.ComponentName`).
2. 配置 `ConvaiObject_EmergencyStop` 位于 **Convai | 对象** → **对象条目**:
   * **名称** — `"EmergencyStop"`
   * **说明** — `"一个红色蘑菇按钮，可切断整条生产线的电源。"`
   * **对象为** — `特定组件` （子网格范围限定所需）
   * **组件名称** — `"SM_EmergencyStopButton"` （Actor 上 Static Mesh 组件的确切名称）
3. 配置 `ConvaiObject_FuelGauge` 位于 **Convai | 对象** → **对象条目**:
   * **名称** — `"FuelGauge"`
   * **说明** — `"一个显示当前燃油压力（bar）的表盘。"`
   * **对象为** — `特定组件`
   * **组件名称** — `"SM_FuelGaugeDial"`
4. 开启 `UConvaiPlayerComponent`，请确保 **凝视注意力文本** (`GazeAttentionText`）和 **凝视应响应** (`GazeShouldRespond`）已按需配置。

`ObjectEntry.ComponentName` 匹配是不区分大小写的子字符串查找，并且仅在以下情况下适用： **对象为** 是 `特定组件`。在默认 **整个 Actor** 模式下，一个非空的 **组件名称** 不会限定凝视范围。如果名称无法解析，则该组件会从限定范围的凝视检测中排除，并在首次解析尝试时记录警告。调用 `GetResolvedComponent()` 在 `UConvaiObjectComponent` 可在运行时确认匹配——它会自动重新验证，因此不存在单独的刷新调用。

**结果：** 查看 `SM_EmergencyStopButton` 只会高亮该网格并将 `"EmergencyStop"` 提升为注意力。查看 `SM_FuelGaugeDial` 只会高亮该网格并将 `"FuelGauge"`。查看面板框架不会提升任何一个范围限定对象，因为没有配置的组件范围与该命中匹配。

### 下一步

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