Box2D

In this manual it is assumed you are familiar with basic physics concepts, such as mass, force, torque, and impulses. If not, please first consult the many tutorials provided by Chris Hecker and David Baraff (google these names). You do not need to understand their tutorials in great detail, but they do a good job of laying out the basic concepts that will help you use Box2D.

Wikipedia is also an excellent source of physics and mathematics knowledge. In some ways it is more useful than Google, because it has carefully crafted content.

This is not a prerequisite, but if you are curious about the about the inner workings of Box2D, you can look at these articles .

Box2D works with several fundamental objects. We briefly define these objects here and more details are given later in this document.

Every Box2D program begins with the creation of a world object. This is the physics hub that manages memory, objects, and simulation.

To create a world object, first we need to define a bounding box for the world. Box2D uses the bounding box to accelerate collision detection. The size isn't critical, but a better fit will improve performance. It is better to make the box too big than to make it too small.

Local worldAABB:b2AABB = New b2AABB
worldAABB.SetLowerBound(-100.0, -100.0)
worldAABB.SetUpperBound(100.0, 100.0)
		

Next we define the gravity vector. Yes, you can make gravity go sideways (or you could just rotate your monitor). Also we tell the world to allow bodies to sleep when they come to rest. A sleeping body doesn't require any simulation.

Local gravity:b2Vec2 = New b2Vec2.Create(0.0, -10.0)
Local doSleep:int = true
		

Now we create the world object. Normally you would create the world on the heap and store the pointer in one of your game structures. However, creating the world on the stack works fine in this example.

Local world:b2World = New b2World.Create(worldAABB, gravity, doSleep)
		

So now we have our physics world, let's start adding some stuff to it.

Bodies are built using the following steps:

For step 1 we create the ground body. For this we need a body definition . With the body definition we specify the initial position of the ground body.

Local groundBodyDef:b2BodyDef = New b2BodyDef
groundBodyDef.SetPositionXY(0.0, -10.0)
		

For step 2 the body definition is passed to the world object to create the ground body. The world object does not keep a reference to the body definition. The ground body is created as a static body. Static bodies don't collide with other static bodies and are immovable. Box2D determines that a body is static when it has zero mass. Bodies have zero mass by default, therefore they are static by default.

Local groundBody:b2Body = world.CreateBody(groundBodyDef)
		

For step 3 we create a ground polygon definition. We use the SetAsBox shortcut to form the ground polygon into a box shape, with the box centered on the origin of the parent body.

Local groundShapeDef:b2PolygonDef = New b2PolygonDef
groundShapeDef.SetAsBox(50.0, 10.0)
		

The SetAsBox function takes the half-width and half-height. So in this case the ground box is 100 units wide (x-axis) and 20 units tall (y-axis). Box2D is tuned for meters, kilograms, and seconds. So you can consider the extents to be in meters. However, it is possible to change unit systems, as discussed later in this document

We finish the ground body in step 4 by creating the ground polygon shape on the ground body.

groundBody.CreateShape(groundShapeDef)
		

Again, Box2D does not keep a reference to the shape or body definitions. It copies the data into the b2Body structure.

Note that every shape must have a parent body, even shapes that are static. However, you can attach all static shapes to a single static body. This need for static bodies is done to make the Box2D code more uniform internally, reducing the number of potential bugs.

You might notice a pattern here. Most Box2D types are prefixed with b2 . This is done to reduce the chance for naming conflicts with your code.

So now we have a ground body. We can use the same technique to create a dynamic body. The main difference, besides dimensions, is that we must establish the dynamic body's mass properties.

First we create the body using CreateBody .

Local bodyDef:b2BodyDef = new b2BodyDef
bodyDef.SetPositionXY(0.0, 4.0)
Local body:b2Body = world.CreateBody(bodyDef)
		

Next we create and attach a polygon shape. Notice that we set density to 1. The default density is zero. Also, the friction on the shape is set to 0.3. Once the shape is attached, we instruct the body to compute it's mass properties from the attached shapes using the method SetMassFromShapes . This gives you a hint that you can attach more than one shape per body. If the computed mass is zero, then the body becomes truly static. Bodies have a mass of zero by default, that's why we didn't need to call SetMassFromShapes for the ground body.

Local shapeDef:b2PolygonDef = New b2PolygonDef
shapeDef.SetAsBox(1.0, 1.0)
shapeDef.SetDensity(1.0)
shapeDef.SetFriction(0.3)
body.CreateShape(shapeDef)
body.SetMassFromShapes()
		

That's it for initialization. We are now ready to begin simulating.

So we have initialized the ground box and a dynamic box. Now we are ready to set Newton loose to do his thing. We just have a couple more issues to consider.

Box2D uses a bit of numerical code called an integrator . Integrators simulate the physics equations at discrete points of time. This goes along with the traditional game loop where we essentially have a flip book of movement on the screen. So we need to pick a time step for Box2D. Generally physics engines for games like a time step at least as fast as 60Hz or 1/60 seconds. You can get away with larger time steps, but you will have to be more careful about setting up the definitions for your world. We also don't like the time step to change much. So don't tie the time step to your frame rate (unless you really, really have to). Without further ado, here is the time step.

Local timeStep:Float = 1.0 / 60.0
		

In addition to the integrator, Box2D also uses a larger bit of code called a constraint solver. The constraint solver solves all the constraints in the simulation, one at a time. A single constraint can be solved perfectly. However, when we solve one constraint, we slightly disrupt other constraints. To get a good solution, we need to iterate over all constraints a number of times.

