9.2 Blend Trees & State Machines

You already know how to make an Animator play a single clip, like Idle or Run. That's fine as long as the character never changes what it's doing. The moment the player pushes forward while the character is standing still, you hit a wall: how do you go from the Idle pose to the Run pose without it looking like a jump cut in a badly edited video? The answer, in almost every game you've ever played, is that the engine never actually "switches" — it blends. This chapter is about how Unity's Animator does that blending, and how you drive it from C#.

1. Why You Rarely Play Just One Clip

If you switch clips with animator.Play("Run"), Unity throws away whatever pose is currently showing and jumps straight to frame 0 of Run on the very next frame. There's no in-between. The legs teleport from one shape to another in a single frame.

The fix nearly every game uses is blending: instead of switching instantly, you mix two (or more) poses together using a blend weight (a number from 0 to 1 saying how much of a clip's pose counts toward the final result). A weight of 1.0 means "100% this clip." A weight of 0.0 means "0% this clip, ignore it completely." A weight of 0.5 means "average this clip's pose and another clip's pose 50/50, bone by bone."

Unity's Animator gives you three tools that are all really the same idea — blend by weight — applied in different situations:

• Cross-fading — hand weight off from one state to another over time, for a one-off transition like "start jumping."
• Blend Trees — hand weight between several clips continuously, driven by a live number like speed, so movement never has a seam.
• Layers — blend a whole body region (say, the upper body) on top of a base layer, using a mask to say exactly which bones are affected.

This chapter builds all three, then shows the state machine that decides which state (a clip or a blend tree) is active, and how to drive the whole thing from your own C# scripts.

2. Cross-Fading Between Two Clips

The simplest blend is a cross-fade: tell the Animator "start playing this state, and blend into it over N seconds." Unity lowers the old state's weight and raises the new one's, every frame, until the new state reaches a weight of 1.0 and fully owns the pose.

using UnityEngine;

public class SimpleCrossFade : MonoBehaviour
{
    public Animator animator;

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.R))
        {
            // Blend from whatever is playing right now into "Run"
            // over 0.25 seconds.
            animator.CrossFade("Run", 0.25f);
        }
    }
}

There's no console output for this — it's a visual effect you'd see in the Game view. But you can trace exactly what weight Unity is using each frame during that 0.25 second blend:

"Pose" means the position and rotation of every bone in the character's rig (from the skinned mesh chapter). Each frame, Unity samples both clips at the current time, multiplies every bone's transform by that clip's weight, and adds the two results together. That's why a half-and-half blend between a standing pose and a running pose looks like a smooth, physically plausible in-between body — not two characters overlapping like a ghost.

CrossFade(stateName, duration) takes the name of the state to blend into and how many seconds the blend should take. There's a related method, CrossFadeInFixedTime, which measures the transition duration in real seconds no matter how long the target clip is (handy when timing must be exact, like syncing to a sound effect).

Cross-fading is great for one-off, code-triggered transitions. But locomotion — walking that gradually speeds up into running — needs something that blends continuously as a number changes, not just once between two named clips. That's what a blend tree is for.

3. 1D Blend Trees: From Idle to Walk to Run

A Blend Tree is a special kind of state in the Animator: instead of holding one clip, it holds several clips and blends between them based on one or more parameters (named values stored on the Animator, covered fully in section 5). A 1D Blend Tree uses exactly one float parameter — typically called Speed — and a list of motions, each tagged with a threshold: the parameter value at which that motion should play at full weight.

You build a 1D Blend Tree in the Animator window (right-click a state, Create State, From New Blend Tree, then open it), not in code. Inside it you'd set:

• Blend Type: 1D
• Parameter: Speed
• Motion list: Idle at threshold 0, Walk at threshold 2, Run at threshold 6

At runtime, Unity looks at the current value of Speed, finds the two motions whose thresholds it falls between, and blends only those two. Everything else gets weight 0.

The math is linear interpolation (from the math/vectors chapter): find how far Speed is between the two neighboring thresholds as a fraction from 0 to 1, and use that fraction as the weight split. As Speed keeps rising past 2.0, Walk's weight keeps falling and Run's keeps rising, with no seam — no frame where one clip abruptly replaces another.

