视频与音频
godot-2d-animation
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).
thedivergentai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add thedivergentai/GD-Agentic-Skills --skill godot-2d-animation技能说明
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_finishedfor looping animations — The signal only fires on non-looping animations. Useanimation_loopedinstead for loop detection. - NEVER call
play()and expect instant state changes — AnimatedSprite2D appliesplay()on the next process frame. Calladvance(0)immediately afterplay()if you need synchronous property updates (e.g., when changing animation + flip_h simultaneously). - NEVER set
framedirectly when preserving animation progress — Settingframeresetsframe_progressto 0.0. Useset_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 — Golden sync path:
play()+advance(0)withflip_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
| 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. |