Getting started with b2IDE

1. You'll need Box2D.

This guide will assume that you already have the AS3 version of the Box2D physics engine, and at least a vague idea of how to use it. If you don't, go get it now, and make sure you can at least compile the examples that come with it. b2IDE has only been tested with Box2D's current release (2.0.1).

2. You'll also need b2IDE.

Download the current release, and put the source files in your classpath. (Probably you'll want the b2IDE folder sitting right next to your Box2D folder.) If you haven't already set your classpath to include the b2IDE and Box2D sources, do that now. In Flash, open Edit > Preferences > ActionScript > ActionScript 3.0 Settings, and in the "Source Path" section add the path to the folder containing the b2IDE and Box2D folders.

3. Take a look at hello_world.fla

In the b2IDE release files, take a look inside examples/hello_world.fla. Compile the file (control-enter) and you should see a simple physics simulation using b2IDE. Back in the FLA, we'll find all the basics of using b2IDE. On the stage, you'll find a MovieClip called myWorldMC, which corresponds directly to the Box2D engine's b2World entity. Inside myWorldMC are a variety of other MovieClips representing shapes, bodies, and joints. In the library, right-click on any MC and choose "Properties", and you should see a dialog similar to the one pictured at right. Here you can see that each MC is extending one of the b2IDE classes (in the "Base Class" option).

4. Set up your own simulation.

Open a new FLA. Create a new MovieClip that will function as your world, called MyWorld or something of the sort. Then, attach your MC to the b2IDE.WorldMC class, by performing the following steps:

1. Right-click the MC in the library, and choose "Properties".
2. If the properties dialog is very small, click the "Advanced" button.
3. Turn on the "Export for ActionScript" checkbox.
4. For "Base class", enter b2IDE.WorldMC
5. Close the dialog.

Your MC is now attached to b2IDE.WorldMC, and if you don't need to change any parameters then you can finish here. Usually, however, you'll want your MC to inherit WorldMC's parameters, so you can edit them in the IDE. To make this possible:

1. Again, right-click your world MC in the library, and choose "Component Definition".
2. For "Class", enter b2IDE.WorldMC
3. Hit "OK" and wait a moment while Flash processes the parameters.

Now, drag your world MC onto the stage and select it. If you set up the parameters as just described, then in the Component Inspector window you'll see a list of parameters related to the WorldMC, such as gravity, timestep, etc. Most of these parameters correspond directly to variables in the Box2D engine, but a few are specific to b2IDE. See the relevant API reference for details.

Once you have a class that extends b2IDE.WorldMC on the stage, you can give it some contents. Create a second MovieClip called "box", and draw a rectangular shape inside it. Then attach this MC to b2IDE.Shapes.BoxMC using the same process you used above. Then, inside your world MC, drag several copies of your box MC to the stage. By default, they all start with a density of 0, so they'll be fixed in place, so in the Component Inspector window, you'll probably want to change the density of some of your boxes to something like 1.

Incidentally, once you've added some boxes to your world, feel free to rotate, resize, or skew each box as you like. When b2IDE initializes them to the physics engine, it will create them as polygons with the appropriately transformed shape. Generally, b2IDE attempts to cover all the eventualities this way, so that you can lay things out in the IDE however you like.

5. Test your simulation.

That's it! Hit control-enter to test your simulation. If all went well, you'll see several of your boxes on the screen - either fixed in place, if you forgot to give them a non-zero density, or falling into oblivion if you forgot to make a floor. If an error occurred, there's probably a message of some kind traced to the Output window. Check there, or compare your contents to the Hello_World example to see what went wrong.

If you're familiar with the Box2D engine, you're probably wondering why you were allowed to add a Shape directly into the world without putting it inside a Body. The answer is that when b2IDE finds bare shapes inside a WorldMC, it automatically generates a BodyMC to contain them. This means that at runtime, the MovieClip you made will no longer be a direct child of the WorldMC, but a grandchild. This is done for convenience, and to maintain the structure of having b2IDE entities to correspond to all Box2D entities, but it's the sort of thing you may need to be aware of. Details like this can be found in the API reference.

Once your simulation is working correctly, here are a couple more things to try:

Add a Mouse Joint:

Using the same process described above, make a MovieClip that extends b2IDE.Joints.MouseJointMC and add it to your world. When b2IDE finds that MC, it will remove it from the display list and set up a Mouse Joint for you. See the MouseJointMC API for details.

Define geometry with anchors:

In the box MC you made above, you simply drew a rectangle in the MC, and b2IDE assumed the physical entity should be the same size as the rectangle. Instead, you can define the box's geometry with anchors. Make a MovieClip that extends b2IDE.Shapes.AnchorMC. Then add two copies of this MC inside your box, at the opposite corners of the box's geometry. When b2IDE creates the box, it will use the anchors to determine the size, then remove the anchor MCs from the display list. This way, your box's graphics can be larger or smaller than its physical size. (Most other joints and shapes also require the use of one or more anchors to define their geometry - see the API reference of each class for details.)

6. Good luck!

Have fun, and be sure to report any bugs or feature requests using the "Issues" tab at the top of this site.

Thanks for using b2IDE!