unity-animation

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: unity-animation
description: >
  Unity 6 animation system guide. Use when working with Animator Controllers, animation state machines, blend trees, animation clips, Avatar system, humanoid rigs, root motion, animation events, Timeline, or Cinemachine. Based on Unity 6.3 LTS documentation.
---

# Unity Animation System

## Animation System Overview

Unity's Mecanim animation system is built on three interconnected components:

1. **Animation Clips** -- Unit pieces of motion (Idle, Walk, Run)
2. **Animator Controller** -- State machine organizing clips into a flowchart of states and transitions
3. **Avatar System** -- Maps humanoid character skeletons to a common internal format for retargeting

The **Animator** component is attached to GameObjects and references both the Animator Controller and Avatar assets needed for playback.

### Animation Types

- **Humanoid** -- Requires Avatar configuration; supports retargeting between different character rigs; 15-20% more CPU-intensive than Generic
- **Generic** -- Animates Transform or MonoBehaviour properties on specific hierarchies; not transferable between different hierarchies
- **Legacy** -- Older Animation component; use for simple single-shot or UI animations

## Animator Controller

An Animator Controller asset arranges Animation Clips and Transitions for a character or animated GameObject.

**Creating:** Right-click in Project window > Create > Animator Controller

### Key Components

- **States** -- Each state plays an associated Animation Clip or Blend Tree
- **Transitions** -- Define how and when the state machine switches between states
- **Parameters** -- Variables (Float, Int, Bool, Trigger) that scripts set to control transitions
- **Layers** -- Separate state machines for different body parts or animation concerns
- **Sub-State Machines** -- Nested state machines for hierarchical organization

### Parameters

Four types are available:

| Type | Description | Script Method |
|------|-------------|---------------|
| Float | Decimal number | `SetFloat()` / `GetFloat()` |
| Int | Whole number | `SetInteger()` / `GetInteger()` |
| Bool | True/false | `SetBool()` / `GetBool()` |
| Trigger | Auto-resetting bool | `SetTrigger()` / `ResetTrigger()` |

```csharp
using UnityEngine;

public class PlayerAnimController : MonoBehaviour
{
    Animator animator;

    void Start()
    {
        animator = GetComponent<Animator>();
    }

    void Update()
    {
        // Note: Uses legacy Input Manager for simplicity. See unity-input for the new Input System.
        float h = Input.GetAxis("Horizontal");
        float v = Input.GetAxis("Vertical");
        bool fire = Input.GetButtonDown("Fire1");

        animator.SetFloat("Forward", v);
        animator.SetFloat("Strafe", h);
        animator.SetBool("Fire", fire);
    }

    void OnCollisionEnter(Collision col)
    {
        if (col.gameObject.CompareTag("Enemy"))
        {
            animator.SetTrigger("Die");
        }
    }
}
```

### Animator Override Controller

Replaces animation clips in an Animator Controller while keeping structure, parameters, and logic intact. Useful for multiple characters sharing the same state machine but using different clips.

**Critical:** Set transition exit times in **normalized time** (not seconds) when using Override Controllers, or exit times may be ignored if override clips have different durations.

### Layers

- **Override mode** -- Replaces animation from previous layers
- **Additive mode** -- Adds animation on top of previous layers
- **Avatar Mask** -- Restricts a layer to specific body parts (e.g., upper body only)
- **Synced Layers** -- Reuse state machine structure with different clips

## State Machines and Transitions

### States

Each state in the Animator Controller represents a distinct action. Special states include:
- **Entry** -- Default entry point
- **Any State** -- Transitions from any current state
- **Exit** -- Exits the current state machine or sub-state mac