Thank you for sending me a Playbook. i like it very much. i didn’t very much like the steps involved to put my work on the device, though. It was the most needlessly complicated thing i’ve had to do in all my life. i’d like to see the Playbook succeed, but you need to put more effort into helping your developers succeed first.

Here are a few of the issues i ran into while porting my game Heads to your platform:

1. i had to download Many Things, and sign up for Many Accounts. Each Thing and each Account came with 15 pages of legalese with an “I Agree” button at the bottom. I Agree … that this stinks.
2. One of the Many Things i had to download was Adobe AIR 2.5. i followed the link on your site to Adobe AIR 2.6, which i downloaded instead. When i tried to follow your workflow, i was told that only AIR 2.5 would work, so i had to cast about the Internatz to find the 2.5 download, which wasn’t made immediately and obviously available on the Adobe site. If i’m creating something for your platform, everything i do should ideally be immediate and obvious.

   

3. i downloaded VMWare and your VMWare Playbook profile so that i could run a virtual Playbook. But the emulator stalled at the startup screen for a very long time. i checked message boards, and found two possible solutions:
   1. Leave it overnight.
   2. Alternatingly restart your computer or VMWare multiple times (some reports said “six or seven”) until it works.

   i opted to restart VMWare and my computer multiple times until it worked. This was very frustrating. i’m not the only one who experienced this problem, as evidenced by this web comic by my Twitter pal @IQAndreas:

   

   

   

   

   

   

   

   

   

   

   

   

   

4. In order to deploy my game to the virtual Playbook, i had to know its IP. To get that, i had to swipe the “development” option into the “on” position and punch in my password. i had to use the software keyboard to punch in my password, because my computer keyboard didn’t work. And worse than that, it took about 4-5 tries swiping the slider and punching in my password before the Developer hammer icon would appear on the home screen … for whatever reason, that slider kept undoing itself.

   

   Somebody call Jerry O’Connell, cuz this slider be busted.

5. When it came time to bundle my files together in a .bar file, i was dismayed to find that since i don’t use Flash Builder (but, rather, FlashDevelop), i would need to use the command line to continue. i hate the command line. HAATE it. i know that eggheads love it, and that you employ Many Eggheads at RIM, but you have to understand that even though the command line is useful and powerful and 1337 and everything, i absolutely can’t be arsed with it. Like, not at all. So knock it off.

   Here is what i had to type into the command line in order to bundle my project into a .bar file:

   C:\dev\BlackBerryTabletSDK\blackberry-tablet-sdk-0.9.3\bin\blackberry-airpackager -package MyGame.bar -installApp -launchApp MyGame-app.xml blackberry-tablet.xml MyGame.swf blackberry-tablet-icon.png -device 192.168.58.128 -password 123456

   This is not a fun thing to have to type. Know what i want to do? Click a button. Can you make it so that i just click a button? Buttons good, typing bad. It may not be 1337, but it also doesn’t eat up my entire afternoon.

6. i am currently rocking three Blackberry accounts: one to develop my game, one to sell my game, and one to talk about my game on your forums. This is Too Many Accounts. Know how many there should be? One. Know why? Because it’s easier. Know what’s not easy? You.
7. When i signed my application, i had to download a file that you sent to me two days after i emailed you and asked you for it. That’s Too Many Days. That’s because you also took two or three days to approve my vendor account. Why not do this in one step instead of two? Clearly, a vendor is always going to need the application signing file. See how you don’t make things easy, when you potentially could?
8. Then i had to use the command line (which, as we’ve already established, is bad) to create a file that i could send to you so that my computer could sign files. At least i think that’s what i was doing. Here’s what the command looked like:
   

   blackberry-signer -csksetup -cskpass DesiredCSKPassword

   Then i had to use the command line (bad. BAD!) to send you my .csj file to receive permission to sign my other file. i think. i’m not quite sure what was going on, because it was tough to interpret the command, which looked like this:

   blackberry-signer -register -csjpin PinEnteredWhileRequestingCSJ -cskpass PasswordEnteredWhileGeneratingCSK client-RDK-XXXXXXXXXX.csj

   Next, i had to create a .p12 certificate using this command:

   blackberry-keytool -genkeypair -keystore DesiredCertificateName.p12 -storepass NewPassword -dname “cn=MyCompanyName” -alias author

   Then i had to get you to sign the file using this command:

   blackberry-signer -verbose -cskpass CSKPassword -keystore CertificateName.p12 -storepass StorePassword BarFileNameForRIMToSign.bar RDK

   Then i had to sign the file myself using this command:

   blackberry-signer -keystore CertificateName.p12 -storepass StorePassword RimSignedBarFile.bar author

