godot-animation-player

name	godot-animation-player
description	Drives Godot AnimationPlayer timelines: value/method/audio/bezier tracks, RESET tracks, root_motion, queue/blend_times, and CALL_MODE_DISCRETE callbacks. Use when the user wants cutscenes, UI transitions, prop playback, or procedural track_insert_key. Trigger: animation_finished, animation_set_next, seek. Not for AnimationTree BlendSpace2D/StateMachine locomotion and not AnimatedSprite2D SpriteFrames. Never use CALL_MODE_CONTINUOUS for one-shot method tracks.
version	1.0.1

When to Use

Use this skill for timeline-based keyframe animations, cutscenes, character animations, complex UI transitions, root motion extraction, and procedural animation generation in Godot 4.7. Trigger keywords: AnimationPlayer, Animation, track_insert_key, root_motion, animation_finished, RESET_track, call_mode, animation_set_next, queue, blend_times.

Prerequisites

• Godot 4.7 project.
• Ensure AnimationPlayer node is present in the scene.
• Read the appropriate script from scripts/ before implementing the corresponding pattern (see Procedure).

Procedure

1. Track Types Deep Dive

Value Tracks (Property Animation)

# Animate ANY property: position, color, volume, custom variables
var anim := Animation.new()
anim.length = 2.0

# Position track
var pos_track := anim.add_track(Animation.TYPE_VALUE)
anim.track_set_path(pos_track, ".:position")
anim.track_insert_key(pos_track, 0.0, Vector2(0, 0))
anim.track_insert_key(pos_track, 1.0, Vector2(100, 0))
anim.track_set_interpolation_type(pos_track, Animation.INTERPOLATION_CUBIC)

# Color track (modulate)
var color_track := anim.add_track(Animation.TYPE_VALUE)
anim.track_set_path(color_track, "Sprite2D:modulate")
anim.track_insert_key(color_track, 0.0, Color.WHITE)
anim.track_insert_key(color_track, 2.0, Color.TRANSPARENT)

$AnimationPlayer.add_animation("fade_move", anim)
$AnimationPlayer.play("fade_move")

Method Tracks (Function Calls)

# Call functions at specific timestamps
var method_track := anim.add_track(Animation.TYPE_METHOD)
anim.track_set_path(method_track, ".")  # Path to node

# Insert method calls
anim.track_insert_key(method_track, 0.5, {
    "method": "spawn_particle",
    "args": [Vector2(50, 50)]
})

anim.track_insert_key(method_track, 1.5, {
    "method": "play_sound",
    "args": ["res://sounds/explosion.ogg"]
})

# CRITICAL: Set call mode to DISCRETE
anim.track_set_call_mode(method_track, Animation.CALL_MODE_DISCRETE)

# Methods must exist on target node:
func spawn_particle(pos: Vector2) -> void:
    # Spawn particle at position
    pass

func play_sound(sound_path: String) -> void:
    $AudioStreamPlayer.stream = load(sound_path)
    $AudioStreamPlayer.play()

Audio Tracks

# Synchronize audio with animation
var audio_track := anim.add_track(Animation.TYPE_AUDIO)
anim.track_set_path(audio_track, "AudioStreamPlayer")

# Insert audio playback
var audio_stream := load("res://sounds/footstep.ogg")
anim.audio_track_insert_key(audio_track, 0.3, audio_stream)
anim.audio_track_insert_key(audio_track, 0.6, audio_stream)  # Second footstep

# Set volume for specific key
anim.audio_track_set_key_volume(audio_track, 0, 1.0)  # Full volume
anim.audio_track_set_key_volume(audio_track, 1, 0.7)  # Quieter

Bezier Tracks (Custom Curves)

# For smooth, custom interpolation curves
var bezier_track := anim.add_track(Animation.TYPE_BEZIER)
anim.track_set_path(bezier_track, ".:custom_value")

# Insert bezier points with handles
anim.bezier_track_insert_key(bezier_track, 0.0, 0.0)
anim.bezier_track_insert_key(bezier_track, 1.0, 100.0,
    Vector2(0.5, 0),    # In-handle
    Vector2(-0.5, 0))   # Out-handle

# Read value in _process
func _process(delta: float) -> void:
    var value := $AnimationPlayer.get_bezier_value("custom_value")
    # Use value for custom effects

2. Root Motion Extraction

# Scene structure:
# CharacterBody3D (root)
#   ├─ MeshInstance3D
#   │   └─ Skeleton3D
#   └─ AnimationPlayer

# AnimationPlayer setup:
@onready var anim_player: AnimationPlayer = $AnimationPlayer

