/particles-vfx

name: particles-vfx
description: Use when implementing particle effects — GPUParticles2D/3D, ParticleProcessMaterial, emission shapes, subemitters, trails, attractors, collision, and common VFX recipes

Particle Systems in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.

> **Related skills:** **shader-basics** for custom particle shaders, **3d-essentials** for lighting and environment that affect particles, **2d-essentials** for 2D rendering context, **tween-animation** for code-driven VFX timing, **godot-optimization** for particle performance tuning.

---

1. Core Concepts

GPU vs CPU Particles

| Node | Processing | Features | Use For | |---------------------|------------|-----------------------------------------|--------------------------------| | `GPUParticles2D` | GPU | Full features, high counts, trails | Most 2D effects | | `GPUParticles3D` | GPU | Full features, attractors, collision | Most 3D effects | | `CPUParticles2D` | CPU | Simpler, no trails/attractors | Low-end devices, few particles | | `CPUParticles3D` | CPU | Simpler, no trails/attractors | Low-end devices, few particles |

**Rule of thumb:** Use GPU particles by default. Switch to CPU particles only for low-end/web targets or when you need CPU-side particle positions (e.g., spawning objects at particle locations).

> You can convert between GPU and CPU particles in the editor: select the node → toolbar → **Convert to CPUParticles2D/3D** (or vice versa).

Particle System Architecture

GPUParticles2D/3D
├── Process Material (ParticleProcessMaterial)   ← physics, emission, color
├── Draw Pass 1 (Mesh)                            ← what each particle looks like
└── (Optional) Draw Pass 2-4                      ← additional meshes

Minimal Setup

1. Add a **GPUParticles2D** (or 3D) node 2. In Inspector → Process Material → **New ParticleProcessMaterial** 3. Set **Amount** (number of particles) 4. Configure emission, direction, velocity, gravity 5. (2D) Set **Texture** for particle appearance 6. (3D) Set **Draw Pass 1** mesh (QuadMesh for billboards, or custom mesh)

---

2. Key Node Properties

GPUParticles2D/3D Properties

| Property | Type | Description | |-------------------|----------|-----------------------------------------------------| | `emitting` | `bool` | Start/stop emission | | `amount` | `int` | Total particles alive at once | | `lifetime` | `float` | Seconds each particle lives | | `one_shot` | `bool` | Emit once then stop | | `preprocess` | `float` | Simulate this many seconds before first frame | | `speed_scale` | `float` | Time multiplier for particle physics | | `explosiveness` | `float` | 0.0 = spread over lifetime, 1.0 = all at once | | `fixed_fps` | `int` | Lock particle update rate (0 = match render FPS) | | `local_coords` | `bool` | Particles move with the node (true) or stay in world (false) | | `draw_order` | `enum` | Index, Lifetime, or Reverse Lifetime | | `amount_ratio` | `float` | Fraction of particles to emit (0.0–1.0) |

One-Shot vs Continuous

# Continuous emitter (fire, smoke, ambient dust)
$GPUParticles2D.one_shot = false
$GPUParticles2D.emitting = true

# One-shot burst (explosion, impact splash)
$GPUParticles2D.one_shot = true
$GPUParticles2D.emitting = false  # arm it
# Later, trigger:
$GPUParticles2D.restart()
$GPUParticles2D.emitting = true

// Continuous
var particles = GetNode<GpuParticles2D>("GPUParticles2D");
particles.OneShot = false;
particles.Emitting = true;

// One-shot burst
particles.OneShot = true;
particles.Emitting = false;
// Trigger:
particles.Restart();
particles.Emitting = true;

Local Billboard Alignment (Godot 4.7+)

`GPUParticles3D` gains `TRANSFORM_ALIGN_LOCAL_BILLBOARD` (`= 4`): each particle's Z axis faces the camera while preserving a given axis — X or Y, chosen via `transform_align_axis`. For billboarded particles, `transform_align_channel_filter` selects which custom channel to read to calculate their angle. `ParticleProcessMaterial` pairs this with per-axis rotation velocity: enable `use_rotation_velocity_3d`, then set `rotation_velocity_3d_min/max` (`Vector3`, on the particle's local axes) and optionally `rotation_velocity_3d_curve` (per-axis curve over lifetime).

# 3D only — billboard toward the camera while keeping the Y axis fixed.
# Assumes a ParticleProcessMaterial is assigned (section 1 setup).
$GPUParticles3D.transform_align = GPUParticles3D.TRANSFORM_ALIGN_LOCAL_BILLBOARD
$GPUParticles3D.transform_align_axis = RenderingServer.PARTICLES_ALIGN_AXIS_Y

var mat: ParticleProcessMaterial = $GPUParticles3D.process_material
mat.use_rotation_velocity_3d = true
mat.rotation_velocity_3d_min = Vector3(-2.0, 0.0, 0.0)
mat.rotation_velocity_3d_max = Vector3(2.0, 0.0, 0.0)

// Assumes a ParticleProcessMaterial is assigned (section 1 setup).
var particles = GetNode<GpuParticles3D>("GPUParticles3D");
particles.TransformAlign = GpuParticles3D.TransformAlignEnum.LocalBillboard;
particles.TransformAlignAxis = RenderingServer.ParticlesTransformAlignAxis.Y;

var mat = (ParticleProcessMaterial)particles.ProcessMaterial;
mat.UseRotationVelocity3D = true;
mat.RotationVelocity3DMin = new Vector3(-2.0f, 0.0f, 0.0f);
mat.RotationVelocity3DMax = new Vector3(2.0f, 0.0f, 0.0f);

---

3. ParticleProcessMaterial — Essential Properties

The material drives per-particle behavior: **emission shape** (Point / Sphere / Box / Ring / Points / Directed Points), **directio