9. When i finally went to upload my file, in the web form you asked me for an additional icon in some bizarre size (243×717 or something like that). i went away and produced that icon, and by the time i returned, the web form had timed out. Know what would be easier? A checklist!
   

   YOU WILL NEED:

   • A swf
   • An xml file called whatever.xml – download it HERE!
   • A thumbnail icon – download a template HERE!
   • A second icon – download a template HERE!
   • A brief description of your application – max X words
   • A long-form description of your application – max Y words

   And HERE’S an image of how all this stuff looks when it’s in the Blackberry App World! We’ve LABELLED everything for you, so you know where the descriptions and icons appear and how they’ll look to the user.

   Really, though – how long does that kind of thing take to set up? An afternoon? Why does this not exist yet?

10. To add insult to injury, my game was initially rejected because it did not contain the icon.png. i figured i must have forgotten to include the .png filename when i created the .bar file, so i went through all of those horrible steps again. For a second time, my game was rejected. Same reason.

    Know what the problem was? i hadn’t added this to the xml file:

    <icon>
        <image>whatever.png</image>
    </icon>

    N’awesome.

i didn’t enjoy doing this, and i don’t want to have to do it ever again. Know what i want? i want a big blank area where i can drag and drop my file, with a huge shiny juicy button that says “GO BITCH GO” which, when i click it, does all the bullshit i just described above. Please get your eggheads on that.

In addition to all of the brilliant software and hardware engineers you employ, you simply need to hire more people to evaluate this process. An egghead will tell you that using the command line is cool and awesome and that everyone loves doing it. A person will tell you the actual truth: using the command line blows, and you need to put that shit on a button.

Please let me know if and when you plan to put that shit on a button, and i’ll gladly continue developing for your device, because it’s pretty cool.

Sincerely,

Ryan Henson Creighton

President, Untold Entertainment Inc.

Bang on De Drum All Day

Here’s a secret about programmers: they are inherently lazy. The less typing a programmer can do, the better. Programming is all about dreaming up complex tasks that programmers don’t want to do, and delegating those tasks to a computer so that the programmer can blow off and watch cartoons the rest of the day.

Many programming structures are designed to make a programmer’s life easier. And a programming rule of thumb is generally that if you have to type something twice, there’s an opportunity to make your code more efficient.

Functions make your code more efficient. Let’s imagine a game where we need to create a bunch of monsters. If you’ve read Understanding Loops, you know that you can set up a loop to run an action multiple times. i’ll use a combination of pseudocode (in comments) and real code to demonstrate:

// Make 50 monsters.
var totalMonsters:int = 50;
var i:int = 0;
for(i=0; i<totalMonsters; i++)
{
    // make a monster
}

So far so good. But there are a few other things we have to do with these monsters we create. We need to put each one on a hill. Then we need to dress each monster up in a Power Hat. Next, we need to hide a key to each monster’s hilly domain. Let’s modify the loop:

// Make 50 monsters.
var totalMonsters:int = 50;
var i:int = 0;
for(i=0; i<totalMonsters; i++)
{
    // make a monster
    // put the monster on a hill
    // put a power hat on the monster
    // hide a key
}

Mmmm … we’re almost there. Now we need to create a portrait for that each monster and put it inside the castle, so that when the hero defeats a monster, the portrait gets a big checkmark on it. Then we need to create a magic gem that will kill each monster. Each gem needs to be buried somewhere underground. Finally, we need to create a villager for each monster in the game. Each villager will give you a clue as to where to find the monster-killing gem.

// Make 50 monsters.
var totalMonsters:int = 50;
var i:int = 0;
for(i=0; i<totalMonsters; i++)
{
    // make a monster
    // put the monster on a hill
    // put a power hat on the monster
    // hide a key
    // create a portrait
    // put the monster's face on the portrait
    // put the portrait inside the castle
    // create a gem
    // bury the gem underground
    // create a villager
    // give the villager a gem clue
}

