Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-animation

godot-animation

Verified

Godot 4.7 animation APIs: AnimationPlayer, AnimationTree state machines, AnimatedSprite2D and create_tween() Tweens, with a headless state test. Use when travel() does nothing, an animation will not play, a tween snaps back or the log says "Animation not found". Not for easing choices (`game-feel`), sprite art (`create-game-assets`) or Unity (`unity-animation`).

Godot Animation (4.x)

Drive clips, blends and tweens the way Godot expects, then prove the names and states with a headless test. Targets Godot 4.7; check config/features in project.godot first.

Workflow

  1. Pick one owner per property. AnimationPlayer stores keyframed clips. An active AnimationTree plays those clips and owns their tracks, so code talks to the tree. Tween is for short code-driven moves (UI pops, fades, one-off motion).
  2. Characters: clips in an AnimationPlayer, then an AnimationTree with anim_player pointing at it, active = true, and an AnimationNodeStateMachine or blend space as tree_root. Sprite sheets: AnimatedSprite2D + SpriteFrames, or key frame in a clip.
  3. Drive from gameplay state, not input: pick the state from velocity and floor checks each physics tick and call travel(); set blend positions through parameters/ paths.
  4. Events: animation_finished for non-looping clips, Call Method tracks for frame-exact hits and footsteps.
  5. Verify before you finish (paths are relative to this skill's folder):
    • If godot-nodes-scenes is installed, run python3 ../godot-nodes-scenes/scripts/check_godot_project.py <project> after editing .tscn files; it catches broken resource paths and parent= node paths. The headless test below covers anim_player.
    • Run the scene headless and read the log, because Godot exits 0 after these errors: godot --headless --path <project> --quit-after 300 res://player.tscn > run.log 2>&1, then grep -nE "SCRIPT ERROR|^ERROR:" run.log. "Animation not found", "No such node" (bad travel() target) and "started with no Tweeners" all land there.
    • Copy assets/test_animation_states.gd to res://tests/, list the clip and state names the code uses, and run it with godot --headless --path <project> --script res://tests/test_animation_states.gd. Exit 0 means every clip exists, the tree is active and wired, and each state is reachable. CI wiring: godot-gdscript-headless-testing.
    • Timing and look need eyes: ask the user to play the scene and report anything that pops, slides or plays at the wrong moment.

Patterns

1. Play a clip and continue when it ends

@onready var anim: AnimationPlayer = $AnimationPlayer

func attack() -> void:
    anim.play("attack")                 # must not loop, or the signal never comes
    await anim.animation_finished
    anim.play("idle")

2. State machine: travel between states

@onready var tree: AnimationTree = $AnimationTree
@onready var playback: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")

func _physics_process(_delta: float) -> void:
    var moving := velocity.length() > 5.0
    playback.travel(&"run" if moving else &"idle")   # follows the graph's transitions

travel() walks the shortest path of enabled transitions; start(&"state") jumps there at once. Calling travel() every tick with the state it is already in does not restart it.

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

# tree.tree_root is an AnimationNodeBlendSpace2D with idle/run points placed in it.
func update_locomotion(input_dir: Vector2) -> void:
    tree.set("parameters/blend_position", input_dir)
# If the blend space is instead a child named "Move" in a blend tree/state machine,
# its parameter is "parameters/Move/blend_position".

4. Tween: pop a UI element in

func pop_in(node: Control) -> void:
    node.pivot_offset = node.size / 2                 # scale from the centre
    node.scale = Vector2.ZERO
    node.modulate.a = 0.0
    var tw := create_tween().set_parallel(true)
    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 ":"

Gotchas

  • Nothing animates and travel() does nothing → AnimationTree.active is false or anim_player is empty or points at the wrong node.
  • await anim.animation_finished never returns → the clip loops; looping clips do not emit it. Await a non-looping clip, or use a Call Method key at the end of the loop.
  • play("run") does not restart the clip → playing the clip that is already playing continues from the current position. Call stop() first or seek(0.0, true) to restart.
  • The tree and code fight → while an AnimationTree is active, AnimationPlayer.play() on the same clips is overridden. Change states through the tree.
  • Wrong parameter path → root parameters start at parameters/ (parameters/playback, parameters/blend_position); a named child adds its name (parameters/Move/blend_position). The tree's Inspector lists them under Parameters.
  • Tween (bound to ...): started with no Tweeners → create_tween() was called and nothing was added that frame, often in a branch that returns early. Create the tween right before adding steps.
  • Infinite loop detected and the tween dies → set_loops() (0 = forever) on a tween whose steps take no time, such as only tween_callback(). Add a tween_interval().
  • A tween stalls → node.create_tween() pauses while that node is outside the tree and dies when it is freed; get_tree().create_tween() is unbound. Tweens are one-shot: create a new one for each animation and kill() the old one so two do not fight.
  • Scale or rotation tween on a Container child snaps back → containers reset child transforms. In 4.7+ set offset_transform_enabled = true and tween offset_transform_scale/_rotation/_position, which are visual only.
  • Tweening modulate overwrites the other channels → tween "modulate:a" instead.
  • 3.x code → there is no Tween node and no yield; use create_tween() and await anim.animation_finished.

References

  • Read references/animation-tree-and-tween.md for transitions and advance conditions, root motion, one-shot and blend-tree nodes, Call Method tracks, SpriteFrames, and the full Tween API including the 4.7 tween_await().
  • assets/test_animation_states.gd is the headless test used in step 5.

Related skills

  • godot-2d-movement: the velocity and floor state that choose animations.
  • game-feel: which easing, squash and timing to use.
  • godot-ui-control: the UI that tweens animate.
  • godot-3d-essentials: 3D character scenes driven by AnimationTree.
  • godot-gdscript-headless-testing: running the animation test in CI.

Version notes

Last verified: 2026-11-11 against the Godot 4.7.2 class reference and a 4.7.2 headless run.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall