Packageorg.flintparticles.common.emitters
Classpublic class Emitter
InheritanceEmitter Inheritance flash.events.EventDispatcher
Subclasses Emitter2D

The Emitter class is the base class for the Emitter2D and Emitter3D classes. The emitter class contains the common behavioour used by these two concrete classes.

An Emitter manages the creation and ongoing state of particles. It uses a number of utility classes to customise its behaviour.

An emitter uses Initializers to customise the initial state of particles that it creates; their position, velocity, color etc. These are added to the emitter using the addInitializer method.

An emitter uses Actions to customise the behaviour of particles that it creates; to apply gravity, drag, fade etc. These are added to the emitter using the addAction method.

An emitter uses Activities to alter its own behaviour, to move it or rotate it for example.

An emitter uses a Counter to know when and how many particles to emit.

All timings in the emitter are based on actual time passed, independent of the frame rate of the flash movie.

Most functionality is best added to an emitter using Actions, Initializers, Activities and Counters. This offers greater flexibility to combine behaviours without needing to subclass the Emitter classes.



Public Properties
 PropertyDefined By
  actions : Vector.<Action>
The array of all actions being used by this emitter.
Emitter
  activities : Vector.<Activity>
The array of all actions being used by this emitter.
Emitter
  counter : Counter
The Counter for the Emitter.
Emitter
  fixedFrameTime : Number
Indicates a fixed time (in seconds) to use for every frame.
Emitter
  initializers : Vector.<Initializer>
The array of all initializers being used by this emitter.
Emitter
  maximumFrameTime : Number
The maximum duration for a single update frame, in seconds.
Emitter
  particleFactory : ParticleFactory
This is the particle factory used by the emitter to create and dispose of particles.
Emitter
  particles : Vector.<Particle>
The collection of all particles being managed by this emitter.
Emitter
  particlesArray : Array
[read-only] The actual array of particles used internally by this emitter.
Emitter
  running : Boolean
[read-only] Indicates if the emitter is currently running.
Emitter
  useInternalTick : Boolean
Indicates whether the emitter should manage its own internal update tick.
Emitter
Protected Properties
 PropertyDefined By
  _dispatchCounterComplete : Boolean = false
Indicates if the emitter should dispatch a counterComplete event at the end of the next update cycle.
Emitter
  _processLastFirst : Boolean = false
Used to alternate the direction in which the particles in the particles array are processed, to iron out errors from always processing them in the same order.
Emitter
Public Methods
 MethodDefined By
  
The constructor creates an emitter.
Emitter
  
addAction(action:Action):void
Adds an Action to the Emitter.
Emitter
  
addActivity(activity:Activity):void
Adds an Activity to the Emitter.
Emitter
  
addInitializer(initializer:Initializer):void
Adds an Initializer object to the Emitter.
Emitter
  
addParticle(particle:Particle, applyInitializers:Boolean = false):void
Add a particle to the emitter.
Emitter
  
addParticles(particles:Vector.<Particle>, applyInitializers:Boolean = false):void
Adds existing particles to the emitter.
Emitter
  
Used by counters to tell the emitter to dispatch a counter complete event.
Emitter
  
hasAction(action:Action):Boolean
Detects if the emitter is using a particular action or not.
Emitter
  
hasActionOfType(actionClass:Class):Boolean
Detects if the emitter is using an action of a particular class.
Emitter
  
hasActivity(activity:Activity):Boolean
Detects if the emitter is using a particular activity or not.
Emitter
  
hasActivityOfType(activityClass:Class):Boolean
Detects if the emitter is using an activity of a particular class.
Emitter
  
hasInitializer(initializer:Initializer):Boolean
Detects if the emitter is using a particular initializer or not.
Emitter
  
hasInitializerOfType(initializerClass:Class):Boolean
Detects if the emitter is using an initializer of a particular class.
Emitter
  
Kill all the particles on this emitter.
Emitter
  
pause():void
Pauses the emitter.
Emitter
  
removeAction(action:Action):void
Removes an Action from the Emitter.
Emitter
  
removeActivity(activity:Activity):void
Removes an Activity from the Emitter.
Emitter
  
removeInitializer(initializer:Initializer):void
Removes an Initializer from the Emitter.
Emitter
  
removeParticle(particle:Particle):Boolean
Remove a particle from this emitter.
Emitter
  
removeParticles(particles:Vector.<Particle>):void
Remove a collection of particles from this emitter.
Emitter
  
resume():void
Resumes the emitter after a pause.
Emitter
  
