Box2D 3.1.0
A 2D physics engine for games
 
Loading...
Searching...
No Matches
Simulation

Rigid body simulation is the primary feature of Box2D. It is the most complex part of Box2D and is the part you will likely interact with the most. Simulation sits on top of the foundation and collision layers, so you should be somewhat familiar with those by now.

Rigid body simulation contains:

  • worlds
  • bodies
  • shapes
  • contacts
  • joints
  • events

There are many dependencies between these objects so it is difficult to describe one without referring to another. In the following, you may see some references to objects that have not been described yet. Therefore, you may want to quickly skim this section before reading it closely.

Ids

Box2D has a C interface. Typically in a C/C++ library when you create an object with a long lifetime you will keep a pointer (or smart pointer) to the object.

Box2D works differently. Instead of pointers, you are given an id when you create an object. This id acts as a handle which helps avoid problems with dangling pointers.

This also allows Box2D to use data-oriented design internally. This helps to reduce cache misses drastically and also allows for SIMD optimizations.

So you will be dealing with b2WorldId, b2BodyId, etc. These are small opaque structures that you will pass around by value, just like pointers. Box2D creation functions return an id. Functions that operate on Box2D objects take ids.

b2BodyId myBodyId = b2CreateBody(myWorldId, &myBodyDef);
B2_API b2BodyId b2CreateBody(b2WorldId worldId, const b2BodyDef *def)
Create a rigid body given a definition.
Body id references a body instance. This should be treated as an opaque handle.
Definition id.h:45

There are functions to check if an id is valid. Box2D functions will assert if you use an invalid id. This makes debugging easier than using dangling pointers.

if (b2Body_IsValid(myBodyId) == false)
{
// oops
}
B2_API bool b2Body_IsValid(b2BodyId id)
Body identifier validation. Can be used to detect orphaned ids. Provides validation for up to 64K all...

Null ids can be established in a couple ways. You can use predefined constants or zero initialization.

b2BodyId myNullBodyId = b2_nullBodyId;
b2BodyId otherNullBodyId = {0};

You can test if an id is null using some helper macros:

if (B2_IS_NULL(myBodyId))
{
// do something
}
#define B2_IS_NULL(id)
Macro to determine if any id is null.
Definition id.h:84
if (B2_IS_NON_NULL(myShapeId))
{
// do something
}
#define B2_IS_NON_NULL(id)
Macro to determine if any id is non-null.
Definition id.h:87

World

The Box2D world contains the bodies and joints. It manages all aspects of the simulation and allows for asynchronous queries (like AABB queries and ray-casts). Much of your interactions with Box2D will be with a world object, using b2WorldId.

World Definition

Worlds are created using a definition structure. This is temporary structure that you can use to configure options for world creation. You must initialize the world definition using b2DefaultWorldDef().

b2WorldDef b2DefaultWorldDef(void)
Use this to initialize your world definition.
World definition used to create a simulation world.
Definition types.h:81

The world definition has lots of options, but for most you will use the defaults. You may want to set the gravity:

worldDef.gravity = (b2Vec2){0.0f, -10.0f};
2D vector This can be used to represent a point or free vector
Definition math_functions.h:21
b2Vec2 gravity
Gravity vector. Box2D has no up-vector defined.
Definition types.h:83

If your game doesn't need sleep, you can get a performance boost by completely disabling sleep:

worldDef.enableSleep = false;
bool enableSleep
Can bodies go to sleep to improve performance.
Definition types.h:120

You can also configure multithreading to improve performance:

worldDef.workerCount = 4;
worldDef.enqueueTask = myAddTaskFunction;
worldDef.finishTask = myFinishTaskFunction;
worldDef.userTaskContext = &myTaskSystem;
b2FinishTaskCallback * finishTask
Function to finish a task.
Definition types.h:138
void * userTaskContext
User context that is provided to enqueueTask and finishTask.
Definition types.h:141
int workerCount
Number of workers to use with the provided task system.
Definition types.h:132
b2EnqueueTaskCallback * enqueueTask
Function to spawn tasks.
Definition types.h:135

Multithreading is not required but it can improve performance substantially. Read more here.

World Lifetime

Creating a world is done using a world definition.

b2WorldId myWorldId = b2CreateWorld(&worldDef);
// ... do stuff ...
b2DestroyWorld(myWorldId);
// Nullify id for safety
myWorldId = b2_nullWorldId;
World id references a world instance. This should be treated as an opaque handle.
Definition id.h:38
B2_API void b2DestroyWorld(b2WorldId worldId)
Destroy a world.
B2_API b2WorldId b2CreateWorld(const b2WorldDef *def)
Create a world for rigid body simulation.

You can create up to 128 worlds. These worlds do not interact and may be simulated in parallel.

When you destroy a world, every body, shape, and joint is also destroyed. This is much faster than destroying individual objects.

Simulation

The world is used to drive the simulation. You specify a time step and a sub-step count. For example:

float timeStep = 1.0f / 60.f;
int32_t subSteps = 4;
b2World_Step(myWorldId, timeStep, subSteps);
B2_API void b2World_Step(b2WorldId worldId, float timeStep, int subStepCount)
Simulate a world for one time step.

After the time step you can examine your bodies and joints for information. Most likely you will grab the position off the bodies so that you can update your game objects and render them. Or more optimally, you will use b2World_GetBodyEvents().

You can perform the time step anywhere in your game loop, but you should be aware of the order of things. For example, you must create bodies before the time step if you want to get collision results for the new bodies in that frame.

As I discussed in the HelloWorld tutorial, you should use a fixed time step. By using a larger time step you can improve performance in low frame rate scenarios. But generally you should use a time steps 1/30 seconds (30Hz) or smaller. A time step of 1/60 seconds (60Hz) will usually deliver a high quality simulation.

The sub-step count is used to increase accuracy. By sub-stepping the solver divides up time into small increments and the bodies move by a small amount. This allows joints and contacts to respond with finer detail. The recommended sub-step count is 4. However, increasing the sub-step count may improve accuracy. For example, long joint chains will stretch less with more sub-steps.

The scissor lift sample shown here works better with more sub-steps and is configured to use 8 sub-steps. With a primary time step of 1/60 seconds, the scissor lift is taking sub-steps at 480Hz!

Rigid Bodies

Rigid bodies, or just bodies have position and velocity. You can apply forces, torques, and impulses to bodies. Bodies can be static, kinematic, or dynamic. Here are the body type definitions:

Body types

b2_staticBody: A static body does not move under simulation and behaves as if it has infinite mass. Internally, Box2D stores zero for the mass and the inverse mass. A static body has zero velocity. Static bodies do not collide with other static or kinematic bodies.

b2_kinematicBody: A kinematic body moves under simulation according to its velocity. Kinematic bodies do not respond to forces. A kinematic body is moved by setting its velocity. A kinematic body behaves as if it has infinite mass, however, Box2D stores zero for the mass and the inverse mass. Kinematic bodies do not collide with other kinematic or static bodies. Generally you should use a kinematic body if you want a shape to be animated and not affected by forces or collisions.

b2_dynamicBody: A dynamic body is fully simulated and moves according to forces and torques. A dynamic body can collide with all body types. A dynamic body always has finite, non-zero mass.

Caution: Generally you should not set the transform on bodies after creation. Box2D treats this as a teleport and may result in undesirable behavior and/or performance problems.

Bodies carry shapes and moves 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 and shapes attached to the same body don't collide.

Shapes have collision geometry and density. Normally, bodies acquire their mass properties from the shapes. However, you can override the mass properties after a body is constructed.

You usually keep ids 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 ids so you can destroy them when you are done with them.

Body Definition

Before a body is created you must create a body definition (b2BodyDef). The body definition holds the data needed to create and initialize a body correctly.

Because Box2D uses a C API, a function is provided to create a default body definition.

b2BodyDef b2DefaultBodyDef(void)
Use this to initialize your body definition.
A body definition holds all the data needed to construct a rigid body.
Definition types.h:178

This ensures the body definition is valid and this initialization is mandatory.

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.

Let's go over some of the key members of the body definition.

Body Type

As discussed previously, there are three different body types: static, kinematic, and dynamic. b2_staticBody is the default. You should establish the body type at creation because changing the body type later is expensive.

b2BodyDef bodyDef;
bodyDef.type = b2_dynamicBody;
b2BodyType type
The body type: static, kinematic, or dynamic.
Definition types.h:180
@ b2_dynamicBody
positive mass, velocity determined by forces, moved by solver
Definition types.h:166

Position and Angle

You can initialize the body position and angle in the body definition. This has far better performance than creating the body at the world origin and then moving the body.

Caution: Do not create a body at the origin and then move it. If you create several bodies at the origin, then performance will suffer.

A body has two main points of interest. The first point is the body's origin. Shapes and joints are attached relative to the body's origin. The second point of interest is the center of mass. The center of mass is determined from the mass distribution of the attached shapes or is explicitly set using b2MassData. Much of Box2D's internal computations use the center of mass position. For example the body stores the linear velocity for the center of mass, not the body origin.

Body Origin and Center of Mass

When you are building the body definition, you may not know where the center of mass is located. Therefore you specify the position of the body's origin. You may also specify the body's angle in radians. If you later change the mass properties of the body, then the center of mass may move on the body, but the origin position and body angle does not change and the attached shapes and joints do not move.

bodyDef.position = (b2Vec2){0.0f, 2.0f};
bodyDef.angle = 0.25f * b2_pi;
b2Vec2 position
The initial world position of the body.
Definition types.h:185

A rigid body is a frame of reference. You can define shapes and joints in that frame. Those shapes and joint anchors never move in the local frame of the body.

Damping

Damping is used to reduce the world velocity of bodies. Damping is different than friction because friction only occurs with contact. Damping is not a replacement for friction and the two effects are used together.

Damping parameter are non-negative. Normally you will use a damping value between 0 and 1. I generally do not use linear damping because it makes bodies look like they are floating.

bodyDef.linearDamping = 0.0f;
bodyDef.angularDamping = 0.1f;
float linearDamping
Linear damping is used to reduce the linear velocity.
Definition types.h:201
float angularDamping
Angular damping is used to reduce the angular velocity.
Definition types.h:207

