ClickPopMedia » Box2DFlash

Changes to Box2DFlash “Hello World” example.

Paul — Wed, 30 Apr 2008 00:28:36 +0000

I’ve talked about the basics of Box2DFlash v1.4.3 in my Introductory tutorial. I showed how to create your world and how to introduce simple bodies into that world. With the release of Box2DFlash v2.0.0 the basics remain mostly the same, there are a few details changed. I need to go over these small changes before I move on to the next step of adding joints and forces to the bodies.

The first and biggest change (although really a small thing) is that we no longer work in pixels! We now work in units that by default equal 30 pixels to 1 unit (think of it as meters; 30px : 1m). With this change our normal gravity is no longer (0, 300) but instead (1, 10). This makes more sense to me at least because gravity in reality is 9.81 m/s/s. This is going to effect almost everything you do, from applying forces to setting the width and height of a box.

The reason for such a change (I believe) is to make it easier for you to dynamically scale a project. Just change the ratio of pixels per unit and everything should scale correctly.

The second change is the way we add objects to the world. The creation of a new shape and object is still very much the same, but we now have the ability to adjust the center of mass. For now, just leaving the center of mass to auto calculate we need to get the body object when adding the new bodyDef to the world.

var body:b2Body;
var bodyDef:b2BodyDef;
var boxDef:b2PolygonDef;

// Add ground body
bodyDef = new b2BodyDef();
bodyDef.position.Set(10, 12); //Small numbers… remember it’s scaled 30:1
boxDef = new b2PolygonDef();
boxDef.SetAsBox(30, 3); //THIS IS NEW!
boxDef.friction = 0.3;

// Add sprite to body userData
bodyDef.userData = new PhysGround();
bodyDef.userData.width = 30 * 2 * 30;
bodyDef.userData.height = 30 * 2 * 3;
addChild(bodyDef.userData);
body = m_world.CreateStaticBody(bodyDef); //THIS IS MOSTLY NEW
body.CreateShape(boxDef); //THIS IS NEW
body.SetMassFromShapes(); //THIS IS NEW

Haha! I guess I forgot to mention that we no longer have a b2BoxDef anymore… we only have b2PolyDef (renamed b2PolygonDef). We can quickly define it as a box though using the method public function SetAsBox(hx:Number, hy:Number):void.

Anyways, let us bring our attention back to adding the object to the world. When you add the object to the world, you are creating it as either a static (unmoving) body or as a dynamic body (body = m_world.CreateDynamicBody(bodyDef);).
It then returns the new body object BY REFRENCE. It is not giving you a copy of that object. This way when we make changes, such as add the shape and set the mass (center of mass really) we don’t have to go send it back again.

The method public function SetMassFromShapes():void is the way to auto calculate and set your center of mass. Otherwise you have to us public function SetMass(massData:b2MassData):void, but this is a whole new complication.

OK! With that, we are pretty much back up to speed after my last tutorial.

Box2DFlash v2.0.0 Released!

Paul — Mon, 21 Apr 2008 18:30:33 +0000

Box2DFlash v2.0.0 was finally released on the 17th of this month (April). Box2DFlash is the Flash AS3 port of Erin Catto’s C++ physics engine Box2D. Erin Catto is a physics programmer at Blizzard Entertainment (WarCraaaft!). I’ve been looking forward to this release since I found out about it while making a tutorial for the previous release (v1.4.3) about a month ago.

Some of the major changes/additions to this version are:

- Continuous physics.
Continuous physics means that the physics is now independent of the frame rate. This prevents bodies from passing through each other at higher speeds. This feature can potentially make this version slower then previous versions, but it also makes it MUCH more accurate.
- Shape create/destroy.

You can destroy a shape on the parent body easily. You may do this to model a breakable object.

In the past you couldn’t add or remove shapes from a body object that was already in the world object.
- Joints defined in local coordinates.

Box2D requires [joint anchor] points to be specified in local coordinates. This way the joint can be specified even when the current body transforms violate the joint constraint — a common ocurrence when a game is saved and reloaded.

- Moveable center of mass.
This is great because you can now have a hammer that’s center of mass is in the head, not the middle of the handle.
- Sensors.

Some times game logic needs to know when two shapes overlap yet there should be no collision response. This is done by using sensors. A sensor is a shape that detects collision but does not produce a response…

- Contact listener callback.
- Contact filter callback.
These callbacks are essentially events. It is now much easier to do something or other on collisions. Say, cause damage to your spaceship when a meteor strikes it.
- Revised manual.
Sure. Having an up to date manual is a good thing. Currently the manual is only for the C++ version, but all the concepts are the same for the flash version and it will help a lot for understanding the example projects.
- Doxygen documents.
- Eliminated deferred destruction.
This was a feature in previous versions of Box2D that was only needed because there was no contact callbacks. It’s gone now so I’m not going to bother explaining what it was.
- Improved testbed with more examples.
Check it out! It’s really just the example project/code that they give you to learn some of the features.

With this release I will be getting back to making some tutorials on how to use this awesome resource. So, keep checking back to see what’s new and I will hopefully not disappoint you.

Cool Games Made with Box2DFlash

Paul — Mon, 24 Mar 2008 05:31:11 +0000

After writing my introduction tutorial to Erin Catto’s Box2D AS3 physics engine port, I found out that I was writing about version 1.4.3. Well a new version (v 2.0.0) is set to come out within the next few weeks, so I thought that I would put off any more tutorials on Box2DFlash till I find out what has changed.

Until then, I’ve found a bunch of fun games made with the Box2D engine and I thought I would share them with you.

