> 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 中的设置，再给出完成相应行为所需的运行时代码。字段说明请参阅 [注视配置文件参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/profile-reference.md)；完整的脚本接口请参阅 [注视脚本参考](https://docs.convai.com/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，不回避目光，并充分配合头部动作——贯穿所有对话状态；而在简报间隙， `Idle` 会保留配置文件中设定的环境行为，而不是持续凝视。 `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` 应设为 `Natural` （默认值）；如果使用 `ConversationLock` 或 `AlwaysLock` 并启用 `LockBlocksGlances` （默认值），这次瞥视请求会被忽略，谈判人员会始终看着受训者。这不适合需要中断目光接触、查看文件的角色。

**预期结果：** 谈判人员会低头看合同两秒，但身体不会转向；停留结束后，会自动将注意力转回受训者。

### 场景 3：群体场景中的多角色聆听

**情境：** 在一个公司入职引导场景中，三名 NPC 并肩站立。一人说话时，另外两人应转向倾听；三人都处于闲置状态时，他们应偶尔互相对视，而不是茫然地盯着前方。

#### 组件设置

为每个参与的角色添加 `CharacterGazeTargetProvider` (**Add Component > Convai > Gaze > Advanced > Character Target**)，并与其 `ConvaiGazeController`一起添加。保持 **Publish Self** 和 **Look At Others** 启用，这样每个角色既会将自身作为目标提供，也会为其他角色生成候选目标。默认的 **Priority** 值 `7` 介于玩家锚点的 `10` 和世界对象的 `5`之间，因此倾听者会转向正在说话的同事，但与玩家的对话仍会优先。

将每个角色的 **Attend To Speaker** (`ConvaiGazeController.AttendToSpeaker`（一个 `GazeSpeakerAttention` 值）保持为默认值： `Off`, `Player`, `Characters`或 `Anyone`）。这项设置会让正在倾听的角色转向当前发言者——上面的 `Anyone`默认值 `CharacterGazeTargetProvider` 只会让角色具备被注视的资格。 `Anyone` 会响应玩家和其他角色的回合，这正是此场景所需的行为。

#### 验证每个角色都已添加 Provider

```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} has no Character Gaze Target Provider and will not join mutual gaze.");
        }
    }
}
```

`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("No gauge target resolved.");

        GazeHandle look = gaze.GazeAt(target, new GazeOptions { Engagement = 1f, HoldSeconds = 4f });
        using (cancellationToken.Register(look.Release))
        {
            await look.Settled;
            look.Release();
            return ConvaiActionExecutionResult.Answered("The gauge reads 40 percent.");
        }
    }
}
```

`GazeAt` 使用显式设置的 `Engagement` 值 `1` 可用于任何对话状态，包括 `Idle`，并且优先级高于所有自动目标。等待 `handle.Settled` 可确保角色确实看向目标后才作答—— `Settled` 会在视线明显对准目标后完成，因此角色眼睛还没看过去时，绝不会先报出读数。 `ConvaiActionExecutionResult.Answered` 是结果中唯一会告知角色本身的部分；是否朗读答案，则由 Actions Editor 中针对每个动作单独决定。

**预期结果：** 技术员会先明显地看向仪表，再报告读数——角色的视线尚未稳定对准目标时，绝不会返回答案。

### 后续步骤

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

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

{% content-ref url="/pages/beb7fd6775b7e9b4da287a76d337e2f0e2a2b17f" %}
[排查视线问题](https://docs.convai.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
