注视注意力参考

注视注意力系统的完整属性、事件、方法和类参考，包括所有默认值和版本特定行为。

视线注意系统中每个属性、事件、方法和类的规范参考。 Convai Player 组件 和 Convai 对象组件 各页面仅总结其组件本地的视线表面；请使用此页面查看完整的跨组件 API、默认值和版本特定行为。

权威来源： Source/Convai/Public/ConvaiPlayerComponent.h, Source/Convai/Public/ConvaiObjectComponent.h, Source/Convai/Public/Gaze/ConvaiGazeHighlightActor.h, Source/Convai/Public/Gaze/ConvaiGazeCursorWidget.h，以及 Source/Convai/Public/ConvaiChatbotComponent.h.

UConvaiPlayerComponent — 视线注意属性

所有属性都位于 Convai | 凝视注意力 “细节”面板中的该类别中，除非另有说明。

核心开关

属性	类型	默认值	描述
bEnableGazeAttention	bool	false	总开关。其他所有视线属性在此项启用之前都会呈灰色禁用。 true.

注意行为

属性	类型	默认值	描述
GazeShouldRespond	EC_RunLLMOption	从不	当视线目标被提升为注意对象时会发生什么。 总是 — 聊天机器人会立即生成回复。 Auto — 由 Convai 决定。 从不 — 仅进行静默状态更新。
GazeAttentionText	FString	""	随注意提升一并发送的叙事事件文本（例如 "玩家正在看阀门。"）。仅在以下情况下生效： GazeShouldRespond 为 Auto 或 总是.
GazeAttentionDelay	float （秒）	1.0	高亮对象在被提升为“处于注意中”之前所需的持续注视时长。
GazeAttentionLossDelay	float （秒）	5.0	当前注意槽在失去注视后释放前的离开注视时长。

射线追踪设置

属性	类型	默认值	描述
GazeMaxDistance	float （厘米，AdvancedDisplay）	5000.0	从玩家摄像机或 VR HMD 发出的最大线性射线追踪距离。
GazeAngleTolerance	float （度）	5.0	点积回退锥体的半角。当严格射线追踪未命中有效视线目标且未被非 Convai 几何体阻挡时，系统会遍历所有 UConvaiObjectComponent 子系统池中的实例，并选取该锥体内与视线方向最对齐的那个。将其设为 0 可禁用该回退。
GazeTraceChannel	ECollisionChannel （AdvancedDisplay）	ECC_Visibility	视线线性射线追踪使用的碰撞通道。

高亮属性（类别：Convai | Gaze Attention | Highlight）

属性	类型	默认值	描述
GazeHighlightActorClass	TSubclassOf<AConvaiGazeHighlightActor>	插件默认值	在被注视对象上方生成的高亮 Actor 类。分配子类可自定义视觉效果。
GazeHighlightColor	FLinearColor	(1.0, 0.9, 0.2, 1.0) （淡黄色）	传递给高亮 Actor 的 HighlightColor 属性，然后 SetTarget 被调用。
GazeOverlayMaterial	TSoftObjectPtr<UMaterialInterface>	未设置	覆盖材质。未设置时，插件使用 /ConvAI/Highlights/M_ConvaiGazeOverlay （菲涅尔边缘轮廓）。可替换为任何公开 EmissiveColor 向量参数的材质。
GazeHighlightEmissiveIntensity	float （AdvancedDisplay）	2.5	传递给高亮 Actor 的 EmissiveIntensity 标量参数。插件的覆盖材质会将 EmissiveColor 在内部乘以此值。

光标属性（类别：Convai | Gaze Attention | Cursor）

属性	类型	默认值	描述
bShowGazeCursor	bool	true	在视线跟踪激活时显示屏幕中央准星。
bAlwaysShowGazeCursor	bool	false	即使视线未落在 Convai 对象上，也将光标保持在 Active 视觉状态。
GazeCursorWidgetClass	TSubclassOf<UConvaiGazeCursorWidget>	插件默认值	用于光标的 Widget 类。可通过 Blueprint 子类覆盖以自定义准星视觉效果。
GazeCursorActiveColor	FLinearColor	白色 (1,1,1,1)	视线落在 Convai 对象上时的光标颜色。
GazeCursorIdleColor	FLinearColor （AdvancedDisplay）	(1,1,1,0) （透明）	视线未落在任何对象上时的光标颜色。默认 alpha 为 0 时，光标在空闲时不可见。
GazeCursorDotSize	float （Slate 单位，AdvancedDisplay）	6.0	未缩放 Slate 单位下光标方形的边长。
GazeCursorFadeInTime	float （秒，AdvancedDisplay）	0.1	从 Idle 到 Active 状态的淡入时长。 0 会立即跳变。
GazeCursorFadeOutTime	float （秒，AdvancedDisplay）	0.25	从 Active 到 Idle 状态的淡出时长。 0 会立即跳变。

