godot-particles

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) — GPUParticles2D/CPUParticles2D setup, amount/lifetime/one-shot, and when 2D trails need CPU particles for smooth motion.
• ParticleProcessMaterial 2D — emission shapes, gravity/velocity curves, and color ramps that drive most 2D VFX without custom shaders.
• Creating a 3D particle system — GPUParticles3D scene wiring, process material assignment, and first-emission checklist for 3D VFX.
• Process material properties — ParticleProcessMaterial emission, forces, scale/color curves, and collision/sub-emitter modes used by expert patterns.
• Particle properties — node-level amount, lifetime, explosiveness, local_coords, visibility AABB, preprocess, and restart/finished lifecycle.
• Particle subemitters — chaining impact/debris systems and why a particle system cannot recurse as its own sub-emitter.
• Particle collision — GPUParticlesCollision* shapes, rigid/hide modes, and GPU collision limits versus CPU-synced SFX.
• Particle attractors — attractor types plus cull_mask/layer isolation so global weather does not pay every attractor cost.
• Particle trails — trail ribbons and why smoke/fire trails must use global space (local_coords = false).
• Particle shader — shader_type particles, CUSTOM/USERDATA, COLLIDED/emit_subparticle(), and keep_data process loops.
• Using MultiMesh — when millions of entities should bypass GPUParticles via MultiMesh + interpolated buffers.
• Visibility ranges — GeometryInstance3D distance fade/hysteresis that stops distant environmental particle processing.

Related Skills

Prerequisites

• godot-project-foundations — scenes, resources, and import basics before packing VFX Prefabs and GradientTexture1D materials.
• godot-gdscript-mastery — typed GPUParticles APIs, finished handlers, and safe restart()/await patterns used by pools and burst spawners.
• godot-shaders-basics — ShaderMaterial workflow and shading-language fundamentals required before shader_type particles process logic.

Complements

• godot-3d-materials — draw materials, transparency sorting, and next_pass stacks that render quads/meshes spawned by GPUParticles3D.
• godot-3d-lighting — emissive fire/sparks vs environment exposure; pair particle albedo with real lights when VFX must light the scene.
• godot-audio-systems — impact/loop SFX while GPU emitters are active when per-particle collision audio is unavailable.
• godot-performance-optimization — amount budgets, visibility AABB, attractor masks, and MultiMesh cutovers when VFX dominate GPU time.
• godot-camera-systems — camera-follow heightfields, visibility-range thresholds, and frustum-aware weather emitters.
• godot-signal-architecture — finished and one-shot connection hygiene for pooled recyclers that must not leak ghost callbacks.
• godot-2d-physics — physics-parented 2D trails where CPUParticles2D + interpolation replaces stuttering GPUParticles2D.

Downstream / consumers

• godot-combat-system — hit sparks, blood/debris bursts, and muzzle FX spawned from damage resolution.
• godot-ability-system — cast/channel/impact VFX attached to ability lifecycle and targeting feedback.
• godot-genre-shooter — muzzle flash, tracers, explosions, and environmental smoke stacks built on these particle patterns.
• godot-monte-carlo-balancer — when VFX density/readability changes perceived difficulty or telegraph clarity, simulate juice budgets with combat outcomes.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.