Foundation.ParticleEmitter

ParticleEmitters are responsible for creating and controlling the life cycle of NonReactiveParticles. Emitters are single point drawable objects. An emitter itself is not drawn. Instead, renderers will draw the active (alive) particles owned by an emitter.

There are a large number of configuration values to control how particles are emitted. While these might be confusing and overwhelming at first glance, simply playing with the values will quickly show you how the emitter system works.

To simplify the process for creating particle systems, a GUI tool will be added to the tool chain in the near future. Check back soon!


Example

Assumes a default game prefab stored as game:

// Create a new emitter
var part = new Foundation.ParticleEmitter(new Foundation.Rectangle(100, 100, 50, 50), someTexture.getRegion('all'), game['time']);

// Add emitter to a layer
game['layers']['default'].pushBack(part);

// Set some emission values 
part.alphaDTChange    = -0.33; // Alpha decays at 0.33 units per second
part.lifeSeconds      = 3;     // Particle will live for 3 seconds
part.minDirectionX    = -0.5;  // X component of direction vector will be between -0.5...
part.maxDirectionX    =  0.5;  // ... and 0.5
part.directionY       =  1;    // Y component of direction vector will be 1 (fixed)

// Set the emitter to auto emit every 2 milliseconds
part.autoEmitDT = 0.002;


Implementation Details

Reference paths

  • '/foundation/_digest.ts'
  • '/foundation/core/actors/_digest.ts'
  • '/foundation/core/actors/ParticleEmitter.ts'

Extends

This type does not extend a base.

Implements

This type implements the following interfaces:


Public Properties (General)

timer: GameTimeTracker

  • Get or set a timer reference (ideally the game time) to control particle lifetimes.

defaultEmitCount: number

  • The number of particles emitted with each emit call, if not specified at call time.

compositeOperation: string

particleCount: number

  • Get the number of active / alive particles in the system.

getParticle(n: number): NonReactiveParticle

  • Get a reference to the nth particle in the system.

autoEmitDT: number

  • If > 0, particles will auto emit every autoEmitDT seconds. E.g. 0.25 will auto emit every 250 milliseconds.
  • Defaults to 0.

active: boolean

  • Whether or not the emitter is active. If the emitter is inactive, it will not emit, particles will not be updated, and will not be drawn.

bounds: Rectangle

  • The emitter's bounding rectangle. The rectangle does not bind individual particles, but determines whether or not the full system should be drawn. The system will only be drawn when the emitter's bounding rectangle intersects the game camera.

layer: Layer

  • Back reference to the layer the emitter lives on.

image: TextureRegion

  • The texture region used for each particle in the system (the emitter itself is not drawn).

Public Properties (Particle Controls)

minDirectionX: number

  • When emitting, the x direction will be randomized between minDirectionX and maxDirectionX.
  • x and y together form a direction vector for the particle.
  • To fix the x direction for particles, set minDirectionX and maxDirectionX to the same value.

maxDirectionX: number

  • When emitting, the x direction will be randomized between minDirectionX and maxDirectionX.
  • x and y together form a direction vector for the particle.
  • To fix the x direction for particles, set minDirectionX and maxDirectionX to the same value.

minDirectionY: number

  • When emitting, the y direction will be randomized between minDirectionY and maxDirectionY.
  • x and y together form a direction vector for the particle.
  • To fix the y direction for particles, set minDirectionY and maxDirectionY to the same value.

maxDirectionY: number

  • When emitting, the y direction will be randomized between minDirectionY and maxDirectionY.
  • x and y together form a direction vector for the particle.
  • To fix the y direction for particles, set minDirectionY and maxDirectionY to the same value.

alpha: number

  • The initial alpha value for a newly emitted particle.
  • Clamped to [0,1]

minAlphaDTChange

  • When emitting, the rate of alpha change per second will be randomized between minAlphaDTChange and maxAlphaDTChange.
  • To fix rate of alpha change for particles, set minAlphaDTChange and maxAlphaDTChange to the same value.

minVelocityDT

  • When emitting, the velocity (number of world units per second) will be randomized between minVelocityDT and maxVelocityDT.
  • To fix velocity for particles, set minVelocityDT and maxVelocityDT to the same value.

maxVelocityDT

  • When emitting, the velocity (number of world units per second) will be randomized between minVelocityDT and maxVelocityDT.
  • To fix velocity for particles, set minVelocityDT and maxVelocityDT to the same value.

minLifeSeconds

  • When emitting, the lifetime will be randomized between minLifeSeconds and maxLifeSeconds.
  • To fix lifetime for particles, set minLifeSeconds and maxLifeSeconds to the same value.

minOffsetX

  • When emitting, the starting position will be offset from the emitter point on x by a random value between minOffsetX and maxOffsetX.
  • To fix x offset for particles, set minOffsetX and maxOffsetX to the same value.

minOffsetY

  • When emitting, the starting position will be offset from the emitter point on y by a random value between minOffsetY and maxOffsetY.
  • To fix y offset for particles, set minOffsetY and maxOffsetY to the same value.

Public Properties (Simplified Particle Controls)

alphaDTChange

  • Set min and max values at once.

directionX

  • Set min and max values at once.

directionY

  • Set min and max values at once.

velocityDT

  • Set min and max values at once.

lifeSeconds

  • Set min and max values at once.

offsetX

  • Set min and max values at once.

offsetY

  • Set min and max values at once.

Constructors

(bounds: Rectangle, image: TextureRegion, timer: GameTimeTracker, particleWidth: number = 10, particleHeight: number = 10, particleCount: number = 100)

  • bounds: See bounds property description.
  • particleTextre: See image property description.
  • timer: See timer property description.
  • particleWidth: The width of an individual particle.
  • particleHeight: The height of an individual particle.
  • particleCount: The number of particles in the system / available for emission.

Instance Methods

emit(n?: number): void

  • Emit n particles, or as many particles as are available up to n.
  • If n is not passed, defaultEmitCount will be used.

moveToPoint(x: number, y: number): void

  • Move the emitter to the specified x and y point.

rotateDirection(rads: number): void

  • Rotate the current direction ranges (min, max) by the specified radian value.

setDirectionByRotation(min: number, max: number): void

  • Set the direction ranges (min, max) by rotation from radian values