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.
- Tween stalls when its node leaves the tree.
node.create_tween() pauses while that
node is outside the tree and dies when it is freed. Use get_tree().create_tween() for a
tween that must keep running while the node is out of the tree.
- Scale/rotation tween on a child of a
Container snaps back → the container resets
child transforms whenever it re-sorts. In 4.7+ set offset_transform_enabled = true and
tween offset_transform_scale / offset_transform_rotation / offset_transform_position
instead (visual only by default).
- 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.
1---2name: godot-animation3description: >4 Animate in Godot 4.7 three ways: AnimationPlayer for keyframed clips (incl. Call5 Method tracks), AnimationTree with state machines and blend spaces for6 character animation, and Tween for short procedural/UI tweens via create_tween().7 Use when working with AnimationPlayer/AnimationTree nodes in a .tscn, blending8 character states, sprite-sheet animation, or code-driven Tweens.9metadata:10 source: https://skillmd.com/skills/junmystery/godot-animation11---1213# Godot Animation (4.x)1415Choose and drive the right animation tool: `AnimationPlayer` (clips), `AnimationTree`16(blending/state machines), or `Tween` (short procedural moves). Targets **Godot 4.7**.1718## When to use1920- Use when playing keyframed animations, blending walk/run/idle states, animating a21 sprite sheet, or tweening UI/objects in code.2223**When *not* to use:** the movement *logic* that decides which state to play →24`godot-2d-movement`; UI layout (vs. UI tweening) → `godot-ui-control`; shader-driven25effects → `godot-shaders`.2627## Core workflow28291. **Pick the tool:**30 - `AnimationPlayer` — author keyframed clips (transforms, properties, method calls,31 audio, even other animations). The source of truth for clip data.32 - `AnimationTree` — blend and transition between those clips at runtime with a state33 machine and/or blend spaces. Needs an `AnimationPlayer` to pull clips from.34 - `Tween` — fire-and-forget procedural interpolation in code (`create_tween()`); ideal35 for UI pops, fades, and one-off moves.362. **For 2D sprite sheets:** use `AnimatedSprite2D` + `SpriteFrames`, or keyframe the37 `frame` property in an `AnimationPlayer`.383. **For characters:** build clips in `AnimationPlayer`, then add an `AnimationTree`39 (`active = true`), set its `anim_player`, and design an `AnimationNodeStateMachine` or40 `AnimationNodeBlendSpace2D` as the tree root.414. **Drive transitions from code** via the playback object (`travel`) or by setting blend42 parameters.435. **React to clip events** with the `animation_finished` signal and Call Method tracks.4445## Patterns4647### 1. AnimationPlayer: play a clip and await it4849```gdscript50@onready var anim: AnimationPlayer = $AnimationPlayer5152func attack() -> void:53 anim.play("attack")54 await anim.animation_finished # resume after the clip ends55 anim.play("idle")56```5758### 2. AnimationTree state machine: travel between states5960```gdscript61@onready var tree: AnimationTree = $AnimationTree6263func _ready() -> void:64 tree.active = true # the tree drives animation; AnimationPlayer is the source6566func set_state(state: StringName) -> void:67 # The playback object controls an AnimationNodeStateMachine root.68 var sm: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")69 sm.travel(state) # transitions using the graph's connections7071func _physics_process(_d: float) -> void:72 set_state(&"run" if velocity.length() > 5.0 else &"idle")73```7475### 3. Blend space: blend run direction by a 2D parameter7677```gdscript78# Root is an AnimationNodeBlendSpace2D named "Move" with idle/run points placed in it.79func update_locomotion(input_dir: Vector2) -> void:80 # Parameter path = "parameters/<node name>/blend_position".81 tree.set("parameters/Move/blend_position", input_dir)82```8384### 4. Tween: fade and scale a UI element (code-driven)8586```gdscript87func pop_in(node: Control) -> void:88 node.scale = Vector2.ZERO89 node.modulate.a = 0.090 var tw := create_tween() # bound to this node's tree91 tw.set_parallel(true) # run the two tweens together92 tw.tween_property(node, "scale", Vector2.ONE, 0.2) \93 .set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)94 tw.tween_property(node, "modulate:a", 1.0, 0.2) # sub-property via ":"95```9697## Pitfalls9899- **`AnimationTree.active` left false** → nothing animates and `travel()` appears to do100 nothing. Set `active = true` and assign the `anim_player` path.101- **Wrong parameter path.** Blend/condition paths are `"parameters/<NodeName>/..."` and102 must match the node names in the tree exactly (e.g. `"parameters/playback"`,103 `"parameters/Move/blend_position"`). A typo silently no-ops.104- **AnimationPlayer and AnimationTree fighting.** When an `AnimationTree` is active, don't105 also call `AnimationPlayer.play()` for the same tracks — let the tree own playback.106- **3.x Tween node is gone.** There is no `Tween` node to add in 4.x; create tweens in107 code with `create_tween()` (which returns a `Tween`). They auto-start and free themselves.108- **Tween stalls when its node leaves the tree.** `node.create_tween()` pauses while that109 node is outside the tree and dies when it is freed. Use `get_tree().create_tween()` for a110 tween that must keep running while the node is out of the tree.111- **Scale/rotation tween on a child of a `Container` snaps back** → the container resets112 child transforms whenever it re-sorts. In 4.7+ set `offset_transform_enabled = true` and113 tween `offset_transform_scale` / `offset_transform_rotation` / `offset_transform_position`114 instead (visual only by default).115- **Reusing a finished tween.** A tween is one-shot; call `create_tween()` again for a new116 animation. Use `set_loops()` for repetition.117- **`yield`/`yield(anim, "...")` is gone.** Use `await anim.animation_finished`.118- **Sub-property tweens** use a colon: `"modulate:a"`, `"position:x"`. Tweening the whole119 property instead overwrites siblings.120121## References122123- For state machine transitions/conditions, root motion, one-shot/blend nodes, method &124 call tracks, `SpriteFrames`/`AnimatedSprite2D`, and Tween easing/chaining/callbacks,125 read `references/animation-tree-and-tween.md`.126127## Related skills128129- `godot-2d-movement` — supplies the velocity/state that selects animations.130- `godot-ui-control` — UI that Tweens animate.131- `godot-3d-essentials` — 3D character scenes driven by AnimationTree.132- `game-ai` — state machines that mirror animation states.