There are two phases in the constraint solver: a velocity phase and a position phase. In the velocity phase the solver computes the impulses necessary for the bodies to move correctly. In the position phase the solver adjusts the positions of the bodies to reduce overlap and joint detachment. Each phase has its own iteration count. In addition, the position phase will exit iteraions early if the errors are small.

The suggested iteration count for Box2D is 10 for both velocity and position. You can tune this number to your liking, just keep in mind that this has a trade-off between speed and accuracy. Using fewer iterations increases performance but accuracy suffers. Likewise, using more iterations decreases performance but improves the quality of your simulation. For this simple example, we don't need many iterations. Here are our chosen iteration counts.

Local velocityIterations:Int = 8
Local positionIterations:Int = 1
		

Note that the time step and the iteration count are completely unrelated. An iteration is not a sub-step. One iteration is a single pass over all the constraints withing a time step. You can have multiple passes over the constraints within a single time step.

We are now ready to begin the simulation loop. In your game the simulation loop can be merged with your game loop. In each pass through your game loop you call b2World::Step. Just one call is usually enough, depending on your frame rate and your physics time step.

The Hello World program was designed to be dead simple, so it has no graphical output. Rather that being utterly boring by producing no output, the code prints out the position and rotation of the dynamic body. Yay! Here is the simulation loop that simulates 60 time steps for a total of 1 second of simulated time.

For Local i:Int = 0 Until 60
	world.DoStep(timeStep, velocityIterations, positionIterations)
	Local position:b2Vec2 = body.GetPosition()
	Local angle:Float = body.GetAngle()
	Print position.X() + " " + position.Y() + " " + angle
Next
		

When a world leaves scope or is deleted by calling delete on a pointer, all the memory reserved for bodies and joints is freed. This is done to make your life easier. However, you will need to nullify any body, shape, or joint pointers you have because they will become invalid.

Once you have conquered the HelloWorld example, you should start looking at Box2D's examples.

The testbed has many examples of Box2D usage in the test cases and the framework itself. I encourage you to explore and tinker with the testbed as you learn Box2D.

A large number of the decisions about the design of Box2D were based on the need for quick and efficient use of memory. In this section I will discuss how and why Box2D allocates memory.

Box2D tends to allocate a large number of small objects (around 50-300 bytes). Using the system heap through malloc or new for small objects is inefficient and can cause fragmentation. Many of these small objects may have a short life span, such as contacts, but can persist for several time steps. So we need an allocator that can efficiently provide heap memory for these objects.

Box2D's solution is to use a small object allocator (SOA). The SOA keeps a number of growable pools of varying sizes. When a request is made for memory, the SOA returns a block of memory that best fits the requested size. When a block is freed, it is returned to the pool. Both of these operations are fast and cause little heap traffic.

Since Box2D uses a SOA, you should never new or malloc a body, shape, or joint. You do have to allocate a b2World. The b2World class provides factories for you to create bodies, shapes, and joints. This allows Box2D to use the SOA and hide the gory details from you. Never, ever, call delete or free on a body, shape, or joint.

While executing a time step, Box2D needs some temporary workspace memory. For this, it uses a stack allocator to avoid per-step heap allocations. You don't need to interact with the stack allocator, but it's good to know it's there.

As mentioned above, memory management plays a central role in the design of the Box2D API. So when you create a b2Body or a b2Joint , you need to call the factory methods on b2World .

There are creation methods:

Method CreateBody:b2Body(def:b2BodyDef)
Method CreateJoint:b2Joint(def:b2JointDef)
		

And there are corresponding destruction methods:

Method DestroyBody(body:b2Body)
Method DestroyJoint(joint:b2Joint)
		

When you create a body or joint, you need to provide a definition or def for short. These definitions contain all the information needed to build the body or joint. By using this approach we can prevent construction errors, keep the number of function parameters small, provide sensible defaults, and reduce the number of accessors.

Since shapes musted be parented to a body, they are created and destroyed using a factory method on b2Body :

Method CreateShape:b2Shape(def:b2ShapeDef)
Method DestroyShape(shape:b2Shape)
		

Factories do not retain references to the definitions. So you can create and re-use definitions and keep them in temporary resources.

Box2D works with floating point numbers, so some tolerances have to be used to make Box2D perform well. These tolerance have been tuned to work well with meters-kilogram-second (MKS) units. In particular, Box2D has been tuned to work well with moving objects between 0.1 and 10 meters. So this means objects between soup cans and buses in size should work well.

Being a 2D physics engine it is tempting to use pixels as your units. Unfortunately this will lead to a poor simulation and possibly weird behavior. An object of length 200 pixels would be seen by Box2D as the size of a 45 story building. Imagine trying to simulate the movement of a high-rise building with an engine that is tuned to simulate ragdolls and barrels. It isn't pretty.

The b2Shape , b2Body , and b2Joint classes allow you to attach user data as a void pointer. This is handy when you are examining Box2D data structures and you want to determine how they relate to the data structures in your game engine.

For example, it is typical to attach an actor pointer to the rigid body on that actor. This sets up a circular reference. If you have the actor, you can get the body. If you have the body, you can get the actor.

Local actor:GameActor = GameCreateActor()
Local bodyDef:b2BodyDef = new b2BodyDef
bodyDef.SetUserData(actor)
actor.body = box2Dworld.CreateBody(bodyDef)
		

