> 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) 首先，如果凝视注意力尚未启用，或者你还没有标记一个世界对象。

### 在 Blueprint 中响应凝视事件

**场景：** 在安全演练模拟中，当玩家看向危险设备时，会将其高亮并播放警告音效。

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

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

该 `ObjectComponent` 事件上的参数携带了 `UConvaiObjectComponent` 已输入的。读取其 `ObjectEntry.Name` 以识别是哪个对象触发了事件。在 Blueprint 中， `ObjectEntry` 会显示为一个结构体引脚 — 展开它以访问 `名称` 字段中。

`OnGazeEnd` 当凝视离开对象时触发，无论注意力是否曾被提升。用它来停止在 `OnGazeBegin`.

**结果：** 警告音会在准星进入已标记对象的瞬间播放——在达到注意力阈值之前就会播放。

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

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

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

```
// Blueprint 伪代码
事件 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` on `UConvaiPlayerComponent`。玩家组件会在广播之前应用高亮， `OnGazeBegin`，因此此事件中的颜色更改会影响下一个被高亮的目标，除非你通过自定义高亮 actor 刷新高亮。

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

### 使用自定义高亮 actor

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

**设置：**

1. 在 Content Browser 中，创建一个新的 Blueprint 类，其父类为 `AConvaiGazeHighlightActor`。将其命名为 `BP_PulsingGazeHighlight`.
2. 在 Blueprint 类默认值中，启用 **Can Ever Tick** （基于 C++ 的类在 UE 5.3+ 中会禁用 Tick）。重写 `Tick` 以动画化 `EmissiveIntensity` ，使用正弦曲线随时间变化。
3. 在 `UConvaiPlayerComponent`中，设置 `GazeHighlightActorClass` 到 `BP_PulsingGazeHighlight`.

玩家组件会自动生成并销毁高亮 actor。 `GetTarget()` 是位于 `GetTargetComponent()` 在 Blueprint 子类中可提供对当前目标的读取访问，如果自定义效果需要附着到它。

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

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

**场景：** 无论玩家看向哪里，叙事片段都必须让角色的注意力保持在简报屏幕上。

{% hint style="info" %}
`SetObjectInAttention` 在 **启用操作** (`EnvironmentData.bEnableActions`）时没有效果 `false` 在聊天机器人上。请在连接此模式之前确认已启用动作。
{% endhint %}

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

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

在此调用之后， `AttentionSource` 在聊天机器人上变为 `Explicit（Blueprint/C++）`。在锁定解除之前，基于凝视的注意力更新会被静默拒绝。

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

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

传入一个空的 `FConvaiObjectEntry` 会清除注意力槽并重置 `AttentionSource` 到 `无`，从而让凝视再次接管。

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

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

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

**设置：**

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

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

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

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

**结果：** 每次凝视进入或离开一个 Convai 对象时，准星都会改变图像，而无需修改玩家 Pawn Blueprint。

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

**场景：** 工厂车间模拟将 Convai 对象放置在彼此 1–2 米范围内。默认的 1 秒停留和 5 秒释放会导致角色对无意的瞥视做出反应。

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

```
// Blueprint 伪代码 — 在 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(true)` 在 `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 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-usage-examples.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.