凝视脚本参考

Convai Gaze 系统公共 API 参考，包括控制器、凝视读数、句柄以及目标提供器接口。

Convai Gaze 系统公开类型的完整参考。类型位于 Convai.Modules.Gaze.Components, Convai.Modules.Gaze.Core, Convai.Modules.Gaze.Providers, Convai.Domain.Embodiment.Readings以及 Convai.Domain.Embodiment.Semantics 命名空间中，如各类型所注。

ConvaiGazeController

ConvaiCharacterModule<ConvaiGazeProfile>, MonoBehaviour — Convai.Modules.Gaze.Components

菜单路径： Convai/具身/凝视. DisallowMultipleComponent, RequireComponent(GazeAttentionRequests).

Convai Gaze 系统的组合根：它决定角色看向什么（目标锁定）、每个对话状态对其投入多大力度（策略），并将视线分配到躯干、颈部/头部、眼睛和眼睑（求解器）。

属性

属性	类型	说明
Current	GazeReading	角色最新的凝视读数，每个认知 tick 都会发布。
PlayerAnchorOverride	Transform	该角色将其视为“玩家”的 Transform。 null (默认) 解析为 Camera.main，然后是任何已启用的摄像机。用于分屏、多玩家或过场动画骨架；运行时会立即生效。
EyeContactMode	GazeEyeContactMode	眼神接触如何受控。可在运行时设置；会平滑渐入。
AttendToSpeaker	GazeSpeakerAttention	当角色不在自己轮次时，是否会转向当前正在说话的其他人。取值： 关闭, 玩家, 角色, 任何人 (默认)。可在运行时设置。
FocusFidelity	GazeFocusFidelity	在……期间使用的精度 EyeContactMode 处于活动状态时保持的分类法规范标签。
PlayerAnchorAimMode	GazeAnchorAimMode	玩家锚点的对话瞄准点如何推导。
PlayerAnchorAimOffset	Vector3	由 GazeAnchorAimMode.LocalOffset.
AllowScriptedOverridesDuringExactFocus	布尔值	显式 GazeAt 请求是否可抢占一个正在进行的 精确 焦点。默认禁用。
LockBlocksGlances	布尔值	在眼神接触锁定生效期间，会吸收“瞥视”级脚本请求，因此不会有任何东西短暂把视线从玩家锚点上拉开。默认开启。

方法

方法	签名	说明
GazeAt	GazeHandle GazeAt(Transform target, GazeOptions options = default)	将视线指向一个（可移动的）Transform。一个 null 目标会返回 null.
GazeAt	GazeHandle GazeAt(Vector3 worldPoint, GazeOptions options = default)	将视线指向一个世界空间点。
GlanceAt	GazeHandle GlanceAt(Transform target, float durationSeconds = 1.2f)	短暂瞥向一个（可移动的）Transform，然后返回策略目标。一个 null 目标会返回 null.
GlanceAt	GazeHandle GlanceAt(Vector3 worldPoint, float durationSeconds = 1.2f)	短暂瞥向一个世界空间点。
ReleaseAllScriptedGaze	void ReleaseAllScriptedGaze()	释放所有脚本化凝视请求。
RegisterTargetProvider	void RegisterTargetProvider(IGazeTargetProvider provider)	注册一个非组件提供者（系统、网络代码、测试）。
UnregisterTargetProvider	void UnregisterTargetProvider(IGazeTargetProvider provider)	取消注册一个通过 RegisterTargetProvider.
RefreshProviders	void RefreshProviders()	重新扫描角色层级中的目标提供者。
RefreshEyeBackend	void RefreshEyeBackend()	重新解析眼部输出后端（骨骼 vs. EyeLook* BlendShape）来自配置文件。更改后调用 眼部驱动模式 在运行时。
CaptureCapabilities	void CaptureCapabilities(List<GazeCapabilityInfo> results)	填充 结果 包含所有可选凝视能力，以及该角色当前是否具备。
CaptureSnapshot	void CaptureSnapshot(GazeSnapshot snapshot)	填充 快照 与实时凝视状态。
CaptureSnapshot	GazeSnapshot CaptureSnapshot()	会分配一个便捷重载，创建并填充一个新的 GazeSnapshot.
TryGetPlayerAnchor	bool TryGetPlayerAnchor(out Transform anchor)	解析该角色当前视为玩家的 Transform。返回 否 当没有锚点、没有提供者、也没有可回退的摄像机时返回。

事件

事件	签名	在……时触发
TargetChanged	event Action<GazeTargetChange>	每次凝视目标切换时都会触发，与跟踪日志一致。

GazeReading

只读结构体 — Convai.Domain.Embodiment.Readings

角色当前凝视决策的不可变快照，通过 ConvaiGazeController.Current.

