I wanted to try something fun with Flash this week, so I did a quick search for “Flash Physics Engine.” Lo and behold, I struck gold. Box2DFlashAS3 is an open source ActionScript 3.0 conversion of the C++ Physics Engine Box2D. I’m very impressed with its well coded structure and easily implemented nature. I learned a few new things that will change how I code forever just by reading through their example files.

Still, they have limited resources right now as far as help documentation goes (”Please refer to the source code from the examples provided to get an idea of how to use Box2DFlash in your projects.” — that’s the ReadMe.txt that comes with it… not very helpful,huh). I thought I might give you an example of my own and walk through it step by step.

That was the thought, but it has taken me all weekend to understand the engine well enough to explain how it works. The beauty of it though, is you don’t have to understand how it works to use it.Now to get right into it then! First of all, in order to do anything with Box2DFlash you’re going to have to include most (if not all) of the files. If you have the 349KB folder “Box2D” in your project folder, then your includes will work just like this:

Easy.

Now you have to create a b2World object (source code of the class is in Box2D/Dynamics/b2World.as). The world object is the entire body of the engine. Everything is contained within it once your are done.

NOTE: The brain of the engine is b2BroadPhase.as and the heart is the Step() function withing the world object. Don’t go messing with the brain (b2BroadPhase.as) ever. You will totally mess up the engine.

The world object constructor requires 3 things:
1.) A coordinate system in the form of a b2AABB class object.
2.) A vector that defines gravity. That will be in the form of a b2Vec2 class object.
3.) A boolean variable that defines whether objects “sleep” or not. (I recommend you make it true, that they can sleep)

My examples are not my own here. The code I’m showing is an excerpt from the “Hello World” code they provided with the engine.

After creating a world object you have to bring it to life by setting its heart to beating:

Running the Step() function every frame will update all the Body Definitions you add to your world.
As of right now this world is empty though. In order to add balls and boxes and any strange polygonal shapes you can think of, we need to create Body Definitions for them.

A Body Definition consists of 2, 3, or 4 things.
1.) A Shape Definition.
2.) An (x,y) position.
optional:
3.) Rotation (in radians)
4.) A pre-made Sprite object.

In the example flash movie at the beginning of this post you will notice that all the shapes are simple. That’s because everything is being redrawn every frame with only lines and no fill. That’s right, EVERYTHING is made in code. Nothing was drawn by hand.
If you want your game, or whatever, to have a little more character then that example movie, then you will probably want to associate hand made Sprites with your Body Definitions.

In the “Hello World” example, they use Sprites to display their objects. You could leave them invisible too if you really wanted. Either way they will still be accounted for in the calculations.

On to something very important. What is a Shape Definition!? We have 3 types of shape definition and they all extend the base b2ShapeDef class.

First we have the b2BoxDef class. The b2BoxDef has 4 important properties:
1.) Extents - this is a vector that essentially goes from one corner of the box to the exact center. In other words, half the width and hight. (box is a rectangle)
2.) Density - in the collision equations we use density * area = mass
A density of 0 (zero) or null will make the object static and it will never move in the case of a collision or gravity.
3.) Friction - this is used to calculate the friction between 2 objects… you should keep it between 0.0 and 1.0
4.) Restitution - this is the bounciness of the object. Should probably also stay between 0.0 and 1.0

The b2CircleDef has only one differences in it’s properties. Instead of Extents it has Radius, which is easy to remember.
The b2PolyDef has an array of (max 8) vertices instead of Extents or Radius. These vertices are just b2Vec2 vector objects.

Now Adding a bunch of objects to our world should be easy:

That’s great isn’t it? It’s really not that hard to add a whole bunch of objects to your world. You should know that the Step() function that we added earlier will only take care of moving and rotating our body definitions. If we have sprites to represent those definitions then we need to update them manually… they made the code for that easy and you can copy and paste it almost exactly into every one of your projects.
We just have to rewrite our Update function from before:

That’s it for now. We have objects in a world that can collide with each other and are affected by gravity. There is still a lot more to talk about, but I am just walking you through the “Hello World” first. We still need to cover Joints, Pulleys, Gears, Compound Shapes, Forced rotation (like cars tires), and a lot more… I doubt I will be able to cover all these topics anytime soon, but I will definitely write more tutorials on this physics engine in the future.

You can download my copy of the “Hello World” example project with all of my comments included (there is almost no commenting in the original).

Download Hello World w/ comments.

You can get all of the library files needed for Box2DFlash at their site. It’s free.

Credits:
Box2D - Erin Catto ( http://gphysics.com/ )
Box2DFlashAS3 - Matthew Bush (Flash ActionScript 3.0 port of Erin Catto’s work)