运行时管理环境

针对 chatbot 环境方法的参考，这些方法会在活动游戏会话期间添加、移除和更新对象与角色。

在游戏运行时使用这些方法更新聊天机器人的世界知识——例如，当新房间加载、道具生成或新的 NPC 进入场景时。 UConvaiChatbotComponent 为对象、角色、当前对话对象、注意中的对象以及连接时的环境附加项提供变更方法。运行时变更方法位于 BlueprintCallable 在 Convai|Actions 类别； GatherEnvironmentExtras 属于 BlueprintCallable 在 Convai|Session 类别。

方法分组一览

组	方法	用途
对象	AddObject, AddObjects, RemoveObject, RemoveObjects, ClearObjects	在会话进行中添加或移除世界对象
角色	AddCharacter, AddCharacters, RemoveCharacter, RemoveCharacters, ClearCharacters	添加或移除聊天机器人可引用的其他 NPC
对话对象	SetConversationPartner	告诉聊天机器人它正在与谁交谈
注意	SetObjectInAttention, TrySetObjectInAttentionFromGaze, TryClearObjectInAttentionFromGaze	设置、通过注视门控，或清除注意中的对象
会话开始	GatherEnvironmentExtras	在 /connect 之前填充附加项 /connect
实用工具	EnsureObjectComponentsForEnvironmentObjects	生成缺失的 UConvaiObjectComponent 实例

大多数会推送网络更新的方法都接受一个 bFlushImmediately 参数。 TryClearObjectInAttentionFromGaze 通过非立即路径进行清除。参见 防抖与刷新 了解详情。

该 FConvaiEnvironmentData 结构体

EnvironmentData (FConvaiEnvironmentData）是静态配置， UConvaiChatbotComponent 会在以下时发送给 Convai /connect 。它包含：

• bEnableActions (bool，默认 true）—— 连接时的动作配置开关。当 false，则 action_config 块不会在 /connect发送，并且通过 SetObjectInAttention 不起作用。
• 动作 —— 默认动作列表（移动到, 跟随, 停止移动, 等待).
• 对象 —— 在连接时暴露给聊天机器人的对象。
• 角色 —— 在连接时暴露给聊天机器人的角色。
• CurrentAttentionObject —— 当前用于注意和引用解析的对象。

请通过以下方法变更环境，而不是直接写入 EnvironmentData 来自 Blueprint 的字段。

添加和移除对象

方法	说明
AddObject(Object, bFlushImmediately)	添加一个 FConvaiObjectEntry 并安排一次 update-scene-metadata 推送，当该对象不在连接时快照中时。
AddObjects(Objects, bFlushImmediately)	一次调用添加多个条目。
RemoveObject(ObjectName, bFlushImmediately)	移除与给定名称匹配的条目并安排一次同步。
RemoveObjects(ObjectNames, bFlushImmediately)	按名称移除多个条目。
ClearObjects(bFlushImmediately)	从本地列表中移除所有对象。

如果某个对象包含在 action_config 在 /connect，调用 AddObject 使用相同名称不会更新冻结的 action_config 快照。只有对该会话来说是新增的对象才会通过实时 update-scene-metadata 通道传递。要将描述更改传播到现有对象，请调用 StopSession 然后 StartSession 以重新连接。

添加和移除角色

方法	说明
AddCharacter(Character, bFlushImmediately)	添加一个 FConvaiObjectEntry 到角色列表。
AddCharacters(Characters, bFlushImmediately)	添加多个条目。
RemoveCharacter(InCharacterName, bFlushImmediately)	按名称移除匹配的条目。
RemoveCharacters(InCharacterNames, bFlushImmediately)	按名称移除多个条目。
ClearCharacters(bFlushImmediately)	从本地列表中移除所有角色。

设置对话对象

SetConversationPartner(Partner, bFlushImmediately) 告诉聊天机器人它当前正在与哪个其他角色交谈。如果 Partner.Name 尚未在 EnvironmentData.Characters中，该方法会自动添加它。

要在不从列表中移除该角色的情况下清除对话对象，请传入一个 FConvaiObjectEntry 带有空的 Name.

控制注意

SetObjectInAttention(Object, Text, ShouldRespond, bFlushImmediately) 设置聊天机器人当前关注的对象，并可选择触发上下文事件。该调用在 bEnableActions 属于 false。如果该对象尚未在对象列表中，该方法会自动添加它。

AttentionSource (EConvaiAttentionSource, Transient, BlueprintReadOnly，类别 Convai|Actions）反映上一次设置注意的是谁：

• 无 —— 未设置注意目标。
• 显式 (显式（Blueprint/C++））—— 注意由 Blueprint 或 C++ 代码设置。
• 注视 —— 注意由注视管线设置。

当 AttentionSource 属于 显式时，对 TrySetObjectInAttentionFromGaze 的调用会被阻止并返回 false。这可防止注视系统覆盖显式的程序设置注意。

TryClearObjectInAttentionFromGaze(ExpectedObject) 仅在以下情况下清除由注视拥有的注意槽：当 AttentionSource 属于 注视 并且当前注意对象仍匹配 ExpectedObject.Name。这可保护较新的注意目标，避免被来自较旧目标的延迟注视结束事件清除。

在会话开始时填充环境

使用 GatherEnvironmentExtras 适用于关卡是程序生成的情况，或者你需要从运行时世界查询构建对象列表，而不是在 Details 面板中手动放置组件。

GatherEnvironmentExtras 是一个 BlueprintNativeEvent （显示名称 “Gather Environment Extras”）在以下内部调用一次 StartSession() 在 /connect 握手过程中。请在以下 Blueprint 子类中重写它： UConvaiChatbotComponent 以附加依赖于运行时世界状态的对象、角色或动作。

该重写会接收三个输出数组：

• OutExtraActions —— 附加到默认动作列表。
• OutExtraObjects —— 附加到 EnvironmentData.Objects.
• OutExtraCharacters —— 附加到 EnvironmentData.Characters.

该重写是在已配置的默认值上追加，而不是替换它们。这里才是通过世界查询填充环境的正确位置，而不是通过 Details 面板。

参见 场景元数据使用示例 ，查看这种模式的完整伪代码示例。

确保对象组件

EnsureObjectComponentsForEnvironmentObjects() 遍历 EnvironmentData.Objects。对于每个具有有效 Ref actor，它会生成一个匹配的 UConvaiObjectComponent ，前提是尚无现有组件覆盖同一目标。它返回新生成组件的数量，并且可安全多次调用（幂等）。

自动生成的组件会注册到整个子系统范围的对象池中，因此关卡中的每个聊天机器人都能通过与手动放置的对象组件相同的接近度、跟踪属性和注视管线看到它们。

在以下时机调用它： BeginPlay 在填充之后 EnvironmentData.Objects 从代码中，或者在调用 AddObject / AddObjects 当你希望接近度和注视系统跟踪动态添加的 Actor 时。

防抖与刷新

所有变更方法都会在防抖窗口内批量处理更新，将快速调用合并为一条 WebRTC 消息。传入 bFlushImmediately = true 以绕过该窗口并立即发送。请谨慎使用 bFlushImmediately —— 高频调用会产生许多小消息并增加网络开销。

下一步

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