场景元数据组件参考

用于向 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>	（空）	可选。	每个条目的运行时属性会作为动态上下文状态键暴露给所有已连接角色。参见 跟踪的属性 下方。
已注册 （只读）	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 个字符的对象会包含在负载中，但会在编辑器中生成验证警告。

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

跟踪的属性

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

字段	类型	默认值	描述
属性名称	string	""	启用此条目所必需。与 对象名称 组合以形成动态上下文状态键。
反应	ConvaiRespondMode	静默	当此属性值发生变化时应用于角色的反应。参见 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 不在场景中），收集器会记录错误，且所有收集调用都将变为无操作。

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

手动触发

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

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

有关完整的公共方法列表，请参见 场景元数据脚本 API.

下一步

场景元数据脚本 API场景元数据使用示例