Introduction to Box2D for Flash and AS3

Box2D is a popular physics engine with a solid Flash port, which was used to create the excellent game Fantastic Contraption. In this tutorial, the first of a series, you’ll get to grips with the basics of Box2D 2.1a for Flash and AS3.

---

Step 1: The Boring Setup

I’m going to assume you already know how to set up a basic Flash project using your editor and workflow of choice, whether that means creating a FLA with a document class, a pure AS3 project in a different editor, or whatever. I’m using FlashDevelop, but you should use whatever you feel comfortable with.

Create your project, and name the main class Main.as. Give it some boilerplate code; mine looks like this:

package
{
 import flash.display.Sprite;
 import flash.events.Event;

 [Frame(factoryClass="Preloader")]
 public class Main extends Sprite
 {

  public function Main():void
  {
   if (stage) init();
   else addEventListener(Event.ADDED_TO_STAGE, init);
  }

  private function init(e:Event = null):void
  {
   removeEventListener(Event.ADDED_TO_STAGE, init);
   getStarted();
  }

  private function getStarted():void
  {

  }

 }

}

Don’t worry about the [Frame] metatag — that’s just how FlashDevelop creates a preloader. All you need to know is that getStarted() is run when the SWF has fully loaded. Create a function of the same name that runs when your Main class has loaded.

I’m also going to assume you’re comfortable with using a separate library or API in your project. Download Box2DFlash 2.1a from this page (I’m using the Flash 9 version), and extract the zip to wherever you normally put your APIs. Next, add a classpath to point to the \Source\ folder from the zip. Alternatively, you could just extract the contents of the \Source\ folder to the same directory as your Main class.

Great! That was easy. Let’s start using Box2D.

---

Step 2: A Whole New b2World

“If you want to make an apple pie from scratch, you must first create the universe,” wrote Carl Sagan; if we want to make a few physics objects, we only need to create a world.

In Box2D, a world is not a planet or an ecosystem; it’s just the name given for the object that manages the overall physics simulation. It also sets the strength of gravity — not just how quickly objects accelerate but also in which direction they fall.

We’ll create a vector to set the gravity before creating the world itself:

import Box2D.Common.Math.b2Vec2;

//...

private function getStarted():void
{
 var gravity:b2Vec2 = new b2Vec2(0, 10);
}

A b2Vec2 is a Box2D Euclidean vector (the second 2 stands for 2D again, because it’s possible to have a 3D Euclidean vector). Daniel Sidhion wrote an excellent tutorial explaining what Euclidean vectors are (they are nothing to do with the Vector class in AS3), so check that out if you’re not sure. But briefly, think of a Euclidean vector as an arrow:

This arrow shows b2Vec2(4, 9); it points down and to the right. Our gravity vector, then, will point straight down. The longer the arrow, the stronger the gravity, so later on in the tutorial you could try changing the gravity vector to b2Vec(0, 2) to simulate a much weaker gravity, much like that on the Moon.

Now we’ll create the world itself:

import Box2D.Dynamics.b2World;

//...

public var world:b2World;

//...

private function getStarted():void
{
 var gravity:b2Vec2 = new b2Vec2(0, 10);
 world = new b2World(gravity, true);
}

The second parameter we pass to b2World() tells it that it can stop simulating objects that it doesn’t need to simulate any more, which helps speed up the simulation but is completely irrelevant to us at the moment.

Run the SWF to check there are no errors. You won’t be able to see anything yet, though. The world is currently completely empty!

---

Step 3: Reinvent the Wheel

Let’s create a simple circular object; this could represent a rock, a basketball, or a potato, but I’m going to see it as a wheel [...]

Read more: Introduction to Box2D for Flash and AS3