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)