func _ready() -> void:
    # Enable root motion (point to root bone)
    anim_player.root_motion_track = NodePath("MeshInstance3D/Skeleton3D:root")
    anim_player.play("walk")

func _physics_process(delta: float) -> void:
    # Extract root motion
    var root_motion_pos := anim_player.get_root_motion_position()
    var root_motion_rot := anim_player.get_root_motion_rotation()
    var root_motion_scale := anim_player.get_root_motion_scale()
    
    # Apply to CharacterBody3D
    var transform := Transform3D(basis.rotated(basis.y, root_motion_rot.y), Vector3.ZERO)
    transform.origin = root_motion_pos
    global_transform *= transform
    
    # Velocity from root motion
    velocity = root_motion_pos / delta
    move_and_slide()

3. Animation Sequences & Queueing

# Play animations in sequence
@onready var anim: AnimationPlayer = $AnimationPlayer

func play_attack_combo() -> void:
    anim.play("attack_1")
    await anim.animation_finished
    anim.play("attack_2")
    await anim.animation_finished
    anim.play("idle")

# Or use queue:
func play_with_queue() -> void:
    anim.play("attack_1")
    anim.queue("attack_2")
    anim.queue("idle")  # Auto-plays after attack_2

Blend Times

# Smooth transitions between animations
anim.play("walk")

# 0.5s blend from walk → run
anim.play("run", -1, 1.0, 0.5)  # custom_blend = 0.5

# Or set default blend
anim.set_default_blend_time(0.3)  # 0.3s for all transitions
anim.play("idle")

4. RESET Track Pattern

# Create RESET animation with default values
var reset_anim := Animation.new()
reset_anim.length = 0.01  # Very short

var track := reset_anim.add_track(Animation.TYPE_VALUE)
reset_anim.track_set_path(track, "Sprite2D:position")
reset_anim.track_insert_key(track, 0.0, Vector2(0, 0))  # Default position

track = reset_anim.add_track(Animation.TYPE_VALUE)
reset_anim.track_set_path(track, "Sprite2D:modulate")
reset_anim.track_insert_key(track, 0.0, Color.WHITE)  # Default color

anim_player.add_animation("RESET", reset_anim)

# AnimationPlayer automatically plays RESET when scene loads
# IF "Reset on Save" is enabled in AnimationPlayer settings

5. Procedural Animation Generation

# Create bounce animation programmatically
func create_bounce_animation() -> void:
    var anim := Animation.new()
    anim.length = 1.0
    anim.loop_mode = Animation.LOOP_LINEAR
    
    # Position track (Y bounce)
    var track := anim.add_track(Animation.TYPE_VALUE)
    anim.track_set_path(track, ".:position:y")
    
    # Generate sine wave keyframes
    for i in range(10):
        var time := float(i) / 9.0  # 0.0 to 1.0
        var value := sin(time * TAU) * 50.0  # Bounce height 50px
        anim.track_insert_key(track, time, value)
    
    anim.track_set_interpolation_type(track, Animation.INTERPOLATION_CUBIC)
    $AnimationPlayer.add_animation("bounce", anim)
    $AnimationPlayer.play("bounce")

6. Advanced Patterns

Play Animation Backwards

# Play animation in reverse (useful for closing doors, etc.)
anim.play("door_open", -1, -1.0)  # speed = -1.0 = reverse

# Pause and reverse
anim.pause()
anim.play("current_animation", -1, -1.0, false)  # from_end = false

Animation Callbacks (Signal-Based)

# Emit custom signal at specific frame
func _ready() -> void:
    $AnimationPlayer.animation_finished.connect(_on_anim_finished)

func _on_anim_finished(anim_name: String) -> void:
    match anim_name:
        "attack":
            deal_damage()
        "die":
            queue_free()

Seek to Specific Time

# Jump to 50% through animation
anim.seek(anim.current_animation_length * 0.5)

# Scrub through animation (cutscene editor)
func _input(event: InputEvent) -> void:
    if event is InputEventMouseMotion and scrubbing:
        var normalized_pos := event.position.x / get_viewport_rect().size.x
        anim.seek(anim.current_animation_length * normalized_pos)

7. Performance Optimization

Disable When Off-Screen

extends VisibleOnScreenNotifier2D

func _ready() -> void:
    screen_exited.connect(_on_screen_exited)
    screen_entered.connect(_on_screen_entered)

func _on_screen_exited() -> void:
    $AnimationPlayer.pause()

func _on_screen_entered() -> void:
    $AnimationPlayer.play()

8. Expert Patterns

Shared-Animation-Library

class_name SharedAnimationManager extends Node

@export var shared_library: AnimationLibrary
@onready var anim_player: AnimationPlayer = $AnimationPlayer