Here are some examples of cases where you would need the user data:

Keep in mind that user data is optional and you can put anything in it. However, you should be consistent. For example, if you want to store an actor pointer on one body, you should keep an actor pointer on all bodies. Don't store an actor pointer on one body, and a foo pointer on another body. This will likely lead to a crash if you try to cast an actor pointer into a foo pointer.

If you don't like this API design, that's ok! You have the source code! Seriously, if you have feedback about anything related to Box2D, please leave a comment in the forum .

The b2World class contains the bodies and joints. It manages all aspects of the simulation and allows for asynchronous queries (like AABB queries). Much of your interactions with Box2D will be with a b2World object.

Creating a world is fairly simple. You need to provide a bounding box and a gravity vector.

The axis-aligned bounding box should encapsulate the world. You can improve performance by making the bounding box a bit bigger than your world, say 2x just to be safe. If you have lots of bodies that fall into the abyss, your should detect this and remove the bodies. This will improve performance and prevent floating point overflow.

To create and destory a world you need to use Create and Free .

Local myWorld:b2World = new b2World.Create(aabb, gravity, doSleep);
... do stuff ...
myWorld.Free()
		

The world class contains factories for creating and destroying bodies and joints. These factories are discussed later in the sections on bodies and joints. There are some other interactions with b2World that I will cover now.

Local timeStep:Float = 1.0 / 60.0
Local iterationCount:Int = 10
myWorld.DoStep(timeStep, iterationCount)
			

Local b:b2Body = myWorld.GetBodyList()
While b
	b.WakeUp()
	b = b.GetNext()
Wend
			

Local b:b2Body = myWorld.GetBodyList()
While b
	Local myActor:GameActor = GameActor(b.GetUserData())
	If myActor.IsDead() Then
		myWorld.DestroyBody(b) ' ERROR: now GetNext returns garbage.
	End If
	b = b.GetNext()
Wend
			

Local node:b2Body = myWorld.GetBodyList()
While (node)
	Local b:b2Body = node
	node = node.GetNext()

	Local myActor:GameActor = GameActor(b.GetUserData())
	If myActor.IsDead() Then
		myWorld.DestroyBody(b)
	End If
Wend
			

Local node:b2Body = myWorld.GetBodyList()
While node
	Local b:b2Body = node
	node = node.GetNext()

	Local myActor:GameActor = GameActor(b.GetUserData())
	If myActor.IsDead() Then
		Local otherBodiesDestroyed:Int = GameCrazyBodyDestroyer(b)
		If otherBodiesDestroyed Then
			node = myWorld.GetBodyList()
		End If
	End If
Wend
			

Local aabb:b2AABB = new b2AABB
aabb.SetLowerBound(-1.0, -1.0)
aabb.SetUpperBound(1.0, 1.0)
Local k_bufferSize:Int = 10
Local buffer:b2Shape[] = New b2Shape[k_bufferSize]
Local count:Int = myWorld.Query(aabb, buffer)
For Local i:Int = 0 Until count
	buffer[i].GetBody().WakeUp()
Next
			

Bodies have position and velocity. You can apply forces, torques, and impulses to bodies. Bodies can be static or dynamic. Static bodies never move and don't collide with other static bodies.

Bodies are the backbone for shapes. Bodies carry shapes and move them around in the world. Bodies are always rigid bodies in Box2D. That means that two shapes attached to the same rigid body never move relative to each other.

You usually keep references to all the bodies you create. This way you can query the body positions to update the positions of your graphical entities. You should also keep body references so you can destroy them when you are done with them.

Before a body is created you must create a body definition ( b2BodyDef ). You can create a body definition on the stack or build it into your game's data structures. The choice is up to you.

Box2D copies the data out of the body definition, it does not keep a pointer to the body definition. This means you can recycle a body definition to create multiple bodies.

Lets go over some of the key members of the body definition.

bodyDef.GetMassData().SetMass(2.0) ' the body's mass in kg
bodyDef.SetCenter(b2Vec2.ZERO)     ' the center of mass in local coordinates
bodyDef.SetRotationalInertia(3.0)  ' the rotational inertia in kg*m^2.
			

bodyDef.SetPositionXY(0.0, 2.0) ' the body's origin position
bodyDef.SetAngle(45)            ' the body's angle in degrees.
			

bodyDef.SetLinearDamping(0.0)
bodyDef.SetAngularDamping(0.01)
			

bodyDef.SetAllowSleep(True)
bodyDef.SetIsSleeping(False)
			

bodyDef.SetIsBullet(True)

Bodies are created and destroyed using a body factory provided by the world class. This lets the world create the body with an efficient allocator and add the body to the world data structure.

Bodies can be dynamic or static depending on the mass properties. Both body types use the same creation and destruction methods.

Local dynamicBody:b2Body = myWorld.CreateBody(bodyDef)
... do stuff ... 
myWorld.DestroyBody(dynamicBody)
dynamicBody = NULL
		

Static bodies do not move under the influence of other bodies. You may manually move static bodies, but you should be careful so that you don't squash dynamic bodies between two or more static bodies. Friction will not work correctly if you move a static body. Static bodies never simulate on their own and they never collide with other static bodies. It is faster to attach several shapes to a static body than to create several static bodies with a single shape on each one. Interally, Box2D sets the mass and inverse mass of static bodies to zero. This makes the math work out so that most algorithms don't need to treat static bodies as a special case.

Box2D does not keep a reference to the body definition or any of the data it holds (except user data references). So you can create temporary body definitions and reuse the same body definitions.

Box2D allows you to avoid destroying bodies by deleting your b2World object, which does all the cleanup work for you. However, you should be mindful to nullify any body references that you keep in your game engine.

When you destroy a body, the attached shapes and joints are automatically destroyed. This has important implications for how you manage shape and joint references. See Section 9.2,

Suppose you want to connect a dynamic body to ground with a joint. You'll need to connect the joint to a static body. If you don't have a static body, you can get a shared ground body from your world object. You can also attach static shapes to the ground body.

Local ground:b2Body = myWorld.GetGroundBody()
... build a joint using the ground body ...
		

After creating a body, there are many operations you can perform on the body. These include setting mass properties, accessing position and velocity, applying forces, and transforming points and vectors.

Method SetMassFromShapes()

Method SetMass(massData:b2MassData)
			

Method GetMass:Float()
Method GetInertia:Float()
Method GetLocalCenter:b2Vec2()
			

Method IsBullet:Int()
Method SetBullet(flag:Int)

Method IsStatic:Int()
Method IsDynamic:Int()

Method IsFrozen:Int()

Method IsSleeping:Int()
Method AllowSleeping(flag:Int)
Method WakeUp()
			

Method SetXForm:Int(position:b2Vec2, angle:Float)
Method GetXForm:b2XForm()
Method GetPosition:b2Vec2()
Method GetAngle:Float()
			

Method GetWorldCenter:b2Vec2()
			

Method SetLinearVelocity(v:b2Vec2)
Method GetLinearVelocity:b2Vec2()
Method SetAngularVelocity(omega:Float)
Method GetAngularVelocity:Float()
			

Method ApplyForce(force:b2Vec2, point:b2Vec2)
Method ApplyTorque(float32 torque:Float)
Method ApplyImpulse(impulse:b2Vec2, point:b2Vec2)
			

If Not myBody.IsSleeping() Then
	myBody.ApplyForce(myForce, myPoint)
End If
			

Method GetWorldPoint:b2Vec2(localPoint:b2Vec2)
Method GetWorldVector:b2Vec2(localVector:b2Vec2)
Method GetLocalPoint:b2Vec2(worldPoint:b2Vec2)
Method GetLocalVector:b2Vec2(worldVector:b2Vec2)
			

Local s:b2Shape = body.GetShapeList()
While s
	Local data:MyShapeData = MyShapeData(s.GetUserData())
	... do something with data ...
	s = s.GetNext()
Wend
			

Shapes are the collision geometry attached to bodies. Shapes are also used to define the mass of a body. This lets you specify the density and let Box2D do the work of computing the mass properties.

Shapes have properties of friction and restitution. Shapes carry collision filtering information to let you prevent collisions between certain game objects.

Shapes are always owned by a body. You can attach multiple shapes to a single body. Shapes are abstract classes so that many types of shapes can be implemented in Box2D. If you are brave, you can implement your own shape type (and collision algorithms).

Shape definitions are used to create shapes. There is common shape data held by b2ShapeDef and specific shape data held by derived classes.

Local friction:Float = Sqr(shape1.GetFriction() * shape2.GetFriction())
			

Local restitution:Float = b2Max(shape1.GetRestitution(), shape2.GetRestitution())
			

playerShapeDef.GetFilter().SetCategoryBits($0002)
monsterShapeDef.GetFilter().SetCategoryBits($0004)
playerShape.GetFilter().SetMaskBits($0004)
monsterShapeDef.GetFilter().SetMaskBits($0002)
			

shape1Def.GetFilter().SetGroupIndex(2)
shape2Def.GetFilter().SetGroupIndex(2)
shape3Def.GetFilter().SetGroupIndex(-8)
shape4Def.GetFilter().SetGroupIndex(-8)
			

myShapeDef.SetIsSensor(True)
			

Local def:b2CircleDef = New b2CircleDef
def.SetRadius(1.5)
def.SetLocalPosition(Vec2(1.0, 0.0))
			

6.2.6. Polygon Definitions

b2PolyDef is used to implement convex polygons. They are a bit tricky to use correctly, so please read closely. The maximum vertex count is defined by b2_maxPolyVertices which is currently 8. If you need to use more vertices, you must modify b2_maxPolyVertices in b2Settings.h .

When you build a polygon definition you must specify the number of vertices you will use. The vertices must be specified in counter-clockwise (CCW) order about the z-axis of a right-handed coordinate system. This might turn out to be clockwise on your screen, depending on your coordinate system conventions.

Polygons must be convex . In other words, each vertex must point outwards to some degree. Finally, you must not overlap any vertices. Box2D will automatically close the loop.

Here is an example of a polygon definition of a triangle:

Local triangleDef:b2PolygonDef = New b2PolygonDef
Local vertices:b2Vec2[] = New b2Vec2[3]
vertices[0] = Vec2(-1.0, 0.0)
vertices[1] = Vec2(1.0, 0.0)
vertices[2] = Vec2(0.0, 2.0)
triangleDef.SetVertices(vertices)
			

The vertices are defined in the coordinate system of the parent body. If you need to offset a polygon within the parent body, then just offset all the vertices.

For convenience, there are functions to initialize polygons as boxes. You can have either an axis-aligned box centered at the body origin or an oriented box offset from the body origin.