runAhead(time:Number, frameRate:Number = 10):void
Makes the emitter skip forwards a period of time with a single update.
Emitter
  
start():void
Starts the emitter.
Emitter
  
stop():void
Stops the emitter, killing all current particles and returning them to the particle factory for reuse.
Emitter
  
update(time:Number):void
Used to update the emitter.
Emitter
Protected Methods
 MethodDefined By
  
Emitter
  
initParticle(particle:Particle):void
Emitters do their own particle initialization here - usually involves positioning and rotating the particle to match the position and rotation of the emitter.
Emitter
  
Used to sort the particles as required.
Emitter
Events
 Event Summary Defined By
  Dispatched when the counter for the particle system has finished its cycle and so the system will not emit any more particles unless the counter is changed or restarted.Emitter
  Dispatched when an emitter attempts to update the particles' state but it contains no particles.Emitter
  Dispatched when the particle system has updated and the state of the particles has changed.Emitter
  Dispatched when a pre-existing particle is added to the emitter.Emitter
  Dispatched when a particle is created and has just been added to the emitter.Emitter
  Dispatched when a particle dies and is about to be removed from the system.Emitter
Property Detail
_dispatchCounterCompleteproperty
protected var _dispatchCounterComplete:Boolean = false

Indicates if the emitter should dispatch a counterComplete event at the end of the next update cycle.

_processLastFirstproperty 
protected var _processLastFirst:Boolean = false

Used to alternate the direction in which the particles in the particles array are processed, to iron out errors from always processing them in the same order.

actionsproperty 
actions:Vector.<Action>

The array of all actions being used by this emitter.


Implementation
    public function get actions():Vector.<Action>
    public function set actions(value:Vector.<Action>):void
activitiesproperty 
activities:Vector.<Activity>

The array of all actions being used by this emitter.


Implementation
    public function get activities():Vector.<Activity>
    public function set activities(value:Vector.<Activity>):void
counterproperty 
counter:Counter

The Counter for the Emitter. The counter defines when and with what frequency the emitter emits particles.


Implementation
    public function get counter():Counter
    public function set counter(value:Counter):void
fixedFrameTimeproperty 
fixedFrameTime:Number

Indicates a fixed time (in seconds) to use for every frame. Setting this property causes the emitter to bypass its frame timing functionality and use the given time for every frame. This enables the particle system to be frame based rather than time based.

To return to time based animation, set this value to zero (the default).

This feature only works if useInternalTick is true (the default).


Implementation
    public function get fixedFrameTime():Number
    public function set fixedFrameTime(value:Number):void

See also

initializersproperty 
initializers:Vector.<Initializer>

The array of all initializers being used by this emitter.


Implementation
    public function get initializers():Vector.<Initializer>
    public function set initializers(value:Vector.<Initializer>):void
maximumFrameTimeproperty 
maximumFrameTime:Number

The maximum duration for a single update frame, in seconds.

Under some circumstances related to the Flash player (e.g. on MacOSX, when the user right-clicks on the flash movie) the flash movie will freeze for a period. When the freeze ends, the current frame of the particle system will be calculated as the time since the previous frame, which encompases the duration of the freeze. This could cause the system to generate a single frame update that compensates for a long period of time and hence moves the particles an unexpected long distance in one go. The result is usually visually unacceptable and certainly unexpected.

This property sets a maximum duration for a frame such that any frames longer than this duration are ignored. The default value is 0.5 seconds. Developers don't usually need to change this from the default value.


Implementation
    public function get maximumFrameTime():Number
    public function set maximumFrameTime(value:Number):void
particleFactoryproperty 
particleFactory:ParticleFactory

This is the particle factory used by the emitter to create and dispose of particles. The 2D and 3D libraries each have a default particle factory that is used by the Emitter2D and Emitter3D classes. Any custom particle factory should implement the ParticleFactory interface.


Implementation
    public function get particleFactory():ParticleFactory
    public function set particleFactory(value:ParticleFactory):void

See also

particlesproperty 
particles:Vector.<Particle>

The collection of all particles being managed by this emitter.


Implementation
    public function get particles():Vector.<Particle>
    public function set particles(value:Vector.<Particle>):void
particlesArrayproperty 
particlesArray:Array  [read-only]

The actual array of particles used internally by this emitter. You may want to use this to manipulate the particles array directly or to provide optimized access to the array inside a custom behaviour. If you don't need the actual array, using the particles property is slightly safer.


Implementation
    public function get particlesArray():Array

See also

runningproperty 
running:Boolean  [read-only]

Indicates if the emitter is currently running.


Implementation
    public function get running():Boolean
useInternalTickproperty 
useInternalTick:Boolean

Indicates whether the emitter should manage its own internal update tick. The internal update tick is tied to the frame rate and updates the particle system every frame.

If users choose not to use the internal tick, they have to call the emitter's update method with the appropriate time parameter every time they want the emitter to update the particle system.


Implementation
    public function get useInternalTick():Boolean
    public function set useInternalTick(value:Boolean):void
Constructor Detail
Emitter()Constructor
public function Emitter()

The constructor creates an emitter.

Method Detail
addAction()method
public function addAction(action:Action):void

Adds an Action to the Emitter. Actions set the behaviour of particles created by the emitter.

Parameters

action:Action — The Action to add

See also

removeAction();
org.flintParticles.common.actions.Action.getDefaultPriority()
addActivity()method 
public function addActivity(activity:Activity):void

Adds an Activity to the Emitter. Activities set the behaviour of the Emitter.

Parameters

activity:Activity — The activity to add

See also

removeActivity()
org.flintParticles.common.activities.Activity.getDefaultPriority()
addInitializer()method 
public function addInitializer(initializer:Initializer):void

Adds an Initializer object to the Emitter. Initializers set the initial state of particles created by the emitter.

Parameters

initializer:Initializer — The Initializer to add

See also

removeInitializer()
org.flintParticles.common.initializers.Initializer.getDefaultPriority()
addParticle()method 
public function addParticle(particle:Particle, applyInitializers:Boolean = false):void

Add a particle to the emitter. This enables users to create a particle externally to the emitter and then pass the particle to this emitter for management. Or remove a particle from one emitter and add it to another.

Parameters

particle:Particle — The particle to add to this emitter
 
applyInitializers:Boolean (default = false) — Indicates whether to apply the emitter's initializer behaviours to the particle (true) or not (false).

See also

addParticles()method 
public function addParticles(particles:Vector.<Particle>, applyInitializers:Boolean = false):void

Adds existing particles to the emitter. This enables users to create particles externally to the emitter and then pass the particles to the emitter for management. Or remove particles from one emitter and add them to another.

Parameters

particles:Vector.<Particle> — The particles to add to this emitter
 
applyInitializers:Boolean (default = false) — Indicates whether to apply the emitter's initializer behaviours to the particle (true) or not (false).

See also

createParticle()method 
protected function createParticle():Particle

Returns
Particle
dispatchCounterComplete()method 
public function dispatchCounterComplete():void

Used by counters to tell the emitter to dispatch a counter complete event.

hasAction()method 
public function hasAction(action:Action):Boolean

Detects if the emitter is using a particular action or not.

Parameters

action:Action — The action to look for.

Returns
Boolean — true if the action is being used by the emitter, false otherwise.
hasActionOfType()method 
public function hasActionOfType(actionClass:Class):Boolean

Detects if the emitter is using an action of a particular class.

Parameters

actionClass:Class — The type of action to look for.

Returns
Boolean — true if the emitter is using an instance of the class as an action, false otherwise.
hasActivity()method 
public function hasActivity(activity:Activity):Boolean

Detects if the emitter is using a particular activity or not.

Parameters

activity:Activity — The activity to look for.

Returns
Boolean — true if the activity is being used by the emitter, false otherwise.
hasActivityOfType()method 
public function hasActivityOfType(activityClass:Class):Boolean

Detects if the emitter is using an activity of a particular class.

Parameters

activityClass:Class — The type of activity to look for.

Returns
Boolean — true if the emitter is using an instance of the class as an activity, false otherwise.
hasInitializer()method 
public function hasInitializer(initializer:Initializer):Boolean

Detects if the emitter is using a particular initializer or not.

Parameters

initializer:Initializer — The initializer to look for.

Returns
Boolean — true if the initializer is being used by the emitter, false otherwise.
hasInitializerOfType()method 
public function hasInitializerOfType(initializerClass:Class):Boolean

Detects if the emitter is using an initializer of a particular class.

Parameters

initializerClass:Class — The type of initializer to look for.

Returns
Boolean — true if the emitter is using an instance of the class as an initializer, false otherwise.
initParticle()method 
protected function initParticle(particle:Particle):void

Emitters do their own particle initialization here - usually involves positioning and rotating the particle to match the position and rotation of the emitter. This method is called before any initializers that are assigned to the emitter, so initializers can override any properties set here.

The implementation of this method in this base class does nothing.

Parameters

particle:Particle

