> 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/embodiment/gaze/usage-examples.md).

# Gaze 使用示例

通过四个完整的 Convai Gaze 使用示例，配置眼神接触、脚本化瞥视，并协调多角色视线。

这些场景展示了如何 `ConvaiGazeController` 以及其支持组件如何组合以满足真实的应用需求。每个场景都是自包含的：先描述 Inspector 设置，然后给出完成该行为所需的任何运行时代码。字段参考见 [注视配置参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/profile-reference.md)；完整的脚本接口见 [注视脚本参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/scripting-reference.md).

### 场景 1：讲解时保持眼神接触

**情境：** 安全简报模拟中的一名讲师 NPC 在整个程序讲解过程中必须始终与学员保持稳定的眼神接触，而不是在简报之间变成呆滞的凝视。

#### 运行时脚本

```csharp
using Convai.Modules.Gaze.Components;
using UnityEngine;

public sealed class SafetyBriefingGazeDirector : MonoBehaviour
{
    [SerializeField] private ConvaiGazeController instructorGaze;

    public void BeginExplanation()
    {
        instructorGaze.EyeContactMode = GazeEyeContactMode.ConversationLock;
        instructorGaze.FocusFidelity = GazeFocusFidelity.Social;
    }

    public void EndExplanation() =>
        instructorGaze.EyeContactMode = GazeEyeContactMode.Natural;
}
```

`GazeEyeContactMode.ConversationLock` 会在每个对话状态中对玩家锚点给予完全投入——参与度固定为 1、无回避、头部完全参与——而 `空闲` 在简报之间则保持该配置文件预设的环境行为，而不是一直盯着看。 `GazeFocusFidelity.Social` 会在接触锥内保持微妙的凝视活性，使锁定看起来仍然是有生命感的，而不是机械化的。

**预期结果：** 讲师在整个讲解过程中都与学员保持完全投入的眼神接触，并在接触锥内保留微妙的凝视活性，使锁定看起来有生命感而非机械化，并在 `EndExplanation()` 运行之前注册。

### 场景 2：瞥一眼文件，然后回到访客身上

**情境：** 谈判模拟中的一名谈判者 NPC 在学员举起桌上的合同时时，应先朝合同看一眼，然后再把注意力转回学员，不要丢掉对话脉络。

#### 运行时脚本

```csharp
using Convai.Modules.Gaze.Components;
using UnityEngine;

public sealed class NegotiationDocumentCue : MonoBehaviour
{
    [SerializeField] private ConvaiGazeController negotiatorGaze;
    [SerializeField] private Transform contractOnTable;

    public void ShowContract() =>
        negotiatorGaze.GlanceAt(contractOnTable, durationSeconds: 2f);
}
```

`GlanceAt` 它是一项投入但低优先级的脚本请求：它绝不会转动身体，而且角色会在两秒停留结束后立即回到策略所规定的行为——无需额外记录。保持 `EyeContactMode` 时 `自然` （默认值）用于此场景；在 `ConversationLock` 或 `AlwaysLock` 与 `LockBlocksGlances` 开启（默认值）时，瞥视会被吸收，谈判者就不会把目光从学员身上移开；而对于一个本应打破接触并查看文件的角色来说，这样的表现是错误的。

**预期结果：** 谈判者会先低头看合同两秒钟，而不会转动身体，停留结束后会自动把注意力转回学员。

### 场景 3：群组场景中的多角色倾听

**情境：** 企业入职场景中有三个 NPC 站在一起。当其中一个说话时，另外两个应转身倾听；当三人都处于空闲状态时，他们应偶尔交换眼神，而不是茫然地直视前方。

#### 组件设置