属性	类型	说明
TargetKind	GazeTargetKind	当前目标的来源分类。
目标	Transform	正在凝视的可选 Transform。可能为 null 即使已锁定目标（没有对应 Transform 的世界空间点）；优先使用 WorldPoint 用于计算。
WorldPoint	Vector3	凝视所指向的平滑世界空间点。
参与度	float	在 [0, 1]：本帧中眼睛/头部/身体对目标投入的强度。
IsAverting	布尔值	是 当回避节拍故意打破眼神接触时为真。目标仍然被占用；之后会恢复接触。
GenerationId	整数	每当视线移动到不同目标时递增的稳定 ID，用于在不比较 Transform 引用的情况下检测重新定向。

GazeReading.None 是未接合读数（GazeTargetKind.None，无目标、零投入）。

GazeTargetChange

只读结构体 — Convai.Modules.Gaze.Core.Diagnostics

事件载荷，用于 ConvaiGazeController.TargetChanged，描述一次凝视目标切换。

属性	类型	说明
FromKind	GazeTargetKind	前一个目标的类型。
ToKind	GazeTargetKind	新目标的类型。
FromName	字符串	前一个目标的显示名称（"-" 若无则为）。
ToName	字符串	新目标的显示名称（"-" 若无则为）。
原因	字符串	该变化的人类可读原因。
Time	float	……的值 Time.time 当变化发生时。

GazeHandle

密封类 — Convai.Modules.Gaze.Components

用于一个脚本化凝视请求的实时句柄，由 GazeAt 和 GlanceAt返回。所有操作都具有幂等性，并且对取消安全。

属性

属性	类型	说明
TargetName	字符串	请求目标的显示名称，用于诊断。
IsActive	布尔值	请求是否仍然有效（未释放、未过期，也未被销毁所取代）。
Settled	Task<bool>	完成 是 注视对齐到目标后完成，或者 否 当请求在对齐前结束时完成。
Completion	Task	当请求结束时完成——持续时间结束、已释放或目标丢失。
结果	GazeOutcome	该请求最终的结果。 Taken 直到有其他内容说明为止。

方法

方法	签名	说明
释放	void Release()	结束该请求。可安全多次调用，也可在取消回调中调用。

GazeOptions

结构体 — Convai.Modules.Gaze.Components

脚本化 GazeAt 请求的选项。参见 脚本化注视 了解字段默认值和用法。

字段	类型	说明
优先级	整数	脚本化请求之间的优先级（数值越高越优先；若相同则更近的请求获胜）。脚本化请求始终高于自动目标。
HoldSeconds	float	来自请求的保持时长（秒）。数值 <= 0 保持直到 GazeHandle.Release() 被调用。
参与度	float	Engagement 覆盖值，位于 (0, 1]。数值 <= 0 使用当前对话状态的投入度。
允许身体转向	布尔值	此请求是否可以触发朝目标的全身转身。

GazeOutcome

枚举 — Convai.Modules.Gaze.Components

凝视请求为何未能到达目标，或其已到达的确认。

值	整数	说明
Taken	0	凝视请求处于有效状态，或已抵达其目标。
被打断	1	请求在视线到达之前就结束了——已释放、已过期、被取代，或其目标已被销毁。
HeldEyeContactInstead	2	角色有意保持眼神接触，因此这次瞥视被并入其中而未单独执行，因为 LockBlocksGlances 开启时显示。

GazeEyeContactMode

枚举 — Convai.Modules.Gaze.Components

如何 ConvaiGazeController 管理其与玩家锚点的眼神接触。

值	整数	说明
自然	0	配置文件中按DialogueState 的策略表驱动投入、回避和头部参与。默认。
ConversationLock	1	在每个对话（非空闲）状态下完全投入玩家锚点； 空闲 保留作者设定的表格行。
AlwaysLock	2	在每种状态下都完全投入玩家锚点， 空闲 包括在内。
SpeakingFocus	3	仅在角色正在说话时才投入玩家锚点。

GazeFocusFidelity

枚举 — Convai.Modules.Gaze.Components

激活的眼神接触模式对其玩家锚点的保持精度。

值	整数	说明
社交	0	在保持玩家作为对话目标的同时，保留轻微的注视运动和有社交意义的头部手势。推荐用于对话角色。
精确	1	在焦点活动期间抑制有意的移开视线和注视偏移。眨眼、眼睑、瞳孔、辐辏和身体转动仍可用。

GazeAnchorAimMode

枚举 — Convai.Modules.Gaze.Components

对话焦点点如何从其锚点 Transform 推导。

值	整数	说明
自动	0	使用摄像机的精确位置，并对其他锚点应用常规的视线抬升。
ExactTransform	1	使用锚点的精确世界位置。
LocalOffset	2	转换 PlayerAnchorAimOffset 从锚点本地空间到世界空间。