Your job in C# is just to keep Speed up to date, usually smoothed so it doesn't jump instantly when the player taps a key:

using UnityEngine;

public class Locomotion1D : MonoBehaviour
{
    public Animator animator;
    public float maxSpeed = 6f;
    public float acceleration = 10f;

    private float currentSpeed;

    void Update()
    {
        float input = Mathf.Clamp01(Mathf.Abs(Input.GetAxis("Vertical")));
        float targetSpeed = input * maxSpeed;

        currentSpeed = Mathf.MoveTowards(currentSpeed, targetSpeed, acceleration * Time.deltaTime);
        animator.SetFloat("Speed", currentSpeed);
    }
}

Worked trace: say the player holds "forward" fully (Input.GetAxis("Vertical") == 1), so targetSpeed = 6. Starting from currentSpeed = 0, with acceleration = 10 and a frame time of about 0.016s (60 FPS), currentSpeed rises roughly 0.16 per frame: 0 -> 0.16 -> 0.32 -> ... until it reaches 6 about 0.6 seconds later. While that's happening, the blend tree is smoothly sliding from Idle through Walk and into Run, exactly the way the diagram above describes, frame by frame.

4. 2D Blend Trees: Blending by Movement Direction

A 2D Blend Tree works the same way but uses two float parameters at once — usually MoveX (strafe, left/right) and MoveZ (forward/back) — so you can blend between clips laid out over a 2D plane instead of a single line. This is what lets a character strafe-run diagonally with a blend of RunForward and RunRight, instead of only ever running straight ahead.

In the Animator window you'd pick a 2D blend type and place each motion at a 2D point:

Unity offers a few different 2D blend types, and picking the right one matters:

• Simple Directional — best when you have one motion at the center (idle) plus motions around it with no two motions pointing in nearly the same direction. Cheap and predictable.
• Freeform Directional — handles motions that share very similar directions (like a run and a sprint both pointing "forward") without them fighting each other for weight.
• Freeform Cartesian — treats the two parameters as plain X/Y coordinates instead of a direction and speed. Good when the axes aren't really "a direction," like blending by two unrelated stats.

For a normal 8-direction movement set (forward, back, left, right, and the four diagonals), Freeform Directional is the usual choice. Driving it from C# means keeping MoveX and MoveZ updated with the character's local movement direction:

using UnityEngine;

public class Locomotion2D : MonoBehaviour
{
    public Animator animator;
    public float smoothTime = 0.1f;

    private Vector2 currentBlend;
    private Vector2 blendVelocity;

    void Update()
    {
        float h = Input.GetAxisRaw("Horizontal"); // strafe: -1 left, +1 right
        float v = Input.GetAxisRaw("Vertical");   // -1 back, +1 forward

        Vector2 targetBlend = new Vector2(h, v);
        currentBlend = Vector2.SmoothDamp(currentBlend, targetBlend, ref blendVelocity, smoothTime);

        animator.SetFloat("MoveX", currentBlend.x);
        animator.SetFloat("MoveZ", currentBlend.y);
    }
}

Worked trace: the player holds forward and right together, so h = 1, v = 1, and targetBlend = (1, 1). Vector2.SmoothDamp eases currentBlend toward that point over roughly smoothTime seconds instead of snapping there. Once currentBlend settles near (1, 1), the 2D blend tree finds the motions closest to that direction — likely RunForward and RunRight, or a dedicated RunForwardRight clip if you authored one — and blends them so the character visibly runs diagonally, feet matching the direction of travel.

5. The Animator State Machine: States, Transitions, and Parameters

Blend trees decide how to blend within one node. The state machine decides which node is active at all — is the character in Locomotion, or Jump, or Attack? You build it visually in the Animator window as a graph of boxes and arrows.

• State — a box in the graph. Holds either a single clip or a Blend Tree.
• Transition — an arrow from one state to another, with a list of conditions that must all be true for it to fire.
• Parameter — a named value stored on the Animator: Float, Int, Bool, or Trigger. Transitions read them to decide when to fire; blend trees read the Float ones to decide how to blend.
• Any State — a special node whose outgoing transitions can fire no matter which state is currently active. Good for things that can interrupt anything, like getting hit or dying.

