Skip to content

Particles

@shell/particles plays particle effects (fire, smoke, sparks, rain, snow) and makes things pop: coins or sparks that burst off a point, and a number that rises and fades.

  • An effect is a file of layers, effects/<name>.particles.json, made and tuned in the editor’s Particle Editor. A ParticleEmitter on an entity plays it, or particles.play plays it once at a point.
  • A burst or a number is no entity. One call makes it, it moves on the game’s clock with @shell/animate’s easings, and it ends by itself.

Engine2D already installs ParticlesPlugin, after PixiPlugin, and @shell/engine-2d re-exports the package. A world built of its own plugins adds it after PixiPlugin and AnimatePlugin:

import { ParticlesPlugin } from '@shell/particles';
world.addPlugin(ParticlesPlugin);

A ParticleEmitter plays an effect file where its entity is drawn, at its depth, and follows it as it moves.

FieldDefaultWhat
effectThe effect file’s url
playsOnStarttruePlays as the game starts
loop'effect''effect' loops as the file says; 'once' or 'forever' overrides it
scale1The effect’s distances, speeds and sizes times this
playingfalseWhether it plays now; one that does not loop sets it back once it is over

A system plays one that does not play on start, or plays one that runs once again, by setting playing:

import { Define, Mut, ParticleEmitter } from '@shell/engine-2d';
export const LightCampfires = Define.system()
.scene('level')
.queries({ fires: { data: [Campfire, Mut(ParticleEmitter)] } })
.update(({ queries }) => {
queries.fires.forEach((fire) => {
if (fire.$campfire.lit && !fire.$particleEmitter.playing)
fire.$particleEmitter.playing = true;
});
});
const run = resources.get('particles').play('/assets/effects/coins.particles.json', { x, y });

It plays with no entity, and is taken away when it is over; a loop plays one run of it. It answers { done, stop() }. z, rotation and scale are options too.

An effect has duration (ms), loop, prewarm (a loop starts full) and layers. Each layer has its own start and duration, and these modules:

ModuleWhat
emissionrate a second, bursts of { t, count }, max alive, perDistance as it moves
shapePoint, circle, rectangle or line, from its area or edge; angle and spread in degrees
particlelife, speed, rotation, spin, each a [least, most] range
overLifesize, alpha, speed as [start, end, ease]; color, up to 4 stops
forcesgravity as [x, y], drag, noise (strength, scale)
lookpicture, a sheet and its flipbook, blend normal or add, space world or local

A layer’s off lists modules switched off: their settings stay in the file, and the layer plays as if they were not there. The editor and the Agent’s tools write the files; validateEffect says what of one is wrong, and a file that is wrong plays nothing and is told once.

Assets → New Particle Effect… makes one from a preset: Fire, Smoke, Sparks, Coin burst, Dust puff, Rain, Snow, Confetti, or Empty. Opened, it is a tab of the Particle Editor: its layers, a preview, and the selected layer’s modules in the Inspector, each change an undo step. A change reaches every emitter of the effect at once, in a game that is playing too. In the scene view an effect plays only while its entity is selected; Play and the game always play it. The Agent has create_particles, get_particles, set_particles and edit_particles.

const particles = resources.get('particles');
particles.burst({
x,
y,
picture: '/assets/textures/coin.svg',
count: 8,
size: 12,
reach: 30,
});

The particles fly off the point in a ring, popping in as they go, and then shrink away. Give size, the width the thing has in the game: without it each is drawn as wide as the picture’s file.

OptionDefaultWhat
x, yThe point of the world it comes from
pictureThe url of the picture, as Texture.source takes it
sheet{ columns, rows, frame }: one frame of a sheet, counted as SpriteSheet counts
count7How many particles
sizeits ownHow wide each is drawn at full size, in pixels
reach24How far they fly, in pixels
duration450How long they fly, in milliseconds; they shrink away in 250 more
ease'outCubic'The flight’s easing: any of Easing
tint0xffffffA colour over the picture
z1000What it is in front of, as position.z is

It answers how many particles it started: fewer once MAX_PARTICLES (1000) are alive.

particles.rise({
x,
y: y - 10,
text: '+10',
look: { fill: 0xffcc00, stroke: 0x1a1a2e, strokeWidth: 4, fontSize: 24, fontWeight: 'bold' },
});

It pops in, rises, and fades in its last 200 milliseconds. x and y are its middle, at the bottom of its letters.

OptionDefaultWhat
textWhat it says
lookbold gold with a dark edgeText’s fields: font, size, weight, fill, edge
height30How far it rises, in pixels
duration1300How long it lives, in milliseconds
ease'outCubic'The rise’s easing
z1001What it is in front of

It answers whether it was shown: not once MAX_NUMBERS (100) are alive.

Give numbers a few looks, not a colour each. PixiJS draws a number with a bitmap font. With no edge every colour shares one font. With an edge, each look is a font of its own with its fill drawn in, and PixiJS warns past 50 of them.

  • They move by the time tweens move by, so the editor’s Pause holds them and a game’s timeScale slows them.
  • Stop in the editor takes them away with the play world, and a world that unmounts takes them all away.
  • An emitter goes with its entity: while the entity’s Scene is paused, it holds where it is, and it goes when that Scene is unloaded.
  • A burst, a number or an effect played once belongs to the Scene that was active when it started, as a spawn would: while that Scene is paused (scenes.pause(level)), it holds where it is. An unloaded Scene does not take it along: each ends within its time (a burst 700 ms, a number 1300 ms), into the next level if a switch came first. particles.clear() ends all of them at once.
  • particles.alive is { particles, numbers, effects }: how many are alive now.

Effects draw with PixiJS’s ParticleContainer on WebGL and WebGPU, one a layer, and with a Sprite a particle on Canvas2D. Every effect’s particles together are capped at 20,000 (MAX_EFFECT_PARTICLES), and a layer’s max is at most 5000. Large see-through particles, smoke most, cost more than their count, on phones above all: keep them few.

Bursts: each picture at each depth is one PixiJS container in the world, and a particle is a Sprite in it: batched with the others on WebGL, one drawImage on Canvas2D, with a tint made once for each colour. No entity, no component and no tween is made for one. A picture that is not loaded yet is loaded as a Texture’s is. The burst’s time runs from the call, and it shows once the picture is there.