Convai Object 组件

对象标记组件的参考——Convai Object Component 暴露的每个 Blueprint 可见属性、函数和事件。

UConvaiObjectComponent 被添加到任何 Actor ——门、开关、箱子、房间触发器、载具——，使其自动对关卡中的所有 Convai 聊天机器人可见。它对世界对象所起的作用与 UConvaiChatbotComponent 用于 AI 角色，而 UConvaiPlayerComponent 用于玩家。

添加组件路径： Convai Object Component。无需手动向各个聊天机器人注册：插件的子系统会发现所有已注册的对象组件，并在会话开始时将它们的身份和状态注入到每个聊天机器人中。

身份

该 ObjectEntry 属性通过 ShowOnlyInnerProperties。下表中的所有字段都会直接显示在组件的 Details 面板中，而不是位于嵌套结构体内。父组件属性位于 Convai|Object；内部结构体字段保留其 Convai|Action API 元数据。

属性	类型	默认值	类别	说明
名称 （通过 ObjectEntry)	FString	""	Convai|Action API	发送给 Convai 的显示名称。必须在关卡中的所有对象和角色之间唯一——重复项会由子系统自动重命名。
说明 （通过 ObjectEntry)	FString	""	Convai|Action API	该对象给 AI 的自然语言描述。
移动目标模式 （通过 ObjectEntry)	EConvaiMoveTarget	Actor	Convai|Action API	AI 移动动作是针对整个 Actor（将 Actor 作为目标）还是其上的某个特定组件或 Socket（将组件作为目标).
接受半径 （通过 ObjectEntry)	float （厘米）	150.0	Convai|Action API	……的距离 AI 移动到 会认为移动已完成。
组件名称 （通过 ObjectEntry)	FString	""	Convai|Action API	在对 Actor 的组件进行匹配时，不区分大小写的子字符串， 移动目标模式 为 将组件作为目标。留空则使用 Actor 的原点。
Socket 或 Bone 名称 （通过 ObjectEntry)	FName	无	Convai|Action API	已解析组件上的 Socket 或骨骼。仅在 移动目标模式 为 将组件作为目标。未找到时回退到组件原点。
bStepOntoBounds （通过 ObjectEntry)	bool	false	Convai|Action API	当 true，目标点会投影到目标边界框顶部，这样 AI 会走上平台或表面，而不是停在边缘。两种移动目标模式都适用。

有关 FConvaiObjectEntry 字段以及 EConvaiMoveTarget 枚举，请参见 数据类型和枚举.

身份函数

函数	返回	类别	说明
GetResolvedComponent(bForceRefresh)	USceneComponent*	Convai|Object	返回使用 组件名称，或 nullptr 当对象针对整个 Actor 时。结果会被缓存；传入 bForceRefresh = true 可绕过缓存。

跟踪属性

此 Actor 上 AI 会实时感知的属性。每一项都会选择一个 UPROPERTY （或一个返回字符串的纯函数），说明其含义，可选地说明各个取值的含义，并指定聊天机器人应如何对变化作出反应。

属性	类型	默认值	类别	说明
TrackedProperties	TArray<FConvaiTrackedProperty>	[]	Convai|Object	要监视的属性列表。每个被跟踪的属性都会在会话开始时发送给所有聊天机器人，并在游戏过程中其值发生变化时再次发送。

有关 FConvaiTrackedProperty 是位于 FConvaiTrackedPropertyStateValueDesc 字段，参见 数据类型和枚举.

跟踪属性函数

这些函数可在运行时添加、移除和更新跟踪属性——适用于只有在玩家执行某个动作后才变得相关的属性。

函数	返回	输入	类别	说明
AddTrackedProperty(InProperty)	bool	InProperty (FConvaiTrackedProperty)	Convai|Object	添加一个新的跟踪属性，并立即将其当前值推送给所有聊天机器人。返回 false 当该属性路径在此 Actor 上不存在、无法被跟踪（不支持的类型），或已在列表中时返回
RemoveTrackedProperty(PropertyPath)	bool	PropertyPath (FName)	Convai|Object	停止跟踪该属性。返回 true 如果已移除。最后一次广播的值会保留在每个聊天机器人的上下文中，并停止更新。
UpdateTrackedProperty(PropertyPath, NewSettings)	bool	PropertyPath (FName), NewSettings (FConvaiTrackedProperty)	Convai|Object	更新已跟踪属性的描述、状态值说明，或 ShouldRespond 模式。 PropertyPath 是关键——如果需要针对不同属性，请先移除再重新添加。
GetTrackedProperties(OutProperties)	—	OutProperties (TArray<FConvaiTrackedProperty>&)	Convai|Object	返回当前跟踪属性列表的副本，供 Blueprint 检查。

接近状态

属性	类型	默认值	类别	说明
bAutoGenerateProximityState	bool	true	Convai|Object	当 true，插件会自动为每个聊天机器人生成一个 “<ObjectName>.ProximityToYou” 状态键，用通俗语言描述该对象相对于每个聊天机器人的位置。示例值包括 “附近，前方偏右”, “很远，在后方”，以及 “没有步行路径，后方”.

