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. AParticleEmitteron an entity plays it, orparticles.playplays 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);Effects
Section titled “Effects”On an entity
Section titled “On an entity”A ParticleEmitter plays an effect file where its entity is drawn, at its depth, and follows it as
it moves.
| Field | Default | What |
|---|---|---|
effect | The effect file’s url | |
playsOnStart | true | Plays as the game starts |
loop | 'effect' | 'effect' loops as the file says; 'once' or 'forever' overrides it |
scale | 1 | The effect’s distances, speeds and sizes times this |
playing | false | Whether 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; }); });Once, at a point
Section titled “Once, at a point”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.
What a file holds
Section titled “What a file holds”An effect has duration (ms), loop, prewarm (a loop starts full) and layers. Each layer has
its own start and duration, and these modules:
| Module | What |
|---|---|
emission | rate a second, bursts of { t, count }, max alive, perDistance as it moves |
shape | Point, circle, rectangle or line, from its area or edge; angle and spread in degrees |
particle | life, speed, rotation, spin, each a [least, most] range |
overLife | size, alpha, speed as [start, end, ease]; color, up to 4 stops |
forces | gravity as [x, y], drag, noise (strength, scale) |
look | picture, 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.
In the editor
Section titled “In the editor”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.
A burst
Section titled “A burst”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.
| Option | Default | What |
|---|---|---|
x, y | The point of the world it comes from | |
picture | The url of the picture, as Texture.source takes it | |
sheet | { columns, rows, frame }: one frame of a sheet, counted as SpriteSheet counts | |
count | 7 | How many particles |
size | its own | How wide each is drawn at full size, in pixels |
reach | 24 | How far they fly, in pixels |
duration | 450 | How long they fly, in milliseconds; they shrink away in 250 more |
ease | 'outCubic' | The flight’s easing: any of Easing |
tint | 0xffffff | A colour over the picture |
z | 1000 | What it is in front of, as position.z is |
It answers how many particles it started: fewer once MAX_PARTICLES (1000) are alive.
A number that rises
Section titled “A number that rises”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.
| Option | Default | What |
|---|---|---|
text | What it says | |
look | bold gold with a dark edge | Text’s fields: font, size, weight, fill, edge |
height | 30 | How far it rises, in pixels |
duration | 1300 | How long it lives, in milliseconds |
ease | 'outCubic' | The rise’s easing |
z | 1001 | What 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.
On the game’s clock
Section titled “On the game’s clock”- They move by the time tweens move by, so the editor’s Pause holds them and a game’s
timeScaleslows 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.aliveis{ particles, numbers, effects }: how many are alive now.
How they are drawn
Section titled “How they are drawn”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.