凝视目标与提供器

将场景对象标记为凝视候选项，添加高级提供器组件，并从代码中注册自定义凝视目标提供器。

将 GameObject 标记为凝视候选项，添加这 8 个高级提供器组件以获得更丰富的目标选择行为，并从代码中注册自定义提供器。在添加后使用此页面 ConvaiGazeController 到角色上，当你希望它以非默认方式注意特定场景对象、其他角色或玩家时。

前提条件

• ConvaiGazeController 已添加到角色（Convai/具身/凝视).
• 要标记的场景对象，或提供其自身候选项的脚本。

将场景对象标记为凝视目标

添加 ConvaiGazeTarget (Convai/凝视/目标）到任何 GameObject，即可将其设为场景中每个 Convai 角色的凝视候选项。不需要场景元数据。

字段	默认	用途
优先级	5	优先级层级。玩家锚点发布时为 10，因此默认的 5 在对话中会让给玩家。将其提高到高于 10 以超过玩家的优先级。
基础相关度	0.75	在……内部时的相关度 完全相关距离.
最大距离	10 （米）	超过该距离后，目标不再作为候选项。
完全相关距离	3 （米）	低于该距离时，相关度达到最大值。
瞄准偏移	(0, 0, 0)	从该 Transform 到眼睛实际瞄准点的本地空间偏移，例如画作顶部。

ConvaiGazeTarget 是通用标记。仅在 WorldObjectGazeTargetProvider，如下所述，仅当对象已经带有 ConvaiObjectMetadata.

添加高级凝视提供器

高级提供器位于 Convai/凝视/高级/ ，可在 Add Component 菜单中找到。每个组件都是可选的——添加 ConvaiGazeController 会为角色赋予眼睛、头部、待机生命感、眨眼、身体转向和对话节奏，无需进一步设置；这些组件在此基础上添加更多能力。

角色目标——角色之间的相互凝视

CharacterGazeTargetProvider (Convai/凝视/高级/角色目标）使角色看向其他 Convai 角色，也能被其他 Convai 角色看向。每个参与角色添加一个组件；身份、对话状态以及视线点都来自该角色的具身上下文。

字段	默认	用途
发布自身	是	将此角色注册为其他角色可注视的目标。
看向他人	是	为其他已注册角色生成凝视候选项。
优先级	7	介于玩家锚点（10）和世界对象（5）之间，因此在对话中玩家优先，但角色会胜过背景道具。
说话优先级	9	当此角色正在说话时使用的优先级层级——高于空闲 优先级 层级，这样已经将注意力放在说话者上的听者不会被拉向旁观者，同时仍低于玩家锚点（10).
最大距离	12 （米）	超过该距离后，其他角色不再作为候选项（0 = 无限）。
完全相关距离	4 （米）	低于该距离后，其他角色处于完全相关状态。
空闲瞥视相关度	0.35	非说话角色的相关度。说话中的角色始终是完全相关的，因此听者会转向当前发言者。
视线高度偏移	1.6 （米）	其他角色瞄准的视线高度，直到该角色的头骨从绑定中解析出来。
启用空闲瞥视	是	空闲时，与附近角色偶尔交换短暂眼神。
空闲瞥视间隔最小值 / 最大值	5 / 12 （秒）	空闲角色间瞥视之间的间隔范围。
空闲瞥视持续时间	1.4 （秒）	一次空闲角色瞥视的持续时间。
空闲瞥视投入度	0.5	空闲瞥视的投入程度。

眼瞳驱动器——瞳孔扩张

ConvaiEyePupilDriver (Convai/凝视/高级/眼瞳驱动器）使用凝视模块平滑后的唤醒信号扩张角色的瞳孔。它通过复用的 MaterialPropertyBlock 按每个渲染器写入，因此共享材质资源永远不会被修改。

字段	默认	用途
渲染器	空	显式指定的渲染器目标。留空以自动发现所有 SkinnedMeshRenderer 该角色下其材质暴露了着色器属性的对象。
着色器属性名	_PupilScale	要驱动的着色器浮点属性。默认使用 Reallusion RL5 角膜着色器的瞳孔缩放属性。
最大扩张百分比	12 （范围 5–20)	在完全唤醒时的最大瞳孔扩张，表示为每个渲染器基础属性值的百分比。
反转符号	否	当某个绑定中属性值越大反而使瞳孔越小时，翻转扩张方向。

动态上下文桥接——注意力锚定

GazeDynamicContextBridge (Convai/凝视/高级/动态上下文桥接）将角色当前凝视对象镜像到 Convai 动态上下文键 current_attention_object，因此诸如“it”或“that”之类的代词引用会根据角色实际注视的对象来解析。

字段	默认	用途
参与阈值	0.5	对象被发布前所需的最低凝视投入度。

联合注意——注意玩家在看什么

GazeJointAttention (Convai/凝视/高级/联合注意）注意玩家正在看的东西并也看向那里，然后再返回到凝视策略所规定的对象——“我看到吸引你注意力的东西”这一反应节拍。它完全建立在公开的 GlanceAt API 之上，因此无需更改凝视核心。

字段	默认	用途
锥角度数	8	用于判断玩家视线射线是否指向候选对象的半锥角。
最大距离米数	12	候选对象可被注意到的最远玩家距离。
停留秒数	0.7	玩家必须持续注视某个对象多长时间后，角色才会注意到它。
瞥视持续秒数	1.4	看向被注意对象的瞥视持续时间。
反应延迟最小/最大秒数	0.2 / 0.5	从注意到到瞥视之间的延迟范围。
冷却秒数	10	同一对象再次被注意前的按对象冷却时间。
全局最小间隔秒数	4	任意两次联合注意瞥视之间的最小间隔。
评估间隔秒数	0.2	玩家视线评估之间的间隔（默认约 5 Hz）。
发布注意力上下文	否	将被注意对象的名称发布到 Convai 动态上下文。
空闲时激活 / 聆听时激活	是 / 是	联合注意处于激活状态的对话状态。

指代性瞥视——瞥一眼被提到的对象

GazeReferentialGlances (Convai/凝视/高级/指代性瞥视）当角色自己的语句提到某个已注册世界对象时，让角色瞥向它——“看看那幅画”。它基于角色的最终转写进行匹配，并完全建立在公开的 GlanceAt API。

字段	默认	用途
瞥视持续时间	1.6 （秒）	看向被提到对象的瞥视持续时间。
冷却秒数	10	同一对象再次被瞥视前的按对象冷却时间。
最大提及词数	4	可匹配的对象名称最长词数。
最小/最大延迟秒数	0.3 / 0.8	提及与瞥视之间的延迟范围。

玩家锚点——覆盖角色查找“玩家”的方式

PlayerAnchorTargetProvider (Convai/凝视/高级/玩家锚点）是开箱即用的“看向玩家”提供器。 ConvaiGazeController 当角色没有其他提供器时，会在运行时自动配置一个。可手动添加以按角色覆盖锚点——用于分屏、多人或过场动画绑定。

字段	默认	用途
优先级	10	在各提供器之间比较的静态优先级层级。
显式锚点	无	为空时，解析为 Camera.main，然后是第一个符合条件且启用的 Game 视图摄像机。
视线高度偏移	1.6 （米）	应用于显式非摄像机锚点的垂直抬升。
瞄准模式	自动	GazeAnchorAimMode ——凝视在锚点上的瞄准位置。
面部存在方式	自动	GazeAnchorFacePresence ——角色是否将锚点视为一张脸，并注视其周围（眼睛、嘴巴），而不是精确瞄准它。 自动 根据锚点决定：手动指定的会被视为脸，而 SDK 自行解析出的摄像机则被视为视点，并精确瞄准它。 脸 始终将锚点视为脸——在 VR 中是正确的，因为摄像机位于玩家双眼之间。 点 始终精确瞄准锚点。
本地瞄准偏移	(0, 0, 0)	由 本地偏移 模式。
最大距离	8 （米）	超过该距离后，玩家不再作为候选项。
完全相关距离	4 （米）	低于该距离时，相关度达到最大值。
检查视线	否	要求到玩家之间有无遮挡的直线。被遮挡时，相关度会衰减，重新出现时会播放正常的获取扫视。
遮挡层掩码	Physics.DefaultRaycastLayers	在视线测试中被视为视觉遮挡的层。
视线检查间隔	0.1 （秒）	视线射线检测之间的节流间隔。
视线起点高度	1.6 （米）	视觉射线从角色根节点之上的眼线高度开始。

玩家注意力传感器——知道玩家何时也在看回来

PlayerAttentionSensor (Convai/凝视/高级/玩家注意力传感器）告诉角色玩家是否正在看它。默认信号是主摄像机的前向射线；XR 眼动追踪通过 IPlayerGazeRaySource （见 为 XR 提供自定义玩家凝视射线）而无需任何 XR 包依赖。平滑后的信号会发布到 Convai 动态上下文键 player_attention (looking_at_me / 离开，边沿触发）。

字段	默认	用途
检测间隔	0.1 （秒）	检测采样之间的间隔。
基础半角	6 （度）	会话距离下的基础接受锥半角。
最大半角	28 （度）	近距离下的最大接受锥半角。
角色角半径	0.35 （米）	角色头部/上半身的大致角半径。
头部高度	1.6 （米）	未解析出 Head 骨骼时使用的视线高度。
上升秒数 / 下降秒数	0.5 / 1.5	注意力信号建立与衰减的时间常数。
进入阈值 / 退出阈值	0.6 / 0.35	发布用滞后阈值 looking_at_me / 离开.
发布到上下文	是	将看向/离开状态发布到 Convai 动态上下文。
凝视射线源组件	无	实现……的可选组件 IPlayerGazeRaySource。留空则从玩家摄像机进行瞄准。

世界对象目标——标记已制作的世界对象

WorldObjectGazeTargetProvider (Convai/凝视/高级/世界对象目标）将一个已制作的 Convai 世界对象——即已经带有 ConvaiObjectMetadata (RequireComponent）——标记为环境凝视候选项。附近角色在空闲时会瞥向它，而当它赢得注意力时，动态上下文桥接会将其报告给 Convai。

字段	默认	用途
优先级	5	优先级层级，保持低于玩家锚点（10）以便在对话中玩家获胜。
基础相关度	0.75	在……内部时的相关度 完全相关距离.
最大距离	10 （米）	超过该距离后，对象不再作为候选项。
完全相关距离	3 （米）	低于该距离时，相关度达到最大值。

从代码扩展目标选择

注册自定义目标提供器

实现 IGazeTargetProvider 并调用 ConvaiGazeController.RegisterTargetProvider 适用于不来自 MonoBehaviour 的角色层级中的候选项——例如系统级来源、通过网络代码同步的目标，或测试替身。

using Convai.Domain.Embodiment.Semantics;
using Convai.Modules.Gaze.Components;
using Convai.Modules.Gaze.Providers;
using UnityEngine;

public sealed class ScannerBeaconProvider : IGazeTargetProvider
{
    private readonly Transform _beacon;

    public ScannerBeaconProvider(Transform beacon) => _beacon = beacon;

    public bool TryGetCandidate(Transform characterRoot, out GazeTargetCandidate candidate)
    {
        candidate = default;
        if (_beacon == null) return false;

        candidate = new GazeTargetCandidate(
            GazeTargetKind.WorldObject,
            priority: 6,
            relevance: 0.8f,
            target: _beacon,
            worldPoint: _beacon.position,
            debugName: "Scanner Beacon");
        return true;
    }
}

// 附加到角色上（或持有一个序列化的 ConvaiGazeController 引用）：
public sealed class ScannerBeaconRegistrar : MonoBehaviour
{
    [SerializeField] private Transform beaconTransform;

    private void Start()
    {
        ConvaiGazeController gaze = GetComponent<ConvaiGazeController>();
        gaze.RegisterTargetProvider(new ScannerBeaconProvider(beaconTransform));
    }
}

TryGetCandidate 每个认知 tick 都会运行，因此请保持实现开销低。返回 否 （或相关度为 0）会移除该帧的候选项；仲裁器会处理获取和释放的平滑。调用 UnregisterTargetProvider 当该提供器不再有效时。

为 XR 提供自定义玩家凝视射线

IPlayerGazeRaySource 提供玩家当前注视方向的世界空间射线，因此 PlayerAttentionSensor 和 GazeJointAttention 可以在没有 SDK 对 XR 包有硬依赖的情况下判断玩家是否在看某个东西。请基于 OpenXR 或厂商眼动追踪适配器实现，并按组件注册：

using Convai.Domain.Embodiment.Interfaces;
using Convai.Modules.Gaze.Providers;
using UnityEngine;

public sealed class OpenXrEyeTrackingSource : IPlayerGazeRaySource
{
    public bool TryGetPlayerGazeRay(out Ray ray)
    {
        // 从 XR 眼动追踪 API 填充 `ray`。当追踪丢失时返回 false。
        ray = default;
        return false;
    }
}

// 附加到角色上：
public sealed class XrGazeRaySetup : MonoBehaviour
{
    private void Start()
    {
        PlayerAttentionSensor sensor = GetComponentInChildren<PlayerAttentionSensor>();
        sensor.SetGazeRaySource(new OpenXrEyeTrackingSource());
    }
}

返回 否 当这一帧没有可用射线时——例如追踪丢失、头显关闭——这样消费者会回退到摄像机射线。该来源按组件实例注册，而不是进程级注册，因此一个场景的适配器不会悄悄驱动另一个场景中的角色。

目标运动如何被过滤

每个凝视目标的瞄准点都会先经过平滑处理，然后才会被头部运动检测器看到，因此一两厘米的普通移动——比如说话角色的头部轻微晃动、手持设备上的摄像机晃动——不会被识别为移动目标，也不会触发头部重新规划。真正的不连续变化，例如镜头切换或传送，会在原始跳变而不是平滑后的跳变上被检测到，因此眼睛仍会立即跳到新位置，而不是向其滑动。

验证目标已被找到

进入 Play 模式并打开 Convai > 凝视编辑器 在选中角色时。窗口的实时视图会列出当前激活的目标及其类型（玩家, 世界对象, 角色, 脚本, 环境，或 移动路径）。一个从未出现的目标通常意味着其提供器组件已禁用、超出 最大距离，或者低于另一个提供器的优先级层级。

故障排查

一个 ConvaiGazeTarget 从未被选中

症状： 该对象从未在凝视编辑器的实时视图中作为激活目标出现。

原因： 目标的 优先级 处于或低于另一候选项的层级，或者该角色位于 最大距离.

解决方法： 提高 优先级 到高于竞争层级，或增大 最大距离 / 完全相关距离.

验证： 重新打开凝视编辑器实时视图，并确认目标名称作为激活目标出现。

高级提供者什么也不做

症状： 没有控制台警告，但该行为始终不会触发。

原因： 大多数高级提供者需要 EmbodimentContext 和 ConvaiGazeController 在父级层级中；缺少它会记录警告并禁用该组件。

解决方法： 在控制台中检查是否有一个 组件处于不活动状态 指明缺失依赖项的警告，并确认该组件位于与……相同的角色层级下 ConvaiGazeController.

验证： 组件成功重新启用后，警告就不再出现。

下一步

脚本化凝视配置眼神接触凝视脚本参考