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.