ClickPopMedia » ActionScript

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)

Intro to ActionScript 3.0 Tweening

Paul — Tue, 11 Mar 2008 01:12:49 +0000

I am going to talk about how to animate using Tween objects in ActionScript. Tween objects are enormously useful. They can change any numeric property of any object over time.

For example one of the most common uses of Tween objects in ActionScript is to fade an image out as another fades in. The advantage of using a Tween object to do this instead of any of your other options is

1.) it is easy to understand
2.) it is the easiest to code
3.) it generally looks the best.

It’s fairly easy to write a bit of code that will change the X position of a movieClip by 2 every frame, but that will be very linear and boring. Also when does it stop? and how? You would have to create a lot of if() statements that just take forever to think through and would make your code harder to read. (VQ: lots of nested if statements are usually a thing to avoid)

With a Tween object you can use Easing methods. In the example that follows I used the Easing method Regular.easeInOut to start the motion with a little acceleration and then bring it to a stop in the same way.

If the motion of the dot gets annoying you can stop or start it again at any time by clicking on the Flash movie.

Notice how the motion is almost natural at the ends. It doesn’t just stop and turn around. The code used to create this motion is simple and short:

package classes {
import flash.display.MovieClip;
import fl.transitions.Tween;
import fl.transitions.TweenEvent;
import fl.transitions.easing.*; //I like to import them all so it’s easy to play with later.

public class Oscillator extends MovieClip{
/*These constants allow me to change the tween without
digging through my code to find it. It’s just good practice*/
private const ANCHOR1:Number = 5;
private const ANCHOR2:Number = 565;
private const TIME:Number = 1.5;

private var myTweenX:Tween; //ALWAYS declare tweens as globals or properties

public function Oscillator() {
myTweenX = new Tween(this, "x", Regular.easeInOut, ANCHOR1, ANCHOR2, TIME, true);
myTweenX.start();
myTweenX.addEventListener(TweenEvent.MOTION_FINISH, yoyoTween);
}

//Yoyo simply runs the Tween in reverse. And then reverse of the reverse (forward).
private function yoyoTween(event:TweenEvent):void {
event.currentTarget.yoyo();
}
}
}

I would recommend downloading the source code for this movie at the bottom of the post and playing with some of the other Easing methods such as, Elastic, Strong, Bounce, Back, and None.

Alright! Before you go off and try to use Tweens all over the place I need to tell you about the most common mistake people make when using Tween objects. You must ALWAYS declare you Tween variables as globals (outside of any function) or properties (outside of any method).

If ever I see someone complaining about their Tween being buggy and cutting out halfway through the animation (and I see that complaint a LOT) it’s because they declared and ran their Tween from within a function or method. What happens (and this doesn’t ALWAYS happen, but it will eventually) is that the function finishes running before the Tween does. Then the Flash Run-Time Environment cleans up the memory (called garbage collecting) and your tween gets deleted! before it finishes. This might not happen while you are testing it yourself, but it will happen eventually while someone else is using it.

If you have Adobe Flash CS3 then you should type the word “Tween” in the ‘action’ panel then right click it and pick the bottom option on the drop down menu ‘View Help’. That will show you the EXCELLENT help files on tweens that come along with Flash. I’m just trying to introduce you to an incredibly useful tool… there really isn’t too much to teach about how to use it. You just need to play and experiment with it yourself.

You can also download my code for the Flash movie example earlier here: Oscillator Source

Putting ’static’ to good use.

Paul — Mon, 03 Mar 2008 23:00:34 +0000

I’m going to talk about how to build a simple 4 function calculator using static variables and meathods in Flash ActionScript 3.0. This is my first tutorial, so if you have questions or comments, I would appreciate them and will do what I can.

First of all we want to think through how this is going to work. I wanted two types of buttons; The digit buttons (1, 2, 3…) and the operator buttons (+, -, =…) and so I created 2 simple MovieClips that are almost the same as my base and then assigned them custom classes which I planned to make later.
The buttons are just a simple gray box with rounded corners (which doesn’t matter… make it whatever you want) and a small textField with instance name “btnKey” (which does matter, at least for my code).
None of that goes on the stage. I want to add everything to the stage with code so that it’s a simple matter of giving them instance names and passing them their initial values.Just to give ourselves something to work with I filled in the basics of our button classes

package classes {
import flash.display.MovieClip;
import flash.events.MouseEvent;
import flash.text.TextField;

public class BaseDigitBtn extends MovieClip {
private var num:Number;

public function BaseDigitBtn(numP:Number) {
this.num = numP;
btnKey.text = String(numP);

mouseChildren = false;
buttonMode = true;

stop();
addEventListener(MouseEvent.MOUSE_UP, OnRelease);
}

private function OnRelease(event:MouseEvent):void {
/****I will decide what happens here later****/
}
}
}

I pretty much use the same code for both BaseDigitBtn and BaseFuncBtn, only one receives a string var while the other receives a number.

…

public function BaseFuncBtn(disp:String, strP:String) {

this.str = strP;

btnKey.text = disp; mouseChildren = false;

buttonMode = true;

stop();

addEventListener(MouseEvent.MOUSE_UP, OnRelease);

}

…

Now if we want we can write the code to put these buttons on the stage. It’s only a few lines of code really that are copied and pasted till I’m blue in the face then with little added changes in each:

/**Importing my 3 custom classes**/

import classes.BaseDigitBtn;

import classes.BaseFuncBtn;

import classes.Calc; //I will talk about this class in a second… just hold on.Calc.clearField(); //I needed to initalize some variables

/*************Creating all my button instances*********************/

var Btn1:BaseDigitBtn = new BaseDigitBtn(1);

var Btn2:BaseDigitBtn = new BaseDigitBtn(2);

var Btn3:BaseDigitBtn = new BaseDigitBtn(3);

var Btn4:BaseDigitBtn = new BaseDigitBtn(4);

var Btn5:BaseDigitBtn = new BaseDigitBtn(5);

var Btn6:BaseDigitBtn = new BaseDigitBtn(6);

var Btn7:BaseDigitBtn = new BaseDigitBtn(7);

var Btn8:BaseDigitBtn = new BaseDigitBtn(8);

var Btn9:BaseDigitBtn = new BaseDigitBtn(9);

var Btn0:BaseDigitBtn = new BaseDigitBtn(0);

//The first peram in the following declerations is what is displayed on the

//button. The second peram is the name of the opperator.

var BtnA:BaseFuncBtn = new BaseFuncBtn("+", Calc.ADD);

var BtnS:BaseFuncBtn = new BaseFuncBtn("-", Calc.SUBTRACT);

var BtnM:BaseFuncBtn = new BaseFuncBtn("X", Calc.MULTIPLY);

var BtnD:BaseFuncBtn = new BaseFuncBtn("/", Calc.DIVIDE);

var BtnE:BaseFuncBtn = new BaseFuncBtn("=", Calc.EQUALS);

var BtnC:BaseFuncBtn = new BaseFuncBtn("C", Calc.CLEAR);

var BtnPN:BaseFuncBtn = new BaseFuncBtn("+/-", Calc.POS_NEG);

var BtnDec:BaseFuncBtn = new BaseFuncBtn(".", Calc.DECIMAL);

/*****************Placing those buttons on the stage******************/

for(var i = 1; i < 10; i++) {

addChild(this["Btn" + i]);

this["Btn"+i].x = 10 + ((i-1)%3)*50;

this["Btn"+i].y = 10 + (int((i-1)/3))*34;

}

addChild(BtnA);

BtnA.x = 160;

BtnA.y = 10;

addChild(BtnS);

BtnS.x = 160;

BtnS.y = 44;

addChild(BtnM);

BtnM.x = 160;

BtnM.y = 78;

addChild(BtnD);

BtnD.x = 160;

BtnD.y = 112;

addChild(BtnE);

BtnE.x = 110;

BtnE.y = 112;

addChild(Btn0);

Btn0.x = 60;

Btn0.y = 112;

addChild(BtnC);

BtnC.x = 10;

BtnC.y = 112;

addChild(BtnPN);

BtnPN.x = 110;

BtnPN.y = 146;

addChild(BtnDec);

BtnDec.x = 60;

BtnDec.y = 146;

/**********A cheap (not the best, but good enough for us) easy way to keep the display refreshing******/

addEventListener(Event.ENTER_FRAME, OnEnterFrame);

function OnEnterFrame(event:Event):void {

digitDisplay.text = Calc.getDispNum(); //returns a string

}

So, now that we’ve made all the basic buttons, it’s time to get into the heart of this calculator. Everything happens in one class I called Calc.
First of all I want to explain that I usually like to make public static constants for a lot of my strings that I want to use as a parameter because it makes it easier to debug if you make a typo. You saw them being used when I created the instances of my operator buttons and here they are being declared in my Calc class:

package classes {

public class Calc {

/*****Useing these makes debuging easier and is good practice****/

public static const ADD:String = "add";

public static const SUBTRACT:String = "subtract";

public static const MULTIPLY:String = "multiply";

public static const DIVIDE:String = "divide";

public static const EQUALS:String = "equals";

public static const CLEAR:String = "clear";

public static const DECIMAL:String = "decimal";

public static const POS_NEG:String = "positive/negative";

public static const SQRT:String = "sqrt";

public static const SQUARE:String = "square";

public static const POWER:String = "power";

public static const BACK:String = "back"; public static var isActive:Boolean; //Used to tell me what to display, the total or the number being entered.

public static var activeNum:Number; //The number being entered.

public static var decVal:Number; //Used to place the next decimal at the Nth place.

private static var total:Number;

private static var activeFunc:Function; //Points to the opporator function currently active.

public function Calc() { //This constructor isn’t really used.

clearField();

}

public static function clearField():void { //Resets the calculator.

total = 0;

activeNum = 0;

isActive = false;

decVal = -1;

activeFunc = addition;

}

/*This meathod is called from the BaseFuncBtn class and is passed

the operator name of the key. Value received should be one of the

public constants declared earlier in this class.*/

public static function funcKey(str:String):void {

switch(str) {

case "add":

equals();

activeFunc = addition;

break;

case "subtract":

equals();

activeFunc = subtraction;

break;

case "multiply":

equals();

activeFunc = multiplication;

break;

case "divide":

equals();

activeFunc = division;

break;

case "clear":

if(isActive){ //If you made a mistake while entering a number, this will forgive you a little.

isActive = false;

activeNum = 0;

}else {

clearField();

}

break;

case "equals":

isActive = true; //Set to ‘true’ so you can repeat the last opperation over and over.

equals();

break;

case "decimal":

if(decVal < 0)

decVal = 0;

break;

case "positive/negative":

if(isActive){

activeNum *= -1;

}else {

total *= -1;

}

break;

default:

trace("Something went wrong. String was: " + str);

}

/*Called from the stage and is used to display the current values*/

public static function getDispNum():String {

if(decVal < 0){

if(isActive){

return(String(activeNum));

}

return(String(total));

}else {

/*If decVal is >= 0 then isActive WILL be true, so this code

here isn’t all needed. But, it’s not hurting anything either…

The computer was rounding decimals off weird (i.e. instead of 2.3

it would have something like 2.300000012) so I need .toFixed() for

the active number being entered.*/

if(isActive){

return(String(activeNum.toFixed(decVal)));

}

return(String(total.toFixed(decVal)));

}

private static function equals():void {

if(isActive){

total = activeFunc(total, activeNum);

isActive = false; //Set to ‘false’ so you can change your mind about the next opperation without re-calculating

decVal = -1;

}

private static function addition(num1:Number, num2:Number):Number {

return(num1 + num2);

}

private static function subtraction(num1:Number, num2:Number):Number {

return(num1 – num2);

}

private static function multiplication(num1:Number, num2:Number):Number {

return(num1 * num2);

}

private static function division(num1:Number, num2:Number):Number {

return(num1 / num2);

}

Notice that almost everything in that class is STATIC. This is so we don’t have to create an instance of the class to use them. For example, in my OnEnterFrame function I used digitDisplay.text = Calc.getDispNum(); The digitDisplay is an instance of a textField that I put on the stage, while Calc is just my class.

The last thing that needs to be done is entering a little bit of code that needs to be run when you click a button. That was some fun code to come up with (not really):

/******In the BaseDigitBtn class********/

private function OnRelease(event:MouseEvent):void {

/*This just resets the active number before the next opperation. I don’t

want to erase the old active number till the last second so that I can

repeat the last opperation by pressing equals again.*/

if(!Calc.isActive){

Calc.activeNum = 0;

}

if(Calc.decVal < 0){

if(Calc.activeNum >= 0){

Calc.activeNum = Calc.activeNum * 10 + num;

}else {

Calc.activeNum = Calc.activeNum * 10 – num;

}

}else {

if(Calc.decVal < 20)

Calc.decVal++; //Decimals are annoying.

if(Calc.activeNum >= 0){

Calc.activeNum = Calc.activeNum + (num / Math.pow(10, Calc.decVal));

}else {

Calc.activeNum = Calc.activeNum – (num / Math.pow(10, Calc.decVal));

}

Calc.isActive = true;

}

/************And in the BaseFuncBtn class**********/

private function OnRelease(event:MouseEvent):void {

Calc.funcKey(str);

}

A quick explination of the BaseDigitBtn’s OnRelease function and then we are done:
Entering numbers on a calculator always places the new digit to the far right. That is easy to take care of by multiplying by 10 to shift what you have to the left and then adding your new number… untill you try to enter decimals. With decimals you have to divide by the next highest power of 10 for every spot you move to the right and this can cause some rounding errors. I take care of that in Calc.getDispNum(); with the .toFixed() which will cut it off and not show the 12,000,000th of a unit that it’s off.

You can download the source files for this tutorial here: Calculator Flash Source

It shouldn’t take long at all to add a square root operator key or sin/cos/tan keys. Try it yourself.

Answers to ALL your ActionScript questions.

Paul — Tue, 19 Feb 2008 17:54:28 +0000

As a designer you might be really excited about the power Flash CS3 has to offer you, but a little frustrated with the complicated ActionScript required to turn your vision into reality. Or maybe, as a Flash developer you are getting hung up on the difficult transition from ActionScript 2.0 to AS 3.0. Well, it’s my job here to try and help you through that learning process.

I’m going to be trying to post a new ActionScript 3.0 tutorial once a week (and maybe some AS 2.0 tutorials if requested) every Monday. If you have any specific requests or questions you can ask them in a post comment or send me an e-mail at Paul@ClickPopMedia.com. If you are looking for more immediate answers there is a great resource for ActionScript help at ActionScript.org. You might see me answering questions in their forum (as TomMalufe) or see some of my tutorials posted there.