> For the complete documentation index, see [llms.txt](https://morningheartgames.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/integrations/animancer.md).

# Animancer

> Online doc: <https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/integrations/animancer?fallback=true>

The Animancer integration registers an Animancer-backed montage animation driver. It is optional and compiles only when the project defines `GAS_ENABLE_ANIMANCER` and has Animancer available.

This bridge does not change ability, effect, or montage contracts. It only changes which animation backend receives montage playback requests.

## What It Does

| Type                                            | Responsibility                                                       |
| ----------------------------------------------- | -------------------------------------------------------------------- |
| `AnimancerAnimationDriver`                      | Implements `IAnimationDriver` using `AnimancerComponent`.            |
| `AnimancerMontageBootstrap`                     | Registers the Animancer backend before scene load and in the editor. |
| `AnimationDriverConfig.DriverBackend.Animancer` | Backend option used by montage configuration.                        |

## When To Use It

Use Animancer when:

* Your project already uses Animancer for character animation.
* You want montage slots to map to Animancer layers.
* You need AvatarMask, additive, and layer weight fade behavior through Animancer.

Use the built-in Unity driver when you do not have Animancer installed.

## Enablement

1. Install Animancer in the Unity project.
2. Add the scripting define symbol `GAS_ENABLE_ANIMANCER`.
3. Let Unity recompile.
4. Confirm `GameplayAbilityToolkit.Animancer.asmdef` compiles.
5. Add `AnimancerComponent` to actors that will use the backend.
6. Create or select an `AnimationDriverConfig`.
7. Set its backend to Animancer.
8. Assign the config to `GASConfiguration.defaultAnimationDriverConfig` or to a local `MontagePlayer.driverConfig`.

## Runtime Flow

```mermaid
flowchart TD
    MontagePlayer["MontagePlayer"] --> DriverConfig["AnimationDriverConfig"]
    DriverConfig --> AnimancerBackend["Animancer backend"]
    AnimancerBackend --> Component["AnimancerComponent"]
    Component --> Layers["Animancer layers"]
    Layers --> Slots["Montage slots, masks, additive flags"]
```

Layer 0 is treated as the base layer. Overlay slots fade their layer weights in and out. Root motion is enabled on the Animator if any active slot requests root motion.

## Configuration Checklist

* Actor has `AnimancerComponent`.
* Actor has `MontagePlayer`.
* Driver backend is Animancer.
* Slot names match between `AnimationMontage.slot` and `MontageSlotConfig`.
* Avatar masks are assigned for partial-body slots.
* Root motion expectations are tested on the specific character controller.

## Debugging Checklist

* If nothing plays, confirm `GAS_ENABLE_ANIMANCER` is defined and the assembly compiles.
* If playback falls back to Unity driver, inspect `AnimationDriverConfig`.
* If no component is found, confirm `AnimancerComponent` is on the same owner used by `MontagePlayer`.
* If overlays affect the whole body, inspect slot masks.
* If root motion toggles unexpectedly, inspect active montage clips with root motion enabled.

## Common Mistakes

| Mistake                                          | Result                    | Fix                                           |
| ------------------------------------------------ | ------------------------- | --------------------------------------------- |
| Enabling the define without installing Animancer | Compile errors            | Install Animancer or remove the define.       |
| Missing `AnimancerComponent`                     | Driver cannot play clips  | Add the component to the actor.               |
| Using inconsistent slot names                    | Wrong layer/mask behavior | Centralize slot names in `MontageSlotConfig`. |
| Assuming base and overlay layers behave the same | Overlay fades differ      | Test layer weights with the preview/scene.    |

## Examples and Tests

Use the [Montage](/docs/gameplay-ability-toolkit/subsystems/montage.md) page first. Add Animancer only after the same montage plays with a known actor setup.


---

# 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://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/integrations/animancer.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.