animation
Godot animation developer — use when working with AnimationPlayer, AnimationTree, blend spaces, state machines, or skeletal IK.
SKILL.mdskills/animation/SKILL.md
GitHubGodot Animation
Expert Godot 4.x animation programmer specializing in AnimationPlayer, AnimationTree state machines, root motion, skeletal IK, and procedural overrides.
Overview
Godot's animation stack is layered: AnimationPlayer drives keyframe tracks; AnimationTree blends and routes between clips using blend spaces, state machines, and blend trees; Skeleton3D and SkeletonIK3D handle bone transforms and IK. In Godot 4.3+, AnimationMixer is the unified base class for both AnimationPlayer and AnimationTree, exposing shared playback and callback APIs. Always drive characters through AnimationTree — use AnimationPlayer only as a clip library.
Key Nodes & APIs
| Node / Class | Purpose | Key Methods / Properties |
|---|---|---|
AnimationPlayer |
Keyframe clip library and standalone playback | play(), queue(), stop(), animation_finished, CallbackTrack |
AnimationTree |
Blend graph controller; references an AnimationPlayer |
active, advance_expression_base_node, get_root_motion_position() |
AnimationMixer |
Base class for AnimationPlayer and AnimationTree (4.3+) |
animation_list, get_animation(), AnimationMixerPlaybackUpdated |
AnimationNodeStateMachine |
State machine node inside an AnimationTree |
travel(), get_current_node(), is_playing() |
AnimationNodeStateMachinePlayback |
Runtime playback handle retrieved via tree["parameters/playback"] |
travel(), start(), stop(), get_current_node() |
AnimationNodeBlendSpace1D |
1-D blend space for speed-based locomotion | Add points with add_blend_point() |
AnimationNodeBlendSpace2D |
2-D blend space for directional locomotion | set_blend_position() via tree parameters |
Skeleton3D |
Bone hierarchy; target for IK and procedural overrides | set_bone_global_pose_override(), find_bone() |
SkeletonIK3D |
FABRIK IK solver attached to Skeleton3D |
start(), stop(), target property |
BoneAttachment3D |
Attaches a node (weapon, prop) to a specific bone | bone_name, override_pose |
MeshInstance3D |
Renderable mesh; exposes blend shapes as property tracks | set_blend_shape_value(), get_blend_shape_value() |
Core Patterns
Pattern 1 — State Machine Travel
Retrieve the AnimationNodeStateMachinePlayback resource at runtime and call travel() to transition to a named state. AnimationTree.active must be true first.
# character.gd
@onready var tree: AnimationTree = $AnimationTree
@onready var playback: AnimationNodeStateMachinePlayback = tree["parameters/playback"]
func _ready() -> void:
tree.active = true
func jump() -> void:
playback.travel("Jump")
func land() -> void:
playback.travel("Idle")
func _physics_process(delta: float) -> void:
# Feed blend space parameter each frame
tree["parameters/LocomotionBlend/blend_position"] = velocity.length()
Pattern 2 — Root Motion on CharacterBody3D
Enable root motion in the AnimationTree inspector (root_motion_track set to the hips bone path). Each frame, extract the delta position and apply it to velocity so the physics engine handles collisions.
# root_motion_character.gd
@onready var tree: AnimationTree = $AnimationTree
@onready var body: CharacterBody3D = self
func _ready() -> void:
tree.active = true
func _physics_process(delta: float) -> void:
# Root motion gives world-space displacement for this frame
var root_motion: Vector3 = tree.get_root_motion_position()
var motion: Vector3 = global_transform.basis * root_motion
velocity = motion / delta # Convert displacement to velocity
move_and_slide()
Pattern 3 — Procedural Look-At Bone Override
After the animation pose is computed, override a specific bone's global pose to make a character look at a target. Set weight to blend smoothly between animated and procedural.
# look_at_head.gd
@onready var skeleton: Skeleton3D = $Armature/Skeleton3D
var head_bone_idx: int = -1
var look_target: Node3D
func _ready() -> void:
head_bone_idx = skeleton.find_bone("Head")
func _process(_delta: float) -> void:
if head_bone_idx == -1 or look_target == null:
return
var bone_origin: Vector3 = skeleton.get_bone_global_pose(head_bone_idx).origin
var look_dir: Vector3 = (look_target.global_position - bone_origin).normalized()
var look_transform := Transform3D(
Basis.looking_at(look_dir, Vector3.UP),
bone_origin
)
# weight 1.0 = fully procedural; true = persistent override
skeleton.set_bone_global_pose_override(head_bone_idx, look_transform, 1.0, true)
func stop_look_at() -> void:
skeleton.clear_bones_global_pose_override()
Pattern 4 — Await Animation Finished
Use await animation_player.animation_finished to sequence actions after a clip ends. Never use Timer nodes as a workaround — they drift from actual animation length.
# combo_attack.gd
@onready var anim: AnimationPlayer = $AnimationPlayer
func execute_combo() -> void:
anim.play("Attack1")
await anim.animation_finished
anim.play("Attack2")
await anim.animation_finished
anim.play("AttackFinisher")
await anim.animation_finished
anim.play("Idle")
Pattern 5 — CallbackTrack for Keyframe Events
Add a CallbackTrack inside an animation to call a method at a specific keyframe time. The method must exist on the node set as the animation player's owner or any node reachable from it.
# footstep_handler.gd — method called from CallbackTrack keyframe
extends CharacterBody3D
func _ready() -> void:
# CallbackTrack in AnimationPlayer calls "play_footstep" at keyframe time
pass
func play_footstep() -> void:
$FootstepAudio.play()
In the editor: open the animation, add a Method Track, set the node path to this node, and insert a key at the desired time with method name play_footstep.
Pattern 6 — Blend Shape Animation
Animate blend shapes by creating a Property Track targeting the path MeshInstance3D:blend_shapes/shape_name. You can also drive them from code.
# facial_expression.gd
@onready var face_mesh: MeshInstance3D = $Armature/FaceMesh
func set_smile(weight: float) -> void:
# weight is 0.0–1.0
face_mesh.set_blend_shape_value(
face_mesh.find_blend_shape_by_name("mouth_smile"),
weight
)
func _ready() -> void:
# AnimationPlayer property track path for the editor:
# Node path: Armature/FaceMesh
# Property: blend_shapes/mouth_smile
pass
Pattern 7 — BoneAttachment3D for Weapon/Prop
Attach a weapon or prop to a skeleton bone without manual transform math. BoneAttachment3D keeps itself parented to the bone every frame.
# weapon_equip.gd
@onready var attachment: BoneAttachment3D = $Armature/Skeleton3D/RightHandAttachment
@onready var weapon_scene: PackedScene = preload("res://weapons/sword.tscn")
func equip_weapon() -> void:
# BoneAttachment3D.bone_name is set in the inspector to "RightHand"
var weapon: Node3D = weapon_scene.instantiate()
attachment.add_child(weapon)
weapon.position = Vector3.ZERO # local offset relative to bone
Common Pitfalls
AnimationTree.activeis false. Callingplayback.travel()silently does nothing ifactiveis nottrue. Set it in_ready()and assert it in debug builds.advance_expression_base_nodenot set. When anAnimationTreeuses expression conditions in transitions (e.g.,speed > 0.5), Godot evaluates them on the node atadvance_expression_base_node. If left empty or pointing to the wrong node, all expression conditions fail and no transition ever fires. Set it to the character root node.- Root motion and
move_and_slide()fighting. If you apply root motion viavelocity = motion / deltabut also setvelocityelsewhere in the same frame (e.g., gravity), gravity wins or they cancel. Keep a clear single site that ownsvelocity.yseparately fromvelocity.xz. - Using
Timerinstead ofawait animation_finished. Timers drift if animation speed changes or the clip is interrupted. Always useawait animation_player.animation_finishedfor sequencing. - Driving a bone override before the skeleton pose is computed.
set_bone_global_pose_overridemust be called after_processanimates the skeleton, or it gets overwritten. Use_processwithNOTIFICATION_TRANSFORM_CHANGEDor call it in a deferred manner afterAnimationTreeupdates. - Forgetting to call
skeleton.clear_bones_global_pose_override(). Overrides persist until explicitly cleared. If a look-at or IK system is disabled, clear the override or the bone stays locked in the last procedural pose. - Blend shape property track path mismatch. The property track path must exactly match
blend_shapes/shape_nameon theMeshInstance3D. A renamed shape or wrong node path produces no error but animates nothing.
Performance
| Concern | Guidance |
|---|---|
| Animation update mode | Use AnimationPlayer.playback_process_mode = ANIMATION_PROCESS_PHYSICS for characters that call move_and_slide(); use ANIMATION_PROCESS_IDLE for UI and non-physics objects to avoid redundant updates. |
| Bone count | Keep character skeletons under 60 bones for mobile. Desktop is comfortable at 150+. High bone counts multiply the cost of every set_bone_global_pose_override() call. |
| IK solver cost | SkeletonIK3D runs FABRIK iteratively each physics frame. Limit max_iterations (default 10) and restrict it to characters in camera range. Disable start() when off-screen. |
AnimationTree graph complexity |
Deep nested blend trees with many AnimationNodeBlendTree layers add per-frame blend cost. Flatten where possible; merge infrequently toggled branches with AnimationNodeOneShot. |
| Root motion read | get_root_motion_position() is cheap (a single Vector3 read). Do not cache it across frames — it accumulates delta and resets each call. |
Anti-Patterns
| Wrong | Right |
|---|---|
await get_tree().create_timer(anim.current_animation_length).timeout |
await anim.animation_finished |
Set velocity from both root motion and a separate movement script |
Own velocity.xz exclusively through root motion; add velocity.y (gravity) separately |
Leave advance_expression_base_node empty |
Assign it to the character root node in the inspector |
Drive AnimationPlayer.play() directly for a character with AnimationTree active |
Always use playback.travel() through the state machine; direct play() bypasses blending |
BoneAttachment3D.override_pose = true without setting bone_idx |
Set both bone_name and let the node resolve bone_idx in _ready(), or set bone_idx explicitly |
Calling set_bone_global_pose_override every _ready() |
Call it every frame in _process() or _physics_process() — pose resets each frame from animation |
References
- AnimationPlayer
- AnimationTree
- AnimationMixer (4.3+)
- AnimationNodeStateMachine
- AnimationNodeStateMachinePlayback
- Skeleton3D
- SkeletonIK3D
- BoneAttachment3D
- Using AnimationTree (tutorial)
- Root motion tutorial
Delegate to
| Task | Skill |
|---|---|
| GDScript animation logic | godot:coder |
| Signal connections | godot:signals |
| API lookup | godot:docs |