Godot 4 AnimationTree: complete guide to character animation logic

Controlling game character animation in Godot 4 requires more than AnimationPlayer — the moment you need blended locomotion, directional movement, or state-driven transitions, you need AnimationTree. This guide walks through the complete setup: building a StateMachine, configuring BlendSpace2D for directional movement, setting transition conditions via GDScript, and importing GLB animations cleanly from Blender.

AnimationTree vs AnimationPlayer: which to use

AnimationPlayer plays individual animation clips. It handles simple cases well — a door opening, a platform moving, a UI fade. But for a character with idle, walk, run, jump, and attack states that blend together based on velocity and input, AnimationPlayer alone becomes unmanageable.

AnimationTree is a node that sits on top of AnimationPlayer and routes playback through a graph of logic nodes:

• StateMachine — drives transitions between named states via conditions
• BlendSpace1D / BlendSpace2D — interpolates between animations based on one or two float inputs
• BlendTree — mixes animations with adjustable weights
• Transition — simple crossfade between two clips

You can combine these: a StateMachine at the root with each state containing a BlendSpace2D for locomotion, a separate state for jumping, and a transition to an attack state. The hierarchy mirrors how a real character animation system works.

Setup basics:

@onready var anim_tree: AnimationTree = $AnimationTree
@onready var anim_player: AnimationPlayer = $AnimationPlayer

func _ready() -> void:
    anim_tree.active = true
    anim_tree["parameters/StateMachine/current_node"] = "Idle"

Set AnimationTree.anim_player in the inspector to point at your AnimationPlayer. Enable active either in the inspector or via code.

Setting up a StateMachine in Godot 4

In the AnimationTree panel (bottom editor area), double-click the node to open the graph view. Add a StateMachine node as the root (right-click → Add Node → StateMachine).

Inside the StateMachine:

1. Add states by right-clicking → Add Node → Animation and naming each one (Idle, Walk, Run, Jump, Attack)
2. Connect states with transition arrows (hover a state, then drag from the arrow that appears)
3. Set the Start node to your initial state

Each transition has:

• Switch Mode: Immediate (cuts instantly), Sync (waits for sync point), At End (waits for clip end)
• Auto Advance: triggers the transition when its condition becomes true
• Conditions: boolean or float comparisons you drive from code

To add a condition:

func _physics_process(delta: float) -> void:
    var velocity := CharacterBody3D(owner).velocity
    var speed := velocity.length()
    
    anim_tree["parameters/StateMachine/conditions/is_moving"] = speed > 0.1
    anim_tree["parameters/StateMachine/conditions/is_jumping"] = not CharacterBody3D(owner).is_on_floor()

In the StateMachine editor, on the transition from Idle → Walk, enable Auto Advance and set Condition to is_moving. The transition fires automatically once the condition is true.

BlendSpace2D for directional movement

BlendSpace2D maps two float inputs — typically horizontal and vertical velocity — to a 2D grid of animation clips. Godot interpolates between the nearest clips based on the current parameter values.

Inside the locomotion state, replace the Animation node with a BlendSpace2D:

1. Open the BlendSpace2D editor
2. Set X Axis label to velocity_x, range -1 to 1
3. Set Y Axis label to velocity_z, range -1 to 1
4. Add animation points at the corners and center:
   • (0, 0) → Idle
   • (0, 1) → Walk Forward
   • (0, -1) → Walk Backward
   • (-1, 0) → Strafe Left
   • (1, 0) → Strafe Right

Godot triangulates the grid automatically. Drive the blend position from code:

func _physics_process(delta: float) -> void:
    var local_vel := owner.global_transform.basis.inverse() * CharacterBody3D(owner).velocity
    var blend_pos := Vector2(local_vel.x, local_vel.z).limit_length(1.0)
    anim_tree["parameters/StateMachine/locomotion/BlendSpace2D/blend_position"] = blend_pos

Use local_vel (velocity in local space) so strafing maps to the correct animation axis regardless of character rotation.

Blend modes: The default Interpolated mode trilinearly blends between the three nearest points. Discrete switches abruptly to the nearest point — useful for 8-directional movement without foot-sliding artefacts. Carry interpolates but remembers the last blend position, reducing jitter when the character stops.

Importing GLB animations and connecting to AnimationTree

When exporting from Blender for Godot 4, use these GLB settings:

Format: glTF 2.0 (.glb)
Include → Animations: ✓
NLA Tracks: Push Down Actions Before Export
Rest & Ranges → Always Export Bones: ✓
Armature → Add Leaf Bones: ✗ (Godot adds its own)

On import into Godot 4:

1. Select the .glb in the FileSystem panel
2. Open Import tab → Animation → set Import to All Clips
3. Under Animation → Clips, rename animations to match your state names (Idle, Walk_Forward, Run)
4. Hit Reimport

The imported animations live inside the .glb resource. Reference them in AnimationPlayer by their clip name. Name your Blender NLA strips exactly what you want the Godot clip to be called — Godot preserves the strip name on import.

Set Loop Mode per clip in the Import tab:

Clips with wrong loop settings cause the StateMachine to hold or cut unexpectedly at At End transitions.

Pre-wiring checklist

• ☐Armature scale is 1.0, 1.0, 1.0 in Godot scene (apply scale in Blender before export)
• ☐No .001 bone name suffixes (check Blender outliner for duplicates)
• ☐Clip count matches your Blender NLA strip count
• ☐Loop flags set correctly per clip type
• ☐AnimationTree.anim_player points at the correct AnimationPlayer node
• ☐AnimationTree.active is true at runtime

Practical tips

• Nested StateMachines: build a top-level machine (Ground / Air / Ragdoll) with sub-machines for each state group. Keeps the graph readable as complexity grows.
• TimeScale parameter: use parameters/StateMachine/attack/TimeScale/scale to speed up a single clip without duplicating it.
• One-shot animations: use a OneShot node inside a BlendTree for hit reactions — it overlays for the clip duration then returns to the base state automatically.
• Root motion: enable Root Motion Track in AnimationTree and read anim_tree.get_root_motion_position() each physics frame to drive movement from animation data rather than from code velocity.

For production Godot 4 projects, browse free rigged characters and animated props at the BitSoul 3D marketplace — all GLB assets include clean bone hierarchies ready to wire into AnimationTree without rework.

This post is part of the Ultimate Guide to Free 3D Game Assets — BitSoul's complete reference for formats, texturing, rigging, optimization, and engine integration.

Build with real assets: grab the 98-model Character Pack on the BitSoul marketplace and drop them straight into your project.