该接近度值会作为一个跟踪属性发送给每个聊天机器人，并带有 ShouldRespond = Never。当聊天机器人或对象正在移动时，插件会延迟更新，并复用上一次可达性结果，直到任一端移动超过 ~100 厘米，因此静止场景几乎没有性能开销。设计师手动编写的 TrackedProperties 名为 ProximityToYou 会覆盖同一状态键的合成值。

接近度状态使用 Unreal 的导航系统（允许部分路径），并在共享轮询 tick 上评估（通常每个对象 0.25 s 次）。当 bStepOntoBounds 为 false，路径终点位于……之内 max(AcceptanceRadius * 2, 150 厘米) 的水平范围内时会被视为可达；在默认 接受半径 为 150.0情况下，该水平容差为 300 厘米。当 bStepOntoBounds 为 true，终点必须位于对象的占地范围内，并带有一个很小的 1.0 uu 误差。垂直容差使用 max(SourceHeight, 150 厘米).

注视注意力

控制该对象是否参与玩家的凝视管线，并为自定义凝视集成提供通知函数。有关覆盖玩家、对象、高亮和聊天机器人组件的完整凝视 API，请参见 凝视关注参考.

属性	类型	默认值	类别	说明
bGazeable	bool	true	Convai|Object|Gaze	当 false，玩家组件的凝视管线将完全跳过此对象——不会高亮，也不会有 OnGazedIn/OnGazedOut 事件，也不会提升关注。用于那些 AI 应该知道其存在（用于动作或状态跟踪），但不应能通过玩家凝视到达的对象。

凝视函数

这些函数会被 UConvaiPlayerComponent 自动调用，当其凝视管线检测到此对象的进入、离开以及关注阈值转换时。它们也 BlueprintCallable 因此非凝视流程——电影镜头、自定义聚焦系统、接近触发器——也可以驱动同一路径。

函数	输入	类别	说明
NotifyGazeBegin(Player)	Player (UConvaiPlayerComponent*)	Convai|Object|Gaze	当玩家的凝视进入此对象边界时调用。触发 OnGazedIn.
NotifyGazeEnd(Player)	Player (UConvaiPlayerComponent*)	Convai|Object|Gaze	当玩家的凝视离开此对象时调用。触发 OnGazedOut.
NotifyGazeAttentionBegin(Player, Text, ShouldRespond)	Player (UConvaiPlayerComponent*), Text (FString), ShouldRespond (EC_RunLLMOption)	Convai|Object|Gaze	当玩家凝视停留足够长时间，使此对象被提升为“被关注”时调用。会分发给子系统已知的每个聊天机器人，要求每个聊天机器人通过其凝视门控 setter 占用关注槽位。每个聊天机器人都会根据其当前 AttentionSource ——凝视无法覆盖一个 显式 已设置。触发 OnAttentionGained.
NotifyGazeAttentionEnd(Player)	Player (UConvaiPlayerComponent*) ——可能是 nullptr	Convai|Object|Gaze	当玩家停止注视此对象足够久，从而释放关注槽位时调用。会向每个聊天机器人分发一个凝视门控清除操作。当没有聊天机器人当前持有此对象的凝视关注时也可安全调用。触发 OnAttentionLost.

调试

属性	类型	默认值	类别	说明
bDebugDrawProximityPaths	bool	false	Convai|Object|Debug	当 true，会在视口中绘制从每个已订阅聊天机器人到此对象的导航路径——当聊天机器人已在目标处时为青色，可达时为绿色，不可达时为红色。路径会在每次重新评估接近度时重绘，并一直保留到下一次。每个对象组件都拥有自己的线段批处理，因此多个开启此开关的组件不会相互覆盖。 bAutoGenerateProximityState 为 false。在正式发布构建中禁用。

事件（可由 Blueprint 绑定的委托）

这四个事件都共享 FConvaiObjectGazeEvent 委托签名： (ObjectComponent: UConvaiObjectComponent, PlayerComponent: UConvaiPlayerComponent).

事件	显示名称	类别	当
OnGazedIn	被凝视进入	Convai|Object|Gaze	玩家的凝视进入此对象的边界（在任何关注停留阈值之前）。
OnGazedOut	被凝视离开	Convai|Object|Gaze	玩家的凝视离开此对象。
OnAttentionGained	获得关注	Convai|Object|Gaze	已达到凝视停留阈值，并已尝试跨聊天机器人提升关注。聊天机器人是否接受是单独的流程，若 启用操作 已关闭，或 AttentionSource 为 Explicit（Blueprint/C++）.
OnAttentionLost	失去关注	Convai|Object|Gaze	该对象已从聊天机器人的关注槽位中释放。 PlayerComponent 可能是 nullptr 因为 NotifyGazeAttentionEnd 接受可为空的玩家参数；使用前务必进行空值检查。

相关参考

Convai Chatbot 组件Convai Player 组件数据类型和枚举Convai 实用函数