添加 `CharacterGazeTargetProvider` (**Add Component > Convai > Gaze > Advanced > Character Target**）到每个参与角色，并连同其 `ConvaiGazeController`。将 **发布自身** 和 **看向他人** 保持开启，这样每个角色既会把自己作为目标提供出来，也会为其他角色生成候选目标。默认的 **优先级** 的 `7` 位于玩家锚点的 `10` 和世界对象的 `5`之间，因此倾听者会转向正在说话的同事，但与玩家的对话仍会优先。

将每个角色的 **听众关注** (`ConvaiGazeController.AttendToSpeaker`下方，有一个 `GazeSpeakerAttention` 值： `关闭`, `玩家`, `角色`，或 `任何人`）保持默认， `任何人`。这才是会真正把倾听中的角色转向当前发言者的设置—— `CharacterGazeTargetProvider` 上面的设置只会让角色具备被注视的资格。 `任何人` 会同时对玩家的发言回合和其他角色的发言回合作出反应，这正是此场景所需要的。

#### 验证每个角色都具有提供器

```csharp
using Convai.Modules.Gaze.Providers;
using Convai.Runtime.Components;
using UnityEngine;

public sealed class MultiCharacterGazeAudit : MonoBehaviour
{
    private void Start()
    {
        foreach (ConvaiCharacter character in ConvaiManager.ActiveManager.Characters)
        {
            if (character.GetComponentInChildren<CharacterGazeTargetProvider>(true) == null)
                Debug.LogWarning($"{character.name} 没有 Character Gaze Target Provider，且不会加入互相注视。");
        }
    }
}
```

`ConvaiManager.ActiveManager.Characters` 列出所有 `ConvaiCharacter` 管理器当前拥有的角色，这使其成为对一个在不同时间添加了多个 NPC 的场景进行一次性审计的便捷方式。无论基于距离的相关性衰减如何，正在说话的角色对其他角色始终是完全相关的，这也是倾听者会转向当前发言者的原因； **空闲时的眼神交换** （默认开启）控制所有角色同时空闲时彼此之间的偶尔眼神交流。

**预期结果：** 两个倾听中的角色会转向说话者，而当场景进入空闲状态后，三个角色都会偶尔交换眼神，而不是茫然地直视前方。

### 场景 4：看向目标后回答问题

**情境：** 设备训练模拟中的一名技术员 NPC 被要求读取仪表读数。它应在报告读数之前明显看向仪表，而不是头还朝着学员时就立刻回答。

#### 动作执行器

```csharp
using System.Threading;
using System.Threading.Tasks;
using Convai.Modules.Gaze.Components;
using Convai.Runtime.Actions;
using UnityEngine;

public sealed class ReadGaugeActionExecutor : ConvaiActionExecutorBase
{
    [SerializeField] private ConvaiGazeController gaze;

    public override async Task<ConvaiActionExecutionResult> ExecuteAsync(
        ConvaiActionInvocation invocation, CancellationToken cancellationToken)
    {
        Transform target = invocation.ResolvedTarget?.InteractionPoint;
        if (target == null)
            return ConvaiActionExecutionResult.Unhandled("未解析到仪表目标。");

        GazeHandle look = gaze.GazeAt(target, new GazeOptions { Engagement = 1f, HoldSeconds = 4f });
        using (cancellationToken.Register(look.Release))
        {
            await look.Settled;
            look.Release();
            return ConvaiActionExecutionResult.Answered("仪表读数为 40%。");
        }
    }
}
```

`GazeAt` 并带有明确的 `参与度` 的 `1` 可在任何对话状态下工作，包括 `空闲`，并优先于所有自动目标。等待 `handle.Settled` 会以角色确实已经看过去为前提来放行回答—— `Settled` 一旦视线明显对齐到目标上就完成，因此报告的数值绝不会比目光先到。 `ConvaiActionExecutionResult.Answered` 是唯一会告知角色本身的结果部分；答案是否被说出，则是在 Actions Editor 中按每个动作单独决定的。

**预期结果：** 技术员会在报告读数之前明显看向仪表——在角色的目光在目标上稳定下来之前，答案绝不会被返回。

### 下一步

{% content-ref url="/pages/0c6914a280e6fc584ecfe676625883fc201033e3" %}
[脚本控制的视线](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/scripted-gaze.md)
{% endcontent-ref %}

{% content-ref url="/pages/864133eda5776302d8f8f9afeef2de62388e08bc" %}
[视线目标与提供器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/targets-and-providers.md)
{% endcontent-ref %}

{% content-ref url="/pages/beb7fd6775b7e9b4da287a76d337e2f0e2a2b17f" %}
[排查视线问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/troubleshooting.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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.