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 aParticleEmitterdirectly. speedvsspeedX/speedY:speedsets speedX and deactivates speedY (radial).speedX/speedYswitches to point mode (radial: false).scalevsscaleX/scaleY:scaleapplies to scaleX and deactivates scaleY. Use both for non-uniform scaling.coloroverridestint: They are mutually exclusive;color(array) takes priority.moveToX/moveToY: Both must be set to activate. Overridesangleandspeed.emittingvsactive:emitting: false= no new particles but alive ones update.active: false= entire emitter frozen.stopvscomplete:'stop'fires when emission stops.'complete'fires when the last alive particle dies.frequency: 0: Means emit every frame (max rate), not "never." Useemitting: falseto prevent emission.frequency: -1: Puts the emitter in explode mode -- it will not flow automatically. Useexplode()to emit bursts.holdfreezes particle: After lifespan expires,holdkeeps the particle visible and frozen for the specified ms before it dies. Useful for trail/lingering effects.advancefast-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: Callreserve()or setreservein config to pre-create particle objects upfront, avoiding GC spikes during gameplay from on-demand allocation.- Zone source methods: RandomZone needs
getRandomPoint(point). EdgeZone needsgetPoints(quantity, stepRate). DeathZone needscontains(x, y). - Particle pool:
maxParticleslimits total objects (not alive count). UsemaxAliveParticlesfor visible limit. - Texture required: The emitter needs a valid texture key. Use
frameconfig 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).