> 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).

# 场景元数据组件参考

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

### ConvaiObjectMetadata

**添加组件路径：** `Convai → 对象元数据`

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

#### Inspector 字段

| 字段                       | 类型       | 默认值               | 约束             | 说明                                                                   |
| ------------------------ | -------- | ----------------- | -------------- | -------------------------------------------------------------------- |
| **Object Name**          | `string` | *（GameObject 名称）* | 必填。最多 50 个字符。  | Convai 用于在对话中识别并引用此对象的名称。首次添加组件时，会自动从 GameObject 的名称填充。可编辑为清晰、易读的标签。 |
| **Object Description**   | `string` | `""`              | 可选。最多 200 个字符。 | 一段真实、具体的描述——对象是什么、位于哪里，以及任何关键属性。AI 使用这段文本来锚定其回复。                     |
| **Include In Metadata**  | `bool`   | `true`            | —              | 取消勾选后，此对象会在下一次元数据收集中被排除，但不会移除或禁用该组件。可用于管理运行时是否纳入。                    |
| **Is Registered** *（只读）* | `bool`   | —                 | 只读             | 调试指示器。显示 `true` 当该组件当前已注册到 `ConvaiMetadataRegistry`。在播放模式下可见。        |

#### 生命周期

`ConvaiObjectMetadata` 自行管理注册：

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

在运行时被停用的 GameObject 将不会出现在下一次元数据收集中，即使 **Include In Metadata** 仍然勾选。

#### 验证规则

`ConvaiObjectMetadata.IsValid` 返回 `true` 当 **Object Name** 非空且不全是空白字符。50 字符限制仅通过编辑器警告强制提示，使用 `GetValidationErrors()` ——名称超过 50 个字符的对象仍然会通过 `IsValid` 并包含在负载中。

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

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

### ConvaiSceneMetadataCollector

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

#### Inspector 字段

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

#### 依赖项与注入

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

如果这些依赖项未被注入（例如，如果 `ConvaiManager` 未出现在场景中），采集器会记录警告，且所有收集调用都将变为无操作。

{% hint style="danger" %}
不要将 `ConvaiSceneMetadataCollector` 添加到没有 `ConvaiManager`。当 `ConvaiManager` 缺失时，组件会记录 `"[ConvaiSceneMetadataCollector] 依赖项未注入。请将 ConvaiManager 添加到场景中。"` 作为 **error** 在 Console 中的消息，并自行禁用。
{% endhint %}

#### 手动触发

当 **Collect On Start** 被禁用时，请调用 `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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/component-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.