> 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 标记为凝视候选项，添加这 8 个高级提供器组件以获得更丰富的目标选择行为，并从代码中注册自定义提供器。在添加后使用此页面 `ConvaiGazeController` 到角色上，当你希望它以非默认方式注意特定场景对象、其他角色或玩家时。

### 前提条件

* `ConvaiGazeController` 已添加到角色（`Convai/具身/凝视`).
* 要标记的场景对象，或提供其自身候选项的脚本。

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

添加 `ConvaiGazeTarget` (`Convai/凝视/目标`）到任何 GameObject，即可将其设为场景中每个 Convai 角色的凝视候选项。不需要场景元数据。

| 字段       | 默认          | 用途                                                              |
| -------- | ----------- | --------------------------------------------------------------- |
| `优先级`    | `5`         | 优先级层级。玩家锚点发布时为 `10`，因此默认的 `5` 在对话中会让给玩家。将其提高到高于 `10` 以超过玩家的优先级。 |
| `基础相关度`  | `0.75`      | 在……内部时的相关度 `完全相关距离`.                                            |
| `最大距离`   | `10` （米）    | 超过该距离后，目标不再作为候选项。                                               |
| `完全相关距离` | `3` （米）     | 低于该距离时，相关度达到最大值。                                                |
| `瞄准偏移`   | `(0, 0, 0)` | 从该 Transform 到眼睛实际瞄准点的本地空间偏移，例如画作顶部。                            |

{% hint style="info" %}
`ConvaiGazeTarget` 是通用标记。仅在 `WorldObjectGazeTargetProvider`，如下所述，仅当对象已经带有 `ConvaiObjectMetadata`.
{% endhint %}

### 添加高级凝视提供器

高级提供器位于 `Convai/凝视/高级/` ，可在 Add Component 菜单中找到。每个组件都是可选的——添加 `ConvaiGazeController` 会为角色赋予眼睛、头部、待机生命感、眨眼、身体转向和对话节奏，无需进一步设置；这些组件在此基础上添加更多能力。

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

`CharacterGazeTargetProvider` (`Convai/凝视/高级/角色目标`）使角色看向其他 Convai 角色，也能被其他 Convai 角色看向。每个参与角色添加一个组件；身份、对话状态以及视线点都来自该角色的具身上下文。

| 字段                  | 默认             | 用途                                                                          |
| ------------------- | -------------- | --------------------------------------------------------------------------- |
| `发布自身`              | `是`            | 将此角色注册为其他角色可注视的目标。                                                          |
| `看向他人`              | `是`            | 为其他已注册角色生成凝视候选项。                                                            |
| `优先级`               | `7`            | 介于玩家锚点（`10`）和世界对象（`5`）之间，因此在对话中玩家优先，但角色会胜过背景道具。                             |
| `说话优先级`             | `9`            | 当此角色正在说话时使用的优先级层级——高于空闲 `优先级` 层级，这样已经将注意力放在说话者上的听者不会被拉向旁观者，同时仍低于玩家锚点（`10`). |
| `最大距离`              | `12` （米）       | 超过该距离后，其他角色不再作为候选项（`0` = 无限）。                                               |
| `完全相关距离`            | `4` （米）        | 低于该距离后，其他角色处于完全相关状态。                                                        |
| `空闲瞥视相关度`           | `0.35`         | 非说话角色的相关度。说话中的角色始终是完全相关的，因此听者会转向当前发言者。                                      |
| `视线高度偏移`            | `1.6` （米）      | 其他角色瞄准的视线高度，直到该角色的头骨从绑定中解析出来。                                               |
| `启用空闲瞥视`            | `是`            | 空闲时，与附近角色偶尔交换短暂眼神。                                                          |
| `空闲瞥视间隔最小值` / `最大值` | `5` / `12` （秒） | 空闲角色间瞥视之间的间隔范围。                                                             |
| `空闲瞥视持续时间`          | `1.4` （秒）      | 一次空闲角色瞥视的持续时间。                                                              |
| `空闲瞥视投入度`           | `0.5`          | 空闲瞥视的投入程度。                                                                  |

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

`ConvaiEyePupilDriver` (`Convai/凝视/高级/眼瞳驱动器`）使用凝视模块平滑后的唤醒信号扩张角色的瞳孔。它通过复用的 `MaterialPropertyBlock` 按每个渲染器写入，因此共享材质资源永远不会被修改。

| 字段        | 默认                 | 用途                                                             |
| --------- | ------------------ | -------------------------------------------------------------- |
| `渲染器`     | 空                  | 显式指定的渲染器目标。留空以自动发现所有 `SkinnedMeshRenderer` 该角色下其材质暴露了着色器属性的对象。 |
| `着色器属性名`  | `_PupilScale`      | 要驱动的着色器浮点属性。默认使用 Reallusion RL5 角膜着色器的瞳孔缩放属性。                  |
| `最大扩张百分比` | `12` （范围 `5`–`20`) | 在完全唤醒时的最大瞳孔扩张，表示为每个渲染器基础属性值的百分比。                               |
| `反转符号`    | `否`                | 当某个绑定中属性值越大反而使瞳孔越小时，翻转扩张方向。                                    |

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

`GazeDynamicContextBridge` (`Convai/凝视/高级/动态上下文桥接`）将角色当前凝视对象镜像到 Convai 动态上下文键 `current_attention_object`，因此诸如“it”或“that”之类的代词引用会根据角色实际注视的对象来解析。

| 字段     | 默认    | 用途                |
| ------ | ----- | ----------------- |
| `参与阈值` | `0.5` | 对象被发布前所需的最低凝视投入度。 |

#### 联合注意——注意玩家在看什么

`GazeJointAttention` (`Convai/凝视/高级/联合注意`）注意玩家正在看的东西并也看向那里，然后再返回到凝视策略所规定的对象——“我看到吸引你注意力的东西”这一反应节拍。它完全建立在公开的 `GlanceAt` API 之上，因此无需更改凝视核心。

| 字段                | 默认            | 用途                          |
| ----------------- | ------------- | --------------------------- |
| `锥角度数`            | `8`           | 用于判断玩家视线射线是否指向候选对象的半锥角。     |
| `最大距离米数`          | `12`          | 候选对象可被注意到的最远玩家距离。           |
| `停留秒数`            | `0.7`         | 玩家必须持续注视某个对象多长时间后，角色才会注意到它。 |
| `瞥视持续秒数`          | `1.4`         | 看向被注意对象的瞥视持续时间。             |
| `反应延迟最小/最大秒数`     | `0.2` / `0.5` | 从注意到到瞥视之间的延迟范围。             |
| `冷却秒数`            | `10`          | 同一对象再次被注意前的按对象冷却时间。         |
| `全局最小间隔秒数`        | `4`           | 任意两次联合注意瞥视之间的最小间隔。          |
| `评估间隔秒数`          | `0.2`         | 玩家视线评估之间的间隔（默认约 5 Hz）。      |
| `发布注意力上下文`        | `否`           | 将被注意对象的名称发布到 Convai 动态上下文。  |
| `空闲时激活` / `聆听时激活` | `是` / `是`     | 联合注意处于激活状态的对话状态。            |

#### 指代性瞥视——瞥一眼被提到的对象

`GazeReferentialGlances` (`Convai/凝视/高级/指代性瞥视`）当角色自己的语句提到某个已注册世界对象时，让角色瞥向它——“看看那幅画”。它基于角色的最终转写进行匹配，并完全建立在公开的 `GlanceAt` API。

| 字段          | 默认            | 用途                  |
| ----------- | ------------- | ------------------- |
| `瞥视持续时间`    | `1.6` （秒）     | 看向被提到对象的瞥视持续时间。     |
| `冷却秒数`      | `10`          | 同一对象再次被瞥视前的按对象冷却时间。 |
| `最大提及词数`    | `4`           | 可匹配的对象名称最长词数。       |
| `最小/最大延迟秒数` | `0.3` / `0.8` | 提及与瞥视之间的延迟范围。       |

#### 玩家锚点——覆盖角色查找“玩家”的方式

`PlayerAnchorTargetProvider` (`Convai/凝视/高级/玩家锚点`）是开箱即用的“看向玩家”提供器。 `ConvaiGazeController` 当角色没有其他提供器时，会在运行时自动配置一个。可手动添加以按角色覆盖锚点——用于分屏、多人或过场动画绑定。

| 字段       | 默认                             | 用途                                                                                                                                                                         |
| -------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `优先级`    | `10`                           | 在各提供器之间比较的静态优先级层级。                                                                                                                                                         |
| `显式锚点`   | 无                              | 为空时，解析为 `Camera.main`，然后是第一个符合条件且启用的 Game 视图摄像机。                                                                                                                           |
| `视线高度偏移` | `1.6` （米）                      | 应用于显式非摄像机锚点的垂直抬升。                                                                                                                                                          |
| `瞄准模式`   | `自动`                           | `GazeAnchorAimMode` ——凝视在锚点上的瞄准位置。                                                                                                                                         |
| `面部存在方式` | `自动`                           | `GazeAnchorFacePresence` ——角色是否将锚点视为一张脸，并注视其周围（眼睛、嘴巴），而不是精确瞄准它。 `自动` 根据锚点决定：手动指定的会被视为脸，而 SDK 自行解析出的摄像机则被视为视点，并精确瞄准它。 `脸` 始终将锚点视为脸——在 VR 中是正确的，因为摄像机位于玩家双眼之间。 `点` 始终精确瞄准锚点。 |
| `本地瞄准偏移` | `(0, 0, 0)`                    | 由 `本地偏移` 模式。                                                                                                                                                               |
| `最大距离`   | `8` （米）                        | 超过该距离后，玩家不再作为候选项。                                                                                                                                                          |
| `完全相关距离` | `4` （米）                        | 低于该距离时，相关度达到最大值。                                                                                                                                                           |
| `检查视线`   | `否`                            | 要求到玩家之间有无遮挡的直线。被遮挡时，相关度会衰减，重新出现时会播放正常的获取扫视。                                                                                                                                |
| `遮挡层掩码`  | `Physics.DefaultRaycastLayers` | 在视线测试中被视为视觉遮挡的层。                                                                                                                                                           |
| `视线检查间隔` | `0.1` （秒）                      | 视线射线检测之间的节流间隔。                                                                                                                                                             |
| `视线起点高度` | `1.6` （米）                      | 视觉射线从角色根节点之上的眼线高度开始。                                                                                                                                                       |

#### 玩家注意力传感器——知道玩家何时也在看回来

`PlayerAttentionSensor` (`Convai/凝视/高级/玩家注意力传感器`）告诉角色玩家是否正在看它。默认信号是主摄像机的前向射线；XR 眼动追踪通过 `IPlayerGazeRaySource` （见 [为 XR 提供自定义玩家凝视射线](#supply-a-custom-player-gaze-ray-for-xr)）而无需任何 XR 包依赖。平滑后的信号会发布到 Convai 动态上下文键 `player_attention` (`looking_at_me` / `离开`，边沿触发）。

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

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

`WorldObjectGazeTargetProvider` (`Convai/凝视/高级/世界对象目标`）将一个已制作的 Convai 世界对象——即已经带有 `ConvaiObjectMetadata` (`RequireComponent`）——标记为环境凝视候选项。附近角色在空闲时会瞥向它，而当它赢得注意力时，动态上下文桥接会将其报告给 Convai。

| 字段       | 默认       | 用途                              |
| -------- | -------- | ------------------------------- |
| `优先级`    | `5`      | 优先级层级，保持低于玩家锚点（`10`）以便在对话中玩家获胜。 |
| `基础相关度`  | `0.75`   | 在……内部时的相关度 `完全相关距离`.            |
| `最大距离`   | `10` （米） | 超过该距离后，对象不再作为候选项。               |
| `完全相关距离` | `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` 每个认知 tick 都会运行，因此请保持实现开销低。返回 `否` （或相关度为 `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());
    }
}
```

返回 `否` 当这一帧没有可用射线时——例如追踪丢失、头显关闭——这样消费者会回退到摄像机射线。该来源按组件实例注册，而不是进程级注册，因此一个场景的适配器不会悄悄驱动另一个场景中的角色。

### 目标运动如何被过滤

每个凝视目标的瞄准点都会先经过平滑处理，然后才会被头部运动检测器看到，因此一两厘米的普通移动——比如说话角色的头部轻微晃动、手持设备上的摄像机晃动——不会被识别为移动目标，也不会触发头部重新规划。真正的不连续变化，例如镜头切换或传送，会在原始跳变而不是平滑后的跳变上被检测到，因此眼睛仍会立即跳到新位置，而不是向其滑动。

### 验证目标已被找到

进入 Play 模式并打开 `Convai > 凝视编辑器` 在选中角色时。窗口的实时视图会列出当前激活的目标及其类型（`玩家`, `世界对象`, `角色`, `脚本`, `环境`，或 `移动路径`）。一个从未出现的目标通常意味着其提供器组件已禁用、超出 `最大距离`，或者低于另一个提供器的优先级层级。

### 故障排查

#### 一个 `ConvaiGazeTarget` 从未被选中

**症状：** 该对象从未在凝视编辑器的实时视图中作为激活目标出现。

**原因：** 目标的 `优先级` 处于或低于另一候选项的层级，或者该角色位于 `最大距离`.

**解决方法：** 提高 `优先级` 到高于竞争层级，或增大 `最大距离` / `完全相关距离`.

**验证：** 重新打开凝视编辑器实时视图，并确认目标名称作为激活目标出现。

#### 高级提供者什么也不做

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

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

**解决方法：** 在控制台中检查是否有一个 `组件处于不活动状态` 指明缺失依赖项的警告，并确认该组件位于与……相同的角色层级下 `ConvaiGazeController`.

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

### 下一步

{% 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/3e45c80fb1153e604c743a1f3a0a835d39719b0e" %}
[配置眼神接触](/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 脚本参考](/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 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/targets-and-providers.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.