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

# 场景元数据组件参考

Convai Object Component 的完整属性、函数和事件参考，包括对象标识、跟踪属性、接近状态和注视事件。

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

### 对象身份

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

#### 核心标识字段

这些字段属于 `ObjectEntry`.

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

#### 导航目标字段

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

| 属性                                                   | 类型                             | 默认         | 说明                                                                |
| ---------------------------------------------------- | ------------------------------ | ---------- | ----------------------------------------------------------------- |
| `ObjectReference` (Blueprint 显示名称 `对象为`)             | `EConvaiObjectReference`       | `整个 Actor` | 此 Actor 的哪一部分算作此对象——整个 Actor，还是某个特定组件。控制当没有 `MovementPoints` 被编写。 |
| `接受半径`                                               | `float` （厘米）                   | `150`      | 将移动到此处的动作视为完成的厘米距离。                                               |
| `组件名称`                                               | `FString`                      | —          | 用于 `特定组件` 范围。留空则以 Actor 的原点为目标。                                   |
| `Socket 或骨骼名称`                                       | `FName`                        | —          | 匹配组件上的 Socket 或骨骼（`特定组件` 仅在……范围内）。                                |
| `MovementPoints`                                     | `TArray<FConvaiMovementPoint>` | `[]`       | 此对象的设计师编写目的地。参见 [移动点](#movement-points) 下文。                       |
| `将对象用作回退` (`bFallbackToObjectWhenPointsUnreachable`) | `bool`                         | `false`    | 当所有 `MovementPoints` 条目都无法到达时，改为走向对象本身，而不是报告对象不可达。                |

#### 对象引用

`EConvaiObjectReference` 控制当没有 `MovementPoints` 被编写时，Convai 如何指导 AI 对此对象进行导航：

* `整个 Actor` — AI 会停在 `Actor`的碰撞边界处。适用于较大或环境性对象： `“去车那里”`, `“跟随玩家”`.
* `特定组件` — AI 会走到某个特定子组件的位置，也可以是一个命名的 socket 或骨骼。适用于精确目标： `“站在门把手旁”`.

当 `MovementPoints` 被编写时，它们会接管为移动目标，并且 `ObjectReference` 只定义该对象在凝视和视觉方面的含义。

#### 移动点

中的每个条目 `MovementPoints` (`FConvaiMovementPoint`）标记角色走到此对象时站立的位置——例如门的两侧各编写一个。可在 Details 面板中编辑它们，或者在选中对象时拖动视口可视化器添加的抓取手柄。解析器会选择可到达且步行路径最短的点；如果所有点都被禁用，角色则会直接走到对象本身。

Tick `bCreatesSeparateDestination` (Blueprint 显示名称 `创建单独目的地`）在某个点上，使其成为自己的命名目的地——例如一个电梯平台命名为 `上层平台` 可让 AI 被发送到 `电梯上层平台`，与平台分开。

完整的 `FConvaiMovementPoint` 字段表，请参见 [数据类型和枚举](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/data-types-and-enums.md).

### 跟踪的属性

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

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

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

#### `ShouldRespond` options

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

* `自动` — Convai 会根据对话上下文决定是否作出反应。
* `始终` — 每次变化都会请求回复。
* `从不` — 值会静默更新；聊天机器人会被告知，但不会说话。

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

### 移动感知

该 `MovementAwareness` 属性（`FConvaiObjectMovementSettings`，类别 `Convai\|Object\|Movement Awareness`）检测此对象的平移和旋转，并将简洁的移动方向输入空间上下文。

| 属性                                                   | 类型                           | 默认      | 说明                                                                                           |
| ---------------------------------------------------- | ---------------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `bEnableMovementAwareness` (Blueprint 显示名称 `启用移动感知`) | `bool`                       | `true`  | 总开关。关闭后会移除移动相关措辞以及 `移动` 状态，但会保持普通位置和可达性感知不变。                                                 |
| `MovementSensitivity` (`敏感性`)                        | `EConvaiMovementSensitivity` | `中等`    | 连贯的平移或旋转达到多大程度才算移动。数值越高越能检测到细微运动；数值越低则会过滤更多物理漂移和碰撞抖动。                                        |
| `bExposeMovementState` (`添加移动状态`)                    | `bool`                       | `false` | 添加 `<ObjectName>.Movement` 到上下文中，并使其可供 Watch Property 动作用于。还会报告已确认的停止。空间事实中的移动方向表述无需此选项即可工作。 |
| `StartedMovingResponse` (`移动开始时`)                    | `EC_RunLLMOption`            | `从不`    | 已确认的开始是否应请求回复。仅在以下情况下生效： `bExposeMovementState` 已开启。                                         |
| `StoppedMovingResponse` (`移动停止时`)                    | `EC_RunLLMOption`            | `从不`    | 已确认的停止是否应请求回复。仅在以下情况下生效： `bExposeMovementState` 已开启。                                         |
| `传递`                                                 | `EConvaiContextDelivery`     | `正常发送`  | 当一个响应式过渡到达聊天机器人时。仅在以下情况下生效： `bExposeMovementState` 已开启，并且上面的两个回复字段中至少有一个不是 `从不`.             |
| `bFlushImmediately` (`Flush Immediately`)            | `bool`                       | `false` | 对响应式移动过渡绕过正常上下文批处理。生效条件与 `传递`.                                                               |

`EConvaiMovementSensitivity` 的条件相同。灵敏度值从低到高： `很低`, `低`, `中等`, `高`, `很高`.

### 距离与方向

Convai 对象组件不再计算其自身的每个聊天机器人的接近度值。 `4.0.0-beta.22` 已弃用按对象的接近度机制（`bAutoGenerateProximityState` 以及合成的 `"<ObjectName>.ProximityToYou"` 状态键）；当前插件中两者都不存在。现在，每个已注册对象的距离、方向、可达性和视线都由 [空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness.md) 子系统集中计算，并作为常规上下文的一部分传递给每个聊天机器人。请参见 [空间感知设置参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/spatial-awareness-reference.md) 查看控制此功能的项目设置，以及 [空间感知如何工作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/how-spatial-awareness-works.md) 查看句子模型。

| 属性                         | 类型     | 类别                      | 默认      | 说明                                                                              |
| -------------------------- | ------ | ----------------------- | ------- | ------------------------------------------------------------------------------- |
| `bDebugDrawProximityPaths` | `bool` | `Convai\|Object\|Debug` | `false` | 在编辑器视口中绘制从每个已订阅聊天机器人到此对象的导航路径——可到达时为绿色，不可达时为红色，聊天机器人已在该处时为青色。不受任何其他设置限制。发布前请禁用。 |

### 凝视

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

| 名称                                      | Kind                     | 默认     | 说明                                                                                      |
| --------------------------------------- | ------------------------ | ------ | --------------------------------------------------------------------------------------- |
| `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`                             | `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` | 释放注意力状态。 `Player` 可能是 `nullptr` 在已销毁目标路径中—— `OnAttentionLost` 的接收方必须进行 null 检查 `Player` 后再使用它。 |

### 相关参考

{% 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 %}

{% content-ref url="/pages/10f005ecc29d44fa4ef4dd6d6ca9cf6c1c257d02" %}
[空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness.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/scene-metadata/scene-metadata-component-reference.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.