场景元数据组件参考

Convai Object Component 的完整属性、函数和事件参考，包括对象身份、被跟踪属性、接近状态和注视事件。

UConvaiObjectComponent 是你添加到任何 Actor 在你的关卡中，使 Convai 角色能够感知它。内部而言，它是一个 ActorComponent （类组 Convai），它会与 UConvaiSubsystem自动绑定 ObjectEntry.Ref 到所属的 Actor 当 Ref 未设置，并向关卡中的每个 Convai 角色公开对象身份、实时状态属性和凝视事件。

对象标识

该 ObjectEntry 属性（FConvaiObjectEntry）描述 Actor 到 Convai。因为 ObjectEntry 使用 ShowOnlyInnerProperties，其字段会直接显示在详情面板中，而不是折叠在结构体下。

核心身份字段

这些字段属于 ObjectEntry.

属性	类型	默认值	说明
名称	FString	—	聊天机器人用于此对象的显示名称。每个关卡中必须唯一； UConvaiSubsystem 会自动重命名重复项，并向输出日志写入警告。
说明	FString	—	Convai 在会话开始时接收的通俗描述。

导航目标字段

这些字段控制 Convai 角色在执行移动动作时如何实际移动到该对象。对于大多数对象，默认值就足够了——只有在需要精确的移动目标时才进行配置。它们属于 ObjectEntry.

属性	类型	默认值	说明
移动目标模式	EConvaiMoveTarget	将 Actor 作为目标	AI 如何导航到此对象。
接受半径	float （厘米）	150	移动到达动作被视为完成的距离（厘米）。
组件名称	FString	—	的子组件目标，适用于 将组件作为目标 模式。留空则以 Actor 原点为目标。
Socket 或 Bone 名称	FName	—	匹配组件上的 Socket 或骨骼（将组件作为目标 仅限模式）。
踏上边界 (bStepOntoBounds)	bool	false	当 true时，AI 会导航到目标边界的顶部表面，而不是停在边缘。适用于 将 Actor 作为目标 模式（使用整个 Actor 边界）以及 将组件作为目标 模式（使用解析后的组件边界）。

移动目标模式

EConvaiMoveTarget 控制 Convai 如何指示 AI 对此对象进行导航：

• 将 Actor 作为目标 — AI 会停在 Actor 碰撞边界处。适用于较大或环境类对象： “走到汽车旁”, “跟随玩家”.
• 将组件作为目标 — AI 会走到某个特定子组件点，也可指定命名的 socket 或 bone。适用于精确目标： “站在门把手旁”, “走上平台”.

跟踪属性

TrackedProperties (TArray<FConvaiTrackedProperty>，类别 Convai|Object）保存附加到此的实时状态观察者列表 Actor.

字段	类型	默认值	说明
PropertyPath	FName	—	所属对象上的点路径或函数名 Actor。使用 Bind 详情面板中的按钮可正确填充此项。
说明	FString	—	此属性对 AI 的通俗含义。
StateValueDescriptions	TArray<FConvaiTrackedPropertyStateValueDesc>	—	针对枚举、布尔值或命名状态的每个值的注释。显示在 高级 在详情面板中。
ShouldRespond	EC_RunLLMOption	从不	值在运行时变化时会发生什么。

FConvaiTrackedPropertyStateValueDesc 包含两个字符串字段： 值 （发送给 Convai 的字面值）以及 说明 （该值的通俗含义）。

ShouldRespond 选项

EC_RunLLMOption 控制当跟踪属性值发生变化时聊天机器人的行为：

• Auto — Convai 会根据对话上下文决定是否响应。
• 始终 — 更新会在每次变化时请求响应。
• 从不 — 值会静默更新；聊天机器人会被告知，但不会说话。

会话开始时的初始种子始终为 EC_RunLLMOption::Never 无论 ShouldRespond 被设置为什么——聊天机器人会了解初始值，但不会做出反应。

接近状态

属性	类型	类别	默认值	说明
bAutoGenerateProximityState	bool	Convai|Object	true	当 true，插件会计算一个 “<ObjectName>.ProximityToYou” 使用 UE 导航系统为每个聊天机器人生成一个状态键。
bDebugDrawProximityPaths	bool	Convai|Object|Debug	false	在编辑器视口中绘制每个聊天机器人到该对象的导航路径。显示在 调试 详情面板中的子类别下。在发布前禁用。

接近状态始终使用 EC_RunLLMOption::Never；聊天机器人会获知空间关系，但不会做出反应。当聊天机器人或对象正在移动，或者聊天机器人旋转不稳定时，评估会延后；在连续几次延后 tick 后会强制执行。

凝视

所有凝视属性和事件都位于 Convai|Object|Gaze 类别下。

名称	种类	默认值	说明
bGazeable	bool 属性	true	当 false，凝视管线会完全跳过此对象——没有高亮、没有凝视事件，也不会提升注意力。设置为 false 用于应存在于 AI 环境中但不应吸引玩家凝视的背景道具。
OnGazedIn / OnGazedOut	BlueprintAssignable 委托	—	当玩家的凝视进入或离开此对象时立即触发（在跨越注意力阈值之前）。
OnAttentionGained / OnAttentionLost	BlueprintAssignable 委托	—	当对象组件在尝试向聊天机器人分发后收到凝视注意开始或结束通知时触发。

有关完整的凝视管线、玩家端设置和故障排查，请参见 凝视注意力参考.

蓝图函数

对象函数（类别 Convai|Object)

函数	返回	说明
GetResolvedComponent(bForceRefresh)	USceneComponent*	返回目标场景组件，或者 nullptr 当整个 Actor 是作用范围时。
AddTrackedProperty(InProperty)	bool	在运行时添加一个跟踪属性。返回 false 如果该路径在 Actor上不存在、类型不受支持，或者该路径已被跟踪。
RemoveTrackedProperty(PropertyPath)	bool	停止跟踪某个属性。返回 true 如果属性已被移除。
UpdateTrackedProperty(PropertyPath, NewSettings)	bool	更新 说明, StateValueDescriptions，或 ShouldRespond 用于现有条目。路径是键；若要更改路径，请先移除再重新添加。
GetTrackedProperties(OutProperties)	void	将当前跟踪属性列表的副本写入 OutProperties.

使用 RemoveTrackedProperty 不会从聊天机器人的上下文中清除其最后发送的值。该属性会停止更新，但聊天机器人仍会保留它收到的最后一个值。设计属性移除流程时请考虑这一点。

凝视函数（类别 Convai|Object|Gaze)

函数	返回	说明
NotifyGazeBegin(Player)	void	标记凝视进入。由 UConvaiPlayerComponent自动调用；也可从自定义焦点系统中调用。
NotifyGazeEnd(Player)	void	与以下函数配套： NotifyGazeBegin.
NotifyGazeAttentionBegin(Player, Text, ShouldRespond)	void	通过子系统请求在符合条件的聊天机器人之间提升凝视注意力。也 BlueprintCallable 可用于非凝视流程，例如电影摄像机或自定义焦点系统。
NotifyGazeAttentionEnd(Player)	void	释放注意状态。 玩家 可能是 nullptr 在目标已销毁的路径中—— OnAttentionLost 的接收方必须进行空值检查 玩家 后再使用它。

相关参考

场景元数据如何工作运行时管理环境场景元数据使用示例