Packagecc.cote.airbag
Classpublic class AirBag
InheritanceAirBag Inheritance flash.events.EventDispatcher

The AirBag class allows the pixel-precise detection of collisions amongst a list of DisplayObjects (MovieClips, Sprites, Bitmaps, TextFields, Videos, etc.). It also facilitates the exclusion of certain color ranges from detection and takes into account the desired alpha threshold. To perform collision detection, you must first specify a list of objects upon which the detection will take place. The way do do that is to pass a list of DisplayObjects to the constructor or to the add() method. Both the constructor and the add() method support any combination of the following objects:

By default, collision detection works in a many-to-many relationship. That is, all objects will be checked against all other objects when calling the detect() method.

Alternatively, if a specific target has been assigned by way of the singleTarget property, detection will work in a one-to-many relationship. This means that only collisions between the singleTarget and one of the objects in the list will be reported.

Usage

To use AirBag, you simply create an AirBag object by supplying it with DisplayObjects to add to its detection list. This can be done through the constructor and/or with the add() method:

     public var airbag:AirBag = new AirBag(obj1, obj2, obj3);
     airbag.add(obj4, obj5);

Then, you call the detect() method whenever appropriate. For example, you can continually check for collisions by using an ENTER_FRAME handler:

     addEventListener(Event.ENTER_FRAME, detect);
     
     public function detect(e:Event):void {
         var collisions:Vector.<Collision> = airbag.detect();
         if (collisions.length) {
             trace("Collision detected!");
         }
     }

If you only want to track collisions against a single object, you can use the singleTarget property:

     public var airbag:AirBag = new AirBag(obj1, obj2, obj3);
     airbag.singleTarget = obj4;

This will report all collisions of obj1, obj2 and obj3 with obj4 but won't report collisions of obj1, obj2 and obj3 with themselves.

Starting in version 1.0a rev1, you can listen to events directly on the AirBag object.

     public var airbag:AirBag = new AirBag(obj1, obj2, obj3);
     airbag.addEventListener(AirBagEvent.DETECTION, onDetection);
     
     public function onDetection(e:Event):void {
         if (e.collisions.length) {
             trace("Collision detected!");
         }
     }

The AirBagEvent.DETECTION event is triggered each time detection is performed (typically on ENTER_FRAME unless the skip property is used). The AirBagEvent.COLLISION event is triggered only when at least one collision is found in a detection run.

See also

cc.cote.airbag.Collision
cc.cote.airbag.AirBagEvent
Official AirBag project page


Public Properties
 PropertyDefined By
  alphaThreshold : Number
The alpha (opacity) threshold below which a collision will not be triggered.
AirBag
  calculateAngles : Boolean
Boolean indicating if angles should be calculated and included in the Collision objects.
AirBag
  calculateOverlap : Boolean
Boolean indicating if the vector of overlapping points should be calculated and returned in the Collision objects.
AirBag
  debug : Boolean
Enables/disables debug mode.
AirBag
  ignoreInvisibles : Boolean
Boolean indicating if objects whose visible property are false should be ignored by the detection process.
AirBag
  ignoreParentless : Boolean
Boolean indicating if parentless objects (those who are not on the display list) should be ignored by the detection process.
AirBag
  mode : String
[read-only] The detection mode currently in use.
AirBag
  numObjects : uint
[read-only] The number of objects currently in the detection list.
AirBag
  outlines : Sprite
[read-only] A Sprite inside which debugging shapes are drawn to help visualise how AirBag tracks items and detects collisions.
AirBag
  singleTarget : DisplayObject
A DisplayObject against which all collision detection will exclusively take place.
AirBag
  skip : uint
The number of frames to skip when performing detection.
AirBag
Public Methods
 MethodDefined By
  
AirBag(... objects)
Creates an AirBag object from the DisplayObjects passed as parameters.
AirBag
  
add(... objects):void
Adds DisplayObjects to the detection list.
AirBag
  
addColorToExclusionList(color:uint, alphaRange:uint = 255, redRange:uint = 20, greenRange:uint = 20, blueRange:uint = 20):void
Adds a color to the color exclusion list.
AirBag
  
clear():void
Clears the detection list and removes any singleTarget that might have been assigned.
AirBag
  
detect():Vector.<Collision>
Performs the collision detection and returns a vector of Collision objects.
AirBag
  
dispose():void
Properly disposes of the object.
AirBag
  
remove(... objects):void
Removes DisplayObjects from the detection list.
AirBag
  
removeColorFromExclusionList(theColor:uint):void
Removes a color from the color exclusion list.
AirBag
  
start():void
Starts the automated collision detection process.
AirBag
  
stop():void
Stops the automated collision detection process.
AirBag
  
toString():String
[override] Returns a string representation of the object.
AirBag
Events
 Event Summary Defined By
  Dispatched when AirBag detects at least one collision during its scheduled detection run.AirBag
  Dispatched each time AirBag performs its detection routine.AirBag
Public Constants
 ConstantDefined By
  MANY_TO_MANY : String = manyToMany
[static] Constant defining a MANY_TO_MANY detection mode.
AirBag
  ONE_TO_MANY : String = oneToMany
[static] Constant defining a ONE_TO_MANY detection mode.
AirBag
  VERSION : String = 1.0a rev3
[static] Current version of the library.
AirBag
Property Detail
alphaThresholdproperty
alphaThreshold:Number

The alpha (opacity) threshold below which a collision will not be triggered. This property expects a value between 0 and 1 inclusively. For example, a value of 0.25 means that pixels that are less than 25% opaque will not trigger a collision.

The default value is 1/255 ≈ 0.004.


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

Throws
RangeError The — alphaThreshold property expects a value between 0 and 1 inclusively.
calculateAnglesproperty 
calculateAngles:Boolean

Boolean indicating if angles should be calculated and included in the Collision objects. Leaving it false will improve performance.

The default value is false.


Implementation
    public function get calculateAngles():Boolean
    public function set calculateAngles(value:Boolean):void
calculateOverlapproperty 
calculateOverlap:Boolean

Boolean indicating if the vector of overlapping points should be calculated and returned in the Collision objects. Leaving it false will improve performance.

The default value is false.


Implementation
    public function get calculateOverlap():Boolean
    public function set calculateOverlap(value:Boolean):void
debugproperty 
debug:Boolean

Since : 1.0a rev3

Enables/disables debug mode. When true, Airbag draws visual outlines inside the outlines property. The outlines property is a Sprite that can be added to the stage to visualize the detection process. This shouldn't be enabled in production.

The default value is false.


Implementation
    public function get debug():Boolean
    public function set debug(value:Boolean):void
ignoreInvisiblesproperty 
ignoreInvisibles:Boolean

Boolean indicating if objects whose visible property are false should be ignored by the detection process.

The default value is true.


Implementation
    public function get ignoreInvisibles():Boolean
    public function set ignoreInvisibles(value:Boolean):void
ignoreParentlessproperty 
ignoreParentless:Boolean

Boolean indicating if parentless objects (those who are not on the display list) should be ignored by the detection process. When set to true, objects that are not on stage will not cause collisions.

The default value is true.


Implementation
    public function get ignoreParentless():Boolean
    public function set ignoreParentless(value:Boolean):void
modeproperty 
mode:String  [read-only]

The detection mode currently in use. The value is MANY_TO_MANY when no singleTarget has been defined and ONE_TO_MANY otherwise.

The default value is MANY_TO_MANY.


Implementation
    public function get mode():String
numObjectsproperty 
numObjects:uint  [read-only]

The number of objects currently in the detection list. This number includes the singleTarget if it has been defined.


Implementation
    public function get numObjects():uint
outlinesproperty 
outlines:Sprite  [read-only]

Since : 1.0a rev3

A Sprite inside which debugging shapes are drawn to help visualise how AirBag tracks items and detects collisions. To view the debugging shapes, simply add this Sprite to the stage. This should not be used in production.

The default value is null.


Implementation
    public function get outlines():Sprite

Throws
IllegalOperationError — The 'debug' property must be 'true' to use the debugging outlines.
singleTargetproperty 
singleTarget:DisplayObject

A DisplayObject against which all collision detection will exclusively take place. Assigning a singleTarget changes the detection mode to ONE_TO_MANY detection. This means that collisions will only be checked if they involve the singleTarget. Other collisions amongst members of the detection list, will be ignored.

To unset the singleTarget and revert back to MANY_TO_MANY detection mode, simply assign null to the singleTarget property.


Implementation
    public function get singleTarget():DisplayObject
    public function set singleTarget(value:DisplayObject):void
skipproperty 
skip:uint

Since : 1.0a rev1

The number of frames to skip when performing detection. By default, AirBag performs collision detection for each ENTER_FRAME event. This can be changed by modifying the skip property. For example, if skip is set to 3, AirBag will perform detection on the first ENTER_FRAME event and skip the next 3 ENTER_FRAME events before performing detection again. This is useful if you want to use a different frame rate for your application and for collision detection.

The default value is 0.


Implementation
    public function get skip():uint
    public function set skip(value:uint):void
Constructor Detail
AirBag()Constructor
public function AirBag(... objects)

Creates an AirBag object from the DisplayObjects passed as parameters. The DisplayObjects to use can be specified by passing any of the following as parameters:

By default, collision detection works in a "many-to-many" relationship. That is, all objects will be checked against all other objects. Any collision found will be reported.

If a specific target is assigned by way of the singleTarget property, detection will work in a "one-to-many" relationship. This means that only collisions between the singleTarget and one of the objects in the list will be reported.

Parameters
... objects — A variable number of any of the following objects: Vector.<DisplayObject>, DisplayObject or Array of DisplayObjects.

Throws
ArgumentError — The parameters used to create an AirBag object must be of one of the following data types: Vector.<DisplayObject>, DisplayObject or Array.
Method Detail
add()method
public function add(... objects):void

Adds DisplayObjects to the detection list. Objects to add can be specified using any combination of the following data types: Vector.<DisplayObject>, DisplayObject or Array (of DisplayObjects).

Parameters

... objects — A variable number of any of the following objects: Vector.<DisplayObject>, DisplayObject or Array (of DisplayObjects).


Throws
ArgumentError — The add() method only accepts parameters of the following types: Vector.<DisplayObject>, DisplayObject or Array.
addColorToExclusionList()method 
public function addColorToExclusionList(color:uint, alphaRange:uint = 255, redRange:uint = 20, greenRange:uint = 20, blueRange:uint = 20):void

Adds a color to the color exclusion list. Pixels whose values are within the specified range will not trigger a collision.

Parameters

color:uint — The color to exclude
 
alphaRange:uint (default = 255)
 
redRange:uint (default = 20)
 
greenRange:uint (default = 20)
 
blueRange:uint (default = 20)

clear()method 
public function clear():void

Clears the detection list and removes any singleTarget that might have been assigned. Other settings such as alphaThreshold and excludeColor are not affected by this method.

detect()method 
public function detect():Vector.<Collision>

Since : 1.0a rev3 (previously called checkCollisions)

Performs the collision detection and returns a vector of Collision objects.

Returns
Vector.<Collision>

Throws
Error — The singleTarget must be on stage when ignoreParentless is true.
 
Error — The singleTarget must be visible when ignoreInvisibles is true.

See also

dispose()method 
public function dispose():void

Properly disposes of the object. You should always use dispose() instead of setting the object to null.

remove()method 
public function remove(... objects):void

Removes DisplayObjects from the detection list. Objects to remove can be specified using any combination of the following data types: Vector.<DisplayObject>, DisplayObject or Array (of DisplayObjects).

Parameters

... objects — A variable number of any of the following objects: Vector.<DisplayObject>, DisplayObject or Array of DisplayObjects.


Throws
ArgumentError — The remove() method only accepts parameters of the following types: Vector.<DisplayObject>, DisplayObject or Array.'
removeColorFromExclusionList()method 
public function removeColorFromExclusionList(theColor:uint):void

Removes a color from the color exclusion list.

Parameters

theColor:uint


Throws
ArgumentError — The color was not removed because it could not be found in the color exclusion list.
start()method 
public function start():void

Since : 1.0a rev1

Starts the automated collision detection process. On ENTER_FRAME, AirBag will check if any collisions happened and, if at least one was detected, it will dispatch a CollisionEvent object.

If you want to use a higher frame rate for your application than for collision detection, you can use the skip property.

Important: do not forget to call stop() when you are done with detection.

stop()method 
public function stop():void

Since : 1.0a rev1

Stops the automated collision detection process.

toString()method 
override public function toString():String

Returns a string representation of the object. Useful mostly for debugging purposes.

Returns
String
Event Detail
collision Event
Event Object Type: cc.cote.airbag.AirBagEvent
AirBagEvent.type property = cc.cote.airbag.AirBagEvent.COLLISION

Since : 1.0a rev1

Dispatched when AirBag detects at least one collision during its scheduled detection run.

The COLLISION constant defines the value of the type property of a collision event object.
detection Event  
Event Object Type: cc.cote.airbag.AirBagEvent
AirBagEvent.type property = cc.cote.airbag.AirBagEvent.DETECTION

Since : 1.0a rev1

Dispatched each time AirBag performs its detection routine. This typically is on each ENTER_FRAME but can be altered by the skip property.

The DETECTION constant defines the value of the type property of a detection event object.
Constant Detail
MANY_TO_MANYConstant
public static const MANY_TO_MANY:String = manyToMany

Constant defining a MANY_TO_MANY detection mode.

ONE_TO_MANYConstant 
public static const ONE_TO_MANY:String = oneToMany

Constant defining a ONE_TO_MANY detection mode.

VERSIONConstant 
public static const VERSION:String = 1.0a rev3

Current version of the library.