particles

Particle System

Creating and controlling particle effects in Phaser 4 -- ParticleEmitter creation and configuration, emitter ops (value formats), gravity wells, emission and death zones, flow vs burst modes, following game objects, and particle callbacks.

Key source paths: src/gameobjects/particles/ Related skills: ../sprites-and-images/SKILL.md, ../loading-assets/SKILL.md

Quick Start

// In a Scene's create() method:

// Basic continuous emitter (flow mode)
const emitter = this.add.particles(400, 300, 'flares', {
    frame: 'red',
    speed: 200,
    lifespan: 2000,
    scale: { start: 1, end: 0 },
    alpha: { start: 1, end: 0 },
    gravityY: 150
});

// One-shot burst (explode mode)
const burst = this.add.particles(400, 300, 'flares', {
    frame: 'blue',
    speed: { min: 100, max: 300 },
    lifespan: 1000,
    scale: { start: 0.5, end: 0 },
    emitting: false   // don't auto-start
});
burst.explode(20);    // emit 20 particles at once

Core Concepts

ParticleEmitter

ParticleEmitter extends GameObject and is added directly to the display list. It is both a game object (positionable, scalable, maskable) and the emitter itself. There is no separate manager -- this.add.particles() returns a ParticleEmitter instance.

Factory signature:

this.add.particles(x, y, texture, config);
// x, y: world position (both optional, default 0)
// texture: string key or Texture instance
// config: ParticleEmitterConfig object (optional, can call setConfig later)

Mixins: AlphaSingle, BlendMode, Depth, Lighting, Mask, RenderNodes, ScrollFactor, Texture, Transform, Visible. So you can call setPosition(), setScale(), setDepth(), setBlendMode(), setMask(), setScrollFactor(), etc.

Particle

A lightweight object owned by its emitter. Key properties: x, y, velocityX/Y, accelerationX/Y, scaleX/Y, alpha, angle, rotation, tint, life (total ms), lifeCurrent (remaining ms), lifeT (0-1 normalized), bounce, delayCurrent, holdCurrent. Particles are pooled internally -- you never create them manually.

EmitterOp Value Formats

Most config properties (speed, scale, alpha, angle, x, y, etc.) accept flexible value formats:

x: 400                                        // static value
x: [100, 200, 300, 400]                       // random pick from array
x: { min: 100, max: 700 }                     // random float in range
x: { min: 100, max: 700, int: true }          // random integer
x: { random: [100, 700] }                     // random integer shorthand
scale: { start: 0, end: 1 }                   // ease over lifetime (default linear)
scale: { start: 0, end: 1, ease: 'bounce.out' }  // custom ease
scale: { start: 4, end: 0.5, random: true }   // random start, ease to end
x: { values: [50, 500, 200, 800], interpolation: 'catmull' }  // interpolation
x: { steps: 32, start: 0, end: 576 }          // stepped sequential
x: { steps: 32, start: 0, end: 576, yoyo: true }  // stepped with yoyo
x: {                                           // custom callbacks
    onEmit: (particle, key, t, value) => value,
    onUpdate: (particle, key, t, value) => value
}
x: (particle, key, t, value) => value + 50    // emit-time callback shorthand

Emit-only (no onUpdate): angle, delay, hold, lifespan, quantity, speedX, speedY. Emit + Update (support start/end, onUpdate): accelerationX/Y, alpha, bounce, maxVelocityX/Y, moveToX/Y, rotate, scaleX/Y, tint, x, y.

Flow vs Explode (Burst)

Flow mode (frequency >= 0): emits quantity particles every frequency ms. Default is frequency: 0 (every frame) with emitting: true.

Explode mode (frequency = -1): emits a batch all at once, then stops.

emitter.flow(100, 5);           // 5 particles every 100ms
emitter.flow(100, 5, 50);       // auto-stop after 50 total
emitter.explode(30, 200, 400);  // burst 30 at position
emitter.explode(30);            // burst at emitter position

Common Patterns

