凝视与注意力脚本 API

ConvaiAttentionController、AttentionReading、IFocusTargetProvider、ConvaiGazeCoordinator 和 GazeIntent 的运行时脚本参考。

Gaze & Attention 系统公开两个独立的 API 接口： 注意力系统 （角色看向什么）以及 注视系统 （它如何看起来）。除注明外，二者在运行时均为只读。

---

注意力系统

ConvaiAttentionController

命名空间： Convai.Modules.Attention.Components 组件菜单： Convai → Embodiment → Attention Controller

成员	类型	描述
当前	AttentionReading （get）	当前注意力快照。每帧更新。可安全地从 Update().
RefreshProviders()	void	重新扫描角色层级中的 IFocusTargetProvider 组件。请在运行时添加提供者后调用。

---

AttentionReading

命名空间： Convai.Domain.Embodiment.Readings 类型： readonly struct

角色当前关注对象的不可变快照。由 ConvaiAttentionController.Current.

属性	类型	描述
IsValid	bool	true 当该读数表示一个可用的注意力目标时。 false 在空闲状态下或当没有提供者返回候选项时。
Target	Transform	被关注的 Transform。对于仅由世界空间点定义的候选项，可能为 null 。
SmoothedPoint	Vector3	平滑后的世界空间焦点。将其用于注视目标定位——它能避免目标在帧与帧之间移动造成的抖动。
Commitment	float	[0, 1] 范围内的归一化承诺度。1 = 完全投入；0 = 脱离。会根据 ConvaiAttentionProfile.
TargetGenerationId	int	稳定的整数，每当注意力转移到新目标时递增一次。跨帧比较即可检测注意力切换，而无需轮询标识。 Target 标识。
Empty	AttentionReading （static）	预构建的脱离状态读数（IsValid = false, Commitment = 0).

检测注意力切换：

using Convai.Modules.Attention.Components;
using UnityEngine;

public class AttentionSwitchDetector : MonoBehaviour
{
    [SerializeField] private ConvaiAttentionController _attention;

    private int _lastGenerationId;

    private void Update()
    {
        var reading = _attention.Current;

        if (reading.TargetGenerationId != _lastGenerationId)
        {
            _lastGenerationId = reading.TargetGenerationId;
            OnAttentionSwitched(reading);
        }
    }

    private void OnAttentionSwitched(AttentionReading reading)
    {
        if (!reading.IsValid)
            Debug.Log("注意力已释放——角色处于空闲状态。");
        else
            Debug.Log($"现在关注：{reading.Target?.name ?? \"world point\"} " +
                      $"位于 {reading.SmoothedPoint}");
    }
}

---

AttentionCandidate

命名空间： Convai.Domain.Embodiment.Readings 类型： readonly struct

由 IFocusTargetProvider.TryGetCandidate() 每帧产生。注意力控制器会评估所有候选项并选出胜者。

属性	类型	描述
优先级	int	用于平局裁决的静态排序提示。当相关性分数相同时，优先级更高的候选项获胜。
相关性	float	[0, 1] 范围内的当前相关性。驱动选择概率。 0 = 对注意力系统而言几乎不可见。
Target	Transform	支撑此候选项的可选 Transform。可能为 null.
WorldPoint	Vector3	要看的世界空间点。当 Target 为 null.
DebugName	string	在诊断日志中显示的简短标识符。

---

IFocusTargetProvider

命名空间： Convai.Domain.Embodiment.Interfaces

在任何 MonoBehaviour 上实现此接口，以提供注意力候选项。位于角色 GameObject 或其子对象上的实现了此接口的组件，会在 Discover Providers In Hierarchy 启用时自动发现。

成员	类型	描述
优先级	int （get）	跨提供者用于平局裁决的静态优先级。默认摄像机提供者使用的优先级 0.
TryGetCandidate(characterRoot, out candidate)	bool	每帧调用。返回 true 并填充 candidate 以提议一个目标。返回 false 以在本帧退出竞争。

最小实现：

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

public class ObjectOfInterestProvider : MonoBehaviour, IFocusTargetProvider
{
    [SerializeField] private Transform _target;
    [SerializeField] private float _relevance = 0.75f;

    public int Priority => 5;

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

        candidate = new AttentionCandidate(
            priority: Priority,
            relevance: _relevance,
            target: _target,
            worldPoint: _target.position,
            debugName: "ObjectOfInterest"
        );
        return true;
    }
}

