/unity-animation

name: unity-animation
description: >
  Unity 6.3 LTS character animation with the Animator (Mecanim): states and transitions, blend
  trees, Avatar Mask layers, root motion and humanoid IK. Use for SetTrigger wiring, a transition
  that lags or never fires, sliding root motion, or an upper-body layer overriding the legs. Not
  for AI state machines (`game-ai`), juice (`game-feel`) or Godot (`godot-animation`).

Unity Animation (Animator / Mecanim)

Control animation state with the `Animator` and Animator Controllers in Unity 6.3 LTS (6000.3): parameters, transitions, blend trees, layers and humanoid IK. A `.controller` file is text YAML, so you can read its parameters and states without the Editor, and build one from editor code instead of the Animator window.

When to use

• Connecting clips into a state machine, driving it from script, blending locomotion

(idle, walk, run), layering an upper-body action over movement, foot or hand IK.

• The project has `*.controller` and `*.anim` assets, or a rigged model with an Avatar.

**When not to use:** simple value tweens (UI fades, position lerps) → a coroutine in `unity-csharp-scripting`; when an NPC should attack or flee → `game-ai`; Timeline cutscenes have no skill here. 2D sprite frame animation uses the same Animator with sprite keyframes.

Workflow

1. **Read the controller before writing code.** In the `.controller` YAML, `m_AnimatorParameters` lists each parameter's `m_Name` and `m_Type` (1 Float, 3 Int, 4 Bool, 9 Trigger), and each `AnimatorState` document has its `m_Name`. Your script's strings must match these exactly. 2. **Set the rig.** Humanoid IK and retargeting need the model imported as Humanoid (`animationType: 3` in the model's `.meta`); ask before changing a model's rig, since it rebuilds the Avatar. 3. **Drive locomotion with parameters** (`SetFloat`, `SetBool`, `SetInteger`, `SetTrigger`) through cached `Animator.StringToHash` ids, and let transitions resolve. Use `CrossFadeInFixedTime` only for deliberate scripted cuts such as hit reactions. 4. **Blend continuous motion with a blend tree** driven by one `Float` (or two for 2D directional) instead of many states and transitions. 5. **Layer upper-body actions** with an Avatar Mask and `SetLayerWeight`. 6. **Create or change controllers from code** when the Editor UI is not available (pattern 3), then re-read the YAML to confirm. 7. **Verify** with the checks below.

Patterns

1. Parameters from script with cached hashes

using UnityEngine;

[RequireComponent(typeof(Animator))]
public class CharacterAnim : MonoBehaviour
{
    private static readonly int Speed = Animator.StringToHash("Speed");
    private static readonly int IsGrounded = Animator.StringToHash("IsGrounded");
    private static readonly int Jump = Animator.StringToHash("Jump");
    private Animator _anim;

    private void Awake() => _anim = GetComponent<Animator>();

    public void Tick(float planarSpeed, bool grounded)
    {
        _anim.SetFloat(Speed, planarSpeed, 0.1f, Time.deltaTime);  // damped: no snapping
        _anim.SetBool(IsGrounded, grounded);
    }

    public void DoJump() => _anim.SetTrigger(Jump);   // consumed by the next matching transition
}

2. Wait for the state you just triggered

private System.Collections.IEnumerator AfterAttack()
{
    yield return null;   // let the Animator start the transition
    // During a transition the current state is the one being left; read the next one.
    AnimatorStateInfo info = _anim.IsInTransition(0)
        ? _anim.GetNextAnimatorStateInfo(0)
        : _anim.GetCurrentAnimatorStateInfo(0);
    yield return new WaitForSeconds(info.length);   // approximate inside blend trees
}

3. Build a controller from editor code

Put this in an `Editor` folder. Run it from a menu item, from the Unity CLI with `unity command script eval --code 'BuildLocomotionController.Build();'`, or in batch mode with `-executeMethod BuildLocomotionController.Build`.

using UnityEditor;
using UnityEditor.Animations;
using UnityEngine;

public static class BuildLocomotionController
{
    [MenuItem("Tools/Build Locomotion Controller")]
    public static void Build()
    {
        if (!AssetDatabase.IsValidFolder("Assets/Animation"))
            AssetDatabase.CreateFolder("Assets", "Animation");

        var controller = AnimatorController.CreateAnimatorControllerAtPath("Assets/Animation/Player.controller");
        controller.AddParameter("Speed", AnimatorControllerParameterType.Float);
        controller.AddParameter("Jump", AnimatorControllerParameterType.Trigger);

        AnimatorStateMachine sm = controller.layers[0].stateMachine;
        AnimatorState locomotion = sm.AddState("Locomotion");   // assign a clip or blend tree as its motion
        AnimatorState jump = sm.AddState("Jump");
        sm.defaultState = locomotion;

        AnimatorStateTransition toJump = locomotion.AddTransition(jump);
        toJump.hasExitTime = false;   // react to the trigger at once
        toJump.duration = 0.1f;
        toJump.AddCondition(AnimatorConditionMode.If, 0f, "Jump");

        AnimatorStateTransition back = jump.AddTransition(locomotion);
        back.hasExitTime = true;      // return when the jump clip nearly ends
        back.exitTime = 0.9f;

        AssetDatabase.SaveAssets();
    }
}

Verify

• **No Editor needed:** grep the `.controller` for `m_AnimatorParameters` and the state

names, and compare them with every string or `StringToHash` argument in the scripts. A typo does nothing at runtime, so this catches the most common bug for free.

• **Unity CLI with a ready Editor:** `unity command animation.animator get_controller` reads a

controller's full structure (find its flags with `--help`). In Play mode, read live state: `unity command script eval --code 'var a = GameObject.Find("Player").GetComponent<Animator>(); return a.GetCurrentAnimatorStateInfo(0).IsName("L