> 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/how-scene-metadata-works.md).

# 场景元数据的工作原理

了解场景对象元数据如何在连接时、通过实时更新以及通过跟踪属性变化传递给 Convai。

场景元数据是你为 Convai 角色提供关卡中对象知识的方式。添加一个 `UConvaiObjectComponent` 到任何 `Actor` ——门、机器、设备等——，关卡中的每个角色都会知道该对象存在、它叫什么以及它的用途。当玩家问“这个房间里有什么？”或“北门开着吗？”，角色会使用这些信息来回答。

### 带标签的对象如何传入 Convai

会话开始时，插件会收集所有带标签的对象，并一次性将它们的名称和描述发送给 Convai。你在游戏运行时添加或移除的对象会通过单独的更新消息同步。

内部上，每个 `UConvaiObjectComponent` 都会向 `UConvaiSubsystem` 全局池注册 `BeginPlay`。当聊天机器人调用 `StartSession()`, `UConvaiChatbotComponent` 时，会从子系统中收集已注册的对象组件，构建 `action_config` 负载，并将其作为 `/connect` 握手的一部分发送给 Convai。会话已启动后新增的对象会改为通过单独的 `更新场景元数据` 消息传输。

```mermaid
flowchart TD
    A["UConvaiObjectComponent\nBeginPlay"] -->|注册组件| B["UConvaiSubsystem\n全局对象池"]
    B -->|由…收集| C["UConvaiChatbotComponent\nStartSession()"]
    C -->|构建 action_config| D["/connect 握手"]
    D --> E(["Convai"])
    C -->|"AddObject / RemoveObject\n仅限新对象"| F["update-scene-metadata\n消息"]
    F --> E
```

会话开始时已存在的对象会保留在冻结快照中，若不重启会话则无法在会话中途更新。会话开始后新增的对象条目会通过 `更新场景元数据` 下一次去抖刷新发送，除非变更调用使用 `bFlushImmediately = true`.

### 一览上下文通道

插件为 Convai 角色提供三个世界上下文通道，每个通道用途不同：

|          | 场景元数据                                | 跟踪的属性                           | `SetObjectInAttention` |
| -------- | ------------------------------------ | ------------------------------- | ---------------------- |
| **描述内容** | 静态 `Actor`场景中的静态对象和道具                | 某个 `Actor` `UPROPERTY` 或函数的实时状态 | 角色当前专注的具体对象            |
| **发送时间** | 仅一次，在会话开始时（冻结快照）发送；或者通过运行时环境更新发送新增条目 | 在会话开始时，随后在检测到值变化时发送             | 在显式调用或注视管线触发时发送        |
| **典型用途** | `“主入口处的一扇锁着的门”`                      | `“门现在已解锁”`                      | `“角色注意到灭火器”`           |

三者结合使用，获得最丰富的上下文体验。

### Convai 对象组件

`UConvaiObjectComponent` 是一个 `ActorComponent` ，你可以把它附加到任何 `Actor` ，让 Convai 角色了解其信息。只需在 `Actor` 上放置一个组件就足够；关卡中的每个聊天机器人都会自动看到它，无需为每个聊天机器人单独配置。

在 `BeginPlay` 该组件会加入 `UConvaiSubsystem` 池中。此后启动会话的每个聊天机器人都可以在其环境中包含 `Actor` 组件。

### 对象身份

每个 `UConvaiObjectComponent` 具有一个 `ObjectEntry` (`FConvaiObjectEntry`标识符（名称和描述） `Actor` ，用于向 Convai 描述该对象：

* `名称` ——聊天机器人用于指代该对象的标签。它在关卡内必须唯一。如果两个组件共享同一个名称， `UConvaiSubsystem` 会自动重命名重复项，并向输出日志写入警告。
* `说明` ——Convai 在会话开始时接收的一句自然语言句子或段落。

Convai 会在 `name` 字段中接收该对象的名称，位于其 `action_config.objects` 条目中。保持名称简短且具有描述性（例如 `"FrontDoor"` 而不是 `"BP_Door_01"`）会让引用更容易解析。

### 跟踪的属性

除了静态身份之外，你还可以为受支持的 `UPROPERTY` 值或受支持的纯净、无参数函数使用 `TrackedProperties` (`TArray<FConvaiTrackedProperty>`).

每个 `FConvaiTrackedProperty` 包含：

* `PropertyPath` ——指向 `UPROPERTY` 或函数的点路径，在运行时相对于所属的 `Actor` （例如 `"bIsLocked"`, `"Stats.HP"`, `"GetCurrentRoomName"`).
* `说明` ——其值含义的自然语言说明。
* `StateValueDescriptions` ——按值的可选注释，最适合用于枚举和布尔值。
* `ShouldRespond` (`EC_RunLLMOption`）——当运行时值发生变化时会发生什么。

在会话开始时，每个被跟踪属性的当前值都会以 `EC_RunLLMOption::Never`预置到聊天机器人的上下文中，因此角色会在不发言的情况下获知。每次检测到变化时，插件都会发送动态上下文状态更新，并按配置的 `ShouldRespond`: `自动` 让 Convai 决定是否响应， `始终` 请求回应，并 `从不` 静默更新。

聊天机器人看到的被跟踪属性键是 `"<ObjectName>.<PropertyPath>"` ——例如 `"FrontDoor.bIsLocked"`.

### 距离和方向从何而来

场景元数据注册对象身份——它的名称和描述。它不会计算该对象相对于聊天机器人的位置；这项工作属于 [空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness.md) 子系统，它会在每个已注册的 `UConvaiObjectComponent`、其他角色和玩家之间运行，并在每次轮询时向每个聊天机器人提供一条距离和方向语句。

如果你有之前关于每个对象的笔记或蓝图，描述 `bAutoGenerateProximityState` 标志或合成的 `"<ObjectName>.ProximityToYou"` 状态键，那么该机制已在 `4.0.0-beta.22`中退役。空间感知已在整个项目范围内取代了它——参见 [空间感知如何工作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/how-spatial-awareness-works.md) 获取当前模型，以及 [空间感知设置参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/spatial-awareness-reference.md) 了解每项设置。

该 `Convai Object Component` 仍然为此管线提供一个调试辅助： `bDebugDrawProximityPaths` 会在编辑器视口中绘制每个已订阅聊天机器人到对象的导航路径——可到达时为绿色，不可到达时为红色，聊天机器人已在那里的时候为青色。它不受任何其他设置限制，只要空间感知需要对象的导航路径就会工作。发布前请禁用它。

### 移动状态

一个 `UConvaiObjectComponent` 还可以检测 `Actor` 它所附加的对象是否在移动。 `MovementAwareness` (`FConvaiObjectMovementSettings`）会在每次轮询时采样对象的平移和旋转，并将移动/停止判断纳入空间感知语句中——一个移动中的箱子会被读作正朝向或远离聊天机器人移动，而无需任何进一步配置。

开启 `bExposeMovementState` (Blueprint 显示名称 **添加移动状态**）还会额外发布一个持久的 `"<ObjectName>.Movement"` 状态，聊天机器人可以直接询问它，并在描述中明确“已确认停止”。两个响应设置决定状态转换时是否也应提示角色作出反应：

* `StartedMovingResponse` (**移动开始时**）——聊天机器人在对象开始移动时如何响应。
* `StoppedMovingResponse` (**移动停止时**）——对象被确认停止时聊天机器人如何响应。

两者都使用 `EC_RunLLMOption`: `从不` （默认）会静默更新状态， `自动` 让 Convai 决定是否响应，并 `始终` 在每次转换时请求回应。参见 [场景元数据组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md#movement-awareness) 完整字段表。

### 会话开始时与游戏过程中分别发送什么

会话握手会传送对象列表的冻结快照（`action_config.objects`） `bEnableActions` bool `EnvironmentData` 控制连接时的动作配置：当它为 `false`， `action_config` 该块不会在会话开始时发送，而通过 `SetObjectInAttention` 没有效果。

一旦会话处于活动状态， `UConvaiChatbotComponent` 会更新本地环境镜像并安排同步。新的场景条目和移除会通过 `更新场景元数据`发送；已经存在于连接时快照中的现有条目会保留其原始 `action_config` 数据直到重新连接。

有一条重要限制：如果某个对象在会话开始时已经包含在 `action_config` 中，那么其在冻结快照中的描述在会话中途 `更新场景元数据` 通道发送。要将描述更改传播到现有对象，请调用 `StopSession` 然后 `StartSession` 以使用更新后的描述重新连接。

### 批量更新

当你在短时间内连续调用多个添加或移除方法时，插件会把它们合并为一条网络消息，而不是每次调用都发送一条消息。这是默认行为。传入 `bFlushImmediately = true` 会跳过批处理窗口并立即发送。请谨慎使用 `bFlushImmediately` ——高频调用会产生许多较小的 WebRTC 消息并增加网络开销。

### 下一步

{% content-ref url="/pages/0feb18e88feac4367d421728b98f739c505dcd5a" %}
[场景元数据快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-quick-start.md)
{% endcontent-ref %}

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

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


---

# 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/how-scene-metadata-works.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.