melonjs-particles-and-trails
Use this skill for particle effects and motion trails in melonJS — ParticleEmitter configuration, burst versus stream emission, the referenceSpace frame of reference introduced in 20.2, 3D particle motion through elevation and minSpread/maxSpread in 20.8, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: Trail3d, ribbon, exhaust trail, speed streak, ski track, tyre mark, ribbonNormal, ParticleEmitter, particles, particle editor, tune particles, spawn depth, volume, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter, tintOverLife, colour over life, color over life, flame, fire.
melonjs · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add melonjs/melonJS --skill melonjs-particles-and-trailsAbout this skill
name: melonjs-particles-and-trails description: "Use this skill for particle effects and motion trails in melonJS — ParticleEmitter configuration, burst versus stream emission, the referenceSpace frame of reference introduced in 20.2, 3D particle motion through elevation and minSpread/maxSpread in 20.8, and the Trail renderable. Covers the emitter that silently does nothing until you call an emit method. Triggers on: Trail3d, ribbon, exhaust trail, speed streak, ski track, tyre mark, ribbonNormal, ParticleEmitter, particles, particle editor, tune particles, spawn depth, volume, burstParticles, streamParticles, referenceSpace, ParticleEmitterSettings, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter, tintOverLife, colour over life, color over life, flame, fire." license: MIT
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.
Without an image, particles are white squares of textureSize pixels (8 by
default), coloured by tint. Every such emitter draws the renderer's one
shared white pixel, stretched, so an emitter per explosion or a reset() on
every tweak costs no texture.
Tuning an effect: the Particle Editor
Settings are easier to find by eye than by reasoning. The
Particle Editor
runs one emitter live, with every setting on a slider, from a preset (fire,
smoke, rain, explosions, 3D bursts and rings…), a built-in texture or a sprite
(sheet) of your own, under a 2D camera or an orbiting 3D one. It writes out the
matching new ParticleEmitter(...) call, listing only what differs from the
defaults, and the same settings as JSON, in the emitter's own units, to load at
run time:
// preloaded with { name: "smoke-fx", type: "json", src: "data/fx/smoke.json" }
const effect = loader.getJSON("smoke-fx");
const emitter = new ParticleEmitter(x, y, {
...effect.settings,
// no `image` for the plain square: `getImage` would give null
...(effect.image ? { image: loader.getImage(effect.image) } : {}),
});
Point a user there when they are tuning numbers by trial and error.
It covers every setting that changes how one emitter looks, but not:
- Layered effects. It shows one emitter at a time. A campfire (flames,
sparks, smoke) or an explosion (flash, debris, smoke) is several emitters
at the same spot: tune each in the editor, then add them side by side,
the one drawn on top last (or with a higher
z). - Trails.
TrailandTrail3dare separate renderables; see below. - Code-only settings.
onComplete,autoDestroyOnComplete,accurateBounds, and aContainerasreferenceSpace(it offers"local"and"world").textureAdditiveis left out:blendModereplaces it. - Changes at run time. Calling
burstParticles()when something happens, or assigningemitter.blendModewhile particles are alive, is game code. Its "moving emitter" option previews the common case: an emitter attached to something that moves.
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
Read the complete source ↗