Damping is approximated to improve performance. At small damping values the damping effect is mostly independent of the time step. At larger damping values, the damping effect will vary with the time step. This is not an issue if you use a fixed time step (recommended).

Here's some math for the curious. A first-order different equation for velocity damping is:

\[\frac{dv}{dt} + c v = 0 \]

The solution with initial velocity \(v_0\) is

\[v = v_0 e^{-c t} \]

Across a single time step \(h\) the velocity evolves like so

\[v(t + h) = v_0 e^{-c (t + h)} = v_0 e^{-c t} e^{-c h} = v(t) e^{-c h} \]

Using the Pade approximation for the exponential function gives the update formula:

\[v(t + h) \approx \frac{1}{1 + c h} v(t) \]

This is the formula used in the Box2D solver.

Gravity Scale

You can use the gravity scale to adjust the gravity on a single body. Be careful though, a large gravity magnitude can decrease stability.

// Set the gravity scale to zero so this body will float
bodyDef.gravityScale = 0.0f;
float gravityScale
Scale the gravity applied to this body. Non-dimensional.
Definition types.h:210

Sleep Parameters

What does sleep mean? Well it is expensive to simulate bodies, so the less we have to simulate the better. When a body comes to rest we would like to stop simulating it.

When Box2D determines that a body (or group of bodies) has come to rest, the body enters a sleep state which has very little CPU overhead. If a body is awake and collides with a sleeping body, then the sleeping body wakes up. Bodies will also wake up if a joint or contact attached to them is destroyed. You can also wake a body manually.

The body definition lets you specify whether a body can sleep and whether a body is created sleeping.

bodyDef.enableSleep = true;
bodyDef.isAwake = true;
bool isAwake
Is this body initially awake or sleeping?
Definition types.h:225
bool enableSleep
Set this flag to false if this body should never fall asleep.
Definition types.h:222

The isAwake flag is ignored if enableSleep is false.

Fixed Rotation

You may want a rigid body, such as a character, to have a fixed rotation. Such a body does not rotate, even under load. You can use the fixed rotation setting to achieve this:

bodyDef.fixedRotation = true;
bool fixedRotation
Should this body be prevented from rotating? Useful for characters.
Definition types.h:228

The fixed rotation flag causes the rotational inertia and its inverse to be set to zero.

Bullets

Game simulation usually generates a sequence of transforms that are played at some frame rate. This is called discrete simulation. In discrete simulation, rigid bodies can move by a large amount in one time step. If a physics engine doesn't account for the large motion, you may see some objects incorrectly pass through each other. This effect is called tunneling.

By default, Box2D uses continuous collision detection (CCD) to prevent dynamic bodies from tunneling through static bodies. This is done by sweeping shapes from their old position to their new positions. The engine looks for new collisions during the sweep and computes the time of impact (TOI) for these collisions. Bodies are moved to their first TOI at the end of the time step.

Normally CCD is not used between dynamic bodies. This is done to keep performance reasonable. In some game scenarios you need dynamic bodies to use CCD. For example, you may want to shoot a high speed bullet at a stack of dynamic bricks. Without CCD, the bullet might tunnel through the bricks.

Fast moving objects in Box2D can be configured as bullets. Bullets will perform CCD with all body types, but not other bullets. You should decide what bodies should be bullets based on your game design. If you decide a body should be treated as a bullet, use the following setting.

bodyDef.isBullet = true;
bool isBullet
Treat this body as high speed object that performs continuous collision detection against dynamic and...
Definition types.h:234

The bullet flag only affects dynamic bodies. I recommend using bullets sparingly.

Disabling

You may wish a body to be created but not participate in collision or simulation. This state is similar to sleeping except the body will not be woken by other bodies and the body's shapes will not collide with anything. This means the body will not participate in collisions, ray casts, etc.

You can create a body as disabled and later enable it.

bodyDef.isEnabled = false;
// Later ...
b2Body_Enable(myBodyId);
bool isEnabled
Used to disable a body. A disabled body does not move or collide.
Definition types.h:237
B2_API void b2Body_Enable(b2BodyId bodyId)
Enable a body by adding it to the simulation. This is expensive.

Joints may be connected to disabled bodies. These joints will not be simulated. You should be careful when you enable a body that its joints are not distorted.

Note that enabling a body is almost as expensive as creating the body from scratch. So you should not use body disabling for streaming worlds. Instead, use creation/destruction for streaming worlds to save memory.

Body disabling is a convenience and is generally not good for performance.

User Data

User data is a void pointer. This gives you a hook to link your application objects to bodies. You should be consistent to use the same object type for all body user data.

bodyDef.userData = &myGameObject;
void * userData
Use this to store application specific body data.
Definition types.h:219

This is useful when you receive results from a query such as a ray-cast or event and you want to get back to your game object. You can acquire the use data from a body using b2Body_GetUserData().

Body Lifetime

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

b2BodyId myBodyId = b2CreateBody(myWorldId, &bodyDef);
// ... do stuff ...
b2DestroyBody(myBodyId);
// Nullify body id for safety
myBodyId = b2_nullBodyId;
B2_API void b2DestroyBody(b2BodyId bodyId)
Destroy a rigid body given an id.

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

Box2D allows you to avoid destroying bodies by destroying the world directly using b2DestroyWorld(), which does all the cleanup work for you. However, you should be mindful to nullify body ids that you keep in your application.

When you destroy a body, the attached shapes and joints are automatically destroyed. This has important implications for how you manage shape and joint ids. You should nullify these ids after destroying a body.

Using a 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.

Mass Data

A body has mass (scalar), center of mass (2-vector), and rotational inertia (scalar). For static bodies, the mass and rotational inertia are set to zero. When a body has fixed rotation, its rotational inertia is zero.

Normally the mass properties of a body are established automatically when shapes are added to the body. You can also adjust the mass of a body at run-time. This is usually done when you have special game scenarios that require altering the mass.

b2MassData myMassData;
myMassData.mass = 10.0f;
myMassData.center = (b2Vec2){0.0f, 0.0f};
myMassData.rotationalInertia = 100.0f;
b2Body_SetMassData(myBodyId, myMassData);
B2_API void b2Body_SetMassData(b2BodyId bodyId, b2MassData massData)
Override the body's mass properties.
b2Vec2 center
The position of the shape's centroid relative to the shape's origin.
Definition collision.h:97
float mass
The mass of the shape, usually in kilograms.
Definition collision.h:94
float rotationalInertia
The rotational inertia of the shape about the local origin.
Definition collision.h:100
This holds the mass data computed for a shape.
Definition collision.h:92

After setting a body's mass directly, you may wish to revert to the mass determined by the shapes. You can do this with:

B2_API void b2Body_ApplyMassFromShapes(b2BodyId bodyId)
This update the mass properties to the sum of the mass properties of the shapes.

The body's mass data is available through the following functions:

float mass = b2Body_GetMass(myBodyId);
float inertia = b2Body_GetRotationalInertia(myBodyId);
b2Vec2 localCenter b2Body_GetLocalCenterOfMass(myBodyId);
b2MassData massData = b2Body_GetMassData(myBodyId);
B2_API float b2Body_GetMass(b2BodyId bodyId)
Get the mass of the body, usually in kilograms.
B2_API b2Vec2 b2Body_GetLocalCenterOfMass(b2BodyId bodyId)
Get the center of mass position of the body in local space.
B2_API b2MassData b2Body_GetMassData(b2BodyId bodyId)
Get the mass data for a body.
B2_API float b2Body_GetRotationalInertia(b2BodyId bodyId)
Get the rotational inertia of the body, usually in kg*m^2.

State Information

There are many aspects to the body's state. You can access this state data through the following functions:

b2BodyType bodyType = b2Body_GetType(myBodyId);
b2Body_SetBullet(myBodyId, true);
bool isBullet = b2Body_IsBullet(myBodyId);
b2Body_EnableSleep(myBodyId, false);
bool isSleepEnabled = b2Body_IsSleepingEnabled(myBodyId);
b2Body_SetAwake(myBodyId, true);
bool isAwake = b2Body_IsAwake(myBodyId);
b2Body_Disable(myBodyId);
b2Body_Enable(myBodyId);
bool isEnabled = b2Body_IsEnabled(myBodyId);
b2Body_SetFixedRotation(myBodyId, true);
bool isFixedRotation = b2Body_IsFixedRotation(myBodyId);
B2_API b2BodyType b2Body_GetType(b2BodyId bodyId)
Get the body type: static, kinematic, or dynamic.
B2_API void b2Body_SetBullet(b2BodyId bodyId, bool flag)
Set this body to be a bullet.
B2_API void b2Body_SetType(b2BodyId bodyId, b2BodyType type)
Change the body type.
B2_API void b2Body_SetAwake(b2BodyId bodyId, bool awake)
Wake a body from sleep.
B2_API void b2Body_SetFixedRotation(b2BodyId bodyId, bool flag)
Set this body to have fixed rotation. This causes the mass to be reset in all cases.
B2_API bool b2Body_IsEnabled(b2BodyId bodyId)
Returns true if this body is enabled.
B2_API void b2Body_Disable(b2BodyId bodyId)
Disable a body by removing it completely from the simulation. This is expensive.
B2_API bool b2Body_IsFixedRotation(b2BodyId bodyId)
Does this body have fixed rotation?
b2BodyType
The body simulation type.
Definition types.h:158
B2_API void b2Body_EnableSleep(b2BodyId bodyId, bool enableSleep)
Enable or disable sleeping for this body. If sleeping is disabled the body will wake.
B2_API bool b2Body_IsBullet(b2BodyId bodyId)
Is this body a bullet?
B2_API bool b2Body_IsAwake(b2BodyId bodyId)
@ b2_kinematicBody
zero mass, velocity set by user, moved by solver
Definition types.h:163

Please see the comments on these functions for more details.

Position and Velocity

You can access the position and rotation of a body. This is common when rendering your associated game object. You can also set the position and angle, although this is less common since you will normally use Box2D to simulate movement.

Keep in mind that the Box2D interface uses radians.