---

注视系统

ConvaiGazeCoordinator

命名空间： Convai.Modules.Gaze.Components 组件菜单： Convai → Embodiment → Gaze Coordinator

ConvaiGazeCoordinator 由 ConvaiEyeGazeActuator 在初始化期间自动创建。不要从 Awake() 中访问它——它此时尚不存在。请使用 Start() 或更后面的生命周期事件。

成员	类型	描述
当前	GazeIntent （get）	本帧计算出的当前注视意图。在 ConvaiAttentionController 运行后更新。

---

GazeIntent

命名空间： Convai.Domain.Embodiment.Readings 类型： readonly struct

……的输出 ConvaiGazeCoordinator。由 ConvaiEyeGazeActuator 和 ConvaiHeadLookActuator.

属性	类型	描述
WorldTargetPoint	Vector3	眼部和头部执行器应朝向的世界空间点
OverallWeight	float	[0, 1] 范围内的整体注视权重。缩放执行器跟踪目标的强度。
EyeShare	float	仅由眼睛单独处理的跟踪比例。头部处理 1 − EyeShare.
Relaxed	GazeIntent （static）	预构建的脱离状态意图（OverallWeight = 0）。当协调器没有有效注意力输入时使用。

---

ConvaiHeadLookActuator

命名空间： Convai.Modules.Gaze.Components 组件菜单： Convai → Embodiment → Head Look

成员	类型	描述
CurrentHeadAuthority	float （get）	当前头部旋转权威级别（已平滑，考虑到 MinimumHeadContribution)
IsIdleExploring	bool （get）	true 当头部执行器正在运行其空闲探索行为时（空闲对话状态下会抑制注意力）
CurrentSolvedAngles	Vector2 （get）	当前应用到颈部/头部链的已求解偏航（x）和俯仰（y）角度，单位为度

---

ConvaiEyeGazeActuator

命名空间： Convai.Modules.Gaze.Components 组件菜单： Convai → Embodiment → Eye Gaze

除标准 Unity 组件成员外，眼部执行器没有可在运行时读取的状态属性。使用 ConvaiGazeCoordinator.Current 来读取注视意图，以及 ConvaiAttentionController.Current 来读取注意力状态。

---

脚本示例

为 UI 指示器读取承诺度

using Convai.Modules.Attention.Components;
using UnityEngine;
using UnityEngine.UI;

public class CommitmentBar : MonoBehaviour
{
    [SerializeField] private ConvaiAttentionController _attention;
    [SerializeField] private Slider _slider;

    private void Update()
    {
        _slider.value = _attention.Current.Commitment;
    }
}

---

在场景加载后注册运行时提供者

如果你在运行时添加一个 IFocusTargetProvider 组件（例如实例化一个道具），请调用 RefreshProviders() 这样注意力控制器就会识别它：

using Convai.Modules.Attention.Components;
using UnityEngine;

public class RuntimePropSpawner : MonoBehaviour
{
    [SerializeField] private ConvaiAttentionController _attention;
    [SerializeField] private GameObject _propPrefab;

    public void SpawnProp(Vector3 position)
    {
        var prop = Instantiate(_propPrefab, position, Quaternion.identity);

        // 提供者在新道具上——刷新以便控制器看到它
        _attention.RefreshProviders();
    }
}

---

区分注意力与注视诊断

使用 AttentionReading.IsValid 在注视看起来不对时，判断应排查哪个系统：

using Convai.Modules.Attention.Components;
using UnityEngine;

public class GazeDiagnostics : MonoBehaviour
{
    [SerializeField] private ConvaiAttentionController _attention;

    private void Update()
    {
        if (!_attention.Current.IsValid)
        {
            // 问题出在注意力系统：
            // 没有提供者返回候选项，或所有相关性分数都为 0
            Debug.Log("注意力：没有有效目标");
        }
        else
        {
            // 注意力有效——如果眼睛/头部仍然静止，
            // 问题出在注视系统（配置文件、骨骼配置或协调器）
            Debug.Log($"注意力有效。目标：{_attention.Current.Target?.name}, " +
                      $"承诺度：{_attention.Current.Commitment:F2}");
        }
    }
}

---

下一步

如需帮助处理常见故障——眼睛静止、头部冻结或缺少注意力目标——请参阅故障排除页面。

凝视与注意力故障排查