UConvaiPlayerComponent — 视线事件

所有事件都位于 Convai | Gaze Attention | 事件 类别，并使用委托类型 FConvaiPlayerGazeEvent.

委托签名： (UConvaiPlayerComponent* PlayerComponent, UConvaiObjectComponent* ObjectComponent)

事件	触发时机
OnGazeBegin	玩家视线进入 Convai 对象的瞬间触发。在达到任何注意阈值之前就会触发。
OnGazeEnd	玩家视线离开 Convai 对象的瞬间触发，不受注意状态影响。
OnAttentionGained	当被注视对象在以下时间后被提升为“处于注意中”时： GazeAttentionDelay 秒。即使所有聊天机器人都拒绝该更新，也会触发（例如当 启用动作 已关闭，或者 AttentionSource 为 显式（Blueprint/C++）).
OnAttentionLost	当注意中的槽位被释放时——例如因失去计时器到期、视线切换到另一个对象，或目标 Actor 被销毁。 ObjectComponent 可能是 nullptr 当注意目标被销毁时。

OnAttentionGained 在玩家组件上的事件表示停留阈值已达到，而不是聊天机器人已接受该更新。请检查 AttentionSource 聊天机器人上的 启用动作 是否已开启，以便角色应答。

AConvaiGazeHighlightActor

由以下对象生成的轻量级 Actor： UConvaiPlayerComponent 用于在当前视线目标上提供视觉反馈。

UE 版本行为：

• UE 5.3 及更高版本：会对每个 UMeshComponent 目标上的 SetOverlayMaterial.
• UE 5.0–5.2：回退为 DrawDebugBox 围绕目标边界的 FallbackBoxThickness 和 FallbackBoxPadding 仅在这些版本中控制线框外观。

Blueprint 方法：

方法	签名	描述
SetTarget	(AActor* InTarget, USceneComponent* InTargetComponent = nullptr)	应用或清除高亮。传入 nullptr 以清除。当 InTargetComponent 是一个 UMeshComponent时，覆盖层仅限于该组件。
GetTarget	() → AActor*	对当前目标的只读访问。
GetTargetComponent	() → USceneComponent*	可选的子组件范围。 nullptr 当高亮覆盖整个 Actor 时。

属性：

属性	类型	默认值	描述
HighlightColor	FLinearColor	(1.0, 0.9, 0.2, 1.0)	覆盖层的 EmissiveColor 参数的色调。来自 UConvaiPlayerComponent::GazeHighlightColor.
EmissiveIntensity	float	2.5	写入覆盖材质的标量 EmissiveIntensity 参数。插件材质会将 EmissiveColor 在内部乘以此值。
OverlayMaterial	TSoftObjectPtr<UMaterialInterface>	未设置	覆盖材质。默认值为 /ConvAI/Highlights/M_ConvaiGazeOverlay。回退为 /Engine/EngineMaterials/EmissiveMeshMaterial 仅当烹饪构建中缺少插件资源时（注意：该回退材质没有参数，因此 HighlightColor 将不会生效）。
FallbackBoxThickness	float （AdvancedDisplay）	2.0	UE 5.0–5.2 线框盒的线条粗细。
FallbackBoxPadding	float （AdvancedDisplay）	1.05	UE 5.0–5.2 线框盒的范围倍数。

要使用自定义高亮视觉效果，请在 Blueprint 中继承 AConvaiGazeHighlightActor 并将该子类分配给 UConvaiPlayerComponent::GazeHighlightActorClass.

UConvaiGazeCursorWidget

屏幕中央准星 Widget，由 UConvaiPlayerComponent 在视线跟踪激活时绘制。它是一个纯 C++ Widget，使用 Unreal 的 FCoreStyle::WhiteBrush — 插件不附带任何纹理资源。

Blueprint 方法：

