Packagecom.desuade.partigen.emitters
Classpublic dynamic class BasicEmitter
InheritanceBasicEmitter Inheritance flash.display.Sprite
Subclasses Emitter

Language Version : ActionScript 3
Since : 08.05.2009
Runtime Versions : AIR 1.0, Flash Player 9.0.0

The most basic form of an Emitter, offering the minimum necessary to emit particles.


Public Properties
 PropertyDefined By
  active : Boolean
[read-only] This is true if the emitter is currently emitting.
BasicEmitter
  burst : int = 1
This is the amount of particles to be created on each emission.
BasicEmitter
  cacheParticleAsBitmap : Boolean = false
This will set "cacheAsBitmap = true" on all created particles. Test using this vs groupBitmap - as performance will vary based on each effect. Also test this with BitmapRenderer, as it may vary the effect and performance.
BasicEmitter
  enableEvents : Boolean = false
Enable particle BORN and DIED events.
BasicEmitter
  eps : Number
This stands for "emissions per second".
BasicEmitter
  forceVariety : Boolean = false
This forces pooled particles to rebuild their groups and controllers to eliminate any possible repetition or error at the cost of performance. Set this to true if you plan on making changes to the emitter while it's running.
BasicEmitter
  groupAmount : int = 1
This controls how may particles are made in a "particle group".
BasicEmitter
  groupBitmap : Boolean = false
This will create a new Bitmap object for the particle instead of the direct display object.
BasicEmitter
  groupProximity : int = 0
This determines the maximum distance away from the center of the group to create new particles.
BasicEmitter
  id : int
[read-only] The unique id of the emitter.
BasicEmitter
  life : Number = 1
This is the duration in seconds a particle will exist for. If the value is 0, the particle will live forever.
BasicEmitter
  lifeSpread : * = 0
This is the spread for particle lives.
BasicEmitter
  particle : Class
This is the class used to create new particles from.
BasicEmitter
  particleBaseClass : Class
This is the base class to used for all created particles. When the pools create particle objects, they use this.
BasicEmitter
  particleBlendMode : String = normal
This defines the blendmode for each particle created. Choices: "add", "alpha", "darken", "difference", "erase", "hardlight", "invert", "layer", "lighten", "multiply", "normal", "overlay", "screen", "subtract" Note: PixelRenderer will assume the blendmode of all particles/pixels is the same.
BasicEmitter
  particleFilters : Array
This is an array of filters that gets applied to each particle as it's born.
BasicEmitter
  pool : Pool
This is the Pool to use to store and manage the actual particle objects.
BasicEmitter
  renderer : Renderer
The Renderer to use for created particles.
BasicEmitter
Public Methods
 MethodDefined By
  
BasicEmitter()
This creates a new BasicEmitter. This emitter does not have any controllers, and only offers basic emission and event functionality.
BasicEmitter
  
createParticleBitmap(padding:int = 0):void
This creates the main bitmapdata object used when groupBitmap == true.
BasicEmitter
  
emit(burst:int = 1):void
This method creates new particles each time it's called.
BasicEmitter
  
fromXML(xml:XML, reset:Boolean = true, renderer:Boolean = false):*
This configures the emitter based on the XML, and adds any controllers (if available)
BasicEmitter
  
getPrefetchLifeArray(time:Number):Array
This creates an array of particle's life values, both original and current, based on the eps/burst and supplied time value as it would if the emitter was running for the time duration.
BasicEmitter
  
killParticles():void
This kills all currently existing particles in the pool created by this emitter
BasicEmitter
  
prefetch(time:Number):void
This prefetches (and creates) the particles that would have existed if the emitter was running for the given time.
BasicEmitter
  
reset():void
This resets the emitter to the defaults and purges the pool
BasicEmitter
  
start(time:Number = 0, runcontrollers:Boolean = true):void
Starts the emitter.
BasicEmitter
  
stop(runcontrollers:Boolean = true, purge:Boolean = true):void
This stops the emitter from emitting particles.
BasicEmitter
  
toXML():XML
This generates an XML object representing the entire emitter
BasicEmitter
Property Detail
activeproperty
active:Boolean  [read-only]

This is true if the emitter is currently emitting.


Implementation
    public function get active():Boolean
burstproperty 
public var burst:int = 1

This is the amount of particles to be created on each emission.

cacheParticleAsBitmapproperty 
public var cacheParticleAsBitmap:Boolean = false

This will set "cacheAsBitmap = true" on all created particles.

Test using this vs groupBitmap - as performance will vary based on each effect.

Also test this with BitmapRenderer, as it may vary the effect and performance.

enableEventsproperty 
public var enableEvents:Boolean = false

Enable particle BORN and DIED events. The default is false;

epsproperty 
eps:Number

This stands for "emissions per second". This is how many times per-second that the emitter will run the emit() method.

The total amount of particles-per-second depends on this eps value, the burst, and the group amount.

In order to do 1 emission every 2 seconds, etc, divide 1 by the amount of seconds - ie: eps = 0.5

Note: this internally sets up a timer each time it's set, so the eps value can not be currently tweened.


Implementation
    public function get eps():Number
    public function set eps(value:Number):void
forceVarietyproperty 
public var forceVariety:Boolean = false

This forces pooled particles to rebuild their groups and controllers to eliminate any possible repetition or error at the cost of performance.

Set this to true if you plan on making changes to the emitter while it's running. If you make changes via XML, the pool will automatically force a pool.purge() just to be safe.

groupAmountproperty 
public var groupAmount:int = 1

This controls how may particles are made in a "particle group". This allows you to have many particle act as a single particle.

This lets there be exponentially more particles since the sam amount of controllers/tweens are used regardless of the groupAmount.

groupBitmapproperty 
public var groupBitmap:Boolean = false

This will create a new Bitmap object for the particle instead of the direct display object. Used to improve performance of static particles. Be sure to use in conjunction with createParticleBitmap() (handled automatically with start()).

Test using this vs cacheParticleAsBitmap - as performance will vary based on each effect.

Also test this with BitmapRenderer, as it may vary the effect and performance.

groupProximityproperty 
public var groupProximity:int = 0

This determines the maximum distance away from the center of the group to create new particles.

idproperty 
id:int  [read-only]

The unique id of the emitter.


Implementation
    public function get id():int
lifeproperty 
public var life:Number = 1

This is the duration in seconds a particle will exist for.

If the value is 0, the particle will live forever.

lifeSpreadproperty 
public var lifeSpread:* = 0

This is the spread for particle lives. This will create a random range for the life of new particles.

Note: if the life value is 0, this has no effect.

particleproperty 
particle:Class

This is the class used to create new particles from. This can be an AS3 class, or a library MC. This is the source (image, movieclip, text, etc) used to be added as a child onto the actual particleBaseClass.

As of v2.1, this can be any class, and does NOT have to inherit BasicParticle. If you have custom classes that do inherit it, use particleBaseClass instead.


Implementation
    public function get particle():Class
    public function set particle(value:Class):void
particleBaseClassproperty 
particleBaseClass:Class

This is the base class to used for all created particles.

When the pools create particle objects, they use this. The 'particle' property, is the actual class used for particles you see.

This should only be used by classes that inherit BasicParticle or Particle. Most of the time you should not need to change this.


Implementation
    public function get particleBaseClass():Class
    public function set particleBaseClass(value:Class):void
particleBlendModeproperty 
public var particleBlendMode:String = normal

This defines the blendmode for each particle created.

Choices: "add", "alpha", "darken", "difference", "erase", "hardlight", "invert", "layer", "lighten", "multiply", "normal", "overlay", "screen", "subtract"

Note: PixelRenderer will assume the blendmode of all particles/pixels is the same.

particleFiltersproperty 
public var particleFilters:Array

This is an array of filters that gets applied to each particle as it's born.

poolproperty 
public var pool:Pool

This is the Pool to use to store and manage the actual particle objects. A NullPool is created by default. This can be a new Pool or just assigned to an external independent Pool.

rendererproperty 
public var renderer:Renderer

The Renderer to use for created particles. A NullRenderer is created by default. This can be a new Renderer or just assigned to an external independent Renderer.

Constructor Detail
BasicEmitter()Constructor
public function BasicEmitter()

This creates a new BasicEmitter.

This emitter does not have any controllers, and only offers basic emission and event functionality.

Method Detail
createParticleBitmap()method
public function createParticleBitmap(padding:int = 0):void

This creates the main bitmapdata object used when groupBitmap == true.

Parameters

padding:int (default = 0) — Padding around the image (to compensate for filters).

emit()method 
public function emit(burst:int = 1):void

This method creates new particles each time it's called. The amount of particles it creates is dependent on the burst amount passed.

Parameters

burst:int (default = 1) — The amount of particles to create at once.

fromXML()method 
public function fromXML(xml:XML, reset:Boolean = true, renderer:Boolean = false):*

This configures the emitter based on the XML, and adds any controllers (if available)

Parameters

xml:XML — The XML object to use to configure the emitter
 
reset:Boolean (default = true) — Resets the emitter before applying XML and also purges the pool
 
renderer:Boolean (default = false) — If true, this creates (and overwrites) the emitter's renderer with one from XML. If this is a BitmapRenderer, be sure to call resize(width, height) on it after the XML. Also, for BasicEmitters only (to save file size), you must create a reference to the Renderers you're going to use before using it through XML (for Flash to include the classes). This can be done easily as var renderers:Array = [NullRenderer, StandardRenderer, BitmapRenderer]; (this is done already for the Emitter and IDEEmitter classes).

Returns
* — The emitter object (for chaining)
getPrefetchLifeArray()method 
public function getPrefetchLifeArray(time:Number):Array

This creates an array of particle's life values, both original and current, based on the eps/burst and supplied time value as it would if the emitter was running for the time duration.

Parameters

time:Number — The amount of time that should have passed since the emitter started.

Returns
Array — An Array with Arrays that contain the original life and current life [[1, .8], [1, .5], [1, .2]]
killParticles()method 
public function killParticles():void

This kills all currently existing particles in the pool created by this emitter

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

This prefetches (and creates) the particles that would have existed if the emitter was running for the given time. This shouldn't be called directly, but through the start() method.

Parameters

time:Number — The amount of time that should have passed since the emitter started.

reset()method 
public function reset():void

This resets the emitter to the defaults and purges the pool

start()method 
public function start(time:Number = 0, runcontrollers:Boolean = true):void

Starts the emitter. Passing a time will 'prefetch' particles as if the emitter had already been running for the given amount of time. If you only want to emit once, or at your own rate, use emit()

Parameters

time:Number (default = 0) — Starts the emitter as if it's already been running for this duration in seconds. If using physics controllers, be sure to set BaseTicker.physicsRate = stage.frameRate for accurate rendering.
 
runcontrollers:Boolean (default = true) — This does nothing for BasicEmitters, and is only used for emitter classes with controllers.

See also

emit()
stop()method 
public function stop(runcontrollers:Boolean = true, purge:Boolean = true):void

This stops the emitter from emitting particles.

Parameters

runcontrollers:Boolean (default = true) — This does nothing for BasicEmitters, and is only used for emitter classes with controllers.
 
purge:Boolean (default = true) — This purges the pool when all particles have finished safely.

toXML()method 
public function toXML():XML

This generates an XML object representing the entire emitter

Returns
XML — An XML object representing the emitter



Copyright 2009-2011 Desuade

Sat Feb 5 2011, 08:04 PM -08:00