Trigger deserves special attention: unlike Bool, which stays whatever you last set it to, a Trigger is "armed" by SetTrigger and then automatically cleared the moment a transition that uses it actually fires. It behaves like a one-shot event, which is exactly what you want for "jump now" — you don't want the character to keep re-jumping every frame just because a bool stayed true.

You can inspect what parameters exist on an Animator entirely from code, which is handy for debugging a controller you didn't build yourself:

using UnityEngine;

public class ListAnimatorParameters : MonoBehaviour
{
    public Animator animator;

    void Start()
    {
        foreach (AnimatorControllerParameter p in animator.parameters)
        {
            Debug.Log(p.name + " : " + p.type);
        }
    }
}

Console output for a typical locomotion controller:

Speed : Float
Grounded : Bool
Jump : Trigger

Note that the parameter names are plain strings, and they're case-sensitive. That single fact causes more silent bugs than almost anything else in this chapter, covered in section 10.

6. Transition Duration and Interruption

Every transition arrow in the graph has its own blend settings, separate from the CrossFade call you write in code. The two settings that matter most for a beginner:

• Has Exit Time — if checked, the transition can only fire once the current state's playback reaches a certain normalized time (its position in the clip's loop, expressed 0 to 1 regardless of the clip's actual length in seconds). If unchecked, the transition can fire the instant its conditions become true.
• Transition Duration — how long the blend from the old state into the new one takes. Set to 0, it's an instant snap, not a blend, even though it's technically still a "transition."

These two settings interact in a way that trips up almost everyone the first time:

For fast, responsive actions (jump, dodge, attack cancels) you usually want Has Exit Time off, so the transition fires the instant the condition is true. For animations that should always finish playing once started (a big finisher move, a death animation), you keep it on.

Interrupting a Transition Mid-Blend

Sometimes a transition is already blending when a new, more urgent condition becomes true — the player was blending from Walk into Attack, and now wants to Jump instead. The Interruption Source setting on a transition controls whether that's allowed, and if so, which state's own outgoing transitions are allowed to interrupt it (None, Current State, Next State, or both).

With interruption allowed, the blend doesn't restart from scratch — it keeps whatever mix of the old state is already showing and redirects the incoming half toward the new target. Without it, the character has to finish blending fully into B before a transition out of B can even be considered, which feels laggy for anything that needs to cancel quickly.

7. Layers and Avatar Masks: Aiming While Running

Everything so far blends whole-body poses. But often you want two things happening at once on different parts of the body: legs running from the locomotion state machine, while the upper body independently aims at a target. That's what Layers are for.

The Animator window has a Layers panel. Each layer is its own independent state machine, and its result is blended on top of the layers below it:

• Base Layer — weight always 1.0, affects the whole body, holds your main Locomotion/Jump/etc. state machine.
• Additional layer, e.g. "UpperBodyAim" — its own small state machine (maybe just one Aim state), blend mode set to Override, and an Avatar Mask assigned that only includes the spine, arms, and head bones.

An Avatar Mask is an asset (right-click, Create, Avatar Mask) with a checkbox per bone group. Unmask the legs on the aim layer's mask, and whatever that layer plays simply can't touch leg bones at all — no matter what clip is in it, the legs stay under the base layer's control.

using UnityEngine;

public class AimLayerController : MonoBehaviour
{
    public Animator animator;
    private int aimLayerIndex;

    void Start()
    {
        aimLayerIndex = animator.GetLayerIndex("UpperBodyAim");
    }

    void Update()
    {
        bool isAiming = Input.GetMouseButton(1);
        float targetWeight = isAiming ? 1f : 0f;

        float current = animator.GetLayerWeight(aimLayerIndex);
        animator.SetLayerWeight(aimLayerIndex, Mathf.MoveTowards(current, targetWeight, 5f * Time.deltaTime));
    }
}

Worked trace: while the player holds the right mouse button, targetWeight is 1, and SetLayerWeight ramps the aim layer's weight up from 0 to 1 over about 0.2 seconds (1 / 5). During that ramp, the character's legs keep running exactly as the base layer says, while the upper body gradually rotates into the aim pose — not a snap, a proper cross-fade of just the masked bones.

