> 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 收到其就绪信号时，它会捕获其动作配置对象和角色的快照，为任何受跟踪属性赋值，并将场景元数据标记为待同步。该待处理标志会在角色下一次批量更新时清除——与动态上下文更新使用的相同批处理窗口——该更新会读取注册表并将负载作为一条 `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" %}
受跟踪属性走的是动态上下文通道，但它们是在世界对象的 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.