LittleJS 1.30.1

Render3D

ParticleEmitter3D

ParticleEmitter3D - Spawns camera facing particles, the 3D twin of ParticleEmitter

  • Each particle is a flat square facing the camera, with a soft round dot when no tile is given
  • Set trailTime to draw each particle as a streak along where it has been, for sparks
  • Set angleSpeed to tumble them in the camera plane, which the 2D emitter takes as an argument
  • Particles shoot out along the emitter's own up axis, turned by rotation3D
  • emitConeAngle spreads them, PI sprays in every direction
  • Speeds are per frame and sizes are world units, the same as the 2D emitter
  • scale3D, its own or a parent's, grows the whole effect: the spawn area, the sizes, the speed and the fall
  • gravity here is its own number added to velocity y each frame, so an effect keeps its own fall wherever it is used, the same as the 2D emitter's gravity; gravityScale adds a share of render3D.gravity on top, as the 2D emitter's gravityScale adds the engine's gravity
  • An emitter with an emitTime destroys itself once its last particle is gone, like the 2D emitter
  • Callbacks as the 2D emitter's: particleCreateCallback, particleUpdateCallback, particleCollideCallback and particleDestroyCallback, each given a Particle3D, one object the emitter reuses for every particle and call
  • collideLevel, off by default, has particles hit the level, height maps, voxel maps and mesh colliders, bouncing by restitution and sliding by friction

Extends EngineObject3D

Constructor

new ParticleEmitter3D(pos3D, emitSize, emitTime, emitRate, emitConeAngle, tileInfo, colorStartA, colorStartB, colorEndA, colorEndB, particleTime, sizeStart, sizeEnd, speed, damping, gravity, fadeRate, randomness, additive)render3dExtras.js:1732

Create a particle emitter

pos3D Vector3 optional

World space position of the emitter

emitSize number|Vector3 optional, default 0

Spawn area, a number for a sphere diameter or a vec3 for a box

emitTime number optional, default 0

How long to keep emitting, 0 is forever

emitRate number optional, default 100

Particles per second, 0 does not emit

emitConeAngle number optional

Half angle around the emit direction, PI is every direction

tileInfo TileInfo|TextureInfo optional

Tile to render particles with, or a whole texture, undefined is untextured

colorStartA Color optional

Color at start of life, randomized between the start colors

colorStartB Color optional
colorEndA Color optional

Color at end of life, randomized between the end colors

colorEndB Color optional
particleTime number optional, default 0.5

How long particles live in seconds

sizeStart number optional, default 0.1

Particle size at start of life

sizeEnd number optional, default 1

Particle size at end of life

speed number optional, default 0.1

Spawn speed in world units per frame

damping number optional, default 1

Per frame velocity multiplier, 1 is none

gravity number optional, default 0

Per frame change to velocity y, negative pulls down; its own number, and gravityScale adds a share of render3D.gravity on top

fadeRate number optional, default 0.1

Fraction of life spent fading, half in and half out

randomness number optional, default 0.2

Extra randomness applied to speed, size and life

additive boolean optional, default false

Additive blending

// fire: a stream upward, yellow fading to transparent red, additive
new ParticleEmitter3D(vec3(), .5, 0, 100, .3, undefined, hsl(.12, 1, .6), hsl(.08, 1, .5), hsl(0, 1, .5, 0), hsl(0, 1, .25, 0), 1, .5, 1.5, .05, .95, 0, .3, .2, true);

Members

Methods

Inherited from EngineObject3D

Inherited from EngineObject

Members

additive : booleanrender3dExtras.js:1804

Additive blending

angleDamping : numberrender3dExtras.js:1811

Per frame multiplier on that spin, 1 keeps it

angleSpeed : numberrender3dExtras.js:1809

Radians per frame each particle turns in the camera plane, either way; 0 is no spin

collideLevel : booleanrender3dExtras.js:1824

Particles hit the level, height maps, voxel maps and mesh colliders, bouncing by restitution and sliding along by friction; off by default, it tests each particle's move against the level every frame