8. Root Motion vs In-Place Animation

There are two very different ways an animation clip can represent movement, and mixing them up is a classic source of "my character glides" or "my character's feet slide on the ground" bugs.

Toggle this with the Apply Root Motion checkbox on the Animator component, or the same flag in code, animator.applyRootMotion. When it's on, Unity calls a special method, OnAnimatorMove, once per frame right after evaluating the animation, and moving the object there instead of in Update keeps movement perfectly matched to the feet:

using UnityEngine;

[RequireComponent(typeof(Animator))]
public class RootMotionRelay : MonoBehaviour
{
    private Animator animator;

    void Awake()
    {
        animator = GetComponent<Animator>();
        animator.applyRootMotion = true;
    }

    // Unity calls this automatically, once per frame, only while
    // Apply Root Motion is enabled.
    void OnAnimatorMove()
    {
        transform.position += animator.deltaPosition;
        transform.rotation *= animator.deltaRotation;
    }
}

Root motion looks great for grounded, foot-perfectly-matched movement, but it's harder to control precisely (turning radius and speed are baked into the clip, not a parameter you tune), and it doesn't work well with physics-driven movement. Most action games use in-place clips for locomotion and move the character with code (a CharacterController or Rigidbody, from the physics chapters) driven by the same Speed/MoveX/MoveZ values feeding the blend tree, so the visual animation speed and the actual movement speed always agree. Root motion tends to be reserved for animation-critical moments like a scripted attack lunge or a climb, where exact foot placement matters more than precise player control.

9. Driving and Reading the Animator from C#

Everything above happens because code sets parameters and the Animator reacts. This section is the reference for both directions: writing parameters in, and reading state back out.

Writing Parameters

using UnityEngine;

public class AnimatorParameterDemo : MonoBehaviour
{
    public Animator animator;
    public bool isGrounded;

    void Update()
    {
        // Float: drives 1D/2D blend trees directly
        float speed = new Vector3(Input.GetAxis("Horizontal"), 0f, Input.GetAxis("Vertical")).magnitude;
        animator.SetFloat("Speed", speed);

        // Float with built-in smoothing: eases toward the value over
        // dampTime seconds instead of snapping to it in one frame
        animator.SetFloat("Speed", speed, 0.1f, Time.deltaTime);

        // Bool: stays true or false until you change it again
        animator.SetBool("Grounded", isGrounded);

        // Int: useful for combo steps, weapon type, etc.
        animator.SetInteger("ComboIndex", 2);

        // Trigger: fires once; Unity clears it automatically once a
        // transition that consumes it actually fires
        if (Input.GetButtonDown("Jump"))
        {
            animator.SetTrigger("Jump");
        }

        // ResetTrigger: cancels a trigger that has not fired yet
        if (Input.GetKeyDown(KeyCode.Escape))
        {
            animator.ResetTrigger("Jump");
        }
    }
}

Note the two-argument and four-argument overloads of SetFloat both exist on purpose. The plain one snaps the parameter to the exact value immediately, which is fine if you're already smoothing the value yourself (like Locomotion1D in section 3 does with Mathf.MoveTowards). The dampTime overload lets the Animator do that smoothing for you, which is convenient but gives you less control over exactly how the smoothing behaves.

Reading State Back

using UnityEngine;

public class AnimatorStateReader : MonoBehaviour
{
    public Animator animator;

    void Update()
    {
        AnimatorStateInfo state = animator.GetCurrentAnimatorStateInfo(0);

        if (state.IsName("Jump") && state.normalizedTime >= 1f)
        {
            Debug.Log("Jump clip finished playing");
        }

        if (animator.IsInTransition(0))
        {
            AnimatorTransitionInfo t = animator.GetAnimatorTransitionInfo(0);
            Debug.Log("Blending, progress = " + t.normalizedTime);
        }
    }
}

