> 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/quick-start.md). # Gaze and Attention quick start Add eye contact and natural head movement to an AI character with the minimum required components. By the end, the character tracks the main camera with its eyes and head, with procedural saccades and blinks. ### Prerequisites * A `ConvaiCharacter` component is on the character's root GameObject * The character uses a **humanoid rig** with a configured Unity Avatar * For eye tracking: the Avatar has **eye bones** assigned (Left Eye / Right Eye in the Avatar configuration) * For `AnimationRiggingGazeBridge` (optional): the `com.unity.animation.rigging` package is installed and `CONVAI_ANIMATION_RIGGING` is defined in your project's scripting define symbols *** ### Setup {% stepper %} {% step %} #### Add ConvaiAttentionController Select the character's root GameObject. Add **ConvaiAttentionController** (**Convai → Embodiment → Attention Controller**). The component has two options enabled by default: * **Discover Providers In Hierarchy** — automatically finds all `IFocusTargetProvider` components on the character and its children * **Auto Create Default Focus Provider** — adds a built-in provider that targets the main camera (or the first active camera in the scene) Leave both enabled for a basic setup. The character will begin tracking the camera as soon as the components are active. {% endstep %} {% step %} #### Add ConvaiEyeGazeActuator On the same root GameObject, add **Eye Gaze** (**Convai → Embodiment → Eye Gaze**). The eye actuator automatically creates a `ConvaiGazeCoordinator` on the same GameObject during initialization. You do not need to add the coordinator manually. {% hint style="warning" %} Do not access `ConvaiGazeCoordinator` from `Awake()`. The coordinator is created during the eye actuator's initialization — it is not available until after `Awake()` completes on the character. Use `Start()` or later for any scripted access. {% endhint %} Optionally, assign a `ConvaiGazeEyeProfile` to the **Eye Profile** slot. If left empty, the component uses built-in defaults (18° tracking sharpness, 45° yaw range, 30° pitch range, saccades and blinks enabled). {% endstep %} {% step %} #### Add ConvaiHeadLookActuator On the same root GameObject, add **Head Look** (**Convai → Embodiment → Head Look**). Optionally assign a `ConvaiGazeHeadProfile`. Built-in defaults: 40° neck yaw, 30° neck pitch, 6.0 smoothing sharpness. The head actuator blends with the eye actuator through the shared `ConvaiGazeCoordinator`. When the character speaks, the gaze coordination profile shifts authority toward the head and reduces the eye contribution, creating natural looking-at-the-listener behavior. {% endstep %} {% step %} #### Assign an Attention Profile (optional) If you want to tune attention persistence — how long the character holds gaze before breaking, how quickly it acquires a new target, or the maximum continuous hold duration — assign a `ConvaiAttentionProfile` to the **Attention Profile** slot on `ConvaiAttentionController`. Built-in defaults: 5-second maximum continuous hold, 0.3s acquisition ramp, 0.5s release decay. Create a profile via **Create → Convai → Embodiment → Attention Profile**. {% endstep %} {% step %} #### Enter Play Mode Press Play. With the default focus provider active, the character's eyes and head should track the Scene view camera (or your main runtime camera). **Expected result:** The character's eyes move toward the camera with natural saccades and occasional blinks. The head rotates smoothly to assist when the camera is more than \~10° from the eye center. When the character speaks, gaze locks onto the camera with slightly reduced eye range. {% endstep %} {% endstepper %} *** ### Alternative: Animation Rigging integration If your character uses Unity's Animation Rigging package and you prefer constraint-based gaze over procedural bone writes, use `AnimationRiggingGazeBridge` instead of the eye and head actuators. **Requirements:** * `com.unity.animation.rigging` installed * `CONVAI_ANIMATION_RIGGING` added to **Player Settings → Scripting Define Symbols** * Two `MultiAimConstraint` assets configured for head and eyes on the character's rig Add `AnimationRiggingGazeBridge` to the character's root GameObject and assign the head constraint, eye constraint, and a gaze target pivot transform. The bridge moves the pivot to the attention target point each frame, which the constraints then follow inside the animation graph's IK pass. *** ### Next steps Your character now tracks focus targets with eyes and head. Read Profiles & Tuning to understand all available tuning parameters, or Usage Examples for scenario-specific configuration patterns. {% 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 %} {% 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 %} --- # 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/utilities/gaze-and-attention/quick-start.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.