Color at end of life, randomized between the end colors

Color at end of life, randomized between the end colors

Color at start of life, randomized between the start colors

Color at start of life, randomized between the start colors

damping : numberrender3dExtras.js:1793

Per frame velocity multiplier

emitConeAngle : numberrender3dExtras.js:1775

Half angle around the emit direction, PI is every direction

emitFlat : booleanrender3dExtras.js:1768

Flatten the spawn area across the way it emits, its own up: a sphere becomes a disc and a box a flat rectangle, for rain from a sheet of sky or flames from a patch of ground

emitFrom : Vector3|undefinedrender3dExtras.js:1856
emitRate : numberrender3dExtras.js:1773

Particles per second, 0 does not emit

Spawn area, a number for a sphere diameter or a vec3 for a box

emitTime : numberrender3dExtras.js:1771

How long to keep emitting, 0 is forever; raised while its particles are still alive, it emits again for the added time

fadeRate : numberrender3dExtras.js:1800

Fraction of life spent fading, half in and half out

finishCallback : (function(ParticleEmitter3D): void)|undefinedrender3dExtras.js:1844
gravity : numberrender3dExtras.js:1795

Per frame change to velocity y, its own number and not render3D.gravity

gravityScale : numberrender3dExtras.js:1798

Share of render3D.gravity added each frame on top of its own gravity, 0 by default so an effect keeps its own fall wherever it is used; 1 falls with the world, like debris

particleCollideCallback : Particle3DCollideCallback|undefinedrender3dExtras.js:1837

Decides if a particle stops where it hits the level, with collideLevel on; a callback that returns nothing lets it through

particleCount : numberrender3dExtras.js:1816

How many particles are alive, the first that many of particleData

particleCreateCallback : Particle3DCallback|undefinedrender3dExtras.js:1830

Called with each particle as it is made

particleData : Float32Arrayrender3dExtras.js:1814

The live particles, 21 floats each: position, velocity, start and end color, start and end size, life, age, angle, spin, and trail point count; the emitter owns them, nothing else needs to

particleDestroyCallback : Particle3DCallback|undefinedrender3dExtras.js:1840

Called with each particle as it goes, its life over or destroyed

particleTime : numberrender3dExtras.js:1785

How long particles live in seconds

particleUpdateCallback : Particle3DCallback|undefinedrender3dExtras.js:1833

Called with each particle each update, after it moves

The particle the callbacks get, one object for every particle and call

randomness : numberrender3dExtras.js:1802

Extra randomness applied to speed, size and life

sizeEnd : numberrender3dExtras.js:1789

Particle size at end of life

sizeStart : numberrender3dExtras.js:1787

Particle size at start of life

Spawn speed in world units per frame

How much a particle grips where it lands, 0 to 1: its speed along the surface is cut by this much on each hit, on top of the friction, 1 stops it there

trailData : Float32Array|undefinedrender3dExtras.js:1819

The trail points of every particle, trailMax per particle oldest first, when trailTime is set

trailMax : numberrender3dExtras.js:1821

Trail points kept per particle, from trailTime

trailTime : numberrender3dExtras.js:1807

Seconds of each particle's path to draw as a ribbon behind it, 0 draws billboards; with engineVariableStep it keeps trailTime * frameRate updates of path

worldPos3D : Vector3|undefinedrender3dExtras.js:1850

Where the emitter was at its last update, for when its parent is destroyed

Methods

destroy(immediate)render3dExtras.js:1964

Stop emitting, and go away once the particles already out have finished like the 2D emitter's do

immediate boolean optional

Spawn one particle now

render3D() → voidrender3dExtras.js:2107

Draw the particles, as flat squares or as streaks when trailTime is set

  • The whole emitter sorts as one thing, its particles are not sorted against each other
  • With render3D.instancing on the squares go out as one instanced draw of render3D.billboardMesh

Spawn new particles, move the live ones, and go away when done