killAllParticles()method 
public function killAllParticles():void

Kill all the particles on this emitter.

pause()method 
public function pause():void

Pauses the emitter.

removeAction()method 
public function removeAction(action:Action):void

Removes an Action from the Emitter.

Parameters

action:Action — The Action to remove

See also

addAction()
removeActivity()method 
public function removeActivity(activity:Activity):void

Removes an Activity from the Emitter.

Parameters

activity:Activity — The Activity to remove

See also

addActivity()
removeInitializer()method 
public function removeInitializer(initializer:Initializer):void

Removes an Initializer from the Emitter.

Parameters

initializer:Initializer — The Initializer to remove

See also

addInitializer()
removeParticle()method 
public function removeParticle(particle:Particle):Boolean

Remove a particle from this emitter.

Parameters

particle:Particle — The particle to remove.

Returns
Boolean — true if the particle was removed, false if it wasn't on this emitter in the first place.
removeParticles()method 
public function removeParticles(particles:Vector.<Particle>):void

Remove a collection of particles from this emitter.

Parameters

particles:Vector.<Particle> — The particles to remove.

resume()method 
public function resume():void

Resumes the emitter after a pause.

runAhead()method 
public function runAhead(time:Number, frameRate:Number = 10):void

Makes the emitter skip forwards a period of time with a single update. Used when you want the emitter to look like it's been running for a while.

Parameters

time:Number — The time, in seconds, to skip ahead.
 
frameRate:Number (default = 10) — The frame rate for calculating the new positions. The emitter will calculate each frame over the time period to get the new state for the emitter and its particles. A higher frameRate will be more accurate but will take longer to calculate.

sortParticles()method 
protected function sortParticles():void

Used to sort the particles as required. In this base class this method does nothing.

start()method 
public function start():void

Starts the emitter. Until start is called, the emitter will not emit or update any particles.

stop()method 
public function stop():void

Stops the emitter, killing all current particles and returning them to the particle factory for reuse.

update()method 
public function update(time:Number):void

Used to update the emitter. If using the internal tick, this method will be called every frame without any action by the user. If not using the internal tick, the user should call this method on a regular basis to update the particle system.

The method asks the counter how many particles to create then creates those particles. Then it calls sortParticles, applies the activities to the emitter, applies the Actions to all the particles, removes all dead particles, and finally dispatches an emitterUpdated event which tells any renderers to redraw the particles.

Parameters

time:Number — The duration, in seconds, to be applied in the update step.

See also

sortParticles();
Event Detail
counterComplete Event
Event Object Type: org.flintparticles.common.events.EmitterEvent
EmitterEvent.type property = org.flintparticles.common.events.EmitterEvent.COUNTER_COMPLETE

Dispatched when the counter for the particle system has finished its cycle and so the system will not emit any more particles unless the counter is changed or restarted.

emitterEmpty Event  
Event Object Type: org.flintparticles.common.events.EmitterEvent
EmitterEvent.type property = org.flintparticles.common.events.EmitterEvent.EMITTER_EMPTY

Dispatched when an emitter attempts to update the particles' state but it contains no particles. This event will be dispatched every time the update occurs and there are no particles in the emitter. The update does not occur when the emitter has not yet been started, when the emitter is paused, and after the emitter has been stopped, so the event will not be dispatched at these times.

See the firework example for an example that uses this event.

See also

start();
pause();
stop();
emitterUpdated Event  
Event Object Type: org.flintparticles.common.events.EmitterEvent
EmitterEvent.type property = org.flintparticles.common.events.EmitterEvent.EMITTER_UPDATED

Dispatched when the particle system has updated and the state of the particles has changed.

particleAdded Event  
Event Object Type: org.flintparticles.common.events.ParticleEvent
ParticleEvent.type property = org.flintparticles.common.events.ParticleEvent.PARTICLE_ADDED

Dispatched when a pre-existing particle is added to the emitter.

particleCreated Event  
Event Object Type: org.flintparticles.common.events.ParticleEvent
ParticleEvent.type property = org.flintparticles.common.events.ParticleEvent.PARTICLE_CREATED

Dispatched when a particle is created and has just been added to the emitter.

particleDead Event  
Event Object Type: org.flintparticles.common.events.ParticleEvent
ParticleEvent.type property = org.flintparticles.common.events.ParticleEvent.PARTICLE_DEAD

Dispatched when a particle dies and is about to be removed from the system. As soon as the event has been handled the particle will be removed but at the time of the event it still exists so its properties (e.g. its location) can be read from it.