| name | godot-particles |
| description | 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, emission_shape, color_ramp, sub_emitter, one_shot. |
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
Golden path for one-shot lifecycle: finished + restart() — never Timer-based free.
One-shot bursts wired to the recycler.
Aura vs trail coordinate space + teleport restart().
Global weather via camera-snapped heightfield collision.
Million-entity path with set_buffer_interpolated().
Procedural GPU particle motion with CUSTOM/USERDATA.
Collision-driven emit_subparticle() impacts.
Attractor cull_mask isolation.
Runtime USERDATA without breaking GPU batches.
visibility_range hierarchy for env VFX.
CPUParticles2D + fract_delta for physics-parented 2D trails.
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.
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.
