I have made a simple example flash movie with the actionscript physics engine to show you briefly how it works. If you are unsure about any on the classes i talk (and try to explain) in this post then you can take a look at the APE documentation here.

You will have needed to read this tutorial before starting!

Here is hopefully what we will be creating.

You should see a load of cascading black balls bouncing off various shapes. This is only the very basics of what APE can do but it is amazing as the physics seem very realistic.

Ok, i am now going to show you the entire code and then i will explain it.

What the code means!

Line 1: Setting the movies frame rate to 30 frames per second. This is what i use as my framerate when making games. 

Line 2: Importing the APE classes, if you followed the previous tutorial than this line should work fine.

Lines 3-6: Importing the necessary flash classes.

Line 7: This line adds a listener that triggers the function run every frame. Run is declared later in the code.

line 8: For the APE engine to run it needs to have a container movieclip. This can be set as this or stage but i prefer to have it in a movieClip that i can control. So i have created a new movieClip called "apeholder".

line 9: Setting the dimensions for the apeholder movieClip.

line 10: Adding the apeholder movieClip to the display list.

Line 11: This is setting up an array which will hold the balls that i create. Arrays are objects that store data which can be easily manipulated. For example if i use a for statement like i do later to declare the balls, if i add the balls to the ballarray than i can access them individually later.

line 12: Now we start to add properties directly to the instance of the APE engine that we are using. The init property tells APE to initialize itself. Lower values result in slower more accurate physics where as higher values give faster less accurate physics.

line 13: As i explained earlier this tells the APEngine that it is contained within the apeholder movieClip.

line 14: This adds a force to the physics for example gravity or wind. Vectors are scalers in a direction so this provides a directional force in this case gravity. With no X force and 2 Y force.

line 15: We need to make a group that contains our simulation so i have made on e called examplelevel.

line 16: Making the group able to collide with itself.

line 17: Adding particles to the group. the first one is a rectangle particle called leftwall. In the parameters there is (x, y, width, height, rotation(inradians), fixed). So for this example i have made a particle with an x value of 5, a y of 200, 10 pixels high, 600 pixels tall, no rotation and i have made it fixed to its original position.

line 18: APE comes with a very nice built in drawing API so in this line i have set the style of the bar. setStyle(3 (line thickness), 0x000000(colour - black), 1(alpha of line), 0xFFFFFF(fill colour), 1(fill alpha) ). 

line 19: adding the particle that we just made to the group example level that we made earlier.

lines 20-22: setting up the right wall which is exactly the same as the left wall just with a different x position do no need to explain it.

line 23: Setting up a for statement. These are used to execute code multiple times without having to retype it. You have to set up a variable number i have called mine ballnum. The second input is how many times you want the code to loop in this case 25 and the final input is how much you want the ballnum to go up by, this case its 1.

line 24: Making a new circleparticle from its APE class called ball. The parameters are (x, y, radius, fixed, mass). So i have set up the ball with random x and y coordinates.

line 25: Setting the style of the balls, this is the same as we used earlier for styling the rectangle particles.

line 26: Adding the ball particle to the example level group that we made earlier.

line 27: remember that array that we set up at the beginning? Well we are going to push the ball particle that we made into the array so that it can be accessed from outside the for statement.

line 28: Closing the for statement.

lines 29-34: Creating 2 more fixed rectangle particles the same way as we did before.

lines 35-40: Creating 2 more circle particles that are bigger than the balls we made and that can't move to use as platforms.

line 41: Adding the group example level to the APEngine, this must be done in order to use this group.

line 42: Making a function called run that is triggered every frame by the event listener that we set up near the beginning of the code.

line 43: This is the built-in function in ape that makes all the particles collide and move, this is essential for ape to work.

line 44: This is the built in drawing api that is used to draw all of the ape example that we have made.

line 45: This is another for statement. Like before we have to make a number this time i have called it ballstocheck. in the next parameter it will run as long as it is less than the number of objects in the ballArray, 25. It will go up in ones like the other for statement.

line 46: This if statement checks to see if the balls y position is greater than 400. It does this by using the ball array that we made earlier with the balls to check number.

line 47: Changes the y position of the ball to -50

