> 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] -->|registers| B[ConvaiMetadataRegistry\nstatic, O(1) lookup]
    C[ConvaiCharacter\nreceives character-ready signal] -->|MarkPendingSceneMetadataSync| D[Batched flush\nsame window as dynamic context]
    D -->|GetSceneMetadataList| B
    D --> E[RTVIUpdateSceneMetadata\nupdate-scene-metadata]
    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 -->|value changed| 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.