场景元数据的工作原理

了解场景对象元数据的注册与传递流程，并学习何时使用场景元数据而不是动态上下文。

ConvaiObjectMetadata 和 ConvaiMetadataRegistry 构成核心流水线，从你的场景中收集对象描述，并在每个角色准备就绪时将它们传递给 Convai。该流水线随后还会持续保持已连接角色的对象感知最新——已注册对象在发生更改时可以重新同步其静态描述，或通过受跟踪属性报告变化的运行时状态。 ConvaiSceneMetadataCollector 是一个可选的配套组件，用于手动控制、统计和审计——下文描述的自动传递并不需要它。理解这两条路径有助于你正确配置系统，并在对象没有到达角色时进行调试。

连接时传递流程

每个 ConvaiObjectMetadata 组件都会在 ConvaiMetadataRegistry 启用时自行向……注册。这一过程独立于任何 ConvaiSceneMetadataCollector 位于场景中。

自动的连接时发送由 ConvaiCharacter 本身驱动，而不是由收集器驱动。当角色从 Convai 收到其就绪信号时，它会捕获其动作配置对象和角色的快照，为任何受跟踪属性赋值，并将场景元数据标记为待同步。该待处理标志会在角色下一次批量更新时清除——与动态上下文更新使用的相同批处理窗口——该更新会读取注册表并将负载作为一条 update-scene-metadata RTVI 消息。

对象会在启用和禁用时自行注册和注销——无需手动清理。角色就绪后，Convai 会接收所有已注册对象的当前状态，而无需 ConvaiSceneMetadataCollector 需要手动触发。此后所做的任何更改都会通过下文描述的实时重新同步路径传递。

ConvaiSceneMetadataCollector的 启动时收集 选项如果启用，还会在连接时发送完整负载——这会重复上面的自动发送，对于基本设置来说是多余的。收集器适用于你需要统计日志、手动触发点（CollectAndSendSceneMetadata()），或发送前审计（ValidateAllMetadata()），而不是因为对象要到达角色就必须使用它。完整字段列表请参见 场景元数据组件参考 。

实时重新同步和受跟踪属性

在初始连接时发送之后，有两种机制可使角色的对象感知保持最新。

静态元数据的实时重新同步

设置项 ObjectName, ObjectDescription，或 IncludeInMetadata 通过脚本在一个 ConvaiObjectMetadata 当前已注册的对象会将 ConvaiMetadataRegistry 标记为脏，并通知每个已连接角色。注册或注销一个 ConvaiObjectMetadata 在会话连接期间的组件——例如启用或禁用其 GameObject，或在运行时添加该组件——都会产生相同效果。每个收到通知的角色都会在下一次刷新时自动发送一条后续 update-scene-metadata 消息，而无需手动 CollectAndSendSceneMetadata() 调用。

跟踪的属性

ConvaiObjectMetadata 还可以声明受跟踪属性：一个 ConvaiTrackedContextProperty 条目列表，每个条目命名一个属性、一个初始值、一个可选的运行时源（一个 组件 以及在每次轮询时通过反射读取的成员名），还有一个 ConvaiRespondMode 响应。内部轮询驱动程序每 0.25 秒检查一次每个已注册对象的受跟踪属性，并通过 DynamicContext.SetState，键为 {ObjectName}.{PropertyName}.

受跟踪属性不会以一条 update-scene-metadata 消息的形式传输。它们使用 SetState 与手动调用相同的动态上下文传输，从而让场景对象自身的状态保持同步，而无需在你自己的脚本中编写任何轮询代码。

受跟踪属性走的是动态上下文通道，但它们是在世界对象的 Inspector 中以声明式方式编写的，而不是从脚本中以命令式方式推送的。当对象自身的状态应自动与角色保持同步时请使用它们。当事件和状态不属于任何单个场景对象时，请使用手动 SetState 调用。

场景元数据与动态上下文

这两个系统都会向角色的上下文中注入信息，但它们用于不同目的：

	场景元数据	动态上下文
由谁填充	SDK 自动发现对象	开发者手动注入状态
描述什么	场景中的物理对象和实体	运行时状态、事件、玩家操作
发送时间	在房间连接时发送，然后在已注册对象的名称、描述或包含关系发生变化时自动重新发送	随时按需发送——包括受跟踪属性持续发送时，它们每 0.25 秒轮询一次
典型用途	“南墙上有一个灭火器”	“受训者未通过阀门检查”

将两者结合使用，可获得最丰富的 AI 上下文体验。

场景元数据描述静态世界——有什么存在。动态上下文描述动态世界——正在发生什么。二者相辅相成，而非相互竞争。

下一步

场景元数据快速开始场景元数据使用示例