GetCurrentAnimatorStateInfo(0) asks about layer 0 (the base layer; pass 1 for the second layer, and so on). IsName checks the state's name (or its full path, like "Base Layer.Jump", if names collide across sub-state machines). normalizedTime is the same 0-to-1-per-loop value from section 6, except it keeps counting past 1.0 for looping clips (1.2 means "20% into the second loop") instead of wrapping back to 0, which is exactly why >= 1f is the right check for "has this non-looping clip finished." Once the Jump state's clip has played through fully, the console prints once; while any transition is actively blending, it prints the blend progress every frame.

10. The Common Bug: Transitions That Never Fire, or That Snap

Almost every beginner hits one of these. They're worth memorizing because the Animator gives you no error message for any of them — the transition just quietly doesn't do what you expected.

A Typo in the Parameter Name

// The Animator Controller has a Trigger parameter named exactly "Jump".
animator.SetTrigger("jump"); // wrong case -> silently does nothing

// Fix: match the exact, case-sensitive name shown in the Animator window
animator.SetTrigger("Jump");

Parameter names are plain strings matched by exact spelling and case. "Jump" and "jump" are two different parameters as far as the Animator is concerned. Recent versions of Unity log a console warning for a missing parameter name, but older versions do nothing at all — the trigger is just lost. A common fix is to store the name once as a const string or cache its hash with Animator.StringToHash, so a typo becomes a compile error instead of a silent bug.

Has Exit Time Left On By Accident

Covered in section 6, but worth repeating because it's the single most common "my transition never fires (quickly)" report: a looping state with Has Exit Time checked and Exit Time near 1.0 makes the transition wait for the clip to nearly finish its current loop before it's even allowed to check its conditions. If a state is meant to be interruptible immediately (movement, most actions), uncheck Has Exit Time.

Zero Transition Duration

A Transition Duration of 0 makes the "transition" an instant snap rather than a blend — the same popping problem from section 1, just hidden inside the state machine instead of an explicit Play call. If a change looks like a jump cut even though you're using the state machine and not calling Play directly, check the duration on the transition arrow, not your code.

Comparing Floats for Exact Equality

A transition condition like Speed Equals 0 can fail to ever fire, because a smoothed float (from Mathf.MoveTowards, SmoothDamp, or the dampTime overload of SetFloat) almost never lands on exactly 0.0 — it approaches it and stops a tiny fraction away. Use Less/Greater conditions with a small threshold (Speed Less 0.05) instead of Equals for any float that's being smoothed.

A Trigger Set on a Disabled Object

Calling SetTrigger on an Animator whose GameObject is currently inactive does nothing — there's no error, the call is simply a no-op. If you're queuing up an action (like "jump the instant we land") on a character that might be disabled for a frame (object pooling, a cutscene toggling visibility), check gameObject.activeInHierarchy before relying on a trigger surviving that gap.

11. Putting It Together: A Full Locomotion Controller

Here's how the pieces from this chapter combine in one script driving a full Animator Controller: a 1D blend tree for locomotion, a trigger for jumping, and an aim layer.

The Animator Controller itself (built in the Animator window, not in code) would have:

• Parameters: Speed (Float), Grounded (Bool), Jump (Trigger)
• States: Locomotion (1D Blend Tree on Speed: Idle@0, Walk@2, Run@6), Jump (single clip)
• Transitions: Locomotion -> Jump on the Jump trigger, Has Exit Time off, duration 0.1s. Jump -> Locomotion on Grounded == true, Has Exit Time on at 0.85, duration 0.15s.
• Layers: Base (this state machine), plus UpperBodyAim masked to spine/arms/head.

using UnityEngine;

[RequireComponent(typeof(Animator))]
public class PlayerAnimatorDriver : MonoBehaviour
{
    private Animator animator;
    private int aimLayer;

    public float speed;
    public bool isGrounded = true;

    void Awake()
    {
        animator = GetComponent<Animator>();
        aimLayer = animator.GetLayerIndex("UpperBodyAim");
    }

