godot-particles

Godot 4.7 Baseline

• Expert patterns in this skill target Godot 4.7+ (stable, 2026-06-18).
• Consult the Godot 4.7 migration guide when upgrading projects from 4.6.
• NEVER assume 4.6 defaults (stretch mode, audio area_mask, RichTextLabel percent flags) without checking 4.7 migration notes.

Particle Systems

GPU-accelerated rendering, material-based configuration, and sub-emitters define performant VFX.

Available Scripts

vfx_shader_manager.gd

Expert custom shader integration for advanced particle VFX.

particle_burst_emitter.gd

One-shot particle bursts with auto-cleanup - essential for VFX systems.

custom_particle_logic.gdshader

Expert procedural particle movement logic. Demonstrates persistent CUSTOM data and USERDATA injection for dynamic wind/orbit effects.

sub_emitter_impact.gdshader

High-performance collision handling. Triggers sub-emitters (splashes/debris) using emit_subparticle() and COLLISION_NORMAL.

particle_attractor_opt.gd

Optimization pattern using cull_mask to isolate particle-attractor interactions, preventing global performance bottlenecks.

massive_swarm_multimesh.gd

Bypassing GPUParticles for millions of entities (fish, insects). Uses set_buffer_interpolated() for jitter-free high-count movement.

dynamic_userdata_modulation.gd

Clean architectual pattern for passing runtime variables to particle shaders via USERDATA to preserve GPU batching.

local_vs_global_coords.gd

Expert logic for switching between localized (Auras) and global (Trails) space. Includes correct restart() handling for teleports.

smart_oneshot_recycler.gd

Robust lifecycle management using the finished signal and restart() to avoid async emission failures.

screenspace_weather_heightfield.gd

Optimizing global weather (Rain/Snow) using Camera-snapped GPUParticlesCollisionHeightField3D.

particle_lod_manager.gd

Hierarchical LOD for environmental VFX. Uses visibility_range and margins to cull distant torches or fires completely.

2d_physics_interpolation_fix.gd

Expert workaround for 2D particle stuttering. Switches to CPUParticles2D with fract_delta for smooth physics-parented movement.

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 forget to queue_free() one-shot particles — Use the finished signal instead of an arbitrary Timer for safe lifecycle management.
• 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.

---

Basic Setup

# Add GPUParticles2D node
# Set Amount: 32
# Set Lifetime: 1.0
# Set One Shot: true (for explosions)

Particle Material

# Create ParticleProcessMaterial
var material := ParticleProcessMaterial.new()

# Emission shape
material.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_SPHERE
material.emission_sphere_radius = 10.0

# Gravity
material.gravity = Vector3(0, 98, 0)

# Velocity
material.initial_velocity_min = 50.0
material.initial_velocity_max = 100.0

# Color
material.color = Color.ORANGE_RED

# Apply to godot-particles
$GPUParticles2D.process_material = material

Common Effects

Explosion

extends GPUParticles2D

func _ready() -> void:
    one_shot = true
    amount = 64
    lifetime = 0.8
    explosiveness = 0.9
    
    var mat := ParticleProcessMaterial.new()
    mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_SPHERE
    mat.emission_sphere_radius = 5.0
    mat.initial_velocity_min = 100.0
    mat.initial_velocity_max = 200.0
    mat.gravity = Vector3(0, 200, 0)
    mat.scale_min = 0.5
    mat.scale_max = 1.5
    
    process_material = mat
    emitting = true

Smoke Trail

extends GPUParticles2D

func _ready() -> void:
    amount = 16
    lifetime = 2.0
    
    var mat := ParticleProcessMaterial.new()
    mat.direction = Vector3(0, -1, 0)
    mat.initial_velocity_min = 20.0
    mat.initial_velocity_max = 40.0
    mat.scale_min = 0.5
    mat.scale_max = 1.0
    mat.color = Color(0.5, 0.5, 0.5, 0.5)
    
    process_material = mat

Sparkles/Stars

var mat := ParticleProcessMaterial.new()
mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_BOX
mat.emission_box_extents = Vector3(100, 100, 0)
mat.gravity = Vector3.ZERO
mat.angular_velocity_min = -180
mat.angular_velocity_max = 180
mat.scale_min = 0.1
mat.scale_max = 0.5

# Use star texture
$GPUParticles2D.texture = load("res://textures/star.png")
$GPUParticles2D.process_material = mat

Spawn Particles on Demand

# player.gd
const EXPLOSION_EFFECT := preload("res://effects/explosion.tscn")