Local alignedBoxDef:b2PolygonDef = New b2PolygonDef
Local hx:Float = 1.0 ' half-width
Local hy:Float = 2.0 ' half-height
alignedBoxDef.SetAsBox(hx, hy)

Local orientedBoxDef:b2PolygonDef = New b2PolygonDef
Local center:b2Vec2 = Vec2(-1.5, 0.0)
Local angle:Float = 90
orientedBoxDef.SetAsOrientedBox(hx, hy, center, angle)
			

Shapes are created by initializing a shape definition and then passing the definition to the parent body.

Local circleDef:b2CircleDef = new b2CircleDef
circleDef.SetRadius(3.0)
circleDef.SetDensity(2.5)
Local myShape:b2Shape = myBody.CreateShape(circleDef)
[optionally store shape reference somewhere]
		

This creates the shape and attaches it to the body. You do not need to store the shape pointer since the shape will automatically be destroyed when the parent body is destroyed (see Section 9.2,

After you finish adding shapes to a body, you may want to recompute the mass properties of the body based on the child shapes.

myBody.SetMassFromShapes()
		

This function is expensive, so you should only call it when necessary.

You can destroy a shape on the parent body easily. You may do this to model a breakable object. Otherwise you can just leave the shape alone and let the body destruction take care of destroying the attached shapes.

myBody.DestroyShape(myShape)
		

After removing shapes from a body, you may want to call SetMassFromShapes again.

There's not much to say here. You can get a shape's type and its parent body. You can also test a point to see if it is contained within the shape. Look at b2Shape.h for details.

Joints are used to constrain bodies to the world or to each other. Typical examples in games include ragdolls, teeters, and pulleys. Joints can be combined in many different ways to create interesting motions.

Some joints provide limits so you can control the range of motion. Some joint provide motors which can be used to drive the joint at a prescribed speed until a prescribed force/torque is exceeded.

Joint motors can be used in many ways. You can use motors to control position by specifying a joint velocity that is proportional to the difference between the actual and desired position. You can also use motors to simulate joint friction: set the joint velocity to zero and provide a small, but significant maximum motor force/torque. Then the motor will attempt to keep the joint from moving until the load becomes too strong.

Each joint type has a definition that derives from b2JointDef . All joints are connected between two different bodies. One body may static. If you want to waste memory, then create a joint between two static bodies. :)

You can specify user data for any joint type and you can provide a flag to prevent the attached bodies from colliding with each other. This is actually the default behavior and you must set the collideConnected Boolean to allow collision between to connected bodies.

Many joint definitions require that you provide some geometric data. Often a joint will be defined by anchor points . These are points fixed in the attached bodies. Box2D requires these points to be specified in local coordinates. This way the joint can be specified even when the current body transforms violate the joint constraint --- a common ocurrence when a game is saved and reloaded. Additionally, some joint definitions need to know the default relative angle between the bodies. This is necessary to constraint rotation correctly via joint limits or a fixed relative angle.

Initializing the geometric data can be tedious, so many joints have initialization functions that use the current body transforms to remove much of the work. However, these initialization functions should usually only be used for prototyping. Production code should define the geometry directly. This will make joint behavior more robust.

The rest of the joint definition data depends on the joint type. We cover these now.

7.2.1. Distance Joint

One of the simplest joint is a distance joint which says that the distance between two points on two bodies must be constant. When you specify a distance joint the two bodies should already be in place. Then you specify the two anchor points in world coordinates. The first anchor point is connected to body 1, and the second anchor point is connected to body 2. These points imply the length of the distance constraint.

Here is an example of a distance joint definition. In this case we decide to allow the bodies to collide.

Local jointDef:b2DistanceJointDef = New b2DistanceJointDef
jointDef.Initialize(myBody1, myBody2, worldAnchorOnBody1, worldAnchorOnBody2)
jointDef.SetCollideConnected(True)
			

7.2.2. Revolute Joint

A revolute joint forces two bodies to share a common anchor point, often called a hinge point . The revolute joint has a single degree of freedom: the relative rotation of the two bodies. This is called the joint angle .

To specify a revolute you need to provide two bodies and a single anchor point in world space. The initialization function assumes that the bodies are already in the correct position.

In this example, two bodies are connected by a revolute joint at the first body's center of mass.

Local jointDef:b2RevoluteJointDef = New b2RevoluteJointDef
jointDef.Initialize(myBody1, myBody2, myBody1.GetWorldCenter())
			

The revolute joint angle is positive when body2 rotates CCW about the angle point. Like all angles in Box2D, the revolute angle is measured in radians. By convention the revolute joint angle is zero when the joint is created using Initialize() , regardless of the current rotation of the two bodies.

In some cases you might wish to control the joint angle. For this, the revolute joint can optionally simulate a joint limit and/or a motor.

A joint limit forces the joint angle to remain between an lower and upper bound. The limit will apply as much torque as needed to make this happen. The limit range should include zero, otherwise the joint will lurch when the simulation begins.

A joint motor allows you to specify the joint speed (the time derivative of the angle). The speed can be negative or positive. A motor can have infinite force, but this is usually not desirable. Have you ever heard the expression:

Caution

"What happens when an irresistible force meets an immovable object?"

I can tell you it's not pretty. So you can provide a maximum torque for the joint motor. The joint motor will maintain the specified speed unless the required torque exceeds the specified maximum. When the maximum torque is exceeded, the joint will slow down and can even reverse.

