How to Make a Platformer Game with Cocos2D-X

Box2d Tutorial

In the last chapter we covered creating a TMX Tiled map and how to create rectangular Box2d fixtures. In this chapter we will bring the map to life.

First we'll add dynamic Box2d bodies to the world. Then we'll link player input to physical impulses to create movement.

The Box2d World

In a nutshell, Box2d has a single world object and multiple body objects. The body objects can have one or more fixtures attached to them.

Once the world and bodies are in place, it's a matter of updating the world, ticking the simulation with a small time delta for each frame.

Here's how to create the world:

const float kPixelsPerMeter = 32.0f;
const float kGravity = -kPixelsPerMeter / 0.7f; // adjust this to taste

void Level::createPhysicalWorld()
  world = new b2World(b2Vec2(0.0f, kGravity));

This creates the Box2d world (b2World) object, passing a gravity vector as a parameter to the constructor.

For efficiency's sake, bodies in the world are allowed to sleep, which means that they are automatically excluded from the simulation until something happens to wake them.

We also choose to use a continuous physics model. In essence, this causes the world's collision detection to use ray casting to catch instances where a fast moving body, like a bullet, would have moved entirely through another body during a single tick of the physics simulation.

Box2d ray casting

A contact listener is also set, so that the Level class receives a BeginContact and EndContact callback whenever a collision between two objects occurs.

As we discussed in the last chapter, bodies with rigid fixtures are added to the world to create the level. With those rigid bodies in place, we can move on to creating dynamic bodies, like the player object.

LevelObject Base Class

Before we create the player it is important to have a good object-oriented class system in place for our various objects. I like to create a base class to handle most of the fundamentals, then derive subclasses from it to create specialized objects.

In the case of writing a side-scrolling platformer, the base class will be something map or level related. Let's call it LevelObject:

class LevelObject : public Node
    // It helps to typedef super & self so if you change the name
    // of the class or super class, you don't have to replace all
    // the references
    typedef Node super;
    typedef LevelObject self;

    b2Body* body;
    Sprite* sprite;

    virtual ~LevelObject();

Deriving the base class from Node links the LevelObject into the Cocos2d-X world and provides a parent object that other Cocos2d children (like the sprite) can be added to.

We also give the base class a Box2d b2Body pointer. This is the dynamic body we will use to give the object movement and have it interact with the fixtures and other dynamic bodies that make up the level.

Next we'll give the LevelObject class some basic Box2d-related methods. Here's the method to create the body within the world:

void LevelObject::addBodyToWorld(b2World* world)
  // add a dynamic body to world
  // (subclasses can use other body types by overriding
  // this method and calling body->SetType())
  b2BodyDef bodyDef;
  bodyDef.type = b2_dynamicBody;
    this->getPositionX() / kPixelsPerMeter,
    this->getPositionY() / kPixelsPerMeter
  bodyDef.userData = this;
  bodyDef.fixedRotation = true;
  this->body = world->CreateBody(&bodyDef);

Note the body's userData variable. It's a void* which can point to whatever object we like. This allows us to associate a body with our own class system. When a collision occurs, we can look into the userData variable, dynamically cast it to a LevelObject, then use it within our own game's system.

Here's a few functions to create fixtures:

void LevelObject::addCircularFixtureToBody(float radius)
  b2CircleShape shape;
  shape.m_radius = radius * this->getScale();

void LevelObject::addRectangularFixtureToBody(float width, float height)
  b2PolygonShape shape;
    width * this->getScale(),
    height * this->getScale()

  kFilterCategoryLevel = 0x01,
  kFilterCategorySolidObject = 0x02,
  kFilterCategoryNonSolidObject = 0x04

