godot-animation-player

AnimationPlayer

Timeline-based keyframe animation: track choice, RESET, root motion, libraries — scripts own recipes.

NEVER Do

• NEVER forget RESET tracks — Animated properties otherwise stick across scene changes.
• NEVER use Animation.CALL_MODE_CONTINUOUS for one-shot logic — Use CALL_MODE_DISCRETE.
• NEVER animate embedded resource properties directly — Prefer instance uniforms / owned materials.
• NEVER use animation_finished for looping clips — Use animation_looped or poll current_animation.
• NEVER hardcode animation name strings at scale — Constants / StringName.
• NEVER seek() without update=true when same-frame reads matter.
• NEVER leave off-screen visual-only players active — Cull with notifiers.
• NEVER mutate a playing AnimationLibrary — Stop / wait for finished first.
• NEVER rely on speed_scale for long sync — Prefer seek() against a shared clock.

---

Available Scripts (MANDATORY triggers)

> Open the matching script before implementing that pattern. Deep recipes: [track-authoring.md](references/track-authoring.md), [root-motion-and-sequences.md](references/root-motion-and-sequences.md), [edge-cases.md](references/edge-cases.md).

| Need | Script |

|---|---|

| Method-track hit/state keys | [method_track_logic.gd](scripts/method_track_logic.gd) |

| Stance/weapon library swap | [runtime_anim_lib_swapper.gd](scripts/runtime_anim_lib_swapper.gd) |

| Shader uniform timelines | [dynamic_shader_animation.gd](scripts/dynamic_shader_animation.gd) |

| Runtime track tweak | [procedural_track_modifier.gd](scripts/procedural_track_modifier.gd) |

| Forced RESET orchestration | [reset_track_orchestrator.gd](scripts/reset_track_orchestrator.gd) |

| Bezier → procedural drive | [bezier_curve_extraction.gd](scripts/bezier_curve_extraction.gd) |

| Off-screen active cull | [active_animation_culler.gd](scripts/active_animation_culler.gd) |

| Root motion ↔ physics | [root_motion_physics_sync.gd](scripts/root_motion_physics_sync.gd) |

| Part/equipment tracks | [character_part_swapper_tracks.gd](scripts/character_part_swapper_tracks.gd) |

| TYPE_AUDIO footstep sync | [precise_audio_sync.gd](scripts/precise_audio_sync.gd) |

| Queue/branch sequences | [animation_sequencer.gd](scripts/animation_sequencer.gd) |

| Code-built Animation resources | [programmatic_anim.gd](scripts/programmatic_anim.gd) |

| Alt audio-track setup notes | [audio_sync_tracks.gd](scripts/audio_sync_tracks.gd) |

Critical WHY (keep in body)

