> 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).

# 注意与指代锚定

大多数字符动作在无需任何注意力设置的情况下即可工作——引用参数会自动从已注册对象列表中解析。当你希望角色理解像“it”、“that”和“there”这样的代词，或者需要控制角色当前聚焦于哪个对象时，请阅读本页。

当玩家说“Go to it”或“Pick that up”时，单词“it”或“that”必须解析到一个具体对象。该插件通过两个相互关联的机制来解决此问题：引用锚定（将 Convai 输出中的对象名称与已注册环境中的对象进行匹配解析）和注意力（跟踪角色或玩家当前聚焦的对象，以便代词引用能够可预测地解析）。

### 引用锚定

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

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

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

### 注意力源优先级

注意力槽具有一个所有权模型，用于决定哪个来源可以写入它：

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

**显式优先。** 一旦 `SetObjectInAttention` 设置了该槽后，凝视事件在发出显式清除之前都不能覆盖它。

### 注意力槽

注意力槽是一个单一的 `FConvaiObjectEntry` 存储为 `CurrentAttentionObject` 在 `FConvaiEnvironmentData`。插件会将此槽包含在动作配置和场景上下文中，以便 Convai 在解释诸如……之类的歧义引用时拥有当前聚焦对象 `"this"`, `"that"`, `"it"`，以及 `“there”`.

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

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

#### 从 Blueprint 设置注意力

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

```
// Blueprint 伪代码
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` 仅当聊天机器人仍将凝视视为所有者时才清除该槽 **是位于** 且预期对象与当前正在关注的对象匹配。这样可防止过时的“gaze lost”事件清除较新的目标。

`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 逻辑应调用显式设置器还是受凝视门控的设置器：

```
// 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 返回一个带有一个 `Reference`-类型参数时，该值会针对完整的 `Objects` 是位于 `Characters` 列表进行锚定——不只是当前注意力对象。注意力对象只会影响玩家使用歧义代词时 Convai 选择哪个对象。一旦选定，正常的引用锚定路径会将其解析为一个实时的 `Ref` 指针。

### 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" %}
[Actions 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 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/character-actions/attention-and-reference-grounding.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.