func die() -> void:
    var explosion := EXPLOSION_EFFECT.instantiate()
    get_parent().add_child(explosion)
    explosion.global_position = global_position
    explosion.emitting = true
    queue_free()

3D Particles

extends GPUParticles3D

func _ready() -> void:
    amount = 100
    lifetime = 3.0
    
    var mat := ParticleProcessMaterial.new()
    mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_BOX
    mat.emission_box_extents = Vector3(10, 0.1, 10)
    mat.direction = Vector3.UP
    mat.initial_velocity_min = 2.0
    mat.initial_velocity_max = 5.0
    mat.gravity = Vector3(0, -9.8, 0)
    
    process_material = mat

Color Gradients

var mat := ParticleProcessMaterial.new()

# Create gradient
var gradient := Gradient.new()
gradient.add_point(0.0, Color.YELLOW)
gradient.add_point(0.5, Color.ORANGE)
gradient.add_point(1.0, Color(0.5, 0.0, 0.0, 0.0))  # Fade to transparent red

var gradient_texture := GradientTexture1D.new()
gradient_texture.gradient = gradient

mat.color_ramp = gradient_texture

Sub-Emitters

# Particles that spawn godot-particles (fireworks)
$ParentParticles.sub_emitter = $ChildParticles.get_path()
$ParentParticles.sub_emitter_mode = GPUParticles2D.SUB_EMITTER_AT_END

Best Practices

1. Use Texture for Shapes

# Add texture to godot-particles
$GPUParticles2D.texture = load("res://textures/particle.png")

2. Lifetime Management

# Auto-delete one-shot godot-particles
if one_shot:
    await get_tree().create_timer(lifetime).timeout
    queue_free()

3. Performance

# Reduce amount for mobile
if OS.get_name() == "Android":
    amount = amount / 2

---

Expert Pattern: Particle-Audio-Syncer (Collision Sub-Emitters)

GPU particles do not emit CPU signals for individual collisions. To sync visual impacts, use the Sub-Emitter system to spawn secondary effects (sparks, dust) on contact.

func setup_collision_vfx(primary: GPUParticles3D, impact: GPUParticles3D) -> void:
    # 1. Assign impact system as sub-emitter
    primary.sub_emitter = primary.get_path_to(impact)
    
    var mat := primary.process_material as ParticleProcessMaterial
    if mat:
        # 2. Enable collision and set trigger mode
        mat.collision_mode = ParticleProcessMaterial.COLLISION_RIGID
        mat.sub_emitter_mode = ParticleProcessMaterial.SUB_EMITTER_AT_COLLISION
        mat.sub_emitter_amount_at_collision = 1 # Spawn 1 spark per impact

[!IMPORTANT] Since the CPU cannot track individual GPU collisions, sync audio by playing a randomized looping "impact" sound while the primary emitter is active, or use CPUParticles for precise RayCast-driven audio timing.

---

Expert Pattern: Fluid-Simulation-Particles (Custom Shaders)

For high-performance liquid or swarm effects, bypass ParticleProcessMaterial and use a custom particles shader with state persistence.

shader_type particles;
// 'keep_data' allows the shader to remember state between frames
render_mode keep_data;

void start() {
    if (RESTART) {
        // Initialize position and custom fluid density
        TRANSFORM[3].xyz = EMISSION_TRANSFORM[3].xyz;
        CUSTOM.x = 1.0; 
    }
}

void process() {
    // Apply gravity and attractor forces
    VELOCITY += ATTRACTOR_FORCE * DELTA;
    
    // Built-in GPU collision handling
    if (COLLIDED) {
        VELOCITY = reflect(VELOCITY, COLLISION_NORMAL) * 0.5;
        TRANSFORM[3].xyz += COLLISION_NORMAL * COLLISION_DEPTH;
    }
}

---

Expert Pattern: VFX-Pool-Manager

Prevent frame-spikes from frequent instantiate() and queue_free() calls by pooling and reusing one-shot particle systems.

class_name VFXPool extends Node

@export var vfx_scene: PackedScene
var pool: Array[GPUParticles3D] = []

func _ready() -> void:
    for i in 20:
        var inst := vfx_scene.instantiate() as GPUParticles3D
        add_child(inst)
        inst.emitting = false
        inst.finished.connect(func(): pool.append(inst))
        pool.append(inst)

func spawn(pos: Vector3) -> void:
    if pool.is_empty(): return
    var vfx = pool.pop_back()
    vfx.global_position = pos
    # Use restart() to avoid async GPU state delays
    vfx.restart()

Reference

• Godot Docs: Particles

Related

• Master Skill: godot-master