GazeBodyTurnStyle

枚举 — Convai.Modules.Gaze.Components

当角色注视仅靠头和眼无法够到的目标时，身体如何转向。

值	整数	说明
分步转身	0	播放角色自身的转身动画，因此脚步会跟着转动。需要 Animation Set 中的转身片段以及 Body Animation 模块；两者缺一则回退为平滑旋转。
平滑旋转	1	直接旋转角色，速度由凝视配置文件设置。无需片段，也无需动画模块。

GazeSpeakerAttention

枚举 — Convai.Modules.Gaze.Components

角色是否会转向房间里当前正在说话的人，以及转向谁。仅在角色不在自己轮次时适用，因此不会与角色自身的对话凝视竞争。通过 ConvaiGazeController.AttendToSpeaker；该注视的方式和范围在配置文件的 对话注意力 组中。

值	整数	说明
关闭	0	绝不跟随其他参与者的轮次。
玩家	1	当玩家发言时转向玩家；忽略其他角色的轮次。
角色	2	当其他角色发言时转向该角色；绝不转向玩家。
任何人	3	转向当前持话者，无论是玩家还是角色（默认）。玩家在某个正在说话的角色上插话时，会立即接管话轮。

GazeTargetKind

枚举 — Convai.Domain.Embodiment.Semantics

分类角色当前凝视目标的来源。

值	整数	说明
无	0	无目标——凝视系统完全脱离。
环境	1	环境闲置探索——一个没有场景含义的合成注视点。
玩家	2	玩家锚点（摄像机或显式玩家 Transform）。
世界对象	3	由世界对象凝视目标提供者呈现的场景对象。
脚本	4	一个脚本化的 GazeAt 请求（API 调用或动作执行器）。
角色	5	另一位 Convai 角色，由角色对角色凝视提供者呈现。
移动路径	6	角色移动时前方的路径——沿其行进方向的一个点，而不是场景对象。

IGazeTargetProvider

接口 — Convai.Modules.Gaze.Providers

向 ConvaiGazeController提供凝视目标候选项。角色层级中的提供者会自动发现；其他提供者可在运行时通过 RegisterTargetProvider注册。实现必须轻量—— TryGetCandidate 每个认知 tick 都会运行。

public interface IGazeTargetProvider
{
    bool TryGetCandidate(Transform characterRoot, out GazeTargetCandidate candidate);
}

