Play the Game

Use the left and right arrow keys to manoeuvre your ship, the up and down arrow keys to increase or reduce the size of the magnetic field it produces, and the space bar to reverse the polarity. Collect the white crystals to increase your fuel supply – but avoid the red ones, because they use it up. Don’t hit a rock, or it’s game over!

In this tutorial, we won’t actually create the full game displayed above; we’ll just get started on it, by making a very simple version with primitive graphics and just one type of object. However, by the end, you should have learned enough to be able to add the other features yourself!

The game itself is very simple in its current state. Check back later today for a look at what we could do to improve the game! This tutorial is going to focus on the code and math required to build this demo.

Let’s Get Started!

Set up a new AS3 project in FlashDevelop, and set its dimensions to 550x600px.

Step 1: Identifying the Game Objects

There are six objects in particle that you can identify from playing the game above:

Energy supply – represented by an white oval shape object

Asteroid – represented by a rock-like object

Energy consumer – represented by a red star bounded with green light.

Stars – the background

Range indicator – represented by a white circle

Ship – player object

Of course you can add in any other object to make the game more interactive or add a new feature. For this tutorial we’ll just make

Step 2: The Energy Class

From the objects we identified, four of them actually work in exactly the same way: by falling from top to bottom.

They are:

Stars

Energy supply

Energy consumer

Asteroid

In this tutorial, we’re only going to make the “energy supply” objects, out of the four above. So let’s begin by creating these objects and making them fall down, with a random spawning position and speed.

We’re going to pass a reference to the stage to this class from our Main class (which is automatically created by FlashDevelop as the starting class for our game). This will allow us to add display objects to the display list from this class.

Step 4: Update The Main Class

We’ll now create an instance of StageController within Main and pass it a reference to the stage:

We create a new energy supply with a speed of 4, add it directly to the stage via the StageController, add it to the Vector of all energy objects that we just created, and set its position to a random point within certain bounds.

Editor’s Note: I’m a little uncomfortable with adding a display object directly to the stage like that, although of course it does work. One alternative would be to create a function within StageController that handles this for us.

