> For the complete documentation index, see [llms.txt](https://malbersanimations.gitbook.io/animal-controller/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://malbersanimations.gitbook.io/animal-controller/main-components/manimal-controller.md).

# Animal Controller

## Animal Controller

Animal Controller is a data-driven character controller for Unity.

It drives locomotion, combat, AI, and interactions for any creature. This includes bipeds, quadrupeds, birds, fish, dragons, and humanoids.

Use modular ScriptableObject assets to configure behavior with little or no code.

Whether you build a player hero, wildlife, or an AI boss, use `MAnimal`. You assemble assets instead of writing scripts.

### What it is for

Animal Controller provides physics-based movement and actions for game characters.

* **Player characters** — locomotion, jumping, climbing, swimming, flying, combat, and items.
* **Any creature type** — ground alignment, water surfaces, and flight work through States.
* **AI characters** — enemies, companions, and wildlife use the built-in AI Brain.
* **Interactive characters** — NPCs and objects can react to triggers and interactions.

If it moves, fights, or reacts in your scene, Animal Controller can drive it.

### What’s included

Animal Controller is a complete character framework.

* **Locomotion State Machine** — Idle, Locomotion, Jump, Fall, Climb, Glide, Swim, Fly, Rail Grind, Ledge Grab, and more.
* **AI Brain** — data-driven states, tasks, decisions, waypoints, and target detection.
* **Combat and damage** — damagers, damageables, critical hits, and hit reactions.
* **Stats** — health, stamina, mana, custom stats, regeneration, degeneration, and modifiers.
* **Modes (Abilities)** — attacks, dodges, casts, and layered actions.
* **Super Item and Weapons** — modular equipment for weapons, tools, and projectiles.
* **Interactions, Reactions, and Zones** — scene-driven behavior without code.
* **IK and aiming** — foot placement, aim, and procedural adjustments.
* **Integrations** — Unity Input System, Cinemachine, Final IK, Animation Rigging, and more.

### Core idea: data-driven behavior

The framework uses ScriptableObjects throughout.

A State, Mode, AI Task, and Stat are assets in your project. Drag them onto a character to define its behavior.

* Assemble assets instead of writing scripts. Add a Climb State to enable climbing.
* Reuse assets across characters. Update one Jump State to update every character using it.
* Extend any system when needed. Create custom States, Modes, AI Tasks, Decisions, Item Processors, or Reactions.

### The three core concepts

Animal Controller organizes character animation around States, Modes, and Stances.

| Concept            | What it is                                                        | Examples                                       |
| ------------------ | ----------------------------------------------------------------- | ---------------------------------------------- |
| **State**          | A primary action. Only one State is fully active at a time.       | Idle, Locomotion, Jump, Fall, Climb, Swim, Fly |
| **Mode (Ability)** | An action layered over the current State.                         | Attack, Dodge, Cast Spell, Drink, Emote        |
| **Stance**         | An animation variation that changes style, not the active action. | Crouch, Injured, Combat, Bipedal               |

States are what the character does. Modes are actions performed during a State. Stances define how the character performs them.

### How it works

`MAnimal` works alongside an Animator and a Rigidbody.

* The Animator plays animations and sends tags back to `MAnimal`.
* The Rigidbody handles physics interactions with the world.
* `MAnimal` manages rotation, root motion, and code-driven movement.

States, Modes, and Stances determine movement and animation blending.

### Setup requirements

`MAnimal`, an [Animator](https://docs.unity3d.com/Manual/class-Animator.html), and a [Rigidbody](https://docs.unity3d.com/Manual/class-Rigidbody.html) must sit at the same hierarchy level.

#### Animator component

{% hint style="warning" %}
Set the Animator **Update Mode** to **Animate Physics** when using a Rigidbody.
{% endhint %}

![](/files/DRUh7f0NoUAKh2XETnNq)

#### Rigidbody

The Rigidbody lets the character interact with rigidbodies and static scene objects.

`MAnimal` manages rotation. Freeze all Rigidbody rotation constraints.

![](/files/erUEW2Ovv5pR2E8adn76)

#### Colliders

{% hint style="info" %}
For bipeds and quadrupeds, add colliders to major bones such as the **Spine** and **Head**. You can also use one Capsule Collider on the root GameObject.
{% endhint %}

![](https://lh4.googleusercontent.com/vIC0-z6Wo9gZKm4xkT83ftRD3dlesFSOOFWJyxK5e3tUJYf54RxQnuem45jEEFY_cNHcpBXbxO-z1FznZg0uL_OYUZIHvjMCaRjfKK8IgomjSmWseHYIULxCoghCxezctcV8Acer)

{% hint style="info" %}
**Important:** A collider on the character root must not touch the ground. Otherwise, it can cause sliding on slopes.
{% endhint %}

<figure><img src="/files/lhKbA2hC3H5lMILfyPYZ" alt=""><figcaption><p>Keep the collider above the bottom edge to prevent sliding.</p></figcaption></figure>

#### Layer

Animal Controller uses the **Animal** layer by default. Set every GameObject in the character hierarchy to this layer.

Set attack triggers, interaction triggers, and unrelated colliders to **Ignore Raycast**.

#### Animator Controller

The Animator Controller is the core animation logic for `MAnimal`. It exchanges information with `MAnimal` about active animations, [States](/animal-controller/main-components/manimal-controller/states.md), [Modes](/animal-controller/main-components/manimal-controller/modes.md), and Stances.

![](/files/5ny82R529QfscGWlWRka)

Animation States use unique tags. `MAnimal` checks these tags against the active State.

Examples include `Locomotion`, `Jump`, `Idle`, `Fly`, and `Fall`.

![](/files/72Dzb3AN3KGKEX4Go29p)

### Where to go next

* [Guide to Use All Malbers Assets with AC](/animal-controller/quickstart/guide-to-use-malbers-unity-assets-with-ac.md) — set up a character and get moving.
* [States](/animal-controller/main-components/manimal-controller/states.md) — explore the locomotion state machine.
* [Modes](/animal-controller/main-components/manimal-controller/modes.md) and [Stances](/animal-controller/main-components/manimal-controller/stances.md) — create abilities and animation variations.
* [AI](/animal-controller/main-components/ai.md) — build AI characters with the Brain, Tasks, and Decisions.
* [Stats](/animal-controller/global-components/stats.md) and [Weapon Manager](/animal-controller/main-components/weapon-manager.md) — configure damage, equipment, and character stats.