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

# 场景元数据脚本 API

场景元数据脚本接口分为两部分。 `ConvaiMetadataRegistry` 是静态中央注册表——用于查询注册状态并监听变更。 `ConvaiSceneMetadataCollector` 是运行时协调器——用于触发采集、检查就绪状态，并审计所有已注册对象。

### ConvaiMetadataRegistry

`ConvaiMetadataRegistry` 是一个静态类。可直接通过类名访问所有成员——无需实例或组件引用。

#### 属性

| 成员   | 类型    | 说明                                            |
| ---- | ----- | --------------------------------------------- |
| `数量` | `int` | 已注册的总数 `ConvaiObjectMetadata` 实例，包括无效和已禁用的实例。 |

#### 方法

| 方法                        | 返回                           | 说明                                                                                                                        |
| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `GetAllMetadata()`        | `ConvaiObjectMetadata[]`     | 返回所有已注册实例，包括名称为空、已禁用 `Include In Metadata`或空引用的实例。                                                                        |
| `GetValidMetadata()`      | `ConvaiObjectMetadata[]`     | 仅返回非空、具有 `Include In Metadata` 已启用并通过名称验证（`IsValid == true`）。这正是下一次发送中包含的集合。                                              |
| `GetSceneMetadataList()`  | `List<SceneMetadata>`        | 将所有有效元数据转换为可序列化的传输格式。这是发送给 Convai 的负载。                                                                                    |
| `GetStatistics()`         | `Dictionary<string, object>` | 返回包含以下键的分解： `TotalRegistered`, `ValidMetadata`, `InvalidMetadata`, `NullReferences`, `ValidNames`, `InvalidReasons`。用于调试。 |
| `CleanupNullReferences()` | `int`                        | 移除已销毁但尚未注销的条目。返回移除的数量。如果对象是在正常 Unity 生命周期事件之外被销毁的，请调用此方法。                                                                 |
| `Clear()`                 | `void`                       | 清除所有已注册条目。用于测试和场景卸载。不要在生产环境中调用。                                                                                           |

#### 静态事件

| 事件                       | 签名                             | 当                                       |
| ------------------------ | ------------------------------ | --------------------------------------- |
| `OnMetadataRegistered`   | `Action<ConvaiObjectMetadata>` | A `ConvaiObjectMetadata` 组件启用并自行注册。     |
| `OnMetadataUnregistered` | `Action<ConvaiObjectMetadata>` | A `ConvaiObjectMetadata` 组件禁用或被销毁并自行注销。 |

```csharp
void OnEnable()
{
    ConvaiMetadataRegistry.OnMetadataRegistered += HandleObjectRegistered;
    ConvaiMetadataRegistry.OnMetadataUnregistered += HandleObjectUnregistered;
}

void OnDisable()
{
    ConvaiMetadataRegistry.OnMetadataRegistered -= HandleObjectRegistered;
    ConvaiMetadataRegistry.OnMetadataUnregistered -= HandleObjectUnregistered;
}

private void HandleObjectRegistered(ConvaiObjectMetadata metadata)
{
    Debug.Log($"已注册: {metadata.ObjectName}（总计 {ConvaiMetadataRegistry.Count} 个）");
}

private void HandleObjectUnregistered(ConvaiObjectMetadata metadata)
{
    Debug.Log($"已注销: {metadata.ObjectName}");
}
```

### ConvaiSceneMetadataCollector

通过组件引用访问。 `ConvaiManager` 在启动时注入依赖——无需手动设置。

```csharp
private ConvaiSceneMetadataCollector _collector;

void Awake()
{
    _collector = FindObjectOfType<ConvaiSceneMetadataCollector>();
}
```

#### 公共方法

| 方法                              | 返回                    | 说明                                                                                                                                |
| ------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `IsReadyToSendMetadata()`       | `bool`                | 返回 `true` 当依赖已注入且房间会话处于 `已连接` 状态时。请务必在调用 `CollectAndSendSceneMetadata()` 之前先检查。                                                   |
| `CollectAndSendSceneMetadata()` | `void`                | 从 `ConvaiMetadataRegistry`读取所有有效元数据，组装负载，并通过 RTVI 将其发送给 Convai `update-scene-metadata` 消息。如果房间未连接或依赖未注入，则会提前返回并向 Console 记录警告或错误。 |
| `GetMetadataCount()`            | `int`                 | 返回可包含的有效对象数量，不会触发发送。可用于 UI 显示或发送前验证。                                                                                              |
| `GetCurrentMetadata()`          | `List<SceneMetadata>` | 返回当前负载列表，不会触发发送。可用于查看下一次调用将发送什么。                                                                                                  |
| `ValidateAllMetadata()`         | `void`                | 将所有已注册对象的验证问题记录到 Console。可在开发期间用于发现缺失名称、长度超限或已禁用对象。                                                                               |

#### 常见模式

**场景加载时手动触发：**

```csharp
IEnumerator LoadScenario(ScenarioData data)
{
    yield return StartCoroutine(SpawnScenarioProps(data));

    // 等待房间就绪
    yield return new WaitUntil(() => _collector.IsReadyToSendMetadata());
    _collector.CollectAndSendSceneMetadata();
}
```

**运行时排除对象并重新发送：**

```csharp
// 当锁着的门打开时，将其从 AI 上下文中移除
void OnDoorUnlocked(ConvaiObjectMetadata doorMetadata)
{
    doorMetadata.IncludeInMetadata = false;
    if (_collector.IsReadyToSendMetadata())
        _collector.CollectAndSendSceneMetadata();
}
```

**发送前审计：**

```csharp
void LogPreSendAudit()
{
    _collector.ValidateAllMetadata(); // 将所有问题打印到 Console
    Debug.Log($"将发送 {_collector.GetMetadataCount()} 个对象");

    var preview = _collector.GetCurrentMetadata();
    foreach (var item in preview)
        Debug.Log($"  - {item.Name}: {item.Description}");
}
```

**调试统计：**

```csharp
var stats = ConvaiMetadataRegistry.GetStatistics();
foreach (var kv in stats)
    Debug.Log($"{kv.Key}: {kv.Value}");
```

### 下一步

{% content-ref url="/pages/16c5aa93667aec71180b560b3408b114f488e893" %}
[场景元数据使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/usage-examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/f6f3f3d88a3636afea1b0c8774162c2014fba780" %}
[排查场景元数据问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/troubleshooting-and-diagnostics.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/scripting-api-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.