LittleJS 1.30.1

ParticleEffects

LittleJS Particle Effects Plugin

  • Ready made particle effects in one line, particleEffect('fire', pos), and particleEffect3D for 3D
  • Every built-in effect is tuned around a one unit emitter; options.scale grows it to fit, options.hue and options.saturation recolor it
  • Effects are plain data, {name, settings, behaviors}, the format the particle designer saves: load a library the designer saved with particleEffectsLoad and play its effects by name
  • The built-in effects draw with a sheet of shapes the plugin draws itself, so they need no image

Functions

Constants

Typedefs

Functions

particleEffect(nameOrEffect, pos, options) → ParticleEmitter|undefinedparticleEffects.js:645

Play an effect: a 2D emitter set to it, placed, scaled and recolored

  • A continuous effect (fire, a torch) goes until destroyed or given an emitTime, a one-shot ends itself
  • Any setting in the options replaces the effect's own for this play: {emitTime: .5} for a burst of a continuous effect, {emitTime: 0, emitRate: 30} to keep a one-shot going, or speed, particleTime and the rest
  • Attach it to an object with attach(emitter) to follow it, which keeps its angle, where addChild sets the angle
nameOrEffect string|ParticleEffect

A built-in or added effect's name, or an effect

pos Vector2 optional
options ParticleEffectOptions optional

What to change for this play, each left out when not wanted: scale grows the whole effect, the built-ins fit a one unit object at 1; hue turns its colors around the color wheel, 1 is all the way; saturation multiplies its saturation, 0 is gray; angle is its direction, 0 is up, the effect's own angle when not given; tileInfo, a TileInfo or a TextureInfo, is the game's own art to draw with in place of the effect's shape, tinted by its colors, a whole texture drawn as one tile; and any effect setting by its name, emitTime, emitRate, speed and the rest, replaces the effect's own

Returns
  • undefined when there is no such effect
particleEffect3D(nameOrEffect, pos3D, options) → ParticleEmitter3D|undefinedparticleEffects.js:764

Play an effect in 3D: a ParticleEmitter3D set to it, placed, scaled and recolored

  • The same effect data as particleEffect, so the look carries across: a circle spawn area becomes a sphere and a rectangle a box as deep as it is wide, both flat across the way it emits with options.flatten, a disc or a sheet; a trail becomes a streak of the same length, and the settings the 3D emitter lacks (particleConeAngle, randomColorLinear, velocityInheritance, localSpace) are left out; the stick behavior becomes the emitter's stick, its grip where a particle lands
nameOrEffect string|ParticleEffect

A built-in or added effect's name, or an effect

pos3D Vector3 optional
options ParticleEffectOptions optional

scale, hue, saturation, angle, tileInfo and any setting as particleEffect; angle turns it about z, so 0 is up; flatten makes the spawn area flat across the way it emits; roundLighting lights each particle as a ball, for smoke and clouds a light shines into

Returns
  • undefined when there is no such effect
particleEffectApply(emitter, effect)particleEffects.js:552

Set a 2D emitter to an effect, live, so a running one keeps its particles

emitter ParticleEmitter
effect ParticleEffect
particleEffectApply3D(emitter, effect)particleEffects.js:723

Set a 3D emitter to an effect, live, so a running one keeps its particles; its place, scale and flatten stay

emitter ParticleEmitter3D
effect ParticleEffect
particleEffectFromEmitter(emitter, name) → ParticleEffectparticleEffects.js:667

An effect with a 2D emitter's settings, to save, build again, or build in 3D with particleEffect3D; its tile is left out, since a hand made emitter's tile is its own texture and not one an effect can name, and so are its scale, which an effect does not keep: pass it again with options.scale, and its renderOrder, which an effect takes from additive; a finished emitter's emit time is the time it emitted for

emitter ParticleEmitter
name string optional, default Effect
particleEffectRecolor(effect, hue, saturation) → ParticleEffectparticleEffects.js:311

A copy of an effect with its four colors turned around the color wheel and their saturation scaled; lightness and alpha stay, and gray and white have no hue to turn

effect ParticleEffect
hue number optional, default 0

How far around the wheel, 1 is all the way

saturation number optional, default 1

Multiplies the saturation, 0 is gray, clamped to 1

particleEffectsAdd(effects)particleEffects.js:334

Add effects to play by name, sanitized; one with the name of an effect already there replaces it, and one with no settings takes every default

effects Array<ParticleEffectInput>|ParticleEffectInput
particleEffectsAddBehavior(name, update, update3D, min, max, value, description)particleEffects.js:514

Add a behavior effects can use by name, or replace one

name string
update function

Pushes a 2D particle, given the strength

update3D function optional

The same for a 3D particle, none does nothing in 3D; it replaces a behavior of the same name whole, its 3D push and range too

min number optional

Strength range the designer offers, and the range a strength is clamped to

max number optional, default 2
value number optional, default 1

Strength when first added

description string optional
particleEffectSanitize(raw) → ObjectparticleEffects.js:249

Any input into a whole effect: missing fields take their defaults, bad ones are dropped or clamped

raw Object optional

{name, settings, behaviors}, from a library file, the designer or code, checked as it may be anything

particleEffectsGet(name) → ParticleEffect|undefinedparticleEffects.js:347

The effect with a name, any case, undefined if there is none

name string
particleEffectShapeTile(name) → TileInfo|undefinedparticleEffects.js:391

