凝视与注意力使用示例

四个循序渐进的凝视与注意力配置示例——从基础 Inspector 设置到自定义 IFocusTargetProvider 实现以及注意力配置文件调优。

这些示例从仅在 Inspector 中调整配置开始，逐步过渡到用于自定义关注提供器和多角色设置的 C# 脚本。先从示例 1 开始了解基线配置，然后继续查看更高级的模式。

---

示例 1 — 以权威眼神交流的安全培训讲师

场景： 一个工厂安全培训模拟包含一位会进行流程讲解的 NPC 讲师。这个角色需要自信、持续的眼神交流来展现权威——但也必须自然地移开视线，以避免显得像机器人一样盯视。

设置（仅 Inspector）：

创建一个 ConvaiAttentionProfile 并配置：

字段	值	原因
MaxContinuousHoldSeconds	8.0	为体现权威感而延长注视保持时间
InterestDecayPerSecond	0.08	缓慢衰减——讲师保持目光的时间远长于默认的 5 秒
CommitmentAcquireSeconds	0.2	玩家进入画面时快速锁定

创建一个 ConvaiGazeCoordinationProfile。覆盖 发言 状态：

字段	值
OverallWeight	1.0
EyeShare	0.30

将这两个配置文件都分配给角色的组件。

预期结果： 讲师在简报期间保持较长时间的眼神交流，大约 8 秒后会打破注视，并迅速重新锁定。说话时，头部会有力地朝向玩家旋转，而眼睛则提供精细的跟踪细节。

---

示例 2 — 医疗设备关注优先级

场景： 一个临床培训场景中的护士角色必须在与患者（玩家）进行眼神交流和查看场景中的医疗设备之间切换。设备的关注优先级高于默认相机提供器。

设置：

实现一个自定义的 IFocusTargetProvider 用于设备：

using Convai.Domain.Embodiment.Interfaces;
using Convai.Domain.Embodiment.Readings;
using UnityEngine;

public class EquipmentFocusProvider : MonoBehaviour, IFocusTargetProvider
{
    [SerializeField] private Transform _equipmentTransform;
    [SerializeField] private float _relevanceWhenActive = 0.9f;

    private bool _isActive;

    public int Priority => 20; // 高于默认相机提供器（0）

    public bool TryGetCandidate(Transform characterRoot, out AttentionCandidate candidate)
    {
        if (!_isActive || _equipmentTransform == null)
        {
            candidate = default;
            return false;
        }

        candidate = new AttentionCandidate(
            priority: Priority,
            relevance: _relevanceWhenActive,
            target: _equipmentTransform,
            worldPoint: _equipmentTransform.position,
            debugName: "医疗设备"
        );
        return true;
    }

    public void SetActive(bool active) => _isActive = active;
}

将此组件添加到角色的根 GameObject 上。 ConvaiAttentionController 会在 在层级中发现提供器 被启用时自动发现它。

从你的模拟逻辑中激活设备提供器：

public class NurseSimulationController : MonoBehaviour
{
    [SerializeField] private EquipmentFocusProvider _equipmentProvider;

    public void OnEquipmentCheckRequired()
    {
        _equipmentProvider.SetActive(true);
    }

    public void OnEquipmentCheckComplete()
    {
        _equipmentProvider.SetActive(false);
    }
}

预期结果： 当 OnEquipmentCheckRequired() 触发时，护士的目光会转向设备变换。当检查完成后，关注会释放，默认相机提供器会按照正常的承诺时机重新获取焦点。

---

示例 3 — 角色间对视的多角色对话

场景： 一个谈判训练模拟包含两个 NPC 角色，他们在玩家面前彼此对话。当某个角色发言时，每个角色都应跟踪对方；在停顿期间则应看向玩家。

设置：

在每个角色上，将默认相机焦点提供器替换为自定义的 IFocusTargetProvider 用于指向另一角色头部的：

using Convai.Domain.Embodiment.Interfaces;
using Convai.Domain.Embodiment.Readings;
using UnityEngine;

public class CharacterFocusProvider : MonoBehaviour, IFocusTargetProvider
{
    [SerializeField] private Transform _targetHeadBone;
    [SerializeField] private float _relevance = 0.85f;

    public int Priority => 10;

    public bool TryGetCandidate(Transform characterRoot, out AttentionCandidate candidate)
    {
        if (_targetHeadBone == null)
        {
            candidate = default;
            return false;
        }

        candidate = new AttentionCandidate(
            priority: Priority,
            relevance: _relevance,
            target: _targetHeadBone,
            worldPoint: _targetHeadBone.position,
            debugName: "其他角色"
        );
        return true;
    }
}

禁用 自动创建默认焦点提供器 on ConvaiAttentionController 针对每个角色。添加 CharacterFocusProvider 到每个角色，并交叉分配它们的头骨。

调整注意力配置文件，以便更快地打破视线接触，从而实现自然的对话模式：

字段	值
MaxContinuousHoldSeconds	3.5
InterestDecayPerSecond	0.30

预期结果： 在对话轮换期间，每个角色的目光会自然地在另一角色和中性位置之间交替，从而呈现出真实双向互动的效果。

---

示例 4 — 具有高风险评估目光的考官

场景： 一个军事模拟包含一名军官考官，在正式评估期间其目光会变得更加锐利和具评估性。扫视范围应缩小，闲置探索应停止，且以头部为主导的跟踪应增强。

设置：

创建两个 ConvaiGazeEyeProfile 资源：

普通配置文件：

• 默认值（启用扫视，启用闲置探索）

评估配置文件：

• SaccadeMaxDegrees: 0.8 （非常小——几乎不动的目光）
• EnableIdleExploration: false
• TrackingSharpness: 25.0 （更灵敏的眼部跟踪）

这些注视驱动器不提供运行时 SetProfile() 方法。若要在运行时更改配置文件，可以为每个阶段使用单独的角色 GameObject 并进行激活/停用，或者在子类上公开一个公共包装字段，用于重新赋值配置文件引用。

要通过在每个阶段开始时激活不同的角色 GameObject 来切换配置文件：

using UnityEngine;

public class ExaminerPhaseController : MonoBehaviour
{
    [SerializeField] private GameObject _normalExaminer;
    [SerializeField] private GameObject _assessmentExaminer;

    public void BeginAssessment()
    {
        _normalExaminer.SetActive(false);
        _assessmentExaminer.SetActive(true);
    }

    public void EndAssessment()
    {
        _assessmentExaminer.SetActive(false);
        _normalExaminer.SetActive(true);
    }
}

预期结果： 在评估阶段，考官的眼睛移动幅度很小，几乎不进行探索，而是以紧密的焦点持续注视玩家，呈现出持续的评估注意力。

---

下一步

有关完整的 API 参考，包括自定义 IFocusTargetProvider 契约以及所有可读取的注意力状态，请参阅 Scripting API 页面。

凝视与注意力脚本 API