> 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/component-reference.md).

# 场景元数据组件参考

用于向 Convai 描述场景对象并暴露其实时跟踪状态的两个组件的参考，包括 Inspector 字段和生命周期。

Scene Metadata 系统由两个组件组成。 `ConvaiObjectMetadata` 应放在 AI 应了解的每个对象上。 `ConvaiSceneMetadataCollector` 应放在 `ConvaiManager` GameObject 上，并负责收集和传输。

### ConvaiObjectMetadata

**添加组件路径：** `Convai → 世界对象`

`ConvaiObjectMetadata` 是一个 `MonoBehaviour` 用于向 Convai 描述一个单独的 GameObject。启用后，它会自行注册到 `ConvaiMetadataRegistry`。当禁用或销毁时，它会自动注销——无需手动清理。

#### Inspector 字段

| 字段             | 类型                                   | 默认值               | 约束             | 描述                                                                  |
| -------------- | ------------------------------------ | ----------------- | -------------- | ------------------------------------------------------------------- |
| **对象名称**       | `string`                             | *（GameObject 名称）* | 必填。最多 50 个字符。  | Convai 用于在对话中标识并引用此对象的名称。首次添加组件时会从 GameObject 的名称自动填充。可编辑为清晰、可读的标签。 |
| **对象描述**       | `string`                             | `""`              | 可选。最多 200 个字符。 | 一段客观、具体的描述——对象是什么、位于何处以及任何关键属性。AI 使用这段文本来依据其回答。                     |
| **包含在元数据中**    | `bool`                               | `true`            | —              | 取消勾选后，此对象会被排除在下一次元数据收集之外，但不会移除或禁用该组件。可用此项管理运行时是否包含。                 |
| **跟踪属性**       | `List<ConvaiTrackedContextProperty>` | *（空）*             | 可选。            | 每个条目的运行时属性会作为动态上下文状态键暴露给所有已连接角色。参见 [跟踪的属性](#tracked-properties) 下方。 |
| **已注册** *（只读）* | `bool`                               | —                 | 只读             | 调试指示器。显示 `true` 当该组件当前已注册到 `ConvaiMetadataRegistry`。在播放模式下可见。       |

#### 生命周期

`ConvaiObjectMetadata` 自行管理其注册：

| 事件           | 行为                                                   |
| ------------ | ---------------------------------------------------- |
| `OnEnable`   | 注册到 `ConvaiMetadataRegistry`                         |
| `OnDisable`  | 从…注销 `ConvaiMetadataRegistry`                        |
| `OnDestroy`  | 从…注销 `ConvaiMetadataRegistry`                        |
| `OnValidate` | 自动填充 **对象名称** 来自 `gameObject.name` 如果为空；会在编辑器中记录验证错误 |

运行时被停用的 GameObjects 将不会出现在下一次元数据收集中，即使 **包含在元数据中** 仍保持勾选。

更改 **对象名称**, **对象描述**，或 **包含在元数据中** 通过公共的 `ObjectName`, `ObjectDescription`，或 `IncludeInMetadata` 属性会将元数据标记为已更改，并在会话处于活动状态时立即重新同步所有已连接角色——该更改不会延迟到下一次连接。

#### 验证规则

`ConvaiObjectMetadata.IsValid` 返回 `true` 时自动连接， **对象名称** 不能为空且不能全是空白字符。50 字符限制仅会通过编辑器警告由 `GetValidationErrors()` ——名称超过 50 个字符的对象仍然会通过 `IsValid` 并包含在负载中。

名称为空的对象 **对象名称** 失败 `IsValid` 并被排除在 `GetValidMetadata()` 以及发送给 Convai 的负载中。名称超过 50 个字符的对象会包含在负载中，但会在编辑器中生成验证警告。

{% hint style="warning" %}
`OnValidate` 验证失败时会在编辑器中记录警告，但不会阻止组件被添加。添加组件后请检查 Console，以便在进入播放模式前发现配置错误。
{% endhint %}

#### 跟踪的属性

中的每个条目 **跟踪属性** 是一个 `ConvaiTrackedContextProperty` ——一个可序列化的逐条目定义，将一个运行时值作为动态上下文状态键暴露给每个已连接角色。

| 字段        | 类型                  | 默认值  | 描述                                                                                                                                                                       |
| --------- | ------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **属性名称**  | `string`            | `""` | 启用此条目所必需。与 **对象名称** 组合以形成动态上下文状态键。                                                                                                                                       |
| **反应**    | `ConvaiRespondMode` | `静默` | 当此属性值发生变化时应用于角色的反应。参见 [`ConvaiRespondMode`](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/relay-component-reference.md#convairespondmode). |
| **初始值**   | `string`            | `""` | 对象注册时发送的值，以及用于没有 **源组件** 配置的条目的值。                                                                                                                                        |
| **源组件**   | `组件`                | `无`  | 可选。用于在每次轮询时读取实时值的组件。若要使用固定值请留空。                                                                                                                                          |
| **源成员名称** | `string`            | `""` | 可选。位于 **源组件** 上要读取的属性、字段或无参数方法名称。                                                                                                                                        |

每个条目的状态键构建为 `"{ObjectName}.{PropertyName}"` 通过 `ConvaiObjectMetadata.BuildStateKey`.

当两者都 **源组件** 和 **源成员名称** 已设置时， `ConvaiTrackedContextProperty` 会通过反射在每次轮询时实时读取值，并按顺序检查：匹配的属性、字段、无参数方法（包括非公有成员）。当任一字段未设置时，该条目将保持固定为 **初始值** ，直到被代码更改。

对已连接角色的轮询和传递由内部的 `ConvaiWorldObjectPollDriver` ——无需添加面向用户的组件。它会在 `ConvaiManager` GameObject 上创建，当前第一个 `ConvaiObjectMetadata` 组件注册时，便会每隔 `0.25` 秒评估所有已注册对象上的跟踪属性，并在最后一个 `ConvaiObjectMetadata` 组件注销时销毁。

### ConvaiSceneMetadataCollector

`ConvaiSceneMetadataCollector` 是协调器。它监视房间连接事件，从 `ConvaiMetadataRegistry`读取所有有效元数据，并将负载发送给 Convai。在 Inspector 中，点击 **Add Component** 并搜索 `Convai Scene Metadata Collector`。将其放置在与 `ConvaiManager` 相同场景中的任意 GameObject 上——其所需依赖会在启动时通过 `ConvaiManager.ActiveManager`.

#### Inspector 字段

| 字段                | 类型      | 默认值     | 描述                                                                           |
| ----------------- | ------- | ------- | ---------------------------------------------------------------------------- |
| **启动时收集**         | `bool`  | `false` | 启用后，收集器会在房间会话到达 `SessionState.Connected`时立即自动发送完整的元数据负载。如需手动控制何时发送元数据，请禁用此项。 |
| **日志统计**          | `bool`  | `true`  | 每次收集时都会写入一条 Console 记录，显示对象数量、收集耗时和注册表明细。可用于验证所有预期对象是否已被捕获。                  |
| **上次收集数量** *（只读）* | `int`   | —       | 显示最近一次收集所包含的对象数量。在播放模式下可见。                                                   |
| **上次收集时间** *（只读）* | `float` | —       | 显示最近一次收集操作所用时长（秒）。在播放模式下可见。                                                  |

#### 依赖与注入

`ConvaiSceneMetadataCollector` 需要两个注入的依赖—— `IEventHub` 和 `IConvaiRoomConnectionService` ——由 `ConvaiManager` 在启动时自动提供。无需手动连接。

如果未注入这些依赖（例如，如果 `ConvaiManager` 不在场景中），收集器会记录错误，且所有收集调用都将变为无操作。

{% hint style="danger" %}
不要将 `ConvaiSceneMetadataCollector` 添加到没有 `ConvaiManager`的场景中。当 `ConvaiManager` 缺失时，该组件会记录 `"[ConvaiSceneMetadataCollector] Dependencies not injected. Add ConvaiManager to scene."` 作为一条 **error** 在 Console 中的条目，并自行禁用。
{% endhint %}

#### 手动触发

当 **启动时收集** 被禁用时，请从脚本中调用 `CollectAndSendSceneMetadata()` ，以在应用需要的时刻触发收集。如果房间未连接，该方法将无操作——请使用 `IsReadyToSendMetadata()` 先检查就绪状态。

```csharp
if (_collector.IsReadyToSendMetadata())
    _collector.CollectAndSendSceneMetadata();
```

有关完整的公共方法列表，请参见 [场景元数据脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/scripting-api-reference.md).

### 下一步

{% content-ref url="/pages/553ff838d38639ef80a27f8380dc466768470562" %}
[场景元数据脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/scripting-api-reference.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/component-reference.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.