20.9. The ParticleEmitter Interface

Added SDK 0.28.0

An emitter is added to a particular synchronizer to emit particles when the synchronizer synchronizes a particle system.

Note

This is a low-level particle system API.

20.9.1. Methods

20.9.1.1. sync

Summary

Called by synchronizer to synchronize this particular emitter. This may be called multiple times by a synchronizer if it implements for example: fixed time steps.

Syntax

emitter.sync(synchronizer, system, timeStep);

synchronizer

The ParticleSynchronizer invoking this emitter.

system

The ParticleSystem being synchronized.

timeStep

The amount of time to synchronize emitter for.

20.9.1.2. reset

Summary

Reset this emitter, ready for re-use.

Syntax

emitter.reset();

20.9.1.3. enable

Summary

Enable this emitter.

Syntax

emitter.enable();

20.9.1.4. disable

Summary

Disable this emitter.

Syntax

emitter.disable();

20.9.1.5. burst

Summary

Enable emitter for a specific set of spawn events.

Syntax

emitter.burst(count);

count (Optional)

The number of spawn events to enable emitter for.

20.9.1.6. timeout

Summary

Enable emitter for a specific amount of time.

The emitter should behave so that after timeout seconds have passed, the last emitted particle has just finished its life time.

Syntax

emitter.timeout(timeout);

20.9.1.7. applyArchetype

Summary

Apply emitter specific archetype parameters to this emitter. This is used by the ParticleManager.

Syntax

emitter.applyArchetype(archetype, particleDefn, renderer, updater);

archetype

The emitter specific archetype parameters to be applied.

particle

The definition objects for the particles in an archetype. This is the dictionary returned by ParticleBuilder.compile.

renderer

The ParticleRenderer this emitter will be used with to be used to convert userData object property of archetype to its integer value.

updater

The ParticleUpdater this emitter will be used with to be used to convert userData object property of archetype to its integer value.

20.9.1.8. getMaxLifeTime

Summary

Get the maximum life time required to fully support the intended behavior of this emitter.

Syntax

var maxLifeTime = emitter.getMaxLifeTime();

20.9.1.9. getMaxParticles

Summary

Get the maximum amount of particles required to fully support the intended behavior of this emitter.

Syntax

var maxParticles = emitter.getMaxParticles();

20.9.1.10. getMaxSpeed

Summary

Get the maximum speed required for particles to fully support the intended behavior of this emitter.

Syntax

var maxSpeed = emitter.getMaxSpeed();

20.9.2. Properties

20.9.2.1. enabled

Whether this emitter is currently enabled.

Note

Read Only

20.9.3. The DefaultParticleEmitter Object

An emitter, compatible with the DefaultParticleSynchronizer and assuming usage of the DefaultParticleUpdater in the sense that the emitter assumes a standard euclidean simulation space with no specific userData set on the particles.

This emitter will emit continuous streams of particles with a set rate, with particles emitted in a specific direction in an optional combination of a flat angular spread, and a conical spread using either a uniform or normal distribution.

Particles will be emitted from within a random radius of a position in either a flat disc or spherical spread with some distribution, with randomized lifetimes and speeds.

Prediction

This emitter will make use of the system updater’s predict method so that particles can be emitted at exactly the rate specified, regardless of update time-steps. This also means that if the particle system was not updated for a period of time due to being outside the camera’s view frustum, when made visible again it will appear as though the particle system was always being updated with particles retrospectively created.

20.9.3.1. Methods

20.9.3.2. create

Summary

Create a new emitter.

Syntax

var emitter = DefaultParticleEmitter.create();

20.9.3.3. Properties

This list of properties is the same as the list of parameters supported by a ParticleArchetype using this synchronizer unless otherwise specified.

20.9.3.4. forceCreation

Value of forceCreation when creating particles. See ParticleSystem.createParticle.

Default value is false.

20.9.3.5. usePrediction

If true, then particles will have their position and velocity predicted using the system updater, this enables (at a small overhead) more accurate creation of particles whose creation time does not exactly overlap with system updates, and to improve behavior when looking back onto a previously invisible particle system.

Default value is true.

20.9.3.6. emittance

Parameters controlling the emittance of particles.

Fields

rate (Default 4)

How often particles are emitted, a rate of 3 specifies 3 emittance events every second.

delay (Default 0)

A delay in seconds from when the emitter is enabled, to when it first emits particles.

