> 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/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/scripting-reference.md). # Gaze scripting reference Reference for the Convai Gaze system's public API, including the controller, gaze readings, handles, and the target provider interface. Complete reference for the public types in the Convai Gaze system. Types live in the `Convai.Modules.Gaze.Components`, `Convai.Modules.Gaze.Core`, `Convai.Modules.Gaze.Providers`, `Convai.Domain.Embodiment.Readings`, and `Convai.Domain.Embodiment.Semantics` namespaces, as noted per type. ### `ConvaiGazeController` `ConvaiCharacterModule`, `MonoBehaviour` — `Convai.Modules.Gaze.Components` Menu path: `Convai/Embodiment/Gaze`. `DisallowMultipleComponent`, `RequireComponent(GazeAttentionRequests)`. The Convai Gaze system's composition root: it decides what the character looks at (targeting), how strongly each dialogue state commits to it (policy), and articulates the look across torso, neck/head, eyes, and eyelids (solvers). #### Properties | Property | Type | Description | | ---------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Current` | `GazeReading` | The character's latest gaze reading, published every cognition tick. | | `PlayerAnchorOverride` | `Transform` | The transform this character treats as "the player". `null` (default) resolves to `Camera.main`, then any enabled camera. Assign for split-screen, multiplayer, or cutscene rigs; applies immediately at runtime. | | `EyeContactMode` | `GazeEyeContactMode` | How eye contact is governed. Settable at runtime; ramps in smoothly. | | `AttendToSpeaker` | `GazeSpeakerAttention` | Whether the character turns to whoever else is currently speaking while it is not in its own turn. Values: `Off`, `Player`, `Characters`, `Anyone` (default). Settable at runtime. | | `FocusFidelity` | `GazeFocusFidelity` | Precision used while `EyeContactMode` is active. | | `PlayerAnchorAimMode` | `GazeAnchorAimMode` | How the player anchor's conversational aim point is derived. | | `PlayerAnchorAimOffset` | `Vector3` | Anchor-local aim offset used by `GazeAnchorAimMode.LocalOffset`. | | `AllowScriptedOverridesDuringExactFocus` | `bool` | Whether explicit `GazeAt` requests may preempt an active `Exact` focus. Disabled by default. | | `LockBlocksGlances` | `bool` | While an eye-contact lock is in force, absorbs glance-tier scripted requests so nothing briefly pulls gaze off the player anchor. On by default. | #### Methods | Method | Signature | Description | | -------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GazeAt` | `GazeHandle GazeAt(Transform target, GazeOptions options = default)` | Directs gaze at a (moving) transform. A `null` target returns `null`. | | `GazeAt` | `GazeHandle GazeAt(Vector3 worldPoint, GazeOptions options = default)` | Directs gaze at a world-space point. | | `GlanceAt` | `GazeHandle GlanceAt(Transform target, float durationSeconds = 1.2f)` | Glances at a (moving) transform briefly, then returns to the policy target. A `null` target returns `null`. | | `GlanceAt` | `GazeHandle GlanceAt(Vector3 worldPoint, float durationSeconds = 1.2f)` | Glances at a world-space point briefly. | | `ReleaseAllScriptedGaze` | `void ReleaseAllScriptedGaze()` | Releases every scripted gaze request. | | `RegisterTargetProvider` | `void RegisterTargetProvider(IGazeTargetProvider provider)` | Registers a non-component provider (systems, netcode, tests). | | `UnregisterTargetProvider` | `void UnregisterTargetProvider(IGazeTargetProvider provider)` | Unregisters a provider added through `RegisterTargetProvider`. | | `RefreshProviders` | `void RefreshProviders()` | Rescans the character hierarchy for target providers. | | `RefreshEyeBackend` | `void RefreshEyeBackend()` | Re-resolves the eye output backend (bones vs. `EyeLook*` blendshapes) from the profile. Call after changing `EyeActuationMode` at runtime. | | `CaptureCapabilities` | `void CaptureCapabilities(List results)` | Fills `results` with every optional gaze capability and whether this character currently has it. | | `CaptureSnapshot` | `void CaptureSnapshot(GazeSnapshot snapshot)` | Fills `snapshot` with the live gaze state. | | `CaptureSnapshot` | `GazeSnapshot CaptureSnapshot()` | Allocating convenience overload that creates and fills a new `GazeSnapshot`. | | `TryGetPlayerAnchor` | `bool TryGetPlayerAnchor(out Transform anchor)` | Resolves the transform this character currently treats as the player. Returns `false` when there is no anchor, no provider, and no camera to fall back on. | #### Events | Event | Signature | Raised when | | --------------- | -------------------------------- | ----------------------------------------------------------------- | | `TargetChanged` | `event Action` | Raised for every gaze target transition, mirroring the trace log. | ### `GazeReading` Readonly struct — `Convai.Domain.Embodiment.Readings` Immutable snapshot of the character's current gaze decision, exposed through `ConvaiGazeController.Current`. | Property | Type | Description | | -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TargetKind` | `GazeTargetKind` | Source classification of the current target. | | `Target` | `Transform` | Optional transform being gazed at. May be `null` even when a target is engaged (a world-space point without a backing transform); prefer `WorldPoint` for math. | | `WorldPoint` | `Vector3` | Smoothed world-space point the gaze is directed toward. | | `Engagement` | `float` | Effective engagement in `[0, 1]`: how strongly the eyes/head/body commit to the target this frame. | | `IsAverting` | `bool` | `true` while an aversion beat has deliberately broken eye contact. The target is still owned; contact resumes after. | | `GenerationId` | `int` | Stable ID that increments whenever gaze moves to a different target, for detecting re-targets without comparing transform references. | `GazeReading.None` is the disengaged reading (`GazeTargetKind.None`, no target, zero engagement). ### `GazeTargetChange` Readonly struct — `Convai.Modules.Gaze.Core.Diagnostics` Event payload for `ConvaiGazeController.TargetChanged`, describing one gaze target transition. | Property | Type | Description | | ---------- | ---------------- | ------------------------------------------------------ | | `FromKind` | `GazeTargetKind` | Kind of the previous target. | | `ToKind` | `GazeTargetKind` | Kind of the new target. | | `FromName` | `string` | Display name of the previous target (`"-"` when none). | | `ToName` | `string` | Display name of the new target (`"-"` when none). | | `Reason` | `string` | Human-readable reason for the change. | | `Time` | `float` | Value of `Time.time` when the change happened. | ### `GazeHandle` Sealed class — `Convai.Modules.Gaze.Components` Live handle for one scripted gaze request, returned by `GazeAt` and `GlanceAt`. All operations are idempotent and cancellation-safe. #### Properties | Property | Type | Description | | ------------ | ------------- | -------------------------------------------------------------------------------------------------------- | | `TargetName` | `string` | Display name of the requested target, for diagnostics. | | `IsActive` | `bool` | Whether the request is still live (not released, expired, or superseded by destroy). | | `Settled` | `Task` | Completes `true` once gaze is aligned on the target, or `false` when the request ended before alignment. | | `Completion` | `Task` | Completes when the request ends — hold elapsed, released, or target lost. | | `Outcome` | `GazeOutcome` | What became of the request. `Taken` until something says otherwise. | #### Methods | Method | Signature | Description | | --------- | ---------------- | ------------------------------------------------------------------------------ | | `Release` | `void Release()` | Ends the request. Safe to call multiple times and from cancellation callbacks. | ### `GazeOptions` Struct — `Convai.Modules.Gaze.Components` Options for a scripted `GazeAt` request. See [Scripted gaze](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/scripted-gaze.md) for field defaults and usage. | Field | Type | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | `Priority` | `int` | Priority among scripted requests (higher wins; recency breaks ties). Scripted requests always outrank automatic targets. | | `HoldSeconds` | `float` | Hold duration in seconds from the request. Values `<= 0` hold until `GazeHandle.Release()` is called. | | `Engagement` | `float` | Engagement override in `(0, 1]`. Values `<= 0` use the current dialogue state's engagement. | | `AllowBodyTurn` | `bool` | Whether this request may trigger a full-body turn toward the target. | ### `GazeOutcome` Enum — `Convai.Modules.Gaze.Components` Why a gaze request never reached its target, or confirmation that it did. | Value | Integer | Description | | ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `Taken` | `0` | The gaze request is live, or it arrived on its target. | | `Interrupted` | `1` | The request ended before gaze arrived — released, expired, superseded, or its target was destroyed. | | `HeldEyeContactInstead` | `2` | The character deliberately held eye contact and the glance was folded into it rather than taken, because `LockBlocksGlances` is on. | ### `GazeEyeContactMode` Enum — `Convai.Modules.Gaze.Components` How `ConvaiGazeController` governs eye contact with its player anchor. | Value | Integer | Description | | ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------- | | `Natural` | `0` | The profile's per-`DialogueState` policy table drives engagement, aversion, and head participation. Default. | | `ConversationLock` | `1` | Full commitment to the player anchor in every conversational (non-`Idle`) state; `Idle` keeps the authored table row. | | `AlwaysLock` | `2` | Full commitment to the player anchor in every state, `Idle` included. | | `SpeakingFocus` | `3` | Commits to the player anchor only while the character is producing speech. | ### `GazeFocusFidelity` Enum — `Convai.Modules.Gaze.Components` How precisely an active eye-contact mode holds its player anchor. | Value | Integer | Description | | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Social` | `0` | Preserves small fixation motion and socially useful head gestures while keeping the player as the conversational target. Recommended for dialogue characters. | | `Exact` | `1` | Suppresses intentional look-aways and fixation offsets while focus is active. Blinks, eyelids, pupils, vergence, and body turns remain available. | ### `GazeAnchorAimMode` Enum — `Convai.Modules.Gaze.Components` How the conversational focus point is derived from its anchor transform. | Value | Integer | Description | | ---------------- | ------- | ------------------------------------------------------------------------------------------- | | `Auto` | `0` | Uses a camera's exact position and applies the conventional eye-line lift to other anchors. | | `ExactTransform` | `1` | Uses the anchor's exact world position. | | `LocalOffset` | `2` | Transforms `PlayerAnchorAimOffset` from anchor-local to world space. | ### `GazeBodyTurnStyle` Enum — `Convai.Modules.Gaze.Components` How a character turns its body when it looks at something it cannot reach with head and eyes alone. | Value | Integer | Description | | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SteppingTurn` | `0` | Plays the character's own turn animation, so the feet step round. Needs turn clips in the Animation Set and the Body Animation module; falls back to smooth rotation without either. | | `SmoothRotation` | `1` | Rotates the character directly, at the speed the gaze profile sets. Needs no clips and no animation module. | ### `GazeSpeakerAttention` Enum — `Convai.Modules.Gaze.Components` Whether a character turns to whoever is currently speaking in the room, and to whom. Applies only while the character is not in its own turn, so it never competes with the character's own conversational gaze. Set through `ConvaiGazeController.AttendToSpeaker`; the manner and limits of the look are tuned in the profile's [Conversation attention](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/profile-reference.md#conversation-attention) group. | Value | Integer | Description | | ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `Off` | `0` | Never follow another participant's turn. | | `Player` | `1` | Turn to the player while the player is speaking; ignore other characters' turns. | | `Characters` | `2` | Turn to another character while that character is speaking; never to the player. | | `Anyone` | `3` | Turn to whoever holds the floor, player or character (default). A player barging in over a speaking character takes the floor immediately. | ### `GazeTargetKind` Enum — `Convai.Domain.Embodiment.Semantics` Classifies where the character's current gaze target came from. | Value | Integer | Description | | ------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `None` | `0` | No target — the gaze system is fully disengaged. | | `Ambient` | `1` | Ambient idle exploration — a synthetic fixation point with no scene meaning. | | `Player` | `2` | The player anchor (camera or explicit player transform). | | `WorldObject` | `3` | A scene object surfaced by a world-object gaze target provider. | | `Scripted` | `4` | A scripted `GazeAt` request (API call or action executor). | | `Character` | `5` | Another Convai character, surfaced by a character-to-character gaze provider. | | `TravelPath` | `6` | The path ahead while the character is traveling — a point along its direction of travel, not a scene object. | ### `IGazeTargetProvider` Interface — `Convai.Modules.Gaze.Providers` Supplies gaze target candidates to `ConvaiGazeController`. Providers on the character hierarchy are discovered automatically; additional providers register at runtime through `RegisterTargetProvider`. Implementations must be cheap — `TryGetCandidate` runs every cognition tick. ```csharp public interface IGazeTargetProvider { bool TryGetCandidate(Transform characterRoot, out GazeTargetCandidate candidate); } ``` `GazeTargetCandidate` is a readonly struct carrying `Kind` (`GazeTargetKind`), `Priority` (`int`, higher tiers always win), `Relevance` (`float`, `0`–`1`, `0` removes the candidate), `Target` (`Transform`, optional), `WorldPoint` (`Vector3`), `DebugName` (`string`), and `HasFace` (`bool`, default `false`) — whether there is a face at `WorldPoint` worth looking around rather than aiming at exactly. A provider that does not set it gets exact aim; set it `true` only when the point really is somebody's face. ### `GazeCapabilityInfo` Readonly struct — `Convai.Modules.Gaze.Core` One optional gaze capability: what it does in plain English, and which component provides it. Filled by `ConvaiGazeController.CaptureCapabilities`. | Property | Type | Description | | -------------- | ------------------ | --------------------------------------------------------------- | | `Id` | `GazeCapabilityId` | Stable identifier. | | `DisplayName` | `string` | What a user should see — never the component's class name. | | `Description` | `string` | One sentence explaining what turning it on changes. | | `ProviderType` | `Type` | The `MonoBehaviour` type that provides this capability. | | `IsPresent` | `bool` | Whether an enabled provider exists on this character right now. | `GazeCapabilityId` values: `PlayerAttention` (`0`), `AttentionGrounding` (`1`), `ReferentialGlances` (`2`), `JointAttention` (`3`), `CharacterGaze` (`4`), `PupilResponse` (`5`) — one per advanced provider described in [Gaze targets and providers](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/targets-and-providers.md). ### `GazeSnapshot` Sealed class — `Convai.Modules.Gaze.Core.Diagnostics` Mutable, reusable capture of the full gaze runtime state for HUDs and tests. Allocate once and refill through `ConvaiGazeController.CaptureSnapshot(GazeSnapshot)`. | Field | Type | Description | | ---------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Reading` | `GazeReading` | The published gaze reading at capture time. | | `TargetKind` | `GazeTargetKind` | Kind of the currently engaged target, or `None` when disengaged. | | `TargetName` | `string` | Diagnostic name of the currently engaged target, or `"-"` when disengaged. | | `DialogueState` | `DialogueState` | Dialogue state the policy engine acted on this frame. | | `PolicyEngagement` | `float` | Smoothed policy engagement before target commitment is applied. | | `TorsoAngles` | `Vector2` | Solved torso yaw/pitch contribution in degrees. | | `HeadAngles` | `Vector2` | Solved head (neck+head) yaw/pitch contribution in degrees. | | `HeadRollDegrees` | `float` | Roll written to the head bone this frame. Non-zero only while a head gesture asks for a tilt. | | `TargetErrorAngles` | `Vector2` | The full gaze shift still required this frame, before any actuator takes its share. Zero while disengaged. | | `LeftEyeAngles` / `RightEyeAngles` | `Vector2` | Solved eye yaw/pitch in degrees, orbit space. | | `EyePhase` | `string` | Current fixation/saccade phase label (`"Fixating"`, `"Saccade"`, `"Pursuit"`, and similar). | | `ContactErrorDegrees` | `float` | Live angular error between where the eyes aim and where the gaze target actually is. `float.NaN` while disengaged. | | `AimErrorDegrees` | `float` | Composed angular error between where the eyes actually point and the target, including every offset applied after the solver's own goal. `float.NaN` while disengaged. | | `TargetHasFace` | `bool` | Whether the current target is somebody's face, so face scanning applies. | | `LookNature` | `string` | What the character means by the current look — `"Glance"`, `"Attention"`, `"Reflex"`. | | `FocusActive` | `bool` | Whether a product-level conversational focus scope is active. | | `FocusFidelity` | `GazeFocusFidelity` | Precision contract applied while `FocusActive` is true. | | `FocusDegraded` | `bool` | Whether focus is retaining a last-known point because its anchor is unavailable. | | `ContactUsesBoneBackend` | `bool` | `true` when the active eye backend drives bones; `false` identifies the blendshape backend. | | `BlinkWeight` | `float` | Normalized blink weight (`0` open, `1` closed). | | `IsReorienting` | `bool` | Whether a body reorientation is currently in flight. | | `IsNodding` | `bool` | Whether a listening backchannel nod is currently playing. | | `PlayerAttention` | `float` | Smoothed 0–1 "is the player looking at me" estimate from a `PlayerAttentionSensor`, or `-1` when no sensor is present. | | `PlayerLooking` | `bool` | The sensor's post-hysteresis classification. Only meaningful while `PlayerAttention` is not negative. | | `AttendingSpeaker` | `bool` | Whether the character is currently following somebody else's turn — the "everyone looks at the person talking" behavior. `false` while it is in its own turn, while `AttendToSpeaker` is `Off`, and while nobody attendable speaks. | | `SpeakerAttention` | `string` | One line describing what conversation attention is actually doing — who is being watched, or the gate that turned the speaker away (`"too far"`, `"behind them"`, `"its own turn"`). | | `LodEnabled` | `bool` | Whether crowd LOD is active on this character. | | `LodFar` | `bool` | Whether the character is in the reduced-rate far LOD band. | | `LodExpressionSkipped` | `bool` | Whether the solver stage is being skipped this frame (off-screen LOD). | | `RecentTrace` | `List` | Recent transition log copied from the trace ring buffer, oldest first. | #### Head-pose contributor trace These fields break down what moved the head this frame and why. `HeadAngles` and `TorsoAngles` are what a reader normally wants; this group exists for diagnosing a specific head-pose defect — a residual gap between `TargetErrorAngles` and the sum of the actuators below, where one contributor has backed off and another has silently clamped. Read them together, not individually. | Field | Type | Description | | ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `HeadGoal` | `Vector2` | The actuator ladder's head yaw/pitch goal, in degrees, for this frame's shift. | | `HeadShiftActive` | `bool` | Whether the head is executing a shaped movement toward a new goal (the ballistic lane is in flight). | | `StabilizationOffset` | `Vector2` | The stabilization reflex's applied offset, in degrees, that cancels the animation's own head deviation. | | `AnimatedDeviation` | `Vector2` | The animation's own measured head deviation, in degrees, that the stabilization reflex is cancelling. | | `GestureOffset` | `Vector2` | Composed head-gesture offset, in degrees — backchannel nod, external program, and floor-yield dip. | | `AversionHeadOffset` | `Vector2` | Aversion beat's head-share offset, in degrees, after the eye-contact-lock and turn-taking scaling that fed the head solve. | | `AversionEyeOffset` | `Vector2` | Aversion beat's eye-share offset, in degrees, as fed to the eye solve. | | `MicroOffset` | `Vector2` | Composed eye micro-motion offset, in degrees — micro-saccade dwell, face-scan, and arrival-settle pitch. | | `ChainLagOffset` | `Vector2` | Degrees the neck/head chain-lag redistribution shifts onto the head bone this frame — the overlapping-action follow-through and settle. | | `AppliedHeadDeltaDegrees` | `float` | Degrees the head bone's world rotation moved between this frame and the last, measured after the solve writes the bone. | | `TargetPointDeltaMeters` | `float` | Meters the engaged directive's world point moved since the last expression tick. | | `GenerationId` | `int` | The directive's generation id at capture time; increments on every re-target, so a probe can tell a contributor step apart from a fresh look. | #### Methods | Method | Signature | Description | | ------- | -------------- | ----------------------------------------------- | | `Clear` | `void Clear()` | Resets all fields to their disengaged defaults. | ### Related reference {% content-ref url="/pages/g9qN2LHADqPrumtNSGVx" %} [Gaze profile reference](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/profile-reference.md) {% endcontent-ref %} {% content-ref url="/pages/k5F6dEGorM9KVWBpa8DX" %} [Scripted gaze](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/scripted-gaze.md) {% endcontent-ref %} {% content-ref url="/pages/16odkxZo8BSnEg0yfigy" %} [Gaze targets and providers](/api-docs/plugins-and-integrations/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 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/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/scripting-reference.md?ask=&goal= ``` `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.