godot-animation

Godot Animation (4.x)

Choose and drive the right animation tool: AnimationPlayer (clips), AnimationTree (blending/state machines), or Tween (short procedural moves). Targets Godot 4.7.

When to use

• Use when playing keyframed animations, blending walk/run/idle states, animating a sprite sheet, or tweening UI/objects in code.

When not to use: the movement logic that decides which state to play → godot-2d-movement; UI layout (vs. UI tweening) → godot-ui-control; shader-driven effects → godot-shaders.

Core workflow

1. Pick the tool:
   • AnimationPlayer — author keyframed clips (transforms, properties, method calls, audio, even other animations). The source of truth for clip data.
   • AnimationTree — blend and transition between those clips at runtime with a state machine and/or blend spaces. Needs an AnimationPlayer to pull clips from.
   • Tween — fire-and-forget procedural interpolation in code (create_tween()); ideal for UI pops, fades, and one-off moves.
2. For 2D sprite sheets: use AnimatedSprite2D + SpriteFrames, or keyframe the frame property in an AnimationPlayer.
3. For characters: build clips in AnimationPlayer, then add an AnimationTree (active = true), set its anim_player, and design an AnimationNodeStateMachine or AnimationNodeBlendSpace2D as the tree root.
4. Drive transitions from code via the playback object (travel) or by setting blend parameters.
5. React to clip events with the animation_finished signal and call/method tracks.

Patterns

1. AnimationPlayer: play a clip and await it

@onready var anim: AnimationPlayer = $AnimationPlayer

func attack() -> void:
    anim.play("attack")
    await anim.animation_finished     # resume after the clip ends
    anim.play("idle")

2. AnimationTree state machine: travel between states

@onready var tree: AnimationTree = $AnimationTree

func _ready() -> void:
    tree.active = true                # the tree drives animation; AnimationPlayer is the source

func set_state(state: StringName) -> void:
    # The playback object controls an AnimationNodeStateMachine root.
    var sm: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")
    sm.travel(state)                  # transitions using the graph's connections

func _physics_process(_d: float) -> void:
    set_state(&"run" if velocity.length() > 5.0 else &"idle")