场景元数据脚本 API

ConvaiMetadataRegistry 和 ConvaiSceneMetadataCollector 的参考，包括静态事件、手动触发模式和调试工具。

场景元数据脚本接口分为两部分。 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 组件禁用或被销毁并自行注销。

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 在启动时注入依赖——无需手动设置。

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。可在开发期间用于发现缺失名称、长度超限或已禁用对象。

常见模式

场景加载时手动触发：

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

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

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

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

发送前审计：

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

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

调试统计：

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

下一步

场景元数据使用示例场景元数据故障排查