QuickBox2D

Kind of class:public class
Package:com.actionsnippet.qbox
Inherits from:EventDispatcher
Version:1.1
Author:Zevan Rosser
Classpath:com.actionsnippet.qbox.QuickBox2D
File last modified:Saturday, 07 November 2009, 12:25:26
In order to make use of this library you'll need to instantiate a QuickBox2D instance.

What does the QuickBox2D class do?
It instantiates the main classes that Box2D needs to run (b2World and b2AABB).
It manages the Box2D simulation via start() and stop() methods.
It contains methods for creating rigid bodies and joints - such as addCircle(), addBox() and addPoly()
It contains a few additional methods for debugging and mouse interaction.
Events broadcasted to listeners:
  • Event with type: STEP - dispatched whenever a world timeStep occurs. This can be more than once per frame if framerate independent motion is on (frim).
  • Event with type: render - dispatched at the end of QuickBox2D's internal enterframe event.

Summary


Constructor
  • QuickBox2D (main:MovieClip, params:Object = null)
    • Creates a new QuickBox2D instance.
Class properties
  • STEP : String
    • Constant value for use with the QuickBox2D step event
  • DISTANCE : String
    • Constant value "distance" joint type
  • REVOLUTE : String
    • Constant value "revolute" joint type
  • PRISMATIC : String
    • Constant value "prismatic" joint type
  • GEAR : String
    • Constant value "gear" joint type
  • PULLEY : String
    • Constant value "pulley" joint type
Instance properties
  • worldAABB : b2AABB
    • The Box2D b2AABB instance.
  • gravity (v:b2Vec2) : b2Vec2
    • The world gravity vector.
  • w : b2World
    • The Box2D b2World instance.
  • iterations : int
    • The Box2D iterations.
  • timeStep : Number
    • The Box2D time step.
  • main : MovieClip
    • The MovieClip containing the Box2D world.
  • frim : Boolean
    • Toggles FRIM (frame rate independent movement).
  • totalTimeSteps : int
    • This value is incremented every time a time step occurs.
Instance methods
  • grid (size:int = 30, lineColor:uint = 0xFFFF00, lineAlpha:Number = 1) : void
    • Draws a grid for testing/debugging purposes only.
  • createStageWalls (params:Object = null) : void
    • Draws boxes on each side of the stage.
  • traceMouse : void
    • Causes the mouse location (in meters) to be traced to the output window when the stage is clicked.
  • mouseDrag : void
    • Turns on mouse dragging for all non-static (dynamic) rigid bodies.
  • destroy : void
    • Removes all event listeners within the QuickBox2D instance.
  • start : void
    • Starts the Box2D simulation.
  • stop : void
    • Stops the Box2D simulation.
  • addContactListener : QuickContacts
    • Enables all contact listener events.
  • addTimeStepSequence (sequence:Array) : void
    • This method is used for creating a sequence of function calls based on the QuickBox2D totalTimeSteps value.
  • updateBodies : void
  • addPoly (params:Object) : QuickObject
    • Adds a polygon to the world.
  • addBox (params:Object) : QuickObject
    • Adds a box to the world.
  • addCircle (params:Object) : QuickObject
    • Adds a circle to the world.
  • addJoint (params:Object) : QuickObject
    • Adds a joint to the world.
  • addGroup (params:Object) : QuickObject
    • Creates a group out of existing QuickObject instances.
  • create (type:String, params:Object) : QuickObject
    • Can create any type of QuickObject.
  • setDefault (params:Object = null) : void
    • Sets some default params for all QuickObjects.
  • setMouse (xp:Number, yp:Number) : void
    • Use this method for passing in custom mouse coordinates for mouseDrag.
  • updateMouse : void
  • createMouse (evt:MouseEvent) : void

Constructor

QuickBox2D

public function QuickBox2D (
main:MovieClip, params:Object = null)

Creates a new QuickBox2D instance.
Parameters:
main :
The MovieClip to render the Box2D world into.
params:
An Object containing settings for QuickBox2D and the Box2D world. See below for details.

