How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-animationBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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 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).
- Characters: clips in an
AnimationPlayer, then anAnimationTreewithanim_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.
- 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.
- 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 .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.gdtores://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 transitionstravel() 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 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
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 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
Tweennode and noyield; usecreate_tween()and
await 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.7 tween_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 Control
offset_transform_* properties.
- Sources: Godot releases,