> 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/character-actions/attention-and-reference-grounding.md).

# 注意力与引用锚定

了解 Convai Unreal Engine 插件如何解析代词引用和注意力目标，从而让角色理解玩家指的是哪个对象。

大多数角色动作无需任何注意力设置即可工作——引用参数会自动从已注册对象列表中解析。当你希望角色理解诸如“it”、“that”和“there”之类的代词，或当你需要控制角色当前关注哪个对象时，请阅读本页。

当玩家说“Go to it”或“Pick that up”时，单词“it”或“that”必须解析为某个特定对象。该插件通过两个相互关联的机制来解决这一点：引用锚定（将 Convai 输出中的对象名称与已注册环境中的对象对应起来）和注意力（跟踪角色或玩家当前关注的是哪个对象，从而使代词引用能够可预测地解析）。

### 引用锚定

当 Convai 返回一个带有 `引用`-类型参数时，原始值是从已注册对象和角色名称中选出的名称字符串。插件会将该字符串与 `EnvironmentData.Objects` 和 `EnvironmentData.Characters` 按精确的已注册名称进行解析。

结果会存储在 `FConvaiResultParam.RefValue` 中，作为一个已填充的 `FConvaiObjectEntry` （包括实时 `引用` Actor 指针）。无法解析的值会生成一个空的 `FConvaiObjectEntry` 带有空的 `引用`.

引用锚定针对聊天机器人组件上的实时 `FConvaiEnvironmentData` 进行工作。通过 `添加对象` 在运行时添加的对象会立即更新本地环境，因此后续的动作解析可以针对当前本地对象和角色列表进行解析。动作契约会固定角色在下一次重连之前能够执行哪些动作模板，而会话中途的场景上下文更新会刷新场景上下文，而不是扩展连接时的动作目标集合。

### 注意力源优先级

注意力槽采用所有权模型来决定哪个来源可以向其写入：

| 来源   | 优先级 | 由                                            | 可被以下项覆盖    |
| ---- | --- | -------------------------------------------- | ---------- |
| `无`  | —   | 默认/已清除状态                                     | 任何来源       |
| `凝视` | 低   | 通过凝视管线 `UConvaiObjectComponent`              | 另一个凝视事件或显式 |
| `显式` | 高   | 对……的 Blueprint/C++ 调用 `SetObjectInAttention` | 仅另一个显式调用   |

**显式优先。** 一旦 `SetObjectInAttention` 设置了该槽，凝视事件就无法覆盖它，直到发出显式清除为止。

### 注意力槽

注意力槽是一个单一的 `FConvaiObjectEntry` 存储为 `CurrentAttentionObject` 在 `FConvaiEnvironmentData`。插件会将此槽包含在动作配置和场景上下文中，因此当 Convai 解释诸如 `"this"`, `"that"`, `"it"`，以及 `“there”`.

注意力槽在聊天机器人组件上有一个关联的来源标志：

| `EConvaiAttentionSource` 值 | 含义                                                          |
| -------------------------- | ----------------------------------------------------------- |
| `无`                        | 没有对象处于注意力中。                                                 |
| `显式`                       | 对 `SetObjectInAttention` 的 Blueprint 或 C++ 调用会设置该槽。凝视无法覆盖它。 |
| `凝视`                       | 凝视管线已设置该槽。另一次凝视事件可以覆盖它。                                     |

#### 从 Blueprint 设置注意力

调用 `SetObjectInAttention` 在 `Convai 聊天机器人` 组件以显式设置注意力对象：

```
// 蓝图伪代码
SetObjectInAttention(
    AttentionObject: FConvaiObjectEntry,  // 要聚焦的对象
    Text: FString,                         // 可选的上下文事件文本
    ShouldRespond: EC_RunLLMOption,        // Convai 应如何响应
    bFlushImmediately: bool                // 若紧急则绕过防抖
)
```

传入一个空的 `FConvaiObjectEntry` （默认构造，且为空的 `名称`）以清除该槽。

`SetObjectInAttention` 在以下情况下无效： `EnvironmentData.bEnableActions` 是 `false` 在聊天机器人上——Convai 只会在 `action_config` 发送时 `/connect`.

#### 从凝视设置注意力

凝视管线使用 `TrySetObjectInAttentionFromGaze` 和 `TryClearObjectInAttentionFromGaze`。这些受所有权规则约束：

* `TrySetObjectInAttentionFromGaze` 在以下情况下成功： `AttentionSource` 是 `无` 或 `凝视`。它返回 `false` 当该槽为 `显式`时，保留显式所有者不变。
* `TryClearObjectInAttentionFromGaze` 仅当聊天机器人仍将凝视视为所有者时清除该槽 **和** 且期望对象与当前被关注的对象匹配。这样可以防止过时的“失去凝视”事件擦除更新的目标。

`UConvaiObjectComponent` 通过 `NotifyGazeAttentionBegin` 和 `NotifyGazeAttentionEnd`自动驱动这些调用。通常情况下，除非你在构建自定义聚焦系统，否则无需直接调用凝视设置器。关于完整的跟踪管线、高亮行为和组件作用域的目标规则，请参见 [凝视注意力的工作方式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/how-gaze-attention-works.md).

#### AttentionSource 属性

`AttentionSource` 是一个 `瞬态`、Blueprint 可读 `EConvaiAttentionSource` 属性，位于 `UConvaiChatbotComponent`。阅读它以决定你的 Blueprint 逻辑应调用显式还是受凝视约束的设置器：

```
// 蓝图伪代码
// 在设置显式注意力之前，检查当前来源
Source = ChatbotComponent.AttentionSource
// Source == None 或 Gaze → 可安全调用 SetObjectInAttention
// Source == Explicit → 检查你的调用是否应覆盖现有的显式所有者
```

### 如何通过凝视将对象提升为注意力对象

凝视管线通过 `UConvaiObjectComponent`。通常你只需要读取 `AttentionSource` 或直接调用 `SetObjectInAttention` ；下面的步骤说明自动路径如何工作。

当 `UConvaiObjectComponent` 被添加到场景 Actor 上，且玩家看向它时：

1. `UConvaiPlayerComponent`的凝视管线会触发 `NotifyGazeBegin` 在对象组件上，触发 `OnGazedIn`.
2. 当玩家的凝视停留时间超过配置的阈值时， `NotifyGazeAttentionBegin` 会触发。
3. `NotifyGazeAttentionBegin` 会广播到子系统中每个已注册的聊天机器人，并调用 `TrySetObjectInAttentionFromGaze`.
4. 每个聊天机器人都会根据自己的 `AttentionSource`.

当玩家移开视线时， `NotifyGazeAttentionEnd` 会广播 `TryClearObjectInAttentionFromGaze` 到每个聊天机器人。

### 与动作参数解析的关系

当 Convai 返回一个带有 `引用`-类型参数时，值会针对完整的 `对象` 和 `角色` 列表进行锚定——不仅仅是当前注意力对象。注意力对象只会影响 Convai 在玩家使用含糊代词时选择哪个对象。一旦选定，正常的引用锚定路径会将其解析为一个实时的 `引用` 指针。

### LookAtTarget 和 PointAtTarget

`UConvaiChatbotComponent` 公开两个用于动画的已复制 Actor 引用：

* `LookAtTarget` ——角色的 AnimBP 应驱动凝视/IK 朝向的 Actor。
* `PointAtTarget` ——角色手臂 IK 应指向的 Actor。

这些与注意力槽无关，也不会影响对话或动作管线。可从 Blueprint 设置它们来驱动动画状态，而不影响 Convai 解析对象引用的方式。

### 下一步

{% content-ref url="/pages/9d759a9e65c274645e91b88390d8bb2c4762bd80" %}
[配置动作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/configuring-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/8e18d509947b40274dca96b384f432486348198f" %}
[动作 Blueprint 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/actions-blueprint-reference.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/character-actions/attention-and-reference-grounding.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.