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

# 场景元数据如何工作

`ConvaiObjectMetadata`, `ConvaiMetadataRegistry`，以及 `ConvaiSceneMetadataCollector` 形成一个三段式管道，从你的场景中收集对象描述，并在会话连接时将它们传递给 Convai。理解这一流程有助于你正确配置系统，并在对象未能到达角色时进行调试。

### 注册与传递流程

每个 `ConvaiObjectMetadata` 组件会自行注册到 `ConvaiMetadataRegistry` ，当启用时。房间连接后， `ConvaiSceneMetadataCollector` 会读取该注册表，组装负载，并将其作为 `update-scene-metadata` RTVI 消息发送给 Convai。

```mermaid
flowchart TD
    A[ConvaiObjectMetadata\nOnEnable] -->|registers| B[ConvaiMetadataRegistry\nstatic, O(1) lookup]
    B -->|GetSceneMetadataList| C[ConvaiSceneMetadataCollector]
    C -->|SessionState.Connected| D[RTVIUpdateSceneMetadata\nupdate-scene-metadata]
    D --> E([Convai])
```

对象在启用和禁用时会自动注册和注销——无需手动清理。Convai 会在连接时接收所有已注册对象的当前状态。

### 场景元数据 vs. 动态上下文

这两种系统都会向角色的上下文中注入信息，但用途不同：

|          | 场景元数据       | 动态上下文          |
| -------- | ----------- | -------------- |
| **由谁填充** | SDK 自动发现对象  | 开发者手动注入状态      |
| **描述内容** | 场景中的物理对象和实体 | 运行时状态、事件、玩家操作  |
| **发送时间** | 一次，在房间连接时   | 随时，按需          |
| **典型用途** | “南墙上有一个灭火器” | “培训员刚刚未通过阀门检查” |

将两者结合使用，以获得最丰富的 AI 上下文体验。

{% hint style="info" %}
场景元数据描述的是静态世界——存在什么。动态上下文描述的是动态世界——正在发生什么。它们是互补的，而不是竞争的。
{% endhint %}

### 下一步

{% content-ref url="/pages/6870c01843dd57c3ac7ecac3bfb3a6790f115e1b" %}
[场景元数据快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/16c5aa93667aec71180b560b3408b114f488e893" %}
[场景元数据使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/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-unity-sdk/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.