Scale, Alpha, and Color Over Lifetime

// Scale and alpha with custom easing
this.add.particles(400, 300, 'spark', {
    lifespan: 2000,
    speed: 100,
    scale: { start: 1, end: 0, ease: 'power2' },
    alpha: { start: 1, end: 0, ease: 'cubic.in' }
});

Color Interpolation

The color property interpolates through an array of colors over particle lifetime (overrides tint):

this.add.particles(400, 300, 'spark', {
    lifespan: 2000, speed: 100, scale: { start: 0.5, end: 0 },
    color: [0xfacc22, 0xf89800, 0xf83600, 0x9f0404], colorEase: 'quad.out'
});

Tinting Particles

this.add.particles(400, 300, 'spark', { tint: 0xff0000 });                           // static
this.add.particles(400, 300, 'spark', { tint: { start: 0xffffff, end: 0xff0000 } }); // over lifetime

Gravity Wells

A GravityWell applies inverse-square gravitational force, pulling (or repelling with negative power) particles toward a point.

const emitter = this.add.particles(400, 300, 'spark', {
    speed: 100, lifespan: 4000, scale: { start: 0.4, end: 0 }, quantity: 2
});

const well = emitter.createGravityWell({
    x: 400, y: 300, power: 2, epsilon: 100, gravity: 50
});

// Update at runtime
well.x = 300;
well.power = -1;  // negative = repel

// Or create manually and add
const well2 = new Phaser.GameObjects.Particles.GravityWell(500, 200, 3, 100, 50);
emitter.addParticleProcessor(well2);
emitter.removeParticleProcessor(well2);

Emission Zones (Random)

A RandomZone spawns particles at random positions within a shape. The source must have a getRandomPoint(point) method -- all Phaser geometry classes (Circle, Ellipse, Rectangle, Triangle, Polygon, Line) support this, or provide a custom source:

// Using built-in geometry
this.add.particles(400, 300, 'spark', {
    speed: 50, lifespan: 2000,
    emitZone: { type: 'random', source: new Phaser.Geom.Circle(0, 0, 100) }
});

// Custom source object (any object with getRandomPoint)
emitter.addEmitZone({
    type: 'random',
    source: {
        getRandomPoint: (point) => {
            const a = Math.random() * Math.PI * 2;
            point.x = Math.cos(a) * 100;
            point.y = Math.sin(a) * 50;
            return point;
        }
    }
});

Emission Zones (Edge)

An EdgeZone places particles sequentially along shape edges. The source must have a getPoints(quantity, stepRate) method. Curves, Paths, and all geometry shapes support this:

this.add.particles(400, 300, 'spark', {
    lifespan: 1500, speed: 20,
    emitZone: {
        type: 'edge',
        source: new Phaser.Geom.Circle(0, 0, 150),
        quantity: 48,     // number of points on edge (use 0 with stepRate instead)
        yoyo: false,      // reverse direction at ends
        seamless: true    // remove duplicate endpoint
    }
});

// Or add post-creation with any source that has getPoints
emitter.addEmitZone({ type: 'edge', source: geom, quantity: 50, yoyo: false, seamless: true });

Multiple emission zones: Pass an array to emitZone or call addEmitZone() multiple times. Zones iterate in sequence. The total property controls how many particles emit before rotating to the next zone (-1 = never rotate).

this.add.particles(400, 300, 'spark', {
    emitZone: [
        { type: 'random', source: new Phaser.Geom.Circle(0, 0, 50) },
        { type: 'random', source: new Phaser.Geom.Circle(200, 0, 50) }
    ]
});

Death Zones

A DeathZone kills particles when they enter (or leave) a region. The source must have a contains(x, y) method.

// Kill particles entering a rectangle
this.add.particles(400, 100, 'spark', {
    speed: 200, lifespan: 5000, gravityY: 100,
    deathZone: { type: 'onEnter', source: new Phaser.Geom.Rectangle(300, 400, 200, 50) }
});