lines 48-50: Closing the statements.

Hopefully this should work, if you have any issues with the code than just leave a comment and i will get back to you.

APE, or the Actionscript Physics Engine is a free as3 physics engine built by Alex Cove. It is really easy to use once you get the hang of it and it has detailed documentation to read if you get stuck.

In this tutorial i will show you how to make a simple ball example with gravity.

Firstly you will need to download the latest version of APE. There is a stable release on Alex Cove's website but i am using the 'bleeding edge' one from the google code repository. You can download the whole package from my site here.

Unzip the folder and save it in a place so that you know where it is for example mine is located in my documents folder on my computer.

Now load up flash and create a new actionscript 3 file like normal and save this file however you want. To load the APE classes into the flash authoring environment so that we can use them we first need to change the root classpath of the .swf that will be created. The next step is the most important to get APE running in flash. Follow exactly as i say!

Go to file>publish settings then a screen should pop up that looks like this one below. Click on the flash tab in the centre, that is highlighted in the picture below. Now look to the picture on the right.

Click on actionscript 3 settings, where the mouse curser is on the screenshot. A screen like the one below should show.

Click on the browse to path button that is above the large 'classpath' box at the bottom of the window, where the mouse curser is pointing.

This will send you to a browsing screen where you have to select the classpath.

h of your .swf. You need to choose the ape_a045 folder that you downloaded earlier and select the source folder inside that. This is where your classpath needs to be. Take a look at this picture. The folder should only have a folder called org inside it like shown.

Click choose and then the white box at the bottom of the publish settings should have the direct path to the source folder inside the ape_a045 folder on it.

If the class path is correct click OK and then click OK again to return to the flash authoring environment.

Next we can start to code and use the engine.

Loading sound from an external source (i.e, not embedded in the .swf file) is really easy to do once you know how. I am going to use the same example as i used for the last tutorial but the sound is not going to be embedded in the .swf it is going to be hosted on my site

Here is the example. I have changed the sound to a whole song to demonstrate how quickly it takes to load.

Important!

Before i started i uploaded a .mp3 file to the internet so that i could call it with a URL request in this code.

You will need to do this for this code to work from the internet, alternatively you can put a sound file in the root classpath of your .fla (this is usually the same folder as the .fla).

Another important note

if you are loading a file on the internet change you publish settings for flash to “access network file only” and if you are loading it from a folder change it to “access local files only”.

To do this it was simple. I replaced one line of the old code for three more lines of code.

I replaced the line:

var sound:Sound = new acoust();

with:

var loadsound:URLRequest = new URLRequest("http://where my mp3 file is on the internet.mp3");

var sound:Sound = new Sound();

sound.load(loadsound);

Line 1: a new variable called loadsound which requests the file from the url mentioned inside the brackets and the “”

line 2: a variable like before that holds a blank instance of the sound class instead of the class that we made called acoust.

line 3: loading the sound that we got from the internet via the URL request into the blank instance of the sound class that we named earlier. 

Note: if you want to load the sound locally from a folder you just replace "http://where my mp3 file is on the internet.mp3" with “sound name.mp3” 

The complete code for ease.

import flash.media.Sound;

var loadsound:URLRequest = new URLRequest("http://where my mp3 file is on the internet.mp3");

var sound:Sound = new Sound();

sound.load(loadsound);

var channel:SoundChannel;

var soundisplaying:Boolean = false;

var pausePosition:int = 0;

playbut.addEventListener(MouseEvent.CLICK, playsound);

stopbut.addEventListener(MouseEvent.CLICK, stopsound);

function playsound(event:Event):void {

if (soundisplaying==false) {

channel = sound.play(pausePosition);

soundisplaying = true;

channel.addEventListener(Event.SOUND_COMPLETE, soundComplete);

}

}

function stopsound(event:Event):void {

pausePosition = channel.position;

channel.stop();

soundisplaying =false;

}

function soundComplete(event:Event):void {

channel = sound.play();

channel.addEventListener(Event.SOUND_COMPLETE, soundComplete);

}

Ok this will hopefully help some of you.

i am going away for a week so don’t expect any more posts until i get back!