> 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/scripting-reference.md).

# Gaze 脚本参考

Convai Gaze 系统公共 API 的参考，包括控制器、Gaze 读取值、句柄以及目标提供器接口。

Convai Gaze 系统公共类型的完整参考。这些类型位于以下命名空间中： `Convai.Modules.Gaze.Components`, `Convai.Modules.Gaze.Core`, `Convai.Modules.Gaze.Providers`, `Convai.Domain.Embodiment.Readings`以及 `Convai.Domain.Embodiment.Semantics` ，具体命名空间已在各类型旁注明。

### `ConvaiGazeController`

`ConvaiCharacterModule<ConvaiGazeProfile>`, `MonoBehaviour` — `Convai.Modules.Gaze.Components`

菜单路径： `Convai/Embodiment/Gaze`. `DisallowMultipleComponent`, `RequireComponent(GazeAttentionRequests)`.

Convai Gaze 系统的组合根：它决定角色看向什么（目标选择）、角色在每种对话状态下对目标的关注程度（策略），并通过躯干、颈部/头部、眼睛和眼睑的求解器来表现视线。

#### 返回的结果

| 属性                                       | 类型                     | 说明                                                                                                    |
| ---------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `Current`                                | `GazeReading`          | 角色最新的视线读数，每个认知周期都会发布。                                                                                 |
| `PlayerAnchorOverride`                   | `Transform`            | 此角色视为“玩家”的 Transform。 `null` （默认）会解析为 `Camera.main`，然后是任意启用的摄像机。对于分屏、多人游戏或过场动画中的角色装置，请为此项赋值；运行时会立即生效。 |
| `EyeContactMode`                         | `GazeEyeContactMode`   | 控制眼神接触的方式。可在运行时设置；效果会平滑渐变。                                                                            |
| `AttendToSpeaker`                        | `GazeSpeakerAttention` | 角色不在自己的回合时，是否转向当前正在说话的其他对象。取值： `Off`, `Player`, `Characters`, `Anyone` （默认）。可在运行时设置。                  |
| `FocusFidelity`                          | `GazeFocusFidelity`    | 在以下模式启用时使用的精度： `EyeContactMode` 。                                                                     |
| `PlayerAnchorAimMode`                    | `GazeAnchorAimMode`    | 确定玩家锚点的对话瞄准点的方式。                                                                                      |
| `PlayerAnchorAimOffset`                  | `Vector3`              | 锚点局部瞄准偏移量，由以下模式使用： `GazeAnchorAimMode.LocalOffset`.                                                   |
| `AllowScriptedOverridesDuringExactFocus` | `bool`                 | 显式的 `GazeAt` 请求是否可以抢占当前的 `Exact` 注视。默认禁用。                                                             |
| `LockBlocksGlances`                      | `bool`                 | 眼神接触锁定生效期间，吸收注视级别的脚本请求，避免视线短暂离开玩家锚点。默认启用。                                                             |

#### 方法

| 方法                         | 签名                                                                      | 说明                                                                  |
| -------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `GazeAt`                   | `GazeHandle GazeAt(Transform target, GazeOptions options = default)`    | 使视线注视某个（会移动的）变换。如果 `null` 目标，则返回 `null`.                            |
| `GazeAt`                   | `GazeHandle GazeAt(Vector3 worldPoint, GazeOptions options = default)`  | 使视线注视世界空间中的某个点。                                                     |
| `GlanceAt`                 | `GazeHandle GlanceAt(Transform target, float durationSeconds = 1.2f)`   | 短暂瞥向某个（会移动的）变换，然后回到策略目标。如果 `null` 目标，则返回 `null`.                    |
| `GlanceAt`                 | `GazeHandle GlanceAt(Vector3 worldPoint, float durationSeconds = 1.2f)` | 短暂瞥向世界空间中的某个点。                                                      |
| `ReleaseAllScriptedGaze`   | `void ReleaseAllScriptedGaze()`                                         | 释放所有脚本控制的注视请求。                                                      |
| `RegisterTargetProvider`   | `void RegisterTargetProvider(IGazeTargetProvider provider)`             | 注册非组件提供程序（系统、网络代码、测试）。                                              |
| `UnregisterTargetProvider` | `void UnregisterTargetProvider(IGazeTargetProvider provider)`           | 取消注册通过 `RegisterTargetProvider`.                                    |
| `RefreshProviders`         | `void RefreshProviders()`                                               | 重新扫描角色层级结构中的目标提供程序。                                                 |
| `RefreshEyeBackend`        | `void RefreshEyeBackend()`                                              | 根据配置文件重新解析眼部输出后端（骨骼或 `EyeLook*` 混合形状）。运行时更改 `EyeActuationMode` 后调用。 |
| `CaptureCapabilities`      | `void CaptureCapabilities(List<GazeCapabilityInfo> results)`            | 将 `results` 填入所有可选注视功能及角色当前是否具备这些功能。                                |
| `CaptureSnapshot`          | `void CaptureSnapshot(GazeSnapshot snapshot)`                           | 将 `snapshot` 以及实时注视状态。                                              |
| `CaptureSnapshot`          | `GazeSnapshot CaptureSnapshot()`                                        | 便捷重载，用于分配并填充一个新的 `GazeSnapshot`.                                    |
| `TryGetPlayerAnchor`       | `bool TryGetPlayerAnchor(out Transform anchor)`                         | 解析此角色当前视为玩家的变换。若没有锚点、没有提供程序，且没有可用作后备的摄像机，则返回 `false` 。              |

