> 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/how-gaze-and-attention-works.md).

# How Gaze and Attention works

The Gaze & Attention utility adds natural eye contact and head tracking to AI characters. It runs entirely inside Unity — no data is sent to Convai — and operates independently of the session lifecycle. Two cooperating layers handle what the character looks at and how it looks there.

***

### Attention layer

The Attention layer decides **what** the character looks at. It evaluates all registered `IFocusTargetProvider` components each frame, selecting a winner using priority, distance-based relevance, and an interest budget that prevents indefinite fixation on a single target.

***

### Gaze layer

The Gaze layer decides **how** the character looks at the attention target. It translates the active attention reading into eye rotation, head movement, procedural saccades, blinks, and eyelid follow. Gaze authority is weighted by the current dialogue state — the character looks more assertively during speech and more softly during idle.

***

### Component pipeline

```mermaid
graph LR
    A[IFocusTargetProvider<br/>one or more] --> B[ConvaiAttentionController]
    B --> C[ConvaiGazeCoordinator]
    C --> D[ConvaiEyeGazeActuator]
    C --> E[ConvaiHeadLookActuator]
    D --> F[Eye bones / blendshapes]
    E --> G[Neck and head bones]
```

Each layer is independently configurable through ScriptableObject profiles. You can tune attention persistence, eye tracking sharpness, head range, saccade frequency, and per-dialogue-state gaze authority — all without code.

| Component                    | Responsibility                                                                         |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| `ConvaiAttentionController`  | Selects the active focus target each frame                                             |
| `ConvaiGazeCoordinator`      | Blends attention output with dialogue state to produce `GazeIntent`                    |
| `ConvaiEyeGazeActuator`      | Rotates eye bones and drives blendshapes from `GazeIntent`                             |
| `ConvaiHeadLookActuator`     | Rotates neck and head bones from `GazeIntent`                                          |
| `AnimationRiggingGazeBridge` | Optional: drives Unity Animation Rigging constraints instead of procedural bone writes |

***

### Next steps

{% content-ref url="/pages/8db0a7c73598ac534a4c40ffac06ec94256588a3" %}
[Gaze and Attention quick start](/api-docs/plugins-and-integrations/convai-unity-sdk/utilities/gaze-and-attention/quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/bdf689d789a4f88bf1d26ce6d354d98074cfd771" %}
[Attention and gaze profiles](/api-docs/plugins-and-integrations/convai-unity-sdk/utilities/gaze-and-attention/profiles-and-tuning.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/how-gaze-and-attention-works.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.