Worlds were briefly mentioned in one of the earlier topics as being the main entity in which all the Box2D bodies live. When you create or delete a body, you call a function of the world object to do this, so the world is managing all the allocations for the objects within it too. This means that the world is pretty important, so let's take a look at what we can do with one.

  • define gravity
  • tune the physics simulation
  • find shapes in a given region
  • cast a ray and find intersected shapes
  • simulate 'explosions' that affect all shapes in a region

The last three of these will be covered in a later topic, so right now we will just look at the first of these, and the life cycle of a world. Let's take a quick look at the way it is done.

A world is created by first defining its properties and then calling the creation function:

// Create a global array of Box2D world instances
b2CreateWorldArray();

// Create world definition with default properties
const worldDef = b2DefaultWorldDef();

// Set gravity (normal earth gravity, 9.8 m/s/s straight down!)
worldDef.gravity = new b2Vec2(0, -9.8);

// Create the world and store its Id
const worldId = b2CreateWorld(worldDef);

The gravity setting affects every dynamic object in the world, and can be changed later by using b2World_SetGravity. For example, try adding this to one of the scenes we made earlier to make a zero-gravity world:

b2World_SetGravity(worldId, new b2Vec2(0, 0));

Bodies will automatically sleep when they come to rest, for efficiency. When bodies sleep, they are excluded from the simulation until something happens to 'wake' them again. This could be a collision from another body, a force applied to it etc. You can control this behavior using:

// Enable/disable sleeping
b2World_EnableSleeping(worldId, true); // or false

Once you have a world created as above, you can add bodies into it as we've been doing. To make anything interesting happen, we need to repeatedly call the Step function of the world to run the physics simulation.

const timeStep = 1/20.0;      // the length of time passed to simulate (seconds)
const subStepCount = 8;       // number of sub-steps for internal physics solving

b2World_Step(worldId, timeStep, subStepCount);

In this example, each call to Step will advance the simulation by 1/20th of a second, so a body moving at 5m/s like in our first scene would move 5 * 1/20=0.25m in that time. The timeStep also affects how gravity gets to act on each body. You might find that things appear to fall at different accelerations depending on the time step. To make a realistic looking simulation, you will generally set the timeStep value to match the number of times per second you will be calling the world's Step() function in your game. For example in the testbed, the default framerate is 60 frames per second, so Step() is called 60 times a second with timeStep set to 1/60th of a second.

The subStepCount setting affects the way bodies will react when they collide. Typically in Box2D when a collision between two objects is detected, those objects are overlapping (stuck into other) and some calculation needs to be done to figure out how each body should move or rotate so that they are not overlapping any more. Making this value higher will give you a more correct simulation, at the cost of some performance.

Firstly, these values are only relevant to collision resolution, so if nothing is colliding then they are not used at all. When two things collide, to resolve the collision (push both bodies so they don't overlap any more) they need to have their position and velocity changed. The need for changing the position should be obvious - this is to correct the overlap. The velocity also needs to be changed, for example to make sure that a ball bounces off a wall correctly, or to make something rotate if it is hit off-center.

The exact details of which body should move where, what their new velocities should be, whether their angular velocity should also be affected etc, is handled by an iterative solver. This means that the calculation does not give you a perfect result the first time, but each time you do it the result gets more accurate. Probably the simplest example of iterative solving is the Newton-Raphson method for finding the roots of a function. Here is a nice animated gif showing this procedure (if you are not familiar with 'finding roots', it just means finding the point where the blue function line crosses the x-axis).

Newton-Raphson method animation

As you can see in the animated gif, the same calculation is done over and over, and each time the solution gets closer to the exact result. Typically you would stop doing this calculation when the result does not change much anymore, because that means you are so close to the solution that doing more iterations does not improve the answer a worthwhile amount. If your calculation time is limited, you could stop doing the calculation after a fixed number of iterations, even though the answer you get is not an exact solution.

Typically Box2D is used for fast-paced simulations where an exact solution is not necessary, and at 60 frames per second it's hard to see little imperfections anyway. So we usually want to set an upper limit on how many iterations to do, to keep the CPU time required reasonable.

One way to decide on a good balance of these values for your situation would be to start by setting them really low, even as low as 1 may sometimes be ok for sparse simulations. If you have fast collisions, or many things touching each other all at the same time (especially piles and stacks of bodies) you will need to raise these values to avoid having things penetrating each other and making things look sloppy. At some point, you will find that raising the values further doesn't really help anything.

One last point to note is that these values are only an upper limit. If Box2D decides that the solution it has is good enough, it will stop calculating without using all the iterations you have allowed it. So even if you set these to say, 50, that does not mean it will always take ten times longer than setting it to 5. It only means that in a demanding case (like a big stack of blocks) you have given it permission to take ten times as long. This means that your game could run nice and smooth, until you get a huge pile of things stacked up and then it mysteriously starts to get slow and choppy, so you should check that the values you set will perform ok for all cases that your game is likely to encounter.

Cleaning up

When you're done with a world object, destroy it:

b2DestroyWorld(worldId);

When a world is destroyed like this, it takes care of deleting all the joints and bodies in it. Remember not to use the deleted body IDs after this!

Credits

This tutorial is adapted from an original piece of work created by Chris Campbell and is used under license.