You can download the source files here.

Box2D is a C++ 2D physical world simulation created by Erin Catto and ported to many other languages. The Actionscript 3 version we will be using in this tutorial is adapted from the original Box2D by BorisTheBrave and can be found here. We will be using the 2.1a version which is the latest one at this date.

What is Box2D?

Box2D simulates a virtual 2D world by using complex Mathematical formulas and applying the results to virtual objects. That’s right, everything is virtual in box2D. Box2D is not a DisplayObject that you display on the screen. Box2D does not display graphics on the screen either. In fact Box2D has no direct relation with whatever you will display on the screen.

How do I use Box2D?

To use Box2D with your next game or application, you create a Box2D world, create some Box2D bodies/objects then use the values (position, rotation) from these bodies/objects to position and rotate your graphics in your application. So one part of your application will be managing Box2D, another part of your application will be using Box2D values to actually display and position graphics on the screen.

How easy is it to work with Box2D?

Let’s just say that beginners will have a real hard time working with Box2D:

. Box2D documentation is not really developed.
Documentation doesn’t come with examples. Most methods/properties have no description of what they are supposed to be doing.

. Box2D doesn’t throw errors.
In the best cases if you do a mistake working with Box2D, what you are trying to do won’t work. In the worst cases it will crash Flash altogether.

. Box2D doesn’t dispatch events.
Box2D uses a system of class callbacks. Is it up to you to wrap that up into a class dispatching events.

. Box2D framework and used patterns are a bit confusing.
Getting or setting one value in Box2D can be made via public member variables, getters/setters or even methods. You better check the documentation regularly to know which one to use.

. Box2D doesn’t use pixels but meters as measure unit.
If you create a 100×100 object in Box2D you are creating a 100 meter x 100 meter object. Pretty much the size of a building. Box2D is slower and less accurate with bigger object so you will need to scale down all the value you pass to Box2D and then scale them up when you retrieve them. We usually handle this with a public static const scale value.

. Box2D uses radians exclusively for angle measurement.
Flash doesn’t use radians for rotating objects so here again to set an angle in Box2D you will need to convert to radian first and when retrieving angles you will need to convert back to degrees.

Also to create any kind of object in Box2D you often have to write quite a few lines of code. This process can be very repetitive and not quite suited for efficient development. That is why a good OOP knowledge will help you on wrapping up most repetitive code into classes/static methods.

Now that we know more about Box2D, it is time to write some code. Let’s start by creating a functional Box2D world.