> 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/scripting-api.md).

# Dialogue Animation scripting API

`ConvaiDialogueAnimationController` exposes a read-only state surface and two runtime swap methods. All properties are safe to query every frame from any script.

***

### ConvaiDialogueAnimationController

**Namespace:** `Convai.Modules.DialogueAnimation.Components`\
**Component menu:** Convai → Embodiment → Dialogue Animation

#### Methods

| Method                | Parameters                              | Description                                                                            |
| --------------------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
| `SetLibrary(library)` | `DialogueAnimationLibrary library`      | Swaps the active clip pool immediately. Takes effect on the next clip selection cycle. |
| `SetConfig(config)`   | `DialogueAnimationRuntimeConfig config` | Replaces the active runtime config. Timing and weight changes apply on the next tick.  |

#### Assigned asset properties

| Property          | Type                             | Description                                              |
| ----------------- | -------------------------------- | -------------------------------------------------------- |
| `Library`         | `DialogueAnimationLibrary`       | Currently assigned library                               |
| `Config`          | `DialogueAnimationRuntimeConfig` | Currently assigned config                                |
| `Contract`        | `DialogueAnimatorContract`       | Active animator contract (may be null if using defaults) |
| `CharacterGender` | `CharacterGender`                | Active gender filter for clip selection                  |

#### Validation

| Property              | Type   | Description                                                                                                       |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `HasValidIdleLibrary` | `bool` | `true` when the assigned library has at least one valid idle clip. Use this at startup to catch misconfiguration. |

#### Current clip properties

| Property                    | Type            | Description                                      |
| --------------------------- | --------------- | ------------------------------------------------ |
| `CurrentFoundationIdleClip` | `AnimationClip` | Clip currently assigned to the Base Idle slot    |
| `CurrentIdleOverlayClip`    | `AnimationClip` | Clip currently playing in the Idle Overlay layer |
| `CurrentBodyTalkClip`       | `AnimationClip` | Clip currently playing in the Body Talk layer    |
| `CurrentTalkClip`           | `AnimationClip` | Clip currently playing in the Head Talk layer    |

#### Layer weight properties

| Property                        | Type    | Description                                                                                                                                                                                |
| ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `CurrentBaseIdleLayerWeight`    | `float` | Current weight of the Base Idle layer (Layer 0)                                                                                                                                            |
| `CurrentIdleOverlayLayerWeight` | `float` | Current weight of the Idle Overlay layer (Layer 1)                                                                                                                                         |
| `CurrentBodyTalkLayerWeight`    | `float` | Current weight of the Body Talk layer (Layer 2)                                                                                                                                            |
| `CurrentHeadTalkLayerWeight`    | `float` | Current weight of the Head Talk layer (Layer 3)                                                                                                                                            |
| `CurrentTalkLayerWeight`        | `float` | Strongest active talk-layer contribution — `max(CurrentBodyTalkLayerWeight, CurrentHeadTalkLayerWeight)`. Use this to drive UI or external systems that need a single "is talking" signal. |

#### Runtime layer index properties

| Property                       | Type  | Description                                               |
| ------------------------------ | ----- | --------------------------------------------------------- |
| `RuntimeBaseIdleLayerIndex`    | `int` | Resolved Animator layer index for Base Idle at runtime    |
| `RuntimeIdleOverlayLayerIndex` | `int` | Resolved Animator layer index for Idle Overlay at runtime |
| `RuntimeBodyTalkLayerIndex`    | `int` | Resolved Animator layer index for Body Talk at runtime    |
| `RuntimeHeadTalkLayerIndex`    | `int` | Resolved Animator layer index for Head Talk at runtime    |

#### Selection diagnostic properties

| Property        | Type  | Description                                                                           |
| --------------- | ----- | ------------------------------------------------------------------------------------- |
| `LastIdleIndex` | `int` | Index into the library's `IdleEntries` array for the most recently selected idle clip |
| `LastTalkIndex` | `int` | Index into the library's `TalkEntries` array for the most recently selected talk clip |

***

### Scripting examples

#### Validate configuration at startup