You can use a joint motor to simulate joint friction. Just set the joint speed to zero, and set the maximum torque to some small, but significant value. The motor will try to prevent the joint from rotating, but will yield to a significant load.

Here's a revision of the revolute joint definition above; this time the joint has a limit and a motor enabled. The motor is setup to simulate joint friction.

Local jointDef:b2RevoluteJointDef = New b2RevoluteJointDef
jointDef.Initialize(body1, body2, myBody1.GetWorldCenter())
jointDef.SetLowerAngle(-90)
jointDef.SetUpperAngle(45)
jointDef.EnableLimit(True)
jointDef.SetMaxMotorTorque(10.0)
jointDef.SetMotorSpeed(0.0)
jointDef.EnableMotor(True)
			

7.2.3. Prismatic Joint

A prismatic joint allows for relative translation of two bodies along a specified axis. A prismatic joint prevents relative rotation. Therefore, a prismatic joint has a single degree of freedom.

The prismatic joint definition is similar to the revolute joint description; just substitute translation for angle and force for torque. Using this analogy provides an example prismatic joint definition with a joint limit and a friction motor:

Local jointDef:b2PrismaticJointDef = new b2PrismaticJointDef
Local worldAxis:b2Vec2 = new b2Vec2.Create(1.0, 0.0)
jointDef.Initialize(myBody1, myBody2, myBody1.GetWorldCenter(), worldAxis)
jointDef.SetLowerTranslation(-5.0)
jointDef.SetUpperTranslation(2.5)
jointDef.SetEnableLimit(True)
jointDef.SetMotorForce(1.0)
jointDef.SetMotorSpeed(0.0)
jointDef.EnableMotor(True)
			

The revolute joint has an implicit axis coming out of the screen. The prismatic joint needs an explicit axis parallel to the screen. This axis is fixed in the two bodies and follows their motion.

Like the revolute joint, the prismatic joint translation is zero when the joint is created using Initialize() . So be sure zero is between your lower and upper translation limits.

7.2.4. Pulley Joint

A pulley is used to create an idealized pulley. The pulley connects two bodies to ground and to each other. As one body goes up, the other goes down. The total length of the pulley rope is conserved according to the initial configuration.

length1 + length2 = constant
			

You can supply a ratio that simulates a block and tackle . This causes one side of the pulley to extend faster than the other. At the same time the constraint force is smaller on one side than the other. You can use this to create mechanical leverage.

length1 + ratio * length2 = constant
			

For example, if the ratio is 2, then length1 will vary at twice the rate of length2. Also the force in the rope attached to body1 will have half the constraint force as the rope attached to body2.

Pulleys can be troublesome when one side is fully extended. The rope on the other side will have zero length. At this point the constraint equations become singular (bad). Therefore the pulley joint constrains the maximum length that either side can attain. Also, you may want to control the maximum lengths for gameplay reasons. So the maximum lengths improve stability and give you more control.

Here is an example pulley definition:

Local anchor1:b2Vec2 = myBody1.GetWorldCenter()
Local anchor2:b2Vec2 = myBody2.GetWorldCenter()
Local groundAnchor1:b2Vec2 = new b2Vec2.Create(p1.X(), p1.Y() + 10.0)
Local groundAnchor2:b2Vec2 = new b2Vec2.Create(p2.X(), p2.Y() + 12.0)
Local ratio:Float = 1.0
Local jointDef:b2PulleyJointDef = new b2PulleyJointDef
jointDef.Initialize(myBody1, myBody2, groundAnchor1, groundAnchor2, anchor1, anchor2, ratio)
jointDef.SetMaxLength1(18.0)
jointDef.SetMaxLength2(20.0)
			

7.2.5. Gear Joint

If you want to create a sophisticated mechanical contraption you might want to use a gears. In principle you can create gears in Box2D by using compound shapes to model gear teeth. This is not very efficient and might be tedious to author. You also have to be careful to line up the gears so the teeth mesh smoothly. Box2D has a simpler method of creating gears: the gear joint .

The gear joint requires the you have two bodies connected to ground by a revolute or prismatic joint. You can use any combination of those joint types. Also, Box2D requires that the revolute and prismatic joints were created with the ground as body1.

Like the pulley ratio, you can specify a gear ratio. However, in this case the gear ratio can be negative. Also keep in mind that when one joint is a revolute joint (angular) and the other joint is prismatic (translation), then the gear ratio with have units of length or one over length.

coordinate1 + ratio * coordinate2 = constant
			

Here is an example gear joint:

Local jointDef:b2GearJointDef = new b2GearJointDef
jointDef.SetBody1(myBody1)
jointDef.SetBody2(myBody2)
jointDef.SetJoint1(myRevoluteJoint)
jointDef.SetJoint2(myPrismaticJoint)
jointDef.SetRatio(2.0 * Pi / myLength)
			

Note that the gear joint depends on two other joints. This creates a fragile situation. What happens if those joints are deleted?

Caution

Always delete gear joints before the revolute/prismatic joints on the gears. Otherwise your code will crash in a bad way due to the orphaned joint references in the gear joint. You should also delete the gear joint before you delete any of the bodies involved.

Joints are created and destroyed using the world factory methods. This brings up an old issue:

Here's an example of the lifetime of a revolute joint:

