Melonjs Particles And Trails Agent Skill

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.

Sprite-sheet particles

Use framewidth and frameheight (the same names as on Sprite) to divide

image into a regular grid. Each omitted dimension defaults to that of the

image. Frames are numbered from zero left-to-right, then top-to-bottom; only

whole cells count, so partial cells along the right/bottom edges are ignored.

Margins and spacing are not supported.

const explosion = new ParticleEmitter(x, y, {
    image: loader.getImage("explosion-sheet"),
    framewidth: 32, frameheight: 32,
    frames: [0, 1, 2, 3],
    minLife: 400, maxLife: 800,
});
world.addChild(explosion);
explosion.burstParticles();

Omit frames to use every cell. Each particle traverses the sequence once

over its own lifetime, with equal time for each entry; repeated indices hold

a frame longer. Existing scale, opacity and rotation still apply. Bounds and

the rotation pivot use one frame's dimensions, rather than the whole sheet.

Set randomFrame: true for debris: a particle chooses one entry at birth and

keeps it until it dies. Different frames share the same image and GPU batch.

Without sheet settings, particles still draw the whole image as before, and

that includes randomFrame on its own: it needs a grid to choose from, so

pair it with framewidth/frameheight or it does nothing.

Note the variety is in SHAPE, not colour. tint belongs to the emitter, so

every particle from one emitter is tinted alike however many frames it picks

between. For a colour that changes over each particle's life, use

tintOverLife (below) rather than drawing one frame per colour.

Frame dimensions must be positive integers that fit inside the image, and an

explicit frames sequence must be nonempty and contain valid integer indices.

Invalid configurations throw RangeError before changing an emitter during

reset(). The frame sequence is copied on construction/reset; resetting changes

only future particles, so ones already alive finish with their original image,

frame size and sequence.

Colour over life: tintOverLife

tintOverLife is the list of tints a particle takes over its life: the first at

birth, the last at the end, evenly spaced and blended in between. Give as many

CSS colours as you like (repeat one to hold it longer); it replaces tint.

// a flame: white hot, then orange, then deep red as it rises and dies
const flame = new ParticleEmitter(x, y, {
    image: softDot,                     // a white texture takes the tints as they are
    tintOverLife: ["#fff3b0", "#ffc455", "#ff8a26", "#e45414", "#a0280c"],
    textureAdditive: true,
});

• Colour only. Opacity is still the built-in fade over the particle's life;

the alpha of a colour in the list is ignored. On an additive emitter, a darker

colour is a dimmer particle, so fold a "fainter" step into the colour itself.

• 32 steps. However many colours, the blend is taken in 32 steps, the same on

every renderer: a particle changes colour at most 32 times. That matters on

Canvas, which keeps a tinted copy of the texture for every colour it is asked

to draw: 32 at most per texture.

• Author the texture white. tint multiplies, so a coloured texture muddies

every step.

• It works alongside sprite-sheet frames (one picks the image, the other the

colour), and a list that is empty, not an array, or holds a non-string throws a

TypeError from the constructor or reset(), which then leaves the emitter as

it was. The list is copied: change it through reset().

Where particles are born

width and height are the spawn AREA, and both default to 1 — so by

default every particle launches from the same pixel. That is fine for a

fountain and wrong for an explosion: additive sprites piled on one point clip

all three channels there however well they are tinted, so a burst reads as one

bright flash rather than as debris.

Give it the size of whatever broke. The area is measured from the emitter's own

position, NOT centred on it, so offset by half or the whole burst sits down and

to the right of its source:

const area = radius * 2;
const emitter = new ParticleEmitter(x - area / 2, y - area / 2, {
    width: area, height: area,
});

Particles in 3D

By default a particle keeps the depth it was born at for its whole life: it

moves across the emitter's plane and never toward or away from the camera.

Under a Camera3d that reads as a flat sticker anywhere but dead ahead.

elevation lifts the launch out of that plane and elevationVariation spreads

it. angle is the azimuth within the plane, as it always was:

const emitter = new ParticleEmitter(x, y, {
    angle: 0, angleVariation: Math.PI * 2,
    elevation: 0, elevationVariation: Math.PI / 2,   // a sphere of debris
    speed: 9,
});
world.addChild(emitter, z);     // the depth slice the burst belongs to
emitter.burstParticles();

speed is the length of the whole 3D vector, so an "all directions" burst

covers the sphere evenly instead of bunching toward the poles.

Both default to 0, and that is a gate rather than the 3D path with zeros in

it: an emitter that asks for no elevation runs the same two trig calls it

always did, writes no depth and starts no sort.

The launch is in WORLD axes. vel.x and vel.y add to the particle's

pos.x/pos.y and velZ adds to its depth, so angle and elevation

describe a direction in the world, not on the screen. Building them from a

camera basis works only while the camera's axes ARE the world axes, which stops

being true the moment you pose a Camera3d. For a direction d already in

world terms the pair is angle: Math.atan2(-d.y, d.x),

elevation: Math.asin(d.z).

Cones, rings and spheres: aiming around an axis

angleVariation and elevationVariation are sampled INDEPENDENTLY, spreading

particles over a rectangle of azimuth by elevation. That cannot describe a

shape defined against a direction. A ring of debris leaving a point on a sphere

is the set of directions at ninety degrees to that point's normal, and on a

rectangle the elevation that satisfies it is a function of the azimuth, so no

pair of variations gets there.

Set maxSpread and angle/elevation become an AXIS instead. Each particle

leaves at a polar angle between minSpread and maxSpread off that axis,

