News Apr 7: On-screen logging class for Cocos2d-x
Mar 22: Downhill Supreme 2 released for iOS and Android
Jan 2: YouTube video: Making soft-body wheels in RUBE
Oct 6: Check out Supplyfront RTS, my 7dRTS entry continued.
Sep 26: R.U.B.E v1.5 released. Customizable item labels, snap-to-grid, export filtering, full-text help search.
Sep 18: Added RUBE sample loader for Cocos2d-X.
Sep 16: Updated RUBE sample loader for Cocos2d v2.
Aug 12: RUBE loader for Nape by Zeh Fernando
Aug 7: Added RUBE sample loader for SFML.
Jul 30: Try my MiniLD 7dRTS entry.
Jul 24: Added physics-driven particles tutorial.
Jul 20: New blog post: rendering solid ground (as in Downhill Supreme)
Jul 18: R.U.B.E v1.4 released. Command-line interface for batch jobs, hotkeys for scripts, better script management.
May 22: Downhill Supreme is out now! (iOS)
Apr 2: R.U.B.E v1.3 released. Collision bitplane editing, Cocos2d-iphone loader, usability improvements.
Mar 11: R.U.B.E v1.2 released. Now supports weld, friction, motor joints and automatic image reloading.
Mar 10: RUBE loader for libGDX by Tim Scott
Jan 28: New blog post: a functional combustion engine!
Jan 22: New blog post: wind tunnel
Jan 20: Added explosions tutorial.
Jan 16: Added buoyancy tutorial.
Jan 16: AndEngine sample project to load RUBE scene by Bart Hirst
Jan 14: R.U.B.E v1.1 released, now supports custom properties.
Jan 1: All basic tutorials are now available in Chinese at Huge thankyou to @OhCoder!
Dec 23: Discussion forums have been set up
Dec 4: R.U.B.E v1.0 is ready !
Dec 2: YouTube video: Box2D pendulum clock
Nov 26: New blog post: rocket platform thingy
Nov 25: Video of R.U.B.E scenes in Chipmunk.
Nov 23: A sample project to load R.U.B.E scenes into Chipmunk physics! Details here.
Nov 14: An XCode sample project to load R.U.B.E scenes on iOS is now available. Details here.
Nov 11: A Java version of b2dJson is now available, based on JBox2D.
Nov 6: A Javascript version of b2dJson based on box2dweb is now available. Demo here!
Nov 2: The full specification of the JSON format used by b2dJson can be found here: b2dJson file structure
Oct 28: YouTube video: 2-minute ragdoll in R.U.B.E Box2D editor
Sep 29: YouTube video: R.U.B.E Box2D editor usage example

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: