> 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 角色提供关卡中对象知识的方式。添加一个 `UConvaiObjectComponent` 到任何 `Actor` ——门、机器、设备等——，关卡中的每个角色都会知道该对象的存在、名称以及作用。当玩家问“这个房间里有什么？”或“北门开着吗？”，角色会利用这些信息来回答。

### 带标签的对象如何到达 Convai

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

在内部，每个 `UConvaiObjectComponent` 都会将自身注册到 `UConvaiSubsystem` 全局池中 `BeginPlay`。 `StartSession()`, `UConvaiChatbotComponent` 从子系统中收集已注册的对象组件，构建 `action_config` 负载，并将其作为 `/connect` 握手的一部分发送给 Convai。会话已启动后添加的对象会通过单独的 `update-scene-metadata` 消息来传输。

```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
```

会话开始时已存在的对象会保留在一个冻结快照中，且无法在会话中途更新，除非重新启动会话。会话开始后新增的对象条目会通过 `update-scene-metadata` 在下一次防抖刷新时发送，除非该变更调用使用 `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`: `Auto` 让 Convai 决定是否作出反应， `始终` 请求响应，并 `从不` 静默更新。

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

### 接近状态

当 `bAutoGenerateProximityState` 为 `true` （默认值），插件会计算一个合成状态键 `“<ObjectName>.ProximityToYou”` ，方法是查询 Unreal Engine 导航系统。支持部分路径，因此即使聊天机器人无法沿完整导航路线到达该对象，接近描述也仍然有意义。

该值将可达性和相对方向结合起来，形成诸如 `“附近，前方”`, `“有一段距离，左侧”`，或 `“没有步行路径，后方”`。当对象或聊天机器人正在主动移动时（稳定性门控），评估会被延后，并在连续若干次延后 tick 后强制执行。由于接近信息属于空间上下文而非对话内容， `ShouldRespond` 接近状态的 `EC_RunLLMOption::Never`始终为；Convai 会被静默告知。

`bDebugDrawProximityPaths` 会在编辑器视口中绘制从每个聊天机器人到该对象的导航路径，前提是 `bAutoGenerateProximityState` 已开启。在发布前请关闭此标志。

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

会话握手会传递对象列表的冻结快照（`action_config.objects`）。 `bEnableActions` 布尔值 on `EnvironmentData` 控制连接时的动作配置：当它处于 `false`，则 `action_config` 时，该块不会在会话开始时发送，并且通过 `SetObjectInAttention` 不起作用。

一旦会话处于运行状态， `UConvaiChatbotComponent` 上的对象和角色变更方法会更新本地环境镜像并安排同步。新的场景条目和移除会通过 `update-scene-metadata`；而连接时快照中已存在的条目会保留其原始 `action_config` 数据，直到重新连接。

有一个重要限制：如果某个对象在会话开始时已包含在 `action_config` 中，那么冻结快照里的描述就不能在会话中途更改。只有对该会话而言是新对象的条目才会通过实时 `update-scene-metadata` 通道传输。要将描述更改传播到现有对象，请调用 `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/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 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/how-scene-metadata-works.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.