> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/gaze-and-attention/usage-examples.md).

# 注视与注意力使用示例

这些示例从仅在 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` 用于设备：

```csharp
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` 会在 **在层级中发现提供器** 被启用时自动发现它。

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

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

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

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

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

***

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

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

**设置：**

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

```csharp
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` （更灵敏的眼部跟踪）

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

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

```csharp
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 页面。

{% content-ref url="/pages/5a9422b007899ae59891f1bd5d95035da644a167" %}
[注视与注意力脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/gaze-and-attention/scripting-api.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/utilities/gaze-and-attention/usage-examples.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.