Check `HasValidIdleLibrary` before your session starts to catch missing library assignments early:

```csharp
using Convai.Modules.DialogueAnimation.Components;
using UnityEngine;

public class AnimationValidator : MonoBehaviour
{
    [SerializeField] private ConvaiDialogueAnimationController _animController;

    private void Start()
    {
        if (!_animController.HasValidIdleLibrary)
        {
            Debug.LogError(
                $"[{name}] No valid idle clips in the assigned library. " +
                "Assign a DialogueAnimationLibrary with at least one idle entry.",
                this);
        }
    }
}
```

***

#### Drive a UI engagement indicator from talk layer weight

`CurrentTalkLayerWeight` updates every frame from the Animator's internal cache:

```csharp
using Convai.Modules.DialogueAnimation.Components;
using UnityEngine;
using UnityEngine.UI;

public class TalkLayerIndicator : MonoBehaviour
{
    [SerializeField] private ConvaiDialogueAnimationController _animController;
    [SerializeField] private Slider _engagementSlider;

    private void Update()
    {
        _engagementSlider.value = _animController.CurrentTalkLayerWeight;
    }
}
```

***

#### Swap libraries based on a simulation event

```csharp
using Convai.Modules.DialogueAnimation.Components;
using Convai.Modules.DialogueAnimation.Core;
using UnityEngine;

public class ContextualAnimationSwap : MonoBehaviour
{
    [SerializeField] private ConvaiDialogueAnimationController _animController;
    [SerializeField] private DialogueAnimationLibrary _calmLibrary;
    [SerializeField] private DialogueAnimationLibrary _urgentLibrary;

    public void OnEmergencyAlert()
    {
        _animController.SetLibrary(_urgentLibrary);
    }

    public void OnStandDown()
    {
        _animController.SetLibrary(_calmLibrary);
    }
}
```

***

#### Use separate config assets for independent multi-character clip selection

To prevent two characters from selecting the same clips in sync, author separate `DialogueAnimationRuntimeConfig` assets and set a different `DeterministicSeed` value on each in the Inspector. Then assign each config at runtime:

```csharp
using Convai.Modules.DialogueAnimation.Components;
using Convai.Modules.DialogueAnimation.Runtime;
using UnityEngine;

public class MultiCharacterSetup : MonoBehaviour
{
    [SerializeField] private ConvaiDialogueAnimationController[] _characters;
    // Assign one config asset per character in the Inspector.
    // Set a different DeterministicSeed on each config asset to diverge their RNG streams.
    [SerializeField] private DialogueAnimationRuntimeConfig[] _perCharacterConfigs;

    private void Awake()
    {
        for (int i = 0; i < _characters.Length; i++)
        {
            _characters[i].SetConfig(_perCharacterConfigs[i]);
        }
    }
}
```

***

#### Monitor layer weights for an engagement dashboard

Read all four layer weights simultaneously to drive a per-layer visualization:

```csharp
using Convai.Modules.DialogueAnimation.Components;
using UnityEngine;

public class LayerWeightDashboard : MonoBehaviour
{
    [SerializeField] private ConvaiDialogueAnimationController _ctrl;

    private void Update()
    {
        float idle     = _ctrl.CurrentBaseIdleLayerWeight;
        float overlay  = _ctrl.CurrentIdleOverlayLayerWeight;
        float bodyTalk = _ctrl.CurrentBodyTalkLayerWeight;
        float headTalk = _ctrl.CurrentHeadTalkLayerWeight;

        // All four values are live Animator cache reads — no heap allocation
        Debug.Log($"Idle:{idle:F2} Overlay:{overlay:F2} Body:{bodyTalk:F2} Head:{headTalk:F2}");
    }
}
```

***

### Next steps

For help diagnosing animation issues at runtime, see the Troubleshooting page.

{% content-ref url="/pages/53c2015ebf2f2d7e04074279408d7cbacde002e8" %}
[Dialogue Animation troubleshooting](/api-docs/plugins-and-integrations/convai-unity-sdk/utilities/dialogue-animation/troubleshooting.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/scripting-api.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.