/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.

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 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

Expert architecture (scripts)

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.