b2Body_SetTransform(myBodyId, position, rotation);
b2Transform transform = b2Body_GetTransform(myBodyId);
b2Vec2 position = b2Body_GetPosition(myBodyId);
b2Rot rotation = b2Body_GetRotation(myBodyId);
float angleInRadians = b2Rot_GetAngle(rotation);
B2_API b2Vec2 b2Body_GetPosition(b2BodyId bodyId)
Get the world position of a body. This is the location of the body origin.
B2_API void b2Body_SetTransform(b2BodyId bodyId, b2Vec2 position, b2Rot rotation)
Set the world transform of a body.
B2_API b2Transform b2Body_GetTransform(b2BodyId bodyId)
Get the world transform of a body.
B2_API b2Rot b2Body_GetRotation(b2BodyId bodyId)
Get the world rotation of a body as a cosine/sine pair (complex number)
float b2Rot_GetAngle(b2Rot q)
Get the angle in radians in the range [-pi, pi].
Definition math_functions.h:410
2D rotation This is similar to using a complex number for rotation
Definition math_functions.h:38
A 2D rigid transform.
Definition math_functions.h:45

You can access the center of mass position in local and world coordinates. Much of the internal simulation in Box2D uses the center of mass. However, you should normally not need to access it. Instead you will usually work with the body transform. For example, you may have a body that is square. The body origin might be a corner of the square, while the center of mass is located at the center of the square.

b2Vec2 worldCenter = b2Body_GetWorldCenterOfMass(myBodyId);
b2Vec2 localCenter = b2Body_GetLocalCenterOfMass(myBodyId);
B2_API b2Vec2 b2Body_GetWorldCenterOfMass(b2BodyId bodyId)
Get the center of mass position of the body in world space.

You can access the linear and angular velocity. The linear velocity is for the center of mass. Therefore, the linear velocity may change if the mass properties change. Since Box2D uses radians, the angular velocity is in radians per second.

b2Vec2 linearVelocity = b2Body_GetLinearVelocity(myBodyId);
float angularVelocity = b2Body_GetAngularVelocity(myBodyId);
B2_API float b2Body_GetAngularVelocity(b2BodyId bodyId)
Get the angular velocity of a body in radians per second.
B2_API b2Vec2 b2Body_GetLinearVelocity(b2BodyId bodyId)
Get the linear velocity of a body's center of mass. Usually in meters per second.

You can drive a body to a specific transform. This is useful for kinematic bodies.

b2Vec2 targetPosition = {42.0f, -100.0f};
b2Rot targetRotation = b2MakeRot(B2_PI);
b2Transform target = {targetPosition, targetRotation};
float timeStep = 1.0f / 60.0f;
b2Body_SetTargetTransform(myBodyId, target, timeStep);
B2_API void b2Body_SetTargetTransform(b2BodyId bodyId, b2Transform target, float timeStep)
Set the velocity to reach the given transform after a given time step.
b2Rot b2MakeRot(float radians)
Make a rotation using an angle in radians.
Definition math_functions.h:355
#define B2_PI
https://en.wikipedia.org/wiki/Pi
Definition math_functions.h:79

Forces and Impulses

You can apply forces, torques, and impulses to a body. When you apply a force or an impulse, you can provide a world point where the load is applied. This often results in a torque about the center of mass.

b2Body_ApplyForce(myBodyId, force, worldPoint, wake);
b2Body_ApplyTorque(myBodyId, torque, wake);
b2Body_ApplyLinearImpulse(myBodyId, linearImpulse, worldPoint, wake);
b2Body_ApplyAngularImpulse(myBodyId, angularImpulse, wake);
B2_API void b2Body_ApplyLinearImpulse(b2BodyId bodyId, b2Vec2 impulse, b2Vec2 point, bool wake)
Apply an impulse at a point.
B2_API void b2Body_ApplyForce(b2BodyId bodyId, b2Vec2 force, b2Vec2 point, bool wake)
Apply a force at a world point.
B2_API void b2Body_ApplyTorque(b2BodyId bodyId, float torque, bool wake)
Apply a torque.
B2_API void b2Body_ApplyAngularImpulse(b2BodyId bodyId, float impulse, bool wake)
Apply an angular impulse.

Applying a force, torque, or impulse optionally wakes the body. If you don't wake the body and it is asleep, then the force or impulse will be ignored.

You can also apply a force and linear impulse to the center of mass to avoid rotation.

b2Body_ApplyForceToCenter(myBodyId, force, wake);
b2Body_ApplyLinearImpulseToCenter(myBodyId, linearImpulse, wake);
B2_API void b2Body_ApplyForceToCenter(b2BodyId bodyId, b2Vec2 force, bool wake)
Apply a force to the center of mass.
B2_API void b2Body_ApplyLinearImpulseToCenter(b2BodyId bodyId, b2Vec2 impulse, bool wake)
Apply an impulse to the center of mass.

Caution: Since Box2D uses sub-stepping, you should not apply a steady impulse for several frames. Instead you should apply a force which Box2D will spread out evenly across the sub-steps, resulting in smoother movement.

Coordinate Transformations

The body has some utility functions to help you transform points and vectors between local and world space. If you don't understand these concepts, I recommend reading "Essential Mathematics for Games and Interactive Applications" by Jim Van Verth and Lars Bishop.

b2Vec2 worldPoint = b2Body_GetWorldPoint(myBodyId, localPoint);
b2Vec2 worldVector = b2Body_GetWorldVector(myBodyId, localVector);
b2Vec2 localPoint = b2Body_GetLocalPoint(myBodyId, worldPoint);
b2Vec2 localVector = b2Body_GetLocalVector(myBodyId, worldVector);
B2_API b2Vec2 b2Body_GetLocalVector(b2BodyId bodyId, b2Vec2 worldVector)
Get a local vector on a body given a world vector.
B2_API b2Vec2 b2Body_GetWorldVector(b2BodyId bodyId, b2Vec2 localVector)
Get a world vector on a body given a local vector.
B2_API b2Vec2 b2Body_GetLocalPoint(b2BodyId bodyId, b2Vec2 worldPoint)
Get a local point on a body given a world point.
B2_API b2Vec2 b2Body_GetWorldPoint(b2BodyId bodyId, b2Vec2 localPoint)
Get a world point on a body given a local point.

Accessing Shapes and Joints

You can access the shapes on a body. You can get the number of shapes first.

int shapeCount = b2Body_GetShapeCount(myBodyId);
B2_API int b2Body_GetShapeCount(b2BodyId bodyId)
Get the number of shapes on this body.

If you have bodies with many shapes, you can allocate an array or if you know the number is limited you can use a fixed size array.

b2ShapeId shapeIds[10];
int returnCount = b2Body_GetShapes(myBodyId, shapeIds, 10);
for (int i = 0; i < returnCount; ++i)
{
b2ShapeId shapeId = shapeIds[i];
// do something with shapeId
}
B2_API int b2Body_GetShapes(b2BodyId bodyId, b2ShapeId *shapeArray, int capacity)
Get the shape ids for all shapes on this body, up to the provided capacity.
Shape id references a shape instance. This should be treated as an opaque handle.
Definition id.h:53

You can similarly get an array of the joints on a body.

Body Events

While you can gather transforms from all your bodies after every time step, this is inefficient. Many bodies may not have moved because they are sleeping. Also iterating across many bodies will have lots of cache misses.

Box2D provides b2BodyEvents that you can access after every call to b2World_Step() to get an array of body movement events. Since this data is contiguous, it is cache friendly.

b2BodyEvents events = b2World_GetBodyEvents(m_worldId);
for (int i = 0; i < events.moveCount; ++i)
{
const b2BodyMoveEvent* event = events.moveEvents + i;
MyGameObject* gameObject = event->userData;
MoveGameObject(gameObject, event->transform);
if (event->fellAsleep)
{
SleepGameObject(gameObject);
}
}
b2BodyMoveEvent * moveEvents
Array of move events.
Definition types.h:1144
int moveCount
Number of move events.
Definition types.h:1147
Body events are buffered in the Box2D world and are available as event arrays after the time step is ...
Definition types.h:1142
Body move events triggered when a body moves.
Definition types.h:1131
B2_API b2BodyEvents b2World_GetBodyEvents(b2WorldId worldId)
Get the body events for the current time step. The event data is transient. Do not store a reference ...

The body event also indicates if the body fell asleep this time step. This might be useful to optimize your application.

Shapes

A body may have zero or more shapes. A body with multiple shapes is sometimes called a compound body.

Shapes hold the following:

  • a shape primitive
  • density, friction, and restitution
  • collision filtering flags
  • parent body id
  • user data
  • sensor flag

These are described in the following sections.

Shape Lifetime

Shapes are created by initializing a shape definition and a shape primitive. These are passed to a creation function specific to each shape type.

shapeDef.density = 10.0f;
shapeDef.material.friction = 0.7f;
b2Polygon box = b2MakeBox(0.5f, 1.0f);
b2ShapeId myShapeId = b2CreatePolygonShape(myBodyId, &shapeDef, &box);
b2Polygon b2MakeBox(float halfWidth, float halfHeight)
Make a box (rectangle) polygon, bypassing the need for a convex hull.
A solid convex polygon.
Definition collision.h:134
b2SurfaceMaterial material
The surface material for this shape.
Definition types.h:373
float density
The density, usually in kg/m^2.
Definition types.h:378
float friction
The Coulomb (dry) friction coefficient, usually in the range [0,1].
Definition types.h:338
B2_API b2ShapeId b2CreatePolygonShape(b2BodyId bodyId, const b2ShapeDef *def, const b2Polygon *polygon)
Create a polygon shape and attach it to a body.
b2ShapeDef b2DefaultShapeDef(void)
Use this to initialize your shape definition.
Used to create a shape.
Definition types.h:368

This creates a polygon and attaches it to the body. You do not need to store the shape id since the shape will automatically be destroyed when the parent body is destroyed. However, you may wish to store the shape id if you plan to change properties on it later.

You can create multiple shapes on a single body. They all can contribute to the mass of the body. These shapes never collide with each other and may overlap.

You can destroy a shape on the parent body. 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.

b2DestroyShape(myShapeId);
B2_API void b2DestroyShape(b2ShapeId shapeId, bool updateBodyMass)
Destroy a shape.

Material properties such as density, friction, and restitution are associated with shapes instead of bodies. Since you can attach multiple shapes to a body, this allows for more possible setups. For example, you can make a car that is heavier in the back.

Density

The shape density is used to compute the mass properties of the parent body. The density can be zero or positive. You should generally use similar densities for all your shapes. This will improve stacking stability.