All params Object Properties:
debug:: false - If set to true, QuickBox2D will use the Box2D debug renderer to draw the world.
gravityX : 0 - The x component of the gravity vector for the Box2D world.
gravityY: 20 - The y component of the gravity vector for the Box2D world.
timeStep: 1 / 60 - The Box2D time step.
iterations: 20 - The Box2D iterations.
frim: true - Toggles FRIM (frame rate independent movement).
bounds: [-100, -100, 100, 100] - Defines the bounding box for the Box2D world.
renderJoints: true - Toggles the rendering of joints for the simple renderer.
simpleRender: true - Toggles the QuickBox2D simple renderer. Set this to false if you don’t want to utilize any of the QuickBox2D rigid body skinning.
customMouse false - Toggles the ability for custom mouse coordinates to be passed in via the setMouse. This can be useful if your using QuickBox2D with a 3D engine.

Class properties

DISTANCE

public static DISTANCE:String = "distance"
(read,write)

Constant value "distance" joint type

GEAR

public static GEAR:String = "gear"
(read,write)

Constant value "gear" joint type

PRISMATIC

public static PRISMATIC:String = "prismatic"
(read,write)

Constant value "prismatic" joint type

PULLEY

public static PULLEY:String = "pulley"
(read,write)

Constant value "pulley" joint type

REVOLUTE

public static REVOLUTE:String = "revolute"
(read,write)

Constant value "revolute" joint type

STEP

public static STEP:String = "step"
(read,write)

Constant value for use with the QuickBox2D step event

Instance properties

frim

public frim:Boolean
(read,write)

Toggles FRIM (frame rate independent movement). By default this is set to true. Turning it off will cause the stage.frameRate (the frame rate of the swf) to effect the speed of the Box2D simulation.

gravity

public gravity:b2Vec2
(read,write)

The world gravity vector. This can be changed during runtime.

iterations

public iterations:int = 20
(read,write)

The Box2D iterations. This effects the accuracy of the simulation, lower values will be less CPU intensive and less accurate, higher values will be more CPU intensive and more accurate.

main

public main:MovieClip
(read,write)

The MovieClip containing the Box2D world.

timeStep

public timeStep:Number = 1 / 60.0
(read,write)

The Box2D time step. The default is 1 / 60.0 - for simplicity it is not recommended that you change this value

totalTimeSteps

public totalTimeSteps:int = 0
(read,write)

This value is incremented every time a time step occurs. This is very useful for having event occur in your simulation at a specific time. If frim is on this value will be framerate independent. For more info see addTimeStepSequence

w

public w:b2World
(read,write)

The Box2D b2World instance.

worldAABB

public worldAABB:b2AABB
(read,write)

The Box2D b2AABB instance.

Instance methods

addBox

public function addBox (
params:Object) : QuickObject

Adds a box to the world.
Parameters:
params:
An Object containing properties that describe all aspects of the box. See below for a full list of valid properties.
Nearly all of these properties come straight from the Box2D b2ShapeDef and b2BodyDef (and subclasses). QuickBox2D puts them all in one place for easy rigid body instantiation.

Common Properties:
x: 3.0 - The x location in meters.
y: 3.0 - The y location in meters.
width: 1.0 - The width in meters.
height: 1.0 - The height in meters.
angle: 0.0 - The angle in radians.
draggable: true - Enable or disable dragging if the mouseDrag method has been called.

