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: it is neither the engine's 2D gravity nor render3D.gravity, so an effect keeps its own fall wherever it is used
  • 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 height maps and voxel maps, bouncing by restitution and sliding by friction

Constructor

new ParticleEmitter3D(pos3Dopt, emitSizeopt, emitTimeopt, emitRateopt, emitConeAngleopt, tileInfoopt, colorStartAopt, colorStartBopt, colorEndAopt, colorEndBopt, particleTimeopt, sizeStartopt, sizeEndopt, speedopt, dampingopt, gravityopt, fadeRateopt, randomnessopt, additiveopt)

Create a particle emitter

Parameters:
NameTypeAttributesDefaultDescription
pos3DVector3<optional>

World space position of the emitter

emitSizenumber | Vector3<optional>
0

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

emitTimenumber<optional>
0

How long to keep emitting, 0 is forever

emitRatenumber<optional>
100

Particles per second, 0 does not emit

emitConeAnglenumber<optional>

Half angle around the emit direction, PI is every direction

tileInfoTileInfo | TextureInfo<optional>

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

colorStartAColor<optional>

Color at start of life, randomized between the start colors

colorStartBColor<optional>
colorEndAColor<optional>

Color at end of life, randomized between the end colors

colorEndBColor<optional>
particleTimenumber<optional>
0.5

How long particles live in seconds

sizeStartnumber<optional>
0.1

Particle size at start of life

sizeEndnumber<optional>
1

Particle size at end of life

speednumber<optional>
0.1

Spawn speed in world units per frame

dampingnumber<optional>
1

Per frame velocity multiplier, 1 is none

gravitynumber<optional>
0

Per frame change to velocity y, negative pulls down; its own number, not render3D.gravity, so the 2D emitter's gravityScale has no equivalent here

fadeRatenumber<optional>
0.1

Fraction of life spent fading, half in and half out

randomnessnumber<optional>
0.2

Extra randomness applied to speed, size and life

additiveboolean<optional>
false

Additive blending

Source
Example
// 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);

Extends

  • EngineObject3D

Members

additive

Properties
TypeDescription
boolean

Additive blending

Source

angleDamping

Properties
TypeDescription
number

Per frame multiplier on that spin, 1 keeps it

Source

angleSpeed

Properties
TypeDescription
number

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

Source

collideLevel

Properties
TypeDescription
boolean

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

Source

colorEndA

Properties
TypeDescription
Color

Color at end of life, randomized between the end colors

Source

colorEndB

Properties
TypeDescription
Color

Color at end of life, randomized between the end colors

Source

colorStartA

Properties
TypeDescription
Color

Color at start of life, randomized between the start colors

Source

colorStartB

Properties
TypeDescription
Color

Color at start of life, randomized between the start colors

Source

damping

Properties
TypeDescription
number

Per frame velocity multiplier

Source

emitConeAngle

Properties
TypeDescription
number

Half angle around the emit direction, PI is every direction

Source

emitRate

Properties
TypeDescription
number

Particles per second, 0 does not emit

Source

emitSize

Properties
TypeDescription
number | Vector3

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

Source

emitTime

Properties
TypeDescription
number

How long to keep emitting, 0 is forever

Source

fadeRate

Properties
TypeDescription
number

Fraction of life spent fading, half in and half out

Source

gravity

Properties
TypeDescription
number

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

Source

particleCollideCallback :Particle3DCollideCallback|undefined

Type:
  • Particle3DCollideCallback | undefined
Properties
TypeDescription
Particle3DCollideCallback | undefined

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

Source

particleCount

Properties
TypeDescription
number

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

Source

particleCreateCallback :Particle3DCallback|undefined

Type:
  • Particle3DCallback | undefined
Properties
TypeDescription
Particle3DCallback | undefined

Called with each particle as it is made

Source

particleData

Properties
TypeDescription
Float32Array

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

Source

particleDestroyCallback :Particle3DCallback|undefined

Type:
  • Particle3DCallback | undefined
Properties
TypeDescription
Particle3DCallback | undefined

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

Source

particleTime

Properties
TypeDescription
number

How long particles live in seconds

Source

particleUpdateCallback :Particle3DCallback|undefined

Type:
  • Particle3DCallback | undefined
Properties
TypeDescription
Particle3DCallback | undefined

Called with each particle each update, after it moves

Source

particleView :Particle3D

Type:
  • Particle3D
Properties
TypeDescription
Particle3D

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

Source

randomness

Properties
TypeDescription
number

Extra randomness applied to speed, size and life

Source

sizeEnd

Properties
TypeDescription
number

Particle size at end of life

Source

sizeStart

Properties
TypeDescription
number

Particle size at start of life

Source

speed

Properties
TypeDescription
number

Spawn speed in world units per frame

Source

trailData :Float32Array|undefined

Type:
  • Float32Array | undefined
Properties
TypeDescription
Float32Array | undefined

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

Source

trailMax

Properties
TypeDescription
number

Trail points kept per particle, from trailTime

Source

trailTime

Properties
TypeDescription
number

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

Source

worldPos3D :Vector3|undefined

Type:
  • Vector3 | undefined
Properties
TypeDescription
Vector3 | undefined

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

Source

Methods

destroy(immediateopt)

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

Parameters:
NameTypeAttributesDescription
immediateboolean<optional>
Source

emitParticle()

Spawn one particle now

Source

render3D() → {void}

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
Source
Returns:
Type: 
void

update()

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

Source