godot-2d-animation

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 0c0182b848c3 · 20 Oct 2026Report an issue or request a re-scan

• Publisherthedivergentai GitHub userOwner of the repository this skill is read from
• Source folderthedivergentai/gd-agentic-skills/skills/godot-2d-animationThe exact folder we audited
• LicenceLGPL-3.0As the repository states it
• Commit pinned for this verdict0c0182b848c3A new audit runs when the source changes
• Repository statusNot archivedLast push 3 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Expert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect…

---
name: godot-2d-animation
description: "Expert patterns for 2D animation in Godot using AnimatedSprite2D and skeletal cutout rigs. Use when implementing sprite frame animations, procedural animation (squash/stretch), cutout bone hierarchies, or frame-perfect timing systems. Trigger keywords: AnimatedSprite2D, SpriteFrames, animation_finished, animation_looped, frame_changed, frame_progress, set_frame_and_progress, cutout animation, skeletal 2D, Bone2D, procedural animation, animation state machine, advance(0)."
---

## 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)
| Scenario | Load | Do NOT Load |
|----------|------|-------------|
| Single character / player | `one_frame_sync_fix.gd`, `animation_state_sync.gd`, optional `animation_tree_step.gd` / `tween_lifecycle_manager.gd` | `multimesh_swarm_anim.gd`, `gpu_mesh_optimizer.gd` (unless fill-rate profiling demands it) |
| Frame events / hitboxes / SFX sync | `animation_sync.gd` (+ AnimationPlayer method tracks) | Swarm/MultiMesh scripts |
| Squash/stretch game-feel | **MANDATORY** `procedural_squash_stretch.gd` | Inline landing-condition snippets in this skill |
| Cutout / IK limbs | `skeleton_2d_rig_helper.gd` | MultiMesh swarm scripts |
| Shader flash / dissolve on anim | `shader_hook.gd` | — |
| Thousands of bats/fish/props | `multimesh_swarm_anim.gd` (+ docs fish tutorial) | Per-entity AnimatedSprite2D / Tween managers |

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

---

## Expert Decision Tree: Choosing the Right Animation Tool

| Scenario | Recommended Node | Expert Insight |
|----------|------------------|----------------|
| Isolated, pure frame-by-frame spritesheets | **AnimatedSprite2D** | Cannot animate non-visual properties or method tracks — escalate to AnimationPlayer when you need those. |
| Cutout animations, non-visual sync, audio/particles | **AnimationPlayer** | Owns transforms, mesh deformation, method/value tracks. |
| Complex state machines, blending, locomotion | **AnimationTree** | Logic graph over an AnimationPlayer; use `travel()` via `animation_tree_step.gd`. |
| Procedural, dynamic, fire-and-forget UI/fx | **Tween** | Runtime targets; always go through `tween_lifecycle_manager.gd`. |
| Swarms of thousands of entities | **MultiMeshInstance2D + Shader** | Load `multimesh_swarm_anim.gd` only; skip character sync scripts. |

---

## Golden Path: One-Frame 

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/thedivergentai/gd-agentic-skills
git -C gd-agentic-skills checkout 0c0182b848c3

Works in

1. 2026-10-20
   ✓SAFE B 89 / 100

   first audit · source 0c0182b848c3

Questions about godot-2d-animation

• github.com/thedivergentai/gd-agentic-skills/tree/main/skills/god — the audited source at commit 0c0182b848c3 and every finding aboveObserved · 20 Oct 2026

Spotted something wrong? Report a correction · Methodology