Rendering Properties: (These are used with QuickBox2D's simpleRenderer)
skin: null - Set this to the name of a linkage class from your library if you'd like to use a graphics created in flash for your rigid body skin.

The following properties will not do anything if you have set the skin property or if you have set simpleRender to false.
lineColor: 0x000000 - Line color.
lineAlpha: 1.0 - Line alpha.
lineThickness: 0.0 - Line thickness.
fillColor: 0xCCCCCC - Fill color.
fillAlpha: 1.0 - Fill alpha.

Additional Properties:
density: 1.0 - The density in kg/m^2.
friction: 0.5 - The friction coefficient. Normally ranges from 0 - 1.
restitution: 0.2 - The restitution of the rigid body. This is like elasticity or bounciness. Normally ranges from 0 - 1.
linearDamping: 0.0 - Linear damping.
angularDamping: 0.0 - Angular damping.
isBullet: false - uses CCD (continuous collision detection) to prevent fast moving object from moving through other objects.
fixedRotation: false - If set to true the rigid body will not rotate.
allowSleep: true - If set to false the rigid body will never sleep.
isSleeping: false - If set to true the rigid body will start off sleeping. This can be useful for creating breakable objects.
mass: - The mass of the rigid body. This is usually set automatically - setting it on polygons may cause unexpected results.
maskBits: - 0xFFFF - Collision mask bits. See Box2D manual for a description of this http://www.box2d.org/manual.html#d0e845
categoryBits: 1 - Category bits. See Box2D manual for a description of this http://www.box2d.org/manual.html#d0e845
groupIndex: 0 - Group index.See Box2D manual for a description of this http://www.box2d.org/manual.html#d0e845
Returns:

addCircle

public function addCircle (
params:Object) : QuickObject

Adds a circle to the world.
Parameters:
params:
An Object containing properties that describe all aspects of the circle. See below for a full list of valid properties.
Nearly all of these properties come straight from the Box2D b2ShapeDef and b2BodyDef (and subclasses). QuickBox2D puts them all in one place for easy rigid body instantiation.

Common Properties:
x: 3.0 - The x location in meters.
y: 3.0 - The x location in meters.
radius: 1.0 - The radius in meters.
angle: 0.0 - The angle in radians.
draggable: true - Enable or disable dragging if the mouseDrag method has been called.

Rendering Properties: (These are used with QuickBox2D's simpleRenderer)
skin: null - Set this to the name of a linkage class from your library if you'd like to use a graphics created in flash for your rigid body skin.

The following properties will not do anything if you have set the skin property or if you have set simpleRender to false.
lineColor: 0x000000 - Line color.
lineAlpha: 1.0 - Line alpha.
lineThickness: 0.0 - Line thickness.
fillColor: 0xCCCCCC - Fill color.
fillAlpha: 1.0 - Fill alpha.

Additional Properties:
density: 1.0 - The density in kg/m^2.
friction: 0.5 - The friction coefficient. Normally ranges from 0 - 1.
restitution: 0.2 - The restitution of the rigid body. This is like elasticity or bounciness. Normally ranges from 0 - 1.
linearDamping: 0.0 - Linear damping.
angularDamping: 0.0 - Angular damping.
isBullet: false - uses CCD (continuous collision detection) to prevent fast moving object from moving through other objects.
fixedRotation: false - If set to true the rigid body will not rotate.
allowSleep: true - If set to false the rigid body will never sleep.
isSleeping: false - If set to true the rigid body will start off sleeping. This can be useful for creating breakable objects.
mass: - The mass of the rigid body. This is usually set automatically - setting it on polygons may cause unexpected results.
maskBits: - 0xFFFF - Collision mask bits. See Box2D manual for a description of this http://www.box2d.org/manual.html#d0e845
categoryBits: 1 - Category bits. See Box2D manual for a description of this http://www.box2d.org/manual.html#d0e845
groupIndex: 0 - Group index.See Box2D manual for a description of this http://www.box2d.org/manual.html#d0e845
Returns:

addContactListener

public function addContactListener (
) : QuickContacts

Enables all contact listener events. This is used for advanced collision. Returns an instance of QuickContacts (QuickBox2D's b2ContactListener). You should store a reference to this, add desired listeners, read desired properties and call desired methods. For more info see QuickContacts.

addGroup

public function addGroup (
params:Object) : QuickObject

Creates a group out of existing QuickObject instances. This is usually reffered to as a compound shape.
Parameters:
params:
An Object containing properties that describe all aspects of the group. See below for a full list of valid properties.
Nearly all of these properties come straight from the Box2D b2ShapeDef and b2BodyDef (and subclasses). QuickBox2D puts them all in one place for easy rigid body instantiation.

Common Properties:
x: 3.0 - The x location in meters.
y: 3.0 - The y location in meters.
objects: null - An array of QuickObject instances to group together.
angle: 0.0 - The angle in radians.
draggable: true - Enable or disable dragging if the mouseDrag method has been called.

Rendering Properties: (These are used with QuickBox2D's simpleRenderer)
skin: null - Set this to the name of a linkage class from your library if you'd like to use a graphics created in flash for your rigid body skin. This can also be set to a DisplayObject instance on the stage - currently boxes and circles x,y and angle values are reset based on the DisplayObject instance's x,y and rotation properties.

Additional Properties:
linearDamping: 0.0 - Linear damping.
angularDamping: 0.0 - Angular damping.
isBullet: false - uses CCD (continuous collision detection) to prevent fast moving object from moving through other objects.
fixedRotation: false - If set to true the rigid body will not rotate.
allowSleep: true - If set to false the rigid body will never sleep.
isSleeping: false - If set to true the rigid body will start off sleeping. This can be useful for creating breakable objects.
Returns:

addJoint

public function addJoint (
params:Object) : QuickObject

Adds a joint to the world.
Parameters:
params:
An Object containing properties that describe all aspects of the joint. See below for a full list of valid properties
Common Properties:
a: null - A QuickObject.body property to attach one end of the joint to.
b: null - A QuickObject.body property to attach the other end of the joint to.
if the below propertyes (x1, y1, x2, y2) are not set they will be calculated based on the center points of a and b.
x1: null - The x location for the end of the joint anchored to body a.
y1: null - The y location for the end of the joint anchored to body a.
x2: null - The x location for the end of the joint anchored to body b.
y2: null - The y location for the end of the joint anchored to body b.

Rendering Properties: (These are used with QuickBox2D's simpleRenderer)
skin: null - Set this to the name of a
linkage class from your library if you'd like to use a graphics created in flash for your joint. This class must be dynamic.
If you are trying to use a Sprite here, just use a MovieClip instead. Currently DisplayObject/Class skins only work for b2DistanceJoints.

The following properties will not do anything if you have set the skin property or if you have set simpleRender to false.
lineColor: 0x000000 - Line color.
lineAlpha: 1.0 - Line alpha.
lineThickness: 0.0 - Line thickness.

Properties for all joints:
type: - The type of joint, either distance, prismatic, revolute, pulley or gear.
collideConnected: true - If set to false, the two bodies attached to this joint will not collide.

Properties for distance joints:
frequencyHz: 0 - The response speed. Using numbers above zero will cause the joint to act more like a rubber band.
dampingRatio: 0 - The damping ratio. 0 = no damping, 1 = critical damping.
length: 0 - The equilibrium length between the anchor points. If not set, this will automatically be calculated based on the distance between (x1, y1) and (x2, y2).

Properties for some joints (revolute, prismatic)
enableLimit false - Enable joint limits (constraints on angle and translation).
enableMotor: false - Toggle joint motor.
motorSpeed: 0 - Set motor speed
referenceAngle 0 - p.referenceAngle;

Properties for revolute joints:

upperAngle: 0 - p.upperAngle;
lowerAngle: 0 - p.lowerAngle;
maxMotorTorque: 0 - p.maxMotorTorque;

Properties for prismatic joints:
axis: null - Axis b2Vec2, must be set.
anchor: null - Anchor b2Vec2, must be set.
upperTranslation: 0 - Upper limit b2Vec2 in local coordinates.
lowerTranslation: 0 - Upper limit b2Vec2 in local coordinates.
maxMotorForce: 0 - Max force for motor.

Properties for pulley joints:
groundAnchor1: (0,a.x) - Ground anchor for body a b2Vec2;
groundAnchor2: (0,b.x) - Ground anchor for body b b2Vec2;
anchor1: (a.x, b.x) - Anchor for body a;
anchor2: (a.x, b.x) - Anchor for body b;
ratio: 1 - This causes one side of the pulley to extend faster than the other when not set to 1.

Properties for gear joints:
joint1: null - Either revolute or prismatic joint tied to the groundBody and a, must be set.
joint2: null - Either revolute or prismatic joint tied to the groundBody and b, must be set.
ratio: 1 - This causes one of the gears to move more/less than the other when not set to 1.
Returns:

addPoly

public function addPoly (
params:Object) : QuickObject

Adds a polygon to the world.
Parameters:
params:
An Object containing properties that describe all aspects of the polygon. See below for a full list of valid properties.
Nearly all of these properties come straight from the Box2D b2ShapeDef and b2BodyDef (and subclasses). QuickBox2D puts them all in one place for easy rigid body instantiation.

Common Properties:
x: 3.0 - The x location in meters.
y: 3.0 - The y location in meters.
points: null - An array describing the contour of the polygon. QuickBox2D will triangulate the verts array automatically if this property is set.
verts: [[-.5, -1, 1, -1, 1, 1, -1, 1]] - A two dimensional array of vertices describing the polygon.

angle: 0.0 - The angle in radians.
draggable: true - Enable or disable dragging if the mouseDrag method has been called.

Rendering Properties: (These are used with QuickBox2D's simpleRenderer)
skin: null - Set this to the name of a linkage class from your library if you'd like to use a graphics created in flash for your rigid body skin.

The following properties will not do anything if you have set the skin property or if you have set simpleRender to false.
lineColor: 0x000000 - Line color.
lineAlpha: 1.0 - Line alpha.
lineThickness: 0.0 - Line thickness.
fillColor: 0xCCCCCC - Fill color.
fillAlpha: 1.0 - Fill alpha.

Additional Properties:
density: 1.0 - The density in kg/m^2.
friction: 0.5 - The friction coefficient. Normally ranges from 0 - 1.
restitution: 0.2 - The restitution of the rigid body. This is like elasticity or bounciness. Normally ranges from 0 - 1.
linearDamping: 0.0 - Linear damping.
angularDamping: 0.0 - Angular damping.
isBullet: false - uses CCD (continuous collision detection) to prevent fast moving object from moving through other objects.
fixedRotation: false - If set to true the rigid body will not rotate.
allowSleep: true - If set to false the rigid body will never sleep.
isSleeping: false - If set to true the rigid body will start off sleeping. This can be useful for creating breakable objects.
mass: - The mass of the rigid body. This is usually set automatically - setting it on polygons may cause unexpected results.
maskBits: - 0xFFFF - Collision mask bits. See Box2D manual for a description of this http://www.box2d.org/manual.html#d0e845
categoryBits: 1 - Category bits. See Box2D manual for a description of this http://www.box2d.org/manual.html#d0e845
groupIndex: 0 - Group index.See Box2D manual for a description of this http://www.box2d.org/manual.html#d0e845
Returns:

addTimeStepSequence

public function addTimeStepSequence (
sequence:Array) : void

This method is used for creating a sequence of function calls based on the QuickBox2D totalTimeSteps value. If frim is on, totalTimeSteps is framerate independent.
This method takes a variable number of Objects as its arguments. Each Object should be set up as follows:
time: - When to call the callback function.
callback: - The function to call when totalTimeSteps is equal to this Object's time property.
args: - An optional array of arguments to pass to the callback function.

create

public function create (
type:String, params:Object) : QuickObject

Can create any type of QuickObject.
Parameters:
type:
The type of QuickObject to create, either "box", "circle", "poly" or "joint".
For a list of possible params see any of the below methods:
addBox
addCircle
addPoly
addJoint
Returns:

createMouse

public function createMouse (
evt:MouseEvent) : void

createStageWalls

public function createStageWalls (
params:Object = null) : void

Draws boxes on each side of the stage.
params:
  • The params Object for all four boxes. See the addBox method for list of valid Object properties.

destroy

public function destroy (
) : void

Removes all event listeners within the QuickBox2D instance. This should only be called if you know your application will not be using this instance again.

grid

public function grid (
size:int = 30, lineColor:uint = 0xFFFF00, lineAlpha:Number = 1) : void

Draws a grid for testing/debugging purposes only.
Parameters:
size :
The width and height of the grid squares. The default size is 30 because with QuickBox2D default settings 30 pixels = 1 meter.
lineColor:
The line color.
lineAlpha:
The line alpha.

mouseDrag

public function mouseDrag (
) : void

Turns on mouse dragging for all non-static (dynamic) rigid bodies.

setDefault

public function setDefault (
params:Object = null) : void

Sets some default params for all QuickObjects. This can be useful for setting default rendering styles - but can contain any default properties for
any type of object - box, circle, poly or joint.
Parameters:
params:
For a full list of possible params see any of the below methods:
addBox
addCircle
addPoly
addJoint

setMouse

public function setMouse (
xp:Number, yp:Number) : void

Use this method for passing in custom mouse coordinates for mouseDrag. This can be useful if your using QuickBox2D with a 3D engine. You must call this method every time you wish to update the position of the mouse joint.

start

public function start (
) : void

Starts the Box2D simulation.

stop

public function stop (
) : void

Stops the Box2D simulation.

traceMouse

public function traceMouse (
) : void

Causes the mouse location (in meters) to be traced to the output window when the stage is clicked.

updateBodies

public function updateBodies (
) : void

updateMouse

public function updateMouse (
) : void