// Kill particles leaving a circle (confine to area)
this.add.particles(400, 300, 'spark', {
    speed: 100, lifespan: 5000,
    deathZone: { type: 'onLeave', source: new Phaser.Geom.Circle(400, 300, 150) }
});

// Custom death zone source (any object with contains)
emitter.addDeathZone({
    type: 'onEnter',
    source: { contains: (x, y) => x > 600 && y > 400 }
});

Following a Game Object

const player = this.add.sprite(100, 100, 'player');
const emitter = this.add.particles(0, 0, 'spark', {
    speed: 50, lifespan: 800, scale: { start: 0.5, end: 0 }
});

emitter.startFollow(player);                       // follow position
emitter.startFollow(player, 10, -20);              // with offset
emitter.startFollow(player, 0, 0, true);           // track visibility too
emitter.stopFollow();

// Or via config:
this.add.particles(0, 0, 'spark', { follow: player, followOffset: { x: 0, y: -20 } });

Particle Callbacks

// Via config
const emitter = this.add.particles(400, 300, 'spark', {
    speed: 100, lifespan: 2000,
    emitCallback: (particle, emitter) => { /* on emit */ },
    deathCallback: (particle) => { /* on death */ }
});

// Or set after creation
emitter.onParticleEmit((particle, emitter) => { /* ... */ });
emitter.onParticleDeath((particle) => { /* ... */ });

// Iterate alive/dead particles
emitter.forEachAlive((particle, emitter) => { /* particle.x, particle.lifeT */ });

Duration, StopAfter, and Advance

// Auto-stop after 3 seconds (alive particles continue until they expire)
this.add.particles(400, 300, 'spark', { speed: 100, duration: 3000 });

// Emit exactly 50 particles then stop
this.add.particles(400, 300, 'spark', { speed: 100, stopAfter: 50 });

// Pre-warm: fast-forward 2 seconds so particles visible on first frame
this.add.particles(400, 300, 'spark', { speed: 100, lifespan: 2000, advance: 2000 });
// Or manually: emitter.fastForward(2000, 50);

Particle Bounds (Bounce)

this.add.particles(400, 300, 'spark', {
    speed: 200, lifespan: 5000, bounce: 0.8,
    bounds: { x: 100, y: 100, width: 600, height: 400 },
    collideLeft: true, collideRight: true, collideTop: true, collideBottom: true
});
// Or: emitter.addParticleBounds(100, 100, 600, 400);

Texture Frames and Animations

// Random frame per particle
this.add.particles(400, 300, 'flares', { frame: ['red', 'green', 'blue'] });

// Sequential frames cycling through with quantity per frame
this.add.particles(400, 300, 'flares', {
    frame: { frames: ['red', 'green', 'blue'], cycle: true, quantity: 4 }
});

// Particle animation (plays anim over particle lifetime)
this.add.particles(400, 300, 'explosion', { anim: 'explode_anim', lifespan: 1000 });

// Multiple anims, randomly assigned
this.add.particles(400, 300, 'sheet', {
    anim: { anims: ['fire', 'smoke'], cycle: false, quantity: 1 }
});

Sorting Particles

this.add.particles(400, 300, 'spark', { sortProperty: 'y', sortOrderAsc: true });
// Or: sortCallback: (a, b) => a.y - b.y

Custom Particle Processor

Extend ParticleProcessor to apply custom per-particle logic each frame. Implement update(particle, delta, step, t):

class WindProcessor extends Phaser.GameObjects.Particles.ParticleProcessor {
    constructor (windX, windY) {
        super(0, 0);
        this.windX = windX;
        this.windY = windY;
    }

    update (particle, delta, step, t) {
        particle.velocityX += this.windX * step;
        particle.velocityY += this.windY * step;
    }
}

emitter.addParticleProcessor(new WindProcessor(0.5, 0));

Custom Particle Class

Extend Particle and override update for per-particle behavior. Set via particleClass in config:

class TrailParticle extends Phaser.GameObjects.Particles.Particle {
    update (delta, step, processors) {
        const result = super.update(delta, step, processors);
        this.alpha = this.lifeT;  // custom: alpha matches life progress
        return result;  // must return true if particle is still alive
    }
}

this.add.particles(400, 300, 'spark', {
    particleClass: TrailParticle,
    speed: 100, lifespan: 2000
});

Configuration Reference

ParticleEmitterConfig -- Simple Properties

Property	Type	Default	Description
active	boolean	true	False = emitter does not update at all
emitting	boolean	true	False = no new particles (alive ones still update)
blendMode	string/number	0	Blend mode for rendering
frequency	number	0	ms between flow cycles; 0 = every frame; -1 = explode
gravityX, gravityY	number	0	Gravity in px/s^2
maxParticles	number	0	Hard limit on total particle objects (0 = unlimited)
maxAliveParticles	number	0	Max alive particles at once (0 = unlimited)
duration	number	0	Auto-stop after ms (0 = forever)
stopAfter	number	0	Auto-stop after N particles emitted (0 = unlimited)
advance	number	0	Fast-forward on creation (ms)
radial	boolean	true	True = speed+angle; false = speedX/speedY
particleBringToTop	boolean	true	New particles render on top
timeScale	number	1	Time multiplier for updates
follow	Vector2Like	null	Object to follow
followOffset	Vector2Like		Offset from follow target
trackVisible	boolean	false	Match follow target's visibility
reserve	number		Pre-allocate particle objects
particleClass	function	Particle	Custom particle class
sortProperty	string		Particle property to sort by
sortOrderAsc	boolean		Sort ascending if true

ParticleEmitterConfig -- EmitterOp Properties

All accept the flexible value formats described above.

Property	Default	E/U	Description
x, y	0	E+U	Particle offset from emitter
speed	0	E	Radial speed (sets speedX, deactivates speedY)
speedX, speedY	0	E	Directional speed (sets radial=false)
angle	{min:0,max:360}	E	Emission angle in degrees
scale	1	E+U	Uniform scale (sets scaleX, deactivates scaleY)
scaleX, scaleY	1	E+U	Non-uniform scale
alpha	1	E+U	Alpha transparency
rotate	0	E+U	Rotation in degrees
tint	0xffffff	E+U	Tint color (WebGL)
color		E+U	Color array to interpolate (overrides tint)
colorEase			Ease for color interpolation
lifespan	1000	E	Lifetime in ms
delay	0	E	Delay before visible (ms)
hold	0	E	Hold at end of life before dying (ms)
quantity	1	E	Particles per flow cycle
accelerationX/Y	0	E+U	Acceleration (px/s^2)
maxVelocityX/Y	10000	E+U	Max velocity
bounce	0	E+U	Bounce restitution (0-1)
moveToX, moveToY	0	E+U	Target position (overrides angle/speed)

E = emit-only, E+U = emit + update (supports start/end, onUpdate)

Zone Config Properties

Config Key	Type	Properties
emitZone	object or array	{ type: 'random', source: <shape> }
		{ type: 'edge', source: <shape>, quantity, stepRate, yoyo, seamless, total }
deathZone	object or array	{ type: 'onEnter'|'onLeave', source: <shape> }
bounds	object	{ x, y, width, height } or { x, y, w, h }

Events

All events are emitted on the ParticleEmitter instance itself.

Event	String	Callback Args	When
START	'start'	(emitter)	start() is called and emitter begins emitting
STOP	'stop'	(emitter)	stop() is called, or duration/stopAfter limit reached
COMPLETE	'complete'	(emitter)	Final alive particle dies after emitter has stopped
EXPLODE	'explode'	(emitter, particle)	explode() is called
DEATH_ZONE	'deathzone'	(emitter, particle, zone)	A death zone kills a particle

emitter.on('stop', (emitter) => { /* stopped emitting */ });
emitter.on('complete', (emitter) => { /* all particles dead */ });
emitter.on('deathzone', (emitter, particle, zone) => { /* ... */ });

API Quick Reference