Local jointDef:b2RevoluteJointDef = new b2RevoluteJointDef
jointDef.SetBody1(myBody1)
jointDef.SetBody2(myBody2)
jointDef.SetAnchorPoint(myBody1.GetCenterPosition())
Local joint:b2RevoluteJoint = myWorld.CreateJoint(jointDef)
... do stuff ...
myWorld.DestroyJoint(joint)
joint = Null
		

It is always good to nullify your pointer after they are destroyed. This will make the program crash in a controlled manner if you try to reuse the pointer.

The lifetime of a joint is not simple. Heed this warning well:

This precaution is not always necessary. You may organize your game engine so that joints are always destroyed before the attached bodies. In this case you don't need to implement the listener class. See Section 9.2, "e;Implicit Destruction"e; for details.

Many simulations create the joints and don't access them again until they are detroyed. However, there is a lot of useful data contained in joints that you can use to create a rich simulation.

First of all, you can get the bodies, anchor points, and user data from a joint.

Method GetBody1:b2Body()
Method GetBody2:b2Body()
Method GetAnchor1:b2Vec2()
Method GetAnchor2:b2Vec2()
Method GetUserData:Object()
		

All joints have a reaction force and torque. This the reaction force applied to body 2 at the anchor point. You can use reaction forces to break joints or trigger other game events. These functions may do some computations, so don't call them if you don't need the result.

Method GetReactionForce:b2Vec2()
Method GetReactionTorque:Float()
		

Method GetJointAngle:Float()
Method GetJointSpeed:Float()
Method GetMotorTorque:Float()
			

Method SetMotorSpeed(speed:Float)
Method SetMaxMotorTorque(torque:Float)
			

... Game Loop Begin ...
myJoint.SetMotorSpeed(Cos(0.5 * time))
 ... Game Loop End ...
			

... Game Loop Begin ...
Local angleError:Float = myJoint.GetJointAngle() - angleTarget
Local gain:Float = 0.1
myJoint.SetMotorSpeed(-gain * angleError)
... Game Loop End ...
			

Method GetJointTranslation:Float()
Method GetJointSpeed:Float()
Method GetMotorForce:Float()
Method SetMotorSpeed(speed:Float)
Method SetMotorForce(force:Float)
			

Method GetLength1:Float()
Method GetLength2:Float()
			

Contacts are objects created by Box2D to manage collision between shapes. There are different kinds of contacts, derived from b2Contact , for managing contact between different kinds of shapes. For example there is a contact class for managing polygon-polygon collision and another contact class for managing circle-circle collision. This is normally not important to you, I just thought you might like to know.

Here is some terminlogy associated with contacts. This terminology is particular to Box2D, but you might find similar terminology in other physics engines.

Contacts are created when two shape's AABBs overlap. Sometimes collision filtering will prevent the creation of contacts. Box2D sometimes needs to create a contact even though the collision is filtered. In this case it uses a b2NullContact that prevents collision from occuring. Contacts are destroyed with the AABBs cease to overlap.

So you might gather that there may be contacts created for shapes that are not touching (just their AABBs). Well, this is correct. It's a "chicken or egg" problem. We don't know if we need a contact object until one is created to analyze the collision. We could delete the contact right away if the shapes are not touching, or we can just wait until the AABBS stop overlapping. Box2D takes the latter approach.

You can receive contact data by implementing b2ContactListener . This listener reports a contact point when it is created, when it persists for more than one time step, and when it is destroyed. Keep in mind that two shapes may have multiple contact points.

Type MyContactListener Extends b2ContactListener

	Method Add(point:b2ContactPoint)
		' handle add point
	End Method
	
	Method Persist(point:b2ContactPoint)
		' handle persist point
	End Method
	
	Method Remove(point:b2ContactPoint)
		' handle remove point
	End Method
	
	Method Result(point:b2ContactResult)
		' handle results
	End Method

End Type
		

Continuous physics uses sub-stepping, so a contact point may be added and removed within the same time step. This is normally not a problem, but your code should handle this gracefully.

Contact points are reported immediately when they are added, persisted, or removed. This occurs before the solver is called, so the b2ContactPoint object does not contain the computed impulse. However, the relative velocity at the contact point is provided so that you can estimated the contact impulse. If you implement the Result listener function, you will receive b2ContactResult objects for solid contact points after the solver has been called. These result structures contain the sub-step impulses. Again, due to continuous physics you may receive multiple results per contact point per b2World::DoStep .

It is tempting to implement game logic that alters the physics world inside a contact callback. For example, you may have a collision that applies damage and try to destroy the associated actor and its rigid body. However, Box2D does not allow you to alter the physics world inside a callback because you might destroy objects that Box2D is currently processing, leading to orphaned references.

The recommended practice for processing contact points is to buffer all contact points that you care about and process them after the time step. You should always process the contact points immediately after the time step, otherwise some other client code might alter the physics world, invalidating the contact buffer. When you process the contact point buffer you can alter the physics world, but you still need to be careful that you don't orphan references stored in the contact point buffer. The testbed has example contact point processing that is safe from orphaned references.

This code from the CollisionProcessing test shows how to handle orphaned bodies when processing the contact buffer. Here is an excerpt. Be sure to read the comments in the listing. This code assumes that all contact points have been buffered in the b2ContactPoint array m_points .