The mass of a body is not adjusted when you set the density. You must call b2Body_ApplyMassFromShapes() for this to occur. Generally you should establish the shape density in b2ShapeDef and avoid modifying it later because this can be expensive, especially on a compound body.

b2Shape_SetDensity(myShapeId, 5.0f);
B2_API void b2Shape_SetDensity(b2ShapeId shapeId, float density, bool updateBodyMass)
Set the mass density of a shape, usually in kg/m^2.

Friction

Friction is used to make objects slide along each other realistically. Box2D supports static and dynamic friction, but uses the same parameter for both. Box2D attempts to simulate friction accurately and the friction strength is proportional to the normal force. This is called Coulomb friction. The friction parameter is usually set between 0 and 1, but can be any non-negative value. A friction value of 0 turns off friction and a value of 1 makes the friction strong. When the friction force is computed between two shapes, Box2D must combine the friction parameters of the two parent shapes. This is done with the geometric mean:

float mixedFriction = sqrtf(b2Shape_GetFriction(shapeIdA) * b2Shape_GetFriction(shapeIdB));
B2_API float b2Shape_GetFriction(b2ShapeId shapeId)
Get the friction of a shape.

If one shape has zero friction then the mixed friction will be zero.

Restitution

Restitution is used to make objects bounce. The restitution value is usually set to be between 0 and 1. Consider dropping a ball on a table. A value of zero means the ball won't bounce. This is called an inelastic collision. A value of one means the ball's velocity will be exactly reflected. This is called a perfectly elastic collision. Restitution is combined using the following formula.

float mixedRestitution = b2MaxFloat(b2Shape_GetRestitution(shapeIdA), b2Shape_GetRestitution(shapeIdB));
float b2MaxFloat(float a, float b)
Definition math_functions.h:117
B2_API float b2Shape_GetRestitution(b2ShapeId shapeId)
Get the shape restitution.

Restitution is combined this way so that you can have a bouncy super ball without having a bouncy floor.

When a shape develops multiple contacts, restitution is simulated approximately. This is because Box2D uses a sequential solver. Box2D also uses inelastic collisions when the collision velocity is small. This is done to prevent jitter. See b2WorldDef::restitutionThreshold.

Friction and restitution callbacks

Advanced users can override friction and restitution mixing using b2FrictionCallback and b2RestitutionCallback. These should be very light weight functions because they are called frequently. See the API reference for details.

float MyFrictionCallback(float frictionA, int userMaterialIdA, float frictionB, int userMaterialIdB)
{
if (userMaterialIdA > userMaterialIdB)
{
return frictionA;
}
return frictionB;
}
worldDef.frictionCallback = MyFrictionCallback;
b2FrictionCallback * frictionCallback
Optional mixing callback for friction. The default uses sqrt(frictionA * frictionB).
Definition types.h:114

Filtering

Collision filtering allows you to efficiently prevent collision between shapes. For example, say you make a character that rides a bicycle. You want the bicycle to collide with the terrain and the character to collide with the terrain, but you don't want the character to collide with the bicycle (because they must overlap). Box2D supports such collision filtering using categories, masks, and groups.

Box2D supports 64 collision categories. For each shape you can specify which category it belongs to. You can also specify what other categories this shape can collide with. For example, you could specify in a multiplayer game that players don't collide with each other. Rather than identifying all the situations where things should not collide, I recommend identifying all the situations where things should collide. This way you don't get into situations where you are using double negatives. You can specify which things can collide using mask bits. For example:

enum MyCategories
{
PLAYER = 0x00000002,
MONSTER = 0x00000004,
};
b2ShapeDef playerShapeDef = b2DefaultShapeDef();
b2ShapeDef monsterShapeDef = b2DefaultShapeDef();
playerShapeDef.filter.categoryBits = PLAYER;
monsterShapeDef.filter.categoryBits = MONSTER;
// Players collide with monsters, but not with other players
playerShapeDef.filter.maskBits = MONSTER;
// Monsters collide with players and other monsters
monsterShapeDef.filter.maskBits = PLAYER | MONSTER;
uint64_t maskBits
The collision mask bits.
Definition types.h:277
uint64_t categoryBits
The collision category bits.
Definition types.h:268
b2Filter filter
Collision filtering data.
Definition types.h:381

Here is the rule for a collision to occur:

uint64_t catA = shapeA.filter.categoryBits;
uint64_t maskA = shapeA.filter.maskBits;
uint64_t catB = shapeB.filter.categoryBits;
uint64_t maskB = shapeB.filter.maskBits;
if ((catA & maskB) != 0 && (catB & maskA) != 0)
{
// shapes can collide
}

Another filtering feature is collision group. Collision groups let you specify a group index. You can have all shapes with the same group index always collide (positive index) or never collide (negative index). Group indices are usually used for things that are somehow related, like the parts of a bicycle. In the following example, shape1 and shape2 always collide, but shape3 and shape4 never collide.

shape1Def.filter.groupIndex = 2;
shape2Def.filter.groupIndex = 2;
shape3Def.filter.groupIndex = -8;
shape4Def.filter.groupIndex = -8;

Collisions between shapes of different group indices are filtered according the category and mask bits. If two shapes have the same non-zero group index, then this overrides the category and mask. Collision groups have a higher priority than categories and masks.

Note that additional collision filtering occurs automatically in Box2D. Here is a list:

  • A shape on a static body can only collide with a dynamic body.
  • A shape on a kinematic body can only collide with a dynamic body.
  • Shapes on the same body never collide with each other.
  • You can optionally enable/disable collision between bodies connected by a joint.

Sometimes you might need to change collision filtering after a shape has already been created. You can get and set the b2Filter structure on an existing shape using b2Shape_GetFilter() and b2Shape_SetFilter(). Changing the filter is expensive because it causes contacts to be destroyed.

Chain Shapes

The chain shape provides an efficient way to connect many line segments together to construct your static game worlds. Chain shapes automatically eliminate ghost collisions and provide one-sided collision.

If you don't care about ghost collisions, you can create a bunch of two-sided segment shapes. The performance is similar.

The simplest way to use chain shapes is to create loops. Simply provide an array of vertices.

b2Vec2 points[4] = {
{1.7f, 0.0f},
{1.0f, 0.25f},
{0.0f, 0.0f},
{-1.7f, 0.4f}};
chainDef.points = points;
chainDef.count = 4;
b2ChainId myChainId = b2CreateChain(myBodyId, &chainDef);
// Later ...
b2DestroyChain(myChainId);
// Nullify id for safety
myChainId = b2_nullChainId;
Chain id references a chain instances. This should be treated as an opaque handle.
Definition id.h:61
int count
The point count, must be 4 or more.
Definition types.h:443
const b2Vec2 * points
An array of at least 4 points. These are cloned and may be temporary.
Definition types.h:440
b2ChainDef b2DefaultChainDef(void)
Use this to initialize your chain definition.
B2_API b2ChainId b2CreateChain(b2BodyId bodyId, const b2ChainDef *def)
Chain Shape.
B2_API void b2DestroyChain(b2ChainId chainId)
Destroy a chain shape.
Used to create a chain of line segments.
Definition types.h:435

The segment normal depends on the winding order. A counter-clockwise winding order orients the normal outwards and a clockwise winding order orients the normal inwards.

Chain Shape Outwards Loop
Chain Shape Inwards Loop

You may have a scrolling game world and would like to connect several chains together. You can connect chains together using ghost vertices. To do this you must have the first three or last three points of each chain overlap. See the sample ChainLink for details.

Chain Shape

Self-intersection of chain shapes is not supported. It might work, it might not. The code that prevents ghost collisions assumes there are no self-intersections of the chain. Also, very close vertices can cause problems. Make sure all your points are more than than about a centimeter apart.

Self Intersection is Bad

Each segment in the chain is created as a b2ChainSegment shape on the body. If you have the shape id for a chain segment shape, you can get the owning chain id. This will return b2_nullChainId if the shape is not a chain segment.

b2ChainId chainId = b2SHape_GetParentChain(myShapeId);

You cannot create a chain segment shape directly.

Sensors

Sometimes game logic needs to know when two shapes overlap yet there should be no collision response. This is done by using sensors. A sensor is a shape that detects overlap but does not produce a response.

You can flag any shape as being a sensor. Sensors may be static, kinematic, or dynamic. Remember that you may have multiple shapes per body and you can have any mix of sensors and solid shapes. Sensors can also detect other sensors.

shapeDef.isSensor = true;
bool isSensor
A sensor shape generates overlap events but never generates a collision response.
Definition types.h:388

For both sensors and non-sensors, sensor events must also be enabled. There is a performance cost to generate sensor events, so they are disabled by default.

shapeDef.enableSensorEvents = true;
bool enableSensorEvents
Enable sensor events for this shape. This applies to sensors and non-sensors. False by default,...
Definition types.h:391

Sensors are processed at the end of the world step and generate begin and end events without delay. User operations may cause overlaps to begin or end. These are processed the next time step. Such operations include:

  • destroying a body or shape
  • changing a shape filter
  • disabling or enabling a body
  • setting a body transform
  • disabling or enabling sensor events on a shape

Sensors do not detect objects that pass through the sensor shape within one time step. So sensors do not have continuous collision detection. If you have fast moving object and/or small sensors then you should use a ray or shape cast to detect these events.

You can access the current sensor overlaps. Be careful because some shape ids may be invalid due to a shape being destroyed. Use b2Shape_IsValid to ensure an overlapping shape is still valid.

// First determine the required array capacity to hold all the overlapping shape ids.
int capacity = b2Shape_GetSensorCapacity( sensorShapeId );
std::vector<b2ShapeId> overlaps;
overlaps.resize( capacity );
// Now get all overlaps and record the actual count
int count = b2Shape_GetSensorOverlaps( sensorShapeId, overlaps.data(), capacity );
overlaps.resize( count );
for ( int i = 0; i < count; ++i )
{
b2ShapeId visitorId = overlaps[i];
// Ensure the visitorId is valid
if ( b2Shape_IsValid( visitorId ) == false )
{
continue;
}
// process overlap using game logic
}
B2_API int b2Shape_GetSensorOverlaps(b2ShapeId shapeId, b2ShapeId *overlaps, int capacity)
Get the overlapped shapes for a sensor shape.
B2_API bool b2Shape_IsValid(b2ShapeId id)
Shape identifier validation. Provides validation for up to 64K allocations.
B2_API int b2Shape_GetSensorCapacity(b2ShapeId shapeId)
Get the maximum capacity required for retrieving all the overlapped shapes on a sensor shape.