• CALL_MODE_CONTINUOUS invokes the method every frame across the key span — one-shot hitboxes/VFX need CALL_MODE_DISCRETE.
• Animating embedded sub-resource properties (e.g. material.albedo_color) duplicates resources into the scene — use instanced materials / shader_parameter/* tracks.
• animation_finished does not fire on looping clips — use animation_looped or poll current_animation.
• Mutating a playing AnimationLibrary crashes or leaves bad transforms — stop or await finished before swap.
• speed_scale drifts for rhythm/multiplayer — shared-clock seek(t, true) for long sync.

Track decision matrix

| Track | Use when | Avoid when |

|---|---|---|

| Value | Animate properties (pos, modulate, uniforms) | One-off runtime juice → Tween |

| Method | Hitboxes, SFX hooks, state flips at timestamps | CONTINUOUS call mode / missing method on path |

| Audio | Footsteps / VO locked to frames | Loose AudioStreamPlayer.play() drift |

| Bezier | Custom easing curves sampled at runtime | Simple linear fades |

Track authoring samples → [track-authoring.md](references/track-authoring.md).

Root motion (physics)

CharacterBody3D + Skeleton3D + AnimationPlayer: extract with get_root_motion_position() / rotation on the physics tick — [root_motion_physics_sync.gd](scripts/root_motion_physics_sync.gd). Walk cycles that only move bones leave the body collider behind.

Sequences, blends, RESET

• Chain: animation_set_next / queue / [animation_sequencer.gd](scripts/animation_sequencer.gd).
• Blend times for walk↔run polish; play("run", -1, 1.0, 0.5) or set_default_blend_time.
• Always author a RESET clip with defaults; enable Reset on Save when editing.
• Reverse playback: play("clip", -1, -1.0) for doors/cinematic rewind.

Full recipes → [root-motion-and-sequences.md](references/root-motion-and-sequences.md).

AnimationPlayer vs Tween

| Need | Prefer |

|---|---|

| Timeline / many properties / reusable | AnimationPlayer |

| One-shot runtime / interruptible | Tween (godot-tweening) |

Expert architecture (scripts)

| Pattern | Script | WHY |

|---|---|---|

| Shared humanoid libraries | [runtime_anim_lib_swapper.gd](scripts/runtime_anim_lib_swapper.gd) | One library, many models — play lib/clip |

| Decoupled timeline events | [method_track_logic.gd](scripts/method_track_logic.gd) | Method track → signaler → gameplay listeners |

| Off-screen CPU budget | [active_animation_culler.gd](scripts/active_animation_culler.gd) | active = false or manual advance() |

| Code-built clips | [programmatic_anim.gd](scripts/programmatic_anim.gd) | Dynamic targets not in FBX |

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API;

> load Related Skills when routing work to a peer domain — do not preload the whole lattice.

Official Documentation

• Introduction to the animation features — When AnimationPlayer owns timelines vs Tweens/sprites, and how libraries, RESET, and the editor fit together.
• Animation track types — Value, Method, Bezier, and Audio tracks plus call-mode and keying rules this skill’s patterns depend on.
• AnimationPlayer — play/queue/seek, blend times, animation_finished vs animation_looped, and active culling.
• Animation — Track APIs (track_insert_key, call modes, audio/bezier helpers) and length/loop metadata.
• AnimationLibrary — Shared stance/weapon clip packs added via add_animation_library without duplicating tracks per model.
• AnimationMixer — Root-motion getters, callback process modes, and advance() used by physics sync and budget managers.
• Using AnimationTree — When blends/state machines should drive an underlying AnimationPlayer instead of manual queue.
• Tween — Runtime one-shot motion counterpart for the AnimationPlayer-vs-Tween decision matrix.
• Adding animations (Your first 3D game) — Practical import → AnimationPlayer play loop before advanced track authoring.
• VisibleOnScreenNotifier3D — Screen enter/exit signals used to toggle AnimationPlayer.active for off-screen CPU savings.

Related Skills

Prerequisites

• godot-signal-architecture — Safe animation_finished / animation_looped / custom method-track signaling without lifecycle leaks.
• godot-resource-data-patterns — Shared .tres AnimationLibrary ownership so runtime swaps do not duplicate or mutate playing resources unsafely.
• godot-gdscript-mastery — Typed programmatic track generation, path strings, and Dictionary method-track payloads.

Complements

• godot-animation-tree-mastery — Blend trees, OneShot layers, and travel() when locomotion outgrows AnimationPlayer queue/set_next.
• godot-2d-animation — AnimatedSprite2D / Skeleton2D presentation that still relies on AnimationPlayer method and property tracks.
• godot-tweening — Interruptible runtime tweens when baking a full Animation resource would be overkill.
• godot-shaders-basics — ShaderMaterial uniforms driven by value tracks (shader_parameter/*) without embedding materials.
• godot-audio-systems — Bus/voice pooling around TYPE_AUDIO tracks and footstep/SFX timing on the timeline.
• godot-physics-3d — CharacterBody3D integration for root-motion position/rotation extraction on the physics tick.

Downstream / consumers

• godot-genre-fighting — Frame-perfect hitbox windows and discrete method tracks for cancel windows.
• godot-genre-platformer — Jump/land/run clips, RESET hygiene, and blend times on 2D/3D movers.
• godot-combat-system — Attack timelines that emit damage/VFX events from AnimationPlayer method tracks.

Master

• godot-master — Library router and mirrored module entry for cross-skill discovery.