方法	签名	描述
SetGazeActive	(bool bInGazeActive)	当视线进入或离开 Convai 对象时由玩家组件调用。
IsGazeActive	() → bool	返回当前视线状态。适用于 OnGazeStateChanged 实现。
OnGazeStateChanged	(bool bInGazeActive) (BlueprintImplementableEvent)	在 Blueprint 子类中重写，以在每次状态变化时运行自定义过渡——例如切换图像画刷或播放动画。

属性：

属性	类型	默认值	描述
ActiveColor	FLinearColor	白色 (1,1,1,1)	视线落在 Convai 对象上时的点颜色。
静止颜色	FLinearColor	(1,1,1,0) （透明）	视线未落在任何对象上时的点颜色。默认 alpha 为 0 时，光标在空闲时不可见。
DotSize	float （Slate 单位）	6.0	未缩放 Slate 单位下光标方形的边长。
FadeInTime	float （秒，AdvancedDisplay）	0.1	从 Idle 到 Active 的淡入时长。 0 会立即跳变。
FadeOutTime	float （秒，AdvancedDisplay）	0.25	从 Active 到 Idle 的淡出时长。 0 会立即跳变。

重写 GazeCursorWidgetClass on UConvaiPlayerComponent 以切换为 Blueprint 子类。 SetGazeActive 运行时仍会在重写项上调用。

UConvaiObjectComponent — 视线表面

带有以下标签的对象： UConvaiObjectComponent 会公开视线属性、方法和事件（“细节”面板类别 Convai | 对象 | 凝视).

属性

属性	类型	默认值	描述
bGazeable	bool	true	此对象是否参与视线检测。当 false时，该对象会同时从线性射线匹配和点积回退中排除。
ObjectEntry	FConvaiObjectEntry	—	该对象的标识和目标数据。按视线范围的子网格过滤使用 ObjectEntry.ComponentName 当 ObjectEntry.ObjectReference （详情面板标签 对象是）为 特定组件。请参见 组件作用域凝视 和 FConvaiObjectEntry.

Blueprint 方法

方法	签名	描述
GetResolvedComponent	() → USceneComponent*	返回从以下内容解析出的子组件： ObjectEntry.ComponentName。每次调用都会重新验证缓存匹配——如果缓存组件的所有者或名称不再符合过滤条件，它会自动重新扫描 Actor 的组件树，因此没有手动刷新调用。返回 nullptr 当 ObjectEntry.ObjectReference 不为 特定组件，当 ObjectEntry.ComponentName 为空，或者名称无法解析时。
NotifyGazeBegin	(UConvaiPlayerComponent* Player)	由 UConvaiPlayerComponent 调用，当玩家视线进入此对象时。也会触发 OnGazedIn。可从 Blueprint 调用，以在此组件上模拟视线进入事件。
NotifyGazeEnd	(UConvaiPlayerComponent* Player)	由 UConvaiPlayerComponent 当玩家视线离开此对象时调用。也会触发 OnGazedOut。可从 Blueprint 调用，以模拟视线离开事件。
NotifyGazeAttentionBegin	(UConvaiPlayerComponent* Player, const FString& Text, EC_RunLLMOption ShouldRespond)	由 UConvaiPlayerComponent 当此对象被提升为“处于注意中”时调用。也会触发 OnAttentionGained。可从 Blueprint 调用，以手动将此对象在任意聊天机器人上提升为注意。
NotifyGazeAttentionEnd	(UConvaiPlayerComponent* Player = nullptr)	由 UConvaiPlayerComponent 当此对象从注意中释放时调用。也会触发 OnAttentionLost。传入 nullptr 可在没有特定玩家上下文的情况下释放。

事件

委托签名： FConvaiObjectGazeEvent — (UConvaiObjectComponent* ObjectComponent, UConvaiPlayerComponent* PlayerComponent)

事件	触发时机
OnGazedIn	在玩家视线进入此对象的瞬间触发，早于任何注意阈值达到之前。
OnGazedOut	在玩家视线离开此对象的瞬间触发。
OnAttentionGained	当视线系统在持续注视阈值后将此对象提升时触发。聊天机器人的接受是独立的，并且可能失败，如果 启用动作 已关闭，或者 AttentionSource 为 显式（Blueprint/C++）.
OnAttentionLost	当此对象从注意中的槽位释放时触发。 PlayerComponent 可能是 nullptr 在目标已销毁的路径上——使用前请先做空值检查。

UConvaiChatbotComponent — 注意 API