Sensor overlap can also be determined using events, which are described below.

Sensor Events

Sensor events are available after every call to b2World_Step(). Sensor events are the best way to get information about sensors overlaps. There are events for when a shape begins to overlap with a sensor.

b2SensorEvents sensorEvents = b2World_GetSensorEvents(myWorldId);
for (int i = 0; i < sensorEvents.beginCount; ++i)
{
b2SensorBeginTouchEvent* beginTouch = sensorEvents.beginEvents + i;
void* myUserData = b2Shape_GetUserData(beginTouch->visitorShapeId);
// process begin event
}
int beginCount
The number of begin touch events.
Definition types.h:1040
b2ShapeId visitorShapeId
The id of the dynamic shape that began touching the sensor shape.
Definition types.h:1007
b2SensorBeginTouchEvent * beginEvents
Array of sensor begin touch events.
Definition types.h:1034
A begin touch event is generated when a shape starts to overlap a sensor shape.
Definition types.h:1002
Sensor events are buffered in the Box2D world and are available as begin/end overlap event arrays aft...
Definition types.h:1032
B2_API void * b2Shape_GetUserData(b2ShapeId shapeId)
Get the user data for a shape.
B2_API b2SensorEvents b2World_GetSensorEvents(b2WorldId worldId)
Get sensor events for the current time step. The event data is transient. Do not store a reference to...

And there are events when a shape stops overlapping with a sensor. Be careful with end touch events because they may be generated when shapes are destroyed. Test the shape ids with b2Shape_IsValid.

for (int i = 0; i < sensorEvents.endCount; ++i)
{
b2SensorEndTouchEvent* endTouch = sensorEvents.endEvents + i;
{
void* myUserData = b2Shape_GetUserData(endTouch->visitorShapeId);
// process end event
}
}
b2SensorEndTouchEvent * endEvents
Array of sensor end touch events.
Definition types.h:1037
b2ShapeId visitorShapeId
The id of the dynamic shape that stopped touching the sensor shape.
Definition types.h:1024
int endCount
The number of end touch events.
Definition types.h:1043
An end touch event is generated when a shape stops overlapping a sensor shape.
Definition types.h:1015

Sensor events should be processed after the world step and before other game logic. This should help you avoid processing stale data.

Sensor events are only enabled for shapes and sensors if b2ShapeDef::enableSensorEvents is set to true.

Note: A shape cannot start or stop being a sensor. Such a feature would break sensor events, potentially causing bugs in game logic.

Contacts

Contacts are internal objects created by Box2D to manage collision between pairs of shapes. They are fundamental to rigid body simulation in games.

Terminology

Contacts have a fair bit of terminology that are important to review.

contact point

A contact point is a point where two shapes touch. Box2D approximates contact with a small number of points. Specifically, contact between two shapes has 0, 1, or 2 points. This is possible because Box2D uses convex shapes.

contact normal

A contact normal is a unit vector that points from one shape to another. By convention, the normal points from shapeA to shapeB.

contact separation

Separation is the opposite of penetration. Separation is negative when shapes overlap.

contact manifold

Contact between two convex polygons may generate up to 2 contact points. Both of these points use the same normal, so they are grouped into a contact manifold, which is an approximation of a continuous region of contact.

normal impulse

The normal force is the force applied at a contact point to prevent the shapes from penetrating. For convenience, Box2D uses impulses. The normal impulse is just the normal force multiplied by the time step. Since Box2D uses sub-stepping, this is the sub-step time step.

tangent impulse

The tangent force is generated at a contact point to simulate friction. For convenience, this is stored as an impulse.

contact point id

Box2D tries to re-use the contact impulse results from a time step as the initial guess for the next time step. Box2D uses contact point ids to match contact points across time steps. The ids contain geometric feature indices that help to distinguish one contact point from another.

speculative contact

When two shapes are close together, Box2D will create up to two contact points even if the shapes are not touching. This lets Box2D anticipate collision to improve behavior. Speculative contact points have positive separation.

Contact Lifetime

Contacts are created when two shape's AABBs (bounding boxes) begin to overlap. Sometimes collision filtering will prevent the creation of contacts. 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 because it lets the system cache information to improve performance.

Contact Data

As mentioned before, the contact is created and destroyed by Box2D automatically. Contact data is not created by the user. However, you are able to access the contact data.

You can get contact data from shapes or bodies. The contact data on a shape is a sub-set of the contact data on a body. The contact data is only returned for touching contacts. Contacts that are not touching provide no meaningful information for an application.

Contact data is returned in arrays. So first you can ask a shape or body how much space you'll need in your array. This number is conservative and the actual number of contacts you'll receive may be less than this number, but never more.

int shapeContactCapacity = b2Shape_GetContactCapacity(myShapeId);
int bodyContactCapacity = b2Body_GetContactCapacity(myBodyId);
B2_API int b2Body_GetContactCapacity(b2BodyId bodyId)
Get the maximum capacity required for retrieving all the touching contacts on a body.
B2_API int b2Shape_GetContactCapacity(b2ShapeId shapeId)
Get the maximum capacity required for retrieving all the touching contacts on a shape.

You could allocate array space to get all the contact data in all cases, or you could use a fixed size array and get a limited number of results.

b2ContactData contactData[10];
int shapeContactCount = b2Shape_GetContactData(myShapeId, contactData, 10);
int bodyContactCount = b2Body_GetContactData(myBodyId, contactData, 10);
B2_API int b2Body_GetContactData(b2BodyId bodyId, b2ContactData *contactData, int capacity)
Get the touching contact data for a body.
The contact data for two shapes.
Definition types.h:1154
B2_API int b2Shape_GetContactData(b2ShapeId shapeId, b2ContactData *contactData, int capacity)
Get the touching contact data for a shape.

b2ContactData contains the two shape ids and the manifold.

for (int i = 0; i < bodyContactCount; ++i)
{
b2ContactData* data = contactData + i;
printf("point count = %d\n", data->manifold.pointCount);
}
int pointCount
The number of contacts points, will be 0, 1, or 2.
Definition collision.h:550

Getting contact data off shapes and bodies is not the most efficient way to handle contact data. Instead you should use contact events.

Contact Events

Contact events are available after each world step. Like sensor events these should be retrieved and processed before performing other game logic. Otherwise you may be accessing orphaned/invalid data.

You can access all contact events in a single data structure. This is much more efficient than using functions like b2Body_GetContactData().

b2ContactEvents contactEvents = b2World_GetContactEvents(myWorldId);
Contact events are buffered in the Box2D world and are available as event arrays after the time step ...
Definition types.h:1100
B2_API b2ContactEvents b2World_GetContactEvents(b2WorldId worldId)
Get contact events for this current time step. The event data is transient. Do not store a reference ...

None of this data applies to sensors because they are handled separately. All events involve at least one dynamic body.

There are three kinds of contact events:

  1. Begin touch events
  2. End touch events
  3. Hit events

Contact Touch Event

b2ContactBeginTouchEvent is recorded when two shapes begin touching. These only contain the two shape ids.

for (int i = 0; i < contactEvents.beginCount; ++i)
{
b2ContactBeginTouchEvent* beginEvent = contactEvents.beginEvents + i;
ShapesStartTouching(beginEvent->shapeIdA, beginEvent->shapeIdB);
}
b2ContactBeginTouchEvent * beginEvents
Array of begin touch events.
Definition types.h:1102
b2ShapeId shapeIdA
Id of the first shape.
Definition types.h:1050
b2ShapeId shapeIdB
Id of the second shape.
Definition types.h:1053
int beginCount
Number of begin touch events.
Definition types.h:1111
A begin touch event is generated when two shapes begin touching.
Definition types.h:1048

b2ContactEndTouchEvent is recorded when two shapes stop touching. These only contain the two shape ids.

for (int i = 0; i < contactEvents.endCount; ++i)
{
b2ContactEndTouchEvent* endEvent = contactEvents.endEvents + i;
// Use b2Shape_IsValid because a shape may have been destroyed
if (b2Shape_IsValid(endEvent->shapeIdA) && b2Shape_IsValid(endEvent->shapeIdB))
{
ShapesStopTouching(endEvent->shapeIdA, endEvent->shapeIdB);
}
}
b2ShapeId shapeIdB
Id of the second shape.
Definition types.h:1074
b2ShapeId shapeIdA
Id of the first shape.
Definition types.h:1069
b2ContactEndTouchEvent * endEvents
Array of end touch events.
Definition types.h:1105
int endCount
Number of end touch events.
Definition types.h:1114
An end touch event is generated when two shapes stop touching.
Definition types.h:1065

Similar to b2SensorEndTouchEvent, b2ContactEndTouchEvent may be generated due to a user operation, such as destroying a body or shape. These events are included with simulation events after the next b2World_Step.

Shapes only generate begin and end touch events if b2ShapeDef::enableContactEvents is true.

Hit Events

Typically in games you are mainly concerned about getting contact events for when two shapes collide at a significant speed so you can play a sound and/or particle effect. Hit events are the answer for this.

for (int i = 0; i < contactEvents.hitCount; ++i)
{
b2ContactHitEvent* hitEvent = contactEvents.hitEvents + i;
if (hitEvent->approachSpeed > 10.0f)
{
// play sound
}
}
int hitCount
Number of hit events.
Definition types.h:1117
float approachSpeed
The speed the shapes are approaching. Always positive. Typically in meters per second.
Definition types.h:1093
b2ContactHitEvent * hitEvents
Array of hit events.
Definition types.h:1108
A hit touch event is generated when two shapes collide with a speed faster than the hit speed thresho...
Definition types.h:1079

Shapes only generate hit events if b2ShapeDef::enableHitEvents is true. I recommend you only enable this for shapes that need hit events because it creates some overhead. Box2D also only reports hit events that have an approach speed larger than b2WorldDef::hitEventThreshold.

Contact Filtering

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.

Contact filtering is setup on shapes and is covered here.

Advanced Contact Handling