Oh man. This loop is getting real ugly, real fast. There’s so much STUFF in there. It’s getting out of control.

If we take a close look, we see that we’re running a few tasks that can be grouped together. All the monster stuff goes together. All the key stuff goes together. The gem stuff goes together. The villager stuff goes together. That’s four separate bundles of tasks that, like a pile of sticks, we should be able to wrap up with twine in a tidy little package.

I Have a Tiny Little Package

That’s one of the things Functions do for us: they allow us to group related tasks together into a little package, and we can refer to that package over and over again without having to repeat any lines.

A Function declaration looks very much like a variable or array declaration. Instead of the var keyword, we use the function keyword. In ECMA-based languages like Actionscript 3, Unity javascript and C#, functions are followed by round brackets. Then you open up a statement block between curly brackets, just like in a For Loop or a conditional (If) statement:

function doSomething()
{
   // statements go here
}

Note: If you’re using Unity javascript, best practice is to begin a function name with a capital letter.

So doSomething is our function name. That’s a custom name that we came up with. It makes a lot of sense to use verbs (action words) when naming your functions. We’ll see why in a moment.

Let’s carve out the statements involving the monsters and put them in their own function:

function initMonsters()
{
    // make a monster
    // put the monster on a hill
    // put a power hat on the monster
}

(the “init” here is short for “initialize”, which means “set it up”)

Now, back in the loop, we can substitute those three statements with a Function call. A Function call always uses the name of the function, followed by round brackets, with a semi-colon to end the statement. Take a look:

// Make 50 monsters.
var totalMonsters:int = 50;
var i:int = 0;
for(i=0; i<totalMonsters; i++)
{
    initMonsters(); // We removed these three statements and put them in their own function.
    // Now, we just call the function.
 
    // hide a key
    // create a portrait
    // put the monster's face on the portrait
    // put the portrait inside the castle
    // create a gem
    // bury the gem underground
    // create a villager
    // give the villager a gem clue
}

In common programming parlance, this is called calling a Function.

To understand how a function call works, we need to put ourselves back in the role of our code interpreter, which is a lot like Pac Man.

Pac Man hits the first statement in the loop. It’s a function call. So he jumps out of the loop to wherever the Function is declared, and chews through all of the statements in that Function. When he reaches the bottom of the Function, he bounces back to the loop again, and resumes chewing through code at the very next line.

This works very nicely. Now we can go through and offload all of our chunks of functionality into their own Functions. When we write it all up, i looks something like this:

// Make 50 monsters.
var totalMonsters:int = 50;
var i:int = 0;
for(i=0; i<totalMonsters; i++)
{
    initMonsters();
    initKeys();
    initPortraits();
    initGems();
    initVillagers();
}

Look how much easier to read that loop is now. It’s very clear that we loop 50 times, and each time we make some monsters, some keys, some portraits, some gems, and some villagers. The details for each process are buried in their respective functions. Now, when we look at the initKeys function, we only have to worry about tasks related to initializing those keys.

This bouncing around that the Pac Man-like code interpreter does is the reason why i say that Object Oriented Programming (OOP) is like taking multiple plane flights through time portals.

There are two more very important things to learn about functions: Arguments and Return Values. These are detailed in two additional articles. Once you read through those, you’ll know almost everything there is to know about Functions, and you’ll be ready to start putting that knowledge into practice by building your own stuff!

For more Flash AS3 Tutorials and a pile of other useful stuff, check out our Flash and Actionscript 911 feature.

RandomBoolean()

1
2
3
4
5
6
7
8
9
10

public class Helper
{
	/**
 	* Returns Boolean true or false, randomly.
 	*/		
	public static function RandomBoolean():Boolean
	{
		return  Boolean(Math.floor(Math.random() * 2));
	}		
}

Usage

1

var coinTossIsHeads:Boolean = Helper.RandomBoolean(); //coin toss will randomly be heads or tails

Comments

Sometimes you just need to randomize between true or false, like a coin toss. Since the code is only one line, it may seem extravagant to make a method out of it, but i find it easy to use this way.

For more AS3 Helper Classses and a pile of other useful stuff, check out our Flash and Actionscript 911 feature.

FindAngle()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

