Melonjs Particles And Trails

Particles and trails

An emitter does nothing until you tell it to emit

Adding a ParticleEmitter to the world is not enough. Nothing appears, and nothing warns you.

const emitter = new ParticleEmitter(x, y, {
    image: loader.getImage("spark"),
    totalParticles: 60,
    speed: 4,
    minLife: 200, maxLife: 800,
});

world.addChild(emitter);
emitter.streamParticles();     // continuous — or:
emitter.burstParticles();      // one shot

streamParticles(ms) takes an optional run time; without one it uses the duration setting, which defaults to Infinity — a stream runs until stopStream(). burstParticles(n) launches n, or totalParticles.

For one-shot effects, autoDestroyOnComplete: true removes the emitter once its particles have finished. The onComplete callback fires at that same moment either way.

For repeated effects (muzzle flashes, impacts) keep one long-lived emitter and re-aim it per shot, rather than allocating an emitter per event.

referenceSpace — which frame particles live in

Added in 20.2. This decides what a particle's position is measured from, and it is the difference between an effect that trails behind a moving object and one that drags along with it.

// exhaust that stays where it was emitted, so the ship flies away from it
const exhaust = new ParticleEmitter(x, y, { referenceSpace: "world", /* … */ });

With the default "local", a moving emitter carries its whole cloud along — which is right for a torch flame and wrong for a smoke trail. Changing it at runtime re-bases live particles, so nothing jumps.

Particle tuning changed in 20.2

The 20.2 particle transform fix corrected a drift where drawn positions ran past simulated ones. Particles now travel roughly half as far over their life as they did before.

Consequence: speed values tuned on 19.x or earlier look wrong on 20.2+. If you are copying emitter settings from older code or older tutorials, expect to raise speed or maxLife.

Trails

Trail is a ribbon that follows a target — use it rather than hand-rolling a position history. Its constructor takes one argument, the options object — no x, y pair like every other renderable:

const trail = new Trail({
    target: sprite,             // a renderable or a plain Vector2d
    length: 24,                 // max points kept (default 20)
    width: 20,                  // max ribbon width in px (default 10)
    lifetime: 500,              // per-point lifetime in ms (default 500)
    widthCurve: [1, 0],         // 0 = head, 1 = tail
    gradient: ["#fff", "#f80", "#f000"],
});
trail.blendMode = "additive";
world.addChild(trail, 5);

Omit target and feed it yourself with trail.addPoint(x, y) — the mode for a sword slash, where the ribbon follows a weapon tip rather than an object. Points closer together than minDistance (default 4 px) are dropped.

Trail is 2D. addPoint takes (x, y), points are stored without a z, and the ribbon is drawn as connected screen-space quads. Under a Camera3d it draws a flat ribbon that does not recede with perspective — so it is the wrong tool for a trail behind an object moving into the scene. For that:

• ParticleEmitter with referenceSpace: "world" — particles stay where they were dropped while the emitter moves on, and the emitter propagates its depth to each particle so Camera3d projects them correctly. This is the built-in answer for exhaust, ski tracks and speed trails in 3D.
• A procedural Mesh built from the object's recent path, with mesh.vertexColors for a per-vertex gradient — more work, but a continuous ribbon rather than discrete puffs.

Performance

• Particles come from a shared pool, so a steady-state emitter allocates nothing. Each emitter is still a Container that updates and draws every frame, so one busy emitter beats many idle ones.
• totalParticles (default 50) is a cap on how many are alive at once in stream mode; burstParticles() launches that many in one go, or the count you pass.
• framesToSkip (default 0) skips n updates between simulation steps — the cheapest lever on an emitter with many particles.
• Blending is per particle, set through the blendMode setting or by assigning emitter.blendMode (which reaches the particles already alive as well as later ones). Additive is cheap everywhere: fixed-function on both GPU backends, native lighter on Canvas. The expensive modes are the advanced CSS ones (overlay, soft-light, color-dodge, darken, …), which on WebGL 2 and WebGPU cost a destination capture plus a shader composite per blended draw.

Symptom → cause

Related skills

• melonjs-renderables — draw order and blend modes
• melonjs-effects-and-shaders — blend mode cost on each backend