> 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/utilities/gaze-and-attention/profiles-and-tuning.md).

# Attention and gaze profiles

Four ScriptableObject profiles control the Gaze & Attention system. Each profile addresses a separate domain of behavior. Assign them to the corresponding components via the Inspector, or leave slots empty to use built-in defaults.

***

### ConvaiAttentionProfile

Controls target selection: which candidate wins focus, how quickly the character commits, and how long it holds before breaking away.

**Create via:** Create → Convai → Embodiment → Attention Profile\
**Assign to:** `ConvaiAttentionController` → Attention Profile field

#### Commitment timing

| Field                      | Default | Range  | Description                                                                     |
| -------------------------- | ------- | ------ | ------------------------------------------------------------------------------- |
| `CommitmentAcquireSeconds` | `0.3`   | 0.1–10 | Time in seconds for commitment to ramp from 0 → 1 when a new target is acquired |
| `CommitmentReleaseSeconds` | `0.5`   | 0.1–10 | Time in seconds for commitment to decay from 1 → 0 when a target is lost        |
| `FocusLossHoldSeconds`     | `0.25`  | 0–3    | Grace period after losing sight of a target before commitment begins decaying   |

#### Interest budget

The interest budget prevents the character from fixating on a single target indefinitely. Each frame, the current focus loses interest at `InterestDecayPerSecond`. When interest drops below `InterestBreakThreshold`, the attention system releases the target and evaluates alternatives.

| Field                       | Default | Range  | Description                                                                       |
| --------------------------- | ------- | ------ | --------------------------------------------------------------------------------- |
| `MaxContinuousHoldSeconds`  | `5.0`   | 0.5–20 | Maximum seconds a single target can be held before interest is forcibly exhausted |
| `InterestBreakThreshold`    | `0.15`  | 0–1    | Interest level at which the system releases the current target                    |
| `InterestDecayPerSecond`    | `0.15`  | 0.05–5 | How fast interest falls per second while looking at the current target            |
| `InterestRecoveryPerSecond` | `0.25`  | 0.05–5 | How fast interest recovers per second in neglected candidates                     |

#### Smoothing and offset

| Field                    | Default        | Range  | Description                                                                   |
| ------------------------ | -------------- | ------ | ----------------------------------------------------------------------------- |
| `FocusPositionLerpSpeed` | `10.0`         | 0.1–30 | Lerp speed for smoothing the focus point in world space                       |
| `FocusOffset`            | `(0, 0.05, 0)` | —      | World-space offset added to the focus point, useful for targeting face height |

#### Default focus provider

These fields tune the built-in camera-targeting provider that activates when **Auto Create Default Focus Provider** is enabled on `ConvaiAttentionController`.

| Field                               | Default | Range | Description                                                            |
| ----------------------------------- | ------- | ----- | ---------------------------------------------------------------------- |
| `DefaultFocusBaseRelevance`         | `0.8`   | 0–1   | Base relevance score returned by the default provider                  |
| `DefaultFocusTargetHeadHeight`      | `0`     | ≥ 0   | Vertical offset applied to the focus point when targeting a transform  |
| `DefaultFocusMaxDistance`           | `8.0`   | ≥ 0   | Distance beyond which the default provider returns zero relevance      |
| `DefaultFocusFullRelevanceDistance` | `3.0`   | ≥ 0   | Distance within which the default provider returns full base relevance |

***

### ConvaiGazeCoordinationProfile

Controls how attention output is weighted differently across each dialogue state — how much authority the overall gaze system has, and how that authority is split between eyes and head.

**Create via:** Create → Convai → Embodiment → Gaze Coordination Profile\
**Assign to:** `ConvaiGazeCoordinator` (auto-created by `ConvaiEyeGazeActuator`)

#### Per-state weights

Each dialogue state has an `OverallWeight` and an `EyeShare`.

* **OverallWeight** — how strongly the character looks at the attention target (0 = fully relaxed, 1 = locked-on)
* **EyeShare** — fraction of the tracking handled by eyes alone. The head handles `1 − EyeShare`.

