godot-2d-animation

NEVER Do

• NEVER use AnimatedTexture — This class is deprecated, highly inefficient in modern renderers, and may be removed in future Godot versions. Use AnimatedSprite2D or AnimationPlayer instead.
• NEVER allow Tweens to fight over the same property — If multiple Tweens animate the same property, the last one created forcibly takes priority. Always assign your Tween to a variable and call kill() on the previous instance before creating a new one.
• NEVER process kinematic movement outside the physics tick — If your AnimationPlayer moves a CharacterBody2D, ensure the AnimationPlayer's callback mode is set to Physics. Animating physics bodies during the Idle (render) frame breaks fixed timestep physics interpolation and causes stutter.
• NEVER use `animation_finished` for looping animations — The signal only fires on non-looping animations. Use animation_looped instead for loop detection.
• NEVER call `play()` and expect instant state changes — AnimatedSprite2D applies play() on the next process frame. Call advance(0) immediately after play() if you need synchronous property updates (e.g., when changing animation + flip_h simultaneously).
• NEVER set `frame` directly when preserving animation progress — Setting frame resets frame_progress to 0.0. Use set_frame_and_progress(frame, progress) to maintain smooth transitions when swapping animations mid-frame.
• NEVER forget to cache `@onready var anim_sprite` — The node lookup getter is surprisingly slow in hot paths like _physics_process(). Always use @onready.
• NEVER mix AnimationPlayer tracks with code-driven AnimatedSprite2D — Choose one animation authority per sprite. Mixing causes flickering and state conflicts.
• NEVER use paper-thin skeletons for deformation — 2D meshes require balanced vertex density. If your mesh deforms poorly, increase the vertex count near joints in the Mesh2D editor.

Available Scripts

MANDATORY: Read the script for the pattern you are implementing. Inline recipes that duplicated these scripts were removed — the script is the source of truth.

Do NOT Load (by scenario)

Script index

• one_frame_sync_fix.gd — Golden sync path: play() + advance(0) with flip_h / property changes.
• animation_state_sync.gd — State-driven animation + transition queue.
• animation_sync.gd — Method tracks, signal orchestration, blend-space hooks.
• animation_tree_step.gd — AnimationNodeStateMachinePlayback.travel().
• procedural_squash_stretch.gd — Sole source for physics-driven squash/stretch (do not re-implement landing checks here).
• tween_lifecycle_manager.gd — Kill/reuse Tweens; property-fight prevention.
• skeleton_2d_rig_helper.gd — FABRIK/CCDIK stacks, rest poses.
• shader_hook.gd — AnimationPlayer → ShaderMaterial uniforms.
• gpu_mesh_optimizer.gd — Sprite → tight 2D mesh for fill-rate.
• multimesh_swarm_anim.gd — GPU swarm motion only.
• animation_data_extractor.gd — Value/method tracks decouple hitbox/spawn metadata from SpriteFrames visuals.
• procedural_walker_2d.gd — TwoBoneIK foot planting via raycast targets (pairs with skeleton_2d_rig_helper.gd).
• sprite_sheet_memory_manager.gd — Threaded high-res frame inject + unload for VRAM spikes.

Expert Decision Tree: Choosing the Right Animation Tool

Golden Path: One-Frame Sync (play + advance(0))

When changing animation and sprite properties in the same frame, play() alone applies next process tick — one-frame glitch.

MANDATORY: Read one_frame_sync_fix.gd. Minimal contract:

# After any play() that must match flip/modulate/etc. this frame:
anim.flip_h = dir < 0
anim.play(&"run")
anim.advance(0)  # force pose now

Related: animation_looped (loops) vs animation_finished (one-shots); use set_frame_and_progress when swapping skins mid-clip (see AnimatedSprite2D class docs).

Procedural Squash & Stretch

Do NOT paste landing snippets into agents. A prior body used an impossible condition (not is_on_floor() and is_on_floor()).

MANDATORY sole source: procedural_squash_stretch.gd — impact squash, velocity stretch, lerp recovery. Pair with godot-characterbody-2d / godot-2d-physics for floor/velocity authority.

Quick routing (scripts own the recipes)

• Tween interrupt / flash loops → tween_lifecycle_manager.gd (never race two Tweens on one property).
• AnimationTree travel → animation_tree_step.gd (start then travel).
• IK foot plant → skeleton_2d_rig_helper.gd + SkeletonModification2DTwoBoneIK docs.
• Fill-rate / swarms → gpu_mesh_optimizer.gd / multimesh_swarm_anim.gd per Do-NOT-Load table.
• Pixel filter / shared SpriteFrames → Official Documentation (2D sprite animation, SpriteFrames); keep resources shared via preload.

Expert insights (WHY — keep in body)

• Hybrid cutout + cel — Animate bones for body motion; keyframe frame/texture on child sprites for hand/face swaps. WHY: transform-only motion is cheap; cel swaps stay art-directable without re-rigging.
• GPU fill rate — Large transparent sprites waste fill rate. WHY: tight MeshInstance2D polygons skip transparent texels; pair with gpu_mesh_optimizer.gd.
• Tween property fights — WHY: the last Tween on a property wins silently. Always kill() the prior instance (tween_lifecycle_manager.gd).
• AnimationTree travel — WHY: StateMachine uses internal A* between states; call start() before travel() (animation_tree_step.gd).

Deep recipes (on demand)

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

• 2D sprite animation — Canonical AnimatedSprite2D + SpriteFrames workflow for frame-based sheets and signal timing.
• Introduction to the animation features — When to graduate from spritesheets to AnimationPlayer for tracks, methods, and non-visual properties.
• Cutout animation — Paper-doll hierarchies and hybrid cutout/cel setups before full skeletal IK.
• 2D skeletons — Skeleton2D / Bone2D rigging, rest poses, and deformation expectations for cutout meshes.
• Using AnimationTree — Blend spaces and state-machine graphs that drive an underlying AnimationPlayer.
• Animation track types — Method/value/property tracks for frame-perfect SFX, hitboxes, and shader uniform hooks.
• AnimatedSprite2D — play(), advance(), set_frame_and_progress(), and animation_looped vs animation_finished contracts.
• SpriteFrames — Shared frame resources, loop flags, and per-animation timing used by AnimatedSprite2D.
• Tween — Runtime squash/stretch and interruptible one-shot motion without baking AnimationPlayer clips.
• Animating thousands of fish — GPU vertex / MultiMesh patterns for swarm motion that must leave the node tree.
• SkeletonModification2DTwoBoneIK — Lightweight two-bone IK for procedural foot/hand planting on Skeleton2D stacks.

Related Skills

Prerequisites

• godot-animation-player — AnimationPlayer ownership, callback modes, and track authoring that this skill’s hybrid/cutout patterns assume.
• godot-characterbody-2d — Physics-tick movement so animated CharacterBody2D motion stays on the fixed timestep.
• godot-signal-architecture — Safe wiring for animation_finished / animation_looped / frame_changed without lifecycle leaks.

Complements

• godot-animation-tree-mastery — Deepen blend trees, OneShot layers, and travel() pathfinding beyond the 2D locomotion basics here.
• godot-tweening — Broader Tween composition when squash/stretch or UI pops outgrow inline create_tween() snippets.
• godot-shaders-basics — CanvasItem shader uniforms driven by AnimationPlayer tracks or MultiMesh swarm materials.
• godot-2d-physics — Impact velocity, raycasts for IK targets, and interpolation rules that feed procedural deformation.
• godot-state-machine-advanced — Gameplay FSMs that should own intent while AnimationTree/AnimatedSprite2D own presentation.
• godot-particles — Dust, hit sparks, and trails spawned from method tracks or frame events.
• godot-adapt-3d-to-2d — Directional sheets, billboards, and fake-depth sorting that still use 2D animation nodes.

Downstream / consumers

• godot-genre-platformer — Jump/land/run presentation stacks consume sync, squash/stretch, and state-machine travel patterns.
• godot-genre-fighting — Frame-perfect hitboxes and method tracks depend on AnimationPlayer + AnimatedSprite2D discipline here.
• godot-resource-data-patterns — Shared .tres SpriteFrames and skin packs for memory-safe multi-instance characters.

Master

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