Custom Filtering Callback

For the best performance, use the contact filtering provided by b2Filter. However, in some cases you may need custom filtering. You can do this by registering a custom filter callback that implements b2CustomFilterFcn().

bool MyCustomFilter(b2ShapeId shapeIdA, b2ShapeId shapeIdB, void* context)
{
MyGame* myGame = context;
return myGame->WantsCollision(shapeIdA, shapeIdB);
}
// Elsewhere
b2World_SetCustomFilterCallback(myWorldId, MyCustomFilter, myGame);
B2_API void b2World_SetCustomFilterCallback(b2WorldId worldId, b2CustomFilterFcn *fcn, void *context)
Register the custom filter callback. This is optional.

This function must be thread-safe and must not read from or write to the Box2D world. Otherwise you will get a race condition.

Pre-Solve Callback

This is called after collision detection, but before collision resolution. This gives you a chance to disable the contact based on the contact geometry. For example, you can implement a one-sided platform using this callback.

The contact will be re-enabled each time through collision processing, so you will need to disable the contact every time-step. This function must be thread-safe and must not read from or write to the Box2D world.

bool MyPreSolve(b2ShapeId shapeIdA, b2ShapeId shapeIdB, b2Manifold* manifold, void* context)
{
MyGame* myGame = context;
if (myGame->IsHittingBelowPlatform(shapeIdA, shapeIdB, manifold))
{
return false;
}
return true;
}
// Elsewhere
b2World_SetPreSolveCallback(myWorldId, MyPreSolve, myGame);
A contact manifold describes the contact points between colliding shapes.
Definition collision.h:539
B2_API void b2World_SetPreSolveCallback(b2WorldId worldId, b2PreSolveFcn *fcn, void *context)
Register the pre-solve callback. This is optional.

Note this currently does not work with high speed collisions, so you may see a pause in those situations.

See the Platformer sample for more details.

Joints

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 joints provide motors which can be used to drive the joint at a prescribed speed until a prescribed force/torque is exceeded. And some joints provide springs with damping.

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.

Joint Definition

Each joint type has an associated joint definition. All joints are connected between two different bodies. One body may be static. Joints between static and/or kinematic bodies are allowed, but have no effect and use some processing time.

If a joint is connected to a disabled body, that joint is effectively disabled. When the both bodies on a joint become enabled, the joint will automatically be enabled as well. In other words, you do not need to explicitly enable or disable a joint.

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 the default behavior and you must set the collideConnected Boolean to allow collision between two 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. Additionally, some joint definitions need a reference angle between the bodies. This may be necessary to constrain rotation correctly.

The rest of the joint definition data depends on the joint type. I cover these below.

Joint Lifetime

Joints are created using creation functions supplied for each joint type. They are destroyed with a shared function. All joint types share a single id type b2JointId.

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

jointDef.bodyIdA = myBodyA;
jointDef.bodyIdB = myBodyB;
jointDef.localAnchorA = (b2Vec2){0.0f, 0.0f};
jointDef.localAnchorB = (b2Vec2){1.0f, 2.0f};
b2JointId myJointId = b2CreateRevoluteJoint(myWorldId, &jointDef);
// ... do stuff ...
b2DestroyJoint(myJointId);
myJointId = b2_nullJointId;
Joint id references a joint instance. This should be treated as an opaque handle.
Definition id.h:69
B2_API void b2DestroyJoint(b2JointId jointId)
Destroy a joint.
b2Vec2 localAnchorB
The local anchor point relative to bodyB's origin.
Definition types.h:791
b2Vec2 localAnchorA
The local anchor point relative to bodyA's origin.
Definition types.h:788
b2BodyId bodyIdA
The first attached body.
Definition types.h:782
b2BodyId bodyIdB
The second attached body.
Definition types.h:785
b2RevoluteJointDef b2DefaultRevoluteJointDef(void)
Use this to initialize your joint definition.
B2_API b2JointId b2CreateRevoluteJoint(b2WorldId worldId, const b2RevoluteJointDef *def)
Create a revolute joint.
Revolute joint definition.
Definition types.h:780

It is always good to nullify your ids after they are destroyed.

Joint lifetime is related to body lifetime. Joints cannot exist detached from a body. So when a body is destroyed, all joints attached to that body are automatically destroyed. This means you need to be careful to avoid using joint ids when the attached body was destroyed. Box2D will assert if you use a dangling joint id.

Caution: Joints are destroyed when an attached body is destroyed.

Fortunately you can check if your joint id is valid.

if (b2Joint_IsValid(myJointId) == false)
{
myJointId = b2_nullJointId;
}
B2_API bool b2Joint_IsValid(b2JointId id)
Joint identifier validation. Provides validation for up to 64K allocations.

This is certainly useful, but should not be overused because if you are creating and destroying many joints, this may eventually alias to a different joint. All ids have a limit of 64k generations.

Using Joints

Many simulations create the joints and don't access them again until they are destroyed. 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 type, bodies, anchor points, and user data from a joint.

b2JointType jointType = b2Joint_GetType(myJointId);
b2BodyId bodyIdA = b2Joint_GetBodyA(myJointId);
b2BodyId bodyIdB = b2Joint_GetBodyB(myJointId);
b2Vec2 localAnchorA = b2Joint_GetLocalAnchorA(myJointId);
b2Vec2 localAnchorB = b2Joint_GetLocalAnchorB(myJointId);
void* myUserData = b2Joint_GetUserData(myJointId);
B2_API b2JointType b2Joint_GetType(b2JointId jointId)
Get the joint type.
b2JointType
Joint type enumeration.
Definition types.h:520
B2_API void * b2Joint_GetUserData(b2JointId jointId)
Get the user data on a joint.
B2_API b2Vec2 b2Joint_GetLocalAnchorA(b2JointId jointId)
Get the local anchor on bodyA.
B2_API b2BodyId b2Joint_GetBodyB(b2JointId jointId)
Get body B id on a joint.
B2_API b2BodyId b2Joint_GetBodyA(b2JointId jointId)
Get body A id on a joint.
B2_API b2Vec2 b2Joint_GetLocalAnchorB(b2JointId jointId)
Get the local anchor on bodyB.

All joints have a reaction force and torque. Reaction forces are related to the free body diagram. The Box2D convention is that the reaction force is applied to body B 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.

float torque = b2Joint_GetConstraintTorque(myJointId);
B2_API b2Vec2 b2Joint_GetConstraintForce(b2JointId jointId)
Get the current constraint force for this joint. Usually in Newtons.
B2_API float b2Joint_GetConstraintTorque(b2JointId jointId)
Get the current constraint torque for this joint. Usually in Newton * meters.

See the sample BreakableJoint for more details.

Distance Joint

One of the simplest joints 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 local coordinates. The first anchor point is connected to body A, and the second anchor point is connected to body B. These points imply the length of the distance constraint.

Distance Joint

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

jointDef.bodyIdA = myBodyIdA;
jointDef.bodyIdB = myBodyIdB;
jointDef.localAnchorA = (b2Vec2){1.0f, -3.0f};
jointDef.localAnchorB = (b2Vec2){0.0f, 0.5f};
b2Vec2 anchorA = b2Body_GetWorldPoint(myBodyIdA, jointDef.localAnchorA);
b2Vec2 anchorB = b2Body_GetWorldPoint(myBodyIdB, jointDef.localAnchorB);
jointDef.length = b2Distance(anchorA, anchorB);
jointDef.collideConnected = true;
b2JointId myJointId = b2CreateDistanceJoint(myWorldId, &jointDef);
float length
The rest length of this joint. Clamped to a stable minimum value.
Definition types.h:553
b2Vec2 localAnchorA
The local anchor point relative to bodyA's origin.
Definition types.h:547
bool collideConnected
Set this flag to true if the attached bodies should collide.
Definition types.h:584
b2Vec2 localAnchorB
The local anchor point relative to bodyB's origin.
Definition types.h:550
b2BodyId bodyIdB
The second attached body.
Definition types.h:544
b2BodyId bodyIdA
The first attached body.
Definition types.h:541
b2DistanceJointDef b2DefaultDistanceJointDef(void)
Use this to initialize your joint definition.
B2_API b2JointId b2CreateDistanceJoint(b2WorldId worldId, const b2DistanceJointDef *def)
Create a distance joint.
Distance joint definition.
Definition types.h:539
float b2Distance(b2Vec2 a, b2Vec2 b)
Get the distance between two points.
Definition math_functions.h:272

The distance joint can also be made soft, like a spring-damper connection. Softness is achieved by enabling the spring and tuning two values in the definition: Hertz and damping ratio.

jointDef.enableSpring = true;
jointDef.hertz = 2.0f;
jointDef.dampingRatio = 0.5f;
float dampingRatio
The spring linear damping ratio, non-dimensional.
Definition types.h:563
bool enableSpring
Enable the distance constraint to behave like a spring.
Definition types.h:557
float hertz
The spring linear stiffness Hertz, cycles per second.
Definition types.h:560

The hertz is the frequency of a harmonic oscillator (like a guitar string). Typically the frequency should be less than a half the frequency of the time step. So if you are using a 60Hz time step, the frequency of the distance joint should be less than 30Hz. The reason is related to the Nyquist frequency.

The damping ratio controls how fast the oscillations dissipate. A damping ratio of one is critical damping and prevents oscillation.

It is also possible to define a minimum and maximum length for the distance joint. You can even motorize the distance joint to adjust its length dynamically. See b2DistanceJointDef and the DistanceJoint sample for details.

Revolute Joint

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

Revolute Joint

Like all joints, the anchor points are specified in local coordinates. However, you can use the body utility functions to simplify this.

b2Vec2 worldPivot = {10.0f, -4.0f};
jointDef.bodyIdA = myBodyIdA;
jointDef.bodyIdB = myBodyIdB;
jointDef.localAnchorA = b2Body_GetLocalPoint(myBodyIdA, worldPivot);
jointDef.localAnchorB = b2Body_GetLocalPoint(myBodyIdB, worldPivot);
b2JointId myJointId = b2CreateRevoluteJoint(myWorldId, &jointDef);

The revolute joint angle is positive when bodyB rotates counter-clockwise about the anchor point. Like all angles in Box2D, the revolute angle is measured in radians. By convention the revolute joint angle is zero when the two bodies have equal angles. You can offset this using b2RevoluteJointDef::referenceAngle.

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

