- name
SKILL.md
Die Skill-Datei bleibt im Repository des Herausgebers.
Fügen Sie den kopierten Befehl in ein Terminal ein. Er installiert diese SKILL.md in dem jeweiligen Agenten.
npx skills add melonjs/melonJS --skill melonjs-particles-and-trails -a cursor -yFügen Sie den kopierten Befehl in ein Terminal ein. Er installiert diese SKILL.md in dem jeweiligen Agenten.
npx skills add melonjs/melonJS --skill melonjs-particles-and-trails -a claude-code -yFügen Sie den kopierten Befehl in ein Terminal ein. Er installiert diese SKILL.md in dem jeweiligen Agenten.
npx skills add melonjs/melonJS --skill melonjs-particles-and-trails -a codex -yFügen Sie den kopierten Befehl in ein Terminal ein. Er installiert diese SKILL.md in dem jeweiligen Agenten.
npx skills add melonjs/melonJS --skill melonjs-particles-and-trails -a grok -ySenden Sie die kopierte Nachricht in einem Grok Bot-Chat. Der Bot ruft diese SKILL.md von GitHub ab und fügt sie den Skills hinzu, die alle Ihre Bots gemeinsam nutzen.
Install this skill: https://github.com/melonjs/melonJS/tree/HEAD/packages/melonjs/skills/melonjs-particles-and-trailsVom Herausgeber
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.
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:
z).Trail and Trail3d are separate renderables; see below.onComplete, autoDestroyOnComplete,
accurateBounds (deprecated since 20.2, and does nothing), and a
Container as referenceSpace (it offers
"local" and "world"). textureAdditive is left out: blendMode
replaces it.burstParticles() when something
happens, or assigning emitter.blendMode while particles are alive, is
game code. Its "moving emitter" option previews the common case: an
emitter attached to something that moves.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.
tintOverLifetintOverLife 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,
});
tint multiplies, so a coloured texture muddies
every step.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().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 constructor centres the area on the point it is given, so pass the centre of the source:
const area = radius * 2;
const emitter = new ParticleEmitter(x, y, { width: area, height: area });
After that, pos is the area's top-left corner, as on any renderable. To move
the emitter to a new source later, offset by half, or the burst sits down and
to the right of it:
emitter.pos.set(x - area / 2, y - area / 2); // re-aimed at (x, y)
emitter.burstParticles();
Under a Camera3d, depth (20.13) gives the area its third side: each
particle is born at a random depth within it, centered on the emitter's own
depth, unlike width and height. Without it every particle starts on one
plane facing the camera, so rain or dust seen from the side is a flat sheet. A
2D camera does not show depth, though with an order-dependent blend the
particles are still sorted by it. It is the spawn box's size, not the
emitter's depth property, which is where the emitter sits along Z.
new ParticleEmitter(x, y, { width: 600, height: 20, depth: 400 }); // a volume of rain
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).
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:
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.
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. A stream finishes only once it stops emitting: one left on the
default duration (Infinity) never completes until you call stopStream(),
so give a stream that should clean up after itself a duration.
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 inAdded 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.
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.
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.
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.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.melonjs-renderables — draw order and blend modesmelonjs-effects-and-shaders — blend mode cost on each backendUse 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 mo
---name: melonjs-particles-and-trailsdescription: Use this skill for particle effects and motion trails in melonJS — ParticleEmitter configuration, burst versus…---# packages/melonjs/skills/melonjs-particles-and-trails/SKILL.mdÜbersicht
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, stopStream, autoDestroyOnComplete, onComplete, sprite sheet particles, framewidth, randomFrame, cone, sphere, referenceSpace, ParticleEmitterSettings, elevation, minSpread, maxSpread, spawn area, Trail, explosion, smoke, sparks, debris, ring, exhaust, emitter, tintOverLife, colour over life, color over life, flame, fire.
FAQ
Laden Sie packages/melonjs/skills/melonjs-particles-and-trails/SKILL.md vom Herausgeber herunter oder kopieren Sie den Pfad und öffnen Sie das Repository. PlugMCP listet den Skill und hostet die Datei nicht.
Der Herausgeber pflegt es unter https://github.com/melonjs/melonJS.
Claude, Cursor, Codex und Grok Build können eine SKILL.md lesen, die Sie aus dem Repository des Herausgebers hinzufügen. Grok Bot installiert sie, wenn Sie den Link zum GitHub-Ordner des Skills in einem Chat senden.
tintOverLife| 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 emitter was moved by setting pos to the source: pos is the area's top-left corner, so offset by half (only the constructor centres it) |
| the burst sits up-left of its source | the constructor was given the top-left corner: it centres the area on (x, y), so pass the centre |
| 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 |