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, root-motion-and-sequences.md, edge-cases.md.

Need	Script
Method-track hit/state keys	method_track_logic.gd
Stance/weapon library swap	runtime_anim_lib_swapper.gd
Shader uniform timelines	dynamic_shader_animation.gd
Runtime track tweak	procedural_track_modifier.gd
Forced RESET orchestration	reset_track_orchestrator.gd
Bezier → procedural drive	bezier_curve_extraction.gd
Off-screen active cull	active_animation_culler.gd
Root motion ↔ physics	root_motion_physics_sync.gd
Part/equipment tracks	character_part_swapper_tracks.gd
TYPE_AUDIO footstep sync	precise_audio_sync.gd
Queue/branch sequences	animation_sequencer.gd
Code-built Animation resources	programmatic_anim.gd
Alt audio-track setup notes	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.

Root motion (physics)

CharacterBody3D + Skeleton3D + AnimationPlayer: extract with get_root_motion_position() / rotation on the physics tick — 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.
• 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.

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	One library, many models — play lib/clip
Decoupled timeline events	method_track_logic.gd	Method track → signaler → gameplay listeners
Off-screen CPU budget	active_animation_culler.gd	active = false or manual advance()
Code-built clips	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.