A joint limit forces the joint angle to remain between a lower and upper angle. 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. The lower and upper limit are relative to the reference angle.

A joint motor allows you to specify the joint speed. The speed can be negative or positive. A motor can have infinite force, but this is usually not desirable. Recall the eternal question:

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.

b2Vec2 worldPivot = {10.0f, -4.0f};
jointDef.bodyIdA = myBodyIdA;
jointDef.bodyIdB = myBodyIdB;
jointDef.localAnchorA = b2Body_GetLocalPoint(myBodyIdA, worldPivot);
jointDef.localAnchorB = b2Body_GetLocalPoint(myBodyIdB, worldPivot);
jointDef.lowerAngle = -0.5f * b2_pi; // -90 degrees
jointDef.upperAngle = 0.25f * b2_pi; // 45 degrees
jointDef.enableLimit = true;
jointDef.maxMotorTorque = 10.0f;
jointDef.motorSpeed = 0.0f;
jointDef.enableMotor = true;
bool enableLimit
Enable/disable the joint limit.
Definition types.h:566
bool enableMotor
Enable/disable the joint motor.
Definition types.h:575
float motorSpeed
The desired motor speed, usually in meters per second.
Definition types.h:581

You can access a revolute joint's angle, speed, and motor torque.

float angleInRadians = b2RevoluteJoint_GetAngle(myJointId);
float speed = b2RevoluteJoint_GetMotorSpeed(myJointId);
float currentTorque = b2RevoluteJoint_GetMotorTorque(myJointId);
B2_API float b2RevoluteJoint_GetMotorSpeed(b2JointId jointId)
Get the revolute joint motor speed in radians per second.
B2_API float b2RevoluteJoint_GetMotorTorque(b2JointId jointId)
Get the revolute joint current motor torque, usually in newton-meters.
B2_API float b2RevoluteJoint_GetAngle(b2JointId jointId)
Get the revolute joint current angle in radians relative to the reference angle.

You also update the motor parameters each step.

B2_API void b2RevoluteJoint_SetMaxMotorTorque(b2JointId jointId, float torque)
Set the revolute joint maximum motor torque, usually in newton-meters.
B2_API void b2RevoluteJoint_SetMotorSpeed(b2JointId jointId, float motorSpeed)
Set the revolute joint motor speed in radians per second.

Joint motors have some interesting abilities. You can update the joint speed every time step so you can make the joint move back-and-forth like a sine-wave or according to whatever function you want.

// ... Game Loop Begin ...
b2RevoluteJoint_SetMotorSpeed(myJointId, cosf(0.5f * time));
// ... Game Loop End ...

You can also use joint motors to track a desired joint angle. For example:

// ... Game Loop Begin ...
float angleError = b2RevoluteJoint_GetAngle(myJointId) - angleTarget;
float gain = 0.1f;
b2RevoluteJoint_SetMotorSpeed(myJointId, -gain * angleError);
// ... Game Loop End ...

Generally your gain parameter should not be too large. Otherwise your joint may become unstable.

Prismatic Joint

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

Prismatic Joint

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:

b2Vec2 worldPivot = {10.0f, -4.0f};
b2Vec2 worldAxis = {1.0f, 0.0f};
b2PrismaticJointDef jointDef = b2DefaultPrismaticJointDef();
jointDef.bodyIdA = myBodyIdA;
jointDef.bodyIdB = myBodyIdB;
jointDef.localAnchorA = b2Body_GetLocalPoint(myBodyIdA, worldPivot);
jointDef.localAnchorB = b2Body_GetLocalPoint(myBodyIdB, worldPivot);
jointDef.localAxisA = b2Body_GetLocalVector(myBodyIdA, worldAxis);
jointDef.lowerTranslation = -5.0f;
jointDef.upperTranslation = 2.5f;
jointDef.enableLimit = true;
jointDef.maxMotorForce = 1.0f;
jointDef.motorSpeed = 0.0f;
jointDef.enableMotor = true;
float lowerTranslation
The lower translation limit.
Definition types.h:739
bool enableMotor
Enable/disable the joint motor.
Definition types.h:745
float motorSpeed
The desired motor speed, typically in meters per second.
Definition types.h:751
b2Vec2 localAnchorB
The local anchor point relative to bodyB's origin.
Definition types.h:718
b2BodyId bodyIdA
The first attached body.
Definition types.h:709
float upperTranslation
The upper translation limit.
Definition types.h:742
bool enableLimit
Enable/disable the joint limit.
Definition types.h:736
b2Vec2 localAnchorA
The local anchor point relative to bodyA's origin.
Definition types.h:715
b2BodyId bodyIdB
The second attached body.
Definition types.h:712
b2Vec2 localAxisA
The local translation unit axis in bodyA.
Definition types.h:721
float maxMotorForce
The maximum motor force, typically in newtons.
Definition types.h:748
Prismatic joint definition.
Definition types.h:707

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 body A.

The prismatic joint translation is zero when the anchor points overlap. I recommend to have the prismatic anchor points close to the center of mass of the two bodies. This will improve joint stiffness.

Using a prismatic joint is similar to using a revolute joint. Here are the relevant member functions:

float PrismaticJoint::GetJointTranslation() const;
float PrismaticJoint::GetJointSpeed() const;
float PrismaticJoint::GetMotorForce() const;
void PrismaticJoint::SetMotorSpeed(float speed);
void PrismaticJoint::SetMotorForce(float force);

Mouse Joint

The mouse joint is used in the samples to manipulate bodies with the mouse. It attempts to drive a point on a body towards the current position of the cursor. There is no restriction on rotation.

The mouse joint definition has a target point, maximum force, Hertz, and damping ratio. The target point initially coincides with the body's anchor point. The maximum force is used to prevent violent reactions when multiple dynamic bodies interact. You can make this as large as you like. The frequency and damping ratio are used to create a spring/damper effect similar to the distance joint.

Weld Joint

The weld joint attempts to constrain all relative motion between two bodies. See the Cantilever sample to see how the weld joint behaves.

It is tempting to use the weld joint to define breakable structures. However, the Box2D solver is approximate so the joints can be soft in some cases regardless of the joint settings. So chains of bodies connected by weld joints may flex.

See the ContactEvent sample for an example of how to merge and split bodies without using the weld joint.

Motor Joint

A motor joint lets you control the motion of a body by specifying target position and rotation offsets. You can set the maximum motor force and torque that will be applied to reach the target position and rotation. If the body is blocked, it will stop and the contact forces will be proportional the maximum motor force and torque. See b2MotorJointDef and the MotorJoint sample for details.

Wheel Joint

The wheel joint restricts a point on bodyB to a line on bodyA. The wheel joint also provides a suspension spring and a motor. See the Driving sample for details.

Wheel Joint

The wheel joint is designed specifically for vehicles. It provides a translation and rotation. The translation has a spring and damper to simulate the vehicle suspension. The rotation allows the wheel to rotate. You can specify an rotational motor to drive the wheel and to apply braking. See b2WheelJointDef and the Drive sample for details.

You may also use the wheel joint where you want free rotation and translation along an axis. See the ScissorLift sample for details.

Spatial Queries

Spatial queries allow you to inspect the world geometrically. There are overlap queries, ray-casts, and shape-casts. These allow you to do things like:

  • find a treasure chest near the player
  • shoot a laser beam and destroy all asteroids in the path
  • throw a grenade that is represented as a circle moving along a parabolic path

Overlap Queries

Sometimes you want to determine all the shapes in a region. The world has a fast log(N) method for this using the broad-phase data structure. Box2D provides these overlap tests:

  • axis-aligned bound box (AABB) overlap
  • shape proxy overlap

Query Filtering

A basic understanding of query filtering is needed before considering the specific queries. Shape versus shape filtering was discussed here. A similar setup is used for queries. This lets your queries only consider certain categories of shapes, it also lets your shapes ignore certain queries.

Just like shapes, queries themselves can have a category. For example, you can have a CAMERA or PROJECTILE category.

enum MyCategories
{
STATIC = 0x00000001,
PLAYER = 0x00000002,
MONSTER = 0x00000004,
WINDOW = 0x00000008,
CAMERA = 0x00000010,
PROJECTILE = 0x00000020,
};
// Grenades collide with the static world, monsters, and windows but
// not players or other projectiles.
b2QueryFilter grenadeFilter;
grenadeFilter.categoryBits = PROJECTILE;
grenadeFilter.maskBits = STATIC | MONSTER | WINDOW;
// The view collides with the static world, monsters, and players.
b2QueryFilter viewFilter;
viewFilter.categoryBits = CAMERA;
viewFilter.maskBits = STATIC | PLAYER | MONSTER;
uint64_t maskBits
The collision mask bits.
Definition types.h:303
uint64_t categoryBits
The collision category bits of this query. Normally you would just set one bit.
Definition types.h:299
The query filter is used to filter collisions between queries and shapes.
Definition types.h:297

If you want to query everything you can use b2DefaultQueryFilter();

AABB Overlap

You provide an AABB in world coordinates and an implementation of b2OverlapResultFcn(). The world calls your function with each shape whose AABB overlaps the query AABB. Return true to continue the query, otherwise return false. For example, the following code finds all the shapes that potentially intersect a specified AABB and wakes up all of the associated bodies.

bool MyOverlapCallback(b2ShapeId shapeId, void* context)
{
b2BodyId bodyId = b2Shape_GetBody(shapeId);
b2Body_SetAwake(bodyId, true);
// Return true to continue the query.
return true;
}
// Elsewhere ...
MyOverlapCallback callback;
b2AABB aabb;
aabb.lowerBound = (b2Vec2){-1.0f, -1.0f};
aabb.upperBound = (b2Vec2){1.0f, 1.0f};
b2World_OverlapAABB(myWorldId, aabb, filter, MyOverlapCallback, &myGame);
Axis-aligned bounding box.
Definition math_functions.h:59
b2QueryFilter b2DefaultQueryFilter(void)
Use this to initialize your query filter.
B2_API b2BodyId b2Shape_GetBody(b2ShapeId shapeId)
Get the id of the body that a shape is attached to.
B2_API b2TreeStats b2World_OverlapAABB(b2WorldId worldId, b2AABB aabb, b2QueryFilter filter, b2OverlapResultFcn *fcn, void *context)
Overlap test for all shapes that potentially overlap the provided AABB.