' We are going to destroy some bodies according to contact
' points. We must buffer the bodies that should be destroyed
' because they may belong to multiple contact points.
Local k_maxNuke:Int = 6
Local nuke:b2Body[] = new b2Body[k_maxNuke]
Local nukeCount:Int = 0

' Traverse the contact buffer. Destroy bodies that
' are touching heavier bodies.
For Local i:Int = 0 Until m_pointCount

	Local point:ContactPoint = m_points[i]
	
	Local body1:b2Body = point.GetShape1().GetBody()
	Local body2:b2Body = point.GetShape2().GetBody()
	Local mass1:Float = body1.GetMass()
	Local mass2:Float = body2.GetMass()
	
	If mass1 > 0.0 And mass2 > 0.0 Then
	
		If mass2 > mass1 Then
			nuke[nukeCount] = body1
		Else
			nuke[nukeCount] = body2
		End If
		nukeCount:+ 1
	
		If nukeCount = k_maxNuke Then
			Exit
		End If
	
Next

' Sort the nuke array to group duplicates.
'std::sort(nuke, nuke + nukeCount); .. .TODO

' Destroy the bodies, skipping duplicates.
Local i:Int = 0
While i < nukeCount
	Local b:b2Body = nuke[i]
	i:+ 1
	While i < nukeCount And nuke[i] = b
		i:+ 1
	Wend

	m_world.DestroyBody(b)
Wend

		

Often in a game you don't want all objects to collide. For example, you may want to create a door that only certain characters can pass through. This is called contact filtering, because some interactions are filtered out .

Box2D allows you to achieve custom contact filtering by implementing a b2ContactFilter class. This class requires you to implement a ShouldCollide method that receives two b2Shape references. Your method returns true if the shapes should collide.

The default implementation of ShouldCollide uses the b2FilterData defined in Chapter 6, Shapes .

Method ShouldCollide:Int(shape1:b2Shape, shape2:b2Shape)

	Local filter1:b2FilterData = shape1.GetFilterData()
	Local filter2:b2FilterData = shape2.GetFilterData()

	If filter1.GetGroupIndex() = filter2.GetGroupIndex() And filter1.GetGroupIndex() <> 0 Then
		return filter1.GetGroupIndex() < $7FFF
	End If

	Local collide:Int = (filter1.GetMaskBits() & filter2.GetCategoryBits()) <> 0 And ..
		(filter1.GetCategoryBits() & filter2.GetMaskBits()) <> 0
	return collide
	
End Method

		

You can implement a b2BoundaryListener that allows b2World to inform you when a body has gone outside the world AABB. When you get the callback, you shouldn't try to delete the body, instead you should mark the parent actor for deletion or error handling. After the physics time step, you should handle the event.

Type MyBoundaryListener Extends b2BoundaryListener

	Method Violation(body:b2Body)
		Local myActor:MyActor = MyActor(body.GetUserData())
		myActor.MarkForErrorHandling()
	End Method

End Type
		

You can then register an instance of your boundary listener with your world object. You should do this during world initialization.

myWorld.SetBoundaryListener(myBoundaryListener)
		

Box2D doesn't use reference counting. So if you destroy a body it is really gone. Accessing a pointer to a destroyed body has undefined behavior. In other words, your program will likely crash and burn. To help fix these problems, the debug build memory manager fills destroyed entities with FDFDFDFD . This can help find problems more easily in some cases.

If you destroy a Box2D entity, it is up to you to make sure you remove all references to the destroyed object. This is easy if you only have a single reference to the entity. If you have multiple references, you might consider implementing a handle class to wrap the raw pointer.

Often when using Box2D you will create and destroy many bodies, shapes, and joints. Managing these entities is somewhat automated by Box2D. If you destroy a body then all associated shapes and joints are automatically destroyed. This is called implicit destruction .

When you destroy a body, all its attached shapes, joints, and contacts are destroyed. This is called implicit destruction . Any body connected to one of those joints and/or contacts is woken. This process is usually convenient. However, you must be aware of one crucial issue:

To help you nullify your joint references, Box2D provides a listener class named b2WorldListener that you can implement and provide to your world object. Then the world object will notify you when a joint is going to be implicity destroyed.

Implicit destruction is a great convenience in many cases. It can also make your program fall apart. You may store references to shapes and joints somewhere in your code. These references become orphaned when an associated body is destroyed. The situation becomes worse when you consider that joints are often created by a part of the code unrelated to management of the associated body. For example, the testbed creates a b2MouseJoint for interactive manipulation of bodies on the screen.

Box2D provides a callback mechanism to inform your application when implicit destruction occurs. This gives your application a chance to nullify the orphaned pointers. This callback mechanism is described later in this manual.

You can implement a b2DestructionListener that allows b2World to inform you when a shape or joint is implicitly destroyed because an associated body was destroyed. This will help prevent your code from accessing orphaned pointers.

Type MyDestructionListener Extends b2DestructionListener

	Method SayGoodbye(joint:b2Joint)
		' remove all references to joint.
	End Method

End Type
		

You can then register an instance of your destruction listener with your world object. You should do this during world initialization.

myWorld.SetDestructionListener(myDestructionListener)
		

There are two source files included in Box2D that are supplied specifically for user customization. These are b2Settings.h and b2Settings.cpp .

Box2D works with floating point numbers, so some tolerances have to be used to make Box2D perform well.

There are many tolerances settings that depend on using MKS units. See Section 3.3, “Units” for a deeper explanation of the unit system. See the doxygen docs for explanation of the individual tolerances.