burstMin (Default 1)

The minimum amount of particles emitted at each emittance event.

burstMax (Default 1)

The maximum amount of particles emitted at each event. The actual amount emitted varies uniformly between the min and max values.

20.9.3.7. particle

Parameters about the particles appearances and life times. This object is vastly different for the ParticleArchetype and is described separately.

Object Fields

animationRange (Default [0, 1])

The range of the animation texture used by this particle, this should be accessed from the ParticleBuilder compilation result.

lifeTimeMin (Default 1)

The minimum life time of the emitted particles.

lifeTimeMax (Default 1)

The maximum life time of the emitted particles. The actual life time varies uniformly between the min and max values.

userData (Default 0)

The userData applied when creating particles from this emitter.

Note

This field should not contain randomized seed values, as these will be added automatically by the emitters.

Archetype Fields

name

not-optional. The name of the particle to be emitted, must exist in the ParticleArchetype.

useAnimationLifeTime (Default true)

If true, then the particle animation’s life time will be used as a basis of setting the lifeTimeMin and lifeTimeMax parameters of the emitter when using this emitter with the ParticleManager.

lifeTimeScaleMin (Default 1)

If useAnimationLifeTime is true, then this scale will be applied to the animations life time to compute the required value of lifeTimeMin.

lifeTimeScaleMax (Default 1)

If useAnimationLifeTime is true, then this scale will be applied to the animations life time to compute the required value of lifeTimeMax.

lifeTimeMin (Default 1)

The minimum life time of the emitted particles when useAnimationLifeTime is false.

lifeTimeMax (Default 1)

The maximum life time of the emitted particles when useAnimationLifeTime is false.

renderUserData (Default {})

An object with fields and values matching those expected by the ParticleRenderer createUserData method in use for the archetype.

updateUserData (Default {})

An object with fields and values matching those expected by the ParticleUpdater createUserData method in use for the archetype.

20.9.3.8. position

Parameters about the spawn positions of particles in this emitter.

Fields

position (Default [0, 0, 0])

The base position of particles emitted in the particle system.

spherical (Default false)

If true, then particle position will be selected from within a sphere.

If false, then particle positions will be selected from within a disc.

normal (Default [0, 1, 0])

The normal vector of the disc to select particle positions from when spherical is false.

radiusMin (Default 0)

The minimum radius at which to select particle positions from.

radiusMax (Default 0)

The maximum radius at which to select particle positions from.

radiusDistribution (Default “uniform”)

The distribution to use when selecting the radius to use when selecting particle positions.

• “uniform”

  A uniform distribution.

• “normal”

  A normal (Gaussian) distribution.

radiusSigma (Default 0.25)

The sigma parameter of the normal distribution.

20.9.3.9. velocity

Parameters about the spawn velocities of particles in this emitter.

Fields

theta (Default 0)

theta spherical coordinate for target particle directions in emitter. This is the spherical elevation, with 0 pointing along y-axis, and Math.PI pointing along the negative y-axis.

phi (Default 0)

phi spherical coordinate for target particle directions in emitter. This is the clockwise spherical azimuth, with 0 pointing along the x-axis.

speedMin (Default 1)

The minimum speed to emit particles with.

speedMax (Default 1)

The maximum speed to emit particles with. The actual speed will vary uniformly between the min and max values.

flatSpread (Default 0)

The flat spread angle about the target direction to emit particles in. Math.PI radians would specify the flat spread is a full circle.

flatSpreadAngle (Default 0)

The angle of the flat spread about the target direction, varying this parameter rotates the entire spread about the target direction (Example; if target direction is in direction of x-axis, then varying this parameter would allow selection of a horizontal or vertically orientated flat spread).

flatSpreadDistribution (Default “uniform”)

The distribution to use when selecting angles into the flat spread.

• “uniform”

  A uniform distribution.

• “normal”

  A normal (Gaussian) distribution.

flatSpreadSigma (Default 0.25)

The sigma parameter of the normal distribution.

conicalSpread (Default 0)

The conical spread angle about the target direction to emit particles in. Math.PI radians would specify the conical spread is a full sphere.

conicalSpreadDistribution (Default “uniform”)

The distribution to use when selecting angles into the conical spread.

• “uniform”

  A uniform distribution.

• “normal”

  A normal (Gaussian) distribution.

conicalSpreadSigma (Default 0.25)

The sigma parameter of the normal distribution.