> 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/targets-and-providers.md).

# 视线目标与提供器

将场景对象标记为视线候选项，添加高级提供器组件，并从代码中注册自定义视线目标提供器。

将 GameObject 标记为注视候选对象，添加八种高级 Provider 组件以实现更丰富的目标行为，并通过代码注册自定义 Provider。将 `ConvaiGazeController` 添加到角色后，如果你希望它以非默认方式注意特定场景对象、其他角色或玩家，请使用本页面。

### 前提条件

* `ConvaiGazeController` 已添加到角色（`Convai/Embodiment/Gaze`).
* 要标记的场景对象，或能够自行提供候选对象的脚本。

### 将场景对象标记为注视目标

添加 `ConvaiGazeTarget` (`Convai/Gaze/Target`）到任意 GameObject，即可将其设为场景中所有 Convai 角色的注视候选对象。无需场景元数据。

| 字段                        | 默认值         | 用途                                                                 |
| ------------------------- | ----------- | ------------------------------------------------------------------ |
| `Priority`                | `5`         | 优先级层级。玩家锚点以 `10`发布，因此默认值 `5` 在对话期间会低于玩家。将其调高至 `10` 以上即可获得高于玩家的优先级。 |
| `Base Relevance`          | `0.75`      | 位于 `Full Relevance Distance`.                                      |
| `Max Distance`            | `10` （米）    | 超过此距离后，该目标不再是候选对象。                                                 |
| `Full Relevance Distance` | `3` （米）     | 小于此距离时，相关性达到最大值。                                                   |
| `Aim Offset`              | `(0, 0, 0)` | 相对于 Transform 的局部空间偏移量，用于指定眼睛注视的确切位置，例如一幅画的顶部。                     |

{% hint style="info" %}
`ConvaiGazeTarget` 是通用标记。仅当对象已带有 `WorldObjectGazeTargetProvider`时才使用下文介绍的该组件。 `ConvaiObjectMetadata`.
{% endhint %}

### 添加高级注视 Provider

高级 Provider 位于“添加组件”菜单中的 `Convai/Gaze/Advanced/` 下。每个组件均为可选添加项——添加 `ConvaiGazeController` 即可让角色拥有眼睛、头部、待机动作、眨眼、身体转向和对话节奏，无需进一步设置；这些组件则在此基础上提供更多功能。

#### 角色目标 — 角色之间的相互注视

`CharacterGazeTargetProvider` (`Convai/Gaze/Advanced/Character Target`）可使角色注视其他 Convai 角色，也能被其他 Convai 角色注视。每个参与的角色都添加一个组件；角色身份、对话状态和视线落点均来自角色的具身上下文。

| 字段                                 | 默认值            | 用途                                                                               |
| ---------------------------------- | -------------- | -------------------------------------------------------------------------------- |
| `Publish Self`                     | `true`         | 将此角色注册为其他角色可以注视的目标。                                                              |
| `Look At Others`                   | `true`         | 为其他已注册角色生成注视候选对象。                                                                |
| `Priority`                         | `7`            | 在玩家锚点（`10`）和世界对象（`5`），因此玩家在对话期间优先级最高，而角色的优先级高于背景道具。                              |
| `Speaking Priority`                | `9`            | 角色发言时使用的优先级层级——高于闲置 `Priority` 层级，这样已经将注意力集中在发言者身上的听者就不会被旁观者吸引走；同时仍低于玩家锚点（`10`). |
| `Max Distance`                     | `12` （米）       | 超过此距离后，其他角色将不再作为候选对象（`0` = 无限制）。                                                 |
| `Full Relevance Distance`          | `4` （米）        | 低于此距离时，其他角色的相关性达到最高。                                                             |
| `Idle Glance Relevance`            | `0.35`         | 非发言角色的相关性。发言角色始终具有最高相关性，因此听者会转向当前发言者。                                            |
| `Eye Line Offset`                  | `1.6` （米）      | 在通过绑定的骨架解析出此角色的头部骨骼之前，其他角色注视的视线高度。                                               |
| `Enable Idle Glances`              | `true`         | 闲置时，与附近角色偶尔进行短暂的对视。                                                              |
| `Idle Glance Interval Min` / `Max` | `5` / `12` （秒） | 闲置角色之间对视的时间间隔范围。                                                                 |
| `Idle Glance Duration`             | `1.4` （秒）      | 一次闲置角色对视的持续时间。                                                                   |
| `Idle Glance Engagement`           | `0.5`          | 闲置对视的投入程度。                                                                       |

#### 眼部瞳孔驱动器 — 瞳孔扩张

`ConvaiEyePupilDriver` (`Convai/Gaze/Advanced/Eye Pupil Driver`）会使用注视模块平滑处理后的唤醒度信号扩张角色瞳孔。它通过复用的 `MaterialPropertyBlock` 逐个渲染器写入，因此不会修改共享材质资源。

| 字段                     | 默认值                | 用途                                                           |
| ---------------------- | ------------------ | ------------------------------------------------------------ |
| `Renderers`            | 空                  | 显式指定渲染器目标。留空则自动查找角色下所有 `SkinnedMeshRenderer` ，其材质需包含相应着色器属性。 |
| `Shader Property Name` | `_PupilScale`      | 要驱动的着色器浮点属性。默认使用 Reallusion RL5 角膜着色器的瞳孔缩放属性。                |
| `Max Dilation Percent` | `12` （范围 `5`–`20`) | 唤醒度达到最高时的最大瞳孔扩张幅度，以各渲染器基础属性值的百分比表示。                          |
| `Invert Sign`          | `false`            | 若骨架中较大的属性值会使瞳孔缩小，则反转扩张方向。                                    |

#### 动态上下文桥接 — 注意力定位

`GazeDynamicContextBridge` (`Convai/Gaze/Advanced/Dynamic Context Bridge`）会将角色当前注视的对象同步到 Convai 动态上下文键 `current_attention_object`，因此“它”或“那个”等代词会根据角色实际注视的对象来解析。

| 字段     | 默认值   | 用途              |
| ------ | ----- | --------------- |
| `注视阈值` | `0.5` | 发布对象前所需的最低注视程度。 |

#### 共同注意——留意玩家在看什么

`GazeJointAttention` (`Convai/Gaze/Advanced/Joint Attention`) 会留意玩家正在注视的对象，也朝那里看一眼，然后根据注视策略的指示恢复注视——也就是“我看到了吸引你注意的东西”这一刻。它完全基于公开的 `GlanceAt` API，因此无需更改注视核心。

| 字段                | 默认值             | 用途                         |
| ----------------- | --------------- | -------------------------- |
| `锥形角度（度）`         | `8`             | 用于判断玩家的注视射线是否对准候选对象的锥形半角。  |
| `最大距离（米）`         | `12`            | 可被注意到的候选对象与玩家之间的最大距离。      |
| `注视停留秒数`          | `0.7`           | 玩家必须持续注视对象多长时间，角色才会注意到它。   |
| `短暂注视时长（秒）`       | `1.4`           | 注视被注意到的对象的时长。              |
| `反应延迟最小值/最大值（秒）`  | `0.2` / `0.5`   | 从注意到对象到朝它看一眼之间的延迟范围。       |
| `冷却时间（秒）`         | `10`            | 再次注意到同一对象前，该对象各自的冷却时间。     |
| `全局最小间隔（秒）`       | `4`             | 任意两次共同注意短暂注视之间的最小间隔。       |
| `评估间隔（秒）`         | `0.2`           | 评估玩家注视情况的间隔（默认约为 5 Hz）。    |
| `发布注意力上下文`        | `false`         | 将注意到的对象名称发布到 Convai 动态上下文。 |
| `空闲时启用` / `聆听时启用` | `true` / `true` | 共同注意启用时所处的对话状态。            |

#### 指示性短暂注视——看向提及的对象

`GazeReferentialGlances` (`Convai/Gaze/Advanced/Referential Glances`) 会在角色自己的发言提到某个已注册的世界对象时，让角色看它一眼——例如“看看那幅画”。它会匹配角色的最终转录文本，并完全基于公开的 `GlanceAt` API。

| 字段             | 默认值           | 用途                    |
| -------------- | ------------- | --------------------- |
| `短暂注视时长`       | `1.6` （秒）     | 看向提及对象的时长。            |
| `冷却时间（秒）`      | `10`          | 再次看向同一对象前，该对象各自的冷却时间。 |
| `提及词数上限`       | `4`           | 可匹配的对象名称的最长词数。        |
| `延迟最小值/最大值（秒）` | `0.3` / `0.8` | 从提及对象到看向它之间的延迟范围。     |

#### 玩家锚点——自定义角色如何定位“玩家”

`PlayerAnchorTargetProvider` (`Convai/Gaze/Advanced/Player Anchor`) 是开箱即用的“看向玩家”提供程序。 `ConvaiGazeController` 当角色没有其他提供程序时，会在运行时自动创建一个。手动添加可覆盖每个角色的锚点，适用于分屏、多人游戏或过场动画绑定。

| 字段                            | 默认值                            | 用途                                                                                                                                                                                     |
| ----------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Priority`                    | `10`                           | 用于在各提供程序之间比较的静态优先级层级。                                                                                                                                                                  |
| `Explicit Anchor`             | 无                              | 留空时，会解析为 `Camera.main`，然后是第一个符合条件且已启用的游戏视图摄像机。                                                                                                                                         |
| `Eye Line Offset`             | `1.6` （米）                      | 应用于显式指定的非摄像机锚点的垂直抬升量。                                                                                                                                                                  |
| `Aim Mode`                    | `Auto`                         | `GazeAnchorAimMode` —注视锚点上的哪个位置。                                                                                                                                                       |
| `Face Presence`               | `Auto`                         | `GazeAnchorFacePresence` —角色是否将锚点视为一张脸，并注视其周围（如眼睛、嘴巴），而不是精确瞄准锚点。 `Auto` 根据锚点决定：手动指定的锚点会被视为一张脸，而 SDK 自行解析出的摄像机会被视为视点，并被精确瞄准。 `Face` 始终将锚点视为一张脸——适用于 VR，因为摄像机位于玩家双眼之间。 `Point` 始终精确瞄准锚点。 |
| `Local Aim Offset`            | `(0, 0, 0)`                    | 锚点局部空间中的瞄准偏移，由 `Local Offset` 模式使用。                                                                                                                                                    |
| `Max Distance`                | `8` （米）                        | 超过此距离后，玩家将不再作为候选对象。                                                                                                                                                                    |
| `Full Relevance Distance`     | `4` （米）                        | 小于此距离时，相关性达到最大值。                                                                                                                                                                       |
| `Check Line Of Sight`         | `false`                        | 要求玩家与角色之间视线无遮挡。被遮挡时，相关性会逐渐衰减；玩家重新出现时，将播放常规的目标获取扫视动作。                                                                                                                                   |
| `Obstruction Mask`            | `Physics.DefaultRaycastLayers` | 在线视线检测中视为遮挡物的图层。                                                                                                                                                                       |
| `Line Of Sight Interval`      | `0.1` （秒）                      | 控制线视线射线检测的频率。                                                                                                                                                                          |
| `Line Of Sight Origin Height` | `1.6` （米）                      | 视线射线起点相对于角色根节点的高度。                                                                                                                                                                     |

#### 玩家注意力传感器 — 检测玩家是否正看着角色

`PlayerAttentionSensor` (`Convai/Gaze/Advanced/Player Attention Sensor`）会告知角色玩家是否正在看着它。默认信号来自主摄像机的前向射线；XR 眼动追踪可通过 `IPlayerGazeRaySource` （参见 [为 XR 提供自定义玩家注视射线](#supply-a-custom-player-gaze-ray-for-xr)）接入，且无需依赖任何 XR 程序包。平滑后的信号会发布到 Convai 动态上下文键 `player_attention` (`looking_at_me` / `away`，由状态变化触发）。

| 字段                   | 默认值            | 用途                                             |
| -------------------- | -------------- | ---------------------------------------------- |
| `Detection Interval` | `0.1` （秒）      | 检测采样之间的间隔。                                     |
| `基础半角`               | `6` （度）        | 会话距离处的基础接受锥半角。                                 |
| `最大半角`               | `28` （度）       | 近距离处的最大接受锥半角。                                  |
| `角色角半径`              | `0.35` （米）     | 角色头部/上半身的近似角半径。                                |
| `头部高度`               | `1.6` （米）      | 未解析到 Head 骨骼时使用的视线高度。                          |
| `上升秒数` / `下降秒数`      | `0.5` / `1.5`  | 注意力信号建立和衰减的时间常数。                               |
| `进入阈值` / `退出阈值`      | `0.6` / `0.35` | 用于发布的滞后阈值 `looking_at_me` / `away`.            |
| `发布到上下文`             | `true`         | 将注视/移开状态发布到 Convai 动态上下文。                      |
| `注视射线源组件`            | 无              | 可选组件，实现了 `IPlayerGazeRaySource`。留空则从玩家摄像机发射射线。 |

#### 世界对象目标 — 标记已创作的世界对象

`WorldObjectGazeTargetProvider` (`Convai/Gaze/Advanced/World Object Target`) 会将已创作的 Convai 世界对象（即已包含 `ConvaiObjectMetadata` (`RequireComponent`) 的对象）标记为环境注视候选对象。附近的角色在闲置时会瞥向它；如果它获得注意力，动态上下文桥接器会将其报告给 Convai。

| 字段                        | 默认值      | 用途                            |
| ------------------------- | -------- | ----------------------------- |
| `Priority`                | `5`      | 优先级低于玩家锚点（`10`），以确保对话期间玩家优先。  |
| `Base Relevance`          | `0.75`   | 位于 `Full Relevance Distance`. |
| `Max Distance`            | `10` （米） | 对象超出此距离后将不再作为候选对象。            |
| `Full Relevance Distance` | `3` （米）  | 小于此距离时，相关性达到最大值。              |

### 通过代码扩展目标

#### 注册自定义目标提供程序

实现 `IGazeTargetProvider` 并为非来自角色层级中 `ConvaiGazeController.RegisterTargetProvider` 的候选对象调用 `MonoBehaviour` ——例如系统级来源、通过网络代码同步的目标或测试替身。

```csharp
using Convai.Domain.Embodiment.Semantics;
using Convai.Modules.Gaze.Components;
using Convai.Modules.Gaze.Providers;
using UnityEngine;

public sealed class ScannerBeaconProvider : IGazeTargetProvider
{
    private readonly Transform _beacon;

    public ScannerBeaconProvider(Transform beacon) => _beacon = beacon;

    public bool TryGetCandidate(Transform characterRoot, out GazeTargetCandidate candidate)
    {
        candidate = default;
        if (_beacon == null) return false;

        candidate = new GazeTargetCandidate(
            GazeTargetKind.WorldObject,
            priority: 6,
            relevance: 0.8f,
            target: _beacon,
            worldPoint: _beacon.position,
            debugName: "Scanner Beacon");
        return true;
    }
}

// 挂载到角色上（或持有序列化的 ConvaiGazeController 引用）：
public sealed class ScannerBeaconRegistrar : MonoBehaviour
{
    [SerializeField] private Transform beaconTransform;

    private void Start()
    {
        ConvaiGazeController gaze = GetComponent<ConvaiGazeController>();
        gaze.RegisterTargetProvider(new ScannerBeaconProvider(beaconTransform));
    }
}
```

`TryGetCandidate` 每个认知周期都会运行，因此实现应保持轻量。返回 `false` （或相关性为 `0`）会移除此帧的候选目标；仲裁器负责处理目标获取与释放时的平滑过渡。当提供程序不再有效时，调用 `UnregisterTargetProvider` 取消注册。

#### 为 XR 提供自定义玩家注视射线

`IPlayerGazeRaySource` 提供玩家当前注视方向上的世界空间射线，因此 `PlayerAttentionSensor` 和 `GazeJointAttention` 可以判断玩家是否正在注视某个对象，而 SDK 无需硬性依赖 XR 软件包。可基于 OpenXR 或厂商的眼动追踪适配器实现该接口，并为每个组件注册：

```csharp
using Convai.Domain.Embodiment.Interfaces;
using Convai.Modules.Gaze.Providers;
using UnityEngine;

public sealed class OpenXrEyeTrackingSource : IPlayerGazeRaySource
{
    public bool TryGetPlayerGazeRay(out Ray ray)
    {
        // 从 XR 眼动追踪 API 填充 `ray`。追踪丢失时返回 false。
        ray = default;
        return false;
    }
}

// 挂载到角色上：
public sealed class XrGazeRaySetup : MonoBehaviour
{
    private void Start()
    {
        PlayerAttentionSensor sensor = GetComponentInChildren<PlayerAttentionSensor>();
        sensor.SetGazeRaySource(new OpenXrEyeTrackingSource());
    }
}
```

当此帧没有可用射线时（例如追踪丢失或头显关闭），返回 `false` ，这样使用方就会回退到摄像机射线。射线源按组件实例注册，而非全局注册，因此一个场景中的适配器不会在不知情的情况下驱动另一个场景中的角色。

### 目标移动的过滤方式

每个注视目标的瞄准点都会先经过平滑处理，再交由头部移动检测器处理。因此，普通的轻微移动（例如说话角色的头部晃动、手持设备上的摄像机摆动）不会被识别为目标移动，也不会触发头部重新规划。对于摄像机切换或传送等真正的突变，系统会根据原始跳变而非平滑后的数据进行检测，因此眼睛会立即转向新位置，而不会逐渐滑向目标。

### 验证是否找到了目标

进入播放模式并打开 `Convai > Gaze Editor` 在选中角色时。窗口的实时视图会列出当前已选中的目标及其类型（`Player`, `WorldObject`, `Character`, `Scripted`, `Ambient`或 `TravelPath`）。目标始终未出现，通常意味着其提供程序组件已禁用、超出 `Max Distance`，或优先级低于其他提供程序。

### 故障排查

#### 一个 `ConvaiGazeTarget` 始终未被选中

**症状：** 该对象从未在 Gaze Editor 实时视图中显示为已选中的目标。

**原因：** 目标的 `Priority` 等于或低于其他候选目标的优先级，或者角色超出了 `Max Distance`.

**修复方法：** 将 `Priority` 调高到高于竞争目标的优先级，或增大 `Max Distance` / `Full Relevance Distance`.

**验证：** 重新打开 Gaze Editor 实时视图，确认目标名称显示为已选中的目标。

#### 高级提供程序没有任何作用

**症状：** 控制台没有警告，但行为始终未触发。

**原因：** 大多数高级提供程序都需要在父级层级中存在 `EmbodimentContext` 和 `ConvaiGazeController` ；缺少其中任一组件都会记录警告并禁用该组件。

**修复方法：** 检查控制台，查看是否有指出缺失依赖项的 `component is inert` 警告，并确认该组件位于与 `ConvaiGazeController`.

**验证：** 组件成功重新启用后，该警告不再出现。

### 后续步骤

{% 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/3e45c80fb1153e604c743a1f3a0a835d39719b0e" %}
[配置眼神接触](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/configure-eye-contact.md)
{% endcontent-ref %}

{% content-ref url="/pages/e18fef943d7f4b642c516d5b9e2c689030154ddf" %}
[Gaze 脚本参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/scripting-reference.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/targets-and-providers.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.
