场景元数据如何工作

了解场景对象元数据如何在连接时、通过实时更新以及通过跟踪属性变更到达 Convai。

场景元数据是你向 Convai 角色提供关卡中对象知识的方式。添加一个 UConvaiObjectComponent 到任何 Actor ——门、机器、设备等——，关卡中的每个角色都会知道该对象的存在、名称以及作用。当玩家问“这个房间里有什么？”或“北门开着吗？”，角色会利用这些信息来回答。

带标签的对象如何到达 Convai

当会话开始时，插件会收集所有带标签的对象，并将它们的名称和描述一次性发送给 Convai。你在游戏运行时添加或移除的对象会通过单独的更新消息进行同步。

在内部，每个 UConvaiObjectComponent 都会将自身注册到 UConvaiSubsystem 全局池中 BeginPlay。 StartSession(), UConvaiChatbotComponent 从子系统中收集已注册的对象组件，构建 action_config 负载，并将其作为 /connect 握手的一部分发送给 Convai。会话已启动后添加的对象会通过单独的 update-scene-metadata 消息来传输。

会话开始时已存在的对象会保留在一个冻结快照中，且无法在会话中途更新，除非重新启动会话。会话开始后新增的对象条目会通过 update-scene-metadata 在下一次防抖刷新时发送，除非该变更调用使用 bFlushImmediately = true.

上下文通道一览

该插件为 Convai 角色提供三种世界上下文通道，每种通道用途不同：

	场景元数据	跟踪属性	SetObjectInAttention
描述内容	静态 Actor场景中的对象和道具	某个 Actor UPROPERTY 或函数	角色当前专注的具体对象
发送时间	一次，在会话开始时（冻结快照）或通过运行时环境更新为新条目	在会话开始时发送，然后在检测到值变化时发送	在显式调用或视线管线触发时发送
典型用途	“主入口处的一扇上锁的门”	“门现在已解锁”	“角色注意到灭火器”

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

Convai 对象组件

UConvaiObjectComponent 是一个 ActorComponent 你附加到任何 Actor 你希望 Convai 角色了解的对象上。只需在该 Actor 上放置一个组件即可；关卡中的每个聊天机器人都会自动看到它，无需逐个聊天机器人配置。

在 BeginPlay 该组件加入 UConvaiSubsystem 池。此后启动会话的每个聊天机器人都可以将 Actor 纳入其环境中。

对象标识

每个 UConvaiObjectComponent 包含一个 ObjectEntry (FConvaiObjectEntry），用于描述该 Actor 给 Convai：

• 名称 ——聊天机器人引用此对象时使用的标签。它在每个关卡中都必须唯一。如果两个组件共享同一个名称， UConvaiSubsystem 会自动重命名重复项，并向输出日志写入警告。
• 说明 ——Convai 在会话开始时接收的一句或一段自然语言描述。

Convai 接收该对象的名称于 name 字段中 action_config.objects 条目。保持名称简短且具描述性（例如 “FrontDoor” 而不是 “BP_Door_01”）可使引用更容易解析。

跟踪属性

除了静态标识之外，你还可以为受支持的 UPROPERTY 值或受支持的纯无参数函数附加实时状态观察器，使用 TrackedProperties (TArray<FConvaiTrackedProperty>).

每个 FConvaiTrackedProperty 包含：

• PropertyPath ——一个带点号的路径，指向 UPROPERTY 或函数，在运行时相对于所属的 Actor （例如 “bIsLocked”, “Stats.HP”, “GetCurrentRoomName”).
• 说明 ——该值的自然语言含义。
• StateValueDescriptions ——每个值可选的注释，对枚举和布尔值最有用。
• ShouldRespond (EC_RunLLMOption）——该值在运行时变化时会发生什么。

在会话开始时，每个被跟踪属性的当前值都会以 EC_RunLLMOption::Never注入聊天机器人的上下文中，因此角色会在不发言的情况下得到告知。每次检测到变化时，插件都会发送一个动态上下文状态更新，并使用已配置的 ShouldRespond: Auto 让 Convai 决定是否作出反应， 始终 请求响应，并 从不 静默更新。

聊天机器人看到的被跟踪属性键是 “<ObjectName>.<PropertyPath>” ——例如 “FrontDoor.bIsLocked”.

接近状态

当 bAutoGenerateProximityState 为 true （默认值），插件会计算一个合成状态键 “<ObjectName>.ProximityToYou” ，方法是查询 Unreal Engine 导航系统。支持部分路径，因此即使聊天机器人无法沿完整导航路线到达该对象，接近描述也仍然有意义。

该值将可达性和相对方向结合起来，形成诸如 “附近，前方”, “有一段距离，左侧”，或 “没有步行路径，后方”。当对象或聊天机器人正在主动移动时（稳定性门控），评估会被延后，并在连续若干次延后 tick 后强制执行。由于接近信息属于空间上下文而非对话内容， ShouldRespond 接近状态的 EC_RunLLMOption::Never始终为；Convai 会被静默告知。

bDebugDrawProximityPaths 会在编辑器视口中绘制从每个聊天机器人到该对象的导航路径，前提是 bAutoGenerateProximityState 已开启。在发布前请关闭此标志。

会话开始时与游戏过程中分别发送什么

会话握手会传递对象列表的冻结快照（action_config.objects）。 bEnableActions 布尔值 on EnvironmentData 控制连接时的动作配置：当它处于 false，则 action_config 时，该块不会在会话开始时发送，并且通过 SetObjectInAttention 不起作用。

一旦会话处于运行状态， UConvaiChatbotComponent 上的对象和角色变更方法会更新本地环境镜像并安排同步。新的场景条目和移除会通过 update-scene-metadata；而连接时快照中已存在的条目会保留其原始 action_config 数据，直到重新连接。

有一个重要限制：如果某个对象在会话开始时已包含在 action_config 中，那么冻结快照里的描述就不能在会话中途更改。只有对该会话而言是新对象的条目才会通过实时 update-scene-metadata 通道传输。要将描述更改传播到现有对象，请调用 StopSession 然后 StartSession 以使用更新后的描述重新连接。

批量处理更新

当你快速连续调用多个添加或移除方法时，插件会将它们合并为一条网络消息，而不是每次调用都发送一条消息。这是默认行为。传入 bFlushImmediately = true 会跳过批处理窗口并立即发送。请谨慎使用 bFlushImmediately ——频繁调用会产生许多小型 WebRTC 消息，并增加网络开销。

下一步

场景元数据快速入门场景元数据组件参考运行时管理环境