The Calculation.generateRandomValue(#, #) is a static function we haven’t written yet, so let’s do that now. Create a new class called Calculation and add this function:

This function will generate a random number between the two values passed to it. For more information on how it works, see this Quick Tip. Since this is a static function, we don’t need to create an instance of Calculation in order to call it.

Step 7: Spawning Energy

Let’s set a timer that defines the interval for each spawning. This code goes in StageController‘s constructor function:

So far we should have a few energy supplies falling few seconds, and the player appearing in the middle of the screen:

Step 9: Moving the Player

There are basically two ways to apply movement:

Using Boolean (true/false) values – true = moving, false = not moving. When the right arrow key is pressed, the value for “moving right” will change to true. In each frame update, “moving right” is true, we increase the object’s x-value.

Using direct update each frame – when the right arrow key is pressed, an object is told to move right immediately, by increasing its x-value.

The second method does not lead to smooth movement when the key is continuously pressed, but the first method does – so we shall use the first method.

There are three simple steps to doing this:

Create two Boolean variables, one for moving right and one for moving left.

Line 32: note that we pass in a reference to the player, so that we can access its position.

Line 38: EnergyS is short for Energy Supply.

Line 40 & 41: finding the difference in x- and y-coordinates between the player and the energy supply we are currently checking.

Line 43: calculate the distance between the objects via Pythagorus.

Line 45: check for collision; 28 is the sum of the two objects’ radii (player radius is 20, energy radius is 8).

Line 46 & 47: remove energy supply from screen and from Vector.

Line 51: add a maximum of one unit of energy per frame.

You could alter Line 51 to energyTransfer += 1, to allow the player to absorb more than one energy object at once. It’s up to you – try it out and see how it affects the game.

Step 11: Call Collision Detection Routine

We need to check for collisions every frame, so we should call the function we just wrote from StageController.update().

First, we need to create an integer variable to store the energy transfer value from the collision detection function. We’ll use this value for increasing the ship’s energy and adding to the player’s score.

private var returnedPower:int = 0;

returnedPower = energyM.checkCollision(player);

Step 12: Newton’s Law of Gravitation

Before we go into creating the game mechanic for the ‘Push’ and ‘Pull’ function of the ship, I would like to introduce the physics concept on which the mechanic is based.

The idea is to attract the object towards the player by means of a force. Newton’s Law of Universal Gravitation gives us a great (and simple) mathematical formula we can use for this, where the force is of course the gravitational force:

G is just a number, and we can set it to whatever we like. Similarly, we can set the masses of each object in the game to any values that we like. Gravity occurs across infinite distances, but in our game, we’ll have a cut-off point (denoted by the white circle in the demo from the start of the tutorial).

The two most important things to note about this formula are:

The strength of the force depends on the square of the distance between the two objects (so if the objects are twice as far away, the force is one-quarter as strong).

The direction of the force is along the direct line connecting the two objects through space.

Step 13: Revising Math Concepts

Before we start coding the game mechanics for the ‘Push’ and ‘Pull’ function, let’s be clear on what we want it to do:

Essentially, we want A (the player) to exert a certain force on B (a crystal), and move B towards A based on that force.

We should revise a few concepts:

Flash works in radians rather than degrees.

Flash’s coordinate system has its y-axis reversed: going down means an increase in y.

We can get the angle of the line connecting A to B using Math.atan2(B.y - A.y, B.x - A.x).

We can use trigonometry to figure out how much we need to move B along each axis, based on this angle and the force:

B.x += (Force*Math.cos(angle));

B.y += (Force*Math.sin(angle));

We can use Pythagorus’s theorem to figure out the distance between the two objects:

With random alpha, size, position, and speed, a pseudo-3D background can be generated.

Range indicator

A range indicator circle can be made by simply creating another circle and adding it to the ship’s display list, just like how you added the power indicator text. Make sure the circle is centred on the ship, and has a radius equal to the ship’s push/pull range.

Add transparancy (alpha value) to the circle with the below code:

graphics.beginFill(0xCCCCCC, 0.1);

Try adding extra controls that make the range increase or decrease when the up and down arrow keys are pressed.

Play the Game

Use the left and right arrow keys to manoeuvre your ship, the up and down arrow keys to increase or reduce the size of the magnetic field it produces, and the space bar to reverse the polarity. Collect the white crystals to increase your fuel supply – but avoid the red ones, because they use it up. Don’t hit a rock, or it’s game over!

In this tutorial, we won’t actually create the full game displayed above; we’ll just get started on it, by making a very simple version with primitive graphics and just one type of object. However, by the end, you should have learned enough to be able to add the other features yourself!

The game itself is very simple in its current state. Check back later today for a look at what we could do to improve the game! This tutorial is going to focus on the code and math required to build this demo.

Let’s Get Started!

Set up a new AS3 project in FlashDevelop, and set its dimensions to 550x600px.

Step 1: Identifying the Game Objects

There are six objects in particle that you can identify from playing the game above:

Energy supply – represented by an white oval shape object

Asteroid – represented by a rock-like object

Energy consumer – represented by a red star bounded with green light.

Stars – the background

Range indicator – represented by a white circle

Ship – player object

Of course you can add in any other object to make the game more interactive or add a new feature. For this tutorial we’ll just make

Step 2: The Energy Class

From the objects we identified, four of them actually work in exactly the same way: by falling from top to bottom.

They are:

Stars

Energy supply

Energy consumer

Asteroid

In this tutorial, we’re only going to make the “energy supply” objects, out of the four above. So let’s begin by creating these objects and making them fall down, with a random spawning position and speed.

We’re going to pass a reference to the stage to this class from our Main class (which is automatically created by FlashDevelop as the starting class for our game). This will allow us to add display objects to the display list from this class.

Step 4: Update The Main Class

We’ll now create an instance of StageController within Main and pass it a reference to the stage:

We create a new energy supply with a speed of 4, add it directly to the stage via the StageController, add it to the Vector of all energy objects that we just created, and set its position to a random point within certain bounds.

Editor’s Note: I’m a little uncomfortable with adding a display object directly to the stage like that, although of course it does work. One alternative would be to create a function within StageController that handles this for us.

The Calculation.generateRandomValue(#, #) is a static function we haven’t written yet, so let’s do that now. Create a new class called Calculation and add this function:

This function will generate a random number between the two values passed to it. For more information on how it works, see this Quick Tip. Since this is a static function, we don’t need to create an instance of Calculation in order to call it.

Step 7: Spawning Energy

Let’s set a timer that defines the interval for each spawning. This code goes in StageController‘s constructor function:

So far we should have a few energy supplies falling few seconds, and the player appearing in the middle of the screen:

Step 9: Moving the Player

There are basically two ways to apply movement:

Using Boolean (true/false) values – true = moving, false = not moving. When the right arrow key is pressed, the value for “moving right” will change to true. In each frame update, “moving right” is true, we increase the object’s x-value.

Using direct update each frame – when the right arrow key is pressed, an object is told to move right immediately, by increasing its x-value.

The second method does not lead to smooth movement when the key is continuously pressed, but the first method does – so we shall use the first method.

There are three simple steps to doing this:

Create two Boolean variables, one for moving right and one for moving left.

Line 32: note that we pass in a reference to the player, so that we can access its position.

Line 38: EnergyS is short for Energy Supply.

Line 40 & 41: finding the difference in x- and y-coordinates between the player and the energy supply we are currently checking.

Line 43: calculate the distance between the objects via Pythagorus.

Line 45: check for collision; 28 is the sum of the two objects’ radii (player radius is 20, energy radius is 8).

Line 46 & 47: remove energy supply from screen and from Vector.

Line 51: add a maximum of one unit of energy per frame.

You could alter Line 51 to energyTransfer += 1, to allow the player to absorb more than one energy object at once. It’s up to you – try it out and see how it affects the game.

Step 11: Call Collision Detection Routine

We need to check for collisions every frame, so we should call the function we just wrote from StageController.update().

First, we need to create an integer variable to store the energy transfer value from the collision detection function. We’ll use this value for increasing the ship’s energy and adding to the player’s score.

private var returnedPower:int = 0;

returnedPower = energyM.checkCollision(player);

Step 12: Newton’s Law of Gravitation

Before we go into creating the game mechanic for the ‘Push’ and ‘Pull’ function of the ship, I would like to introduce the physics concept on which the mechanic is based.

The idea is to attract the object towards the player by means of a force. Newton’s Law of Universal Gravitation gives us a great (and simple) mathematical formula we can use for this, where the force is of course the gravitational force:

G is just a number, and we can set it to whatever we like. Similarly, we can set the masses of each object in the game to any values that we like. Gravity occurs across infinite distances, but in our game, we’ll have a cut-off point (denoted by the white circle in the demo from the start of the tutorial).

The two most important things to note about this formula are:

The strength of the force depends on the square of the distance between the two objects (so if the objects are twice as far away, the force is one-quarter as strong).

The direction of the force is along the direct line connecting the two objects through space.

Step 13: Revising Math Concepts

Before we start coding the game mechanics for the ‘Push’ and ‘Pull’ function, let’s be clear on what we want it to do:

Essentially, we want A (the player) to exert a certain force on B (a crystal), and move B towards A based on that force.

We should revise a few concepts:

Flash works in radians rather than degrees.

Flash’s coordinate system has its y-axis reversed: going down means an increase in y.

We can get the angle of the line connecting A to B using Math.atan2(B.y - A.y, B.x - A.x).

We can use trigonometry to figure out how much we need to move B along each axis, based on this angle and the force:

B.x += (Force*Math.cos(angle));

B.y += (Force*Math.sin(angle));

We can use Pythagorus’s theorem to figure out the distance between the two objects:

With random alpha, size, position, and speed, a pseudo-3D background can be generated.

Range indicator

A range indicator circle can be made by simply creating another circle and adding it to the ship’s display list, just like how you added the power indicator text. Make sure the circle is centred on the ship, and has a radius equal to the ship’s push/pull range.

Add transparancy (alpha value) to the circle with the below code:

graphics.beginFill(0xCCCCCC, 0.1);

Try adding extra controls that make the range increase or decrease when the up and down arrow keys are pressed.

Conclusion

There are several methods used to produce menus within Unity, the main two being the built in GUI system and using GameObjects with Colliders that respond to interactions with the mouse. Unity’s GUI system can be tricky to work with so we’re going to use the GameObject approach which I think is also a bit more fun for what we’re trying to achieve here.

Final Result Preview

Please view the full post to see the Unity content.

Step 1: Determine Your Game Resolution

Before designing a menu you should always determine what resolution you are going to serve it to.

Open the Player settings via the top menu, Edit > Project Settings > Player and enter your default screen width and height values into the inspector. I chose to leave mine as the default 600x450px as shown below.

You then need to adjust the size of your Game view from the default "Free Aspect" to "Web (600 x 450)", else you could be positioning your menu items off the screen.

Step 2: Choosing a Menu Background

As you will have seen in the preview, our menu scene is going to have our game environment in the background so that when you click Play you enter seamlessly into the game.

To do this you need to position your player somewhere in the scene where you like the background and round up the Y rotation value. This is so it’s easier to remember and to replicate later, so that the transition can be seamless from the menu into the game.

Let’s now get on with the creation of the menu scene!

Step 3: Creating the Menu Scene

Make sure your scene is saved and is called "game" – you’ll see why later.

Select the game scene within the Project view and duplicate it using Ctrl/Command + D, then rename the copy to "menu" and double-click it to open it.

Note: You can confirm which scene is open by checking the top of the screen, it should say something like "Unity – menu.unity – ProjectName – Web Player / Stand Alone". You don’t want to start deleting parts accidently from your game scene!

Now select and delete the GUI and PickupSpawnPoints GameObjects from the Hierarchy. Expand the "Player" and drag the "Main Camera" so that it’s no longer a child of the Player, then delete the Player.

Next, select the terrain and remove the Terrain Collider Component by right-clicking and selecting Remove Component.

Finally, select the "Main Camera" and remove the MouseLook Component by right-clicking and selecting Remove Component.

If you run the game now nothing should happen and you shouldn’t be able to move at all. If you can move or rotate then redo the above steps.

Step 4: Adjusting the Build Settings

Currently when you build or play your game the only level included within that build is the "game" scene. This means that the menu scene will never appear. So that we can test our menu, we’ll adjust the build settings now.

From the top menu select File > Build Settings and drag the menu scene from your Project View into the Build Settings’ "Scenes In Build" list as shown below

(Make sure you rearrange the scenes to put "menu.unity" at the top, so that it’s the scene that’s loaded first when the game is played.)

Perfect!

Step 5: Adding the Play Button

We’re going to use 3D Text for our menu, so go ahead and create a 3D Text GameObject via the top menu: GameObject > Create Other > 3D Text, then rename it "PlayBT". Set the Y rotation of the PlayBT text to match the Y rotation value of your Main Camera so that it’s facing directly at it and therefore easily readable.

With the PlayBT selected, change the Text Mesh text property from Hello World to "Play", reduce the Character Size to 0.1 and increase the Font Size to 160 to make the text crisper.

Note: If you want to use a font other than the default, either select the font before creating the 3D Text or drag the Font onto the 3DText’s TextMesh’s Font property and then drag the Fonts "Font Material" onto the Mesh Renderers Materials list, overwriting the existing Font Material. Quite a hassle I know!

Finally, add a Box Collider via the top menu: Component > Physics > Box Collider. Resize the Box Collider to fit the text if it doesn’t fit it nicely.

At this point in the tutorial you really need to have both the Scene and Game Views open at the same time since you are now going to move the PlayBT within the Scene View so that it’s centred within your Game View as shown below. I recommend first positioning it horizontally using a top down view and then revert to using a perspective view to position it vertically using the axis handles.

So that’s our Play button all set up. Now let’s make it play!

Step 6: The Mouse Handler Script

Create a new JavaScript script within your scripts folder, rename it "MenuMouseHandler" and add it as a Component of the PlayBT GameObject by either dragging in directly onto PlayBT or by selecting PlayBT and dragging the script onto it’s Inspector.

Enough talk – go run it and watch your game come to life when you click Play!

Note: If you click Play and have found yourself with a build settings error, don’t fret; you just need to check your build settings – revisit Step 4.

Step 7: Ending the Game

So the menu to start the game is great but the game technically never ends since when the timer runs out nothing happens… let’s fix that now.

Open the CountdownTimer script and at the bottom of the Tick() function add the following line:

Application.LoadLevel("menu");

Now re-run your game and when the timer runs out you’ll be taken back to the menu! Easy Peasy!

There we go – a basic menu added to our game. Now let’s make it a little more user friendly with a help screen to explain how to play.

Step 8: Adding the Help Button

The help button is identical to the PlayBT in practically every way, so go ahead and duplicate the PlayBT, rename it to HelpBT and position it below the Play button. Adjust the text property to say "Help" rather than "Play" and perhaps make the Font Size a little smaller as shown below – I used 100.

Now open the MenuMouseHandler script and add the following else if block to your existing if statement.

// if we clicked the help button
else if (this.name == "HelpBT")
{
// rotate the camera to view the help &quot;page&quot;
}

If you check the preview you’ll see that when you click Help the camera rotates around to show the help menu. So, how do we do that?

Step 9: God Save iTween

Our camera rotation can all be done nice and cleanly in one line, thanks to iTween. Without iTween life wouldn’t be nearly as fun. As the name may give away it’s a tweening engine, built for Unity. It’s also free.

Go ahead and open iTween within the Unity Asset store, then click Download/Import and import it all into your project. Once it’s imported you need to move the iTween/Plugins directory into the root of your Assets folder.

You’re now all set to tween your life away!

Step 10: Rotating the Camera

Grab a piece of paper and a pen (or open a blank document) and make a note of your Main Camera’s Y rotation value, as circled below.

Within the scene view rotate the camera around in whichever direction you like around the Y axis so that the Play and Help text are out of view and so that you’ve got a decent background for your help page. You can see mine below: I rotated from -152 to -8.

Return to your MenuMouseHandler script and add the following line within the else if statement:

iTween.RotateTo(Camera.main.gameObject, Vector3(0, -8, 0), 1.0);

We use Camera.main to retrieve the main camera (defined by the "MainCamera" tag) from the scene and use iTween.RotateTo(…) to rotate the camera to a specific angle – in my case -8.

(You need to replace the -8 within the above line with your camera’s current rotation.)

Now go back to your scene and return your camera back to its original rotation that you wrote down at the start of this section, so that it’s facing the PlayBT. Run your game, click Help and the camera should spin around. Woo!

Note: If you get an error about iTween not existing then you haven’t imported it properly – revisit Step 9.

Now let’s build our Help page.

Step 11: Building the Help Page

Rotate your camera back to the Y rotation of your help page – in my case -8.

Now we’re going to add a little explanation text as well as some more text to explain the different pickups and their scores. Finally, we’ll add a Back button to return to the main menu. You can arrange your page in whatever way you wish so feel free to get creative. Here we go…

Duplicate the HelpBT, rename it HelpHeader, set its rotation to that of your camera, change the Anchor value to "upper center" and reduce the Font Size – I used 60.

Next, copy and paste the below paragraph into the text property:

"Collect as many Cubes as you can within the time limit.
Watch out though, they change over time!

Note: It’s worth noting that you can’t type multiline text into the text property; you have to type it in another program and then copy and paste it since pressing enter/return assigns the field.

Finally remove the Box Collider and MenuMouseHandler Components within the Inspector since this text won’t need to be clickable. Hopefully you end up with something like this:

Now drag a pickup prefab into the scene and position it on the screen. I put mine as shown below.

Next, duplicate the HelpHeader, rename it to HelpPowerups, change the Anchor to "upper-left" and copy and paste the below paragraph into the text field.

"Green: + 2 Points

Pink: +/- Random Points

Blue: Random Speed Boost"

Reposition it so you have something like the below.

All that’s left now is to add a Back button to return to the main menu.

Step 12: The Help Page Back Button

Duplicate the HelpBT, rename it BackBT, change its text to "Back", set its rotation to that of your camera and use the Scene View to reposition it within the Game View. I placed mine in the bottom corner as shown here:

Now we just need to update our MenuMouseHandler script to handle mouse clicks from the BackBT as well. Add the following else if block to the bottom of the OnMouseDown()if statements:

This is nearly identical to the previous iTween statement, the only difference being the angle the camera is rotated to – -152 in my case. You need to change this number to the original Y rotation of your camera was (the one you wrote down, remember?)

Now all you need to do it set your camera back to its original rotation – the value you just added to the iTween statement – so that it’s facing the main menu again.

Run the game and your camera should spin round to reveal the help page and spin back round to the main menu. Congratulations, you’ve finished!

Or add an iTween CameraFade and then fade it out when the timer runs out, then load then menu – rather than abruptly ending the game. You could then delay the call to Application.LoadLevel(...) using yield WaitForSeconds(...).

We’ve tackled drawing curves, and finding their quadratic and cubic roots, as well as handy applications for using quadratic roots within games. Now, as promised, we’ll look at applications for finding cubic roots, as well as curves’ gradients and normals, like making objects bounce off curved surfaces. Let’s go!

Example

Let’s take a look one practical use of this math:

In this demo, the “ship” bounces off the edges of the SWF and the curve. The yellow dot represents the closest point to the ship that lies on the curve. You can adjust the shape of the curve by dragging the red dots, and adjust the movement of the ship using the arrow keys.

Step 1: Shortest Distance to a Curve

Let’s consider the scenario where a point is located near a quadratic curve. How do you calculate the shortest distance between the point and the curve?

You can see that we have substituted \(y_c\) with the quadratic equation. At a glance, we can see the highest power is 4. Thus, we have a quartic equation. All we need to do is to find a minimum point in this equation to give us the shortest distance from a point to a quadratic curve.

But before that, we’ll need to understand gradients on a curve…

Step 2: Gradient of a Curve

Before we look at the problem of minimizing a quartic equation, let’s try to understand gradients of a curve. A straight line has only one gradient. But a quadratic curve’s gradient depends on which point on the curve we refer to. Check out the Flash presentation below:

Drag the red dots around to change the quadratic curve. You can also play with the slider’s handle to change the position of blue dot along x. As the blue dot changes, so will the gradient drawn.

Step 3: Gradient Through Calculus

This is where calculus will come in handy. You may have guessed that differentiating a quadratic equation would give you the gradient of the curve.

\[
f(x) = ax^2+bx+c\\
\frac{df(x)}{dx} = 2ax+b
\]

So \(\frac{df(x)}{dx}\) is the gradient of a quadratic curve, and it’s dependant on the \(x\) coordinate. Well, good thing we’ve got a method to handle this: diff1(x:Number) will return the value after a single differentiation.

To draw the gradient, we’ll need an equation to represent the line, \(y=mx+c\). The coordinate of the blue point \((x_p, y_p)\) will be substituted into the \(x\) and \(y\), and the gradient of the line found through differentiation will go into \(m\). Thus the y-intercept of line, \(c\) can be calculated through some algebra work.

Step 4: Coordinate Systems

Always bear in mind of the inverted y-axis of Flash coordinate space as shown in the image below. At first glance, the diagram on right may seem like a negative gradient – but due to the inverted y-axis, it’s actually a positive gradient.

The same goes for the minimum point as indicated below. Because of the inverted y-axis, the minimum point in Cartesian coordinate space (at (0,0)) looks like a maximum in Flash coordinate space. But by referring to the location of origin in Flash coordinate space relative to the quadratic curve, it’s actually a minimum point.

Step 5: Rate of Change for Gradient

Now let’s say I’m interested in finding the lowest point on a curve – how do I proceed? Check out the image below (both figures are in the same coordinate space).

In order to get the minimum point, we’ll just equate \(\frac{df(x)}{dx} = 0\), since by definition we’re looking for the point where the gradient is zero. But as shown above, it turns out that the maximum point on a curve also satisfies this condition. So how do we discriminate between these two cases?

Let’s try differentiation of the second degree. It’ll give us the rate of change of the gradient.

\[
\frac{df(x)}{dx} = 2ax+b\\
\frac{df^2(x)}{dx^2} = 2a
\]

I’ll explain with reference to the image below (drawn in Cartesian coordinate space). We can see that, as we increment along the x-axis, the gradient changes from negative to positive. So the rate of change should be a positive value.

We can also see that when \(\frac{df^2(x)}{dx^2}\) is positive, there’s a minimum point on the curve. Conversely if the rate is negative, a maximum point is present.

Step 6: Back to the Problem

Now we are ready to solve the problem presented in Step 1. Recall the quartic equation (where the highest degree is 4) we arrived at:

\[
z^2 = (x_c-x_p)^2 + [(ax_c^2 + bx_c + c) -y_p]^2
\]

The same quartic equation, plotted

Remember, we are interested to find the minimum point on this curve, because the corresponding point on the original quadratic curve will be the point that’s at the minimum distance from the red dot.

So, let’s differentiate the quartic function to get to gradient of this curve, and then equate the gradient of this quartic function to zero. You will see that the gradient is actually a cubic function. I’ll refer interested readers to Wolfram’s page; for this tutorial, I’ll just pluck the result of their algebra workings:

Solve for the roots of this (rather messy) cubic function and we’ll arrive at the coordinates of the three blue points as indicated above.

Next, how do we filter our results for the minimum point? Recall from the previous step that a minimum point has a rate of change that’s positive. To get this rate of change, differentiate the cubic function that represents gradient. If the rate of change for the given blue point is positive, it’s one of the minimum points. To get the minimum point, the one that we’re interested in, choose the point with the highest rate of change.

Step 7: Sample of Output

So here’s a sample implementation of the idea explained above. You can drag the red dots around to customise your quadratic curve. The blue dot can also be dragged. As you move the blue dot, the yellow one will be repositioned so that the distance between the blue and yellow dots will be minimum among all points on the curve.

As you interact with the Flash presentation, there may be times where three yellow dots appear all at once. Two of these, faded out, refer to the roots obtained from the calculation but rejected because they are not the closest points on the curve to the blue dot.

Step 8: ActionScript Implementation

So here’s the ActionScript implementation of the above. You can find the full script in Demo2.as.

First of all, we’ll have to draw the quadratic curve. Note that the matrix m2 will be referred to for further calculation.

Step 9: Example: Collision Detection

Let’s make use of this concept to detect the overlap between a circle and a curve.

The idea is simple: if the distance between the the blue dot and the yellow dot is less than blue dot’s radius, we have a collision. Check out the demo below. The interactive items are the red dots (to control the curve) and the blue dot. If the blue dot is colliding with the curve, it will fade out a little.

Step 10: ActionScript Implementation

Well, the code is quite simple. Check out the full source in CollisionDetection.as.

You can see that the keyboard controls are updating flags to indicate whether the left, up, right, or down keys are being pressed. These flags will be captured by the enterframe event handler and update the magnitude and direction of the ship.

Step 13: Calculating the Reflection Vector

I’ve already covered the vector calculation of reflection vector in this post. Here, I shall just cover how to obtain the normal vector from gradient.

Conclusion

This week, Matt Porter critiques Jelly Escape, a popular new platformer developed by TawStudio Entertainment. Platformers are a dime a dozen on Flash portals, so let’s see what this one brings to the table…

Play the Game

Overview

The web has always had an abundance of platformer games, thanks to Flash. Unfortunately, most of them lack any kind of serious polish. Fortunately, Jelly Escape isn’t one of them; it’s an incredibly well built platformer, and it’s clear that the developers did their homework and studied industry hit and obvious inspiration: Super Meat Boy.

Gameplay

Jelly Escape’s main focus is simple, quick, addicting platforming, and achieves this quite effectively. The game has a number of tricks up its sleeve to engage the player beyond the first few minutes, and the overall level of polish means players are likely to stick with the game long enough to get to that point.

The most immediate, and engaging aspect of the game to me, is the retro feel. While there has been a surplus of retro-inspired games since the introduction of great Flash game frameworks such as Flixel and FlashPunk, most don’t take that retro-magic to the same level.

As soon as I saw the opening animation where quarters were being popped into an arcade machine, I was hooked. Even if you’re not a hardcore fan of classic gaming, the added story is a very welcome addition, and is sure to please most.

Level Select

The second thing I noticed and was impressed with in Jelly Escape was the sheer number of levels the game had to offer. As soon as you start the game, you can see that there at least 60 – that’s a lot of levels! These are split into four sections of fifteen levels each, so I was pretty convinced that variety wouldn’t be an issue.

While I do love the sheer number of levels offered, I do think all great platformers should have a world map of sorts since, to me, exploration is one of my favorite aspects of gaming. Not only is arranging 60 levels as boxes with numbers a tad boring, it straight up tells you how many levels there are, and doesn’t leave any mystery for the player. I personally love unlocking a new world when I think a game is about to be complete, and this setup just doesn’t allow for that.

Another possible negative aspect of telling the player how many levels there are, is that they may find themselves slightly bored part way through your game and, knowing they’re nowhere near the end, just stop playing. If they thought that they might be nearly finished, they might just stick around another few levels to finish it up. During this time they may become bored and leave anyways, complete the game, or they might just hit your next big game mechanic that adds a breath of fresh air into their gaming experience, keeping them around that much longer.

There are a few levels that can be unlocked through your actions…

A proper compromise to having a full blown world map, versus a simple menu setup, would be to unlock new sets of levels upon the completion of a previous set. Jelly Escape has four sets, but perhaps only one needs to be seen at first; the unlocking of the others could have been used to spice up the player’s experience. Even if my love for exploration isn’t shared by all, it’s important as a developer to understand the various experiences that any gamer enjoys, so that you can be sure to fit in as many positive experiences as your game’s design will allow, and please as large an audience as possible.

Rewards and Stats

One of the strongest points of Jelly Escape is how much – and how often – the player is rewarded. Some of these rewards are given by playing the game well, while others are a bit more creative and are rewarded for completing actions such as following the developers on Twitter and Facebook.

While I’m generally against gimmicks, the unlockables are purely bonus material, and truly don’t take away from the game if you pass them up – so no harm done. It’s actually a great move on the developers part, and I’ll probably use it myself in future games, as I like their implementation.

In addition to the unlockables, the game also keeps track of a ton of stats, such as your best times and lowest death count for each level. Small features like this make for great replay value, and add a lot to the game.

Like many games of this style, Jelly Escape keeps track of how many of a certain collectible you get in each level. This information is shown on the level select screen, and is easily to understand. Unlike certain games, this rating actually matters. Far too many games will give you a “3 star rating” system of sorts, just for the hell of it, with no real incentive for the player to go back and master levels, but Jelly Escape offers two incentives to collect the energy bolts.

The first, which is my favorite, is that you can find characters locked up behind a gate within select levels (as shown on the level select screen), and if you’ve collected enough of the energy collectibles, you can set them free. Once free, you can use their appearance as your jelly’s skin, which is a pretty awesome addition, especially since some of the skins are based off of characters from other popular games.

The second, is that collecting enough bolts will unlock additional challenge levels. I played a few of these myself, and they definitely had an “unlockable level” kind of feel, much like the “secret” zone found in Super Mario World. Between these two awesome incentives, I definitely felt encouraged to replay levels, rather than to just rush through the game.

Level Design

Level design is a strong point of Jelly Escape, as it should be with any platformer. There aren’t too many mechanics in the game, but what’s there is used very well.

I never found the level design to be too repetitive or bland, and was actually impressed with the overall diversity. In addition, the difficulty curve seemed to be rather balanced, as few levels stood out as too hard, but it did feel like the difficulty was slowly climbing. To make things even better, levels are littered with checkpoints so that death isn’t overly punishing: an excellent addition that makes this game far more friendly with its casual target market. Plus, I never encountered any levels that were strictly tedious and not fun.

While the level design is quite well done, some core design choices of the game do take away from the overall fun factor. The game has a rather zoomed out feel, because all of the levels are presented within a single screen. While this seems to be accepted among many platformers, I feel that a more zoomed in view, with a camera for scrolling, is the better approach. To me, this allows for more precise movement, and gives a hint of exploration during gameplay, as you can’t see everything at once.

On the other hand, the game design often requires the levels to fit in a single screen – for example, falling through the bottom of the level simply brings you back to the top, and some levels are designed around this – so perhaps this is just a matter of my preferences getting in the way.

I will note that Super Meat Boy isn’t limited to a single screen however, and I feel that if it had been, it would greatly deter from the experience. Perhaps this was a deliberate design choice, perhaps scrolling levels were simply a technical complexity the developers didn’t want to mess with; either way, I still feel a more zoomed-in experience would benefit the game’s design.

Graphics

The graphics in Jelly Escape are retro, but kick things up with with massive attention to small details in visual effects. Touching walls covers them with your jelly’s slime, and spits out particle effects. Dying makes the edges of the screen tweak out. There’s a neat lighting effect in place where you can see better around your character, and collecting energy within a level increases this effect significantly.

The game is also very animation complete, something that is often lacking in indie platformers. The player is excellently animated, energy collectibles are animated, springs are animated; everything that should have an animation, does. All menus are very clean, and all menu items have a hover effect, which makes for a very polished game. While you may think that menus are nearly worthless in a game as simple as a platformer, retaining a polished and positive image consistently throughout the project is extremely important. If you’re not willing to polish your audio-mute button, don’t bother polishing your enemy animations, as a lack of consistency breaks the entire image.

All in all, the graphical quality of this greatly excels because of the extreme attention to small details. No single effect is a game changer on its own, but together, they make this game look ten times better than it would without them.

Audio

While the audio is nothing amazing in Jelly Escape, it’s still quite well done. I find the music very fitting to the somewhat dark and ominous atmosphere, and I personally feel it’s a very good fit.

As was the case with animations and effects for grpahics, Jelly Escape is extremely complete in the audio department. There’s sounds for literally everything. Jumping has a sound, landing has a sound, enemies hitting walls, opening gates, hitting buttons, dying, hovering over menu items; everything in the entire game has a sound, as it should be.

To further add polish, the toggle music and sound buttons are pretty awesome looking too. Each is its own small audio visualizer, which I found very neat. This is most definitely not needed, but if I noticed it, others did too, so take note of the positive effects such features can have on a players mode, and how it can effect their perception of an author’s hard work.

Conclusion

Jelly Escape may have its flaws, but I haven’t played a web platformer this polished and addicting since MoneySeize, and those were great (albeit somewhat frustrating) times.

Yikes!

Jelly Escape doesn’t take many shortcuts. A ton of unlockables, a huge array of levels, and badges on Kongregate make the addicting qualities of the game shine brighter than ever.

I definitely plan on revisiting the game to finish up those last 30 levels or so, as I’m a sucker for platformers; how far did you play before losing interest?

In this Premium series, you’ll learn how to use Flash to build a Facebook Graph API application that can create slideshows for your public pages. This third part covers generating a code to load the events from a Facebook Page.

Premium Preview

Click to try the app on Facebook.

This application allows you to select a Facebook album or event list from one of your public pages and turn it into a slideshow for your page tab. When the users enter your page, they will see photos from your chosen album, with your photo title and description, or event name, date and invites (for the event tab).

In the second part, we created the embed code for the album (basically finding out the album ID from which we load the photos). This time, we are going to use the Graph API to get a list of a page’s events, based on its Page ID.

Read the Full Tutorial

Tuts+ Premium Membership

We run a Premium membership system which periodically gives members access to extra tutorials, like this one, from across the whole Tuts+ network. If you’re a Premium member, you can log in and read the tutorial. If you’re not a member, you can of course join today!

In the first tutorial of this series, we took a look at drawing curves using equations and AS3. Now, we’re going to tackle solving those equations to find the roots of a curve – that is, the places where the curve crosses a given straight line. We can use this to predict collisions with curved surfaces, and to avoid “tunnelling” in Flash games.

Step 1: Quadratic Roots

First, time for some quick math revision. In this tutorial, we’ll just accept and apply the methods we’ll use, but interested readers can refer to Wikipedia’s page on quadratic equations for information about the mathematical deriviations.

So \(f(x)\) is a quadratic function. If \(f(x)\) is equivalent to 0, \(x\) can be obtained by this formula:

\(b^2 – 4ac\) is called the discriminant of the formula. If the discriminant is negative, the square root of the discriminant will produce imaginary roots, which we can’t plot. Conversely, if the discriminat is positive, you will have real number roots and you’ll be able to plot them onto the screen.

Step 2: Visualising Quadratic Roots

So what are roots? Well in our context they are nothing more than intersection points between the quadratic curve and a line. For example, suppose we are interested to find the intersection point(s) of the following set of equations:

\(
f(x)\ = \ ax^2+bx+c \\
g(x)\ = \ 0
\)

This is a typical scenario of looking for the intersection point(s) between a quadratic curve and the x-axis (because the x-axis is the line where y==0). Since by definition the intersection point(s) are shared by \(f(x)\) and \(g(x)\), we can conclude that \(f(x) = g(x)\) for the values of x that we are looking for.

It’s then a trivial operation where you just substitute the functions and then apply the formula from Step 1 to obtain the roots. Now there are several possibilities we can anticipate as shown below.

(As you can see, “imaginary roots” means, for our purposes, that the curve doesn’t ever cross the x-axis.)

Now let’s consider the case where \(g(x)\) is more than just a mundane horizontal line. Let’s say it’s a slanted line, \(g(x)\ =\ mx\ +\ d\). Now when we equate both functions, we’ll need to do a little precalculation before the formula can be effectively applied.

I’ve included an interactive Flash presentation below so feel free to drag the red and blue dots. Yellow dots indicate the intersection points. You may need to position the curve and line to intersect each other in order for the yellow dots to appear.

Step 3: Plotting This With ActionScript

The full script can be found in Demo1.as; here I’ll just explain a crucial extract of the code. Let’s look at the AS3 for drawing the curve and line:

The bulk of ActionScript for drawing the curve from line 80~104 is largely borrowed from the previous tutorial, so I shall just explain a little about the code for drawing a line.

In the Flash presentation above, there are two interactive blue dots. Each of these has coordinates, and with both dots, a line is formed. Since both dots lie on the same line, they share a common slope and y-intercept to form one general line equation:

\[
y\ =\ mx\ +\ d,\\
m\ =\ slope,\ d\ =\ y-intercept
\]

We can use a little algebra to solve for the two unknowns, \(m\) and \(d\). Given the coordinates of the two blue dots as \((x_1,\ y_1)\) and \((x_2,\ y_2)\):

(Note that a matrix with superscripted -1 refers to inverse of that matrix.)

So using this, \(m\) and \(d\) are calculated. We can can now draw the line by joining the coordinates \((0, y_3)\) and \((stage.stageWidth, y_4)\). How do you find \(y_3\) and \(y_4\)? Well now that \(m\), \(x\) and \(d\) are known, we can simply put all these values into the line general equation,

\(y\ =\ mx\ +\ d\)

..to get those \(y\)s.

Step 4: Calculate the Quadratic Roots

To calculate the position of the intersecting points, we shall use the formula from Step 1. This is done in EqQuadratic.as as the functions shown below:

Returns a Number vector for roots of real number. Elements are NaN if no real roots exist.

roots_i

Property, read only

Nil

Returns a String vector for roots of imaginary number. Elements are null if no imaginary roots exist.

Step 5: Plotting This With ActionScript

An example of utilising this EqQuadratic.as is in Demo1.as. After the initiation of EqQuadratic, we shall use it to calculate the roots. Then, after validating the presence of real roots, we’ll use them to plot the yellow dots.

Now the roots refer to only the \(x\) component of the coordinates. To obtain the \(y\)s, guess what? Again, we put the values of \(m\), \(d\) (calculated earlier in Step 3) and \(x\) (from the roots) into the line general equation, \(y\ =\ mx\ +\ d\). Check out the corresponding code in line 135 and 136.

Step 6: Cubic Roots

Cubic roots, not surprisingly, are the intersection points between a cubic curve and a line. But a cubic curve is a little different to a quadratic curve, and in this respect the possibilities for where intersections could be located are different.

The image below shows a cubic curve intersecting with the x-axis:

Again, here’s a little Flash presentation for you to experiment with. Red and blue dots can be dragged while the yellow ones just indicate the intersection points.

Step 7: General Formula for Cubic Roots

The general formula to find a cubic curve was discovered by Cardano. Although I’m enticed to elaborate on the details, I’ll just point interested readers to the following links:

Anyway, the EqCubic.as class implements this formula to resolve roots of cubic functions along with other mathematical utility functions. Generally all the attributes and methods for EqCubic.as follow the desciption as tabled in Step 4, because both classes EqQuadratic.as and EqCubic.as implement one common interface, IEquation.as, except for the details listed below.

Function

Difference

define

A total of four coefficients (a, b, c, d) to input for cubic equation; just three for quadratic equation.

roots_R, root_i

The total of real and imaginary roots is three for a cubic equation, but two for a quadratic equation.

Step 8: Plotting This With ActionScript

Here’s the Actionscript implementation for the Flash presentation from Step 5. The full code is in Demo3.as.

Again, the ActionScript commands to draw a cubic curve are exactly the same as explained in my previous article, whereas Actionscript commands to draw the line are already explained in Step 3 of this one.

After instantiating cubic_equation in the constructor we proceed on to define its coefficients, calculate the roots, and store the roots in a variable.

One little note on the roots: there are a maximum of three real roots for a cubic equation, but not all real roots are present in all situation as some roots may be imaginary. So what happens when there’s only one real root, for example? Well, one of the array of roots called from cubic_equation.roots_R will be a real number, while all the others will be Not a Number (NaN). Check out the highlighted ActionScript for this.

Step 9: Predicting Where an Object Will Collide With Curved Surface

A great application of calculating roots is projecting a collision point onto curved surface, as show below. Use the left and right arrow keys to steer the moving ship, and press up to accelerate. You will notice that collision points which would have happened in the past are slightly dimmed.

Step 10: Implementation

The idea is similar to that in my tutorial about predicting collision points. However, instead of colliding with a straight line, we’re now using a curved line. Let’s check out the code.

The core code lies in redraw and recalculate. Let’s first see what’s in redraw. It’s the same one we had been using in previous demos. One little note on drawing the line. We saw in previous demos that two dots are needed to draw get the equation. Well, here we only have one ship. So to get the second point, just add the ship’s velocity to its current position. I’ve highlighted the code for convenience.

Step 11: Time-Based Collision Detection

Another great application is not quite as obvious as the first. To perform a more accurate collision detection, instead of basing our conclusion on the distance between two objects, we’ll uae their time to impact. Why? Because “tunneling” can happen if we use distance based collision detection:

Consider a collision detection algorithm that’s based on distance for two circles. Of the four frames shown, only frame 2.15 successfully detected collision between two circles. Why? Because the current distance between the gray and the red circles’ centers is less than the sum of both circles’ radii.

(Readers interested on more details on this topic can refer to this article.)

\[distance\ between\ circles\ < \ radius_{red}\ +\ radius_{gray}\]

The problem is caused by how Flash proceeds by one discrete frame at a time, which means that only frames 1, 2, and 3 will be successfully captured, and not the moments in between thos snapshots of time. Now the gray and red circles did not collide in these frames according to a distance-based calculation, so the red circle tunnels right through the gray one!

To fix this, we need a way to see the collision that occurred between frames 2 and 3. We need to calculate the time to impact between two circles. For example, once we check that time to impact is less than 1 frame at frame 2, this means that once Flash proceeds 1 frame forward collision or even tunneling will have definitely had taken place.

\[if\ time\ to\ impact,\ t,\ fulfills\ 0\ < \ t\

The question is, how do we calculate this time?

Step 12: Precalculations

I’ll try to show my method as simply as possible.

Given the scenario above, the two gray and red circles are currently located at \((x_{gray},\ y_{gray})\) and \((x_{red},\ y_{red})\). They are moving at \(v_{gray}\) and \(v_{red}\) respectively, and set on a collision path. We are interested to calculate the time taken, \(t\), for them to reach positions \((x’_{gray},\ y’_{gray})\) and \((x’_{red},\ y’_{red})\), indicated by the translucent gray and red circles, where the collision occurred.

Note that I’ve derived the horizontal and vertical components of \(v_{gray}\) into \(v_{gray_x}\) and \(v_{gray_y}\). Same goes with velocity of the red circle; check out this Quick Tip to get to know how these components are derived.

We still lack one relationship to bind all these equations together. Let’s see the image below.

The other relationship goes back to Pythagoras. When both circles meet, the distance between both centers is exactly \(rad_{gray}\) plus \(rad_{red}\).

This is where you substitute equations 1~4 into equation 5. I understand its quite daunting mathematically, so I’ve separated it out into Step 13. Feel free to skip it to arrive at the result at Step 14.

Now at a glance, we can easily see the highest power of \(t\) is 2. So we have ourselves a quadratic equation. Let’s collect all the coefficients contributed by these three terms according to their powers.

Note that this only caters for one term in \(eq.\ 5\). We’ll need to perform the same process for another term \((y’_{gray}-y’_{red})^2\). Since they have the same algebraic form, the result should also be the same.
\[
(y'_{gray}-y'_{red})^2\\
=(v_{gray_y}-v_{red_y})^2*t^2+2(v_{gray_y}-v_{red_y})(y_{gray}-y_{red})*t +(y_{gray}-y_{red})^2
\]

Thus after rearrangement in terms of \(t\), \(eq.\ 5\) should be as follow.

Step 15: Sample Implementation

So here’s a Flash presentation to demonstrate the idea. You will see two particles on the stage, one gray and the other red. Both are connected to an arrow, indicating the magnitude and direction of velocity.

Click the "Next" button to progress one frame in time.

Click the "Back" button to revert one frame in time.

To alter the velocity of the particles, press:

“Up” and “down” to increase and decrease the velocity’s magnitude, respectively.

“Left” and “right” to rotate the velocity.

"N" to switch which circle you control.

Finally, to toggle visibility of the arrows, press "V"

Step 16: A Note on the Quadratic Roots

There are two roots to the quadratic equation. In this context, we are interested in the real roots. However if the two particles are not set on collision path (both paths are parallel to each other), then imaginary roots will be produced instead of real roots. In this case, both real roots will remain NaN.

If both particles are set on a collision path, we will get two real roots. But what do these two roots represent?

Recall in Step 12 that we made used of Pythagoras’s Theorem to tie \((x’_{gray},\ y’_{gray})\) and \((x’_{red},\ y’_{red})\) together into an equation. Well, there are two situations where the distance between two circles’ centers are exactly the sum of both radii: one before collision and one after collision. Take a look at this image:

So which one do we choose? Obviously the first because we’re not interested in the instance after collision. So we should always choose the lesser value of both roots and evaluate it. If the value is positive and less than 1, a collision will happen during the next frame. If the value is negative, the collision happened in the past.

Step 17: The ActionScript Explained

Let’s look at the Actionscript implemented for this example. First, the variables.

It’s been about 6 months since we launched our much improved New Tuts+ Premium complete with courses and eBooks. In that time we’ve added 97 hours of video training, 36 eBooks and of course our premium tutorial library has continued to grow and is rapidly apporaching 1000 tutorials, including lots of fantastic Activetuts+ content. Now, for a limited time only, thanks to PayPal we’re offering anyone who joins Tuts+ Premium with a yearly membership via the PayPal service, a $50 cash back to their PayPal account. It’s a good way to get an even better deal on Tuts+ Premium yearly subscriptions!

If you’re serious about skilling up, head over to Tuts+ Premium and invest in yourself and your development! We’re constantly adding more content and it’s only getting better and better, so buying a yearly subscription is worth it. Plus we have a money back guarantee in the first month, so if you discover it’s not for you, you can always bail out without charge (and of course without the $50 cash!) If you enjoy our free Tuts+, you’ll definitely find Tuts+ Premium a valuable edition.

Terms – read these!

Disclaimer:PayPal is not responsible for the promotion offered by Envato and you should read the Terms & Conditions below. The PayPal service is provided by PayPal Australia Pty Limited (ABN 93 111 195 389) which holds an Australian Financial Services Licence, number 304962. Before deciding to sign-up for or use the PayPal service you should consider the Combined Financial Services Guide and Product Disclosure Statement, available at http://www.paypal.com.au.

The promotion is run by Envato Pty Ltd and the promotion period runs from 12.00 noon on 12 June (Australian Eastern Standard Time – AEST) until 11.59am on 19 June (AEST).

If you purchase a yearly $180 USD Tuts+ Premium subscription using a PayPal account during the promotion period, you will receive a $50 USD credit to that PayPal account.

Sorry, but existing Tuts+ Premium yearly members are not eligible for the promotion. Existing Tuts+ Premium monthly members who upgrade to a yearly subscription are eligible.

Payment must be made through PayPal for the promotion to apply.

Your PayPal account must be in good standing at time of purchase (e.g. not limited, closed or otherwise restricted).

The credit will be applied to the PayPal account used to purchase the yearly subscription, and will be made 45 days after the promotion period ends.

The credit will not be given if you exercise the Tuts+ Premium 30 day money back guarantee.

You may only take advantage of this promotion for one time, meaning one $50 credit per person.

The credit will not be given if there is a reversal, chargeback or fraudulent transaction on the subscription payment.

Play fair! Any attempt to defraud Envato may result in immediate disablement of your Tuts+ Premium subscription accounts. And there will be no refund on the Tuts+ Premium subscription. We will have the final say on whether there has been an attempt to defraud Envato.

This promotion cannot be used in conjunction with any other promotional offer or coupon.

Upgrades

If you are an existing monthly Tuts+ Premium member, and interested in upgrading to a yearly membership to take advantage of this offer, be sure to cancel your existing monthly subscription via PayPal. Also, thank you for being a member!!

Kongregate is one of the largest Flash game portals on the net, and has its own API that can be integrated into your games (for which Kongregate even rewards you financially). In this tutorial, I’ll show you how to implement the Kongregate API into your games, and also go into detail about what the API is capable of and why you should use it.

(Note that this tutorial assumes you already have a Kongregate account; if you don’t, then please create one now.)

Final Result Preview

Let’s take a look at what the API enables us to do:

Badges

Mass Messages

High Scores

There’s another big reason to implement the API…

Step 1: Let’s Get Motivated

Before we dive into the technical aspects of implementing the Kongregate API, let’s get ourselves hyped up a little bit, and make sure that we actually want to implement it.

There are many reasons to implement the API, but to most developers, nothing speaks louder than money, and there’s plenty of that involved. When you upload your game to Kongregate, you automatically earn 25% of all ad revenue generated by your game’s page.

It gets better; if you implement their “Statistics & Challenges API”, you’ll receive an additional 10%! Finally, if your game is exclusive to Kongregate, or sponsored by them, you receive an additional 15%. This gives you the opportunity to earn up to 50% of the ad revenue for your game on Kongregate. If you’re wondering how much that is, check out some of my personal stats:

Step 2: Setting Up Our Work Environment

For this tutorial, we’ll be using FlashDevelop, a free (and amazing) open source editor for developers. We’ll be doing everything in simple .as files, so if you’d like to follow along using the Flash IDE, you shouldn’t have any trouble. If you’d like to use FlashDevelop and are unfamiliar with it, check out this excellent FlashDevelop beginner guide to get you started on what I would consider the best AS3 editor out there.

To begin, open FlashDevelop, go to the Project tab, and select “New Project”. From here, select “AS3 Project with Pre-Loader”. Alternatively, you can grab the Preloader.as and Main.as files from the source download, and simply follow along.

Nothing above should be new to you; if it is, all you need to know is that this file is the entry point for our program, this is where it all begins. If you compile this with FlashDevelop, you should get a blank white screen, with no compiler errors.

Step 3: Let’s Get Connected

Before we dive into all the cool features of the API, we need to make sure that we have the API up and running.

Unlike many sponsor APIs, the Kongregate API isn’t a standalone set of files that we need to compile with our project. The API is actually stored on the Kongregate server, and we load it in at runtime. There’s a number of ways to do this in your projects, but for the sake of this tutorial, we’ll simply connect within our Main.as, and a save a reference to it there.

To start, copy the following code into our Main.as file just below the existing imports:

The above are just a few simple imports that will allow us to use the necessary classes for loading in the Kongregate API.

Next, we’ll add a variable to store our reference to the Kongregate API. Go ahead and add the following right above the constructor of our Main.as file.

private var kongregate:*;

Notice that the data type of our kongregate variable is *. If you’re unfamiliar with this, we’re simply telling the compiler that the kongregate variable will accept any data type, much like a wild card.

(Also, note that in a real game you’d want to store your reference to the API somewhere that your entire project has access to, such as a public static const. This reference is needed so that you can use the API from anywhere in your project, for any purpose, rather than just in the Main.as file when we first start up.)

This next piece of code will be contained in a custom function by the name of initKongregateAPI(). This isn’t actually necessary, but I prefer to encapsulate ideas when writing code, as it helps keep the code readable and easy to work with.

While that may look like a lot of code, it’s really not much, and with the comments, it’s quite easy to follow.

As you’ll see, in the first part we’re creating a variable to store the API path from the FlashVars (if you don’t know what these are, look them up really quick, they’re a great thing to understand).

In the second chunk, we determine whether the SWF is on the Kongregate website or running locally, and we assign the proper information to the apiPath variable.

Next, we give the API access to the SWF, with a simple security.allowDomain call, where we pass in the apiPath as the parameter.

We then create a new URLRequest object, which gets the apiPath passed in to the constructor, a new Loader object, and add an event listener for the loader which will call loadComplete when done.

Last, we call loader.load and pass in our request (the newly created URLRequest object, which contains the apiPath of the Kongregate API). If you understand what just happened, great; if not, don’t sweat it, as you won’t have to touch this again.

Don’t Forget to Call It!

Now that the initKongregateAPI function is created, and contains all of the connection code, we should probably make sure this function actually gets called! Simply go back to the init function that our Main.as file already contained, and add a function call to initKongregateAPI after the line that “entry point” line, like so,

The above code is super simple; let’s go over it. We start off by saving a reference to the Kongregate API. As you can see, we’re referencing the Kongregate API through the passed in event parameter, via event.target.content – simple enough.

Now all we have to do is connect, and our SWF is good to go. As you can see, we connect by calling the kongregate.services.connect method. No arguments required.

While that may have seemed like a lot of work, it really wasn’t. I simply went over the connection process in a lot of detail, so that you can understand how we’re actually gaining access to the API, rather than just having that access and using it. Now that you understand it, you can use all the above as boilerplate code.

Step 4: The Statistics & Challenges API

Now that we’re connected, we can take a look at the most important feature of the entire API: the Statistics & Challenges portion. This API sends player related stats to the Kongregate server, which enables a number of things.

First off, this is the most basic way to allow users to compete for high scores on Kongregate. With the API integrated, the Kongregate side bar will include a new tab labeled “ACHIEVEMENTS”, which can be found next to the “CHAT” tab. Players can view leaderboards for any stat you send to the servers, which could be anything from a basic high score to the total number of enemies defeated.

The second and far more important use, is to allow Kongregate to use the stats you submit to create “badges” for your games. Badges are a central part of the Kongregate user experience, and are much like the achievement systems on platforms such as Xbox LIVE.

The best part about having badges added to your game is that your game will become featured for a short duration, greatly increasing the number of views you get, and thus greatly increasing your ad revenue. Even after your game is out of the spotlight, all badged games on Kongregate continue to receive increased views over normal games, which gives you an excellent long tail revenue stream.

Note that badges aren’t added by developers, but are instead created by the Kongregate staff. You’ll need a high rated game to get selected, but you’ll also need the API to be set up – so let’s get that half the battle out of the way!

Step 5: Back-End Preparation

To actually use the stats that we’ll be sending, Kongregate first requires us to let their server know what information it should be prepared to receive from us.

To do this, we simply go to the Statistics page for our game on the Kongregate website. This can be found in the “Edit Game” page, or by adding /statistics to the end of your game’s URL (for example, http://www.kongregate.com/games/EpicShadow/pixel-purge/statistics). For this tutorial, we’ll simply upload our test SWF as the “game”.

Before adding any stats to the Statistics & Challenges API, we need to first understand the four types of stats that can be used, and the rules that they are bound to. Values must be positive, and must be whole integers. The four types are as follows:

Max: The value on the server will be replaced if the new value is higher than the stored value. For example, a high score of 152,000 would replace an old high score of 120,000.

Min: The value on the server will be replaced if the new value is lower than the stored value. For example, in a racing game, a lap time of 31 seconds would replace an older value of 35.

Add: The new value will be added to the stored value. A common use of this would be total enemies defeated, player deaths, etc. Too many requests to the server may result in inaccurate data, so it’s advised that data is only sent in bulk, such as when a level is completed or when the player dies.

Replace: The new value will replace the stored value no matter what. This can be used for a number of things, such as average survival time or player ranking.

Knowing which of the above types you need to use for each of your game stats is extremely important, so make sure you familiarize yourself with the above list. You’ll obviously want a list of stats that you want your game to send to Kongregate, so make sure that you have those prepared before you dive into the next step when actually submitting a game.

For the sake of this tutorial, we’ll simply use the following stats:

Total Clicks (Add)

Max Clicks (Max)

Last X (Replace)

Once your list is prepared, head to the Statistics page of your game, and input the required data. Once the back-end work is done on the Statistics page, the game will be ready to submit data to the Kongregate server.

Step 6: How to Send Stats

To actually send data to the server, we simply call the “submit” function, which looks like this:

submit(statName:String, value:Number):void

As you can see, the function takes two parameters:

statName is the name of your stat. It’s very important that the String passed is identical (case sensitive) to the name of the stat you listed in the previous step when prepping the server to handle your stats.

value is the actual numeric value to be passed. Even though the data type is Number, remember that your value must be a positive, whole integer.

Even though we had four different types of stats we could send, this function only sends the value; the server itself will look at the information we provided in the previous step to determine how to treat the incoming data. It’s as simple as that; now we know how to send data to the server.

Step 7: Prepping Our Project to Send Stats

Now that we’ve prepped the back-end on the Kongregate website, and we now know how to send data, let’s give this project a go.

The first thing we need to do is add some code to our project to actually send our stats. Since the easiest thing to track is mouse input, I’ve chosen mouse-related stats. As you saw in our previous step, I chose Max Clicks, Total Clicks, and Last X.

Max Clicks will be the high score for how many times we click in a single game, to demonstrate the Max type; Total Clicks will be the grand total of all clicks we’ve done, to demonstrate the Add type; and Last X will be the x-position of our most recent click, to demonstrate the Replace type.

To track our Mouse clicks, we’ll need import the MouseEvent class. Go back to Main.as, and add the following to your imports:

import flash.events.MouseEvent;

Now we’re going to need to add a variable for our Max Clicks stat, to keep track of the total number of clicks per game session. Right below where we added the kongregate reference variable (of data type *), add the following:

private var maxClicks:int;

We’re going to need an Event Listener to listen for our clicks, so we’ll add that now. In the init function, right below the call to initKongregateAPI, add the following:

All we’re doing here is incrementing the maxClicks variable by 1, and then submitting all the required information to the Kongregate server. This will add 1 to the Total Clicks stat, send the current maxClicks variable to the server, which will then determine if it’s higher than the previous value and replace it if so, and send the x-position of our previous click, which will automatically replace the previous value.

Our SWF may just be a blank screen, but a lot is going on, and we’re about to see it in action. Make sure you compile the project before moving on.

Step 8: Testing Our Project

Now it’s time to actually upload our project, and see it in action.

Go back to the Kongregate website, head to your game page, and upload the final version of our project. Once you’ve uploaded the project, you’ll be brought to a preview screen, where we can test our project before publishing it. To save the Kongregate staff a lot of time and energy, do everyone a favor and do not press publish on your test SWF. (If you’re working on a real game, go ahead, but for the sake of this tutorial we will not be publishing this project.)

Once you’re on the test page, give the game a few clicks. Refresh the page, and you should now see that there is a “HIGH SCORES” tab next to the “CHAT” and “GAME” tab. If you’ve done everything correctly up to this point, you should have a drop down box that currently reads “Last X” that also contains “Max Clicks” and “Total Clicks”. Note that clicking quickly will result in innacurate stats, as the server can’t keep up with all the requests, so click slowly for best results. This is why I advised earlier that you send large batches of data upon death, or level completion, when possible.

Well, there you go: you’ve now got the most important portion of the Kongregate API up and running. If your project isn’t working at this point, make sure that your Kongregate back-end stat names are typed exactly as they are in your submit function – case-sensitive – as that’s usually the problem.

You can also find the completed code in the final files folder in the source download, so compare your code to that if you’re still having issues.

Step 9: Mass Message Communications

Ever released a game, then later, really wanted to reach out to all of your fans? Well, with the Kongregate API, you can do just that – at least, for all of your Kongregate fans.

There are some restrictions on who can do this, but these restrictions are very much in the best interest of both developers and players. In order to qualify, your game must receive a 3.75 rating or higher, and have at least 10k gameplays.

You can send an “active players” message at most once every seven days. These messages will be sent to any players who have played the game at least three times ever, and at least once within the last ten days.

You can send an “inactive players” message at most once every 30 days. These messages will be received by any players who have played at least five times total, but not within the last ten days.

There are many of reasons to send these messages to your players, such as alerting them of bug fixes, or perhaps informing them of an upcoming sequel. Regardless of what you use this for, it’s an incredibly useful system that can really help you leverage your fans.

So Much More…

While we’ve covered a lot in this tutorial, the Kongregate API is capable of doing much more. Unfortuantely, I’d have to write a small book to go over all of the features, especially those that are useful for web based MMOs. If you’re interested in checking out what other features the API has to offer, I recommend checking out the Kongregate Developers Center for more.

Now that you know how to get the Kongregate API up and running, I strongly encourage you to add it to all of your future games; if you’re lucky, you might even get some badges, and that’s when the real fun begins.

Last year, we released Tr.ace(), an open source debugging tool for Flash that expanded on the built-in trace() function. Now, Tr.ace() v2.0 introduces several new features including the much requested “textfield console” to help you squash those bugs once and for all!

New to Tr.ace()?

Tr.ace() was released nearly a year ago as an Exclusive Freebie on Activetuts+ and is an open source debugging utility for Flash that allowed you to restrict the traces shown within your application to particular users or classes or even both. You could also add linebreaks, timestamps and trace nested arrays and objects neatly with one line of code!

Let’s take a look at what’s changed since Tr.ace() was first released…

By Popular Demand: Tr.ace() Console

The Tr.ace() library now features a class named TrConsole which provides you with a basic console within your SWF through which you can view all your Tr.ace() traces! Check out the demo below to see it in action:

You can clear the console, copy the output to the clipboard and save the output to a text file. You can also minimize the console to reduce the space taken up on screen as well as move it around the screen by simply dragging it. It’s also fully resizable!

To take advantage of this feature you only need two lines of code:

// create the TrConsole instance and add it to the stage
var console:TRConsole = new TrConsole();
addChild(console);

And that’s it – easy!

There are also a few extra options for you to tailor the colours of the console and whether autoscroll is enabled or not. Check out the documentation and example files for more info.

Optional Username and Class Parameters

When Tr.ace() was intially released the username and class parameters were required for all trace calls whether you wanted to use them or not. You’ll be happy to know that they are now optional!

This does reduce some of the functionality of the library but if you’re just wanting to see your traces via the console then you’re able to, without the bloat of the rest of the library.

With parameters:

Tr.ace("with parameters", TrUsers.MSFX, ClassName);

Without parameters:

Tr.ace("without parameters!");

This will hopefully make the library more accessible and less “verbose” for tracers everywhere.

Clear, Copy and Save Your Traces

Via the console featured above you can clear, copy to clipboard, and save the current trace log.

For those who aren’t using the console you can also achieve these via calls to the Tr class as shown below:

// to clear the trace log
Tr.clearLog();
// to copy to the clipboard
Tr.copyLogToClipboard();
// to save the log as a text file with timestamp
Tr.saveLog();

The clipboard functionality must be triggered via a user interaction, as detailed here.

Downloading Tr.ace()

Tr.ace() is an open source library that is available to download here at Activetuts+ in ZIP format and is also available as a public repository on my GitHub, for those a little more nerdy or who wish to fork and/or contribute towards the Tr.ace() library.

The library is AS3 only and has two separate repositories developed for both Flash Player 9 and Flash Player 10+

To use the Tr.ace() library you must download one of the above source packages and copy and paste the ‘uk’ directory, located within the ‘src’ directory, into your global classpath directory. You’re then all set to go!

Hey there and welcome to "Flash Video Training Source", a resource for anybody interested in learning more about Adobe's great tool. We feature educational videos, which will help you master Adobe Flash and help you get to know all of its features. We at "Flash Video Training Source" believe that video training and video... more

Why don't you follow us on Twitter and get the latest video tutorials twitted to your account. Just click on the floating twitter bar to your right!