> 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 插件如何解析代词引用和注意力目标，从而让角色理解玩家指的是哪个对象。

大多数角色动作无需设置注意力——引用参数会自动从已注册的对象列表中解析。若要让角色理解“它”“那个”“那里”等代词，或者需要控制角色当前关注的对象，请阅读本页。

玩家说“去那里”或“把那个捡起来”时，“那里”或“那个”必须解析为某个具体对象。插件通过两种相互关联的机制来实现这一点：引用落地（将 Convai 输出中的对象名称与已注册的环境对象进行匹配）和注意力（跟踪角色或玩家当前关注的对象，以便可预测地解析代词引用）。

### 引用落地

当 Convai 返回一个带有 `Reference`类型参数的动作时，其原始值是从已注册的对象名称和角色名称中选出的名称字符串。插件会根据 `EnvironmentData.Objects` 和 `EnvironmentData.Characters` 中的已注册名称进行精确匹配，以解析该字符串。

解析结果会作为已填充的 `FConvaiResultParam.RefValue` FConvaiObjectEntry `FConvaiObjectEntry` （其中包含实时的 `Ref` Actor 指针）。无法解析的值会产生一个空的 `FConvaiObjectEntry` ，其 `Ref`.

引用值为 null `FConvaiEnvironmentData` 引用落地使用聊天机器人组件中的实时 `AddObject` 在运行时通过

### 添加的对象会立即更新本地环境，因此后续动作解析可依据当前本地对象和角色列表进行匹配。动作契约会固定角色在下次重新连接之前可执行的动作模板；会话中途更新场景上下文只会刷新场景上下文，不会扩展连接时确定的动作目标集合。

注意力来源优先级

| 来源     | 注意力槽采用所有权模型，用于确定哪个来源可以写入该槽： | 优先级          | 设置来源                   |
| ------ | --------------------------- | ------------ | ---------------------- |
| `None` | —                           | 可被以下来源覆盖     | 默认/已清除状态               |
| `Gaze` | 任意来源                        | 低 `通过`       | UConvaiObjectComponent |
| `注视管线` | 另一次注视事件或显式设置                | Explicit `高` | 通过 Blueprint/C++ 调用    |

**SetObjectInAttention** 仅可由另一次显式调用覆盖 `显式设置优先。` 一旦

### SetObjectInAttention

设置了该槽，注视事件就无法覆盖它，除非显式清除。 `注意力槽` 注意力槽是一个单独的 `FConvaiObjectEntry` ，存储在 `CurrentAttentionObject`。该插件会将此槽位纳入动作配置和场景上下文，以便 Convai 在解析诸如 `"this"`, `"that"`, `"it"`和 `"there"`.

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

| `EConvaiAttentionSource` 值 | 含义                                                              |
| -------------------------- | --------------------------------------------------------------- |
| `None`                     | 当前没有关注任何对象。                                                     |
| `注视管线`                     | 通过 Blueprint 或 C++ 调用 `SetObjectInAttention` 来设置槽位。注视功能无法覆盖此设置。 |
| `Gaze`                     | 注视管线设置了此槽位。后续注视事件可以覆盖它。                                         |

#### 从 Blueprint 设置注意力

在 `SetObjectInAttention` 组件上调用 `Convai Chatbot` ，以显式设置注意力对象：

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

传入一个空的 `FConvaiObjectEntry` （默认构造，且 `Name`为空）即可清除该槽位。

`SetObjectInAttention` 在聊天机器人上 `EnvironmentData.bEnableActions` 为 `false` 时不起作用——只有在 `action_config` 已随 `/connect`.

#### 发送时，Convai 才会解析注意力对象。

注视管线使用 `TrySetObjectInAttentionFromGaze` 和 `TryClearObjectInAttentionFromGaze`。这些函数受以下所有权规则限制：

* `TrySetObjectInAttentionFromGaze` 在 `AttentionSource` 为 `None` 或 `Gaze`。它会返回 `false` 当槽位为 `Explicit`时，从而保留显式所有者。
* `TryClearObjectInAttentionFromGaze` 仅当聊天机器人仍将注视视为所有者时，才会清除槽位 **并且** 预期对象与当前受关注对象相匹配。这样可以防止过时的“注视丢失”事件清除较新的目标。

`UConvaiObjectComponent` 会通过以下调用自动驱动这些操作： `NotifyGazeAttentionBegin` 和 `NotifyGazeAttentionEnd`。通常无需直接调用注视设置器，除非你正在构建自定义焦点系统。有关完整的追踪管线、高亮行为和组件级目标定位规则，请参阅 [注视关注的工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/how-gaze-attention-works.md).

#### AttentionSource 属性

`AttentionSource` 是一个 `Transient`、可供蓝图读取的 `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 返回一个参数类型为 `Reference`的动作时，系统会根据完整的 `Objects` 和 `Characters` 列表解析该值，而不仅仅使用当前的注意对象。只有当玩家使用含义模糊的代词时，注意对象才会影响 Convai 选择哪个对象。选定对象后，系统会通过常规的引用解析流程，将其解析为有效的 `Ref` 指针。

### LookAtTarget 和 PointAtTarget

`UConvaiChatbotComponent` 提供两个用于动画的复制 Actor 引用：

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

这些引用独立于注意槽，不会影响对话或动作流程。可通过 Blueprint 设置它们来驱动动画状态，而不影响 Convai 解析对象引用的方式。

### 后续步骤

{% content-ref url="/pages/9d759a9e65c274645e91b88390d8bb2c4762bd80" %}
[配置动作](https://docs.convai.com/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 参考](https://docs.convai.com/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.