#### 事件

| 事件              | 签名                               | 在以下情况触发：                 |
| --------------- | -------------------------------- | ------------------------ |
| `TargetChanged` | `event Action<GazeTargetChange>` | 每次注视目标发生切换时触发，与跟踪日志保持一致。 |

### `GazeReading`

只读结构体 — `Convai.Domain.Embodiment.Readings`

角色当前注视决策的不可变快照，通过以下成员公开： `ConvaiGazeController.Current`.

| 属性                    | 类型               | 说明                                                                         |
| --------------------- | ---------------- | -------------------------------------------------------------------------- |
| `TargetKind`          | `GazeTargetKind` | 当前目标的来源分类。                                                                 |
| `Target`              | `Transform`      | 正在注视的可选变换。即使已锁定目标，也可能为 `null` （例如目标是没有关联变换的世界空间点）；数学计算时优先使用 `WorldPoint` 。 |
| `WorldPoint`          | `Vector3`        | 注视方向所指向的平滑世界空间点。                                                           |
| `Engagement`          | `float`          | 在以下范围内的有效参与度 `[0, 1]`：眼睛、头部和身体在当前帧对目标的关注程度。                                |
| `IsAverting`          | `bool`           | `在刻意移开视线、打破眼神接触的回避动作期间为` true                                              |
| `目标仍由角色持有；之后会恢复眼神接触。` | `int`            | 稳定 ID；每当注视转向不同目标时递增，可用于检测目标切换，而无需比较变换引用。                                   |

`GazeReading.None` 表示未参与注视的读数（`GazeTargetKind.None`、无目标、参与度为零）。

### `GazeTargetChange`

只读结构体 — `Convai.Modules.Gaze.Core.Diagnostics`

用于 `ConvaiGazeController.TargetChanged`事件的负载，描述一次注视目标切换。

| 属性         | 类型               | 说明                             |
| ---------- | ---------------- | ------------------------------ |
| `FromKind` | `GazeTargetKind` | 先前目标的类型。                       |
| `ToKind`   | `GazeTargetKind` | 新目标的类型。                        |
| `FromName` | `string`         | 上一个目标的显示名称（`"-"` 如果没有则为 null）。 |
| `ToName`   | `string`         | 新目标的显示名称（`"-"` 如果没有则为 null）。   |
| `Reason`   | `string`         | 此次更改原因的易读说明。                   |
| `Time`     | `float`          | 更改发生时的 `Time.time` 值。          |

### `GazeHandle`

密封类 — `Convai.Modules.Gaze.Components`

单个脚本化注视请求的实时句柄，由 `GazeAt` 和 `GlanceAt`返回。所有操作均具幂等性且可安全取消。

#### 返回的结果