成员	签名	描述
SetObjectInAttention	(FConvaiObjectEntry AttentionObject, FString Text = "", EC_RunLLMOption ShouldRespond = Auto, EConvaiContextDelivery Delivery = Send Normally, bool bAddAttentionEvent = true, bool bFlushImmediately = false) → void	设置聊天机器人当前处于注意中的对象，并可选提供叙事上下文文本和 LLM 回复选项。会写入 AttentionSource 为 显式 （或 无 当 AttentionObject.Name 为空时，释放该槽位）。当 ShouldRespond 为 Auto 或 总是 和 bAddAttentionEvent 为 true （默认）时，会暂存一个单次刷新的一次性事件，内容为 “<observer> 正在关注 <object name>” — 永不持久化，每次调用仅触发一次。当 EnvironmentData.bEnableActions 为 false (启用动作 位于“细节”面板中），或者当对象尚未出现在聊天机器人的环境列表中，或不在连接时发送的对象之列时；这些情况都会记录一条警告，指出对象和原因。 bFlushImmediately 会立即发送更新，而不是批量处理。
AttentionSource	EConvaiAttentionSource （BlueprintReadOnly, Transient）	最后设置该注意槽位的对象。 无, 目光，或 显式（Blueprint/C++）读取此属性可诊断注意锁定。

由视线门控的方法

以下方法由视线系统在内部调用，但也可从 Blueprint 调用，用于自定义视线集成。

方法	签名	返回值	描述
TrySetObjectInAttentionFromGaze	(FConvaiObjectEntry AttentionObject, FString Text = "", EC_RunLLMOption ShouldRespond = Auto, EConvaiContextDelivery Delivery = Send Normally, bool bAddAttentionEvent = true, bool bFlushImmediately = false) → bool	true 如果接受， false 如果拒绝	仅在以下情况下设置注意槽位： EnvironmentData.bEnableActions 为 true 和 AttentionSource 为 无 或 目光。成功时，会写入 AttentionSource = Gaze。返回 false ，并在操作被禁用或槽位被以下项锁定时记录一条警告，指出对象： 显式 调用者——该调用会被拒绝，而不是静默失败。内部由 UConvaiPlayerComponent使用；也暴露给 Blueprint，以用于必须遵守所有权协议的自定义视线集成。
TryClearObjectInAttentionFromGaze	(FConvaiObjectEntry ExpectedObject) → bool	true 如果清除， false 如果跳过	仅在以下情况下清除注意槽位： AttentionSource == Gaze 且当前注意中的对象匹配 ExpectedObject。可防止过时或延迟的视线丢失调用清除一个已被其他玩家或系统占用的注意槽位。

EConvaiAttentionSource

值	显示名称	含义
无	无	注意槽位为空。视线可将其占用。
目光	目光	槽位由视线系统拥有。视线可更新或释放它。
显式	显式（Blueprint/C++）	槽位被直接 SetObjectInAttention 调用锁定。直到调用者使用一个空的 SetObjectInAttention.

EC_RunLLMOption

值	显示名称	含义
Auto	Auto	由 Convai 决定是否生成口头回复。
总是	总是	聊天机器人始终生成口头回复。
从不	从不	注意更新静默进行；不会触发 LLM 调用。

FConvaiObjectEntry

附带在 UConvaiObjectComponent::ObjectEntry上。视线注意会读取标识字段，以及在按组件范围目标时读取下面的移动模式字段。

字段	类型	默认值	视线相关性
Ref	TWeakObjectPtr<AActor>	nullptr	此对象条目的 Actor 引用。
名称	FString	""	发送给 Convai 的对象名称，作为 current_attention_object。对象注册时不能为空。
描述	FString	""	Convai 用于理解该对象的自然语言描述。
ObjectReference	EConvaiObjectReference	整个 Actor	Details 面板标签 对象是。必须为 特定组件 用于 ComponentName 用于将视线范围限定到子网格。使用默认 整个 Actor时，视线会匹配该 Actor 的任意几何体，而不考虑 ComponentName.
ComponentName	FString	""	对子组件名称的大小写不敏感子串过滤。视线仅在以下情况下使用此字段： ObjectReference 为 特定组件 且名称可解析为以下对象上的组件： Ref.

仅用于移动的字段（AcceptanceRadius, SocketOrBoneName以及相关输出）记录在 角色动作参考.

下一步

注视注意力使用示例排查凝视注意力问题