> 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 字段和生命周期。

场景元数据系统由两个组件构成。 `ConvaiObjectMetadata` 添加到 AI 应了解的每个对象上。 `ConvaiSceneMetadataCollector` 添加到 `ConvaiManager` GameObject 上，并负责收集和传输。

### ConvaiObjectMetadata

**添加组件路径：** `Convai → World Object`

`ConvaiObjectMetadata` 是一个 `MonoBehaviour` 用于向 Convai 描述单个 GameObject。启用时，它会向以下对象注册： `ConvaiMetadataRegistry`。禁用或销毁时，它会自动注销——无需手动清理。

#### 检视器字段

| 字段                           | 类型                                   | 默认                | 约束条件           | 说明                                                                     |
| ---------------------------- | ------------------------------------ | ----------------- | -------------- | ---------------------------------------------------------------------- |
| **中搜索“Convai World Object”** | `string`                             | *（GameObject 名称）* | 必填。最多 50 个字符。  | Convai 用于在对话中识别和引用此对象的名称。首次添加该组件时，会根据 GameObject 的名称自动填充。请编辑为清晰、易读的标签。 |
| **Object Description**       | `string`                             | `""`              | 可选。最多 200 个字符。 | 事实性、具体的描述——对象是什么、位于何处，以及任何关键属性。AI 使用此文本来使其回答基于实际情境。                    |
| **包含到元数据中**                  | `bool`                               | `true`            | —              | 未勾选时，此对象会从下一次元数据收集中排除，但不会移除或禁用该组件。使用此项管理运行时是否包含该对象。                    |
| **Tracked Properties**       | `List<ConvaiTrackedContextProperty>` | *（空）*             | 可选。            | 每个条目的运行时属性，作为动态上下文状态键向所有已连接角色公开。请参阅 [跟踪的属性](#tracked-properties) 下文。   |
| **是否已注册** *（只读）*             | `bool`                               | —                 | 只读             | 调试指示器。显示 `true` 当组件当前已在以下对象中注册时 `ConvaiMetadataRegistry`。在播放模式中可见。     |

#### Lifecycle

`ConvaiObjectMetadata` 自行管理其注册：

| 事件           | 行为                                                                      |
| ------------ | ----------------------------------------------------------------------- |
| `OnEnable`   | 向以下对象注册 `ConvaiMetadataRegistry`                                        |
| `OnDisable`  | 从以下对象注销 `ConvaiMetadataRegistry`                                        |
| `OnDestroy`  | 从以下对象注销 `ConvaiMetadataRegistry`                                        |
| `OnValidate` | 自动填充 **中搜索“Convai World Object”** 来自 `gameObject.name` 如果为空；在编辑器中记录验证错误 |

在运行时被停用的 GameObject 不会出现在下一次元数据收集中，即使 **包含到元数据中** 仍处于勾选状态。

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

#### 验证规则

`ConvaiObjectMetadata.IsValid` 返回 `true` 当 **中搜索“Convai World Object”** 为非空且不全为空白字符。50 个字符的限制仅作为编辑器警告通过以下项强制执行： `GetValidationErrors()` ——名称超过 50 个字符的对象仍会通过 `IsValid` 并包含在载荷中。

具有空 **中搜索“Convai World Object”** 无法通过 `IsValid` 并从以下项中排除： `GetValidMetadata()` 以及从发送给 Convai 的载荷中排除。名称超过 50 个字符的对象会包含在载荷中，但会在编辑器中生成验证警告。

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

#### 跟踪的属性

中的每个条目 **Tracked Properties** 是一个 `ConvaiTrackedContextProperty` ——一种可序列化的、按条目定义的配置，可将一个运行时值作为动态上下文状态键公开给每个已连接角色。

| 字段                   | 类型                  | 默认       | 说明                                                                                                                                                                       |
| -------------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **属性名称**             | `string`            | `""`     | 启用此条目时必填。与 **中搜索“Convai World Object”** 组合以形成动态上下文状态键。                                                                                                                   |
| **响应**               | `ConvaiRespondMode` | `Silent` | 当此属性的值变化时应用于角色的反应。请参阅 [`ConvaiRespondMode`](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/relay-component-reference.md#convairespondmode). |
| **初始值**              | `string`            | `""`     | 对象注册时发送的值，以及用于没有 **Source Component** 已配置的条目的值。                                                                                                                          |
| **Source Component** | `组件`                | `无`      | 可选。每次轮询时从中读取实时值的组件。留空则使用固定值。                                                                                                                                             |
| **源成员名称**            | `string`            | `""`     | 可选。以下对象上要读取的属性、字段或无参数方法的名称： **Source Component** 以读取。                                                                                                                    |

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

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

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

### ConvaiSceneMetadataCollector

`ConvaiSceneMetadataCollector` 是协调器。它会监视房间连接事件，从以下对象读取所有有效元数据： `ConvaiMetadataRegistry`，并将载荷发送到 Convai。在检视器中，点击 **添加组件** 中搜索 `Convai Scene Metadata Collector`。将其放置在与以下对象相同场景中的任意 GameObject 上： `ConvaiManager` ——其所需依赖项会在启动时通过以下方式自动解析： `ConvaiManager.ActiveManager`.

#### 检视器字段

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

#### 依赖项和注入

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

如果未注入依赖项（例如，若 `ConvaiManager` 在场景中缺失），收集器会记录错误，并且所有收集调用都将成为空操作。

{% hint style="danger" %}
不要添加 `ConvaiSceneMetadataCollector` 到没有以下对象的场景中： `ConvaiManager`。当 `ConvaiManager` 缺失时，该组件会记录 `"[ConvaiSceneMetadataCollector] 依赖项未注入。请将 ConvaiManager 添加到场景中。"` 作为一个 **error** 在控制台中的错误，并自行禁用。
{% 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 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/component-reference.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.