    void Update()
    {
        // 1. Locomotion: drive the 1D blend tree
        float input = Input.GetAxis("Vertical");
        speed = Mathf.MoveTowards(speed, input * 6f, 10f * Time.deltaTime);
        animator.SetFloat("Speed", speed);

        // 2. Jump: fire a trigger, guarded by our own grounded check
        if (isGrounded && Input.GetButtonDown("Jump"))
        {
            animator.SetTrigger("Jump");
        }
        animator.SetBool("Grounded", isGrounded);

        // 3. Aim layer: fade in/out with the right mouse button
        bool aiming = Input.GetMouseButton(1);
        float targetWeight = aiming ? 1f : 0f;
        float current = animator.GetLayerWeight(aimLayer);
        animator.SetLayerWeight(aimLayer, Mathf.MoveTowards(current, targetWeight, 5f * Time.deltaTime));
    }
}

Trace one moment: the player is standing still (speed near 0, Locomotion showing mostly Idle), holds the aim button (the UpperBodyAim layer ramps toward weight 1, so the upper body turns to aim while the legs stay idle), then presses forward and jump at nearly the same instant. speed starts ramping toward 6, sliding Locomotion's blend tree from Idle toward Walk; SetTrigger("Jump") fires the Locomotion -> Jump transition immediately, since that transition has Has Exit Time off. All three systems — the blend tree, the trigger-driven state switch, and the independent aim layer — run at the same time without stepping on each other, because each one only touches the parameters and bones it owns.

12. Glossary

• Blend — mixing two or more animation poses together using weights instead of switching instantly.
• Blend weight — a 0 to 1 number saying how much a clip or state contributes to the final pose.
• Cross-fade — smoothly shifting weight from one Animator state to another over a set duration.
• Blend Tree — an Animator state that blends between several motions based on one or more parameters.
• 1D Blend Tree — a blend tree driven by a single float parameter, like Speed.
• 2D Blend Tree — a blend tree driven by two float parameters at once, usually a movement direction.
• Threshold — the parameter value at which a motion in a blend tree plays at full weight.
• State machine — the graph of states and transitions that decides which state is currently active.
• State — a node in the Animator graph holding a single clip or a Blend Tree.
• Transition — a directed connection between two states with conditions deciding when it fires.
• Parameter — a named value (Float, Int, Bool, Trigger) on the Animator, read by transitions and blend trees.
• Trigger — a parameter that stays armed until a transition consumes it, then resets automatically.
• Any State — a special node whose outgoing transitions can fire regardless of the currently active state.
• Has Exit Time — a transition setting that delays it until the current state's clip reaches a given normalized time.
• Transition Duration — how long the blend between the old and new state takes.
• Interruption source — which state's transitions are allowed to redirect a transition that's already blending.
• Layer — an independent state machine in the Animator whose result blends on top of layers below it.
• Avatar Mask — an asset listing exactly which bones a layer is allowed to affect.
• Root motion — movement baked into a clip's root bone, applied to the GameObject's transform by the Animator.
• In-place animation — a clip whose root bone does not move, so the object must be moved by code instead.
• Normalized time — a clip's playback position expressed as a 0 to 1 fraction of one loop.

13. Exercises

void OnFire(InputValue value)
{
    animator.SetTrigger("attack");
}

void OnFire(InputValue value)
{
    animator.SetTrigger("Attack"); // matches the Animator's parameter name exactly
}

using UnityEngine;

public class ShiftLayerFader : MonoBehaviour
{
    public Animator animator;
    private int layerIndex;

    void Start()
    {
        layerIndex = animator.GetLayerIndex("UpperBodyAim");
    }

    void Update()
    {
        bool held = Input.GetKey(KeyCode.LeftShift);
        float targetWeight = held ? 1f : 0f;

        // a full 0 -> 1 fade in 0.2s means a rate of 1 / 0.2 = 5 per second
        float current = animator.GetLayerWeight(layerIndex);
        animator.SetLayerWeight(layerIndex, Mathf.MoveTowards(current, targetWeight, 5f * Time.deltaTime));
    }
}

That covers blending end to end: cross-fading for one-off transitions, 1D and 2D blend trees for continuous locomotion, the state machine that decides which state is active and when, transition timing and interruption, layers and masks for independent body regions, root motion versus in-place movement, and the C# calls that drive and read all of it. The next time a character in your game needs to go from standing still to a full sprint, or aim a weapon while running, you now know exactly which Animator tool handles which half of the job.