void LevelObject::createFixture(b2Shape* shape)
  // note that friction, etc. can be modified later by looping
  // over the body's fixtures and calling fixture->SetFriction()
  b2FixtureDef fixtureDef;
  fixtureDef.shape = shape;
  fixtureDef.density = 1.0f;
  fixtureDef.friction = 0.7f;
  fixtureDef.restitution = 0.1f;
  fixtureDef.filter.categoryBits = kFilterCategorySolidObject;
  fixtureDef.filter.maskBits = 0xffff;

Above we have a couple methods to create either a circular or a rectangular fixture within the body. Subclasses of LevelObject will use these methods to create the body shape they desire.

Note the use of filter categories to allow a fixture to be in the level category (a rigid fixture), solid (a regular solid object) or nonsolid (an object which can be trod upon, like an exit portal).

The Player Object

Now that the LevelObject base class is in place, we can derive the Player object, easily adding a body and fixture:

void Player::addBodyToWorld(b2World* world)
  // let superclass to the work, we just need to set the player to be
  // a bullet so it doesn't fall through the world on huge updates

void Player::addFixturesToBody()

Finally, we need the Level object to create the player. In the last chapter, we looked at how to add objects from the TMX Tiled map data. Here's the addObject function which creates a single object:

LevelObject* Level::addObject(string className, ValueMap& properties)
  // create the object
  LevelObject* o = nullptr;
  if(className == "Player")
    o = new Player;
  else if(className == "Monster")
    o = new Monster;
  else if(className == "MagicChest")
    o = new MagicChest;
  // process the new object
  if( o != nullptr )
  return o;

After the object is constructed, it is given properties that were loaded from the TMX. Then a sprite is added, the body is added to the world and fixtures are added to the body.

The most important part about setting the LevelObject's properties is to give it a position based on the x and y values that a Tiled TMX object is automatically given:

void LevelObject::setProperties(ValueMap& properties)

Ticking the Simulation

With the level, its Box2d world, the objects, their bodies and everything else created, we can now set the world spinning, as it were.

An update is scheduled to tick the physics simulation:

const float kUpdateInterval = 1.0f / 60.0f;
const double kSecondsPerUpdate = 0.1;

double getCurrentTimeInSeconds()
  static struct timeval currentTime;
  gettimeofday(&currentTime, nullptr);
  return (currentTime.tv_sec) + (currentTime.tv_usec / 1000000.0);

  // initialize variables, load the tmx, create the objects, etc...
  // schedule the update
  this->schedule(schedule_selector(Level::update), kUpdateInterval);

void Level::update(float dt)
  // get current time double
  currentTime = getCurrentTimeInSeconds();
  if (!lastTickTime)
    lastTickTime = currentTime;
  // determine the amount of time elapsed since our last update
  double frameTime = currentTime - lastTickTime;
  accumulator += frameTime;
  // update the world with the same seconds per update
  while (accumulator > kSecondsPerUpdate)
    accumulator -= kSecondsPerUpdate;
    // perform a single step of the physics simulation
    world->Step(kSecondsPerUpdate, 8, 1);
  lastTickTime = currentTime;

The update function uses a fixed time step so that even if the game is experiencing a very slow frame rate, the physics will perform predictably.

A fixed time step works by always ticking the simulation by the same amount, then storing any excess time in an accumulator.

The added bonus of fixed time step is that all your objects can be updated with a deterministic time delta. This can greatly simplify artificial intelligence, multiplayer functionality and mathematics in general.

Running It

By now you have enough code at your disposal to piece together a very simple side-scrolling demo. You've drawn a level, created a Box2d physics world and learned how to set it in motion.

You should be able to add a Player object very high above a platform in your level, run your game, and watch your player fall down.

In the next chapter, we'll learn how to accept input and move the player around.

Got questions? Leave a comment below. You can also subscribe to be notified when we release new chapters.

Next Chapter >


  1. Antol

    Greate! Thanks

  2. David

    Hey man, I really appreciate the chapters. Keep up the good work!

  3. Waqas Khan

    Great tutorials there. Keep them coming ! :)