> 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.md).

# Gaze

Find guides for adding eye contact, attention shifts, and full-body turns to a Convai character with the Gaze embodiment module.

Gaze is the Convai embodiment module that decides where a character looks: eye contact with the player, glances at objects and other characters, and full-body turns when the player moves out of view. One component, `ConvaiGazeController`, drives the eyes, head, and body together so the character's attention reads as a single coherent behavior instead of separate systems fighting for the same bones.

### What gaze gives a character

| Behavior               | What it looks like                                                                                                                     |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Eye contact            | The character's eyes and head track the player while listening and speaking, and look away naturally between turns.                    |
| Attention shifts       | Glances at scene objects, other Convai characters, and whatever the player is currently looking at.                                    |
| Body turns             | The character turns its body, not only its head, when the player moves far enough off-axis or walks behind it.                         |
| Conversation awareness | Engagement, aversion, and body participation all scale with the character's current dialogue state instead of running on a fixed loop. |

Add `ConvaiGazeController` to a character through **Convai > Embodiment > Gaze** and it works immediately on the SDK's built-in tuning — no profile asset or additional setup is required to see eye contact in Play mode.

### How it decides what to look at

Every tick, Gaze resolves a target from the available candidates, decides how strongly to commit to it based on the character's dialogue state, and moves the eyes, head, and body in that order to reach it. [How gaze works](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/how-gaze-works.md) covers target priority, the eye-then-head-then-body movement chain, and how [dialogue state](/api-docs/plugins-and-integrations/convai-unity-sdk/core-concepts/dialogue-state.md) drives engagement.

### Where to start

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

### Explore gaze

#### Getting started

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>How gaze works</strong><br>Target priority, the eye-then-head-then-body movement chain, and how dialogue state drives engagement.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/how-gaze-works.md">How gaze works</a></td></tr><tr><td><strong>Gaze quick start</strong><br>Add the Gaze component to a character and see eye contact working in Play mode.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/quick-start.md">Gaze quick start</a></td></tr></tbody></table>

#### Configuring gaze

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Configure eye contact</strong><br>Set how strongly a character commits to the player, from natural behavior to a permanent lock.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/configure-eye-contact.md">Configure eye contact</a></td></tr><tr><td><strong>Gaze targets and providers</strong><br>Mark scene objects as worth looking at and register a custom target source.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/targets-and-providers.md">Gaze targets and providers</a></td></tr><tr><td><strong>Scripted gaze</strong><br>Direct a character's gaze from code with GazeAt and GlanceAt.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/scripted-gaze.md">Scripted gaze</a></td></tr></tbody></table>

#### Reference

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Gaze profile reference</strong><br>Every setting group on ConvaiGazeProfile, with defaults.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/profile-reference.md">Gaze profile reference</a></td></tr><tr><td><strong>Gaze scripting reference</strong><br>The ConvaiGazeController public API: readings, handles, and enums.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/scripting-reference.md">Gaze scripting reference</a></td></tr><tr><td><strong>Gaze usage examples</strong><br>Training, interview, and multi-character scenarios.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/usage-examples.md">Gaze usage examples</a></td></tr><tr><td><strong>Troubleshoot gaze</strong><br>Eyes static, head not turning, and targets never selected.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/gaze/troubleshooting.md">Troubleshoot gaze</a></td></tr></tbody></table>

### Next steps

Gaze is one of five embodiment modules. Add Body Animation next to give the same character idle motion, gestures, and NavMesh-driven movement that Gaze can watch and react to.

{% content-ref url="/pages/XvueBQ9uW4pr3jUaNBed" %}
[Body animation](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment/body-animation.md)
{% endcontent-ref %}

{% content-ref url="/pages/5RuK3poQnrGRdFg2G84l" %}
[Embodiment](/api-docs/plugins-and-integrations/convai-unity-sdk/embodiment.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.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.