particle3dplugin
Effects the rules spawn in a 3D world, on a ledger, drawn by each page.
Putting it in a scene
List it before render3d. The scene's sim lists the particle3d kind from #plugins/particle3d/particle3d.sim.ts, and the scene has one { "is": "particle3d" } actor, the ledger of running effects.
"plugins": ["loader", "scenemanager", "player", "particle3d", "render3d"],
"world": {
"loader": { "assets": { "fx": { "type": "json", "url": "/games/mygame/assets/fx.json", "preload": true } } },
"particle3d": { "effects": "fx", "hold": 0.5 }
},
"prefabs": {
"particle3d": { "next": 1, "live": [] }
}A rule spawns an effect with emit:
import { emit } from '#plugins/particle3d/particle3d.sim.ts'
emit(w, 'spark', [4, 1, -2], { dir: [0, 1, 0], scale: 1.5 })Properties
Read from world.particle3d.
.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.
The effects file
{
"cap": 4000,
"alphaTest": 0.1,
"ppm": 64,
"effects": {
"spark": [
{ "n": [8, 12], "life": [0.3, 0.6], "speed": [3, 7], "spread": 0.8, "g": 9, "tint": 16764006, "tint1": 16729344, "gain": 3, "a1": 0, "add": true }
],
"flash": [
{ "n": [1, 1], "life": [0.15, 0.15], "size": [2, 2], "tint": 16777215, "add": true, "light": { "intensity": 20, "distance": 8, "decay": 2 } }
]
}
}| Key | Meaning |
|---|---|
cap | The most particles a page draws at once. Past it, new ones are dropped. |
alphaTest | Pixels with less opacity than this are not drawn. Default 0. |
ppm | Pixels of a sheet per metre, 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, z] } throws it from that many metres off the point. Any other layer is an emitter. |
Emitters
All lengths are metres, y is up, and a direction is a vector [x, y, z], so [0, 1, 0] is straight up. Times are seconds. Every particle is a flat picture that always faces the camera.
| 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. 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 flat square one metre across. |
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, with none throwing in any direction; and [min, max] speed in metres a second. |
jitter, box | jitter [x, y, z] is how far off the point a particle starts per axis. box [x0, y0, z0, x1, y1, z1] starts it at a random point inside that box. |
g, drag, pull | Gravity in metres a second² down (negative rises), the fraction of speed lost a second, and the pull in metres 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. |
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. Above 1 a particle is brighter than white and, with render3d's bloom on, spills light round it. |
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. |
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 to span the gap and turned about its length to face the camera. Spawn such an effect with a to. |
light | { intensity, distance, decay }: each particle carries a point light of its colour, intensity times its opacity, reaching distance metres times the effect's scale. The scene must list lights3d. |
Spawns
What a rule's emit or a page's emit is handed after the effect's name and its point at, [x, y, z] in metres.
| 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. |
from | A row id. The effect goes on while the page holds that row, following its pos, and ends when the row does. |
fly | Carries the effect's point from at to to at this many metres 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. |
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/particle3d/particle3d.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.particle3d, 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.