| Dialogue state | OverallWeight | EyeShare | Notes                                                   |
| -------------- | ------------- | -------- | ------------------------------------------------------- |
| `Idle`         | `0.45`        | `0.85`   | Attention target suppressed; eyes wander freely         |
| `Listening`    | `0.93`        | `0.52`   | Strong engagement, balanced eye/head split              |
| `Attending`    | `0.90`        | `0.62`   | Character orienting toward focus before player speaks   |
| `Thinking`     | `0.95`        | `0.80`   | Player finished; character hasn't replied; eye-dominant |
| `Speaking`     | `1.0`         | `0.45`   | Full commitment, head-dominant — "locked-in" presence   |
| `Reacting`     | `0.95`        | `0.48`   | Brief reaction beat; similar to speaking split          |
| `Interrupted`  | `0.88`        | `0.85`   | Brief freeze; eye-dominant                              |
| `Settling`     | `0.93`        | `0.70`   | Post-turn cooldown; gaze softens                        |

{% hint style="info" %}
The `Idle` state sets `SuppressAttentionTarget = true`, which disables the attention input entirely and lets the eye and head actuators run their idle exploration behavior without tracking a target.
{% endhint %}

#### Blend smoothing

| Field                | Default | Range | Description                                                             |
| -------------------- | ------- | ----- | ----------------------------------------------------------------------- |
| `WeightBlendSpeed`   | `6.0`   | 0–20  | Smoothing speed for `OverallWeight` transitions between dialogue states |
| `EyeShareBlendSpeed` | `4.0`   | 0–20  | Smoothing speed for `EyeShare` transitions between dialogue states      |

***

### ConvaiGazeEyeProfile

Controls eye rotation mechanics: tracking responsiveness, range limits, procedural saccades, micro-tremor, idle wandering, and blink behavior.

**Create via:** Create → Convai → Embodiment → Gaze Eye Profile\
**Assign to:** `ConvaiEyeGazeActuator` → Eye Profile field

#### Tracking

| Field               | Default | Range | Description                                                                                |
| ------------------- | ------- | ----- | ------------------------------------------------------------------------------------------ |
| `TrackingSharpness` | `18.0`  | 1–40  | How quickly eyes rotate toward the gaze target. 18 matches natural human oculomotor speed. |
| `MaxYawDegrees`     | `45.0`  | 0–90  | Maximum horizontal eye rotation in degrees                                                 |
| `MaxPitchDegrees`   | `30.0`  | 0–90  | Maximum vertical eye rotation in degrees                                                   |

#### Saccades

Saccades are small involuntary eye movements that make the gaze feel alive.

| Field                   | Default | Range     | Description                                  |
| ----------------------- | ------- | --------- | -------------------------------------------- |
| `EnableSaccades`        | `true`  | —         | Enable procedural saccades                   |
| `SaccadeIntervalMean`   | `1.8`   | ≥ 0.05    | Average seconds between saccades             |
| `SaccadeIntervalJitter` | `0.65`  | ≥ 0       | Random variation added to the interval       |
| `SaccadeMaxDegrees`     | `2.5`   | 0–5       | Maximum displacement per saccade in degrees  |
| `SaccadeDuration`       | `0.07`  | 0.01–0.25 | Duration of each saccade movement in seconds |

#### Micro-tremor

High-frequency noise that simulates physiological eye tremor.

| Field                  | Default | Range | Description                          |
| ---------------------- | ------- | ----- | ------------------------------------ |
| `EnableMicroTremor`    | `true`  | —     | Enable micro-tremor noise            |
| `MicroTremorAmplitude` | `0.18`  | 0–1   | Amplitude of the tremor displacement |
| `MicroTremorFrequency` | `11.0`  | 1–30  | Frequency in Hz                      |

#### Idle exploration

When the attention target is suppressed (idle dialogue state), eyes wander within a configurable range.

| Field                              | Default | Range  | Description                                             |
| ---------------------------------- | ------- | ------ | ------------------------------------------------------- |
| `EnableIdleExploration`            | `true`  | —      | Enable idle eye wandering                               |
| `IdleExplorationWeight`            | `0.65`  | 0–1    | Blend weight of idle exploration against straight-ahead |
| `IdleExplorationHorizontalDegrees` | `14.0`  | 0–45   | Maximum horizontal wander range in degrees              |
| `IdleExplorationUpDegrees`         | `5.0`   | 0–25   | Maximum upward wander in degrees                        |
| `IdleExplorationDownDegrees`       | `8.0`   | 0–25   | Maximum downward wander in degrees                      |
| `IdleExplorationIntervalMin`       | `1.1`   | ≥ 0.05 | Minimum seconds between exploration target changes      |
| `IdleExplorationIntervalMax`       | `3.2`   | ≥ 0.05 | Maximum seconds between exploration target changes      |
| `IdleExplorationCenterBias`        | `0.38`  | 0–1    | Probability of returning toward center on each interval |
| `IdleRecenteringChance`            | `0.22`  | 0–1    | Additional recentering chance applied each interval     |