| 属性           | 类型            | 说明                                             |
| ------------ | ------------- | ---------------------------------------------- |
| `TargetName` | `string`      | 所请求目标的显示名称，用于诊断。                               |
| `IsActive`   | `bool`        | 请求是否仍有效（尚未释放、过期或因销毁而失效）。                       |
| `Settled`    | `Task<bool>`  | 当注视对准目标后完成并返回 `true` ；如果请求在对准前结束，则返回 `false` 。 |
| `Completion` | `Task`        | 请求结束时完成 — 持续时间已到、请求已释放或目标已丢失。                  |
| `Outcome`    | `GazeOutcome` | 请求的结果。 `Taken` 直到另有情况发生。                       |

#### 方法

| 方法        | 签名               | 说明                        |
| --------- | ---------------- | ------------------------- |
| `Release` | `void Release()` | 结束请求。可安全地多次调用，也可在取消回调中调用。 |

### `GazeOptions`

结构体 — `Convai.Modules.Gaze.Components`

脚本化 `GazeAt` 请求的选项。字段默认值和用法请参阅 [脚本化注视](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/scripted-gaze.md) 。

| 字段              | 类型      | 说明                                                     |
| --------------- | ------- | ------------------------------------------------------ |
| `Priority`      | `int`   | 脚本化请求之间的优先级（数值越高优先级越高；相同时以最近请求者优先）。脚本化请求始终优先于自动目标。     |
| `HoldSeconds`   | `float` | 请求的保持时长（秒）。取值为 `<= 0` 保持直到 `GazeHandle.Release()` 被调用。 |
| `Engagement`    | `float` | 中的互动覆盖设置 `(0, 1]`。值 `<= 0` 使用当前对话状态的互动设置。              |
| `AllowBodyTurn` | `bool`  | 此请求是否可以触发角色全身转向目标。                                     |

### `GazeOutcome`

枚举 — `Convai.Modules.Gaze.Components`

注视请求未能到达目标的原因，或确认已到达目标。

| 值                       | 整数  | 说明                                                         |
| ----------------------- | --- | ---------------------------------------------------------- |
| `Taken`                 | `0` | 注视请求仍处于活动状态，或已注视到目标。                                       |
| `Interrupted`           | `1` | 注视到达目标前，请求便已结束——被释放、过期、取代，或其目标已被销毁。                        |
| `HeldEyeContactInstead` | `2` | 角色有意保持眼神接触，因此将扫视并入眼神接触，而不是执行扫视，因为 `LockBlocksGlances` 已启用。 |

### `GazeEyeContactMode`

枚举 — `Convai.Modules.Gaze.Components`

ConvaiGazeController `如何` 管理角色与其玩家锚点之间的眼神接触。

| 值                  | 整数  | 说明                                               |
| ------------------ | --- | ------------------------------------------------ |
| `Natural`          | `0` | 配置文件中针对各个`DialogueState` 的策略表决定互动、回避和头部参与方式。默认值。 |
| `ConversationLock` | `1` | 在所有对话状态（非`Idle`）下，始终完全注视玩家锚点； `Idle` 保留配置的表格行。   |
| `AlwaysLock`       | `2` | 在所有状态下（包括 `Idle` ）始终完全注视玩家锚点。                    |
| `SpeakingFocus`    | `3` | 仅当角色正在说话时，才注视玩家锚点。                               |

### `GazeFocusFidelity`

枚举 — `Convai.Modules.Gaze.Components`

活动眼神接触模式对玩家锚点的保持精度。

| 值        | 整数  | 说明                                            |
| -------- | --- | --------------------------------------------- |
| `Social` | `0` | 在保持玩家为对话目标的同时，保留细微的注视移动和具有社交意义的头部动作。建议用于对话角色。 |
| `Exact`  | `1` | 焦点激活时，抑制有意的移开视线和注视偏移。眨眼、眼睑、瞳孔、辐辏和身体转向仍可正常进行。  |

### `GazeAnchorAimMode`

枚举 — `Convai.Modules.Gaze.Components`

如何根据锚点变换推导对话焦点。

| 值                | 整数  | 说明                                        |
| ---------------- | --- | ----------------------------------------- |
| `Auto`           | `0` | 使用摄像机的精确位置；对于其他锚点，则应用常规的视线高度偏移。           |
| `ExactTransform` | `1` | 使用锚点的精确世界位置。                              |
| `LocalOffset`    | `2` | 将 `PlayerAnchorAimOffset` 从锚点局部空间变换到世界空间。 |

### `GazeBodyTurnStyle`

枚举 — `Convai.Modules.Gaze.Components`