public class Helper
{
	/**
 	* These companion methods will convert radians to degrees
 	* and degrees to radians.
 	*/		
	public static function RadiansToDegrees(radians:Number):Number
	{
		return radians * 180 / Math.PI;
	}
 
	public static function DegreesToRadians(degrees:Number):Number
	{
		return degrees * Math.PI / 180;
	}		
}

Usage

1
2
3
4
5
6
7
8
9

// Find the angle between the mouse cursor and someClip in degrees.
// Refer to our Helper.FindAngle method for that method:
var mousePoint:Point = new Point(stage.mouseX, stage.mouseY);
var somePoint:Point = new Point(someClip.x, someClip.y);
 
var angleInRadians:Number = Helper.FindAngle(mousePoint, somePoint);
 
// What the Hell is a radian?  Let's convert that nonsense:
var angleInDegrees:Number = Helper.RadiansToDegrees(angleInRadians);

Comments

So here are some more trigonometry-related methods. If you use the Helper.FindAngle method, you’ll get the result in radians. i for one don’t really know what a radian is, but i do know it’s one of the beasties that scared me away from taking trig in high school.

Let’s say you have a top-down tank in your game. You used Helper.FindAngle to find the angle between the tank turret and the target. Then you want to rotate the tank turret towards the target. But turret.rotation needs an angle in degrees, not radians. Use the RadiansToDegrees method to make everything right with the world.

For more AS3 Helper Classses and a pile of other useful stuff, check out our Flash and Actionscript 911 feature.

FindAngle()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

public class Helper
{
	/**
 	* This method accepts two
 	* Point objects and returns
 	* the angle between them
 	* in radians.
 	*/		
	public static function FindAngle(point1:Point, point2:Point):Number
	{
		var dx:Number = point2.x - point1.x;
		var dy:Number = point2.y - point1.y;
		return -Math.atan2(dx,dy);
	}
}

Usage

1
2
3
4

// Find the angle between the mouse cursor and someClip:
var mousePoint:Point = new Point(stage.mouseX, stage.mouseY);
var somePoint:Point = new Point(someClip.x, someClip.y);
var angle:Number = Helper.FindAngle(mousePoint, somePoint);

Comments

This is a great method that will help you program many different games in Flash. Applications are wide-reaching. Picture a billiards game where you have to find the angle between two balls. Or a space shooter where you need to find the angle between a laser turret and some invading UFOs.

The return value is in radians, which you may not be familiar with if (like me) you stopped taking math courses in the eleventh grade. If you want to convert the result to degrees, refer to our Helper.RadiansToDegrees method.

IMPORTANT: The order in which you pass the points makes a difference. You’ll get a completely different angle by reversing the order of the parameters.

For more AS3 Helper Classses and a pile of other useful stuff, check out our Flash and Actionscript 911 feature.

Wrap()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

 
public class Helper
{
import flash.display.*;
/**
 * This method accepts a
 * DisplayObjectContainer instance
 * and lists the children in its
 * display list by depth, name and
 * type.
 */		
public static function ShowDisplayList
	(theDisplayObjectContainer:DisplayObjectContainer):void
{
	var len:uint = theDisplayObjectContainer.numChildren;
	for(var i:uint = 0; i<len; i++)
	{
		var theChildObject:DisplayObject =
			theDisplayObjectContainer.getChildAt(i); 
		trace("level " + i + ":" + theChildObject.name +
			" " + theChildObject);
	}
	/* output example:
		level0:spaceship [object MovieClip]
		level1:asteroid0 [object MovieClip]
		level2:asteroid1 [object MovieClip]
	*/
}
}

Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

var theParentClip:MovieClip = new MovieClip();
	// create a clip that will hold other clips
 
for(var i:uint = 0; i<20; i++)
{
	// create 20 MovieClips and add them to
	// theParentClip's display list
	var theChildClip:MovieClip = new MovieClip();
	theChildClip.name = "clip" + i;
	theParentClip.addChild(theChildClip);
}
 
Helper.ShowDisplayList(theParentClip);
	// display a report on what's in
	// theParentClip's display list

Comments

Whenever i teach an intro Flash/Actionscript lesson to someone, and i want to stress the importance of the trace(); command, i say that there’s usually a difference between what you think Flash is doing, and what Flash thinks Flash is doing. trace(); is a fast, easy tool to help you find a discrepency between your understanding of what’s going on, and what’s actually happening!