The tile of a built-in shape, on a sheet the plugin draws once; undefined headless, without a canvas or without WebGL, where an effect draws untextured squares

name string

One of particleEffectShapes

particleEffectsLoad(url) → Promise<Array<ParticleEffect>>asyncparticleEffects.js:374

Load a library file the particle designer saved and add its effects

url string
Returns
  • The effects it had
particleEffectsParse(text) → Array<ParticleEffect>particleEffects.js:353

A library file, or one effect, into sanitized effects; throws on bad input

text string
particleEffectsText(effects) → stringparticleEffects.js:368

The text of a library file with these effects, what particleEffectsLoad and the designer read

effects Array<ParticleEffect>

Constants

particleEffectBehaviors : Array<{name:string, update: (function()|undefined), update3D: (function()|undefined), min:number, max:number, value:number, description:string}>particleEffects.js:205

The behaviors an effect can use, each a push applied to every particle every update, with a 2D and a 3D version

particleEffectGroups : Array<string>particleEffects.js:20

The groups the settings are in, in order

particleEffectsBuiltIn : Array<string>particleEffects.js:899

The names of the built-in effects, in the order a gallery shows them

particleEffectSettings : Array<{group:string, name:string, kind: ('number'|'checkbox'|'color'|'shape'), value: (number|boolean|string|Array<number>), min:number, max:number, step:number, description:string, hardMin:number, hardMax:number, extra:boolean}>particleEffects.js:29

Every setting an effect has: its name, kind (number, checkbox, color or shape), default, the range the designer's slider covers (min, max, step), the hard limits a typed value is clamped to, and whether it is set after the emitter is made rather than passed to its constructor (extra)

particleEffectShapes : Array<string>particleEffects.js:230

Names of the shapes the plugin draws, for an effect's shape setting

Typedefs

ParticleEffect : ObjectparticleEffects.js:31

An effect: what particleEffect plays, the designer edits and a library file holds; plain data, so it saves as JSON

name string optional

Its name, any case, 'Effect' when not given

settings ParticleEffectSettings

What it sets on an emitter, each one left out taking its default

behaviors Array<ParticleEffectBehavior> optional

Pushes on every particle every update

ParticleEffectBehavior : ObjectparticleEffects.js:42

A behavior an effect uses, by name, with how strong it is

name string

One of particleEffectBehaviors, or one added with particleEffectsAddBehavior

strength number optional

How strong, the behavior's own value when not given

ParticleEffectSettings : ObjectparticleEffects.js:48

The settings of an effect, each optional, the default when left out; colors are a Color or [r, g, b, a], and an effect that comes back sanitized has them as channels; a test checks this list against particleEffectSettings

emitRate number optional

Particles per second, 0 emits none

emitTime number optional

Seconds to emit for, 0 is forever

emitSize number optional

Diameter, or width when rectangular

emitRect boolean optional

Rectangle emitter, off is a circle

emitHeight number optional

Rectangle height

emitConeAngle number optional

Half angle particles move in, PI is all ways

angle number optional

Emitter angle, 0 points up

particleTime number optional

Seconds each particle lives

sizeStart number optional

Size at the start of life

sizeEnd number optional

Size at the end of life

fadeRate number optional

Share of life spent fading in and out

randomness number optional

How much each particle varies

particleConeAngle number optional

Half angle of start rotation, PI is any

trailScale number optional

Stretch along the motion, 0 is off

additive boolean optional

Glow with additive blending

colorStartA Color|Array<number> optional

Start color, each particle picks between A and B

colorStartB Color|Array<number> optional

Second start color

colorEndA Color|Array<number> optional

End color, each particle picks between A and B

colorEndB Color|Array<number> optional

Second end color

randomColorLinear boolean optional

Pick along A to B, off picks each channel

speed number optional

Start speed, world units per frame

angleSpeed number optional

Spin speed, radians per frame

damping number optional

Speed kept each frame, 1 keeps it all

angleDamping number optional

Spin kept each frame

gravityScale number optional

How much gravity pulls

gravity number optional

Its own fall each frame, the same in any game

velocityInheritance number optional

Share of emitter motion passed on

localSpace boolean optional

Particles move with the emitter

collideLevel boolean optional

Hit tiles

restitution number optional

Bounce when hitting tiles

friction number optional

Speed kept sliding along tiles

shape string optional

Built-in shape: dot, soft, glow, smoke, spark, square, triangle, ring, star or plus, '' uses the tile; any string, so a library read from JSON passes, a name it does not know drawing the default

tileIndex number optional

Tile in texture 0 when no shape, -1 is untextured

tileSize number optional

Tile size in texture pixels

tilePadding number optional

Pixels of padding around each tile

particleEffectSettingsMakeparticleEffects.js:103

What a play of an effect can change: any setting, replacing the effect's own for this play, and scale, which grows the whole effect, the built-ins fitting a one unit object at 1; hue, which turns its colors around the color wheel, 1 all the way; saturation, which multiplies it, 0 gray; angle, its direction, 0 up; tileInfo, the game's own art in place of the shape, tinted by its colors, a TextureInfo drawn whole; and in 3D flatten, a flat spawn area across the way it emits, and roundLighting, each particle lit as a ball, bright on the side toward each light; emitSize may be a vec2, a rectangle; shape is one of the built-in names, so a misspelled one is caught, where an effect's settings, read from JSON, take any string