GazeTargetCandidate 是一个只读结构体，包含 类型 (GazeTargetKind), 优先级 (整数更高层级总是胜出）， 相关性 (float, 0–1, 0 移除候选项）， 目标 (Transform，可选）， WorldPoint (Vector3), 调试名称 (字符串），以及 HasFace (布尔值，默认 否）——是否在 WorldPoint 值得环视而不是精确瞄准。未设置该项的提供者会获得精确瞄准；将其设置为 是 仅当该点确实是某人的脸时。

GazeCapabilityInfo

只读结构体 — Convai.Modules.Gaze.Core

一项可选凝视能力：用浅显英文说明它做什么，以及由哪个组件提供。由 ConvaiGazeController.CaptureCapabilities.

属性	类型	说明
ID	GazeCapabilityId	稳定标识符。
DisplayName	字符串	用户应看到的内容——绝不是组件的类名。
说明	字符串	一句话说明启用后会改变什么。
ProviderType	类型	“ MonoBehaviour 提供此能力的类型。
IsPresent	布尔值	此角色当前是否存在已启用的提供者。

GazeCapabilityId 值： 玩家注意力 (0), 注意力锚定 (1), 指代性瞥视 (2), 共同注意 (3), 角色凝视 (4), 瞳孔反应 (5）——对应 Gaze 目标与提供者.

GazeSnapshot

密封类 — Convai.Modules.Gaze.Core.Diagnostics

用于 HUD 和测试的完整凝视运行时状态的可变、可复用捕获。只需分配一次，并通过 ConvaiGazeController.CaptureSnapshot(GazeSnapshot).

字段	类型	说明
读数	GazeReading	捕获时发布的凝视读数。
TargetKind	GazeTargetKind	当前接合目标的类型，或 无 在脱离时为
TargetName	字符串	当前接合目标的诊断名称，或 "-" 在脱离时为
DialogueState	DialogueState	本帧策略引擎所作用的对话状态。
PolicyEngagement	float	在应用目标投入之前平滑后的策略投入度。
TorsoAngles	Vector2	求解出的躯干偏航/俯仰贡献，单位为度。
HeadAngles	Vector2	求解出的头部（颈部+头部）偏航/俯仰贡献，单位为度。
HeadRollDegrees	float	本帧写入头骨的滚转。仅当头部手势请求倾斜时才非零。
TargetErrorAngles	Vector2	本帧仍需完成的完整视线偏移，在任何执行器分担之前。脱离时为零。
LeftEyeAngles / RightEyeAngles	Vector2	求解出的眼睛偏航/俯仰，单位为度，轨道空间。
EyePhase	字符串	当前注视/扫视阶段标签（“注视中”, “扫视”, “跟随”以及类似项）。
ContactErrorDegrees	float	眼睛瞄准方向与凝视目标实际位置之间的实时角度误差。 float.NaN 在脱离时。
AimErrorDegrees	float	眼睛实际指向与目标之间的合成角度误差，包括求解器自身目标之后应用的所有偏移。 float.NaN 在脱离时。
TargetHasFace	布尔值	当前目标是否是某人的脸，因此适用面部扫描。
LookNature	字符串	角色当前这次注视所表达的含义—— “瞥视”, “注意”, “反射”.
FocusActive	布尔值	产品级对话焦点范围是否处于活动状态。
FocusFidelity	GazeFocusFidelity	在……期间应用的精度约束 FocusActive 为 true 时。
FocusDegraded	布尔值	当锚点不可用时，焦点是否保留最后已知点。
ContactUsesBoneBackend	布尔值	是 当当前激活的眼部后端驱动骨骼时； 否 标识 BlendShape 后端。
BlinkWeight	float	归一化眨眼权重（0 睁开， 1 闭合）。
IsReorienting	布尔值	身体重新定向是否正在进行中。
IsNodding	布尔值	监听回路点头是否正在播放。
玩家注意力	float	来自……的平滑 0–1“玩家是否在看我”估计 PlayerAttentionSensor，或 -1 当没有传感器时。
PlayerLooking	布尔值	传感器的滞后处理后分类。仅在 玩家注意力 不为负时。
AttendingSpeaker	布尔值	角色当前是否正在跟随他人的轮次——“大家看正在说话的人”这种行为。 否 在其自身轮次中时，在 AttendToSpeaker 是 关闭期间，以及在没有可关注对象发言时。
SpeakerAttention	字符串	一行描述对话注意力实际在做什么——正在看谁，或将说话者挡开的门槛（“太远”, “在他们后面”, “它自己的轮次”).
LodEnabled	布尔值	该角色是否启用了人群 LOD。
LodFar	布尔值	角色是否处于降低频率的远距 LOD 区间。
LodExpressionSkipped	布尔值	本帧是否跳过求解阶段（屏幕外 LOD）。
RecentTrace	List<GazeTraceEntry>	从跟踪环形缓冲区复制的最近切换日志，最旧在前。

头部姿态贡献者跟踪

这些字段分解了本帧是什么让头部移动以及原因。 HeadAngles 和 TorsoAngles 通常是读者想要的内容；这组字段用于诊断一个特定的头部姿态缺陷—— TargetErrorAngles 与下方执行器之和之间的残余差距，其中一个贡献者已退让，而另一个已悄悄限幅。应将它们一起阅读，而不是单独看。

字段	类型	说明
HeadGoal	Vector2	执行器阶梯的头部偏航/俯仰目标，单位为度，用于本帧的偏移。
HeadShiftActive	布尔值	头部是否正在执行朝新目标的成形移动（弹道通道正在进行中）。
StabilizationOffset	Vector2	稳定反射所应用的偏移，单位为度，用于抵消动画自身的头部偏差。
AnimatedDeviation	Vector2	动画自身测得的头部偏差，单位为度，由稳定反射抵消。
GestureOffset	Vector2	合成的头部手势偏移，单位为度——回路点头、外部程序以及让话轮的下压。
AversionHeadOffset	Vector2	回避节拍的头部份额偏移，单位为度，经过输入头部求解的眼神接触锁定和轮次切换缩放后。
AversionEyeOffset	Vector2	回避节拍的眼部份额偏移，单位为度，作为输入传给眼部求解。
微偏移	Vector2	组合后的眼部微动偏移，单位为度——微扫视停留、面部扫描和到达稳定俯仰角。
链滞后偏移量	Vector2	本帧颈部/头部链式滞后重分配转移到头骨上的角度——重叠动作的跟随余势与稳定。
已应用的头部增量角度	float	在本帧与上一帧之间，头骨的世界旋转变化了多少度，测量于求解将骨骼写入之后。
目标点增量米数	float	自上次表达式 tick 以来，已启用指令的世界点移动了多少米。
GenerationId	整数	捕获时该指令的生成 ID；每次重新锁定目标都会递增，因此探针可以区分贡献者步骤和一次新的注视。

方法

方法	签名	说明
清除	void Clear()	将所有字段重置为其未启用默认值。

相关参考

凝视配置文件参考脚本化凝视凝视目标与提供器