Physics World

Learn about the class b2World

Source Code

The Physics World

The class b2World is the main component of the Box2D library. It represents the Physical World inside which everything will happen. The code below shows how to create a new physical world, as you can see the only parameter required is the value of gravity. The gravity of Earth is approximately 9.8 m/s2 downward, so we’ll be using that.

The method Dump(), is used to print the state of the physical in your console,  since Box2D does not have any graphics, it’s the only way to know what’s happening. Until we integrate SFML and display the physical word inside a nice window we’ll be using the Dump() method for debugging.

In the sections below, I will show you the other most important methods of the b2World class. You don’t have to know how to use them, we’ll learn that later.

// Nero Game Engine - Box2D Tutorials
#include <Box2D/Box2D.h>
int main()
    b2Vec2 gravity(0.f, -9.8f);
    //create the physical world
    b2World physicWorld(gravity);
    //print the world in console
    return 0;

Bodies and Joints

The physical world is composed of rigid Bodies and Joints. Joints are a way to constraint two objects together. For example, in real life, you can attach two objects using a rope, in Box2D you can do that with a Distance Joint or a Rope Joint. In real life, you can put or attach a Wheel to a car, in Box2D you can do the same using a Wheel Joint.

Below you can see the list of methods offered by the class b2World to manage Bodies and Joints

b2Body*             CreateBody(const b2BodyDef* def);
void                DestroyBody(b2Body* body);
b2Joint*            CreateJoint(const b2JointDef* def);
void                DestroyJoint(b2Joint* joint);
b2Body*             GetBodyList();
const b2Body*       GetBodyList() const;
b2Joint*            GetJointList();
const b2Joint*      GetJointList() const;
int32               GetBodyCount() const;
int32               GetJointCount() const;

Physics Simulation

One of the most important methods of the class b2World is the method Step(). All the physics simulations happen during this method call. The first parameter is the time step, for example, if your game runs at 60FPS the time step would be 1/60 seconds. The simulation is done for this exact time step, which means that this method needs to be called at each Game Loop.

void                Step(float32 timeStep, int32 velocityIterations, int32 positionIterations);
bool                IsLocked() const;
void                ClearForces();
void                DrawDebugData();
b2Contact*          GetContactList();
const b2Contact*    GetContactList() const;
int32               GetContactCount() const;

Physical World Properties

The physics simulation can be adjusted by changing certain properties of the physical world. One of these properties is of course gravity. Below you can see the list of methods offered by the class b2World to adjust the world properties

void        SetGravity(const b2Vec2& gravity);
b2Vec2      GetGravity() const;
void        SetAllowSleeping(bool flag);
bool        GetAllowSleeping();
void        SetWarmStarting(bool flag);
bool        GetWarmStarting() const;
void        SetContinuousPhysics(bool flag);
bool        GetContinuousPhysics();
void        SetSubStepping(bool flag);
bool        GetSubStepping();
void        SetAutoClearForces(bool flag);
bool        GetAutoClearForces() const;
void        ShiftOrigin(const b2Vec2& newOrigin);

Callback Classes

During the physics simulation, many things such as collisions happen. Box2D allows you to provides some classes containing several callback functions in order to implement the behavior you desire when a certain event like collision happens. For example, let’s say you want Box2D to destroy an object after a collision had happened, in this case, you can create a custom b2ContactListener that implements this behavior and provide it to the physical world using the method SetContactListener.

There are four (4) Callback Classes that can be provided to b2World, you will learn how to use all of them.

void        SetDestructionListener(b2DestructionListener* listener);
void        SetContactFilter(b2ContactFilter* filter);
void        SetContactListener(b2ContactListener* listener);
void        SetDebugDraw(b2Draw* debugDraw);

World Query

Finally, the class b2World offers two methods to select objects. The first method QueryAABB, allows to select all objects contained inside a certain area called AABB (Axis Aligned Bounding Box), which is just a complicated way to a Rectangle with no rotation. The second method, RayCast allows you to shoot a line and retrieve all the objects that the line collides with.

void        QueryAABB(b2QueryCallback* callback, const b2AABB& aabb) const;
void        RayCast(b2RayCastCallback* callback, const b2Vec2& point1, const b2Vec2& point2) const;