Box2D C++ tutorials - Introduction

Last edited: April 07 2014

Chinese version -> 中文


Box2D is the world's most ubiquitous 2D physics engine. It's light, robust, efficient and highly portable. It has been battle-proven in many applications on many platforms, and it's open-source and free. Check out the Box2D website at

A physics engine simulates the physics of objects to give them believable real-life movement. Although it can be used for other applications, the project was born primarily as a library for use in games, and games make up the majority of software using Box2D. The engine is written and maintained by one Erin Catto who it seems, not satisfied by simply making kick-ass physics as a day-job, set up Box2D to make kick-ass physics as a hobby as well.

Box2D is written in C++, but has been ported to many different languages by the user community. Here are just a few, you can also find more at A physics engine is not a game engine. Box2D is very good at simulating physics but it is not intended to draw nice graphics, use the network, build worlds or load a game level for you. If you came here hoping for a little more help with these needs, you might like to look into one of the links below.

Box2D C++ tutorials

The user manual explains almost everything you need to know about using the library, at least for C++. However I've been using Box2D for a while and reading the discussion forums I see the same questions coming up quite regularly. Since these are often things I have come across myself too, I decided I would write up some suggestions about how these issues could be solved. Then I figured if I was gonna do that, I might as well make a set of tutorials on using Box2D right from the beginning.

Looking around on the net, I found some people have already done a pretty good job of this:
As you can see these are predominantly in Flash, but I will be doing my tutorials in C++ since that's what I have used for most of my development. I will also be using a more recent version of Box2D than some of the tutorials above. Hopefully having C++ tutorials will be useful for someone, and my topics are not too similar to theirs! Eventually I am hoping to cover the following:

Basic usage
  • Testbed setup (linux, windows, mac)
  • Testbed structure
  • Making a 'test' for the testbed
  • Bodies
  • Fixtures
  • World settings
  • Cancelling gravity
  • Forces and impulses
  • Moving at constant speed
  • Keeping a body rotated at given angle
  • Jumping
  • Using debug draw
  • Drawing your own objects
  • User data
  • Collision callbacks
  • Collision filtering
  • Sensors
  • Raycasting
  • World querying
  • Removing bodies
  • The 'touching the ground' question
  • Joints
  • Some gotchas
Advanced topics
  • Vehicle suspension
  • Sticky projectiles
  • Projected trajectory
  • Explosions
  • Breakable bodies
  • Top-down car physics
  • Terrain
  • One-way walls and platforms
  • Conveyor belts
  • Escalators?
  • Elevators
  • Arrow in flight
  • Advanced character movement
Generally the focus will be on making a platform game, but I'll try to keep the content as broadly applicable as possible. Occasionally I will skip some features of the engine that are relevant to a particular topic, but are somewhat more advanced. Hopefully I can come back at a later date and add some 'advanced' sections here and there.

I will be using version 2.1.2 of the Box2D source code which seems to be the latest official release at this time. For most of the examples I will try to add the code for the tutorial as a 'test' in the 'testbed' which comes with the Box2D source code. This removes the need for setting up a project, window, etc and allows us to get straight into using the actual library itself.
Update:Version 2.1.2 is looking a little old now, but the main difference in the current (v2.3.0) version is the addition of chain shapes. Most of the material in these tutorials is still applicable, and I will try to add a little 'update' note like this in places where something should be mentioned.


To follow these tutorials you will need to have an intermediate-level knowledge of C++. A beginner-level knowledge of OpenGL would be handy too, but not necessary. As for required software, you can download everything you'll need for free - no excuses now huh?


I'm not sure if dedication is the right term to use here, but back in the day I learned OpenGL almost entirely from the NeHe site at, starting right from zero knowledge. The site was an incredibly useful resource and I was very grateful to have it available. Although I rarely visit the NeHe site these days, it was one of the major inspirations for me to set up this site. Thanks Jeff!!!


If you spot any mistakes, have suggestions for improvement or any other feedback, write a comment on one of the topic pages or contact me at the gmail address: 'iforce2d'

Follow me on twitter to be notified when topics are added: