Package | cc.cote.airbag |
Class | public class AirBag |
Inheritance | AirBag ![]() |
AirBag
class allows the pixel-precise detection of collisions amongst
a list of DisplayObject
s (MovieClip
s, Sprite
s,
Bitmap
s, TextField
s, Video
s, 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
DisplayObject
s to the constructor or to the add()
method. Both the
constructor and the add()
method support any combination of the following
objects:
Vector.<DisplayObject>
DisplayObject
Array
of DisplayObject
sBy 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 DisplayObject
s 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
Property | Defined 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 |
Method | Defined 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 | ||
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 |
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 |
Constant | Defined 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 |
alphaThreshold | property |
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
.
public function get alphaThreshold():Number
public function set alphaThreshold(value:Number):void
RangeError The — alphaThreshold property expects a value between 0 and 1
inclusively.
|
calculateAngles | property |
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
.
public function get calculateAngles():Boolean
public function set calculateAngles(value:Boolean):void
calculateOverlap | property |
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
.
public function get calculateOverlap():Boolean
public function set calculateOverlap(value:Boolean):void
debug | property |
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
.
public function get debug():Boolean
public function set debug(value:Boolean):void
ignoreInvisibles | property |
ignoreInvisibles:Boolean
Boolean
indicating if objects whose visible
property are
false
should be ignored by the detection process.
The default value is true
.
public function get ignoreInvisibles():Boolean
public function set ignoreInvisibles(value:Boolean):void
ignoreParentless | property |
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
.
public function get ignoreParentless():Boolean
public function set ignoreParentless(value:Boolean):void
mode | property |
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
.
public function get mode():String
numObjects | property |
numObjects:uint
[read-only]
The number of objects currently in the detection list. This number includes the
singleTarget
if it has been defined.
public function get numObjects():uint
outlines | property |
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
.
public function get outlines():Sprite
IllegalOperationError — The 'debug' property must be 'true' to use the
debugging outlines.
|
singleTarget | property |
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.
public function get singleTarget():DisplayObject
public function set singleTarget(value:DisplayObject):void
skip | property |
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
.
public function get skip():uint
public function set skip(value:uint):void
AirBag | () | Constructor |
public function AirBag(... objects)
Creates an AirBag
object from the DisplayObject
s passed as
parameters. The DisplayObject
s to use can be specified by passing any of the
following as parameters:
Vector.<DisplayObject>
DisplayObject
Array
of DisplayObject
sBy 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.
... objects — A variable number of any of the following objects:
Vector.<DisplayObject>, DisplayObject or Array of
DisplayObjects.
|
ArgumentError — The parameters used to create an AirBag object must be of one of
the following data types: Vector.<DisplayObject>,
DisplayObject or Array.
|
add | () | method |
public function add(... objects):void
Adds DisplayObject
s to the detection list. Objects to add can be specified
using any combination of the following data types:
Vector.<DisplayObject>
, DisplayObject
or
Array
(of DisplayObject
s).
Parameters
... objects — A variable number of any of the following objects:
Vector.<DisplayObject> ,
DisplayObject or Array (of
DisplayObject s).
|
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.
Vector.<Collision> |
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 DisplayObject
s).
Parameters
... objects — A variable number of any of the following objects:
Vector.<DisplayObject>, DisplayObject or Array of
DisplayObjects.
|
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 |
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.
ReturnsString |
collision | Event |
cc.cote.airbag.AirBagEvent
cc.cote.airbag.AirBagEvent.COLLISION
Since : | 1.0a rev1 |
Dispatched when AirBag
detects at least one collision during its scheduled
detection run.
COLLISION
constant defines the value of the type
property
of a collision
event object.
detection | Event |
cc.cote.airbag.AirBagEvent
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.
DETECTION
constant defines the value of the type
property
of a detection
event object.
MANY_TO_MANY | Constant |
public static const MANY_TO_MANY:String = manyToMany
Constant defining a MANY_TO_MANY detection mode.
ONE_TO_MANY | Constant |
public static const ONE_TO_MANY:String = oneToMany
Constant defining a ONE_TO_MANY detection mode.
VERSION | Constant |
public static const VERSION:String = 1.0a rev3
Current version of the library.