> 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/dialogue-animation/how-dialogue-animation-works.md).

# How Dialogue Animation works

The Dialogue Animation module drives body and head gesture animations on AI characters using dialogue state and detected emotion as inputs. Instead of hard-coded animator states for every clip, it uses an `AnimatorOverrideController` to inject clips from a pooled library at runtime — swapping candidates as dialogue progresses. The module runs entirely inside Unity. No animation data is sent to Convai.

***

### Dialogue states and layer control

Each frame the module reads two signals: the current **dialogue state** (idle, listening, thinking, speaking, reacting) and the current **emotion reading** from the Emotion module. It uses those signals to select and crossfade clips from a `DialogueAnimationLibrary` across a four-layer animator stack.

```mermaid
graph LR
    A[Dialogue State] --> C[ConvaiDialogueAnimationController]
    B[Emotion Reading] --> C
    C --> D[Layer 0: Base Idle]
    C --> E[Layer 1: Idle Overlay]
    C --> F[Layer 2: Body Talk]
    C --> G[Layer 3: Head Talk]
```

The four layers are additive and masked: the base idle plays continuously, the idle overlay adds variation, and the two talk layers fade in when the character speaks. Talk layer clips are routed by `DialogueTalkBodyCoverage` — clips can target head only, body only, or both simultaneously.

***

### Configuration assets

The module is driven by four ScriptableObject types:

| Asset                            | Purpose                                                                             |
| -------------------------------- | ----------------------------------------------------------------------------------- |
| `DialogueAnimationLibrary`       | Pool of idle and talk clips, each tagged with emotion affinity and character gender |
| `DialogueAnimationRuntimeConfig` | Timing, blend durations, layer weights, and selection parameters                    |
| `DialogueAnimatorContract`       | Maps layer indices and state names to your Animator Controller                      |
| `ConvaiDialogueAnimationProfile` | Bundles the three assets above into a single character preset                       |

Three bundled profiles ship with the SDK: **Balanced**, **Expressive**, and **Subtle**. They cover most characters without custom authoring.

***

### Next steps

Follow the Quick Start to get the module running on your first character, then read Animation Libraries & Profiles to understand clip pools, timing, and the full field reference.

{% content-ref url="/pages/d426f4256a6e1f6125be8f4b95380e63040b0ad8" %}
[Dialogue Animation quick start](/api-docs/plugins-and-integrations/convai-unity-sdk/utilities/dialogue-animation/quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/qPHprAmwjoclwLCbma19" %}
[Animation libraries and profiles](/api-docs/plugins-and-integrations/convai-unity-sdk/utilities/dialogue-animation/animation-libraries-and-profiles.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/dialogue-animation/how-dialogue-animation-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.