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
*.controllerand*.animassets, 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
- Read the controller before writing code. In the
.controllerYAML,m_AnimatorParameterslists each parameter'sm_Nameandm_Type(1 Float, 3 Int, 4 Bool, 9 Trigger), and eachAnimatorStatedocument has itsm_Name. Your script's strings must match these exactly. - Set the rig. Humanoid IK and retargeting need the model imported as Humanoid
(
animationType: 3in the model's.meta); ask before changing a model's rig, since it rebuilds the Avatar. - Drive locomotion with parameters (
SetFloat,SetBool,SetInteger,SetTrigger) through cachedAnimator.StringToHashids, and let transitions resolve. UseCrossFadeInFixedTimeonly for deliberate scripted cuts such as hit reactions. - Blend continuous motion with a blend tree driven by one
Float(or two for 2D directional) instead of many states and transitions. - Layer upper-body actions with an Avatar Mask and
SetLayerWeight. - Create or change controllers from code when the Editor UI is not available (pattern 3), then re-read the YAML to confirm.
- 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
.controllerform_AnimatorParametersand the state names, and compare them with every string orStringToHashargument 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_controllerreads 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("Locomotion") + " speed=" + a.GetFloat("Speed");' - No CLI: a PlayMode test can instantiate the character prefab, set a parameter, wait a
few frames and assert
GetCurrentAnimatorStateInfo(0).IsName(...); seeunity-csharp-scriptingfor the test setup. - Visual quality (foot sliding, pops): ask the user to watch the Animator window in Play mode and report which transition fired and whether the feet slide.
Gotchas
- A trigger fires late or "sticks". A trigger stays set until a transition consumes it.
If none can consume it now, it fires later at a surprising moment.
ResetTriggerwhen the moment passes, or use aBoolfor sustained states. - Misspelled parameter names do nothing. No exception is thrown. Cache hashes and compare against the controller YAML (Verify).
- Transition feels laggy.
Has Exit Timewaits for the clip to reach its exit time. Turn it off for condition-driven transitions (jump, hit). - Character slides or will not move.
Apply Root Motionis on while code also moves the Transform, or the other way round. Choose root motion or scripted movement per character. - Upper-body layer overrides the whole body. Assign an Avatar Mask, pick Override or Additive, and set the layer weight.
CrossFadetakes far longer than expected. Its duration is normalized to the state's length.CrossFadeInFixedTimetakes seconds.- IK does nothing. IK only applies inside
OnAnimatorIK, needs IK Pass on the layer, and needs a Humanoid Avatar. - A re-enabled character restarts its animation. Deactivating the GameObject resets
its Animator; on re-enable it starts again in the default state with default parameters.
Set
animator.keepAnimatorStateOnDisable = truewhen that is not wanted, or reset the parameters yourself when you take the object from the pool.
References
- Read
references/blend-trees-and-ik.mdwhen setting up 1D or 2D blend trees, layers with Avatar Masks, humanoid IK (OnAnimatorIK, look-at, foot IK), or additive reference poses.
Related skills
unity-csharp-scripting: the MonoBehaviour and coroutine timing used above, and tests.unity-physics: moving the body that the animation shows.game-ai: deciding when to play which state.
Version notes
Last verified: 2026-11-11, against Unity 6000.3.28f1.
AnimatorControllerParameterTypevalues (Float 1, Int 3, Bool 4, Trigger 9) and the editor API in pattern 3 (CreateAnimatorControllerAtPath,AddParameter,AddState,AddTransition,AddCondition,hasExitTime,exitTime,duration), the model.metaanimationTypevalues (Human is 3) andAnimator.keepAnimatorStateOnDisablewere checked in the Unity C# reference source at tag 6000.3.28f1 (Modules/Animation/ScriptBindings/,Editor/Mono/Animation/,Editor/Mono/StateMachine.bindings.cs).animation.animator get_controlleris acom.unity.pipeline1.0.0-pre.1 command (pre-release): https://docs.unity3d.com/Packages/com.unity.pipeline@1.0/manual/index.html- Manual: https://docs.unity.com/en-us/engine/6000.3/manual and Scripting API
Animator.