particle2dplugin
Effects the rules spawn in a flat world, on a ledger, drawn by each page.
Putting it in a scene
List it before render2d. The scene's sim lists the particle2d kind from #plugins/particle2d/particle2d.sim.ts, and the scene has one { "is": "particle2d" } actor, the ledger of running effects. Its prefab is exactly:
"plugins": ["loader", "scenemanager", "player", "particle2d", "render2d"],
"world": {
"loader": { "assets": { "fx": { "type": "json", "url": "/games/mygame/assets/fx.json", "preload": true } } },
"particle2d": { "effects": "fx", "hold": 0.5 }
},
"prefabs": {
"particle2d": { "next": 1, "live": [] }
}A rule spawns an effect with emit:
import { emit } from '#plugins/particle2d/particle2d.sim.ts'
emit(w, 'spark', [120, 80], { dir: [0, -1], scale: 1.5 })Properties
Read from world.particle2d.
.effects : string
The loader catalogue name of the effects file (see below).
.hold : number
Seconds an effect stays on the ledger at least, however short its life, so every page sees it. A page that gets two packets in one frame would otherwise miss an effect that lasted a single step.
The effects file
{
"cap": 2000,
"layer": "things",
"ppm": 1,
"effects": {
"spark": [
{ "n": [8, 12], "life": [0.3, 0.6], "speed": [60, 140], "spread": 0.8, "g": 200, "tint": 16764006, "tint1": 16729344, "a1": 0, "add": true }
],
"explosion": [{ "effect": "spark", "at": [0, -4] }, { "n": [1, 1], "life": [0.4, 0.4], "sheet": "boom", "clip": "burst", "play": true }]
}
}| Key | Meaning |
|---|---|
cap | The most particles a page draws at once. Past it, new ones are dropped. |
layer | The render2d layer particles are drawn on, unless a spawn names another. |
ppm | Pixels of a sheet per stage pixel, for particles drawn from sheets. |
effects | Each effect is a list of layers. { "effect": name } stands for every layer of that effect, and { "effect": name, "at": [x, y] } throws it from x, y pixels off the point. Any other layer is an emitter. |
Emitters
All lengths are stage pixels, as they look on screen: x grows right, y grows down, and the direction [0, -1] is straight up the screen. Times are seconds.
| Key | Meaning |
|---|---|
n | [min, max] particles in a burst. Default 1. A burst is thrown at the start of the effect. |
every, after | Another burst every every seconds while the effect lasts, and the seconds into the effect the first burst is thrown (default 0). |
life | [min, max] seconds a particle lives. Use lasts: true instead for a particle that lives as long as its effect, such as the body of a round in flight. A layer has one or the other. |
skip | A particle starts up to this many seconds into its life, so a burst's frames are not all in step. |
sheet, clip, play | Draw from a sprite sheet clip. Its frames play evenly over a particle's life, or with play at the sheet's own times. Without a sheet a particle is a one pixel square. |
size, grow | [min, max] size multiplier, default 1, and the factor the size is multiplied by from birth to death. |
dir, spread, speed | The direction thrown along, else the spawn's dir; the most radians off it either way, with none throwing in any direction; and [min, max] speed in pixels a second. |
jitter, box | jitter [x, y] is how far off the point a particle starts per axis. box [left, top, right, bottom] starts it at a random point inside that box. |
g, drag, pull | Gravity in pixels a second² down the stage (negative rises), the fraction of speed lost a second, and the pull in pixels a second² toward the point it was thrown from (negative pushes away). |
pace | [[seconds, k], …]: from that many seconds into its life, a particle moves k times as far each step. [[0.2, 0.5], [0.4, 0]] slows in steps and stops. |
follow | The particle keeps its place about the effect's point as the point moves. Without it a particle is left where it was thrown. |
flips | [[seconds, x, y], …]: from that time on, mirror across when x is 1 and upside down when y is 1. |
tint, tint1 | Colour at birth (else the spawn's, else white) and the colour it cools to at death. Numbers such as 0xRRGGBB. |
gain | Multiplies the colour's light, default 1. The stage draws nothing brighter than white, so a gain above 1 brightens each channel as far as white. |
a0, a1, fade | Opacity at birth and at death (default 1), and the seconds before death over which it changes. Left out, it changes over the whole life. |
spin | The most radians a second a particle turns, either way. Without it a particle stands upright. |
origin | [x, y] as fractions of the particle's width and height: the point of the particle that is on its place. [0.5, 1] stands it on its place. |
add, stretch, face | Draw adding light; turn along the way it is moving, head on its place; turn along the effect's dir. |
beam | Draw from the effect's point to its to, stretched and turned to span the gap. Spawn such an effect with a to. |
Spawns
What a rule's emit or a page's emit is handed after the effect's name and its point at, [x, y] or [x, y, h] as render2d reads one.
| Key | Meaning |
|---|---|
life | Seconds the effect keeps emitting. Default 0, a single burst. |
dir | The direction for any layer that gives none. |
to | A second point, where beams end and where the effect lands. |
tint | The colour for any layer that gives none. |
scale | The effect's size. It multiplies every length (particle size, speed, jitter, box, gravity and pull) but not times. |
floor | The height particles come to rest at. 0 is the ground itself. |
from | A row id. The effect goes on while the page holds that row, following its pos, and ends when the row does. Use it for a smoulder on a wreck or a glow on an item. |
fly | Carries the effect's point from at to to at this many world units a second. Its life is the time that takes. |
land | [{ effect, seed?, …spawn }]: effects thrown at to, or at its point, when its life ends. Use it for where a round lands. |
layer | The render2d layer for its particles, in place of the file's. |
Every page draws the same particles for an effect, because rolls come from a generator seeded by the effect's ledger id.
Methods
Rules
From #plugins/particle2d/particle2d.sim.ts.
emit( w, effect, at, spawn? ) : Entry
Spawns an effect and returns its ledger entry. Write the entry's at to move it and its life to stop it.
entry( w, id ) : Entry | undefined
Finds an entry again by its id, undefined once it has left the ledger.
On the page
Through plugins.particle2d, from an actor or another plugin.
emit( effect, at, spawn? )
Spawns an effect on this page only, and returns it. Writing its at, dir or to moves it and writing its life stops it. A spawn with a seed draws the same particles on every page that emits it. With none, rolls are random.