> 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-quick-start.md).

# 视线注意快速入门

在其上启用凝视注意力 `UConvaiPlayerComponent`，标记一个世界 Actor，使其可以接收注意力，并验证玩家将视线停留在其上后，Convai 角色会识别该对象。最后，当玩家注视该 Actor 达到 `GazeAttentionDelay` 持续时间（默认值：1.0 秒）。

### 先决条件

在启用凝视注意力之前，请确认以下内容：

* Convai Unreal Engine 插件已安装，并且 API 密钥已配置。参见 [安装 Convai 插件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md).
* 你的关卡包含一个 `UConvaiChatbotComponent` 位于 AI 角色上，以及一个 `UConvaiPlayerComponent` 位于玩家 Pawn 上，并且具有有效的 `CharacterID` 以及一个可用的麦克风会话。
* **启用操作** 在聊天机器人上已勾选。请选择该聊天机器人在 **大纲视图**，打开 `UConvaiChatbotComponent` 在 **Details** 面板，展开 **Convai | 操作** → **环境**，并确认 **启用操作** (`bEnableActions`）已开启。凝视注意力会写入聊天机器人的注意力槽，这要求在会话连接时操作系统处于激活状态。如果尚未设置操作，请遵循 [角色动作快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/character-actions-quick-start.md) 。

{% hint style="info" %}
如果你还没有标记任何世界对象，请先完成 [场景元数据快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-quick-start.md) 后再继续。凝视注意力至少需要一个 `UConvaiObjectComponent` 并带有非空 **名称**.
{% endhint %}

### 启用凝视注意力并标记一个对象

{% stepper %}
{% step %}

#### 选择玩家 Pawn

在 **大纲视图** （或者 **内容浏览器**，如果正在编辑 Blueprint），打开包含该内容的 Actor 或 Blueprint `UConvaiPlayerComponent`.
{% endstep %}

{% step %}

#### 打开总开关

选择 `UConvaiPlayerComponent` 在 **Details** 面板。在 **Convai | 凝视注意力**，勾选 **启用凝视注意力** (`bEnableGazeAttention`）。默认值为 `false`；在此开启之前，其余所有凝视设置都会保持灰显。
{% endstep %}

{% step %}

#### 设置响应模式

设置 **凝视应响应** (`GazeShouldRespond`）为 `始终`。默认值为 `从不`，这会静默更新注意力槽，而不会请求角色进行语音回复。

在 **凝视注意力文本** (`GazeAttentionText`），输入一句简短的话，例如 `"玩家正在看这个对象。"`。当注意力提升时，Convai 会将此文本用作叙事事件。
{% endstep %}

{% step %}

#### 标记一个世界 Actor

点击关卡中的任意道具——例如箱子、门或一件设备。在 **Details** 面板中，点击 **添加组件** 并搜索 **Convai Object Component**。选择它以添加一个 `UConvaiObjectComponent`.

展开 **Convai | 对象** 并设置：

* **名称** ——一个简短标签，例如 `"SafetyValve"`.
* **说明** ——一句话，例如 `"西侧墙上的红色紧急阀门。"`

在 **Convai | 对象 | 凝视**，确认 **可凝视** (`bGazeable`）已勾选时。当 `bGazeable` 为 `false`时，该对象将完全从凝视管线中排除。
{% endstep %}

{% step %}

#### 进入播放模式并注视该对象

按 **播放**。将准星对准已标记的 Actor，并保持在那里。

你应该会看到三个阶段的反馈：

1. **立即** ——对象上会出现视觉高亮（UE 5.3+ 显示浅黄色覆盖层，UE 5.0–5.2 显示线框框），而中心光标点会变为白色。
2. **在……之后 `GazeAttentionDelay` 秒** （默认 1.0 秒）—— `OnAttentionGained` 会触发，并更新聊天机器人的注意力槽。
3. **不久之后** ——角色开始说话，因为 `GazeShouldRespond` 被设置为 `始终`.
   {% endstep %}
   {% endstepper %}

{% hint style="success" %}
当凝视注意力正常工作时：准星一进入对象就会出现高亮，光标点变为白色，并且——在凝视保持 `GazeAttentionDelay` 秒后——角色开始说出回应。
{% endhint %}

如果高亮从未出现，请参阅 [排查凝视注意力问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/troubleshoot-gaze-attention.md)。如果高亮出现但角色保持沉默，请确认 **启用操作**, `GazeShouldRespond`，以及 `GazeAttentionText` 在玩家组件上。

### 下一步

{% 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/2f301cf695f654f0b6dc66672ff9462854021237" %}
[注视注意力使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-usage-examples.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-quick-start.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.