| Package | org.flintparticles.common.emitters |
| Class | public class Emitter |
| Inheritance | Emitter flash.events.EventDispatcher |
| Subclasses | Emitter3D |
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.
| Property | Defined 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 | ||
| Property | Defined 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 | ||
| Method | Defined By | ||
|---|---|---|---|
Emitter()
The constructor creates an emitter. | Emitter | ||
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 | ||
dispatchCounterComplete():void
Used by counters to tell the emitter to dispatch a counter complete event. | Emitter | ||
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 | ||
killAllParticles():void
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 | ||
| Method | Defined 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 | ||
sortParticles():void
Used to sort the particles as required. | Emitter | ||
| 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 | |||
| _dispatchCounterComplete | property |
protected var _dispatchCounterComplete:Boolean = falseIndicates if the emitter should dispatch a counterComplete event at the end of the next update cycle.
| _processLastFirst | property |
protected var _processLastFirst:Boolean = falseUsed 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.
| actions | property |
actions:Vector.<Action>The array of all actions being used by this emitter.
public function get actions():Vector.<Action> public function set actions(value:Vector.<Action>):void| activities | property |
activities:Vector.<Activity>The array of all actions being used by this emitter.
public function get activities():Vector.<Activity> public function set activities(value:Vector.<Activity>):void| counter | property |
counter:CounterThe Counter for the Emitter. The counter defines when and with what frequency the emitter emits particles.
public function get counter():Counter public function set counter(value:Counter):void| fixedFrameTime | property |
fixedFrameTime:NumberIndicates 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).
public function get fixedFrameTime():Number public function set fixedFrameTime(value:Number):voidSee also
| initializers | property |
initializers:Vector.<Initializer>The array of all initializers being used by this emitter.
public function get initializers():Vector.<Initializer> public function set initializers(value:Vector.<Initializer>):void| maximumFrameTime | property |
maximumFrameTime:NumberThe 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.
public function get maximumFrameTime():Number public function set maximumFrameTime(value:Number):void| particleFactory | property |
particleFactory:ParticleFactoryThis 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.
public function get particleFactory():ParticleFactory public function set particleFactory(value:ParticleFactory):voidSee also
| particles | property |
particles:Vector.<Particle>The collection of all particles being managed by this emitter.
public function get particles():Vector.<Particle> public function set particles(value:Vector.<Particle>):void| particlesArray | property |
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.
public function get particlesArray():ArraySee also
| running | property |
running:Boolean [read-only] Indicates if the emitter is currently running.
public function get running():Boolean| useInternalTick | property |
useInternalTick:BooleanIndicates 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.
public function get useInternalTick():Boolean public function set useInternalTick(value:Boolean):void| Emitter | () | Constructor |
public function Emitter()The constructor creates an emitter.
| addAction | () | method |
public function addAction(action:Action):voidAdds an Action to the Emitter. Actions set the behaviour of particles created by the emitter.
Parameters
action:Action — The Action to add
|
See also
| addActivity | () | method |
public function addActivity(activity:Activity):voidAdds an Activity to the Emitter. Activities set the behaviour of the Emitter.
Parameters
activity:Activity — The activity to add
|
See also
| addInitializer | () | method |
public function addInitializer(initializer:Initializer):voidAdds 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
| addParticle | () | method |
public function addParticle(particle:Particle, applyInitializers:Boolean = false):voidAdd 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) |
See also
| addParticles | () | method |
public function addParticles(particles:Vector.<Particle>, applyInitializers:Boolean = false):voidAdds 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) |
See also
| createParticle | () | method |
| dispatchCounterComplete | () | method |
public function dispatchCounterComplete():voidUsed by counters to tell the emitter to dispatch a counter complete event.
| hasAction | () | method |
public function hasAction(action:Action):BooleanDetects if the emitter is using a particular action or not.
Parameters
action:Action — The action to look for.
|
Boolean — true if the action is being used by the emitter, false
otherwise.
|
| hasActionOfType | () | method |
public function hasActionOfType(actionClass:Class):BooleanDetects if the emitter is using an action of a particular class.
Parameters
actionClass:Class — The type of action to look for.
|
Boolean — true if the emitter is using an instance of the class as an
action, false otherwise.
|
| hasActivity | () | method |
public function hasActivity(activity:Activity):BooleanDetects if the emitter is using a particular activity or not.
Parameters
activity:Activity — The activity to look for.
|
Boolean — true if the activity is being used by the emitter, false
otherwise.
|
| hasActivityOfType | () | method |
public function hasActivityOfType(activityClass:Class):BooleanDetects if the emitter is using an activity of a particular class.
Parameters
activityClass:Class — The type of activity to look for.
|
Boolean — true if the emitter is using an instance of the class as an
activity, false otherwise.
|
| hasInitializer | () | method |
public function hasInitializer(initializer:Initializer):BooleanDetects if the emitter is using a particular initializer or not.
Parameters
initializer:Initializer — The initializer to look for.
|
Boolean — true if the initializer is being used by the emitter, false
otherwise.
|
| hasInitializerOfType | () | method |
public function hasInitializerOfType(initializerClass:Class):BooleanDetects if the emitter is using an initializer of a particular class.
Parameters
initializerClass:Class — The type of initializer to look for.
|
Boolean — true if the emitter is using an instance of the class as an
initializer, false otherwise.
|
| initParticle | () | method |
protected function initParticle(particle:Particle):voidEmitters 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():voidKill all the particles on this emitter.
| pause | () | method |
public function pause():voidPauses the emitter.
| removeAction | () | method |
public function removeAction(action:Action):voidRemoves an Action from the Emitter.
Parameters
action:Action — The Action to remove
|
See also
| removeActivity | () | method |
public function removeActivity(activity:Activity):voidRemoves an Activity from the Emitter.
Parameters
activity:Activity — The Activity to remove
|
See also
| removeInitializer | () | method |
public function removeInitializer(initializer:Initializer):voidRemoves an Initializer from the Emitter.
Parameters
initializer:Initializer — The Initializer to remove
|
See also
| removeParticle | () | method |
public function removeParticle(particle:Particle):BooleanRemove a particle from this emitter.
Parameters
particle:Particle — The particle to remove.
|
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>):voidRemove a collection of particles from this emitter.
Parameters
particles:Vector.<Particle> — The particles to remove.
|
| resume | () | method |
public function resume():voidResumes the emitter after a pause.
| runAhead | () | method |
public function runAhead(time:Number, frameRate:Number = 10):voidMakes 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) |
| sortParticles | () | method |
protected function sortParticles():voidUsed to sort the particles as required. In this base class this method does nothing.
| start | () | method |
public function start():voidStarts the emitter. Until start is called, the emitter will not emit or update any particles.
| stop | () | method |
public function stop():voidStops the emitter, killing all current particles and returning them to the particle factory for reuse.
| update | () | method |
public function update(time:Number):voidUsed 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
| counterComplete | Event |
org.flintparticles.common.events.EmitterEventorg.flintparticles.common.events.EmitterEvent.COUNTER_COMPLETEDispatched 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 |
org.flintparticles.common.events.EmitterEventorg.flintparticles.common.events.EmitterEvent.EMITTER_EMPTYDispatched 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
| emitterUpdated | Event |
org.flintparticles.common.events.EmitterEventorg.flintparticles.common.events.EmitterEvent.EMITTER_UPDATEDDispatched when the particle system has updated and the state of the particles has changed.
| particleAdded | Event |
org.flintparticles.common.events.ParticleEventorg.flintparticles.common.events.ParticleEvent.PARTICLE_ADDEDDispatched when a pre-existing particle is added to the emitter.
| particleCreated | Event |
org.flintparticles.common.events.ParticleEventorg.flintparticles.common.events.ParticleEvent.PARTICLE_CREATEDDispatched when a particle is created and has just been added to the emitter.
| particleDead | Event |
org.flintparticles.common.events.ParticleEventorg.flintparticles.common.events.ParticleEvent.PARTICLE_DEADDispatched 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.