#### Blink

| Field         | Default | Description                                                                                                                                                                   |
| ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EnableBlink` | `true`  | Enable procedural blink scheduling. Blink timing is driven by an `EyeBlinkScheduler` — blink rate is not directly configurable via this profile but can be disabled entirely. |

***

### ConvaiGazeHeadProfile

Controls neck and head rotation: range limits, smoothing, idle head wandering, and the minimum head contribution.

**Create via:** Create → Convai → Embodiment → Gaze Head Profile\
**Assign to:** `ConvaiHeadLookActuator` → Head Profile field

#### Range

| Field          | Default | Range | Description                                                |
| -------------- | ------- | ----- | ---------------------------------------------------------- |
| `MaxNeckYaw`   | `40.0`  | 0–90  | Maximum yaw rotation applied to the neck bone in degrees   |
| `MaxNeckPitch` | `30.0`  | 0–90  | Maximum pitch rotation applied to the neck bone in degrees |
| `MaxHeadYaw`   | `20.0`  | 0–60  | Maximum yaw rotation applied to the head bone in degrees   |
| `MaxHeadPitch` | `15.0`  | 0–60  | Maximum pitch rotation applied to the head bone in degrees |

#### Smoothing

| Field                  | Default | Range  | Description                                                           |
| ---------------------- | ------- | ------ | --------------------------------------------------------------------- |
| `SmoothingSharpness`   | `6.0`   | 0.5–30 | Responsiveness when tracking toward the gaze target                   |
| `ReturnSharpness`      | `5.0`   | 0.5–30 | Responsiveness when returning to neutral                              |
| `IdleSharpness`        | `2.2`   | 0.5–30 | Smoothing during idle exploration (slower = more dreamlike)           |
| `MaxYawSpeedDegrees`   | `160.0` | 0–720  | Maximum yaw rotation speed in degrees per second                      |
| `MaxPitchSpeedDegrees` | `120.0` | 0–720  | Maximum pitch rotation speed in degrees per second                    |
| `DeadzoneDegrees`      | `1.5`   | 0–10   | Angle below which head rotation is suppressed — prevents micro-jitter |

#### Idle exploration

| Field                        | Default | Range  | Description                                             |
| ---------------------------- | ------- | ------ | ------------------------------------------------------- |
| `EnableIdleExploration`      | `true`  | —      | Enable head wandering during idle state                 |
| `IdleExplorationWeight`      | `0.7`   | 0–1    | Blend weight of idle exploration target                 |
| `IdleExplorationYawDegrees`  | `6.0`   | 0–30   | Maximum horizontal head wander in degrees               |
| `IdleExplorationUpDegrees`   | `1.5`   | 0–15   | Maximum upward wander in degrees                        |
| `IdleExplorationDownDegrees` | `2.5`   | 0–15   | Maximum downward wander in degrees                      |
| `IdleExplorationIntervalMin` | `2.2`   | ≥ 0.05 | Minimum seconds between head target changes             |
| `IdleExplorationIntervalMax` | `5.5`   | ≥ 0.05 | Maximum seconds between head target changes             |
| `IdleExplorationCenterBias`  | `0.55`  | 0–1    | Probability of returning toward center on each interval |
| `IdleRecenteringChance`      | `0.32`  | 0–1    | Additional recentering chance per interval              |

#### Authority

| Field                     | Default | Range | Description                                                                                                                                                                           |
| ------------------------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MinimumHeadContribution` | `0.45`  | 0–1   | Floor for head rotation contribution. The head never contributes less than this fraction even when the coordinator assigns a low head-share. Prevents the head from appearing frozen. |

***

### Next steps

See Usage Examples for scenario-specific profile configurations, or Scripting API if you need to read attention state or implement a custom focus provider.

{% content-ref url="/pages/4485b09fb5be00f7295b696c5de8687d4a80c779" %}
[Gaze and Attention usage examples](/api-docs/plugins-and-integrations/convai-unity-sdk/utilities/gaze-and-attention/usage-examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/0f74068e38a6f78390e41d0506de247f8d68516e" %}
[Gaze and Attention scripting API](/api-docs/plugins-and-integrations/convai-unity-sdk/utilities/gaze-and-attention/scripting-api.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:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/utilities/gaze-and-attention/profiles-and-tuning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.