当角色仅靠头部和眼睛无法注视某物时，身体的转向方式。

| 值                | 整数  | 说明                                                            |
| ---------------- | --- | ------------------------------------------------------------- |
| `SteppingTurn`   | `0` | 播放角色自身的转身动画，让双脚随之迈步。需要动画集和身体动画模块中包含转身动画片段；如果缺少其中任一项，则回退为平滑旋转。 |
| `SmoothRotation` | `1` | 按注视配置文件设置的速度直接旋转角色。无需动画片段或动画模块。                               |

### `GazeSpeakerAttention`

枚举 — `Convai.Modules.Gaze.Components`

角色是否转向房间里当前正在说话的人，以及转向谁。仅当角色不处于自己的回合时生效，因此不会与角色自身的对话注视相冲突。通过 `ConvaiGazeController.AttendToSpeaker`设置；注视的方式和限制可在配置文件的 [对话注意力](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/profile-reference.md#conversation-attention) 组。

| 值            | 整数  | 说明                                                |
| ------------ | --- | ------------------------------------------------- |
| `Off`        | `0` | 绝不要跟随其他参与者的回合。                                    |
| `Player`     | `1` | 玩家说话时转向玩家；忽略其他角色的回合。                              |
| `Characters` | `2` | 其他角色说话时转向该角色；绝不转向玩家。                              |
| `Anyone`     | `3` | 转向当前发言者，无论是玩家还是角色（默认）。如果玩家插话打断正在说话的角色，玩家会立即获得发言权。 |

### `GazeTargetKind`

枚举 — `Convai.Domain.Embodiment.Semantics`

对角色当前注视目标的来源进行分类。

| 值             | 整数  | 说明                              |
| ------------- | --- | ------------------------------- |
| `None`        | `0` | 无目标 — 注视系统完全停用。                 |
| `Ambient`     | `1` | 环境空闲探索 — 一个没有场景含义的合成注视点。        |
| `Player`      | `2` | 玩家锚点（摄像机或显式指定的玩家变换）。            |
| `WorldObject` | `3` | 由世界对象注视目标提供程序提供的场景对象。           |
| `Scripted`    | `4` | 脚本化的 `GazeAt` 请求（API 调用或动作执行器）。 |
| `Character`   | `5` | 由角色间注视提供程序提供的另一个 Convai 角色。     |
| `TravelPath`  | `6` | 角色移动时前方的路径 — 沿其行进方向的一个点，而非场景对象。 |

### `IGazeTargetProvider`

接口 — `Convai.Modules.Gaze.Providers`

向 `ConvaiGazeController`提供注视目标候选项。角色层级中的提供程序会自动发现；其他提供程序可在运行时通过 `RegisterTargetProvider`注册。实现必须轻量 — `TryGetCandidate` 会在每次认知周期中运行。

```csharp
public interface IGazeTargetProvider
{
    bool TryGetCandidate(Transform characterRoot, out GazeTargetCandidate candidate);
}
```

`GazeTargetCandidate` 是一个只读结构体，包含 `Kind` (`GazeTargetKind`), `Priority` (`int`，优先级较高的层级始终胜出）、 `Relevance` (`float`, `0`–`1`, `0` （移除候选项）、 `Target` (`Transform`，可选）， `WorldPoint` (`Vector3`), `DebugName` (`string`），以及 `HasFace` (`bool`，默认值为 `false`）——该位置是否有面部 `WorldPoint` 值得环顾，而不是精确瞄准。未设置此项的提供者会进行精确瞄准；仅当该点确实是某个人的面部时，才将其设为 `true` 。

### `GazeCapabilityInfo`

只读结构体—— `Convai.Modules.Gaze.Core`

一项可选的注视能力：用通俗语言说明其功能，以及提供该能力的组件。由 `ConvaiGazeController.CaptureCapabilities`.

| 属性             | 类型                 | 说明                         |
| -------------- | ------------------ | -------------------------- |
| `Id`           | `GazeCapabilityId` | 稳定标识符。                     |
| `DisplayName`  | `string`           | 面向用户显示的名称——绝不是组件的类名。       |
| `Description`  | `string`           | 用一句话说明启用此项会带来什么变化。         |
| `ProviderType` | `Type`             | 提供此能力的 `MonoBehaviour` 类型。 |
| `IsPresent`    | `bool`             | 当前此角色上是否存在已启用的提供者。         |

`GazeCapabilityId` 取值： `PlayerAttention` (`0`), `AttentionGrounding` (`1`), `ReferentialGlances` (`2`), `JointAttention` (`3`), `CharacterGaze` (`4`), `PupilResponse` (`5`）——每个高级提供者各对应一个，详见 [注视目标与提供者](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/targets-and-providers.md).

### `GazeSnapshot`

密封类—— `Convai.Modules.Gaze.Core.Diagnostics`

可变且可重复使用的完整注视运行时状态捕获对象，供 HUD 和测试使用。只需分配一次，然后通过 `ConvaiGazeController.CaptureSnapshot(GazeSnapshot)`.

| 字段                                 | 类型                     | 说明                                                                                                               |
| ---------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `Reading`                          | `GazeReading`          | 捕获时已发布的注视读数。                                                                                                     |
| `TargetKind`                       | `GazeTargetKind`       | 当前正在注视的目标类型，或者 `None` （未注视时）。                                                                                    |
| `TargetName`                       | `string`               | 当前正在注视的目标的诊断名称，或者 `"-"` （未注视时）。                                                                                  |
| `DialogueState`                    | `DialogueState`        | 策略引擎在此帧处理的对话状态。                                                                                                  |
| `PolicyEngagement`                 | `float`                | 应用目标锁定前平滑处理后的策略参与度。                                                                                              |
| `TorsoAngles`                      | `Vector2`              | 求解得到的躯干偏航/俯仰角贡献值，单位为度。                                                                                           |
| `HeadAngles`                       | `Vector2`              | 求解得到的头部（颈部+头部）偏航/俯仰角贡献值，单位为度。                                                                                    |
| `HeadRollDegrees`                  | `float`                | 此帧写入头骨骼的滚转角。仅在头部手势要求倾斜时非零。                                                                                       |
| `TargetErrorAngles`                | `Vector2`              | 此帧仍需完成的完整视线偏移量，尚未计入任何执行器分担的部分。未注视时为零。                                                                            |
| `LeftEyeAngles` / `RightEyeAngles` | `Vector2`              | 求解得到的眼球偏航/俯仰角，单位为度，采用眼眶坐标系。                                                                                      |
| `EyePhase`                         | `string`               | 当前注视/扫视阶段标签（`"Fixating"`, `"Saccade"`, `"Pursuit"`等）。                                                            |
| `ContactErrorDegrees`              | `float`                | 眼睛瞄准方向与视线目标实际位置之间的实时角度误差。 `float.NaN` （未注视时）。                                                                    |
| `AimErrorDegrees`                  | `float`                | 眼睛实际指向与目标之间的合成角度误差，其中包含求解器自身目标之后应用的所有偏移。 `float.NaN` （未注视时）。                                                     |
| `TargetHasFace`                    | `bool`                 | 当前目标是否为某人的脸；若是，则启用面部扫描。                                                                                          |
| `LookNature`                       | `string`               | 角色当前注视的意图—— `"Glance"`, `"Attention"`, `"Reflex"`.                                                               |
| `FocusActive`                      | `bool`                 | 产品级对话焦点范围是否处于活动状态。                                                                                               |
| `FocusFidelity`                    | `GazeFocusFidelity`    | 当 `FocusActive` 为 true 时应用的精度约定。                                                                                 |
| `FocusDegraded`                    | `bool`                 | 当锚点不可用时，焦点是否保留最后已知位置。                                                                                            |
| `ContactUsesBoneBackend`           | `bool`                 | `true` 当活动的眼睛后端驱动骨骼时； `false` 用于标识混合形状后端。                                                                        |
| `BlinkWeight`                      | `float`                | 归一化眨眼权重（`0` 睁开， `1` 闭合）。                                                                                         |
| `IsReorienting`                    | `bool`                 | 身体当前是否正在重新定向。                                                                                                    |
| `IsNodding`                        | `bool`                 | 是否正在播放表示倾听的附和点头动作。                                                                                               |
| `PlayerAttention`                  | `float`                | 由 `PlayerAttentionSensor`提供的“玩家是否在看我”的平滑 0–1 估算值，或 `-1` 没有传感器时的值。                                                |
| `PlayerLooking`                    | `bool`                 | 传感器经过迟滞处理后的分类结果。仅当 `PlayerAttention` 非负时才有意义。                                                                    |
| `AttendingSpeaker`                 | `bool`                 | 角色当前是否正在关注其他人的发言轮次——即“所有人都看着说话的人”的行为。 `false` 角色处于自己的发言轮次时、 `AttendToSpeaker` 为 `Off`时，以及没有任何可关注对象发言时，值均为 false。 |
| `SpeakerAttention`                 | `string`               | 用一行描述对话注意力当前的实际状态——正在关注谁，或哪个条件导致说话者被忽略（`"too far"`, `"behind them"`, `"its own turn"`).                          |
| `LodEnabled`                       | `bool`                 | 此角色是否启用了群体 LOD。                                                                                                  |
| `LodFar`                           | `bool`                 | 角色是否处于降低更新频率的远距离 LOD 区间。                                                                                         |
| `LodExpressionSkipped`             | `bool`                 | 本帧是否跳过求解器阶段（屏幕外 LOD）。                                                                                            |
| `RecentTrace`                      | `List<GazeTraceEntry>` | 从轨迹环形缓冲区复制的近期转换日志，按时间从早到晚排列。                                                                                     |

#### 头部姿态贡献者跟踪信息

这些字段详细说明了本帧中头部因何发生移动。 `HeadAngles` 和 `TorsoAngles` 是读者通常需要查看的字段；此组字段用于诊断特定的头部姿态缺陷——即 `TargetErrorAngles` 与下方执行器之和之间的残余偏差，其中一个贡献量有所回退，另一个则被静默钳制。请结合起来查看，不要单独解读。

| 字段                        | 类型        | 说明                                               |
| ------------------------- | --------- | ------------------------------------------------ |
| `HeadGoal`                | `Vector2` | 执行器阶梯在本帧位移中的头部偏航/俯仰目标值，单位为度。                     |
| `HeadShiftActive`         | `bool`    | 头部是否正在朝新的目标执行有轨迹的运动（弹道式移动正在进行中）。                 |
| `StabilizationOffset`     | `Vector2` | 稳定反射应用的偏移量（单位：度），用于抵消动画自身造成的头部偏移。                |
| `AnimatedDeviation`       | `Vector2` | 动画自身测得的头部偏移（单位：度），稳定反射正对其进行抵消。                   |
| `GestureOffset`           | `Vector2` | 合成的头部手势偏移量（单位：度）——包括反馈点头、外部程序指令和让出发言权时的低头动作。     |
| `AversionHeadOffset`      | `Vector2` | 回避动作中头部所占的偏移量（单位：度）；这是经过眼神接触锁定和轮流发言缩放后，输入头部求解的值。 |
| `AversionEyeOffset`       | `Vector2` | 回避动作中眼睛所占的偏移量（单位：度），即输入眼睛求解的值。                   |
| `MicroOffset`             | `Vector2` | 合成的眼部微动作偏移量（单位：度）——包括微扫视停留、面部扫描和到达后稳定时的俯仰。       |
| `ChainLagOffset`          | `Vector2` | 此帧颈部/头部链的滞后重分配到头骨的角度——即重叠动作的跟随和稳定过程。             |
| `AppliedHeadDeltaDegrees` | `float`   | 头骨在此帧与上一帧之间的世界旋转角度变化（单位：度），在求解器写入骨骼后测量。          |
| `TargetPointDeltaMeters`  | `float`   | 当前生效的指令所指向的世界坐标点自上次表情更新以来移动的距离（单位：米）。            |
| `目标仍由角色持有；之后会恢复眼神接触。`     | `int`     | 捕获时该指令的生成 ID；每次重新指定目标时都会递增，因此探针可以区分贡献项变化与新的注视。   |

#### 方法

| 方法      | 签名             | 说明                |
| ------- | -------------- | ----------------- |
| `Clear` | `void Clear()` | 将所有字段重置为未启用时的默认值。 |

### 相关参考

{% content-ref url="/pages/fab0d9cdf9524b6f370dae71380fef0d847f60e9" %}
[Gaze 配置文件参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/profile-reference.md)
{% endcontent-ref %}

{% 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 %}


---

# 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/scripting-reference.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.