Do not make any assumptions about the order of the callback. The order shapes are returned to your callback may seem arbitrary.

Shape Overlap

The AABB overlap is very fast but not very accurate because it only considers the shape bounding box. If you want an accurate overlap test, you can use a shape overlap query.

The overlap function uses a b2ShapeProxy which is an abstract shape consisting of some points and a radius. You can think of it as a cloud of circles that has been shrink wrapped. This can represent a point, a circle, a line segment, a capsule, a polygon, a rounded rectangle, and so on. The helper function b2MakeProxy takes an array of points and a radius.

In this example, I'm creating a shape proxy from a circle and then calling b2World_OverlapShape(). This takes a b2OverlapResultFcn() to receive results and control the search progress.

b2Circle circle = {b2Vec2_zero, 0.2f};
b2ShapeProxy proxy = b2MakeProxy(&circle.center, 1, circle.radius);
b2World_OverlapShape(myWorldId, &proxy, grenadeFilter, MyOverlapCallback, &myGame);
b2ShapeProxy b2MakeProxy(const b2Vec2 *points, int count, float radius)
Make a proxy for use in overlap, shape cast, and related functions. This is a deep copy of the points...
float radius
The radius.
Definition collision.h:110
b2Vec2 center
The local center.
Definition collision.h:107
A solid circle.
Definition collision.h:105
A distance proxy is used by the GJK algorithm.
Definition collision.h:42
B2_API b2TreeStats b2World_OverlapShape(b2WorldId worldId, const b2ShapeProxy *proxy, b2QueryFilter filter, b2OverlapResultFcn *fcn, void *context)
Overlap test for all shapes that overlap the provided shape proxy.

Ray-casts

You can use ray-casts to do line-of-sight checks, fire guns, etc. You perform a ray-cast by implementing the b2CastResultFcn() callback function and providing the origin point and translation. The world calls your function with each shape hit by the ray. Your callback is provided with the shape, the point of intersection, the unit normal vector, and the fractional distance along the ray. You cannot make any assumptions about the order of the points sent to the callback. The callback may receive points that are further away before receiving points that are closer.

You control the continuation of the ray-cast by returning a fraction. Returning a fraction of zero indicates the ray-cast should be terminated. A fraction of one indicates the ray-cast should continue as if no hit occurred. If you return the fraction from the argument list, the ray will be clipped to the current intersection point. So you can ray-cast any shape, ray-cast all shapes, or ray-cast the closest shape by returning the appropriate fraction.

You may also return of fraction of -1 to filter the shape. Then the ray-cast will proceed as if the shape does not exist.

Here is an example:

// This struct captures the closest hit shape
struct MyRayCastContext
{
b2ShapeId shapeId;
b2Vec2 point;
b2Vec2 normal;
float fraction;
};
float MyCastCallback(b2ShapeId shapeId, b2Vec2 point, b2Vec2 normal, float fraction, void* context)
{
MyRayCastContext* myContext = context;
myContext->shape = shape;
myContext->point = point;
myContext->normal = normal;
myContext->fraction = fraction;
return fraction;
}
// Elsewhere ...
MyRayCastContext context = {0};
b2Vec2 origin = {-1.0f, 0.0f};
b2Vec2 end(3.0f, 1.0f);
b2Vec2 translation = b2Sub(end, origin);
b2World_CastRay(myWorldId, origin, translation, viewFilter, MyCastCallback, &context);
b2Vec2 b2Sub(b2Vec2 a, b2Vec2 b)
Vector subtraction.
Definition math_functions.h:187
B2_API b2TreeStats b2World_CastRay(b2WorldId worldId, b2Vec2 origin, b2Vec2 translation, b2QueryFilter filter, b2CastResultFcn *fcn, void *context)
Cast a ray into the world to collect shapes in the path of the ray.

Ray-cast results may be delivered in an arbitrary order. This doesn't affect the result for closest point ray-casts (except in ties). When you are collecting multiple hits along the ray, you may want to sort them according to the hit fraction. See the CastWorld sample for details.

Shape-casts

Shape-casts are similar to ray-casts. You can view a ray-cast as tracing a point along a line. A shape-cast allows you to trace a shape along a line. Like the shape overlap query, the shape cast uses a b2ShapeProxy to represent an arbitrary shape.

// This struct captures the closest hit shape
struct MyRayCastContext
{
b2ShapeId shapeId;
b2Vec2 point;
b2Vec2 normal;
float fraction;
};
float MyCastCallback(b2ShapeId shapeId, b2Vec2 point, b2Vec2 normal, float fraction, void* context)
{
MyRayCastContext* myContext = context;
myContext->shape = shape;
myContext->point = point;
myContext->normal = normal;
myContext->fraction = fraction;
return fraction;
}
// Elsewhere ...
MyRayCastContext context = {0};
b2Circle circle = {{-1.0f, 0.0f}, 0.05f};
b2ShapeProxy proxy = b2MakeProxy(&circle.center, 1, circle.radius);
b2Vec2 translation = {10.0f, -5.0f};
b2World_CastCircle(myWorldId, &proxy, translation, grenadeFilter, MyCastCallback, &context);

Otherwise, shape-casts are setup similarly to ray-casts. You can expect shape-casts to generally be slower than ray-casts. So only use a shape-cast if a ray-cast won't do.

Just like ray-casts, shape-casts results may be sent to the callback in any order. If you need multiple sorted results, you will need to write some code to collect and sort the results.

Simulation Loop

Simulation Loop

The Box2D simulation loop can be useful to understand when you process results.

Multithreading is represented in the diagram.

  • rectangles are parallel-for work
  • rounded rectangles are single-threaded work, but may be in parallel with other work

Let's review each of these stages.

time step

The game starts the simulation by calling b2World_Step supplying the time step.

find pairs

Box2D maintains a record of every shape that has moved. For each of these shapes the broad-phase (BVH) is queried for overlaps. New overlaps are recorded for processing in the next step. I avoid reporting existing overlaps by using a hash table that records all existing shape pairs. This operation is a parallel-for.

create contacts

This takes the pair results and creates the internal contact pair structure (b2Contact). This structure is persistent across time steps. It is used for the island graph and holding contact manifolds. This operation is single-threaded but most of the work is done in find pairs.

rebuild BVH

After the new shape pairs are known the BVH is not considered until later in the time step. Therefore the BVH for dynamic and kinematic shapes may be optimized. This involves identifying the part of the collision tree that is stale from refitting and then performing a rebuild of that sub-tree. This is a single-single threaded operation that is done concurrently with other work.

narrow phase

This is where the contact manifolds and points are computed. Each active contact pair is confirmed as touching or non-touching. If the touching state changes then contact begin and end events are generated. This is a parallel-for operation.

Notice that contact points are computed at the beginning of the time step, before bodies have moved and before impulses are known. This is necessary for obtaining good simulation results efficiently. If contacts were computed at the end of the time step then new contact points would not be known to the constraint solver and shapes would sink into each other.

The b2PreSolveFcn is called within the parallel-for so it should be efficient and thread-safe. This is only called for shapes that have enablePreSolveEvents == true.

merge islands

Simulation islands are merged when shapes begin touching. Existing islands that have shapes that stop touching are flagged as candidates for splitting. This stage is single-threaded.

split island

A split island task may be generated if:

  • there is an island that has shapes that stopped touching
  • this island has a body that is moving slow enough to sleep Splitting an island may result in several new islands being created. Only a single island will be split per time step because it is expensive. Delaying the split may delay some bodies from sleeping. This is a single-single threaded operation that is done concurrently with other work.

solve constraints

This solves contact and joint constraints and applies restitution. This a parallel-for with multiple internal stages.

update transforms

This stage does several tasks:

  • updates body transforms
  • updates the body sleeping status
  • generates body move events
  • generates island splitting candidates
  • resets forces and torques
  • updates shape bounding boxes
  • performs continuous collision between dynamic and static bodies This stage is parallel-for.

Note that continuous collision does not generate events. Instead they are generated the next time step. However, continuous collision will issue a b2PreSolveFcn callback.

hit events

Active contacts are scanned for fast approach velocities and added to a buffer. This considers contact points that have an impulse. This includes touching contacts and speculative contacts that generated an impulse (they are confirmed). So you may get hit events for contact points that have a positive separation. This is a single-threaded operation.

refit BVH

This updates the BVH for shapes that have moved significantly. This is done by enlarging the shapes bounding box and all ancestor bounding boxes in the BVH. This is a single-threaded operation.

This can result in an inefficient BVH. This is the reason for the rebuild BVH stage. Refitting is faster than rebuilding the BVH but is necessary to ensure the BVH is valid for subsequent queries, such as ray casts.

bullets

This is where bullets are processed. Not that this comes after hit events because continuous collision in Box2D does not generate events until the next time step.

island sleep

When an island goes to sleep the simulation data associated with that island is moved to separate stored. This keeps the active simulation data contiguous and cache friendly.

sensors

Sensor overlaps are checked in the final stage. The overlap state reflects the final body transform. Sensors do not consider sleep so they may react to the user setting a body transform or creating a sleeping body. This is a parallel-for operation. The cost is roughly proportional to the number of sensors.

Determinism

Box2D is designed to be determinism across thread counts and platforms. I believe this is important for debugging and game design.

Multithreaded determinism is achieved by basing simulation order on creation order. This includes bodies, shapes, and joint creation order. Determinism includes results reported to users (events). These events must be in deterministic order.

Cross-platform determinism is achieved on 64-bit platforms by using compiler flags and by avoiding non-deterministic library functions.

  • precise math is used on MSVC
  • floating point contraction is disabled on clang and GCC
  • Box2D has custom implementations of atan2, cosine, and sine.

Determinism is on by default and there is no explicit option to disable it. However, you can break determinism by choosing different compiler flags. Box2D was designed to provide determinism with minimal cost. So there is no advantage to attempting to disable determinism.

I maintain a unit test for determinism that is run for every pull request. Determinism is easy to break, so it is important to have regular validation.

Caution: Box2D determinism does not mean your application will be deterministic. Consider using similar strategies to make your application deterministic as I have used for Box2D.