注视注意力参考

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

凝视注意系统中每个属性、事件、方法和类的权威参考。本 Convai 玩家组件 和 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 | Gaze Attention Details 面板中的类别，除非另有说明。

核心开关

属性	类型	默认值	描述
bEnableGazeAttention	bool	false	主开关。其他所有凝视属性都会置灰，直到此项 true.

注意行为

属性	类型	默认值	描述
GazeShouldRespond	EC_RunLLMOption	从不	当凝视目标被提升为注意对象时会发生什么。 Always — 聊天机器人会立即生成回复。 自动 — 由 Convai 决定。 从不 — 仅进行静默状态更新。
GazeAttentionText	FString	""	随注意提升一并发送的叙事事件文本（例如 “玩家正在看着阀门。”）。仅在以下情况下生效： GazeShouldRespond 为 自动 或 Always.
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>	插件默认值	在被注视对象上生成的高亮演员类。分配子类以自定义视觉效果。
GazeHighlightColor	FLinearColor	(1.0, 0.9, 0.2, 1.0) （浅黄色）	传递给高亮演员的 HighlightColor 属性后 SetTarget 被调用时。
GazeOverlayMaterial	TSoftObjectPtr<UMaterialInterface>	未设置	覆盖材质。未设置时，插件使用 /ConvAI/Highlights/M_ConvaiGazeOverlay （菲涅耳边缘轮廓）。可替换为任何暴露 EmissiveColor 向量参数的材质。
GazeHighlightEmissiveIntensity	float （AdvancedDisplay）	2.5	传递给高亮演员的 EmissiveIntensity 标量参数。插件的覆盖材质会将 EmissiveColor 在内部乘以该值。

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

属性	类型	默认值	描述
bShowGazeCursor	bool	true	在凝视跟踪处于激活状态时显示屏幕中心准星。
bAlwaysShowGazeCursor	bool	false	即使凝视不在 Convai 对象上，也让光标保持 Active 视觉状态。
GazeCursorWidgetClass	TSubclassOf<UConvaiGazeCursorWidget>	插件默认值	用于光标的小部件类。可用 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 | 凝视注意 | 事件 类别，并使用委托类型 FConvaiPlayerGazeEvent.

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

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

OnAttentionGained 在玩家组件上的 AttentionSource 在聊天机器人上的 启用动作 处于开启状态，以便角色应答。

AConvaiGazeHighlightActor

由……生成的轻量级演员 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 当高亮覆盖整个演员时。

属性：

属性	类型	默认值	描述
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

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

Blueprint 方法：

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

属性：

属性	类型	默认值	描述
ActiveColor	FLinearColor	白色 (1,1,1,1)	当凝视位于 Convai 对象上时的点颜色。
IdleColor	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 会立即切换。

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

UConvaiObjectComponent — 凝视表面

标记为 UConvaiObjectComponent 的对象会暴露凝视属性、方法和事件（Details 面板类别 Convai | Object | Gaze).

属性

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

Blueprint 方法

方法	签名	描述
GetResolvedComponent	(bool bForceRefresh = false) → USceneComponent*	返回从缓存中解析的子组件 ObjectEntry.ComponentName后，在聊天机器人组件上执行。 true 以强制重新查找，例如在运行时演员的组件树发生变化后。返回 nullptr 当 ObjectEntry.MoveTargetMode 不是 以组件为目标，当 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, bool bFlushImmediately = false) → void	设置聊天机器人当前的注意对象，可选附带叙事上下文文本和 LLM 响应选项。当 EnvironmentData.bEnableActions 为 false (启用动作 （在 Details 面板中）。会标记 AttentionSource 到 显式. bFlushImmediately ，并立即发送更新，而不是批处理。
AttentionSource	EConvaiAttentionSource (BlueprintReadOnly, Transient)	最后设置注意槽位的是谁。 无, 视线，或 显式（Blueprint/C++）。读取此属性可诊断注意锁定。

凝视门控方法

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

方法	签名	返回	描述
TrySetObjectInAttentionFromGaze	(FConvaiObjectEntry AttentionObject, FString Text = "", EC_RunLLMOption ShouldRespond = Auto, 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

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

FConvaiObjectEntry

承载于以下结构体： UConvaiObjectComponent::ObjectEntry。凝视注意会读取身份字段，并在组件作用域目标情况下读取下面的移动模式字段。

字段	类型	默认值	凝视相关性
引用	TWeakObjectPtr<AActor>	nullptr	此对象条目的演员引用。
名称	FString	""	发送给 Convai 的对象名称为 current_attention_object。对象注册时必须非空。
描述	FString	""	Convai 用于理解该对象的自然语言描述。
MoveTargetMode	EConvaiMoveTarget	以 Actor 为目标	必须为 以组件为目标 (Vector）用于 ComponentName 以将凝视限定到子网格。使用默认 以 Actor 为目标时，凝视会将该条目视为整个演员范围，而不管 ComponentName.
ComponentName	FString	""	对子组件名称的不区分大小写的子串过滤。凝视仅在以下情况下使用此字段： MoveTargetMode 为 以组件为目标 并且名称解析为某个组件位于 引用.

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

下一步

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