around a uniformly random azimuth:

| minSpread … maxSpread | shape |

|---|---|

| 0 … 0.5 | a tight cone along the axis |

| 0 … Math.PI | the whole sphere |

| either value at Math.PI / 2 | a flat disc perpendicular to the axis |

An explosion on a planet's surface is a ring tangent to it: set the axis to the

surface normal and use minSpread: Math.PI / 2 - 0.3, maxSpread: Math.PI / 2.

Keeping the band at or inside ninety degrees is what stops debris tilting back

into the body it came off. angleVariation and elevationVariation are unused

while maxSpread is set.

Sorting, and why it is keyed off the blend mode

A 3D burst only needs depth sorting when its blend is order dependent, and the

emitter decides that for you. Additive blending is commutative, so an additive

burst looks the same however it is ordered and pays nothing; "normal" is not,

so a 3D burst drawn with it is sorted back to front.

The two differ in more than cost. Additive sprites overlapping near the centre

of a burst sum to white however they are tinted, so debris that has to keep its

colour wants textureAdditive: false and accepts the sort. A common shape is

two emitters: a solid, sorted body of debris with a sparser additive spray of

sparks over it.

The default particle sprite is a filled SQUARE, which additive blending hides

and normal blending does not. Pass your own soft image for non-additive

debris.

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.

| value | particles are measured from | use for |

|---|---|---|

| "local" (default) | the emitter | flames, auras, anything welded to the object |

| "world" | the container the emitter sits in | trails, smoke, exhaust, dust |

| a Container | that container | a moving frame — snow inside a moving carriage |

// 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. Use Trail3d in a 3D scene (20.9.0 and later). Trail

stores points without a z and draws connected screen-space quads, which carry

one depth for the whole renderable, so under a Camera3d the ribbon stays flat

and does not narrow along its own length.

const exhaust = new Trail3d(0, 0, {
    target: ship,                 // samples pos.x / pos.y / pos.z
    width: 6,                     // world units, and free to change per frame
    lifetime: 260,
    gradient: ["#eaffff", "#2ea8ff", "#2ea8ff00"],
});
exhaust.blendMode = "additive";
app.world.addChild(exhaust);      // no z: it derives its own from its points

Trail3d is a Mesh, which is most of the difference:

• billboard is spelled and valued exactly as on Sprite3d —

"spherical" (the default here) faces the camera on all axes,

true / "cylindrical" faces it but stays upright, false uses the

ribbonNormal you give it. billboard: false, ribbonNormal: [0, -1, 0]

lays the ribbon in the ground plane for a tyre mark or a wake.

• tint works, and is the per-frame colour lever. On Trail it does

nothing at all, because the primitive batcher reads the draw colour and never

the tint. setColor() / setGradient() rebuild the gradient for a change of

state; they allocate, so they are not per-frame.

If the colour is going to change, author the gradient WHITE. tint

multiplies, so tinting a cyan ribbon red gives muddy brown rather than red. A

neutral gradient hands the hue entirely to the tint, which is what lets one

lever take a trail from white through to red as something overheats.

• A post effect reaches it properly, where Trail has to force a screen

capture.

• It is cheaper: one indexed draw call, against one filled path per segment.
• length is fixed at construction, because the geometry is sized once.

Assigning maxPoints throws rather than silently truncating the ribbon, and

a length that is not a finite number throws at construction.

• It needs a Camera3d. Under a 2D camera it draws nothing and warns once.

A world-space ParticleEmitter (referenceSpace: "world") is still the right

answer when you want discrete puffs rather than a continuous ribbon.

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

| symptom | cause |

|---|---|

| trail looks flat under a Camera3d | Trail is 2D; use Trail3d |

| particles clutter a minimap or a second camera | every camera draws them: set the emitter's visibilityLayer to a layer that camera's cullMask leaves out (see melonjs-camera-and-drawing) |

| Trail3d draws nothing, with a console warning | it needs a Camera3d; the app's cameraClass is still the 2D default |

| trail.tint does nothing | Trail cannot be tinted at all; Trail3d can |

| assigning maxPoints throws | Trail3d sizes its geometry once; pass length to the constructor |

| Trail3d: \length\ must be a finite number | a computed length came out NaN; it is refused rather than silently rendering nothing |

| emitter added but nothing appears | streamParticles() / burstParticles() never called |

| the cloud follows a moving emitter | default referenceSpace: "local" — use "world" for trails |

| particles do not travel far enough | settings tuned pre-20.2, when drawn travel was doubled |

| one-shot emitters accumulate | missing autoDestroyOnComplete: true |

| every particle of an emitter is the same colour all its life | tint is one value for the emitter: use tintOverLife for a colour that changes as it ages |

| a tintOverLife colour's transparency has no effect | the list sets the colour only; opacity is the particle's fade |

| tintOverLife colours look muddy | the texture is coloured; author it white so the tints come through as given |

| frame rate drops with many effects | an emitter per event instead of one re-aimed emitter |

| a 3D burst is invisible under a Camera3d | before 20.8 a particle was culled at twice its depth; update |

| the whole burst launches from one pixel | width/height are the spawn area and default to 1 |

| the burst sits down-right of its source | the spawn area starts at the emitter's position; offset by half |

| the middle of a burst goes white | additive sprites overlapping — textureAdditive: false, or spread them |

| debris chunks look like squares | the default sprite is a filled square; pass your own image |

| a ring tilts with the camera instead of staying on a surface | the launch axis is in WORLD axes, not the camera basis |

Related skills

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