godot-animation

SKILL.md

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

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.

For 2D sprite sheets: use AnimatedSprite2D + SpriteFrames, or keyframe the
frame property in an AnimationPlayer.

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.

Drive transitions from code via the playback object (travel) or by setting blend
parameters.

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")

3. Blend space: blend run direction by a 2D parameter

# Root is an AnimationNodeBlendSpace2D named "Move" with idle/run points placed in it.
func update_locomotion(input_dir: Vector2) -> void:
    # Parameter path = "parameters/<node name>/blend_position".
    tree.set("parameters/Move/blend_position", input_dir)

4. Tween: fade and scale a UI element (code-driven)

func pop_in(node: Control) -> void:
    node.scale = Vector2.ZERO
    node.modulate.a = 0.0
    var tw := create_tween()                          # bound to this node's tree
    tw.set_parallel(true)                             # run the two tweens together
    tw.tween_property(node, "scale", Vector2.ONE, 0.2) \
      .set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
    tw.tween_property(node, "modulate:a", 1.0, 0.2)   # sub-property via ":"

Pitfalls

AnimationTree.active left false → nothing animates and travel() appears to do
nothing. Set active = true and assign the anim_player path.

Wrong parameter path. Blend/condition paths are "parameters/<NodeName>/..." and
must match the node names in the tree exactly (e.g. "parameters/playback",
"parameters/Move/blend_position"). A typo silently no-ops.

AnimationPlayer and AnimationTree fighting. When an AnimationTree is active, don't
also call AnimationPlayer.play() for the same tracks — let the tree own playback.

3.x Tween node is gone. There is no Tween node to add in 4.x; create tweens in
code with create_tween() (which returns a Tween). They auto-start and free themselves.

Reusing a finished tween. A tween is one-shot; call create_tween() again for a new
animation. Use set_loops() for repetition.

yield/yield(anim, "...") is gone. Use await anim.animation_finished.

Sub-property tweens use a colon: "modulate:a", "position:x". Tweening the whole
property instead overwrites siblings.

References

For state machine transitions/conditions, root motion, one-shot/blend nodes, method &
call tracks, SpriteFrames/AnimatedSprite2D, and Tween easing/chaining/callbacks,
read references/animation-tree-and-tween.md.

Related skills

godot-2d-movement — supplies the velocity/state that selects animations.

godot-ui-control — UI that Tweens animate.

godot-3d-essentials — 3D character scenes driven by AnimationTree.

game-ai — state machines that mirror animation states.