> 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` 构成核心管线，负责从你的场景中收集对象描述，并在每个角色准备就绪时将其传递给 Convai。该管线在之后还会持续保持已连接角色的对象感知为最新状态——已注册的对象在发生变化时可重新同步其静态描述，或通过跟踪属性报告运行时状态变化。 `ConvaiSceneMetadataCollector` 是一个可选的配套组件，用于手动控制、统计和审计——下文所述的自动传递并不需要它。理解这两条路径有助于你正确配置系统，并在对象未能到达角色时进行调试。

### 连接时传递流程

每个 `ConvaiObjectMetadata` 组件会将自身注册到 `ConvaiMetadataRegistry` 在启用时。这一过程独立于任何 `ConvaiSceneMetadataCollector` 场景中的。

自动连接时发送由 `ConvaiCharacter` 角色自身驱动，而不是由收集器驱动。当角色收到来自 Convai 的就绪信号时，它会捕获其 action-config 对象和角色的快照，为任何跟踪属性值设定初始值，并将场景元数据标记为待发送。该待发送标记会在角色下一次批处理更新时刷新——也就是动态上下文更新使用的同一个批处理窗口——此时会读取注册表并将负载作为一条 `update-scene-metadata` RTVI 消息。

```mermaid
flowchart TD
    A[ConvaiObjectMetadata\nOnEnable] -->|注册| B[ConvaiMetadataRegistry\n静态，O(1) 查找]
    C[ConvaiCharacter\n接收角色就绪信号] -->|MarkPendingSceneMetadataSync| D[批量刷新\n与动态上下文相同的窗口]
    D -->|GetSceneMetadataList| B
    D --> E[RTVIUpdateSceneMetadata\n更新场景元数据]
    E --> F([Convai])
```

对象会在启用和禁用时自动注册和注销——无需手动清理。角色就绪后，Convai 会接收所有已注册对象的当前状态，并且无需 `ConvaiSceneMetadataCollector` 需要。此后所做的任何更改都会通过下文所述的实时重新同步路径传递。

`ConvaiSceneMetadataCollector`的 **启动时收集** 选项在启用时还会在连接时发送完整负载——这会重复上面的自动发送，对基础设置来说是冗余的。仅在你需要统计日志、手动触发点（`CollectAndSendSceneMetadata()`），或发送前审计（`ValidateAllMetadata()`），而不是因为对象要到达角色时它是必需的。请参见 [场景元数据组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/component-reference.md) 以查看完整字段列表。

### 实时重新同步与跟踪属性

在初始连接时发送后，有两种机制可保持角色对对象的感知为最新。

#### 静态元数据的实时重新同步

设置 `ObjectName`, `ObjectDescription`，或 `IncludeInMetadata` 来自脚本中的一个 `ConvaiObjectMetadata` 当前已注册的对象会标记 `ConvaiMetadataRegistry` 为脏并通知每个已连接角色。注册或注销一个 `ConvaiObjectMetadata` 组件在会话连接期间——例如启用或禁用其 `GameObject`，或在运行时添加该组件——都会产生相同效果。每个收到通知的角色会自动发送后续 `update-scene-metadata` 消息，并在下次刷新时发送，无需手动 `CollectAndSendSceneMetadata()` 调用。

#### 跟踪属性

`ConvaiObjectMetadata` 还可以声明跟踪属性：一个由以下内容组成的列表 `ConvaiTrackedContextProperty` 条目，每个条目指定一个属性、一个初始值、一个可选的运行时来源（一个 `组件` 以及通过反射在每次轮询时读取的成员名），以及一个 `ConvaiRespondMode` 响应。内部轮询驱动程序每 0.25 秒检查一次每个已注册对象的跟踪属性，并通过 `DynamicContext.SetState`，其键格式为 `{ObjectName}.{PropertyName}`.

```mermaid
flowchart TD
    A[ConvaiWorldObjectPollDriver\n每 0.25 秒] -->|EvaluateTrackedProperties| B[ConvaiTrackedContextProperty\n读取运行时来源]
    B -->|值已变化| C[DynamicContext.SetState\nObjectName.PropertyName]
    C --> D([Convai])
```

跟踪属性不会作为一条 `update-scene-metadata` 消息传输。它们使用与手动 `SetState` 调用相同的动态上下文传输，从而在不需要你自己的脚本中编写任何轮询代码的情况下保持场景对象自身状态同步。

{% hint style="info" %}
跟踪属性走的是 Dynamic Context 通道，但它们是在 Inspector 中于世界对象上以声明式方式编写的，而不是由脚本以命令式方式推送。当前对象自身状态应自动与角色保持同步时使用它们。对于一个手动 `SetState` 调用，用于不属于任何单个场景对象的事件和状态。
{% endhint %}

### 场景元数据与动态上下文

这两套系统都会将信息注入角色上下文，但用途不同：

|          | 场景元数据                                      | 动态上下文                               |
| -------- | ------------------------------------------ | ----------------------------------- |
| **由谁填充** | SDK 自动发现对象                                 | 开发者手动注入状态                           |
| **描述什么** | 场景中的物理对象和实体                                | 运行时状态、事件、玩家操作                       |
| **何时发送** | 在房间连接时发送，之后每当已注册对象的名称、描述或是否包含发生变化时都会自动重新发送 | 任何时间，按需发送——包括对每 0.25 秒轮询一次的跟踪属性持续发送 |
| **典型用途** | “南墙上有一个灭火器”                                | “学员未通过阀门检查”                         |

结合使用二者，以获得最具上下文信息的 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 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-unity-sdk/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.