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, em

NEVER Do in Particle Systems NEVER use amount ratio to optimize performance dynamically — It does not save GPU memory or improve processing; the full amount is still allocated. Change the amount property directly instead. NEVER use CPUParticles2D for performance critical effects on Desktop — Use GPUParticles unless targeting low end mobile with no GPU support. However, use CPUParticles2D if you need Physics Interpolation for smooth trails on moving bodies in 2D. NEVER set preprocess to extremely high values — High values (e.g., 60s) will force the GPU to simulate thousands of frames in a single render tick, potentially causing an immediate GPU crash. NEVER leave visibility aabb unconfigured for large systems — Incorrect AABBs cause frustum culling errors (particles popping out) and break LOD calculations. Generate AABBs using the editor toolbar. NEVER enable turbulence on Mobile/Web without testing — 3D noise evaluation per particle is extremely heavy. Disable via Feature Tags on lower end platforms. NEVER use a Timer to lifetime cleanup one shots — Prefer [smart oneshot recycler.gd](scripts/smart oneshot recycler.gd): finished + restart() , or queue free() only on truly disposable instances. NEVER use local coords = true for trails — Smoke or fire left behind by a projectile MUST use global space ( local coords = false ) or the trail will follow the projectile like a stiff stick. NEVER expect GPUParticles2D to interpolate correctly in Godot 4.3 — They stutter when parented to physics bodies. Use CPUParticles2D with fract delta = true for high speed 2D movement. NEVER trigger emitting = true immediately after a finished signal — Async GPU state delays can cause the restart to fail. Use the restart() method instead. NEVER attempt recursion with sub emitters — A particle system cannot be its own sub emitter; it will silently fail. NEVER forget alpha in color gradients — Particles that disappear instantly at the end of their lifetime look harsh; always add a gradient point at 1.0 with 0.0 alpha for a smooth exit. NEVER use EMISSION SHAPE POINT for volumentric explosions — Spawning all particles at a single point looks flat. Use a Sphere or Box shape for natural 3D spread. NEVER forget to set emitting = false initially for one shot VFX — This prevents unwanted emission at the scene origin before you've had a chance to position the node via script. Choose Table (load only the matching script) MANDATORY for the chosen row. Do NOT Load unused particle scripts for a single effect. Goal Prefer Script Burst / one shot VFX (hit, muzzle, explode) GPUParticles + recycle MANDATORY [particle burst emitter.gd](scripts/particle burst emitter.gd) + [smart oneshot recycler.gd](scripts/smart oneshot recycler.gd) Trails behind movers local coords = false MANDATORY [local vs global coords.gd](scripts/local vs global coords.gd) Weather (rain/snow) heightfield camera snapped collision MANDATORY [screenspace weather heightfield.gd](scripts/screenspace weather heightfield.gd) Million entity swarms MultiMesh, not GPUParticles MANDATORY [massive swarm multimesh.gd](scripts/massive swarm multimesh.gd) Custom GPU motion / userdata process material shader [custom particle logic.gdshader](scripts/custom particle logic.gdshader), [dynamic userdata modulation.gd](scripts/dynamic userdata modulation.gd) Impact sub emitters collision subparticle [sub emitter impact.gdshader](scripts/sub emitter impact.gdshader) Attractors without global cost cull mask isolation [particle attractor opt.gd](scripts/particle attractor opt.gd) Distant env VFX LOD visibility range [particle lod manager.gd](scripts/particle lod manager.gd) 2D physics parented trails stutter CPUParticles2D + fract delta MANDATORY [2d physics interpolation fix.gd](scripts/2d physics interpolation fix.gd) Shader param orchestration material helpers [vfx shader manager.gd](scripts/vfx shader manager.gd) GPUParticles vs CPUParticles vs MultiMesh GPUParticles — default for desktop/console VFX amount budgets. CPUParticles2D — only when 2D physics interpolation / smooth parenting is required (see NEVER). MultiMesh — when entity count leaves the particle domain (fish/insects/debris fields). Available Scripts [smart oneshot recycler.gd](scripts/smart oneshot recycler.gd) Golden path for one shot lifecycle: finished + restart() — never Timer based free. [particle burst emitter.gd](scripts/particle burst emitter.gd) One shot bursts wired to the recycler. [local vs global coords.gd](scripts/local vs global coords.gd) Aura vs trail coordinate space + teleport restart() . [screenspace weather heightfield.gd](scripts/screenspace weather heightfield.gd) Global weather via camera snapped heightfield collision. [massive swarm multimesh.gd](scripts/massive swarm multimesh.gd) Million entity path with set buffer interpolated() . [custom particle logic.gdshader](scripts/custom particle logic.gdshader) Procedural GPU particle motion with CUSTOM/USERDATA. [sub emitter impact.gdshader](scripts/sub emitter impact.gdshader) Collision driven emit subparticle() impacts. [particle attractor opt.gd](scripts/particle attractor opt.gd) Attractor cull mask isolation. [dynamic userdata modulation.gd](scripts/dynamic userdata modulation.gd) Runtime USERDATA without breaking GPU batches. [particle lod manager.gd](scripts/particle lod manager.gd) visibility range hierarchy for env VFX. [2d physics interpolation fix.gd](scripts/2d physics interpolation fix.gd) CPUParticles2D + fract delta for physics parented 2D trails. [vfx shader manager.gd](scripts/vfx shader manager.gd) Custom shader integration helpers for particle materials. Expert Pointers One shots: emitting = false at scene origin → place → restart() ([smart oneshot recycler.gd](scripts/smart oneshot recycler.gd)). Trails: local coords = false or the trail sticks to the projectile. Do not invent explosion/smoke/sparkle material recipes here — Official Docs cover material UI; this skill owns lifecycle, coords, LOD, and swarm routing. Deep dives (on demand) Collision sub emitters, fluid shaders, VFX pools → [expert vfx patterns.md](references/expert vfx patterns.md) VFX pool recycle pattern → [vfx pool manager.gd](scripts/vfx pool manager.gd) WHY GPU particles cannot drive per collision SFX — CPU has no collision callbacks; sub emitters or looping impact beds only. Reference Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice. Official Documentation [Particle systems (2D)](https://docs.godotengine.org/en/stable/tutorials/2d/particle systems 2d.html) — GPUParticles2D/CPUParticles2D setup, amount/lifetime/one shot, and when 2D trails need CPU particles for smooth motion. [ParticleProcessMaterial 2D](https://docs.godotengine.org/en/stable/tutorials/2d/particle process material 2d.html) — emission shapes, gravity/velocity curves, and color ramps that drive most 2D VFX without custom shaders. [Creating a 3D particle system](https://docs.godotengine.org/en/stable/tutorials/3d/particles/creating a 3d particle system.html) — GPUParticles3D scene wiring, process material assignment, and first emission checklist for 3D VFX. [Process material properties](https://docs.godotengine.org/en/stable/tutorials/3d/particles/process material properties.html) — ParticleProcessMaterial emission, forces, scale/color curves, and collision/sub emitter modes used by expert patterns. [Particle properties](https://docs.godotengine.org/en/stable/tutorials/3d/particles/properties.html) — node level amount, lifetime, explosiveness, local coords, visibility AABB, preprocess, and restart/finished lifecycle. [Particle subemitters](https://docs.godotengine.org/en/stable/tutorials/3d/particles/subemitters.html) — chaining impact/debris systems and why a particle system cannot recurse as its own sub emitter. [Particle collision](https://docs.godotengine.org/en/stable/tutorials/3d/particles/collision.html) — GPUParticlesCollision shapes, rigid/hide modes, and GPU collision limits versus CPU synced SFX. [Particle attractors](https://docs.godotengine.org/en/stable/tutorials/3d/particles/attractors.html) — attractor types plus cull mask/layer isolation so global weather does not pay every attractor cost. [Particle trails](https://docs.godotengine.org/en/stable/tutorials/3d/particles/trails.html) — trail ribbons and why smoke/fire trails must use global space ( local coords = false ). [Particle shader](https://docs.godotengine.org/en/stable/tutorials/shaders/shader reference/particle shader.html) — shader type particles , CUSTOM/USERDATA, COLLIDED/ emit subparticle() , and keep data process loops. [Using MultiMesh](https://docs.godotengine.org/en/stable/tutorials/performance/using multimesh.html) — when millions of entities should bypass GPUParticles via MultiMesh + interpolated buffers. [Visibility ranges](https://docs.godotengine.org/en/stable/tutorials/3d/visibility ranges.html) — GeometryInstance3D distance fade/hysteresis that stops distant environmental particle processing. Related Skills Prerequisites [godot project foundations](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot project foundations/SKILL.md) — scenes, resources, and import basics before packing VFX Prefabs and GradientTexture1D materials. [godot gdscript mastery](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot gdscript mastery/SKILL.md) — typed GPUParticles APIs, finished handlers, and safe restart() /await patterns used by pools and burst spawners. [godot shaders basics](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot shaders basics/SKILL.md) — ShaderMaterial workflow and shading language fundamentals required before shader type particles process logic. Complements [godot 3d materials](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot 3d materials/SKILL.md) — draw materials, transparency sorting, and next pass stacks that render quads/meshes spawned by GPUParticles3D. [godot 3d lighting](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot 3d lighting/SKILL.md) — emissive fire/sparks vs environment exposure; pair particle albedo with real lights when VFX must light the scene. [godot audio systems](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot audio systems/SKILL.md) — impact/loop SFX while GPU emitters are active when per particle collision audio is unavailable. [godot performance optimization](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot performance optimization/SKILL.md) — amount budgets, visibility AABB, attractor masks, and MultiMesh cutovers when VFX dominate GPU time. [godot camera systems](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot camera systems/SKILL.md) — camera follow heightfields, visibility range thresholds, and frustum aware weather emitters. [godot signal architecture](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot signal architecture/SKILL.md) — finished and one shot connection hygiene for pooled recyclers that must not leak ghost callbacks. [godot 2d physics](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot 2d physics/SKILL.md) — physics parented 2D trails where CPUParticles2D + interpolation replaces stuttering GPUParticles2D. Downstream / consumers [godot combat system](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot combat system/SKILL.md) — hit sparks, blood/debris bursts, and muzzle FX

godot-particles