Clog FLASH: (http://brainclog.com/clog.shtml)
Clog is a fun little flash game where you are some kind of white ice ball bumping and pushing 5 blue ice balls through an obstacle course. I haven’t played very far in this game yet. I keep getting distracted with other things around the fourth level. Still it’s a good example of circular collisions in the engine.

Poker-Blocks C++: (http://www.pokerblocks.com/index.html)

Poker Blocks is a commercial stand alone game that seems to be a mix between Tetris and poker. It seems like a weird combo to me, but it also looks fun judging from the video. I haven’t played this one personally even though there is a 30 day free trial. I just wanted to include it because it looks like one of the better games made with the C++ version of Box2D.

Hikkoshi FLASH: (http://www.skt-products.com/contents/hikkoshi.html)

I found this one to be very fun. There really isn’t much to it. Just click once to start the shot and then click again to let go, but I played it over and over again. My best score is something around 12800+ (I only remember the first 3 digits). If you have Flash Player 9 I recommend giving this one a try… it only takes about 2 minutes to play from start to finish.

Carona Pinnball FLASH: (http://piwna.pl/gry/pinball)
This is just a pinball game. In some foreign language. It’s a little slow too. The reason I’m including it with the others is… well it does use the engine. And, it made the author money. So, I find that inspirational.

Snowball FLASH: (http://www.uberdruck.com/snowball/)
This game was purchased by a radio station in England for their website. The version I am linking to is the original, before it was fixed up to be suitable for the other site. This is a really simple game actually. You are just throwing snowballs at (the prime minister?) a ragdoll and watching the physics make it fly about.

Hopefully I will have something cool of my own to show off by next week.

Physics in ActionScript 3: Box2DFlashAS3

Paul — Mon, 17 Mar 2008 21:57:51 +0000

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:

// Classes used in this example
import Box2D.Dynamics.*;
import Box2D.Collision.*;
import Box2D.Collision.Shapes.*;
import Box2D.Dynamics.Joints.*;
import Box2D.Dynamics.Contacts.*;
import Box2D.Common.*;
import Box2D.Common.Math.*;

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)

// Create world AABB
var worldAABB:b2AABB = new b2AABB();
worldAABB.minVertex.Set(-1000.0, -1000.0);
worldAABB.maxVertex.Set(1000.0, 1000.0);

// Define the gravity vector
var gravity:b2Vec2 = new b2Vec2(0.0, 300.0);

// Allow bodies to sleep
var doSleep:Boolean = true;

// Construct a world object
m_world = new b2World(worldAABB, gravity, doSleep);

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:

// Add event for main loop
addEventListener(Event.ENTER_FRAME, Update, false, 0, true);

public function Update(e:Event):void{
m_world.Step(m_timeStep, m_iterations);
}

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:

var bodyDef:b2BodyDef;
var boxDef:b2BoxDef;
var circleDef:b2CircleDef;

// Add ground body
bodyDef = new b2BodyDef();
boxDef = new b2BoxDef();
boxDef.extents.Set(1000, 100);
boxDef.friction = 0.3;
/*Notice that the ground object has no density like the later
definitions. That’s because it is static and we don’t want it
effected by any forces.*/
bodyDef.position.Set(320, 400);
bodyDef.AddShape(boxDef);

// Add sprite to body userData
/*We have a Sprite object in the library called PhysGround. Here
we are associating that with our body definition.*/
bodyDef.userData = new PhysGround();
bodyDef.userData.width = boxDef.extents.x * 2;
bodyDef.userData.height = boxDef.extents.y * 2;
addChild(bodyDef.userData);
m_world.CreateBody(bodyDef);

// Add some objects
for (var i:int = 1; i < 20; i++){
/*We are going to re-use the same bodyDef from before.
It doesn’t matter now, because it’s already been copied and stored
in our world object.*/
bodyDef = new b2BodyDef();
// Box
if (Math.random() < 0.5){
boxDef = new b2BoxDef();
boxDef.extents.Set(Math.random() * 15 + 10, Math.random() * 15 + 10);
boxDef.density = 1.0;
boxDef.friction = 0.5;
boxDef.restitution = 0.2;
bodyDef.AddShape(boxDef);
/*We have a Sprite object in the library called PhysBox.*/
bodyDef.userData = new PhysBox();
bodyDef.userData.width = boxDef.extents.x * 2;
bodyDef.userData.height = boxDef.extents.y * 2;
}
// Circle
else {
circleDef = new b2CircleDef();
circleDef.radius = Math.random() * 15 + 10;
circleDef.density = 1.0;
circleDef.friction = 0.5;
circleDef.restitution = 0.2
bodyDef.AddShape(circleDef);
/*We have a Sprite object in the library called PhysCircle.*/
bodyDef.userData = new PhysCircle();
bodyDef.userData.width = circleDef.radius * 2;
bodyDef.userData.height = circleDef.radius * 2;
}
bodyDef.position.x = Math.random() * 400 + 120;
bodyDef.position.y = Math.random() * 100 + 50;
m_world.CreateBody(bodyDef);
addChild(bodyDef.userData);
}

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:

public function Update(e:Event):void{

m_world.Step(m_timeStep, m_iterations);

// Go through body list and update sprite positions/rotations
for (var bb:b2Body = m_world.m_bodyList; bb; bb = bb.m_next){
if (bb.m_userData is Sprite){
bb.m_userData.x = bb.m_position.x;
bb.m_userData.y = bb.m_position.y;
bb.m_userData.rotation = bb.m_rotation * (180/Math.PI);
}
}/*This is an extreemly clever way to do this, and I suggest you copy it exactly in your own projects.*/

}

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)