func _ready() -> void:
    # 1. Inject the shared library under a unique key
    anim_player.add_animation_library(&"shared_human", shared_library)
    
    # 2. Access animations using the 'library/animation' syntax
    anim_player.play(&"shared_human/walk")

Animation-Event-Signaling

class_name AnimationSignaler extends Node

## Emitted when the animation reaches a marked event key
signal animation_event(event_type: String)

## Generic receiver for AnimationPlayer Method Tracks
func emit_event(event_type: String) -> void:
    animation_event.emit(event_type)

# Setup in AnimationPlayer:
# 1. Add Method Track pointing to this node
# 2. Keyframe: method="emit_event", args=["spawn_footstep_vfx"]
# 3. Other systems connect to 'animation_event' signal

Animation-Budget-Manager

class_name AnimationBudgetManager extends Node3D

@onready var anim_player: AnimationPlayer = $AnimationPlayer
@onready var visibility_notifier: VisibleOnScreenNotifier3D = $VisibleOnScreenNotifier3D

func _ready() -> void:
    # 1. Disable automatic engine processing
    anim_player.callback_mode_process = AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL

func _process(delta: float) -> void:
    # 2. Cull updates for off-screen entities
    if not visibility_notifier.is_on_screen():
        return
        
    # 3. Manually step the animation forward
    # Optional: Throttle updates (e.g., only call every 2nd frame) for distant entities
    anim_player.advance(delta)

9. Available Scripts (Load Before Use)

MANDATORY: Read the appropriate script before implementing the corresponding pattern.

• method_track_logic.gd: Load when implementing logic triggers using CALL_MODE_DISCRETE for high-precision hitbox and state management.
• runtime_anim_lib_swapper.gd: Load when managing multiple AnimationLibrary resources (Stances, Weapons) on a single AnimationPlayer.
• dynamic_shader_animation.gd: Load when animating shader uniforms (e.g., dissolve, glow) in sync with timeline keyframes.
• procedural_track_modifier.gd: Load for runtime modification of existing tracks (e.g., jump height tweaking) without creating new Animation resources.
• reset_track_orchestrator.gd: Load for forced, immediate state resets across complex multi-track node setups.
• bezier_curve_extraction.gd: Load when extracting numeric data from Bezier tracks at runtime to drive procedural VFX or physics.
• active_animation_culler.gd: Load for performance optimization using VisibleOnScreenNotifier to disable AnimationPlayer.active.
• root_motion_physics_sync.gd: Load for expert 3D CharacterBody motion extraction using get_root_motion_position.
• character_part_swapper_tracks.gd: Load for character customization (equipment/slots) managed entirely through Animation timeline tracks.
• precise_audio_sync.gd: Load for perfectly timed SFX using tracks with volume, pitch, and start-offset control.

Pitfalls

• NEVER forget RESET tracks — Without a RESET track, animated properties don't restore to initial values when changing scenes. Create RESET animation with all default states.
• NEVER use Animation.CALL_MODE_CONTINUOUS for function calls — This calls the method EVERY frame during the keyframe. Use CALL_MODE_DISCRETE (calls once) to avoid logic spam.
• NEVER animate resource properties directly — Animating material.albedo_color creates embedded resources that bloat file size. Store the material in a variable or use instance uniform instead.
• NEVER use animation_finished for looping animations — This signal doesn't fire for looped animations. Use animation_looped or check current_animation in _process().
• NEVER hardcode animation names as strings across large codebases — Use constants or enums. Typos cause silent failures.
• NEVER use seek() without update=true for same-frame logic — If you need properties to update immediately (e.g., for physics checks), you MUST set the update parameter to true.
• NEVER leave unnecessary AnimationPlayers active — If an entity is off-screen and its animation is purely visual (no logic tracks), set active = false to save significant CPU/GPU processing.
• NEVER change AnimationLibrary content while it is playing — This causes immediate crashes or undefined transform states. Stop the player or wait for the finished signal before swapping libraries.
• NEVER rely on speed_scale for long-term synchronization — For multiplayer or rhythm games, use seek() with a global time reference to prevent frame-drift.

Verification

1. Check if animation exists before playing:

if anim.has_animation("walk"):
    anim.play("walk")
else:
    push_error("Animation 'walk' not found!")

2. Verify Method Track Call Mode:

var method_track_idx := anim.find_track(".:method_name", Animation.TYPE_METHOD)
# Ensure it is DISCRETE
assert(anim.track_get_call_mode(method_track_idx) == Animation.CALL_MODE_DISCRETE)

3. Verify RESET animation is present:

assert(anim.has_animation("RESET"), "RESET animation missing!")

Related skills

• Master Skill: godot-master