ShowDisplayList() helps you quickly and easily visualize what’s in your DisplayObjectContainer object and at which depth levels. It’s very handy, because looks can be deceiving – when you look at graphics on the screen, you can’t always tell when there are two or more instances of the same MovieClip sitting on top of each other, or if the clip that didn’t show up is actually sitting behind another clip, etc etc. This method sorts that all out for you, and has already saved my bacon on a few projects.

For more AS3 Helper Classses and a pile of other useful stuff, check out our Flash and Actionscript 911 feature.

Fence()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

public class Helper
{
	import flash.geom.Point;
	import flash.geom.Rectangle;
 
	/**
	 * This method confines a Point
	 * within a Rectangle.  Useful for
	 * games where the player and
	 * enemy characters have to stay
	 * within a boundary (ie the screen!).
	 */
	public static function Fence(point:Point,
				theRect:Rectangle):Point
	{
		// Make sure the point
		// is horizontally within limits
		if (point.x > theRect.right)
		{
			point.x = theRect.right;
		} else if (point.x < theRect.left) {
			point.x = theRect.left;
		}
 
		// Make sure the point
		// is vertically within limits
		if (point.y < theRect.top)
		{
			point.y = theRect.top;
		} else if (point.y > theRect.bottom) {
			point.y = theRect.bottom;
		}
		return point;
	}
}

Usage

/* Imagine an Asteroids-style game
where you need to confine your spaceship
within the boundaries of a movieClip
instance called "spaceClip"
*/
var spaceBoundaries:Rectangle = new Rectangle(spaceClip.x,
					  spaceClip.y,
					  spaceClip.width,
					  spaceClip.height);
	// Store the outer space boundaries
var pos:Point = new Point(spaceship.x, spaceship.y);
	// Store the ship's co-ordinates
var xSpeed:Number = 30;
var ySpeed:Number = 50;
	// Set thrusters to "go!"
pos.offset(xSpeed, ySpeed);
	// add the xSpeed/ySpeed to the ship's current position
pos = Helper.Fence(pos, spaceBoundaries);
	// make sure the ship doesn't escape outer space!
spaceship.x = pos.x;
spaceship.y = pos.y;
	// position the ship on the screen

Comments

Keeping game characters and objects from leaving the play field is one of those stock-standard things you do in many, many different games – from keeping the pigs inside the sty, to keeping the ball inside the tennis court, to keeping the whatever inside the viewable screen limits. We’re sure to get a lot of mileage from the Fence() method in our future projects.

For more AS3 Helper Classses and a pile of other useful stuff, check out our Flash and Actionscript 911 feature.

Wrap()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

public class Helper
{
	/**
	 * This method reigns in a value to keep it between
	 * the supplied minimum and maximum limits.
	 * Useful for wrapping number values 
	 * (particularly paginated interfaces).
	 * Returns the reigned-in result.
	 */
	public static function Wrap(theValue:*, 
				  minLimit:*, maxLimit:*):*
	{
		var result:* = theValue
		if (theValue < minLimit)
		{
			result = maxLimit;
		} else if (theValue > maxLimit) {
			result = minLimit;
		}
		return result;
	}
}

Usage

1
2
3
4
5
6
7

var minLimit:uint = 0;
var maxLimit:uint = 20;
 
var pageIndex:uint = 20;
 
pageIndex = Helper.Wrap(++pageIndex, minLimit, maxLimit);
// pageIndex = 0.  Hooray!  That's a Wrap!

Comments

i find myself doing this kind of thing all the time: checking to see if a number has gone out of bounds, and wrapping it back to the minimum or maximum limit i’ve set. i build many, many projects with paginated interfaces, where you click the Back or Next arrow buttons to flip the page. Clicking Next on the last page sends you to the first page, while clicking Back on the first page wraps you back around to the last page. The Wrap method helps reduce some code clutter and a bit of typing.

Of course, it’s not bulletproof. i cheated a bit by using the * wildcard for the datatypes. i did this so that the method will tolerate various numeric datatypes without complaining. Pass a string, a boolean and an array to this method all at once to see it break.

For more AS3 Helper Classses and a pile of other useful stuff, check out our Flash and Actionscript 911 feature.