Box2d Tutorial

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));
   world->SetAllowSleeping(true);    
   world->SetContinuousPhysics(true);
   world->SetContactListener(this);
}

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.

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's 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 fundamental functions, 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 CCNode
{
   private:
      // 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 CCNode super;
      typedef LevelObject self;

   protected:
      b2Body* body;
      CCSprite* sprite;

   public:
      LevelObject();
      virtual ~LevelObject();
};

Deriving the base class from CCNode 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;
   bodyDef.position.Set(this->getPosition().x / kPixelsPerMeter,
      this->getPosition().y / 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();
   this->createFixture(&shape);
}

void LevelObject::addRectangularFixtureToBody(float width, float height)
{
   b2PolygonShape shape;
   shape.SetAsBox(width * this->getScale(), height * this->getScale());
   this->createFixture(&shape);
}

enum
{
   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;
   this->body->CreateFixture(&fixtureDef);
}

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
   super::addBodyToWorld(world);
   body->SetBullet(true);
}

void Player::addFixturesToBody()
{
   this->addCircularFixtureToBody(0.7f);
}

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,CCDictionary* 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 )
   {
      o->setProperties(properties);
      o->addSprite();
      o->addBodyToWorld(this->world);
      o->addFixturesToBody();
      this->addChild(o);
   }
   
   return o;
}

After the object is constructed, it is given properties from the CCDictionary which was 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(CCDictionary* properties)
{
   if( properties )
      this->setPosition(ccp(floatValue(properties->objectForKey("x")),
         floatValue(properties->objectForKey("y"))));
}

inline float floatValue(CCObject* o)
{
   CCString* string = dynamic_cast<CCString*>(o);
   if( string )
      return string->floatValue();
   return 0.0f;
}

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;

Level::Level()
{
   // 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 = KITApp::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;
}

double KITApp::getCurrentTimeInSeconds()
{
   struct cc_timeval currentTime;
   CCTime::gettimeofdayCocos2d(&currentTime, NULL);
   return (currentTime.tv_sec) + (currentTime.tv_usec / 1000000.0);
}

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.

If you'd like to skip ahead and get all the code & art to a complete Cocos2dx + Box2d game, you can download the source code to Paralaxer at any time.

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

Got questions? Leave a comment below.

Stay tuned. We are writing the next chapter in this free online book. If you'd like, you can subscribe to be notified when we release new chapters.