gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-animation
godot-animation
VerifiedGodot 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
- Pick one owner per property.
AnimationPlayerstores keyframed clips. An activeAnimationTreeplays those clips and owns their tracks, so code talks to the tree.Tweenis for short code-driven moves (UI pops, fades, one-off motion). - Characters: clips in an
AnimationPlayer, then anAnimationTreewithanim_playerpointing at it,active = true, and anAnimationNodeStateMachineor blend space astree_root. Sprite sheets:AnimatedSprite2D+SpriteFrames, or keyframein a clip. - Drive from gameplay state, not input: pick the state from velocity and floor checks
each physics tick and call
travel(); set blend positions throughparameters/paths. - Events:
animation_finishedfor non-looping clips, Call Method tracks for frame-exact hits and footsteps. - Verify before you finish (paths are relative to this skill's folder):
- If
godot-nodes-scenesis installed, runpython3 ../godot-nodes-scenes/scripts/check_godot_project.py <project>after editing.tscnfiles; it catches broken resource paths andparent=node paths. The headless test below coversanim_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, thengrep -nE "SCRIPT ERROR|^ERROR:" run.log. "Animation not found", "No such node" (badtravel()target) and "started with no Tweeners" all land there. - Copy
assets/test_animation_states.gdtores://tests/, list the clip and state names the code uses, and run it withgodot --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.
- If
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.activeis false oranim_playeris empty or points at the wrong node. await anim.animation_finishednever 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. Callstop()first orseek(0.0, true)to restart.- The tree and code fight → while an
AnimationTreeis 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 detectedand the tween dies →set_loops()(0 = forever) on a tween whose steps take no time, such as onlytween_callback(). Add atween_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 andkill()the old one so two do not fight. - Scale or rotation tween on a
Containerchild snaps back → containers reset child transforms. In 4.7+ setoffset_transform_enabled = trueand tweenoffset_transform_scale/_rotation/_position, which are visual only. - Tweening
modulateoverwrites the other channels → tween"modulate:a"instead. - 3.x code → there is no
Tweennode and noyield; usecreate_tween()andawait anim.animation_finished.
References
- Read
references/animation-tree-and-tween.mdfor transitions and advance conditions, root motion, one-shot and blend-tree nodes, Call Method tracks,SpriteFrames, and the full Tween API including the 4.7tween_await(). assets/test_animation_states.gdis 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.
- Godot 4.7.2 (August 2026) is the current stable release; 4.8 is in beta.
- New in 4.7:
Tween.tween_await()withAwaitTweener.set_timeout(), and the Controloffset_transform_*properties. - Sources: Godot releases, Godot 4.7 release page, AnimationTree, Tween.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |