thedivergentai/game-dev-agentic-skills

godot-2d-animation

Expert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs.

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/thedivergentai/game-dev-agentic-skills --skill godot-2d-animation

Prima di iniziare

  • L’installazione non include abbonamenti, quote API o accesso ai file.
  • Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

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)

ScenarioLoadDo NOT Load
Single character / playerone_frame_sync_fix.gd, animation_state_sync.gd, optional animation_tree_step.gd / tween_lifecycle_manager.gdmultimesh_swarm_anim.gd, gpu_mesh_optimizer.gd (unless fill-rate profiling demands it)
Frame events / hitboxes / SFX syncanimation_sync.gd (+ AnimationPlayer method tracks)Swarm/MultiMesh scripts
Squash/stretch game-feelMANDATORY procedural_squash_stretch.gdInline landing-condition snippets in this skill
Cutout / IK limbsskeleton_2d_rig_helper.gdMultiMesh swarm scripts
Shader flash / dissolve on animshader_hook.gd—
Thousands of bats/fish/propsmultimesh_swarm_anim.gd (+ docs fish tutorial)Per-entity AnimatedSprite2D / Tween managers

Script index


Expert Decision Tree: Choosing the Right Animation Tool

ScenarioRecommended NodeExpert Insight
Isolated, pure frame-by-frame spritesheetsAnimatedSprite2DCannot animate non-visual properties or method tracks — escalate to AnimationPlayer when you need those.
Cutout animations, non-visual sync, audio/particlesAnimationPlayerOwns transforms, mesh deformation, method/value tracks.
Complex state machines, blending, locomotionAnimationTreeLogic graph over an AnimationPlayer; use travel() via animation_tree_step.gd.
Procedural, dynamic, fire-and-forget UI/fxTweenRuntime targets; always go through tween_lifecycle_manager.gd.
Swarms of thousands of entitiesMultiMeshInstance2D + ShaderLoad multimesh_swarm_anim.gd only; skip character sync scripts.

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:

gdscript
# 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)

TopicReference / script
Signals / frame events / skin swapsignals-and-frame-events.md
Cutout rigs / procedural IK feetcutout-and-skeletal.md
GPU mesh / swarms / memory streamingexpert-techniques.md
Frame metadata / spawn offsetsanimation_data_extractor.gd
Async SpriteFrames VRAMsprite_sheet_memory_manager.gd

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.
dallo stesso repository

Altri Skills

Tutti gli Skills
thedivergentai
Community

godot-combat-system

Expert patterns for combat systems including hitbox/hurtbox architecture, damage calculation (DamageData class), health components, combat state machines, combo systems, ability cooldowns, and damage popups. Use for action games, RPGs, or fighting games. Trigger keywords: Hitbox, Hurtbox, DamageData, HealthComponent, combatstate, combosystem, abilitycooldown, invincibilityframes, damagepopup.

Installazioni / 1h
1
GitHub Stars
977
Aggiornato
16 ott
thedivergentai
Community

godot-camera-systems

Expert patterns for 2D/3D camera control including smooth following (lerp, positionsmoothing), camera shake (trauma system), screen shake with frequency parameters, deadzone/drag for platformers, look-ahead prediction, and camera transitions. Use for player cameras, cinematic sequences, or multi-camera systems. Trigger keywords: Camera2D, Camera3D, SpringArm3D, positionsmoothing, camerashake, traumasystem, lookahead, dragmargin, cameralimits, cameratransition.

Installazioni / 1h
2
GitHub Stars
969
Aggiornato
16 ott
thedivergentai
Community

godot-dialogue-system

Expert patterns for branching dialogue systems including dialogue graphs (Resource-based), character portraits, player choices, conditional dialogue (flags/quests), typewriter effects, localization support, and voice acting integration. Use for narrative games, RPGs, or visual novels. Trigger keywords: DialogueLine, DialogueChoice, DialogueGraph, dialoguemanager, typewritereffect, branchingdialogue, dialogueflags, localization, voiceacting.

Installazioni / 1h
2
GitHub Stars
969
Aggiornato
16 ott
thedivergentai
Community

godot-particles

Expert blueprint for GPU particle systems (explosions, magic effects, weather, trails) using GPUParticles2D/3D, ParticleProcessMaterial, gradients, sub-emitters, and custom shaders. Use when creating VFX, environmental effects, or visual feedback. Keywords GPUParticles2D, ParticleProcessMaterial, emissionshape, colorramp, subemitter, oneshot.

Installazioni / 1h
2
GitHub Stars
969
Aggiornato
16 ott