> 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/scene-metadata/scene-metadata-component-reference.md).

# 场景元数据组件参考

`UConvaiObjectComponent` 是你添加到任何 `Actor` 在你的关卡中，使 Convai 角色能够感知它。内部而言，它是一个 `ActorComponent` （类组 `Convai`），它会与 `UConvaiSubsystem`自动绑定 `ObjectEntry.Ref` 到所属的 `Actor` 当 `Ref` 未设置，并向关卡中的每个 Convai 角色公开对象身份、实时状态属性和凝视事件。

### 对象标识

该 `ObjectEntry` 属性（`FConvaiObjectEntry`）描述 `Actor` 到 Convai。因为 `ObjectEntry` 使用 `ShowOnlyInnerProperties`，其字段会直接显示在详情面板中，而不是折叠在结构体下。

#### 核心身份字段

这些字段属于 `ObjectEntry`.

| 属性   | 类型        | 默认值 | 说明                                                                  |
| ---- | --------- | --- | ------------------------------------------------------------------- |
| `名称` | `FString` | —   | 聊天机器人用于此对象的显示名称。每个关卡中必须唯一； `UConvaiSubsystem` 会自动重命名重复项，并向输出日志写入警告。 |
| `说明` | `FString` | —   | Convai 在会话开始时接收的通俗描述。                                               |

#### 导航目标字段

这些字段控制 Convai 角色在执行移动动作时如何实际移动到该对象。对于大多数对象，默认值就足够了——只有在需要精确的移动目标时才进行配置。它们属于 `ObjectEntry`.

| 属性                         | 类型                  | 默认值            | 说明                                                                                                    |
| -------------------------- | ------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| `移动目标模式`                   | `EConvaiMoveTarget` | `将 Actor 作为目标` | AI 如何导航到此对象。                                                                                          |
| `接受半径`                     | `float` （厘米）        | `150`          | 移动到达动作被视为完成的距离（厘米）。                                                                                   |
| `组件名称`                     | `FString`           | —              | 的子组件目标，适用于 `将组件作为目标` 模式。留空则以 Actor 原点为目标。                                                             |
| `Socket 或 Bone 名称`         | `FName`             | —              | 匹配组件上的 Socket 或骨骼（`将组件作为目标` 仅限模式）。                                                                    |
| `踏上边界` (`bStepOntoBounds`) | `bool`              | `false`        | 当 `true`时，AI 会导航到目标边界的顶部表面，而不是停在边缘。适用于 `将 Actor 作为目标` 模式（使用整个 `Actor` 边界）以及 `将组件作为目标` 模式（使用解析后的组件边界）。 |

#### 移动目标模式

`EConvaiMoveTarget` 控制 Convai 如何指示 AI 对此对象进行导航：

* `将 Actor 作为目标` — AI 会停在 `Actor` 碰撞边界处。适用于较大或环境类对象： `“走到汽车旁”`, `“跟随玩家”`.
* `将组件作为目标` — AI 会走到某个特定子组件点，也可指定命名的 socket 或 bone。适用于精确目标： `“站在门把手旁”`, `“走上平台”`.

### 跟踪属性

`TrackedProperties` (`TArray<FConvaiTrackedProperty>`，类别 `Convai|Object`）保存附加到此的实时状态观察者列表 `Actor`.

| 字段                       | 类型                                             | 默认值  | 说明                                                 |
| ------------------------ | ---------------------------------------------- | ---- | -------------------------------------------------- |
| `PropertyPath`           | `FName`                                        | —    | 所属对象上的点路径或函数名 `Actor`。使用 **Bind** 详情面板中的按钮可正确填充此项。 |
| `说明`                     | `FString`                                      | —    | 此属性对 AI 的通俗含义。                                     |
| `StateValueDescriptions` | `TArray<FConvaiTrackedPropertyStateValueDesc>` | —    | 针对枚举、布尔值或命名状态的每个值的注释。显示在 **高级** 在详情面板中。            |
| `ShouldRespond`          | `EC_RunLLMOption`                              | `从不` | 值在运行时变化时会发生什么。                                     |

`FConvaiTrackedPropertyStateValueDesc` 包含两个字符串字段： `值` （发送给 Convai 的字面值）以及 `说明` （该值的通俗含义）。

#### `ShouldRespond` 选项

`EC_RunLLMOption` 控制当跟踪属性值发生变化时聊天机器人的行为：

* `Auto` — Convai 会根据对话上下文决定是否响应。
* `始终` — 更新会在每次变化时请求响应。
* `从不` — 值会静默更新；聊天机器人会被告知，但不会说话。

会话开始时的初始种子始终为 `EC_RunLLMOption::Never` 无论 `ShouldRespond` 被设置为什么——聊天机器人会了解初始值，但不会做出反应。

### 接近状态

| 属性                            | 类型     | 类别                      | 默认值     | 说明                                                                          |
| ----------------------------- | ------ | ----------------------- | ------- | --------------------------------------------------------------------------- |
| `bAutoGenerateProximityState` | `bool` | `Convai\|Object`        | `true`  | 当 `true`，插件会计算一个 `“<ObjectName>.ProximityToYou”` 使用 UE 导航系统为每个聊天机器人生成一个状态键。 |
| `bDebugDrawProximityPaths`    | `bool` | `Convai\|Object\|Debug` | `false` | 在编辑器视口中绘制每个聊天机器人到该对象的导航路径。显示在 **调试** 详情面板中的子类别下。在发布前禁用。                     |

接近状态始终使用 `EC_RunLLMOption::Never`；聊天机器人会获知空间关系，但不会做出反应。当聊天机器人或对象正在移动，或者聊天机器人旋转不稳定时，评估会延后；在连续几次延后 tick 后会强制执行。

### 凝视

所有凝视属性和事件都位于 `Convai|Object|Gaze` 类别下。

| 名称                                      | 种类                       | 默认值    | 说明                                                                                    |
| --------------------------------------- | ------------------------ | ------ | ------------------------------------------------------------------------------------- |
| `bGazeable`                             | `bool` 属性                | `true` | 当 `false`，凝视管线会完全跳过此对象——没有高亮、没有凝视事件，也不会提升注意力。设置为 `false` 用于应存在于 AI 环境中但不应吸引玩家凝视的背景道具。 |
| `OnGazedIn` / `OnGazedOut`              | `BlueprintAssignable` 委托 | —      | 当玩家的凝视进入或离开此对象时立即触发（在跨越注意力阈值之前）。                                                      |
| `OnAttentionGained` / `OnAttentionLost` | `BlueprintAssignable` 委托 | —      | 当对象组件在尝试向聊天机器人分发后收到凝视注意开始或结束通知时触发。                                                    |

有关完整的凝视管线、玩家端设置和故障排查，请参见 [凝视注意力参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/gaze-attention-reference.md).

### 蓝图函数

#### 对象函数（类别 `Convai|Object`)

| 函数                                                 | 返回                 | 说明                                                                                |
| -------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------- |
| `GetResolvedComponent(bForceRefresh)`              | `USceneComponent*` | 返回目标场景组件，或者 `nullptr` 当整个 `Actor` 是作用范围时。                                         |
| `AddTrackedProperty(InProperty)`                   | `bool`             | 在运行时添加一个跟踪属性。返回 `false` 如果该路径在 `Actor`上不存在、类型不受支持，或者该路径已被跟踪。                      |
| `RemoveTrackedProperty(PropertyPath)`              | `bool`             | 停止跟踪某个属性。返回 `true` 如果属性已被移除。                                                      |
| `UpdateTrackedProperty(PropertyPath, NewSettings)` | `bool`             | 更新 `说明`, `StateValueDescriptions`，或 `ShouldRespond` 用于现有条目。路径是键；若要更改路径，请先移除再重新添加。 |
| `GetTrackedProperties(OutProperties)`              | `void`             | 将当前跟踪属性列表的副本写入 `OutProperties`.                                                   |

{% hint style="warning" %}
使用 `RemoveTrackedProperty` 不会从聊天机器人的上下文中清除其最后发送的值。该属性会停止更新，但聊天机器人仍会保留它收到的最后一个值。设计属性移除流程时请考虑这一点。
{% endhint %}

#### 凝视函数（类别 `Convai|Object|Gaze`)

| 函数                                                      | 返回     | 说明                                                                                 |
| ------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------- |
| `NotifyGazeBegin(Player)`                               | `void` | 标记凝视进入。由 `UConvaiPlayerComponent`自动调用；也可从自定义焦点系统中调用。                               |
| `NotifyGazeEnd(Player)`                                 | `void` | 与以下函数配套： `NotifyGazeBegin`.                                                        |
| `NotifyGazeAttentionBegin(Player, Text, ShouldRespond)` | `void` | 通过子系统请求在符合条件的聊天机器人之间提升凝视注意力。也 `BlueprintCallable` 可用于非凝视流程，例如电影摄像机或自定义焦点系统。        |
| `NotifyGazeAttentionEnd(Player)`                        | `void` | 释放注意状态。 `玩家` 可能是 `nullptr` 在目标已销毁的路径中—— `OnAttentionLost` 的接收方必须进行空值检查 `玩家` 后再使用它。 |

### 相关参考

{% content-ref url="/pages/a6fd7e3b5ee94be300d9c248743b197b93cc0c96" %}
[场景元数据如何工作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/how-scene-metadata-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/4a8ee50a93a78b9b86484cb79897f6d0d6bde187" %}
[运行时管理环境](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/managing-the-environment-at-runtime.md)
{% endcontent-ref %}

{% content-ref url="/pages/7fc985238017f8bd9de6df276f318c98902cac03" %}
[场景元数据使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-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/scene-metadata/scene-metadata-component-reference.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.