ParticleEmitter Key Methods

Lifecycle: start(advance?, duration?), stop(kill?), pause(), resume(), flow(frequency, count?, stopAfter?), explode(count?, x?, y?), emitParticleAt(x?, y?, count?), emitParticle(count?, x?, y?), fastForward(time, delta?).

Config: setConfig(config), updateConfig(config).

Following: startFollow(target, offX?, offY?, trackVisible?), stopFollow().

Zones: addEmitZone(config), removeEmitZone(zone), clearEmitZones(), addDeathZone(config), removeDeathZone(zone), clearDeathZones().

Processors: createGravityWell(config), addParticleProcessor(processor), removeParticleProcessor(processor), getProcessors().

Bounds: addParticleBounds(x, y, w, h, collideL?, collideR?, collideT?, collideB?).

Callbacks/Iteration: onParticleEmit(cb, ctx?), onParticleDeath(cb, ctx?), killAll(), forEachAlive(cb, ctx?), forEachDead(cb, ctx?).

Counts: getAliveParticleCount(), getDeadParticleCount(), getParticleCount(), atLimit(), reserve(count).

Property setters: setParticleSpeed(x, y?), setParticleScale(x, y?), setParticleGravity(x, y), setParticleAlpha(value), setParticleTint(value), setParticleLifespan(value), setEmitterAngle(value), setQuantity(qty), setFrequency(freq, qty?), setRadial(value), setEmitterFrame(frames, random?, qty?), setAnim(anims, random?, qty?).

Sorting: setSortProperty(property, ascending?), setSortCallback(callback), depthSort().

Utility: getBounds(padding?, advance?, delta?, output?), overlap(target).

GravityWell

Property/Method	Description
x, y	World position of the well
power	Force strength (negative to repel)
epsilon	Min distance for force calc (default 100)
gravity	Gravitational constant (default 50)
active	Enable/disable processing (inherited from ParticleProcessor)

Constructor: new GravityWell(x, y, power, epsilon, gravity) or new GravityWell(config) where config is { x, y, power, epsilon, gravity }.

Gotchas

• No ParticleEmitterManager: Removed in v3.60. this.add.particles() returns a ParticleEmitter directly.
• speed vs speedX/speedY: speed sets speedX and deactivates speedY (radial). speedX/speedY switches to point mode (radial: false).
• scale vs scaleX/scaleY: scale applies to scaleX and deactivates scaleY. Use both for non-uniform scaling.
• color overrides tint: They are mutually exclusive; color (array) takes priority.
• moveToX/moveToY: Both must be set to activate. Overrides angle and speed.
• emitting vs active: emitting: false = no new particles but alive ones update. active: false = entire emitter frozen.
• stop vs complete: 'stop' fires when emission stops. 'complete' fires when the last alive particle dies.
• frequency: 0: Means emit every frame (max rate), not "never." Use emitting: false to prevent emission.
• frequency: -1: Puts the emitter in explode mode -- it will not flow automatically. Use explode() to emit bursts.
• hold freezes particle: After lifespan expires, hold keeps the particle visible and frozen for the specified ms before it dies. Useful for trail/lingering effects.
• advance fast-forwards: Pre-warms the emitter by simulating the given ms on creation, so particles are already visible on the first frame.
• reserve(count) pre-allocates: Call reserve() or set reserve in config to pre-create particle objects upfront, avoiding GC spikes during gameplay from on-demand allocation.
• Zone source methods: RandomZone needs getRandomPoint(point). EdgeZone needs getPoints(quantity, stepRate). DeathZone needs contains(x, y).
• Particle pool: maxParticles limits total objects (not alive count). Use maxAliveParticles for visible limit.
• Texture required: The emitter needs a valid texture key. Use frame config for multi-frame textures.

Source Files

See references/REFERENCE.md for the full source file map. Key entry points: src/gameobjects/particles/ParticleEmitter.js (main class), src/gameobjects/particles/Particle.js (individual particle), src/gameobjects/particles/zones/ (zone classes).