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: 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.

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

Golden path for one-shot lifecycle: finished + restart() — never Timer-based free.

particle_burst_emitter.gd

One-shot bursts wired to the recycler.

local_vs_global_coords.gd

Aura vs trail coordinate space + teleport restart().

screenspace_weather_heightfield.gd

Global weather via camera-snapped heightfield collision.

massive_swarm_multimesh.gd

Million-entity path with set_buffer_interpolated().

custom_particle_logic.gdshader

Procedural GPU particle motion with CUSTOM/USERDATA.

sub_emitter_impact.gdshader

Collision-driven emit_subparticle() impacts.

particle_attractor_opt.gd

Attractor cull_mask isolation.

dynamic_userdata_modulation.gd

Runtime USERDATA without breaking GPU batches.

particle_lod_manager.gd

visibility_range hierarchy for env VFX.

2d_physics_interpolation_fix.gd

CPUParticles2D + fract_delta for physics-parented 2D trails.

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).
• 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
• VFX pool recycle pattern → vfx_pool_manager.gd
• WHY GPU particles cannot drive per-collision SFX — CPU has no collision callbacks; sub-emitters or looping impact beds only.