Packagecv
Classpublic class Orion
InheritanceOrion Inheritance flash.display.Sprite
ImplementsIOutput
SubclassesOrionBitmap, OrionContainer, OrionMouse

Orion ©2009 Gabriel Mariani, coursevector.com.
Visit http://blog.coursevector.com/orion for documentation, updates and more free code.
Licensed under the MIT license - see the source file header for more information.
Orion is an easy to use and light-weight particle system. It's instance oriented much like GTween so you can re-use and modify easily. It's also very fast, capable of handling over 3000 particles at more than 30fps if your computer can handle it. But unless you're doing something really intense you probably won't notice any slowdown. At it's smallest Orion will add about 6kb to your filesize.

The Orion class is the hub of particle system. It determines where the particles will be generated. All particles are generated within the bounds of the Orion instance. So if you set it up to be 100x100, the particles will be generated somewhere within that area. If you set the width and height below 1 (i.e. 0x0), it will generate all the particles at the center of the instance.

To control where the particles can be displayed you can modify the canvas property. The canvas is a simple rectange object, changing the height, width, and position of it will determine where the particles will be displayed and when the edgeFilter will take action.

Orion is easy to use and incredibly flexible and customizable. To keep it's size down, there are effectFilters, the more you add the more work Orion has to do which can affect performance and filesize. So keep this in mind before you use every filter and wonder why it's not handling 3000 particles easily. Below are some examples to show you how to use Orion and how quickly you can get up and running. Since Orion is so customizable, I thought it would be nice to be able to save those configurations so you can use the same settings again. This is what the presets are used for. They will configure an instance of Orion with the given settings. If you have to find a setting you like you can create your own presets and load them as well.


Example
The only requirement to use Orion is to have an item exported from the library. 

  import cv.Orion;
  import cv.orion.preset.Default; // A small set of common presets
  
  var e:Orion = new Orion(linkageClass, null, Default.firework());
  this.addChild(e);


That's it! Although that is a very basic setup but as you can see, it doesn't take much work to get a particle system up and running in your code.


Public Properties
 PropertyDefined by
  cacheBlendMode : String = "normal"
Gets or sets the blend mode applied to particles when they are created.
Orion
  cacheFrames : Array
[read-only] The storage location for frames that are cached.
Orion
  cachePixelSnapping : String = "auto"
Gets or sets pixel snapping when frame caching is enabled.
Orion
  cacheSmoothing : Boolean = false
Gets or sets bitmap smoothing when using frame caching.
Orion
  cacheTarget : MovieClip
[read-only] Gets the frame cache movieclip.
Orion
  canvas : Rectangle
The canvas is used to control the boundaries (edge filter) of the particles animating.
Orion
  createEmitters : Array
Triggers the emitters everytime a particle from this emitter is created.
Orion
  debug : Boolean = false
Turns on debug lines to outline the emitter and canvas dimensions
Orion
  destroyEmitters : Array
Triggers the emitters everytime a particle from this emitter is destroyed.
Orion
  edgeFilter : IFilter
Gets or sets the edge filter used by the emitter to determine what the particles will do when they hit the edge.
Orion
  effectFilters : Array
Gets the filters being applied by the emitter.
Orion
  height : Number
Gets or sets the height of the emitter.
Orion
  output : IOutput
Gets or sets the output class used.
Orion
  particles : Array
[read-only] The array of all the particles in this instance of Orion
Orion
  particlesVisible : Boolean = true
As the particles are updated, this will toggle visibility on or off.
Orion
  paused : Boolean
Gets or sets the paused property
Orion
  settings : Object
The settings object controls all configuration.
Orion
  spriteClass : Class
Gets or sets the specific library linkId (class reference)
Orion
  time : int
[static] Current Time
Orion
  updateEmitters : Array
Triggers the emitters everytime a particle from this emitter gets updated.
Orion
  useCacheAsBitmap : Boolean = false
Gets or sets whether bitmap caching is enabled on particles used within this emitter.
Orion
  useFrameCaching : Boolean
Gets or sets whether frame caching will be enabled.
Orion
  width : Number
Gets or sets the width of the emitter.
Orion
  x : Number
Gets or sets the x position of the emitter.
Orion
  y : Number
Gets or sets the y position of the emitter.
Orion
Public Methods
 MethodDefined by
  
Orion(spriteClass:Class = null, output:IOutput = null, config:Object = null, useFrameCaching:Boolean = false)
The constructor allows a few common settings to be specified during construction.
Orion
  
applyPreset(config:Object = null, reset:Boolean = false):void
Orion
  
emit(point:Point = null):void
Causes the emitter to add particles.
Orion
  
interpolateColor(fromColor:uint, toColor:uint, progress:Number):uint
[static] Finds a color that's between the two numbers given.
Orion
  
interpolateTransform(fromColor:ColorTransform, toColor:ColorTransform, progress:Number):ColorTransform
[static] Finds a ColorTransform that's between the two ColorTransforms given.
Orion
  
killGarbage(e:TimerEvent = null):void
This will run ever 2 seconds and remove any inactive particles from memory.
Orion
  
pause():void
Pauses the particle system
Orion
  
play():void
Resumes or plays the particle system
Orion
  
removeAllParticles():void
Removes all particles from the emitter.
Orion
  
removeItem(array:Array, item:*):Boolean
[static] Removes a specified item from the array.
Orion
  
render(e:Event = null):void
Updates all the particles and positions, updates the output class as well.
Orion
  
rotateCoord(x:Number, y:Number, sin:Number, cos:Number):Point
[static] Takes a given coordinate and rotates it in a 2D space.
Orion
  
update(emitter:Orion):void
This acts as a fake output update function for use by the Update and Destroy emitters.
Orion
Protected Methods
 MethodDefined by
  
addParticle(pt:Point = null):void
Adds a new particle to the system.
Orion
  
cacheFramesOf(mc:MovieClip):void
If it's a movieclip, cache it's frames.
Orion
  
getColorTransform(p:ParticleVO, targetColor:uint):ColorTransform
Used to get a colortransform object for a specific particle.
Orion
  
getCoordinate():Point
Returns a coordinate it's designated position.
Orion
  
getNew():ParticleVO
Returns a new particle
Orion
  
getRecycled():ParticleVO
Checks the recycle bin if a suitable particle can be re-used.
Orion
  
gotoAndStopCached(d:DisplayObject, frame:int):void
Sets a given particle to a specific frame in the movieclip, from the frame cached in memory.
Orion
  
randomRange(min:Number, max:Number):Number
[static] Return a random number between a range of numbers
Orion
  
recycleParticle(p:ParticleVO):void
Removes a particle and stores the reference to the particle inside of the recyclebin dictionary.
Orion
  
removeParticle(p:ParticleVO, doArray:Boolean = true):void
Removes a particle.
Orion
  
renderParticle(p:ParticleVO):void
Updates the specific particle based on the filters assigned to the emitter.
Orion
  
resetParticle(p:ParticleVO):void
Resets the particle and initializes it for use.
Orion
  
stageHandler(e:Event):void
The stage handler, this listens for the Event.ADDED_TO_STAGE event, so it knows when it can access the stage property.
Orion
Events
 EventSummaryDefined by
  
change
This event is dispatched each time Orion renders the particles.Orion
  
resize
This event is dispatched each time Orion is resized.Orion
Public Constants
 ConstantDefined by
  DEG2RAD : Number = 0.017453292519943295
[static] Stored decimal value for conversion
Orion
  VERSION : String = "1.0.0"
[static] The current version of Orion.
Orion
Property detail
cacheBlendModeproperty
public var cacheBlendMode:String = "normal"

Gets or sets the blend mode applied to particles when they are created. It is also used when caching particles.

cacheFramesproperty 
cacheFrames:Array  [read-only]

The storage location for frames that are cached. Used by filters and emitters.

Implementation
    public function get cacheFrames():Array
cachePixelSnappingproperty 
public var cachePixelSnapping:String = "auto"

Gets or sets pixel snapping when frame caching is enabled. Pixel snapping determines whether or not the Bitmap object is snapped to the nearest pixel.

cacheSmoothingproperty 
public var cacheSmoothing:Boolean = false

Gets or sets bitmap smoothing when using frame caching.

cacheTargetproperty 
cacheTarget:MovieClip  [read-only]

Gets the frame cache movieclip. This is the movieclip that has had it's frames cached.

Implementation
    public function get cacheTarget():MovieClip
canvasproperty 
public var canvas:Rectangle

The canvas is used to control the boundaries (edge filter) of the particles animating.

createEmittersproperty 
public var createEmitters:Array

Triggers the emitters everytime a particle from this emitter is created. This allows for effects like the explosion before a firework goes up. This array can only accept instances of the Orion class. When using this, specify the output of the child emitter to the parent emitter.

debugproperty 
public var debug:Boolean = false

Turns on debug lines to outline the emitter and canvas dimensions

destroyEmittersproperty 
public var destroyEmitters:Array

Triggers the emitters everytime a particle from this emitter is destroyed. This allows for effects like the explosion after a firework goes up. This array can only accept instances of the Orion class. When using this, specify the output of the child emitter to the parent emitter.

edgeFilterproperty 
public var edgeFilter:IFilter

Gets or sets the edge filter used by the emitter to determine what the particles will do when they hit the edge. Pass nothing to it in order to reset it.

effectFiltersproperty 
public var effectFilters:Array

Gets the filters being applied by the emitter.

heightproperty 
height:Number  [read-write]

Gets or sets the height of the emitter.

Implementation
    public function get height():Number
    public function set height(value:Number):void
outputproperty 
public var output:IOutput

Gets or sets the output class used. The default is the null.

particlesproperty 
particles:Array  [read-only]

The array of all the particles in this instance of Orion

Implementation
    public function get particles():Array
particlesVisibleproperty 
public var particlesVisible:Boolean = true

As the particles are updated, this will toggle visibility on or off. Used by the BitmapRenderer/PixelRenderer so it can hide the particles without additional overhead.

pausedproperty 
paused:Boolean  [read-write]

Gets or sets the paused property

Implementation
    public function get paused():Boolean
    public function set paused(value:Boolean):void
settingsproperty 
public var settings:Object

The settings object controls all configuration. The settings object can contain the following properties :

spriteClassproperty 
spriteClass:Class  [read-write]

Gets or sets the specific library linkId (class reference)

Implementation
    public function get spriteClass():Class
    public function set spriteClass(value:Class):void
timeproperty 
public static var time:int

Current Time

updateEmittersproperty 
public var updateEmitters:Array

Triggers the emitters everytime a particle from this emitter gets updated. This allows for effects like trailing smoke of a particle. This array can only accept instances of the Orion class. When using this, specify the output of the child emitter to the parent emitter.

useCacheAsBitmapproperty 
public var useCacheAsBitmap:Boolean = false

Gets or sets whether bitmap caching is enabled on particles used within this emitter. If set to true, Flash Player or Adobe AIR caches an internal bitmap representation of the display object. This caching can increase performance for display objects that contain complex vector content.

useFrameCachingproperty 
useFrameCaching:Boolean  [read-write]

Gets or sets whether frame caching will be enabled. Frame caching takes a snapshot of each frame of a movieclip and stores the bitmaps in an array. This bitmapdata is used later for new particles. This can greatly improve performance on occasion (especially movieclips with lots of fiters used inside or multiple frames).

Implementation
    public function get useFrameCaching():Boolean
    public function set useFrameCaching(value:Boolean):void
widthproperty 
width:Number  [read-write]

Gets or sets the width of the emitter.

Implementation
    public function get width():Number
    public function set width(value:Number):void
xproperty 
x:Number  [read-write]

Gets or sets the x position of the emitter.

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

See also

Orion.getCoordinate()
Orion.y
yproperty 
y:Number  [read-write]

Gets or sets the y position of the emitter.

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

See also

Orion.getCoordinate()
Orion.x
Constructor detail
Orion()constructor
public function Orion(spriteClass:Class = null, output:IOutput = null, config:Object = null, useFrameCaching:Boolean = false)

The constructor allows a few common settings to be specified during construction. Options such as the output class or any configuration settings.

Parameters
spriteClass:Class (default = null) — This is the linkage class of the item you have exported from the library.
 
output:IOutput (default = null) — Here you can specify which output class you'd like to use. If you don't want to use one, just leave this as null
 
config:Object (default = null) — Here you can pass in a configuration object. A configuration object is generated by a preset or you can write one by hand. Each configuration object can contain an effectFilters array, an edgeFilter object, and a settings object. The settings object can contain all the same properties that modifying the settings property directly allows.
 
useFrameCaching:Boolean (default = false) — Frame caching is useful for particles that have a lot of glow filters or native Flash filters applied. Turning on frame caching will cause Orion to take a snapshot of each frame of the particle and turn it into a Bitmap and use the Bitmap instead. This can greatly increase performance for complicated particles.

See also

Orion.settings
Orion.useFrameCaching
Method detail
addParticle()method
protected function addParticle(pt:Point = null):void

Adds a new particle to the system. Before creating a new particle, it will check the recycle bin of old particles to see if it can match the particle requested. If so, it will re-use an old particle rather than create a new one as this is quicker on the player.

Parameters
pt:Point (default = null) — The point to position the particle at.

See also

Orion.getCoordinate()
Orion.spriteClass
applyPreset()method 
public function applyPreset(config:Object = null, reset:Boolean = false):voidParameters
config:Object (default = null)
 
reset:Boolean (default = false)
cacheFramesOf()method 
protected function cacheFramesOf(mc:MovieClip):void

If it's a movieclip, cache it's frames.

Parameters
mc:MovieClip — The particle to have it's frames cached.
emit()method 
public function emit(point:Point = null):void

Causes the emitter to add particles.

Parameters
point:Point (default = null) — Where to position the particle
getColorTransform()method 
protected function getColorTransform(p:ParticleVO, targetColor:uint):ColorTransform

Used to get a colortransform object for a specific particle.

Parameters
p:ParticleVO — The particle to be recycled
 
targetColor:uint

Returns
ColorTransform — The given colortransform object
getCoordinate()method 
protected function getCoordinate():Point

Returns a coordinate it's designated position.

Returns
Point — Returns a coordinate at the emitters x,y position or within it.
getNew()method 
protected function getNew():ParticleVO

Returns a new particle

Returns
ParticleVO — The particle
getRecycled()method 
protected function getRecycled():ParticleVO

Checks the recycle bin if a suitable particle can be re-used.

Returns
ParticleVO — The particle
gotoAndStopCached()method 
protected function gotoAndStopCached(d:DisplayObject, frame:int):void

Sets a given particle to a specific frame in the movieclip, from the frame cached in memory.

Parameters
d:DisplayObject — The particle
 
frame:int — The frame number to go to
interpolateColor()method 
public static function interpolateColor(fromColor:uint, toColor:uint, progress:Number):uint

Finds a color that's between the two numbers given.

Parameters
fromColor:uint — The first color
 
toColor:uint — The second color
 
progress:Number — The ratio between the two colors you want returned.

Returns
uint — The color between the two colors.
interpolateTransform()method 
public static function interpolateTransform(fromColor:ColorTransform, toColor:ColorTransform, progress:Number):ColorTransform

Finds a ColorTransform that's between the two ColorTransforms given.

Parameters
fromColor:ColorTransform — The first ColorTransform
 
toColor:ColorTransform — The second ColorTransform
 
progress:Number — The ratio between the two ColorTransforms you want returned.

Returns
ColorTransform — The ColorTransform between the two ColorTransforms.
killGarbage()method 
public function killGarbage(e:TimerEvent = null):void

This will run ever 2 seconds and remove any inactive particles from memory.

Parameters
e:TimerEvent (default = null) — The event dispatched.
pause()method 
public function pause():void

Pauses the particle system

play()method 
public function play():void

Resumes or plays the particle system

randomRange()method 
protected static function randomRange(min:Number, max:Number):Number

Return a random number between a range of numbers

Parameters
min:Number — The minimum number in the range
 
max:Number — The maximum number in the range

Returns
Number — A random number between the two numbers given.
recycleParticle()method 
protected function recycleParticle(p:ParticleVO):void

Removes a particle and stores the reference to the particle inside of the recyclebin dictionary.

Parameters
p:ParticleVO — The particle to be recycled
removeAllParticles()method 
public function removeAllParticles():void

Removes all particles from the emitter. This also frees up any memory used by the particles.

removeItem()method 
public static function removeItem(array:Array, item:*):Boolean

Removes a specified item from the array.

Parameters
array:Array — The array to go through
 
item:* — The item to be removed

Returns
Boolean — A boolean whether it was successful or not
removeParticle()method 
protected function removeParticle(p:ParticleVO, doArray:Boolean = true):void

Removes a particle. This is typically called during the garbage collection phase of a particle's life.

Parameters
p:ParticleVO — The particle to be removed.
 
doArray:Boolean (default = true) — Whether to remove from the particle array or not.
render()method 
public function render(e:Event = null):void

Updates all the particles and positions, updates the output class as well.

Parameters
e:Event (default = null) — The event dispatched.
renderParticle()method 
protected function renderParticle(p:ParticleVO):void

Updates the specific particle based on the filters assigned to the emitter. Also handles any garbage clean up.

Parameters
p:ParticleVO — The particle to be rendered and updated.
resetParticle()method 
protected function resetParticle(p:ParticleVO):void

Resets the particle and initializes it for use.

Parameters
p:ParticleVO — The particle to be rendered and updated.
rotateCoord()method 
public static function rotateCoord(x:Number, y:Number, sin:Number, cos:Number):Point

Takes a given coordinate and rotates it in a 2D space. This is used for calculations like collosions detection.

Parameters
x:Number — The x coordinate
 
y:Number — The y coordinate
 
sin:Number — The sine of the angle to rotate
 
cos:Number — The cosine of the angle to rotate

Returns
Point — The adjusted point after rotation.
stageHandler()method 
protected function stageHandler(e:Event):void

The stage handler, this listens for the Event.ADDED_TO_STAGE event, so it knows when it can access the stage property. If the emitter is not part of the display list, it will automatically pause itself.

Parameters
e:Event — The event dispatched.
update()method 
public function update(emitter:Orion):void

This acts as a fake output update function for use by the Update and Destroy emitters.

Parameters
emitter:Orion — The emitter to be used.
Event detail
changeevent 
Event object type: flash.events.Event

This event is dispatched each time Orion renders the particles.

resizeevent  
Event object type: flash.events.Event

This event is dispatched each time Orion is resized.

Constant detail
DEG2RADconstant
public static const DEG2RAD:Number = 0.017453292519943295

Stored decimal value for conversion

VERSIONconstant 
public static const VERSION:String = "1.0.0"

The current version of Orion.




Copyright 2009 Gabriel Mariani (http://blog.coursevector.com/orion)