This is the fourth part of our tutorial series by Intern Sina on creating an AIR application for free on a PC using FlashDevelop, and deploying it as a native app on an iOS device like the Apple iPad, iPhone or iPod Touch.

Jump to other parts in the series:

• Part 1 – Sign up for an Apple iOS Developer Account
• Part 2 – Obtain your Signing Certificate & Mobile Provisioning Profile, and create your App ID
• Part 3 -Use FlashDevelop to build your mobile AIR app

In this section of the tutorial, the rubber meets the road. You’ll make all the finicky adjustments to FlashDevelop and the AIR bundling files to get your Hello Planet app up and running on your testing device.

Point FlashDevelop to the Merged SDK Folder

Now that your (cr)app is successfully up and running, you have to make a few tweaks and adjustments to FlashDevelop. You’ll start by telling FlashDevelop all about that merged SDK folder you created in Part 3.

1. In the Project panel on the right, you’ll see a file called AIR_iOS_readme.txt. Double click that file to open it.

   This txt file lists a number of settings needed to get your ipa file working. The ipa file is the Holy Grail- the native app file that you’ll send to your testing device to see everything working properly. A window pops up with a bunch of options.

2. Click the Project Properties button at the top of the Properties Panel (alternately, you can use the menus to navigate to Project>Properties).

   

3. Change the version of your AIR SDK from 2.7 to 3.0 because (at the time of this writing), that is the latest version.

   

4. Click on the SDK tab, and click Manage.

   

5. On the next screen you will see list of installed Flex SDKs. Click the ellipsis (…) button at the end of that line. An InstalledSDK Collection Editor window pops up.

   

6. You’re going to point FlashDevelop to the location of our recently-downloaded Flex SDK (the same folder that contains both the Flex SDK and AIR SDK that you created earlier in this tutorial). First click the Add button, and then click on the Path line to get another ellipsis. Click on THAT ellipsis to browse your computer.

   

7. Once you have clicked the ellipsis button, a Windows File Browser appears. Navigate to the merged SDK directory. Select that folder and click OK.

   

8. Click OK again to exit the InstalledSDK Collection Editor window.
9. Click Close.
10. In the drop-down menu, you should see the Default option. Click on the drop-down list and choose the SDK location you just told FlashDevelop about.

    

11. Click Apply.
12. Click OK. Voila! Your SDK is now setup for your FlashDevelop Project.

    Let’s just test it out quickly to see if it works. The code you pasted in the previous tutorial prints out the words “Hello Planet” within your app. Well, I’m going to change mine to say “Sina is Cool”, just because I can, and also because I AM COOL. (You may be tempted to replace “Sina” with your own name. Please don’t, because uh … your code won’t work.)

    Your resulting app should look like this:

    

    A beautiful sight, isn’t it?

    (At this point, Sina actually is pretty damned cool. – Ed.)

Delete the Extra Icons Folder

Now you have FlashDevelop set up to create mobile-formatted AIR apps. Your app compiles, and you have your Mobile Provisioning Profile and your .p12 Signing Certificate waiting in the wings. All you need to do is combine all these amazing files together to create the Holy Grail .ipa file.

An .ipa file is like the program file – the Windows executable (.exe) – that you need to test your iPhone/iPad App on a device, and ultimately upload it to the Apple App Store.

The creators of FlashDevelop 4 made a minor error when they created the Mobile App template: the template generates a duplicate icons folder that will cause a conflict when you try to bundle your .ipa file. You need to get rid of this extra folder to make sure your .ipa file to builds properly.

1. Look in the right sidebar that lists your files and folders. You’ll see a folder called bin. (This is one of the folders that FlashDevelop created for you automatically when you created your project.)
2. Click on the little plus sign beside the bin folder to expand it. You will see a folder called icons tucked inside. Right-click the icons folder and click Delete. Problem solved.

   

Integrate Your Cert Files

This is the third part of our tutorial series by Intern Sina on creating an AIR application for free on a PC using FlashDevelop, and deploying it as a native app on an iOS device like the Apple iPad, iPhone or iPod Touch.

Jump to other parts in the series:

• Part 1 – Sign up for an Apple iOS Developer Account
• Part 2 – Obtain your Signing Certificate & Mobile Provisioning Profile, and create your App ID
• Part 4 – Modify your project settings and test your app on an Apple device

Luke Loses His Hand

Part 2 of this tutorial was like The Empire Strikes Back. It was the crisis moment in the story of deploying a Flash project to the Apple iOS platform. It was dark, it was difficult, and Han Solo wound up frozen in carbonite. Part 3 is redemptive: with all that command line and certificate red tape out of the way, you can finally build our AS3 app using FlashDevelop. Watch closely, friends: you may spot some ewoks.

Install Flash Develop

As I mentioned earlier in the series, FlashDevelop is a FREE, PC-only coding environment that is used throughout the industry and loved by many. If you haven’t installed it, head here to download the latest version.

FlashDevelop is an IDE (Integrated Development Environment) where you can create many different types of applications from scratch. The most amazing thing about FlashDevelop is that you don’t actually need to buy Adobe’s Flash Professional software to create Flash (swf) content. FlashDevelop has amazing, time-saving features like importing code libraries on the fly, and numerous awesome templates. At the time of this writing, the latest edition of FlashDevelop is 4.0.0. This version of FlashDevelop contains a template for Mobile AIR applications which you can use for iOS and Android development. In this tutorial, you’ll use the iOS version of the template.

Create a Merged SDK Folder

There are two SDKs (Software Development Kits) you’ll need to deploy Flash content to the iOS platform: Flex and AIR. Depending on the version of FlashDevelop you install, these two SDKs may already be included in the download. You’re going to download them both anew and put them in a single folder. That way, if you mess anything up, you can take off and nuke the site from orbit instead of messing up your main FD install. It’s the only way.

1. Download the latest AIR SDK (which, at the time of this writing, was v3.0)
2. Download the Flex SDK.
3. These two packages download as .zip files. Extract them wherever you like on your computer – just make sure you know where you put them.
4. Once you have both SDK’s extracted to separate folders, copy everything in the AIR SDK folder into the Flex SDK folder. Windows will ask you if you want to overwrite certain files. Say “yes” to everything.

   

   You now have a folder with the Flex SDK and the AIR SDK merged into one. This is a Good Thing™.

Point FlashDevelop to the Flex SDK

In order to compile (build and execute) your app, you have to point FlashDevelop to the merged SDK folder that you just created.

1. Open up FlashDevelop and hit F10 or go to Tools->Program Settings in the menus.

   

2. In the Program Settings menu, click on AS3 Context.
3. Find the Language section, and the Flex SDK Location line within it.

   

4. Click the ellipsis button at the end of that line, and navigate to the merged SDK folder.
5. Click Close to commit the change.

Set Up Your Mobile AIR Application

Once you have downloaded and installed FlashDevelop, open it up and you should see it in all its glory:

To begin with, you’ll need to create a new FlashDevelop project, which is a group of folders governed by a file filled with metadata about your project.

1. Create a new project by clicking Project -> New Project in the menu.
2. Now you will see a screen with a multitude of options. These are all project starter templates that FlashDevelop has for you to use. The one you want is the AIR Mobile AS3 App. Select this template, choose a location on your hard drive to save it, give a name to your project, and hit OK.

   Note: A package name is not required but the option is there if you’d like to use it.

   

   After you hit OK, FlashDevelop creates a number of folders and files for you, including:

   • The .as3proj file, which is a FlashDevelop project file filled with metadata that keeps track of various aspects of your project.
   • The bin folder. This is where your finished files end up.
   • The lib folder, where you can put your “construction” files and artwork.
   • The src folder, which contains your .as AS3 code files.
3. Once you’ve created your project file, FlashDevelop starts you off with a blank screen. To open up your code, click on the src folder in the Project sidebar on the right. (The Project sidebar lists your computer’s actual directory structure so that you can access your Actionscript files quickly and easily.)
4. Inside the src folder, double click the Main.as file to open it. This is your project’s point of entry, where you can start writing the code for your app.

   

5. Push the F5 key on your keyboard, or the click the little play button at the top-middle of FlashDevelop to compile and run your project.

   

   The first compile will take little bit of time, but any compile after that should be quick, because the compiler builds on an as-needed basis, compiling only your most recent changes (as opposed to Flash Professional, which compiles your ENTIRE project every single time. Bleh!). Once you run your new project, the FlashPlayer should pop up and you should see a blank screen. Luckily, this is exactly what we want. As of right now, this is your App.

   

Hello, Planet

This is nice and all, but let’s try to the write a simple message on screen so that when we are testing, we know it actually works. Let’s write “Hello Planet” on-screen.

1. Just below the green commented line where it says //entry point in your Main.as file, copy and paste these lines into your code:

   var tf:TextField = new TextField();  
   var format:TextFormat = new TextFormat();  
   format.font = "_sans";  
   format.size = 48;  
   tf.defaultTextFormat = format;  
   tf.text = "Hello Planet";  
   tf.width = stage.stageWidth - 20;  
   tf.x = 10;  
   tf.y = 10;  
   addChild(tf);

   

2. Click the compile button (or press F5). Did it screw up? Good. There are a couple more things you have to do before you are ready to compile without errors.
3. In your code, click to place your cursor carat on the word Textfield and hit Ctrl+Shift+1 on your keyboard. The word turns blue. If you scroll to the top of the class, you’ll notice that there is an extra import line at the top of your code. CTRL+SHIFT+1 is a special feature of FlashDevelop that does code completion. In this instance, CTRL+SHIFT+1 automatically handles your import statements for you. You need to import the TextField code with this statement if you want your TextField to work.
4. Use CTRL+SHIFT+1 on the TextFormat word and you should see this:

   

5. Now click Compile (or press F5).

   

   Thar she blows!

   (It works, but it’s no Angry Birds. – Ed.)

Bust Out the Hardware

This is moving along nicely. You:

• Installed FlashDevelop, a free and open-source IDE for creating Flash and AIR content
• Downloaded and sunk the latest AIR SDK and Flex SDK into a single, merged folder
• Pointed FlashDevelop to the Flex SDK to use its superior compiler
• Created a new FlashDevelop project using the Mobile AIR application template
• Wrote and compiled a new Hello Planet AIR app that you can deploy to a testing device

In the next part of the tutorial, you’ll fine-tune FlashDevelop and modify a number of settings and batch files to create the magical, mystical .ipa file, and you’ll see that file running on your testing device.

Continue to Part 4

This is the second part of our tutorial series by Intern Sina on creating an AIR application for free on a PC using FlashDevelop, and deploying it as a native app on an iOS device like the Apple iPad, iPhone or iPod Touch.

Jump to other parts in the series:

• Part 1 – Sign up for an Apple iOS Developer Account
• Part 3 -Use FlashDevelop to build your mobile AIR app
• Part 4 – Modify your project settings and test your app on an Apple device

Drudgery

Without a doubt, this section of our tutorial series on bundling your Adobe AIR App for Apple’s iOS platform is the pits. You have to use a complicated command line interpreter, you have to juggle what may feel like a million different certificates and profiles, and you have to jump through a dizzying array of hoops just to get everything set up … and you’re not even going to start building your app at all! But trust me: once you’ve cleared these hurdles, the rest of the process is gravy.

The first goal of this tutorial is to create a signing certificate, which is used very much like a hot brand on cattle. It’s the digital signature of you or your company that identifies an app as your own. We need to use a program called OpenSSL to create this signing certificate.

Install Open SSL

In order to turn your future AIR project into a native app, you need to create two important files: a Signing Certificate and a Mobile Provisioning Profile. If you are working on a Mac, you actually use a program called Keychain to do some fancy voodoo magic and get the certificate you need. We are working on a PC and we do not have that luxury, so there are a couple of confusing steps that we must go through.

The first thing you have to do is go to http://www.slproweb.com/products/Win32OpenSSL.html. Scroll down, and then download the Visual C++ 2008 Redistributables and install the resulting file. Next, download the Win32 OpenSSL v1.0a Light file and install that after you have installed the first package. These two files will help you create the Signing Certificate Request you so richly deserve.

Be sure to keep track of where you installed those last two elements. Next, visit this site:

http://help.adobe.com/en_US/as3/iphone/index.html.

These are Adobe’s help files for generating your signing certificate and then converting that certificate into a .P12 file. If you get lost in this tutorial, that page will be your safety net.

On that Adobe support page, you will see some instructions for Mac machines. Ignore them. Scroll down to the Windows instructions and give them a once-over.

The instructions say that you have to install Open SSL. You’ve already done that. Open a command prompt window. You can do this by going to your Start button and typing in cmd in the search field. (You can also hold the Windows key on your keyboard and hit the “R” key (for “Run”), then type cmd and hit Enter.)

Once you are in the command prompt, travel your way to your Open SSL bin folder. Depending on where you installed it you will have to travel to a different path than in this example. (For your sake, i hope you installed Open SSL in a location that you can remember!)

If this is your first time using the command prompt, here’s a quick primer on the commands that will help you get around:

• cd This command means “Change Directory”. If you are in a directory and you want to go into one of its sub-directories, use this command plus the directory name (example: cd directoryName)
• cd.. This command will pull you up one level in your directory structure
• dir Type this command to see a list of all of the files and folders within your current directory
• dir /w The /w (wide) switch spreads a directory listing across multiple columns. This is useful for seeing all the folder names at a glance, instead of in one big long scrolling list.

You may have some problems getting some of the following commands to work. A fine commenter (and Ontario resident!) named Dan Zen mentioned on the Adobe guide’s comments section that you may need to input set RANDFILE=.rnd in your command prompt before the following commands will work properly.

Generate a Signing Certificate Request File

With all of that taken care of, you can start inputting some commands to create your Signing Certificate Request file. Once you have that file, you’ll use it to ask Apple for your proper Signing Certificate file that you’ll use to identify your app.

1. Punch this command into your command line interpreter and hit the ENTER key when you’re finished:

   openssl genrsa -out mykey.key 2048

   You should see this response:

   

2. Next, type (or highlight the line, right-click, choose “Copy”, and right-click/”Paste” in the command line interpreter):

   openssl req -new -key mykey.key -out CertificateSigningRequest.certSigningRequest  -subj "/emailAddress=yourAddress@example.com, CN=John Doe, C=US"

3. Now, before you hit ENTER you’ll want to edit a couple of things. First, replace “John Doe” with your own name or company name. Then replace the “yourAddress@example.com” email with your own email. Then press ENTER.

   You should get a message similar to this:

   

   You just generated the Signing Certificate Request file that you’ll use to ask Apple for your Signing Certificate. The Signing Certificate Request file is located in the bin folder of your Open SSL install. It has a .certSigningRequest file extension and should look like this:

   

Obtain a Signing Certificate for Development

You have to upload your Signing Certificate Request file to the Apple Provisioning Portal to get your signing certificate.

Note: There have been instances where this upload does not work with Google Chrome. Just to be safe, use another browser like Firefox.

1. Navigate to the iOS Provisioning Portal after logging in with your developer account and click on Certificates.

   

2. Click Request Certificate.

   

   Note: If you are a team member and/or you have not paid the annual developer fee of $99 dollars, then you cannot request a Signing Certificate. Only the Team Admin – the person who has paid the development fee – will be able make this request.

   On the next screen, you will upload the Signing Certificate Request file that you generated in the previous section.

   

3. Click the Browse button and navigate to the bin folder located within your OpenSSL folder.
4. Once you have selected the Signing Certificate Request file, click Submit. Your next screen should show this:

   

5. Just hit Refresh a couple of times on your browser and you should eventually see this:

   

6. It’s your Signing Certificate! Go ahead and download it. Just to make things easier, you can save that certificate in the bin folder in the Open SSL folder, where your Certificate Signing Request file is sitting.

Convert the Signing Certificate to a .p12 File

Are you having fun yet? Yeah, me neither. We are making good progress though. The next step is converting that Signing Certificate to a p12 certificate, because Apple loves certificates.

1. From the Adobe help page, visit the link describing the process of converting a developer certificate to a p12 file. You get a list of more commands that you’ll have to punch into your trusty old command prompt.

   

2. Copy the first command (highlight the text, right-click and select “Copy” from the context menu):

   openssl x509 -in developer_identity.cer -inform DER -out developer_identity.pem -outform PEM

3. Open up your command prompt as I showed earlier, and navigate to the bin folder of your Open SSL directory.
4. Once you’re there, paste in the first command (right-click and select “Paste” from the context menu), and press ENTER.
5. Skip ahead to Step 3 of the Adobe help guide and copy that command. (The command in Step 2 is for Macs only.)

   openssl pkcs12 -export -inkey mykey.key -in developer_identity.pem -out iphone_dev.p12

6. Once you punch in the command, enter a password and then verify that password. Make sure the password is something that you will remember. (Save it in a .txt file in that folder if you’ve got a lousy memory like me – Ed.) When you are typing in your password, the command prompt does not give you the luxury of seeing dots or asterisks to indicate how many letters you are typing in. Rest assured that the command is accepting your input.

   Note: You may get an error mentioning a “random state”. Just type in the command set RANDFILE=.rnd and it should fix the problem for you.

7. Go into the bin folder in your Open SSL directory and you should see your .p12 file. Hooray!

   

Create an App ID

Now that you have the precious file you need, it’s finally time to create your Mobile Provisioning Profile. You’ll start by setting up a unique ID for the app you’re creating.

1. Navigate back to the Provisioning Portal in your web browser to create an App ID for your app. Log in, click on Provisioning Portal, and click on App IDs.

   

2. Click New App ID.

   Note: If you have not paid the developer fee, or if you are just a team member of the Team Admin, you will not see this option. Ask your Team Admin to complete this step.

   

3. On the next screen you’ll start by writing a Description for your app, which can be anything you want. (This is what the player will see when he sees your app in the App Store. Obviously, there’s a whole marketing concern here that’s outside the scope of this tutorial. Since we’re just building a test app, i recommend you punch SOME CRAZY NONSENSE in there for your description. Take THAT, marketing. -Ed)

   Within the Bundle Seed ID (App ID Prefix) you will have various options, depending on your account status. If you are the Team Admin, you’ll have a “Generate New” option. Team Members will only see a “Use Team ID” option. (If this is not your first App, you could also choose the Bundle Seed IDs for previous project). Either way, leave it at the default.

   The Bundle Identifier lets you create a specific package for your App. The standard way to make this package is to reverse the name of your website domain. I used com.sina.ipadtest. (Our team uses com.untoldentertainment.whatever – Ed.)

   Alternately, you can use a generic Bundle Identifier by just putting an “*” in the field.

   Note: There have been cases where the asterisk does not work for some people. It is a safe bet you make a specific namespace like the examples above.

   

4. Click Submit.

   Voila – you have now created your App ID! On the next screen you will see all of the app profiles you’ve created.

   

Create a Mobile Provisioning Profile

Now that you have an App ID, you can now create your Mobile Provisioning Profile. This is the crowning touch to everything we’ve done in this tutorial so far. The Mobile Provisioning Profile glues your developer(s), your Signing Certificate, your app ID and your testing device together. Once you have this file, you’ll be able to test an app on your device.

1. Within the Provisioning Portal website, click Provisioning in the sidebar.

   

2. Click on New Profile.

   Note: You only see this option if you are the fee-paying Team Admin.

   

3. Give your provisioning profile a Profile Name.

   

4. Choose the Signing Certificate(s) that you want to use with this profile.
5. Use the drop-down list to indicate the app for which you’re creating this profile.
6. Finally, indicate the testing device you want to test it on.
7. Click Submit.

You’ll be taken to a screen that says your Mobile Provisioning Profile is pending. Just click your browser’s refresh button a couple of times until the Downloadbutton appears, and download your precious, hard-fought profile. Make sure to save it in a location you’re likely to remember.

Are We There Yet?

That was a big pile of hoops to jump through just to test an app on your device, and we haven’t even begun building the app yet! Here’s what you just accomplished:

1. You used the command line and OpenSSL to create a Certificate Signing Request file.
2. You sent that file to Apple. Apple responded by enabling you to download your Signing Certificate file. This file identifies you as the developer of your app.
3. You converted your Signing Certificate to the .p12 format.
4. You created an ID for your app.
5. You created your Mobile Provisioning Profile, the glue that holds all these elements together and enables you to test your app on an iOS device.

The good news is that you DO NOT need to repeat the steps to create your Signing Certificate for additional apps. Now that you have that file, you’ll use it to sign all of your iOS apps from here on in. Similarly, you won’t have to re-enter your developer ID or device ID for future projects (unless, of course, you gain a new team member or device). The App ID and Mobile Provisioning Profile are the two pieces that are unique to your app – you WILL need to repeat those steps for additional projects.

The next part of this tutorial series will cover the process of creating your actual Adobe AIR app using FlashDevelop, bundling it up with this mess of certificates and profiles you just built, and deploying the app to your testing device.

Continue to Part 3

This is the first part of our tutorial series by Intern Sina on creating an AIR application for free on a PC using FlashDevelop, and deploying it as a native app on an iOS device like the Apple iPad, iPhone or iPod Touch.

Jump to other parts in the series:

• Part 2 – Obtain your Signing Certificate & Mobile Provisioning Profile, and create your App ID
• Part 3 -Use FlashDevelop to build your mobile AIR app
• Part 4 – Modify your project settings and test your app on an Apple device

Dead Wrong

There’s a lot of FUD floating around about Flash these days. Ever since Steve Jobs took to the mic and sounded the death knell of at least the perception of Flash, there’s been heaping gobs of misinformation about what you can and can’t, should and shouldn’t do with Flash. i chalk it up to the fact that death is news. It’s BIG news when Michael Jackson dies, BIG news when Steve Jobs dies, and equally big news if you can be among the first to report on the death of a technology or company – RIM, Flash, Palm, HP – take your pick. If it bleeds, it leads.

This hyperbolic and sensational misreporting is particularly damaging for those of us who have made our living developing with Flash and Actionscript. Back in 2000, when i first got into Flash, i chose it because the alternative was HTML. HTML appeared and performed completely differently depending on a number of different factors:

1. The platform (Mac, PC or Linux)
2. The screen resolution (640×480, 800×600, 1024×768, etc)
3. The browser (Netscape, Internet Explorer, Safari)
4. The browser version (HTML could render completely differently from IE6 to IE7)

Meanwhile with Flash, i could build something inside the little Flash Player box, and it would look and behave reasonably identically across platforms, resolutions, browsers, and browser versions. (Subsequent versions of the Flash player complicated things a smidge, but we were still WORLDS away from the pain of HTML). What’s more, as a visual person, i could actually lay things out within the tool, instead of coding them abstractly and waiting to see how the browser would render them. If i wanted something to appear over there, i picked it up and put it over there. No futzing around with padding or align tags for hours.

The push towards HTML5 doesn’t scare me – more accurately, it makes me feel ill. It’s a step backwards. Without proper tooling, i see myself banging my head against the wall picturing absolutely everything in codespace (rather than concretely laid out in front of me in designspace), and programming all kinds of exception cases so that my content performs properly depending on platform, browser and version. You know what? No thanks.

Prying Flash from my Cold, Dead Hands

As long as the tools for other technologies stink, and as long as i can keep making and monetizing projects in Flash, i’m going to stay the course until there’s a compelling technological /creative/workflow reason to make a jump. Untold Entertainment has deployed two games written in Actionscript (Sissy’s Magical Ponycorn Adventure and Heads) across two different mobile platforms (Apple iPad and the BlackBerry Playbook), and we’re just getting warmed up.

Here are the facts, at the time of this writing:

1. No one really wants to play a game in a browser on a phone. Native apps are where it’s at.
2. Yes, you CAN put Flash- and Actionscript-created content on an iPhone, in native app format.
3. You can even do it without having to buy Flash Professional or Creative Suite.
4. You can develop entirely on a PC until the very last step (uploading content to the App Store).
5. Untold Entertainment is about to show you how.

What You’ll Need

While buying Adobe’s tools is optional, you’ll still need to spend a bit of money (or mug the right people) to pull this off. Here’s what you’ll need:

1. An Apple Developer account, which is $99 USD/year. Once you start down this path, you’re in it for the long haul … if you let your developer account lapse, they pull all your products off the store. For realsies.
2. A Mac (not free) running the latest version of Xcode (free).
3. An iOS device (optional, but obviously recommended).
4. FlashDevelop v4 or better (free, PC-only)

Introducing Sina

Sina Kashanizadeh is a Sheridan College computer programming student and an intern here at Untold Entertainment. He’s done all the legwork in this process, and has written this step-by-step guiding on porting your Actionscript projects to iOS. Take it away, Sina!

Flash on iOS? So You Want to Be a Hero…

With the mobile world expanding at a crazy rate you may have had the crazy idea to try making an App yourself and putting it on the iPhone. Well, you’re a brave soul, because it can be a confusing task. This is why I have scoured the internet and composed a step by step tutorial of this process. This tutorial would not have been possible without the fantastic people that maintain FlashDevelop and the wonderful community behind it. I would also like to thank Lee Brimelow and Adobe for putting out some great tutorial videos that helped me out a lot. Last but not least, I would like to thank CodeandVisual.com for putting up a fantastic comprehensive guide that inspired me to move forward whenever I had trouble writing this tutorial.

I just want to be clear that this tutorial is not the “be-all, end-all” of this process. There are many different ways of transferring your Flash App to iOS, and the problems I cover are specific to my method. Also, the process I cover is PC-specific.

Getting Started

Before we begin, I would like to recommend a very good video resource by Adobe Evangelist Lee Brimelow, in which he explains the basics of adding an app to the App Store when using Flash. If you do not know how this process works, I highly recommend this video, as it breaks down the somewhat painful process of adding an AIR App to the App Store when using a PC (thanks again, Lee!). The good news is that if you go through this once, you’ll understand the ins and outs of the process. You only have to do the most painful parts once.

The video covers a myriad of stuff but the basics boil down to this: Your end goal is to create an .ipa file, which is what you’ll upload to the App Store. To do this you will require:

• An App
• An iOS developer ID from Apple ($)
• An iPad or iPhone ($)
• A Mac ($, but required for one step only … borrow one from a friend!)
• A Signing Certificate
• A Mobile Provisioning Profile
• YOUR SOUL

Sounds like fun? Well it isn’t, but let’s get cracking anyway!

Any Club that would Have Me as a Member

As I mentioned above, you’ll need a developer ID from Apple. Head over to the iOS Dev Center and register for “free”.

Go through the steps of signing up and the email verification and you will acquire an Apple ID. Now, the unfortunate thing is that you get the Apple ID for free, but if you want to develop anything with it on a device – even a silly test app that you will never release – you will have to pay $99 a year. You’d better be positive that your Angry Birds clone will be worth at least a hundred bucks a year in revenue. You can sign up for a free student account, but again you can’t really do anything with it unless you drop some cash. If you are helping someone develop an App for the iPhone/iPad and they are paying the developer fee, they can add you as a partner to their project.

Adding a Device to Your Developer Account

If you want to test and ultimately launch this App, you will need an Apple device such as an iPhone, iPod Touch or iPad. You will also need to register your Apple device with your Apple ID. Follow these steps:

1. Go into the iOS Developer website and log in with your new account info. Here, you will see the iOS Provisioning Portal. Click on it to see further options.

   

2. click Devices in the sidebar.

   

3. Click Add Devices.Note: if you are a partner developer with a team member profile, you will not be able to add a device. The option will only appear for the master account holder.

   

4. On this screen, you can add up to 100 devices to your account. Start off by adding your Device Name. Nothing fancy here – just enter something that will help you identify it – ie “Sina’s iPad”, or “iPhone what i stole from that guy that one time”.
5. Enter the Device ID (40 hex characters). This is the serial number that is associated with the device that you are trying to register. To find this Device ID, open iTunes while your device is connected. On the main screen, you will see all the information about your device, including a field called Serial Number. It doesn’t look clickable, but click on that field anyway and the number changes to a hex code. That’s your device ID.

   

6. Once you’ve filled in those details, click Submit and the device will be added to your Developer account. Now you can build an Adobe AIR application and test it on your device.The next tutorial will take you through the process of requesting and creating a Signing Certificate, converting that certificate to the p12 format that Apple requires, and generating a Mobile Provisioning Profile for your new app.

   Continue to Part 2

What’s New in Version 2?

Absolutely nothing! The Unity 3.x version is identical to the first edition, save for the fancy new cover by UbiSoft Toronto game artist Dan Cox. The occasional errata from the first edition have been corrected, and the screenshots have been updated so that they match Unity’s subtle interface changes. i’ve included two new spaceship models by Dan in Chapter 11 (the same ones you see on the cover), which i’ll make available to owners of all versions.

The first chapter was updated to discuss the BootCamp demo instead of the original Island Demo, which stopped working reliably as of version 3. Then, just as we were ready to release the book, Unity launched v3.4, which included yet another demo and more subtle UI changes. So Unity 3.x Game Development by Example has been lovingly (?) re-written TWICE to bring it in-line with what those nutty funsters at Unity have been up to.

Should i Buy It?

Yes you should.

i made the rather bold claim that the first edition of the book may very well cure cancer. i realize now that this was entirely irresponsible of me, and i regret my error in judgment. i can say now with all certainty that version two is guaranteed to cure cancer, or your money back. Please contact Pack Publishing for all refund inquiries, including a post mortem certificate from your next of kin.

Praise for Unity 3D Game Development by Example (from actual people)

“A great resource for learning Unity.” – Michael Todd, indie game developer

“Creighton’s book teaches both Unity and good design practices while staying hip, funny, and even controversial. A must read!” – Ryon Levitt, Game Designer

“I went from unemployed to working full-time in California!” – Mohammed Al-Sahaf, game school graduate

“I didn’t loose brain cells when I read this book.” – Brent Arnold, Mobile Developer

1. decrease the amount of time the player has to complete a goal

   

   at the climax of Super Metroid, the player has to escape the ship before it explodes

2. increase the speed or power of obstacles

   

   Pac Man’s ghost enemies speed up as the game escalates

   

   Bubble Bobble introduces the invincible Baron von Blubba when the player dawdles

3. decrease the number of “chances” or “tries” the player has to complete a goal

   

   Donkey Kong gives the player a set number of tries (“lives”) as the game escalates before the machine requires another quarter and the player has to start from the beginning

4. increase complexity

   

   as Bejewelled escalates, it introduces extra gem colours, which makes finding matches more challenging

5. increase the grind – an action the player must perform repeatedly to be successful

   

   Gran Turismo introduces endurance races where the player must race for a set number of real-time hours to win

   

   World of Warcraft confronts the player with increasingly more difficult monsters, which forces the player to repeatedly kill weaker monsters to improve his stats

6. decrease the amount of visual information available to the player

   

   The Legend of Zelda periodically turns out the lights, and requires the player to doggedly re-ignite lamps

7. increase the quota – the number of small goals the player must complete within the time limit. This is really just a variation on decreasing the time limit.

   

   As each level progesses, Diner Dash increases the number of customers you have to serve

Lightning Bolt! Lightning Bolt!

i learned an interesting tip about escalation. i wish i could credit my source, but i have a memory like a sieve . (Mother Nature escalates my life by increasingly turning me into a doddering old fool.) The tip is to escalate your game with a lightning bolt graph, rather than a smooth incline. Regard:

In an old-school arcade game, the levels get progressively more insane, until you lose the game and have to feed the machine more quarters. This makes sense for a coin-op that exists to devour your hard-earned pocket change, but it doesn’t make sense if you’re designing a more modern game where you want your player to be engaged for as long as possible. A freemium game, for example, lives and dies by retaining players; a linear escalation curve increases the likelihood that the player will quit out of fear or exhaustion. If he just barely makes it out of level 10 by the skin of his teeth, he may not even want to attempt level 11. He’d sooner quit while he’s ahead.

A modern game that strives for retention might use a lightning bolt or stair-step graph. Here, level 10 was insanely difficult, but level 11 gives the player a bit of a breather. One of the early examples of this approach that i can remember is the coin-op beat-em-up Final Fight. After brawling your way through a preposterously crime-ridden city as the roid-raging mayor or one of his two ninja buddies, you get to smash a car. No bad guys, no chance of death, no risk of losing – just a time-limited opportunity to smash a car.

A more modern example is Little Things, a hidden object game on the iPad that i’ve been playing this week. The levels in Little Things are, refreshingly, NOT rooms in a Victorian mansion in which a child ghost has murdered a wealthy detective. Instead, they’re little pictures composed of even smaller pictures. The player has to complete his quota by finding the items on the list.

Some of these pictures make it easier to find the little things within. The umbrella’s striped design makes it easier to compartmentalize sections of the image and limit your focus. In contrast, the hideously jam-packed cupcake is a real challenge to sift through.

If Little Things were to escalate linearly, you’d unlock the easy pictures at the beginning of the game, and the denser pictures towards the end. But Little Things has a staggered escalation; the densely-populated hamburger is introduced before the cinchy electric guitar. If the escalation was linear, you’d complete 10 missions in the beagle picture before moving on to complete 10 further missions in the wheelbarrow picture. Instead, Little Things bounces around from picture to picture, shuffling in the easier images to give the player a break. Even the missions themselves are staggered: in one instance, you’ll find yourself scouring the level for 15 objects under distinct time pressure; the very next level, you’ll need to point at four pairs of sunglasses in one of the easier pictures.

The net effect is that Little Things held my attention much longer than it would have if its escalation were progressive. Give consideration to staggered escalation if you count player retention among your next game’s goals.

It took a lot of back and forth and futzing to finally convert the artwork properly, and when i finally found the solution, i realized i had known it all along and had merely forgotten it (because i don’t do this type of thing often). So i’m recording the solution here for posterity; the next time i have to do this, a Google search will turn up my own blog :) It actually wouldn’t be the first time that’s happened.

i’ll keep you on tenterhooks and take you through the frustrating conversion process, just so that you can swear along with me and nod your head and say “yep – that’s happened to me.”

Export Image

The ability to export artwork to .ai format has actually been removed from Flash Professional as of version CS5, and has been replaced with the Adobe .fxg format, which works as expected. The .fxg format even converts gradients properly, which have been a longstanding asspain for the past 10 years. If you’re running CS5 or better, export to .fxg and you’re done. If you’re trapped in CS4 or below, here’s what you may have tried:

1. File > Export > Export Image
2. Choose Adobe Illustrator (*.ai) from the drop-down filetype list
3. Punch in a filename, and click “Save”
4. Open the file in Illustrator

The first roadblock you encounter may be this message:

Can’t open the illustration. The illustration contains an incomplete or garbed object description.

Offending operator: “”

Adobe_Illustrator_AI5 / initialize get exec
%%BeginEncoding: _pixelmic … feh. i can’t be arsed to look up the accented characters to type the rest.

i’ve ranted at length before about the error messages eggheads put into their software products. How on Earth is joe average user – and an artist, at that – supposed to react to and troubleshoot a message like this?

Obviously (?), all the egghead wanted the artist to do was this:

Select the single movieclip and press CTRL+B to break apart the object into separate objects. Now, when i go through the export process and bring the file into Illustrator, i get this:

The reason why the colors are desaturated and grey-looking apparently has to do with the Flash .ai export routine deciding to convert RGB artwork to CMYK artwork. i don’t know why it does this, but it’s not helpful. But at least the artwork is in Illustrator in vector format, right?

At this point, you could pick through every piece of vector art and tweak the color by hand … if you’re a sucker. Instead, let’s get on to the reason you’re here: the actual solution to this non-working nonsense.

WMF FTW!

The secret is to export as a Windows Metafile. Mac people, i don’t know if you have this option. If not, i’m not sure how to help you … but once you counter-intuitively export as a .wmf file instead of an .ai file and bring THAT into Illustrator, voila: your artwork is beautifully preserved with its RGB colors intact.

As i mentioned, the one drawback is that gradients don’t survive the crossing. This character’s cell phone casts an alpha gradient glow across her face, which shows up as a flat white polygon in Illustrator:

.fxg format will fix that. If you’re not ready to upgrade your software, this might entail an ugly hand-conversion process of all your gradients … unless someone else has discovered the esoteric conversion secret to preserving gradients? Anyone?

Big thanks to Gavin Friesen, my Art Director back at Corus, for originally cluing me in to this solution.

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

Unity3D iOS Porting Tips

The article contains a pointers on trimming your Unity pc project to succeed under the more restrictive memory and processor constraints of the iPod/iPad/iPhonograph.

You can do something very similar in Unity 3D, but the process is slightly different. Be sure to read our Flash to Unity 3D Glossary if you’re coming over to Unity 3D from Flash.

1. Create the GameObject

We’ll make it real simple. Click GameObject > Create Other > Cube in the menus to add a cube primitive to the Scene.

2. Create an Empty Prefab

A Prefab is a lot like a Flash MovieClip. It’s going to contain our Cube GameObject. To create the Prefab, click the Create button in the Project panel, and choose Prefab from the resulting menu.

Right/alternate-click on the Prefab, or click and hold (Mac)/press F2 (PC) to rename the Prefab. I called mine “Cube”. This won’t create a naming conflict or anything.

3. Click/drag the Cube into the Prefab

Click and drag the Cube GameObject from the Hierarchy panel into the empty grey Prefab you just created in the Project panel. The Prefab lights up blue to indicate that it’s got junk in the trunk.

It’s now safe to delete the Cube GameObject from the Scene (via the Hierarchy panel) by highlighting it and pressing Delete (PC) or CMD+Delete (Mac). The Cube is safe and sound inside the Prefab.

4. Create a new Javascript

Our Cube Prefab is ready to be instantiated (instantiate == make an instance [copy] of). Let’s create a javascript to do the instantiating. In the Project panel, click Create > Javascript to make a new script.

Name the javascript something sensible. Then, click/drag the script onto the Main Camera. (We do this because our script won’t execute unless it’s hooked up to a GameObject in the Scene.)

5. Store a Reference to the Prefab

This is the fanciest/weirdest thing we’ll do in the entire tutorial.

Double-click the script to open it up in Unitron or Uniscite (depending on whether you have a Mac or a PC).

Declare a variable at the top of the script called myCube:

var myCube : GameObject;
 
function Update()
{
}

Save the script and close the editor.

In order to store a reference to the cube Prefab, we need to click and drag it into the variable we just created.

In the Hierarchy panel, click on the Main Camera, which is the GameObject to which we attached our script.

In the Inspector panel, look for the script component. You’ll see the myCube variable we created, and next to it is a piece of text that says None (Game Object)

myCube is the name of the variable (bucket), and the None (Game Object) is where the value goes.

Now, you need to click and drag the Cube Prefab from the Project panel into that value area that i’ve highlighted.

This is the result:

It’s weird. i know.

NOTE: You called the variable “myCube”, but it gets displayed in the IDE as “My Cube”. Why is that? Chalk it up to a Unity idiosyncrasy that i’m not a huge fan of. Check the script. Your variable is still called “myCube” where it counts.

6. Instantiate the Prefab

Now, with a reference to that Prefab, you’re all ready to go. Double-click to edit your script again, and punch in the following code:

var myCube : GameObject;
 
function Start()
{
     var pos : Vector3(0,0,0); // this is where the Cube will appear when it's instantiated
     var rot : Quaternion = Quaternion.identity; // Quaternion.identity essentially means "no rotation"
     Instantiate(myCube, pos, rot); // The Instantiate command takes a GameObject, a Vector3 for position and a Quaternion for rotation.
}
 
function Update()
{
}

Gettin’ Fancy

If you’ve read our article Understanding Loops with Arrays, you might have a notion of how to use Loops and Arrays to instantiate an armada of Prefabs into your scene. Here’s some sample code:

 
var myCube : GameObject;
 
function Start()
{
     // Store a bunch of different positions in an Array:
     var aPositions : Array = [new Vector3(0,0,0),
                                      new Vector3(1,2,1),
                                      new Vector3(2,1,1),
                                      new Vector3(2,0,0),
                                      new Vector3(0,3,0)];
 
     var rot : Quaternion = Quaternion.identity;
 
     // Loop as many times as there are elements in the aPositions Array:
     for(i=0; i<aPositions.length; i++)
     {
          Instantiate(myCube, aPositions[i], rot); // Put a new cube on the screen using the i'th position   
     }
}

One More for the Road

Just for kicks, here’s a script that’ll throw the cubes on the screen any old place, using Random.Range():

 
var myCube : GameObject;
 
function Start()
{
     // Let's store some minimum and maximum possible x,y and z values
     // to position our cubes:
     var minX : int = -5;
     var maxX : int = 5;
     var minY : int = -5;
     var maxY : int = 5;
     var minZ : int = -5;
     var maxZ : int = 5;
     // (you can fiddle with these numbers to change the range of possible spawn positions)
 
     var totalCubes : int = 50; // Change this to whatever number of cubes you'd like to have on-screen
 
     var rot : Quaternion = Quaternion.identity;
 
     for(i=0; i<totalCubes; i++)
     {
          // Use Random.Range to grab randomized x,y and z values within our min/max ranges:
          var randomX : int = Random.Range(minX, maxX);
          var randomY : int = Random.Range(minY, maxY);
          var randomZ : int = Random.Range(minZ, maxZ);
 
          var pos : Vector3 = new Vector3(randomX, randomY, randomZ);
 
          Instantiate(myCube, pos, rot); // Put a new cube on the screen using a randomized position   
     }
}

thing.renderer.enabled = true; // or false

… where “thing” is a reference to a GameObject.

If you’re doing this in a script that’s attached to the GameObject you want to hide, try:

gameObject.renderer.enabled = false;

Note that the GameObject’s collider is still active, so the GameObject can still be clicked on, run into, etc. Here’s a fast way to make the GameObject’s collider inactive:

gameObject.collider.isTrigger = true;

To disable the GameObject’s clickability, do this:

gameObject.active = false;

Here are a few glossary terms that kinda sorta carry over from Flash to Unity:

MovieClip == GameObject (but more accurately, Symbol == Prefab. Much like a MovieClip/Graphic/Button in Flash, whatever changes you make to a Prefab in Unity will replicate to all instances of that Prefab)

Scene == Scene (but Scenes in Flash are generally useless and glitchy … Scenes in Unity are the bee’s knees)

Library == Project panel

Properties panel == Inspector panel

Timeline == A-NOTHING!! (except that there IS a timeline that allows you to animate GameObjects. The resulting animation is stored in an .anim file inside your Project panel. You can apply an animation to any GameObject in your Scene, so animations are curiously reusable)

Instance names == tags … sorta (but unlike in Flash, you can have multiple GameObject instances with the same tag)

Layers == layers (but Unity does not display its layers in anything nearly as nice as the Flash timeline)

1. Start a New Project

Every Unity sits in its own folder. In this dialogue, browse to or create a new folder where your project will live, and then click the Create button.

What you’re left with is this:

Here’s what’s going on behind the scenes:

Unity automatically creates three sub-folders in your Project folder. You won’t have to touch these folders – in fact, you really shouldn’t, because there’s metadata in there that might get botched if you start poking around. Most of the time, you can import assets directly through the Unity IDE (program).

2. Make a Scene

Unity Projects are comprised of Scenes. In Flash, it wasn’t really a good idea to use the Scenes, but in Unity, it’s darn near a requirement. What you’re looking at now is actually an unnamed Scenes. Scenes must be saved individually … whenever you try to leave one Scene to look at another, you’ll get a Save Confirmation prompt.

The smartest thing to do right off the bat is to save this Scene.

Choose a name for your Scene. Some really simple examples are “Title”, “Credits”, “Win”, “Lose”, and “Game” for an extremely basic project. i’m calling this one “Game”, which is where all my main game action will take place.

Once you hit “Save”, two wonderful things will happen:

The Project panel is where all your stuff goes. It’s very much like the Library in Flash. Scenes have a little Unity 3D icon next to them.

Put Your Scene in a Folder

The final thing you’ll want to do is to create a folder for your Scenes, and dump your Scene inside it.

At the top of the Project panel, click the Create button and choose “Folder”:

You can also right click or alternate click on the Project panel to bring up this menu. Mac users can probably splat-click or some nonsense.

And then:

What Now?

How do i learn Unity 3D?

To learn more about developing games for Unity 3d and to learn the basic controls for getting around the program, read the first chapter of my book Unity 3D Game Development by Example. Next, buy four copies of the book (in case you accidentally drop three of them in the mud).

How do i build a timer in Unity?

When you’re a little further along, read this sample of Chapter 7 of my book, Don’t be a Clock Blocker. That’s how.

How do i program in Unity?

If you need a little help with programming in Unity using javascript, read our Understanding Programming in Unity Javascript series.

How do i transition from Flash to Unity?

Check out our article on Five Common AS3 to UnityScript Translations.

Alright – what else you got?

Like our style? For more free Unity 3D tutorials, sign up for our Unity 3D Game Development by Example newsletter, and we’ll send out a link whenever we post a new tutorial or article on Unity 3D.

Go forth and game!

In Understanding Functions, we learned that Functions are a way to bundle code statements together into a tight little unit that we can invoke (or “call”) any time we like, and as often as we like. There are two very important features to learn about Functions: Arguments and Return Values. We’ll figure out Return Values in this article.

One Fanta, Please

We talked about how Functions that accept arguments require exact change. If a Function asks for a String, you have to pass (“pay”) it a String. If it wants an int, you must pass it an int. If it wants two Arrays, a String, and four ints, you have to pass it those seven datatypes in that exact order. If you pass the right datatypes in the wrong order, if you pass the wrong datatypes altogether, or if you pass the wrong number of arguments, you’ll throw a (possibly cryptic) error.

So let’s imagine that Functions are kinda like vending machines. They require exact change, even specifying the types of coins you need to pay (ie five nickels, NOT one quarter). But what do we get for all our trouble? A kick in the pants and we’re sent on our way, that’s what. Wouldn’t it be great if Functions could actually give back to society, instead of being a drain on our charitable resources?

Thanks to return values, they can. A return value is the can of Coke that the Function vending machine spits out when we plug in our coins.

Just as we type (specify a datatype for) our variables, we can also type our Functions. When we do that, we’re saying “this is the type of thing the Function is going to return (give back/pay out/cough up). Here’s how we write a Function that returns a String:

function giveMeGoodNewsOnly() : String
{
    return "good news";
}

There are a few moving parts involved here. Let’s take it step by step.

The type of the return value goes at the end of the Function declaration. We split it out using a colon (two dots), just like when we type a variable. Here’s a punctuation refresher:

And here’s a representation of the Function using colour blocks, because colours are pretty:

By adding that datatype to the end of our Function declaration, we’re making a promise: the Function will return (pay out/cough up) something that has that datatype. To live up to that promise, we use the return keyword. Return is the command that pays/spits out/coughs up a value. In the code example above, the giveMeGoodNewsOnly Function is typed String, which means it must return a String. In the statement block (between the curly braces), we use the return keyword to return a String. And all was right with the world.

Where Does the Return Type Go?

So, fine – we return something from our Function. But what happens to that value? Remember when our Pac Man-like code interpreter chewed through the Function call, and packed his suitcase with the arguments?

When the code interpreter finds the function, he unpacks the arguments into the parameters.

At this point, the code interpreter has an empty suitcase. When he reaches a return statement, he packs the value into his suitcase.

As we saw earlier, the code interpreter returns to the next line after the original function call. But this time, he’s got a suitcase packed with a return value:

(this is an interactive demonstration! Keep clicking the “Next” button to follow the code interpreter through the example)

Unpacking the Return Value

When the code interpreter arrives from his journey with the return value in tow, we need to somehow capture that return value. Otherwise, the interpreter just throws it away and it disappears into the either.

Here’s a simple example to demonstrate that concept:

6+5;

You know and i know that 6+5 is 11. Your computer knows that too. When you type that into a line of code, the computer adds 6 and 5. And then …? Nothing. We haven’t told the computer to do anything with that result, so it’s a wasted piece of code.

Here are a couple of ways we can make use of the 11 result. We can store the result in a variable (bucket), or we can trace the result to the output/console window:

var result : int = 6+5; // Store the value 11 in a variable called "result"
trace(6+5); // Print 11 to the output window

Note: Unity javascript users should use print or Debug.Log instead of trace to print to the Console window.

It’s the same issue with Functions and their return values. If we call the sayHello Function and it returns a value, the value is going to disappear unless we capture it somehow. Just like the 6+5 example, let’s store the return value in a variable, or print it to the output window:

var greeting : String = sayHello("Jennifer"); // Store the return value "Hello, Jennifer" in a variable called greeting
trace(sayHello("Matthias")); // Print Hello, Matthias to the output window

The code interpreter needs some place to unpack his bags. These are just two ways to capture the return value – there are many, many more. For example, you can add the result to an Array using the Push method (see Understanding Arrays for more info).

You Get a-NOTHING!!!

What do we do about a Function that doesn’t return any value at all? Can we just leave that little section at the end of the declaration blank? Well, you can, but it all depends on how picky your compiler is. You can set the Flash compiler to Strict mode … certain other compilers are strict by default. This means that every variable must be typed (given a datatype), and every Function must also be typed.

The keyword for “no type” is void. If your Function doesn’t return a value, type it as void:

function thisReturnsNothing() : void
{
}

Return Stops the Show

The only really important thing to know about the return keyword is that when the code interpreter chews its way down to that line, it’s like hitting the EJECT button. The interpreter gets booted out of your Function, regardless of whatever statements you may have written beneath it:

function sayHello(playerName : String) : String
{
    return "Hello, " + playerName;
    // This line doesn't get executed.
    // Neither does this one.
    // Nor this one.
    // In fact, anything you write after a return statement gets skipped.
}

Breaking Stuff

As with arguments, there are some great ways to break a Function with return values. In brief, here’s how to do it:

1. Return a value even though your Function is typed void (or it’s untyped).
2. Type your Function to return a value, and don’t return a value.
3. Return a datatype that’s different than the return type declaration.
4. Write some branching logic so that it’s possible your Function may not return a value.

Let’s look at each of these, and the error statements that pop up when we make each mistake.

1. Return a Value When You Shouldn’t

Here’s an example of a Function that is typed void, but it returns an int:

function whoops():void
{
    return 57;
}

When you do this, here’s the error that the Flash compiler throws:

Scene 1, Layer ‘Layer 1′, Frame 1, Line 3 1051: Return value must be undefined.

That’s a pretty clear error message. Thank you, eggheads.

Here’s the error message you get when you use Unity javascript:

Assets/NewBehaviourScript.js(3,12): BCE0022: Cannot convert ‘int’ to ‘void’.

Again, with a tiny bit of detective work, this error is not too tricky to sort out. The compiler thinks you’re trying to make it force a value of type int to be a value of type void (which is what you’re returning), but this is impossible, even for computers.

2. Promise a Return Value, and then Cop Out

If we type a Function with anything other than void, we’re pledging to return a value. If we don’t return a value of that type, the compiler shows up on our doorstep in the middle of the night with mascara streaking her cheeks, demanding to know why you never do the things you say you’re going to do.

Here’s an example of a promise a programmer didn’t follow up on with a return statement:

function makeBabiesWithTanya() : int
{
    var numberOfBabiesWeCanHave : int = 17;
    // Honest.
}

So because the return statement is missing, this Function doesn’t actually give Tanya any babies. And that’s when she notices something is up:

Scene 1, Layer ‘Layer 1′, Frame 1, Line 5 1170: Function does not return a value.

This is one of the clearest error messages you’ll ever receive when using Actionscript 3. Let’s see how it looks in Unity javascript:

(no error)

Unity is clearly a lot more easy-going about this type of thing. Remember that when you’re thinking of which one you should invite on a road trip to Vegas.

3. Return the Wrong Datatype

If the Function is typed int, we gotta return an int. If it’s typed Array, we gotta return an array. Here’s an obvious boob:

function iAmConfused() : int
{
    return "nyearrrghhh";
}

This Function is typed int, but we’re returning a String. Here’s the Flash error:

Scene 1, Layer ‘Layer 1′, Frame 1, Line 3 1067: Implicit coercion of a value of type String to an unrelated type int.

Nice and clear. And in Unity javascript:

Assets/NewBehaviourScript.js(3,12): BCE0022: Cannot convert ‘String’ to ‘int’.

These are both very similar, and they do a pretty good job at getting the point across.

4. Faulty Logic

If you write a Function that should return a value, and you load it up with branching conditional logic, the compiler will actually step through that logic to make sure a value gets returned. Here’s an example of a logic structure that may never return the value promised by the Function:

function badLogic(playerName : String) : String
{
     if(playerName == "Pete")
     {
          return "Hi, Pete!";
     } else if(playerName == "Carl") {
          return "Hi, Carl!";
     }
}

So if the playerName is Pete, we return “Hi, Pete”, and if the playerName is Carl, we return “Hi, Carl”. But what if the playerName is Suzie, Jasmine, Turk, Paolo or Ferdinand? In that case, neither of the statements will get executed, and so it’s possible that the Function will not return a value.

Here’s what the Actionscript 3 compiler has to say about that:

Scene 1, Layer ‘Layer 1′, Frame 1, Line 9 1170: Function does not return a value.

Clear as crystal! And now, Unity javascript:

(no error)

Hmm. Now we’re up against a situation where permissive coding isn’t always a good thing. As a very new programmer, you might think “the fewer errors, the better”. But if you’re expecting that Function to return a value, and it somehow doesn’t, wouldn’t it be more helpful to see an error telling you what went wrong?

Answer: yes. Yes it would.

Your Triumphant Return

Those are the essentials of writing Functions that return values. Together with Understanding Functions and Understanding Functions – Arguments, you should have a complete picture of what Functions are and what they can do. But this is the HOW, not then WHEN of it. These articles just discuss the building blocks of Object-Oriented Programming. Assembly instructions, and even freestyle building – are entirely different matters altogether.

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

In Understanding Functions, we learned that Functions are a way to bundle code statements together into a tight little unit that we can invoke (or “call”) any time we like, and as often as we like. There are two very important features to learn about Functions: Arguments and Return Values. We’ll figure out Arguments in this article.

Til You’re Blue in the Face

Arguments aren’t as unfriendly as they sound. They’re just additional pieces of information we can send to a Function during a Function call. You’ll remember that a Function call looks like this:

doSomething();

Quite often, we need to pass additional information to Functions to make them super-useful. Let’s imagine we have a text input field where the player can enter his name. The player types in his name and clicks a button, and the game says “Hello, John” (or whatever the player’s name is). The dynamic, or changing, part of that Function is the player’s name. Here’s how that Function might look if it was “hard-coded”:

function sayHello()
{
    trace("Hello, John.");  // ain't nothing dynamic about this
}

Note: Unity javascript people will want to start the function name with a capital letter as a best practice, and use either print or Debug.Log in place of trace.

This is okay, but the problem is that every time we call (run, execute, do) that Function, it’s going to say “Hello, John.” What if the player’s name isn’t John? Well, we need to make that part dynamic, because it changes.

Dynamic!

Let’s set up our Function so that we say “Hello”, and then tack on a variable that holds the player’s name:

function sayHello()
{
    trace("Hello, " + playerName);
}

(When working with Strings, the + operator glues two strings together.)

It’s getting better, but we have a new problem: the code interpreter is going to see playerName and think “playerName? What the heck is that?” Then it’s going to freak out and the Earth is going to crash into the Sun, and we don’t want that.

We need to declare and define the playerName variable somewhere. But instead of just declaring playerName any old place, we’re going to tell the sayHello Function which playerName we’d like it to say. We’re going to set our sayHello Function up so that it has a parameter. We do that between the round brackets in the Function declaration:

function sayHello(playerName : String)
{
    trace("Hello, " + playerName);
}

Parameters go between the round brackets in a Function declaration. In the continuing tradition of seeing our blocks of code as visual elements, check this out:

When we structure a Function this way, we say that the sayHello Function accepts one parameter, which is called playerName. The type of playerName is a String (a list of letters and/or numbers). Notice that even though this is kind of like a variable declaration, we don’t need to use the var keyword.

Exact Change Required

i like to think of parameters as the payment that a Function accepts. The sayHello Function takes one argument and stores it in its first parameter. Since the first parameter is of type string, we need to “pay” it a string. If we pay any other datatype (int, float, number, boolean, array), the compiler will throw an error.

Here’s how we “pay” a string to the sayHello Function:

sayHello("Murphy");

Freeze frame! Let’s become the Pac Man-like code interpreter and follow the logic of this statement for a moment.

The interpreter gets to this line and recognizes it as a Function call, thanks to those round brackets at the end.

It also sees – hey! – the programmer has passed an argument to the Function inside those round brackets. So Pac Man puts that in his suitcase, hops in the DeLorean, and travels off in search of the sayHello Function.

When he finds it, before he starts chewing through the statements in the statement block (between the curly braces), the Pac Man-like code interpreter drops off the argument into the waiting playerName parameter bucket, between the round brackets of the Function declaration.

Now the parameter called playerName has a value of “Murphy”. Since “Murphy” is a String, and since the sayHello Function demands exact change (one argument of type String), we’re good to go!

With payment resolved, the code interpreter chews through the statements in the statement block (between the curly braces), reaches the bottom of the Function, and hops back in the DeLorean to pick up where he left off, back at the end of the Function call.

Because the value of the variable playerName is the String “Murphy”, the result is that the console/output window says Hello, Murphy. It will say Hello to whatever name we pass in as an argument.

Breakamage Pt.1 – Wrong Datatype

It’s really important to break code and cause errors, so that when you’re in a jam on a project and an error comes up, you’ll know what it means and how to deal with it.

Try tweaking the sayHello Function call so that you pass an int (integer/whole number) instead of a String:

sayHello(42);

42 is not a String. Your first clue is that it’s missing those double-quotation marks around it. Since the sayHello Function DEMANDS exactly one string as payment, the compiler throws an error.

This is what that error looks like when we use ActionScript 3:

Scene 1, Layer ‘Layer 1′, Frame 1, Line 1 1067: Implicit coercion of a value of type int to an unrelated type String.

i really take exception to the way eggheads write error messages. They could stand to be a LOT more clearly written. But here’s what this error is trying to say: “implicit coercion” means you’re trying to force something to be something else, and ActionScript 3 can’t manage it. In this case, you’re trying to force an int (42) to become a String when Pac Man delivers the goods to the sayHello Function, and the compiler is having a minor freak-out. That’s your clue that you may have passed a mismatched type as an argument to a Function.

This is the error message that the same mistake will cause in Unity javascript;

Assets/NewBehaviourScript.js(4,10): BCE0017: The best overload for the method ‘Tutorial.sayHello(String)’ is not compatible with the argument list ‘(int)’.

Ugh! You eggheads are killing me. Forget what an “overload” is and focus in on the part that (sorta) makes sense to you right now: something is not compatible with the argument list. You can see quite clearly that one is a String, and the other is an int. That’s your clue that you’ve botched the argument type. Go back and patch this up, and you’ll be golden.

Extremely Argumentative

So is that it? Can Functions only accept one argument? No … they can actually accept multiple arguments. Be sure to comma-separate them, like this:

makePizza("pepperoni", "mustard", "tree bark");
 
function makePizze(topping1 : String, topping2 : String, topping3 : String)
{
 
}

B..but … do they all have to be the same datatype (String)? Heck no! You can mix and match. The only rules are that you need to pass the arguments into the Function in the same order as the parameter list, and you need to pass the same number of arguments the Function requires. The Pac Man-like code interpreter unpacks these one at a time in order. So let’s pretend there’s a function that takes a String, an int and an Array (in that order):

function initPatient(patientName : String, age : int, aPhobias : Array)
{
 
}

As long as we pass in a String, an int and an Array, in that order, it works:

var theName : String = "Shaggy";
var theAge : int = 17;
var aThePhobias : Array = new Array("like, ghosts", "like, zombies", "like, creepy-crawly things");
initPatient(theName, theAge, aThePhobias);

That’s fine. But as soon as we mix up the order, there’s trouble:

var theName : String = "Shaggy";
var theAge : int = 17;
var aThePhobias : Array = new Array("like, ghosts", "like, zombies", "like, creepy-crawly things");
initPatient(theAge, theName, aThePhobias);
 
// ERROR!  Totally long-winded explanation that could really be made a lot more clear, but eggheads aren't about making other people's lives easier (unfortunately).  In short, argument type mismatch.

So far so good? You may have noticed that i made the names of the variables i passed into the Function as arguments conspicuously different than the names of the parameters i accepted in the initPatient Function. This is because i wanted you to see that there is a difference between these two things, and that there CAN be a difference. When you call a Function and pass it some arguments, the variable names you pass in don’t matter … it’s the values stored in those variables that Pac Man takes with him on his journey.

Breakamage Pt.2 – Wrong Number of Arguments

Just as sending in the wrong type of argument will throw an error (ie paying a quarter when the Function wants a nickel), the compiler will throw an error if you pass in the wrong number of arguments.

In this example, we have a Function that accepts one argument, but we try to pass it two arguments:

function eatBacon(numberOfStrips : int)
{
    trace("OM NOM NOM!  I just ate " + numberOfStrips + " strips of delicious bacon.");
}
 
eatBacon(57, "i can haz heart attack"); // ERROR!!

The function wants only one argument, but we’re sending it two. Here’s what the error looks like when we use Actionscript 3:

Scene 1, Layer ‘Layer 1′, Frame 1, Line 6 1137: Incorrect number of arguments. Expected no more than 1.

Thankfully, this is one of the clearest error message i’ve ever seen an egghead write.

This is what the error looks like when we use Unity javascript (changing trace to either print or Debug.Log and using a capital letter to begin our Function name):

Assets/NewBehaviourScript.js(8,9): BCE0017: The best overload for the method ‘NewBehaviourScript.eatBacon(int)’ is not compatible with the argument list ‘(int, String)’.

That’s the same error we get when there’s an argument type mismatch, so the Actionscript eggheads did a slightly better job of communicating the problem than the Unity eggheads did. The important thing is that you learn to recognize why Unity or Flash are throwing the error so that you can fix it quickly and get on with your project.

Note that you’ll throw an error even if you “overpay” a Function. If a Function wants exactly two arguments, and you give it nine, you’ll get one of these errors.

But Wait – There’s More!

There are two more advanced topics when it comes to passing and accepting arguments – optional arguments, and Rest arguments. They’re useful, but not crucial. We’ll be sure to cover them in future articles.

For now, get some practice passing arguments to your Functions, and writing parameters to store those articles. The fate of the free world may depend on it! Or whatever.

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

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.

Now that we understand loops, and we understand arrays, we’re ready to smack their featureless plastic genitals together like we’re making Barbie have babies.

Arrays really come alive with Loops. By using an Array’s length property as the loop limiter, we can step through every element in an Array one by one.

Here’s what that looks like in code:

var myArray:Array = new Array("Nigel Tufnel", "Derek Smalls", "David St. Hubbins");
 
var i:int =0;
for(i=0; i<myArray.length; i++)
{
    trace(myArray[i]); // This prints each element in the array, one by one, to the console/output window 
}

Note: If you’re using Unity javascript, try print or Debug.Log instead of trace.

If you truly understand Loops, this shouldn’t be too challenging for you. Instead of using some arbitrary value like one thousand as our limiter, we’re using the array’s length property, which is the number of elements in the array. This property is dynamic, so that any time we add things to our array, or take them away, length is updated for us. We don’t have to rely on a hard-coded value (which means a number that doesn’t change).

The code snippet shown above traces out each element in the array, one after the other:

• Nigel Tufnel
• Derek Smalls
• David St. Hubbins

This is because on every iteration of the loop, our iterator variable called i is increased by one.

i begins life with a value of 0. On the first run through the loop, the code interpreter resolves myArray[i] to myArray[0]. The first element in the array, at index 0, is “Nigel Tufnel”, so that’s what you’ll see in the output console.

On the next iteration, i gets jacked up to 1. The element at index 1 in the array is “Derek Smalls”, so that’s what prints out.

Finally, in the third and final round, we print out “David St. Hubbins”, because myArray[i] resolves to myArray[2]. The element at index 2 of the array is “David St. Hubbins”.

After that, the interpreter bounces back to the top of the loop. i is incremented to 3. We check the limiter:

i < myArray.length

Because i is 3 and myArray.length is also 3, this line resolves to 3 < 3. Since 3 is not less than 3, the answer here is false. And because the answer is false, the code interpreter is not allowed to go through the loop any more. It happily exits the loop and starts chewing through the code beneath the bottom closed curly brace that ties up the loop.

Protip: If you’re a stickler for speed, it’s marginally faster to store myArray.length in a variable, to prevent your interpreter from having to do the length calculation on every iteration of your loop. Here’s what that looks like:

var myArray:Array = new Array("Nigel Tufnel", "Derek Smalls", "David St. Hubbins");
 
var i:int =0;
var len:int = myArray.length;
for(i=0; i<len; i++)
{
    trace(myArray[i]);
}

We store myArray.length in a variable called len, and then refer to that variable in the limiter section of the loop header.

For even more of a tiny speed increase, do away with the new keyword and declare the array like this:

var myArray:Array = ["Nigel Tufnel", "Derek Smalls", "David St. Hubbins"];

Who Cares?

This is all still pretty pointless. When are you ever going to use this when programming a game? Well, for the rest of the article, i’ll lay some real-world examples on you to give you an idea of how to maximize the wonderful union of Loops with Arrays.

Think of any situation in a video game when you have a list of similar things. In a first person shooter, you need to keep track of all the bullets that get fired. Makes sense to create an array to store all of those bullets. You can add bullets to the list and remove them from the list using the Array class methods we looked at in the Understanding Arrays article.

Most games run on one giant loop, with an Update process and a Draw process. Update figures out where everything should be, and Draw renders those things to the player’s view. If you want to update the positions of all the bullets, you may need to use a For Loop to loop through your collection of bullets and move them one tiny bit. Then in the Draw process, you loop through your list of bullets and render them to the screen. When you repeat these processes quickly enough, you get the illusion of animation.

Very often, you’ll use a loop to create the initial array of objects, and then more loops later to pick through that list. Here’s an example of two functions. One initializes all of the monsters, and the other kills all of the monsters (assuming the player just used the “Kill All Monsters” megabomb power-up).

var aMonsters:Array; // this array is a bucket that can hold many things: namely, monsters.
 
function initMonsters():void
{
     aMonsters = [];  // Defines an empty instance of the Array class.
     var totalMonsters:int = 50; // this is a variable (bucket) that contains the number of monsters we'd like to begin with
     for(var i:int = 0; i<totalMonsters; i++)
     {
         aMonsters.push(new Monster()); // Creates a new instance of the Monster class, and adds that instance to the aMonsters array.  
         // If that's confusing to you, we can split this up into two separate lines:
         // var monster:Monster = new Monster();
         // aMonsters.push(monster);
     }
}
 
function killAllMonsters():void
{
     var len:int = aMonsters.length; // store the length of the aMonsters array in a variable called len.
     // By doing this, we speed up our loop ever so slightly.
     for(var i:int = 0; i<len; i++)
     {
         var monster:Monster = aMonsters[0]; // stores a reference to the first monster in the array
         monster.die(); // calls some sort of death method on the monster instance
         aMonsters.shift(); // removes the first element of the array.  The aMonsters array gets shorter and shorter every time we loop, as we remove monster after monster.  By the end of this loop, the aMonsters array is empty.
     }   
}

Note: If some of the initialization stuff here looks a bit spooky, try reading the Understanding Classes series. Hopefully you’re catching what i’m throwing regarding loops and arrays, even if the class stuff is a little unfamiliar.

For Unity javascript: Everything here is almost identical … the main difference is that methods like push begin with capital letters.

Those double-slashes, by the way, are comments. They are ignored by the compiler, and are added to clarify the code.

Get Carded

Here’s another example. Let’s say we’re programming a card game. We can use an array to store our deck of cards. Each element in the array is a card. We use one loop to build the deck. Then we shuffle the deck. Finally, we use a loop to deal some cards onto the table, using the Array.shift() method to deal off the top of the deck. This removes the cards from the array one by one, and adds them to a different array called aCardsOnTable.

var aDeck:Array; // declare an array to hold all the cards
var aCardsOnTable:Array; // declare an array to hold the cards that we deal out
 
function buildDeck():void
{
    aDeck = []; // create an empty instance of the Array class and store it in a variable called aDeck
    var totalCards:int = 52; // we want 52 cards in the deck, so that's how many times we'll loop
    for(var i:int=0; i<totalCards; i++)
    {
         aDeck.push(new Card()); // we instantiate the Card class, and add the new card instance to the aDeck array.
         // Once again, if we're doing too much in this line for you to follow along, here's a longer version of the same code in two steps:
        // var card:Card = new Card(); // create the card instance and store it in a variable
        // aDeck.push(card); // add the card instance to the aDeck array
    }
    shuffle(aDeck); // this is a custom function that you'll probably have to write yourself (just like the Card class).  It randomizes all of the elements in the array.
}
 
function dealCards():void
{
    aCardsOnTable = []; // define aCardsOnTable as an empty array
    var numCardsToDeal : int = 5; // Let's deal 5 cards to the table.
    for(var i:int=0; i<numCardsToDeal; i++)
    {
         aCardsOnTable.push(aDeck.shift()); // pulls the first element out of aDeck, and adds it to aCardsOnTable
         // That's a bit of shorthand.  Let me blow that line out into separate steps in case you're having trouble following it:
         // var topCard:Card = aDeck.shift();  // use shift to pull out the first card in the aDeck array, and store it in a variable called topCard
         // aCardsOnTable.push(topCard); // add the card we removed to the end of the aCardsOnTable array.
    }
    // When we finish with this loop, there are 5 cards in the aCardsOnTable array,
    // and 47 cards left in the aDeck array.
    // This is a great way to deal out cards!   By removing a card from the aDeck array each time using shift(), we ensure that we'll never deal the same card twice.
}

Those previous two examples are very similar. Here’s another real-world example that’s slightly different.

Looping Through Movieclips on the Stage

Super eggheads like to lay out their GUIs (graphical user interfaces – buttons and windows and text boxes and junk) entirely in code. i don’t prefer to do it that way, because i’m a very visual person, and i like to see my interface laid out on-screen. i like to be able to poke, prod and nudge things around visually.

So often, i’ll have a bunch of buttons on the stage. The buttons all have instance names. i’ll put those instance names in an array, and then loop through the array to add standard buttonMode, rollover and rollout effects to all the buttons in one shot. Here’s how that looks, presuming i have the buttons “phyiscally” on my stage and named properly:

 
 
// i call the initBtns function somewhere in my code
 
function initBtns():void
{
    var aBtnNames:Array = ["btnPlay", "btnQuit", "btnCredits"]; // we store the instance names of my on-stage buttons in an array
 
    var len:int = aBtnNames.length; // Let's dynamically loop through as many buttons as we have in the array.
    for(var i:int=0; i<len; i++)
    {
         activateBtn(this[aBtnNames[i]]);
         // Here's a slower, possibly clearer way to say that:
         // var btnName:String = aBtnNames[i]; // Refers to the i'th element of the array
         // var btn:MovieClip = this[btnName] // Refers to a movieclip instance on stage with that name
         // activateBtn(btn); // Passes the reference to that button to the activateBtn function
    }
}
 
function activateBtn(btn:MovieClip):void
{
     // This is standard stuff i want all of my buttons to do:
     btn.buttonMode = true;
     btn.mouseEnabled = true;
     btn.mouseChildren = false;
     btn.addEventListener(MouseEvent.MOUSE_OVER, rollOverBtn);
     btn.addEventListener(MouseEvent.MOUSE_OUT, rollOutBtn);
}

Of course, an even better way to handle this button situation is to create your own custom button class, but we’re taking baby steps here. That’s the thing about code – these pieces we’re learning are like Lego blocks. There are tons of different ways to build a sculpture out of Lego. There are no “right” ways – only preferred ways. Use this Understanding … series to get a grip on all the blocks you have to play with, and then … it’s time to play!

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

If a variable is a bucket that can hold one thing, an array is a superbucket that can hold many things.

The language you use determines what an array can hold. Certain languages will only let you put the same type of thing in your array superbucket – “this superbucket holds only screws”, or “this superbucket holds only issues of Playboy from 1972-1981″. Actionscript 3 lets you mix it up, putting anything you want in your array – including other arrays!

Creating an Array of Your Own

Let’s start simply. To get an instance (copy) of AS3′s built-in Array class that you can play around with, use the new keyword:

var myArray:Array = new Array();

This line of code means that we want to reserve a place in the computer’s memory to store something. The name of that thing is myArray. The type of that thing is an Array. We’re setting the value of that thing using the = operator. We use the new keyword to get a copy of the Array class, and specifying Array() is how we do it, building our new Array instance from the Array class’s constructor function. The semi-colon is like a period ending the statement.

Be sure to check out our Understanding Classes tutorials to learn more about constructor functions.

Once we’re done, we have an instance (copy) of the Array class called myArray that we can mess with.

Filling the Superbucket

Now that we’ve declared our array, let’s define it by adding some elements to it. We’ll throw in a few strings, which are datatypes surrounded by quotation marks.

myArray = ["wookie", "ewok", "sarlac"];

We use those square brackets a lot when working with arrays.

Now the array instance has three elements in it. They’re all string literals, but they could be a mix of things – numbers, ints (whole numbers), booleans (these are like lightswitches – on or off), or other arrays.

Peering Into the Superbucket

In order to find out what’s in our array, we use the name of the array followed by two square brackets, and the number of the element we want to know more about. A semi-colon ends the line, like so:

myArray[2];

Just typing that up won’t do anything, though. The Actionscript interpreter figures out the answer, and keeps it to itself. We need to use the built-in trace function to get Flash to report the value to us in the Output window.

trace(myArray[2]);

The answer is “sarlac”. Surprised? Arrays are zero-based, which means you start counting from zero. So element 0 is “wookie”, element 1 is “ewok”, and element 2 is “sarlac”.

Changing the Contents

If we wanted to put something at the end of this array, we could just be direct about it:

myArray[3] = "taun taun";

Now the array is four elements long: “wookie”, “ewok”, “sarlac”, “taun taun”. In fact, if we just trace out the name of the array, that’s what the Output window will report to us. Give it a try:

trace(myArray);

We can knock an element out and replace it with something else just as directly:

myArray[0] = "hutt";

By directly accessing element 0, we’ve knocked out “wookie” and replaced it with “hutt”. Poor wookie.

The Array Class and its Toys

The Array class gives us a bunch of goodies to play with. Like any class, it has methods (things that it does) and properties (things that it is or has).

Many of the Array class’s methods (things that it does) help us to put new things into the array at specific points, and pull things out of the array. Here are a few examples:

Array.pop(); removes the last element from the array
Array.push(); adds an element to the end of the array
Array.shift(); removes the first element and shifts everything back by one
Array.unshift(); adds an element to the beginning of the array and shifts everything ahead
Array.splice(); lets you specify an index point and a length so you can laser-cut elements out of an array and, if you wish, replace the removed elements with new ones. It’s like open-heart surgery for arrays.

One of the most commonly-used properties (things that it is/has) of an array is length, which just reports how many elements are in your array. So far, myArray.length is 4. You can see this by tracing out your array’s length property:

trace(myArray.length);

Notice that no round brackets are required. You need to use those round brackets for methods, not properties.

Using the Toys

So if we wanted to add a Gungan to our array (for some ungodly reason), we could use the Array class’s push method, like so:

myArray.push("gungan");

Now, myArray.length is 5 – “hutt”, “ewok”, “sarlac”, “taun taun”, “gungan”. Let’s get the wookie back at the beginning of the list by using the unshift method:

myArray.unshift("wookie");

Now, myArray.length is 6. Here’s what myArray looks like: “wookie”, “hutt”, “ewok”, “sarlac”, “taun taun”, “gungan”.

Performing Open-Heart Surgery on an Array

Finally, we’ll decide to get the ewok out of there using our surgical splice method. Splice wants to know where we want to start cutting, how many elements we want to remove, and which elements (if any) we want to insert into the array. Let’s keep it simple, and kill off the ewok for now.

The ewok is sitting at index 2, if we count from the beginning starting at zero. So we tell the splice method that we want to start hacking and slashing at index 2, for a total of 1 elements:

myArray.splice(2,1);

Now when we trace the array, the ewok is gone: “wookie”, “hutt”, “sarlac”, “taun taun”, “gungan”. (Note that when you actually trace out your array, the Output window leaves out the string quotation marks … i’ve left them in here to remind us that we’re working with strings, not variable names.)

What if we wanted to remove the hutt and the sarlac? We’d tell the splice command to start at index 1, which is where the hutt is, and remove two elements, like this:

myArray.splice(1,2);

That means “start at element 1, and remove two elements.” So our array is now “wookie”, “taun taun”, “gungan”.

Finally, we’ll use splice to get rid of that taun taun, and throw some invasive Star Trek races into the mix:

myArray.splice(1,1,"vulcan", "klingon", "tribble");

Now, we trace out the array and we get “wookie”, “vulcan”, “klingon”, “tribble”, “gungan”. That’s because we told splice to start at index 1 (which is where taun taun was), remove one element (namely, taun taun), and insert those three other species/races at the incision point. The transplant was a success, doctor!

How Does This Help Me Build Games?

Admittedly, this all seems pretty pointless when you don’t have a real-world code example. But arrays don’t really come to life until you learn one of the other basic programming elements: loops. In the next tutorial, Understanding Loops, we’ll break down the basic structure. Then in Understanding Loops with Arrays, we’ll see how they play together. Finally, i’ll throw you a few real-world code examples of how i use loops and arrays to code different pieces of my games that you can learn to use in your own projects.

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

For Spellirium we had to develop a system that could determine the most efficient path between a series of nodes on a point. After some diligent research and careful consideration it became clear that the A* search algorithm was the way to go.

Now, I was familiar with the basics behind A* but had never actually implemented it. Thankfully though I had a copy of Keith Peter’s Advanced ActionScript 3.0 Animation which has a very nice chapter all about path finding and A*.

Before we begin, some prerequisite knowledge is required. In order to follow along with this you should have a knowledge of AS3 Classes and Interfaces. It is certainly possible to implement A* without knowledge of these concepts but in order to build a flexible, reusable solution, we will be using both. Check out our Understanding Classes in AS3 tutorials if you need help getting up to speed.

What is A* path finding?

According to the ever-so-useful Wikipedia, A* path finding can be described as:

(A) computer algorithm that (finds an) efficiently traversable path between points, called nodes…. A* uses a best-first search and finds the least-cost path from a given initial node to one goal node (out of one or more possible goals).

Sounds nice, but what does this mean? It means that A* chooses a node (or tile in a tile based world) searches through all the directly connected nodes and calculates a cost to travel to all of them. It then selects the node that has the lowest cost and uses it as the starting node for the next phase of the search. A* continues to do this until it reaches the destination.

To implement the algorithm it is first important to understand a few concepts:

• Node: This is a point along a path. In a tile-based environment you can think of it as a tile. The reason why we don’t call it a tile is because it can be used for non-tile based worlds. You will provide A* with a starting node and ending node. A* will then calculate all the nodes to get from the start to the end.
• Parent Node: When a node is tested in the algorithm all of its directly connected nodes (nodes that are traversable in a single step) are assigned that node as their parent. By doing so, we can easily work backwards through all of the parent nodes to create our path after we reach the destination node.
• Cost: Cost is assigned to each node based on two factors. Nodes with a lower cost are used over nodes with a higher cost. The two parts that make up the cost are: the cost to get to that node from the starting node and the estimated cost to get from that node to the end node. The cost of a node is usually expressed via 3 variables f, g and h.
• g: This is the cost to get to this node via the starting node. We know this value exactly because we can follow the parent nodes all the way to the start and add up their costs.
• h: This is the cost to get from this node to the final node. This value is estimated. It is not exact because we don’t know the path that we will take to get to the final node. Therefore we must estimate the cost and we do so using a function called a heuristic.
• f: This is the total cost of the specific node – it is calculated by adding g + h.
• Heuristic: This is the function that estimates the cost of getting from a particular node to the end node. The beauty of A* is that it supports a variety of heuristics, therefore you can try out different ones until you get the result you are looking for. Heuristic functions can differ based on their speed, efficiency and a variety of other criteria.
• Open list: This is a list of all the nodes that have been visited (in an iteration of the search) and have been assigned a cost. The node that has the lowest cost will be used to perform the next iteration of the search.
• Closed list: This is the list of nodes whose neighbors have been visited.

The Algorithm

Now that is out of the way we can move on to the actual algorithm. Before we actually begin coding, let’s just take a look at how A* actually works.

1. Provide a starting node and an destination node
2. Add the starting node to our open list (which should have been empty)
3. Start our search loop:
   • a. Pick the node currently in the open list with the lowest cost – we will call this node the current node. When we first run the loop this will obviously be our starting node.
   • b. If the current node is the same as the destination then we are done and we can move on to step 5.
   • c. Check every directly connected node. In a tile based world this would be up to 8 tiles. For our implementation we will provide a function that determines all the connected nodes. For each node that is connected:
     • i. If the node is not traversable (you can’t move to it because it Is occupied or for some other reason) or the node is already in the open list or in the closed list we can skip and move on to the next node in the list of connected nodes. Otherwise continue to ii.
     • ii. Calculate the cost of that node.
     • iii. Set the current node as the parentNode.
     • iv. Add the node to the open list.
   • d. Add the current node to the closed list.
4. Now return to step 3 (loop again) with the newly updated open list. (The loop should keep running until it hits the destination node)
5. We have found the destination node (hurrah!) Now we create a list of nodes that will be our path list and we will add the destination node to that list.
6. Add the parent node of the destination node to the path list.
7. Add the parent of the previous node to the path list, we will continue to do this until we have added our starting node.

We should now have a list of all the nodes that make up the best path from our starting node to our destination node.

The Implementation

Now that our theory is out of the way, let’s start writing some code. First we will start with our Node class. For this I will actually create an interface for your node:

public interface INode
{
	function get f():Number;
	function get g():Number;
	function get h():Number;
	function get x():Number;
	function get y():Number;
	function get parentNode():INode;
	function get traversable():Boolean;
	function set f(value:Number):void;
	function set g(value:Number):void;
	function set h(value:Number):void;
	function set parentNode(value:INode):void;
	function set traversable(value:Boolean):void;
}

This is a pretty straight-forward interface. It includes the variables for all the properties we discussed above (f,g,h and parentNode ). The other variables are fairly self-explanatory. X and Y obviously indicate the position of the node. We will use these values in our heuristic to estimate the cost of traveling from the node to the destination. The traversable variable is a simple Boolean that indicates if the node can be used in our path finding. If it is not then the algorithm will simply skip it when it is encountered. This is useful in a world where a node might be occupied by a prop (say a rock, tree or wall) or if there is another player/character occupying that space and you don’t want to support multiple characters on a single node. Implementing this in a class should be very easy.

Now we will build a class called Pathfinder. We will create the class only using static methods. Hopefully this will make it very flexible. It will not take much to turn this into a standard class but for our purposes static methods will do very well.

public class Pathfinder
{
	public static var heuristic:Function = Pathfinder.diagonalHeuristic;

Here, we define the heuristic function we will use to estimate the cost of traveling from a node to the end. In this example we will use the diagonal heuristic. At the end of this article, we will discuss some other heuristics and how to implement them.

Let’s move on to our actual path finding function:

public static function findPath(firstNode:INode, destinationNode:INode, connectedNodeFunction:Function ):Array 	{

Let’s examine the parameters:

• firstNode: INode – this is the first node in our path
• destinationNode: INode – The is the node that we are going to be traveling to
• connectedNodeFunction:Function – This is a function that will return an array of nodes that are connected to a given node.

Since each implementation might be different we abstract it out this way. After we write our class I will use a tile- based example to illustrate how this works, but your method might be different.

Lastly, the function returns an Array. This will contain all the nodes along the path.

Variable Setup

So now that is out of the way let’s do some initial work:

var openNodes:Array = [];
var closedNodes:Array = [];
var currentNode:INode = firstNode;
var testNode:INode;
var connectedNodes:Array;
var travelCost:Number = 1.0;
var g:Number;
var h:Number;
var f:Number;
currentNode.g = 0;
currentNode.h = Pathfinder.heuristic(currentNode, destinationNode, travelCost);
currentNode.f = currentNode.g + currentNode.h;
var l:int = nodes.length;
var i:int;

The first two arrays will hold our open nodes and our closed nodes. Then we have a variable currentNode which will keep track of the node we are currently on. We set this to be our firstNode since that is where we will start.

Next we keep a variable testNode:INode, which will be the node that will be a connected node of our current node.

Next we have g,h and f values we will keep track of for each node.

We then set the initial g value of the currentNode (which is also our first node) to 0 since it does not cost anything to get there since it is already our current location.

Then, we calculate the estimated cost to reach the end using our heuristic, and finally the final cost which is calculated by adding g + h (the starting cost plus the final cost).

Lastly, we have some variables that we will use inside of loops in our A* algorithm.

The Loop

Let’s move on to the actual loop.

while (currentNode != destinationNode) {
	connectedNodes = connectedNodeFunction( currentNode );
	l = connectedNodes.length;
	for (i = 0; i < l; ++i) {
		testNode = connectedNodes[i];
		if (testNode == currentNode || testNode.travesable == false) continue;
		g = currentNode.g  + travelCost;
		h = heuristic( testNode, destinationNode, travelCost);
		f = g + h;
		if ( Pathfinder.isOpen(testNode, openNodes) || Pathfinder.isClosed( testNode, closedNodes) )	{
			if(testNode.f > f)
			{
 
				testNode.f = f;
				testNode.g = g;
				testNode.h = h;
				testNode.parentNode = currentNode;
			}
		}else {
			testNode.f = f;
			testNode.g = g;
			testNode.h = h;
			testNode.parentNode = currentNode;
			openNodes.push(testNode);
		}
	}
	closedNodes.push( currentNode );
	if (openNodes.length == 0) {
		return null;
	}
	openNodes.sortOn('f', Array.NUMERIC);
	currentNode = openNodes.shift() as INode;
}

Whoa! There’s a lot going on there, so let’s try to break it down piece by piece.

while (currentNode != destinationNode) {

Start our loop. If our current node is the same as our destination then we are done and we can build our path!

connectedNodes = connectedNodeFunction( currentNode );
l = connectedNodes.length;
for (i = 0; i < l; ++i) {

So fetch an array of all of the connected nodes of our current node. Store the length and then loop through all of them.

testNode = connectedNodes[i];
if (testNode == currentNode || testNode.travesable == false) continue;

Test each node out of the connected nodes. If the node is the same as our current node or it is not traversable, move on to the next connected node.

Note: Your connectedNodeFunction might omit non traversable nodes which would make the above line redundant and unnecessary.

g = currentNode.g  + travelCost;
h = heuristic( testNode, destinationNode, travelCost);
f = g + h;

Ok, so now we are calculating the actual cost of our node. First, g:

g

In a tile based world, we simply add the cost of the currentNode to the travelCost to determine the cost of the tile. In some tile based environments, a diagonal move sometimes cost more than other moves. In this case you would need to determine if the testNode is diagonal to the currentNode and adjust the travelCost value accordingly.

In our case here at Untold, we had a situation where the cost of each connected node was not the same because the nodes could be spread out across variable distances. So in our case we changed the g calculation to use our heuristic between the currentNode and the testNode.

g  = currentNode.g + Pathfinder.heuristic( currentNode, testNode, travelCost);

Now, h:

h

This is where we use our heuristic. Our heuristic takes in our testNode and our destination node. We also supply the cost to the heuristic which will return a number. Again, we will go over the heuristic later.

f

Finally, we are at f. This is a straightforward calculation to determine the total cost of the node.

if ( Pathfinder.isOpen(testNode, openNodes) || Pathfinder.isClosed( testNode, closedNodes) )	{

Here, we use some simple utility functions to determine if the node is in either our open list or our closed list. If it is, then we should only adjust its f,g and h value if its current cost (f) is greater than the cost we just calculated.

	if(testNode.f > f){
		testNode.f = f;
		testNode.g = g;
		testNode.h = h;
		testNode.parentNode = currentNode;
	}else {
		testNode.f = f;
		testNode.g = g;
		testNode.h = h;
		testNode.parentNode = currentNode;
		openNodes.push(testNode);
	}

If the node is not in either the open list or in the closed list, then we definitely want to assign it the values we just calculated. We also want to add it to the list of open nodes and make sure its parent is set to our currentNode.

We are now done our loop and can add our currentNode to our list of closed nodes.

closedNodes.push( currentNode );
if (openNodes.length == 0) {
	return null;
}
openNodes.sortOn('f', Array.NUMERIC);
currentNode = openNodes.shift() as INode;

If there are no more open nodes, then no path is available between the provided nodes, so we return NULL.

Otherwise, sort our open nodes based on their cost and use the one with the lowest cost as our new currentNode.

If a path is available, the currentNode will eventually be the same as our destination node, and the while loop will exit. At this point, we will be ready to build our path and end our function which we do with a single line:

return Pathfinder.buildPath(destinationNode, firstNode);

Of course this means we need a function called buildPath(). Luckily, it is quite simple and looks like this:

public static function buildPath(destinationNode:INode, startNode:INode):Array {
	var path:Array = [];
	var node:INode = destinationNode;
	path.push(node);
	while (node != startNode) {
		node = node.parentNode;
		path.unshift( node );
	}
	return path;
}

In this function, we simply keep moving through all the parent nodes of the provided nodes and put them at the front of a new array we return to the caller.

The Heuristic

We are almost ready to test out our class with an example but as promised we will first discuss our heuristic.

There is a wide range of heuristics used to calculate an optimum path. The methodology is based on a variety of criteria. Different heuristics return different results and you will need to find the one that is best for your case. Right now, we’ll examine three simple heuristics, but don’t be afraid to go out and find your own.

Now, I was familiar with the basics behind A* but had never actually implemented it. Thankfully though I had a copy of Keith Peter’s Advanced ActionScript 3.0 Animation which has a very nice chapter all about path finding and A*.

Manhattan: This heuristic is the most simple. It ignores any diagonal movement, so if your world does not allow for diagonal movement it might be a good fit. It simply adds the total number of rows and columns between the two provided nodes.

public static function manhattan(node:INode, destinationNode:INode, cost:Number = 1.0):Number {
	return Math.abs(node.x – destinationNode.x) * cost + Math.abs(node.y + destinationNode.y) * cost;
}

Euclidian: This heuristic simply draws a straight line between the two provided nodes and returns its length. You might recall the Pythagorean Theorem from math class? Well, here it is in action.

public static function euclidianHeuristic(node:INode, destinationNode:INode, cost:Number = 1.0):Number {
	var dx:Number = node.x - destinationNode.x;
	var dy:Number = node.y - destinationNode.y;
	return Math.sqrt( dx * dx + dy * dy ) * cost;
}

Diagonal: This heuristic is the most accurate of the three. It is more complex than the previous two, but runs fewer times because of its accuracy. It takes into account a diagonal cost, if it is more expensive than a regular movement.

public static function diagonalHeuristic(node:INode, destinationNode:INode, cost:Number = 1.0, diagonalCost:Number = 1.0):Number {
	var dx:Number = Math.abs(node.x - destinationNode.x);
	var dy:Number = Math.abs(node.y - destinationNode.y);
	var diag:Number = Math.min( dx, dy );
	var straight:Number = dx + dy;
	return diagonalCost * diag + cost * (straight - 2 * diag);
}

Make it Go

Now that we are done with our pathfinding system, we can put it to work. Take a look at the example below. You can click on any two tiles in the grid and then we will then draw a path between the two tiles. You can change the heuristic at any point to see the different results you might get. Also highlighted are any tiles that the pathfinder tests. Notice that the Manhattan heuristic tests far more nodes than the other two.

I implement the pathfinding simply by calling the Pathfinder.findPath() function and passing the start node, end node and the function that determines connected nodes. I then pass the returned array to a function called drawPath. For your usage you probably want to do a lot more than draw a path, you probably want to have a character traverse along that path, but this is just meant to show you how to acquire which path to follow.

drawPath( Pathfinder.findPath(_startNode, _endNode, findConnectedNodes) );

The findConnectedNodes method is very straightforward. It simply returns all nodes that are adjacent to a given node. You can check it out here:

public function findConnectedNodes( node:INode ):Array
{
	var n:Node = node as Node;
	var connectedNodes:Array = [];
	var testNode:Node;
	for (var i:int = 0; i < _nodes.length; i++)
	{
		testNode = _nodes[i];
		if (testNode.row < n.row - 1 || testNode.row > n.row + 1) continue;
		if (testNode.col < n.col - 1 || testNode.col > n.col + 1) continue;
		connectedNodes.push( testNode );
	}
	return connectedNodes;
}

Of course, this implementation will not be sufficient if you want different tiles to have different costs based on terrain (quicksand might be more expensive than grass), but if you can grasp the above you should be able to make the adjustments fairly easily.

Hopefully you will now have a solid understanding of A* path finding and you can now use it in your own applications.

Click here to download the source code for this tutorial.

So while i’m getting to know and understand the best practices of Object-Oriented programming, there are still some tried-and-true methods of finishing work more quickly that don’t obey strict OOP protocol. What follows is a list of pragmatic programming tips – ways to bend the rules, or to leverage the visual tools in the Flash IDE – to speed things up, and to make life easier.

Cheat #1: The Injection Method

The fact that the programming eggheads, the nerderati, have coined a term for this strategy means it can’t be all that bad. The injection method breaks one of the pillars of OOP – encapsulation – but it’s a Hell of a time-saver.

Let’s say you’re building an adventure game. You have an Inventory class and your MainGame class. When the player combines the “dynamite” inventory with the “hammer” inventory item, that action might trigger a death animation. The way you’ve built it, your MainGame class handles all death sequences.

According to the eggheads, the “right” way to do this is for MainGame to instantiate Inventory. In order for Inventory to talk back to MainGame, it should dispatch a custom event, which MainGame listens for:

public class MainGame extends MovieClip
{
    public function MainGame()
    {
          var inventory:Inventory = new Inventory();
          inventory.addEventListener(Inventory.DEADLY_ITEM_COMBINATION, playDeathSequence);
    }
 
    private function playDeathSequence():void
    {
           trace("You have died, because i'm a lousy game developer and i couldn't
                         think of a creative way to solve this situation without screeching
                          the game to a dead stop.");
    }
}

Here’s what the Inventory class looks like:

public class Inventory
{
    public static const DEADLY_ITEM_COMBINATION:String = "deadlyItemCombination";
 
    public function Inventory()
    {
          // Setup stuff goes here - etc etc.
    }
 
    public function combineItems(item1:Item, item2:Item):void
    {
           if(item1.itemType == "hammer" && item2.itemType == "dynaimte")
           {
                 dispatchEvent(new Event(DEADLY_ITEM_COMBINATION));
           }
    }
}

i find it a very time-consuming process to set this up, especially if you need a lot of communication between the two classes. The other asspain is that you can’t specify which deadly item combination triggered the death sequence. What if there is a special death sequence for any dynamite-related inventory screw-up, and a different sequence for any misstep involving the bagOSnakes item? Sure, you can set up some kind of custom event class, but that takes even MORE time, and you’re on a deadline.

With the injection method, you pass a reference to the MainGame class into the Inventory class. Then Inventory can invoke any public methods and properties on MainGame. It breaks encapsulation, sure, but like i said, you’ve got until Friday to make this work, and you probably won’t end up reusing your Inventory class anyway. (Certainly not NOW, you won’t ;)

Here’s how it looks:

public class MainGame extends MovieClip
{
    public function MainGame()
    {
          var inventory:Inventory = new Inventory(this); // pass , or "inject", a reference to the 
                                                                // MainGame class to inventory
    }
 
    public function playDeathSequence(typeOfDeath:String):void
    {
          // inventory calls this public method on MainGame when the time is right 
           if(typeOfDeath == "dynamiteRelated")
          {
               // Play the dynamite death animation
          } else if (typeOfDeath == "bagOSnakesRelated") {
               // Play the bag o' snakes death animation
          }
    }
}

public class Inventory
{
    private var main:MovieClip; // A reference to the MainGame class
 
    public function Inventory(main:MovieClip)
    {
         this.main = main; // Set the instance variable main to whatever's passed into the constructor
    }
 
    public function combineItems(item1:Item, item2:Item):void
    {
           if(item1.itemType == "hammer" && item2.itemType == "dynaimte")
           {
                 main.playDeathSequence("dynamiteRelated");
           } else if (item1.itemType == "bagOSnakes" && item2.itemType == "tickleFeather") {
                 main.playDeathSequence("bagOSnakesRelated");
           }
    }
}

Of course, with anything in programming, there are many ways to skin a cat. If you only ever have one Inventory in your game, you might even make it a static class. The eggheads are going to crucify me for my abuse of the injection method, but that’s alright – i’ve got six dirt-cheap preschool games to build by Friday. i welcome crucifixion with open arms, as it were.

Cheat #2: Dispatching Events from the Timeline

The architects of Actionscript 3 pulled kind of a dick move by rendering the timeline incredibly difficult to deal with. One of the best things about Flash was the amount of complicated graphics and animation stuff it did for you right out of the box, but AS3 robbed us of productivity by making us write a lot of code when we shouldn’t have to.

This disadvantage rears its ugly head when you need to wait for a MovieClip to finish playing its animation. One way to deal with this is to listen to the clip’s ENTER_FRAME or EXIT_FRAME events, and wait until it hits its last frame:

var groovyMovie:GroovyMovie = new GroovyMovie();
addChild(groovyMovie);
groovyMovie.addEventListener(Event.EXIT_FRAME, checkCompletion);
 
function checkCompletion(e:Event = null):void
{
	 if(e.target.currentFrame >= e.target.totalFrames)
	 {
		 // MovieClip has reached the end of its timeline.
	 }
}

That’s fine. But what happens if the clip contains a number of separate animation sequences? You can write a conditional statement inside the checkCompletion() method that looks at the currentLabel property, but that makes your code even thicker:

var groovyMovie:GroovyMovie = new GroovyMovie();
addChild(groovyMovie);
groovyMovie.addEventListener(Event.EXIT_FRAME, checkCompletion);
 
function checkCompletion(e:Event = null):void
{
         var clip:MovieClip = MovieClip(e.target);
 
	 switch(clip.currentLabel)
         {
                case "finishedJumping":
                     doSomethingAfterFinishingJumping();
                     break;
                case "finishedGyrating":
                     doSomethingAfterFinishingGyrating();
                     break;
                default:
                     break;
         }
}

Putting code on the timeline is dirty and bad. Occasionally, i’ll throw in some timeline events (gotoAndPlay(), stop(), etc) but that’s the extent of it. Except in this situation. In this sitaution, if it helps speed things up, i’ll advocate slipping in a dispatchEvent() action on the timeline.

On the salient frame of GroovyMovie:

dispatchEvent(new Event("finishedGyrating"));

And here’s our modified code from elsewhere:

var groovyMovie:GroovyMovie = new GroovyMovie();
addChild(groovyMovie);
groovyMovie.addEventListener("finishedGyrating", doSomethingAfterFinishingGyrating);

No more messy switch statement and – maybe the eggheads can confirm or deny this – i think the code may speed up, because you’re no longer checking that conditional statement every frame. (i’ve never cottoned on to the inner workings of the virtual machine, so if i’m wrong about that, feel free to nerdspank me.)

Cheat #3: Positioning Markers on the Stage

One of the most difficult things about AS3 for me, a visual person, is that i suddenly have to lay visual elements like buttons and text fields out in code, instead of on the stage. You get a lot more control over your elements when you manipulate them with code only, and some stuff just downright doesn’t work unless you work solely with code.

What i can’t stand is not knowing where things are going to end up on the stage. i start by positioning something:

widget.x = 173;
widget.y = 221;

Then i compile. When the code places my element on the stage, i soon see it’s off by a longshot. So i go back to the drawing board:

widget.x = 192;
widget.y = 237;

Compile. Check. Damn – this time, i’ve overshot the mark. i repeat this process – set x/y, compile, check, close swf – until it’s in the right place. And then i do the same with some other element. It’s aggravating.

i’ve found one of the fastest ways to cut through this is to create an empty MovieClip in your library and call it “Empty”. Drag it out to the stage where you want the code-created element to exist. Give it the instance name “marker”, or whatever. Then in your code:

widget.x = marker.x;
widget.y = marker.y;

Later, if you find out you got it wrong, don’t painstakingly tweak the numbers in code. Just grab the marker instance and drag it somewhere else on the stage. Step 4: profit.

Cheat #4: Stealing Color Effect Data

i hope i’m not the only one, but classes like ColorTransform confuse the heck out of me. ColorTransform takes eight arguments:

ColorTransform(redMultiplier:Number = 1.0, greenMultiplier:Number = 1.0, blueMultiplier:Number = 1.0, alphaMultiplier:Number = 1.0, redOffset:Number =0, greenOffset:Number =0, blueOffset:Number = 0, alphaOffset:Number = 0)

Whenever i need a specific outcome from the ColorTransform class, i put a MovieClip on the stage and adjust the Color Effect properties in the Properties panel. If you choose “Advanced” and play with the dials, you may notice that there are eight different parameters you can tweak. These eight params map onto the eight arguments that the ColorTransform class expects.

Here’s the corresponding code, taken from the numbers on the dials. The offset parameters are percentages, so remember to divide the first four offset numbers by 100 (just throw a decimal place in front of them):

var ct:ColorTransform = new ColorTransform(.29, .38, .33, .77, 82, 3, 72, 51);

It’s not exactly a “cheat”, but it does get around this notion that we need to fight tooth and nail to imagine everything through code.

Cheat #5: Guided Layers

This last one is also less of a cheat, and more of a way to get stuff out of codespace and into the more visual Flash environment.

If you’ve ever had to open another programmer’s code and Flash file, you may have been faced with a blank screen. All of the elements are linked in the library, but you don’t know where they’re supposed to go or how they’re supposed to appear without compiling the movie. And if you’ve been hired to fix an incomplete project and the fla won’t compile, you could be in for a world of hurt.

This is usually the path you follow to figure out how the file’s been built:

1. Check for timeline code in the first frame.
2. Check for a document class.
3. Check the library for linkage names to see what gets added to the stage dynamically

In order to be kind to Future-Me, or to anyone who inherits my code if i get hit by a bus, i use guided layers. If you put something on a layer, and then right-click the layer and hit “Guide”, that thing won’t show up when you compile. It’s MUCH friendlier to open up a file and see elements on the stage, so you get some idea of what’s supposed to appear in the file, instead of seeing a blank screen.

Important note: If you put code on your timeline (and in nearly all cases, you shouldn’t), your code will still fire even if you Guide out the layer that it’s on.

Speed Kills

So those are a few ways that i “cheat” by leveraging the Flash IDE or using “good-enough” practices instead of “best” practices to speed through tight timelines. Do you have any less-than-perfect strategies to get around writing mountains of code, or to make things easier on yourself? i’d love hear them!

i’d look like a fool if i tried to write a tutorial at this point. So instead, i’ll share this list of translations of common Actionscript 3 coding tasks to the Unity3D engine’s JavaScript-like UnityScript language.

1. Render an Object Visible or Invisible

Actionscript 3:

thing.visible = true; // or false

UnityScript:

thing.renderer.enabled = true; // or false

2. Tint an Object

Actionscript 3:

var colorTransform:ColorTransform = new ColorTransform();
colorTransform.color = 0xFF0000;
thing.transform.colorTransform=colorTransform;

UnityScript:

thing.renderer.material.color = Color.red;

3. Get a Random Number

Actionscript 3:

var someRandomNumberBetween0And5:int = Math.floor(Math.random()*5);

UnityScript:

var someRandomNumberBetween0And5:int = Random.Range(0, 5);

4. Respond to a Key Press

Actionscript 3:

 
stage.addEventListener(KeyboardEvent.KEY_DOWN, doKeyDown);
 
private function doKeyDown(e:KeyboardEvent):void
{
	switch(e.keyCode)
	{
		case 32:
			// Space bar! Do stuff.
			break;
		default:
			break;
	}
}

UnityScript:

if(Input.GetKeyDown("space"))
{
	// Do stuff.
}

5. Open a Web Page

Actionscript 3:

navigateToURL(new URL("http://www.untoldentertainment.com"), "_self");

UnityScript:

Application.OpenURL("http://www.untoldentertainment.com");

Technical Correctness vs. Getting Sh*t Done

i’ve been really happy with the way this series has been received. If you’re like me, you’ve had a hard time understanding the big deal about OOP and Classes – you know it’s something you’ve got to bite the bullet and eventually learn, but it seems like a whole lot of extra typing for nothing.

But for those of us designers-turned-coders who have embraced Classes (or have been forced into using them for a paid project with a deadline), we’ll tell you that when written the “right” way, Classes can free you from writing a lot of code in your next project.

The trouble comes when you know so much about Classes that you write them too correctly. You can definitely spend too much time making a Class all things to all people and for all purposes. “It’s a MegaClass that can be an animated sprite AND a media player! It’s so VERSATILE!” Meanwhile, you either haven’t launched a game in a year, or your clients are calling every other hour wondering how their project is coming along.

Let’s Recap

In Understanding Classes Part 1, you freed yourself from the timeline. In Part 2, you took a little detour and learned how to piggyback your library to write custom MovieClip symbols using inheritance. In Part 3, you started looking at how code could be organized in separate files to keep your workspace light, and to better organize your work. Now let’s take a look at the next principle of OOP, encaspulation, to see if we can’t turn our Classes into true drag-and-drop Lego bricks.

Lego, Ikea furniture, and Your Code

Once again, the three principles of Object-Oriented Programming are inheritance, encapsulation, and polymorphism.

Think of your Classes as Lego bricks. You want to build a Media Player brick that works in your current project, that you can lift out and snap into your next project that requires a Media Player, with no extra work required. That’s the dream, anyway.

Up to this point, i’ve recommended that you make all of your Classes’ fields (things that a Class is) and methods (things that a Class does) public. Public variables and methods can be accessed by anyone and anything outside the Class.

Let’s look at some code. We have an ImageGallery Class and our Main Class. Main creates an instance (stamp, version, print) of ImageGallery and draws it to the screen using addChild:

package
{
	import flash.display.MovieClip;
 
	public class ImageGallery extends MovieClip
	{
		public var numberOfImagesICanDisplay:int = 5;
		public function ImageGallery()
		{
			// Display numberOfImagesICanDisplay
		}
	}
}

package
{
	import flash.display.MovieClip;
 
	public class Main extends MovieClip
	{
		public function Main()
		{
			var imageGallery:ImageGallery = new ImageGallery();
			addChild(imageGallery);
		}
	}
}

So far so good. But take a close look at that variable on ImageGallery:

		public var numberOfImagesICanDisplay:int = 5;

That field is declared public. That means that any idiot (including YOU) can access that field and change it. Let’s be a total jackwad and, from Main, change it to eight million:

		imageGallery.numberOfImagesICanDisplay:int = 8000000;

This messes up ImageGallery’s pyjama party to the very limit. How is ImageGallery supposed to display eight million photos? It’s only really set up to handle five images. There HAS to be a way to protect important variables like numberOfImagesICanDisplay from other ass-hat Classes like Main.

Stop Looking at My Privates

Fortunately, there is a better and less future-altering way. If we change public to private, only instances (copies, stamps) of the ImageGallery Class can read and write the value of that field. Hooray!

The way i suggested you write your Classes was completely backards. Public is the most permissive access modifier. Private is the least permissive access modifier.

The rule i’ve read is that you should always start out restrictive, declaring everything private, because once you go public it’s kinda hard to go back to private. (If you were an early bloomer in high school who “went public”, you’ll know how difficult it is to regain your privacy)

So declare everything – methods and fields/variables – private. If you find that any outside Classes need to access those methods and fields later, you can open them up by making them public.

What Should I Make Public?

Object-oriented programming eggheads are pretty particular about the kinds of things that should be public, and those that should be private. The example i’ve heard is to think of a device like a vending machine. There are certain client-facing input methods that need to be accessible to the outside world:

• insert coin
• push snack button
• push coin return button

And there are certain things the vending machine is going to return to the person using it:

• snacks
• coins
• error messages (“SOLD OUT”, INCORRECT CHANGE”, “NO CANDY FOR YOU, FATTY”, etc)

So the vending machine accepts input and dispenses output. Everything else is private. The user does not need to be able to control the coils that turn to dispense the snacks. The user has no business figuring out how to make change inside the machine, or managing the vending machine’s inventory of goodies. That’s all internal stuff. That’s private.

Dispatching Events

We already know how to write a public method on a Class, and we learned how to pass a parameter through to the Class. Here’s a snippet from an imaginary vending machine Class:

public function insertCoin(coin:Coin):void
{
	// Tally up the value of the coin that has been inserted
	switch (coin.type)
	{
		case "quarter":
			coinValue += 25;
			break;
		case "dime":
			coinValue += 10;
			break;
		case "nickel":
			coinValue += 5;
			break;
		case "penny":
			// No pennies!
			return coin(coin);
			break;
		default:
			break;
	}
}

And here’s an example of how you might call that function from outside the Class:

vendingMachine.insertCoin(new Quarter());

In Actionscript 3, the proper way to signal to the outside world that something important has happened inside a Class is to fire an even dispatcher. Here’s what that looks like in our imaginary vending machine Class:

// This line goes at the top of the Class where you declare your fields:
public static const RETURN_SNACK:String = "returnSnack";
 
// And then later, when you declare your methods:
private function returnSnack():void
{
	dispatchEvent(new Event(RETURN_SNACK));
}

And here’s how you listen for that event in the Main Class (or from whichever Class instantiates [makes a copy of] the vending machine):

// Make sure you import the generic Event stuff near the top of the file:
import flash.Events.event;
 
// This is what your instantiation and listener definition look like:
var vendingMachine:VendingMachine = new VendingMachine();
vendingMachine.addEventListener(VendingMachine.RETURN_SNACK, getASnack);
 
// And elsewhere, you define the method to respond to the event:
private function getASnack(e:Event)
{
	// HOORAY FOAR SNAKZ!!!
}

Anyone see a problem yet? i do. We’re not really able to pass a parameter back to Main through our dispatchEvent command. So how does Main know what kind of snack it received?

There are a few ways around this. We can store a variable on Main called requestedSnack and take it on faith that vendingMachine returns the correct snack. Or, we can create a public variable on VendingMachine to store the returnedSnack, and in Main’s getASnack method, we refer to vendingMachine.returnedSnack. And then there are super egghead ways to do it that remain mysterious to me.

Let’s Get Ready to Fudge It

But here’s the CHEATERPANTS way of doing things. Using dispatchEvent is nice, because we can plop this vending machine down in any other game or app and it WORKS. It’s encapsulated. There are no dependancies. We just need to listen to all of its dispatched events in the new file, and we’re gold. But to be honest, that’s a whole lot more typing, and i’ve got things to do.

The cheaty way to do it is to pass a reference to Main as a parameter to the VendingMachine Class:

// From Main:
var vendingMachine:VendingMachine = new VendingMachine(this);

// From VendingMachine:
public function VendingMachine(main:MovieClip)
{
}
 
// And then later in VendingMachine:
private function dispenseSnack(snack:Snack):void
{
	main.getASnack(snack);
}

Hooray! No need to listen for an event, dispatch an event, declare a constant, or tapdance around the return value problem. The vendingMachine instance knows who its daddy is, and can invoke any of Main’s public methods.

Of course, the drawback is that this breaks encapsulation. You can no longer pick up your VendingMachine Class and move it to a new project, because VendingMachine is dependant on receiving a reference to a Class that has a public method called getASnack() on it.

Here’s how i go about it: if i’m writing something that i think is pretty handy, and it’s abstract enough that i’ll likely use it in future projects, i might do the extra work to write a nicely encaspulated Class. But if it’s sunny outside and all the other kids are playing in the park, and i can hear their joyous squeals through my opened window, i’ll break encapsulation and throw my Class a reference to the Class that instantiated it.

Don’t Cry, Nerds

Dear Eggheads: i haven’t left you out this time. The concept of passing a variable to the constructor function of a Class was explained perfectly clearly here, i hope, but i know how you like to muck things up with big words and impressive terminology. Your term for this technique is “Dependency Injection”, and if you’d like to read a more serious article on it with fewer pictures and bigger words, check out Joel Hooks’s article AS3 Dependency Injection Demystified.

Here’s a solid step towards demystifying it: STOP CALLING IT DEPENDENCY INJECTION. Sheesh almighty.

To read the rest of the Understanding Classes series, or to see more tutorials, check out our Flash and Actionscript 911 feature.

Trial by Flash

This series of Understanding Classes tutorials chart my progress through unfamiliar Actionscript 3.0 territory. i am a designer-turned-coder, so everything i understand about code was learned in the School of Hard Knocks … most often while a producer breathed down my neck and i had two weeks to program a game using concepts i didn’t grok.

i had already learned to avoid “spaghetti code”, a common newbie Flash developer habit where you stick little bits of code on various MovieClip symbol instances and frames throughout your Flash movie. The next step was to round up all of those little bits of spaghetti code and confine it all to the first frame of my Flash movie.

The next leg of the journey into Actionscript 3.0 was to escape the first frame, and to move all of that first-frame code into its own seprate .as Class file. That’s where Understanding Classes began. It seemed like a pointless step – whether the code was in its own frame or in its own Class file seemed like picky Egghead semantics.

The fuzzy picture came more clearly into focus with the next Understanding Classes tutorial, where we learned to write a custom Class to represent symbols in the Flash library. We used the less-than-helpful example of a Dog Class to explain how to pull this off.

But the time for theory is over. If we’re going to finally learn how to take full advantage of Object Oriented Programming, we need to look at some real-world examples. In this tutorial, we’ll pick through that glob of code in our Main.as file and find places where it makes sense to group chunks of functionality and split them off into their own Class files.

It’s Apparent You’re A Parent

In order to understand when and where to create new Classes, you almost have to think like a parent. All of the methods (things a Class can do) and properties (things a Class is) are your children. As your children grow older, you want them to learn how to take care of themselves. You (hopefully) don’t want to be changing your son’s diapers when he’s 17 years old.

So when you look at that mess of code in your Main.as Class, start asking yourself this question: should this kid, this group of properties and methods, be taking care of himself? Is this stuff that me, the Main.as Class, should be doing, or is this something that this kid can go off and do by himself?

Huh?

Here’s a real-world example:

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.MouseEvent;
 
	public class Main extends MovieClip
	{
		public function Main()
		{
			var myButton:MovieClip = new MyButton();
			myButton.label_txt.text = "Play";
			myButton.addEventListener(MouseEvent.CLICK, clickMyButton);
			myButton.addEventListener(MouseEvent.MOUSE_OVER, rollOverMyButton);
			myButton.addEventListener(MouseEvent.MOUSE_OUT, rollOutMyButton);
			myButton.mouseChildren = false;
			addChild(myButton);
			myButton.x = 150;
			myButton.y = 89;
 
		}
 
		public function clickMyButton(e:Event = null):void
		{
			playGame();
		}
 
		public function rollOverMyButton(e:Event = null):void
		{
			var myButton:MovieClip = MovieClip(e.target);
			myButton.background.gotoAndStop("highlight");
		}
 
		public function rollOutMyButton(e:Event = null):void
		{
			var myButton:MovieClip = MovieClip(e.target);
			myButton.background.gotoAndStop("unhighlight");
		}
 
		public function playGame():void
		{
			// Do some stuff here
		}
	}
}

In this piece of code, the Main.as file adds an instance of the MyButton Class to the stage. When the player clicks the button, we fire the playGame method.

There are some things here that the Main.as Class should probably do, and a bunch of things that the LabelButton Class should do for itself. Let me ask you this: why on God’s green Earth should Main.as care about how the MyButton Class implements all of its MouseEvent code? Making the button highlight on rollOver is MyButton’s responsibility, not Main.as’s responsibility.

Let’s imagine a not-too-distant future. Robots rule the Earth. Gary Coleman is in the White House. And you’re writing a new Actionscript project where you need a MyButton. The way you’ve written it here, can you easily pluck your MyButton Class out of this old project, and plunk it into your new project and expect it to work? No! That’s because you have code that is crucial to the functioning of your MyButton class outside your MyButton Class.

Do the clickMyButton, rollOverMyButton, and rollOutMyButton methods belong to Main, or do they belong to MyButton? Let’s go back to our semi-useless Dog example. Do bark, sniff and peeOnLeg belong to Main, or do they belong to Dog? They belong to Dog. So let’s put them in Dog.

Here’s the above script with the MyButton-specific methods removed:

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
 
	public class Main extends MovieClip
	{
		public function Main()
		{
			var myButton:MovieClip = new MyButton();
			myButton.label_txt.text = "Play";
			addChild(myButton);
			myButton.x = 150;
			myButton.y = 89;
 
		}
 
	}
}

Wow! We really cleaned up our Main Class, didn’t we?

Here’s what our MyButton Class looks like. We’ve just plucked the methods out of our Main Class and put them where they belong, in MyButton. MyButton changes its own diapers.

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.MouseEvent;
 
	public class MyButton extends MovieClip
	{
		public function MyButton()
		{
			addEventListener(MouseEvent.CLICK, clickMyButton);
			addEventListener(MouseEvent.MOUSE_OVER, rollOverMyButton);
			addEventListener(MouseEvent.MOUSE_OUT, rollOutMyButton);
 
		}
 
		public function clickMyButton(e:Event = null):void
		{
			playGame();
		}
 
		public function rollOverMyButton(e:Event = null):void
		{
			background.gotoAndStop("highlight");
		}
 
		public function rollOutMyButton(e:Event = null):void
		{
			background.gotoAndStop("unhighlight");
		}
 
		public function playGame():void
		{
			// Do some stuff here
		}
 
	}
}

If you’re keen-eyed, you’ll notice that we were even able to cut down the code when we moved it to the MyButton Class. Instead of saying myButton.addEventListener(MouseEvent.CLICK, clickMyButton);, we can drop the “myButton” part and just say addEventListener(MouseEvent.CLICK, clickMyButton);. That’s essentially the same as saying this.addEventListener(MouseEvent.CLICK, clickMyButton);. The “this” keyword is like saying “me”. We’re inside the MyButton world, so we’re referring to ourselves. While we are writing code inside the MyButton class, we are MyButton.

Starting an Argumemt

Now what about that line in Main.as where we label the button?

myButton.label_txt.text = "Play";

Is labelling the button a responsibility of Main.as, or a responsibility of MyButton.as? The answer is slightly tricky.

MyButton might not always be labelled “Play”. We could (and should) think generically, so that MyButton could be labelled “Play” or “New Game” or “Change Character” or whatever. So Main.as should be responsible for labelling the button, right?

Not exactly. MyButton should still be responsible for labelling itself. But Main.as should be responsible for deciding what that label says. That way, Main could create buttons that say “Play”, “New Game” and “Change Character”,all using the same MyButton Class. The MyButton Class takes care of all the logic of actually displaying that text on itself.

To pull this off, we pass a parameter to our MyButton Class from Main.as.

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
 
	public class Main extends MovieClip
	{
		public function Main()
		{
			var myButton:MovieClip = new MyButton("Play"); // Check it out!!!
			addChild(myButton);
			myButton.x = 150;
			myButton.y = 89;
 
		}
 
	}
}

Main.as creates a new MyButton instance (stamp, copy), and passes something called a parameter to the MyButton Class. MyButton grabs that parameter and uses it to label itself.

Note: if you’re fuzzy on the concept of datatypes (String, Number, Int, Boolean, etc), you may already be in over your head. Go read a basic tutorial on datatypes, and come on back.

Here’s the MyButton Class, now modified to grab that parameter from Main.as (or whatever Class instantiates [makes a stamp of, makes a copy of] the MyButton class).

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.MouseEvent;
 
	public class MyButton extends MovieClip
	{
		public function MyButton(labelName:String)
		{
			label_txt.text = labelName; // Grab that parameter and label myself!
 
			addEventListener(MouseEvent.CLICK, clickMyButton);
			addEventListener(MouseEvent.MOUSE_OVER, rollOverMyButton);
			addEventListener(MouseEvent.MOUSE_OUT, rollOutMyButton);
 
		}
 
		public function clickMyButton(e:Event = null):void
		{
			playGame();
		}
 
		public function rollOverMyButton(e:Event = null):void
		{
			background.gotoAndStop("highlight");
		}
 
		public function rollOutMyButton(e:Event = null):void
		{
			background.gotoAndStop("unhighlight");
		}
 
		public function playGame():void
		{
			// Do some stuff here
		}
 
	}
}

Beautiful! In this line, we accept a parameter:

public function MyButton(labelName:String)

And in this line, we grab that parameter and use it to label ourselves:

label_txt.text = labelName; // Grab that parameter and label myself!

Jockeying for Position

Finally, we’ll talk about the x/y lines in the Main Class:

myButton.x = 150;
myButton.y = 89;

Is that something that Main should be responsible for, or something that MyButton should be responsible for? x and y are properties of MyButton, so MyButton should handle them, right?

Not so fast! While we could let MyButton position itself, it wouldn’t make sense to. The Class that needs a MyButton should decide where on the screen the button should go. Otherwise, every time we create a new MyButton instance, it’ll appear in the same place on the screen. Not so hot. Main.as should take care of positioning the button instance.

Real Ultimate Power

Et voila! We’re in good shape now. We’ve:

1. Identified a chunk of code that should change its own diapers
2. Moved that code to its own .as Class file
3. Thought generically about how an instance (stamp, copy) of that Class should be treated

Now, check out the glorious wonderland we can experience and enjoy:

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
 
	public class Main extends MovieClip
	{
		public function Main()
		{
			// Instantiate a new play button:
			var myPlayButton:MovieClip = new MyButton("Play");
			addChild(myPlayButton);
			myPlayButton.x = 150;
			myPlayButton.y = 89;
 
			// Instantiate a new instructions button:
			var myInstructionsButton:MovieClip = new MyButton("Instructions");
			addChild(myInstructionsButton);
			myInstructionsButton.x = 210;
			myInstructionsButton.y = 89;
 
			// Instantiate a new credits button:
			var myCreditsButton:MovieClip = new MyButton("Credits");
			addChild(myCreditsButton);
			myCreditsButton.x = 340;
			myCreditsButton.y = 89;
 
		}
 
	}
}

Wowee! THREE new button instances in half the code it took to have ONE button when we first started out.

We’re almost out of the woods. But there’s one nagging thing remaining. Notice that we have a method in the MyButton Class that looks like this:

public function clickMyButton(e:Event = null):void
{
	playGame();
}

Should MyButton decide what happens when it gets clicked? We saw that the Main.as Class can quickly create three instances of MyButton – a Play button, an Instructions button, and a Credits button. These three buttons are all going to do different things when the player clicks them. So the generic MyButton Class cannot possibly define its own click behaviour. Main.as is going to have to decide.

Let’s yank that click code right out of the MyButton Class:

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.MouseEvent;
 
	public class MyButton extends MovieClip
	{
		public function MyButton(labelName:String)
		{
			label_txt.text = labelName; // Grab that parameter and label myself!
 
			// this is where the MouseEvent.CLICK listener used to be
 
			addEventListener(MouseEvent.MOUSE_OVER, rollOverMyButton);
			addEventListener(MouseEvent.MOUSE_OUT, rollOutMyButton);
 
		}
 
 
		public function rollOverMyButton(e:Event = null):void
		{
			background.gotoAndStop("highlight");
		}
 
		public function rollOutMyButton(e:Event = null):void
		{
			background.gotoAndStop("unhighlight");
		}
 
	}
}

And instead, we’ll write the listener for each button’s MouseEvent.CLICK in the Main.as Class:

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.events.MouseEvent;
 
	public class Main extends MovieClip
	{
		public function Main()
		{
			// Instantiate a new play button:
			var myPlayButton:MovieClip = new MyButton("Play");
			myPlayButton.addEventListener(MouseEvent.CLICK, clickBtnPlay); // new line!
			addChild(myPlayButton);
			myPlayButton.x = 150;
			myPlayButton.y = 89;
 
			// Instantiate a new instructions button:
			var myInstructionsButton:MovieClip = new MyButton("Instructions");
			myInstructionsButton.addEventListener(MouseEvent.CLICK, clickBtnInstructions); // new line!
			addChild(myInstructionsButton);
			myInstructionsButton.x = 210;
			myInstructionsButton.y = 89;
 
			// Instantiate a new credits button:
			var myCreditsButton:MovieClip = new MyButton("Credits");
			myCreditsButton.addEventListener(MouseEvent.CLICK, clickBtnCredits); // new line!
			addChild(myCreditsButton);
			myCreditsButton.x = 340;
			myCreditsButton.y = 89;
 
		}
 
		public function clickBtnPlay(e:Event = null):void
		{
			// Play the game
		}
 
		public function clickBtnInstructions(e:Event = null):void
		{
			// Show the instructions
		}
 
		public function clickBtnCredits(e:Event = null):void
		{
			// Show the credits
		}
 
	}
}

And there you have it. The MyButton Class takes care of its own diapers. It labels itself based on a parameter that’s passed to it. It handles its own rollOver and rollOut events. Main.as takes care of creating instances (stamps, copies) of the MyButton Class. Main.as decides:

• What the button label will say
• How the button will be positioned on the screen
• What the button does when clicked

The First of Many

That’s a real-world example of where and when it makes sense to collect your code in a separate Actionscript Class file. Of course, this is just one example in an endless sea of possiblilities. The general rule is that if the code should be changing its own diapers, it should be in its own Class file. And if the code can be written generally so that it can be re-used, you’re ahead of the game.

The mystery that springs up from all of this is the OOP rule of Encapsulation, which states that you should write your Classes so that they’re self-contained and self-reliant. Not only do they change their own diapers, but they rent their own apartment and cook meals for themselves, with no reliance on outside Classes whatsoever to live.

There are advantages and disadvantages to Encapsulation, which we can look at in our next Understanding Classes tutorial. The biggest disadvantage is that to create a truly encapsulated Class, you have to write an ASSLOAD of repetetive Actionscript 3 code. i’ll show you a cheat that’ll break the encapsulation rule, but will save you HOURS of coding. The Eggheads will have my head for it, so let’s just keep it between you and me.

For more tips, tricks and tutorials on Flash and Actionscript, check out our Flash and Actionscript 911 feature.

I promised that in Part 2, we’d learn how to identify chunks of code that should be moved into their own Classes. But before we do that, it’s important to talk about what a Class is. And if you haven’t learned how to extend a MovieClip symbol in your library to write a Class around it, this tutorial is for you!

Disclaimer Dear Eggheads: This tutorial is between me, a designer-turned-coder, and readers who want to learn more about Actionscript programming who likely are not Computer Science graduates. The terminology i use may not be 100% accurate, and some of the things i say may inflame your nerd rage and your unwavering demand for technical accuracy. But this article is not for you. Stop reading now. Go write some slash fiction about Captain Kirk totally doing it with the dog from Battlestar Galactica, and leave us alone to learn.

OOP: There It Is

A Class is an element of OOP – Object Oriented Programming. OOP is a flavour of coding where different objects – or things – interact with each other to solve a problem. If you’re a game programmer, the problem can be described as “How do i make a fun, functional zombie game?” The word “object” is synonymous with “Class”. You could say that Actionscript 3.0 is a Class Oriented Programming language, but the eggheads would stab you in the face.

So a Class is a thing – a chunk, a morsel, a module of code. By writing your Classes the “right” way, you’ll find you can re-use Classes from project to project. By writing them the “wrong” way, you’ll still probably wind up with a project that has nice, well-organized code that makes sense if you re-visit it a year later.

The three principles or rules to follow if you want to maximize the advantages of OOP are encapsulation, inheritance and polymorphism. We’ll be taking a brief, gentle look at inheritance in this tutorial, because i think it’s the easiest to understand when you’re starting out.

Classes contain methods and properties. (Another word for “method” is “function” or “behaviour”. Another word for “property” is “field”.) A method is something a Class can do. A property is something a Class is.
Let’s explain this somewhat better by using a crappy example that a lot of OOP tutorials use. You have a Class called “Dog”. Methods of Dog – things that Dog can do – include:

• bark
• sniff
• humpLeg

Properties of Dog – things that dog is – include:

• color
• breed
• favouriteTreat

Another way to think of it is that methods are verbs, and properties are adjectives.

Let’s Get Real

The Dog example is almost entirely useless to us as programmers. In all my years of experience, i have never written a Dog Class. But i HAVE written my fair share of music and movie players in Flash. Let’s look at the methods and properties of a media player.

Methods of our MediaPlayer Class – things that a media player can do – include:

• play
• pause
• stop
• scrub
• changeVolume
• loadMedia

Properties of our MediaPlayer Class – things that a media player is, or things that describe its state – include:

• isPaused
• songDuration (or movieDuration)
• isFullScreen
• volume

Note that the method “changeVolume” probably changes the property “volume”.

You’re Already an Expert

The good news is that as a Flash developer, you’ve been using Classes this whole time, though you may not have known it. A MovieClip is a Class. It has methods and properties. Let’s look at some of the methods of a MovieClip – things a MovieClip can do:

• gotoAndPlay
• stop
• hitTestPoint (determine whether a point is colliding with me)

And some properties of a MovieClip – things a MovieClip is (or things that describe its state):

• x and y
• alpha
• rotation

Eggheads: Are you still reading this? i told you to take a hike. Don’t jump down my throat. i know that a few of these methods and properties actually belong to Classes that MovieClip inherits from, but we’re just learning, alright? Leave us alone. Go out and LARP or something.

No Pain, No Awesome

Just as you can make the leap from stowing all your code in the first frame of your movie to putting it in an .as Class file, you can (and should) make the leap from having all of your MovieClip instances “physically” present on your stage, to keeping them in the library and drawing them to the stage using code. There are many advantages to using a code-only approach which probably won’t become clear to you until you go through the excrutiating growing pains of “WHY THE HELL AM I DOING IT THIS WAY??” like i did.

So create a MovieClip in your library. NOTE: If you don’t know how to do this, you may already be in over your head. Go check out a beginner Flash tutorial and come on back.

In order for you to make the MovieClip available to you through code, you need to give it a linkage name. Here’s how:

1. Open your Library (CTRL+L)
2. Right-click the MovieClip symbol
3. In Flash CS3, choose “Linkage”. In Flash CS4, choose “Propeties”.
4. Check the box that says “Export for ActionScript”
5. In the “Class:” field, type a logical name for your MovieClip. It’s best practice to start this name with a capital letter. Don’t use any spaces – capitalize each new word SoThatItLooksLikeThis. (This is called “Pascal case”)
6. Click “OK”
7. If you are a Mac user, and you’re saying “What’s a CTRL?? What’s a right mouse button?? i’m freaking OUT, man!”, go buy a PC ;)

Did you notice, before you hit OK, that there was a field labelled “Base Class:” that said “flash.display.MovieClip”? If this is your first time creating a library linkage, or if it’s old hat and you’ve never noticed this field, prepare to blow your own mind: you’ve just used the first principle of OOP – inheritance.

My Mind Done Blow’d Up

Here’s what’s going on behind the scenes. “MovieClip” is a built-in Class that the creators of Actionscript wrote. When you give your library item a linkage name, you are actually subclassing, or inheriting, from the MovieClip Class. That means that your new Class “Dog” or “MediaPlayer” or “EnemySpaceship” can now do all the stuff that a MovieClip can do. It can gotoAndPlay, it can stop, it can hitTestPoint, etc. It also inherits all of MovieClip’s properties – x and y, alpha, rotation, etc. – things that a MovieClip is, things that describe its state.

So now we’re getting to the point. When you create a library linkage like this, Flash is automagically creating a new Class (“Dog”, “MediaPlayer”, whatever). You don’t have to write it. But you CAN write it, if you want to. And since that’s what this tutorial is all about, then oh yes – we want to.

Oh Yes – Let’s

Start a new .as Class file. You can do it in the Flash IDE, you can write it with Notepad or Notepad ++ or any other text editor. i highly recommend Flash Develop. Remember our first Understanding Classes tutorial? Here’s the structure of a Class:

So here’s what our empty Class code should look like:

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

package
{
	import flash.display.MovieClip; // Import statement(s)
 
	public class Dog extends MovieClip
	{
		// Class definition
 
		private var isBarking:Boolean; // Instance variable(s)
 
		public function Dog()
		{
			// Constructor function
			trace("i am a dog");
		}
 
		// Other functions
		private function bark():void
		{
			isBarking = true;
		}
 
		private function stopBarking():void
		{
			isBarking = false;
		}
	}
 
}

Let’s take note of a few important things.

1. i’m calling my Class “Dog”. That’s because the linkage name in used in the Flash library was “Dog”. Note: not “dog” or “DogClip” or anything. D-o-g. Same capitalization, exact same name.
2. And note that the linkage name can be completely different from the library symbol name. My library symbol could be called “This is a thing what i created in teh Flashs”. Doesn’t matter. Actionscript can’t “see” the library item name. It can only “see” the linkage name.
3. Finally, remember that the Class file name has to be the same as the Class name. If our Class is called Dog, we save the file as Dog.as. Pull any other shenanigans, and you’ll get errors.

i mentioned mysteriously in the last tutorial that the word “extends” is an inheritance word. When you create a linkage name in the library, Flash automagically writes a Class for you, and automagically extends (inherits from) MovieClip. Now that we’re writing the Class ourselves, nothing is automagic. We have to explicitly say that Dog (or whatever) extends (inherits from) the MovieClip Class. When this is all done correctly, Flash understands that there is a connection between the linked library Class “Dog”, and the “Dog.as” Class we just wrote.

You may or may not know the code for dynamically placing a linked library item on the stage. Here it is, using Dog as the example:

1
2

var dog:MovieClip = new Dog();  // or var dog:Dog = new Dog();
addChild(dog);

“BUT WAIT!”, you say. “I THOUGHT DOG HAD TO START WITH A CAPITAL LETTER??” Okay, first of all, stop yelling. Lower-case “dog” is the name of the variable that contains an instance (a stamp, a copy) of our master Dog Class. We could use “dog1″, “dog2″, or even “thisIsACopyOfDog”.

When you addChild(dog), you add your instance (stamp, copy) of the Dog Class to the list of things for Flash to draw to the stage (the viewable area that the player sees).

To confirm that your custom library Class is working, test your movie. You should see the trace action “i am a dog” in the Output window. (Press F2 to see the Output window – the trace action won’t appear on the stage)

What’s the Point?

You may be wondering why we went through all of this agony. The easy way is just to draw a dog and make it a MovieClip, and then leave it on the stage. There are many, many advantages to what we’ve just done. Let me list a few:

• You can now add as many Dogs to the stage as you like dynamically. Until now, you had to add them by hand. If you needed another dog, you (the creator) had to drag one out of the library. Now you can create an “Add Dog” button. When the player presses it at run-time, your code dynamically places dogs on the stage. Now the code is doing the work, not you.
• We’re edging closer to the next OOP principle, encapsulation. Within our Dog class, we can store methods (things that a Dog does) and properties (things that a Dog is). Every time we initialize (make a stamp or copy of) Dog, Dog can run a bunch of Dog-specific setup routines: initializeSenseOfSmell, testBarkTone, prepareToChewShoes. If you do it “right”, you’ve created a self-reliant, self-contained Class. Now every time you have a project that needs a Dog (or a MediaPlayer, an ImageGallery, a CountdownClock), you can just copy that .as Class file to a new project. If you’ve done everything “right”, it’ll just work.
• The more you start abstracting your thinking, the more you’ll be able to write generic Classes that do a number of different jobs. You might not have another project that needs a Dog, but your generic Animal Class would still do the trick.
• There’s a problem that Actionscript 3 introduced where you can’t always access certain pieces of MovieClips until they’re drawn to the screen. Writing a custom Class for your library elements can overcome this problem.

What’s Next?

Moving your frame code to an .as Class file was the first step. Learning how to write custom Classes for your linked library items is the next step, since it builds on (hopefully) familiar MovieClip territory and your existing knowledge. In the next tutorial, we’ll take a look at that big wad of code in your Main.as file and try to figure out which methods and properties can be logically grouped and moved into their own Classes.

For more tips, tricks and tutorials, check out our Flash and Actionscript 911 feature.

i love big lists of articles like this that are grouped by topic! We’ve made a few of our own here on the site:

• Flash and Actionscript 911 – An ongoing series of articles and tutorials, including common error messages and what to do about them
• News For You ue_newspoodle compiles a daily list of interesting stories on game development and related topics. Feel free to add your own links!
• Pimp My Game Our feature about monetizing Flash games has been updated with a GREAT list of articles on the subject – scroll to the bottom of the page to find them
• Conjure, a group of ETS students in Montréal, maintain a whopping pantsload of great game industry links (thanks @jeanpierflash!)
• Smashing Magazine offers 35 Excellent Wireframing Resources (thanks @danmartell!)
• Flash Game Blogs – A Who’s Who of the Flash game dev world and links to their blogs, maintained by the folks at GamerSafe/Flash Game License
• Top Indie Developer Blogs – We were delighted and honoured to find ourselves among such great sources on this list, which was posted by the buys at Gambrinous
• How to Raise Start-Up Financing – We prefer to bootstrap wherever possible, but Ben Yoskovitz has a series of articles on building a bidness with Other People’s Money
• Blender Resources – lanzoma composed a list of links to help developers who are new to Blender, a free 3D software package
• Business Resources for Startups – a FANTASTIC list of links across the full spectrum of concerns for start-up companies, game studios included
• Awesome Sources for Game Music – a list of links and mini-reviews for various music stock & service providers
• 50 Awesome Open Courses for Web Writers – Make your corporate game blog sing!
• All the Developer’s Books You Ever Wanted – A great list from Jeez.com of free pdf instructional books on a variety of languages and technologies.
• Indie Game Developer Links – Gaming Horror maintains his own superb list similar to this one.

If you have lists of links that you want to share, leave a comment and i’ll add them to this list!

The path i travelled from complete code newbie to the shock-inducing AS3 god that i am today ( er … hardly) went like this:

Beginner – i put my Actionscript code everywhere – on different frames of the timeline, embedded in nested MovieClips – if i can write code on it, i do.

Intermediate – Scattering code through my Flash movie makes my project an enormous pain to manage and update. i’m going to put ALL of my code on the very first frame of my movie, so i only have to look in one place for it.

Pro – i don’t understand Classes, but i have to take the plunge somehow. i’m going to move all of my first-frame code into a separate .as Class file. i hope that’ll be the first step to breaking everything up into Classes.

Shock-Inducing AS3 God – Man almighty – packing an entire project’s code into one .as Class file makes it an enormous pain to manage and update. i’m going to identify little modules of code and split them off into their own .as Class files. Hey … now i’m starting to use Classes like a superstar!

The Road to Pro

In this tutorial, we’ll help you move from Intermediate to Pro by moving your first-frame code to its own Class in a separate .as file. In Part 2, we’ll take you from Pro to God by discussing ways in which you can split that enormous file up into smaller Classes, and how to figure out which pieces would make good Classes.

Many of the AS3 tutorials you see on the Internatz are written so that you can just paste the code into the first frame and compile the project. This is because it’s easier on the tutorial writers – they assume that you know how to re-write that code to put it in its own Class. But what if you don’t know?

Let’s take a piece of frame code, and bring it outside our Flash .fla file into a separate .as Class file. Here’s the frame code we’ll be using:

1
2
3
4
5
6
7
8
9
10
11

var speed:int = 5;
var ball:MovieClip = new Ball();
addChild(ball);
 
addEventListener(Event.ENTER_FRAME, moveBall);
 
function moveBall(e:Event):void
{
  ball.x += speed;
  ball.y += speed;
}

This code grabs a MovieClip called “Ball” from the library and places it on the stage. On every frame, the ball moves to the right 5 pixels and down 5 pixels. We’re going to pretend that this code exists on Frame 1 of our Flash movie. (Note: you don’t need to copy/paste this code and try it, but go ahead. If you’re not sure how to create a ball MovieClip and link it in the library, you might be in over your head already. Read up a bit on super-basic Flash stuff, and we’ll see you again shortly.)

Now let’s create an empty, external .as Class file to hold all this code. So your project will consist of two files: the Flash .fla file, which has a Ball Movieclip in the library, and a Class file with an .as extension. This isn’t anything fancy – an .as file is just a plaintext (.txt) file that you save with a .as extension. So yes, you can even write this file using Notepad or your favourite text editor.

The .fla and the .as file should exist side-by-side in the same directory.

The Care and Feeding of Classes

Classes demand a particular structure:

Notice a few things:

1. Package (whatever that is) wraps the whole thing
2. the Import statements (whatever they are) come next
3. the Class Definition (huh?) wraps everything else
4. the Instance Variables, Constructor Function and other methods/functions are tucked inside the Class wrapper. You can put these three things in any order, but this is how you’ll usually see them in the wild.

Package

Let’s deal with that Package thing first. The Package declaration is a way of grouping all your Classes together. Let’s say you’re working on a project with Bob. You have a class called “Stuff”, and Bob has a class called “Stuff”. By uniquely naming your Package, your classes won’t conflict.

But are you working with Bob right now? Are you on a big project with multiple programmers? No. So don’t worry about it. Forget Bob – just start with a generic Package declaration, which looks like this:

1
2
3
4

package
{
     // All the other stuff goes in here, between those curly brackets
}

(note that “package” has a lower-case “p” … i’ve used an upper-case “P” in the article just to make the word pop out at you)

Import Statements

Different parts of the ActionScript 3 language are already split up into packages. When you put your code on a frame in Flash, all of those packages are automatically accessible. You don’t have to do any extra work.

But when you work outside Flash, you have to tell the compiler to go grab portions of the AS3 language before you can use them. So if you say this in an .as Class file:

1

var myclip:MovieClip = new MovieClip();

the compiler will throw you an error, effectively saying “What’s a MovieClip??”

Use an Import Statement to explicitely tell the compiler that you are using a certain part of the AS3 language. This is a giant pain in the ass, and a real roadblock when you’re starting out. As a beginner, you don’t know the package names you’ll need. This is just a painstaking trial-and-error period of looking in the documentation, or referring to other people’s code, and eventually you’ll memorize this stuff. (Or you can use a program like Flash Develop, which automagically figures some of it out for you.)

So if you use a line like this later on in your code:

1

var myclip:MovieClip = new MovieClip();

you have to include an Import Statement like this at the top of the file:

1

import flash.display.MovieClip;

(note: small “i” on “import”)

It’s like you’re saying “OK, compiler – we’re going to talk about fish today. Go get that fish book out of the library so that we’re all on the same page.”

Class Definition

This is where you actually start writing your Class. Here’s the format:

1
2
3
4

public class Main extends MovieClip
{
    // The Instance Variables, the Constructor Function and Methods go here
}

Let’s break down that line piece by piece:

public Class Main extends MovieClip

We don’t really need to bother with understanding public vs. private vs. protected vs. internal. Those keywords are all in the same family, but here’s what you need to know: you gotta use “public” here. Don’t worry about the other possibilities until you’ve got a handle on the basics. If you don’t use “public” in the Class that replaces your first-frame code, you’ll get an error.

public Class Main extends MovieClip

We’re writing a Class! i’m getting all tiingly.

public class Main extends MovieClip

This is the name of the Class. Feel free to use your creativity here – you can call it whatever you like. But there are a few important rules:

1. You must use standard naming conventions. Don’t start the name with a number, and stay away from spaces and special characters.
2. Use a capital letter to begin your Class name
3. When you save the file, the file MUST have the same name as your Class. If your Class is called Main, save the file as Main.as. If it’s called MyProject, save the file as MyProject.as. If you don’t do this, there will be trouble.

public class Main extends MovieClip

In earlier attempts to understand Classes and Object Oriented Programming (OOP), you may have heard of the concept of “inheritance.” That’s what the “extends” keyword is all about. Without exploring too deeply, we need to extend / subclass / inherit from an ActionScript 3 Class called MovieClip. Why? Because if we don’t, we’ll get yelled at. So just do it. Strive to understand it later.

public class Main extends MovieClip

That’s the Class we’re inheriting from. It’s like saying “my Class called Main can do everything a MovieClip can do, and more.”

Instance Variables

Instance Variables, sometimes called Fields, are variables that you need to access throughout your Class. If you’re familiar with the idea of scope, you’ll know that when we do this:

1
2
3
4

function myFirstFunction():void
{
   var myVariable:String = "someValue";
}

we’ll get an error if we try doing this:

1
2
3
4

function mySecondFunction():void
{
   trace(myVariable);
}

That’s because myVariable is scoped to myFirstFunction. It doesn’t exist outside that function.

If you want variables to be accessible to all the different functions in your Class, you declare them in the orange area on the diagram. You’ll also need to decide whether you’re making these variables public, private, internal, protected, etc. This is not a decision you need to make when all your code is on the first frame. OOP purists would absolutely FREAK OUT if they were reading this, but i’m going to recommend you make all your variables public for now. It’s the least error-prone approach when you’re learning, and when you know more, you can get a little fancier.

So here’s what a typical Instance Variable would look like at this point in the .as Class file:

1

public var myVariable:String;

Notice that we’re not even setting a value yet. We can, but we don’t have to. We’re just reserving a spot in the computer’s memory for this variable so that the whole Class can use it.

The Constructor Function

This Main Class will be what’s called the “point of entry” into our Flash program. It’s the first place where code will start being activated. A Constructor Function is like the point of entry in any Class. It’s the first function that’s fired when a Class is encountered by the interpreter.

Here’s what our Constructor Function should look like:

1
2
3
4

public function Main()
{
 
}

As with Classes, you have to follow a few rules with your Constructor Function:

1. The Highlander rule: “there can be only one”. i believe other languages allow you to have multiple Constructor Functions, but AS3 does not.
2. The name of the Constructor function must be the same as the name of the Class.
3. Make sure it’s public.
4. Don’t return a value – not even “void”. Constructor Functions are not allowed to return a value.

Putting It All Together

Let’s slap it all together and see what we’ve got:

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

package
{
    import flash.display.MovieClip;
    public class Main extends MovieClip
    {
        // instance variables go here
 
        public function Main()
        {
             trace("It works!");
        }  
 
        // other functions can go here
    }
}

Super! We’ve got the shell of a Class that we can use as our point of entry. (Make sure it’s saved as “Main.as”, or whatever you called your Class.) We’re just missing one step. We have to tell Flash that instead of looking to the first frame of the movie as our point of entry, we want it to look at the “Main” Class.

Open up the Properties panel in Flash and look for an empty field labelled “Document class:” (CS3) or “Class:” (CS4).

Note: you won’t be able to use this feature unless you’re targeting Flash Player 9 or above, with ActionScript 3 or above.

Type “Main” (without the quotes) into this field. Then save and compile. You should see the trace statement “It works!” in the Ouput panel.

All the Rest

Now that we have Flash looking to an external .as file to get the party started, let’s port over some of that first-frame code into our class. i’ll paste the clean version first, and then an identical copy with extensive comments so that you can follow along at home:

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

package
{
    import flash.display.MovieClip;
    import flash.events.Event;
 
    public class Main extends MovieClip
    {
        public var ball:MovieClip;
 
        public function Main()
        {
             ball = new Ball();
             addChild(ball);
             ball.speed = 5;
 
             addEventListener(Event.ENTER_FRAME, moveBall);
        }
 
        public function moveBall(e:Event):void
        {
                ball.x += ball.speed;
                ball.y += ball.speed;
        }
    }
}

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
36
37
38
39
40
41
42

package
{
    // This is the commented version.
    import flash.display.MovieClip; // since both Ball and Main are MovieClips,
              // we have to import the MovieClip Class 
    import flash.events.Event; // Later on, we use the Event Class, so
             // we need to import it here.
 
    public class Main extends MovieClip
    {
        // See how the Class definition and import statements
        // are inside the package curly brackets?
 
        public var ball:MovieClip; // We declare "ball" up here
             // so that the whole Class can refer to it
 
        public function Main()
        {
             // This is the constructor function!
 
             ball = new Ball(); // Since we already declared "ball"
               // as an instance variable, we can just refer to it
               // directly without redefining it
             addChild(ball); // Where does ball get added?  Main
               // is representing our Flash movie's main timeline,
               // so that's where the ball appears
             ball.speed = 5;
 
             addEventListener(Event.ENTER_FRAME, moveBall);
             // note: no need for the word "this", in case you
             // were wondering
        }
 
        public function moveBall(e:Event):void
        {
                ball.x += ball.speed;
                ball.y += ball.speed;
                // Again, because "ball" was defined up top, 
                // the moveBall method can refer to it
        }
    }
}

Are You Smart Yet?

Hopefully, you know enough now to port your whole wad of first-frame code to a separate .as Class file. That’s a baby step towards actually using the power of Classes to save yourself time in the future, and to keep your code organized, updatable, and a pleasure to re-visit.

In the next part of this tutorial, we’ll look at ways you can pick through your Wall of Code and identify which pieces you can could out into their own Class files.

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

i spent a lot less time on this year’s game than i did with my other entries, Two By Two and Here Be Dragons – Bloat. clocked in at around twenty-two hours. i took time out of the schedule for luxuries like eating, sleeping, and going to the bathroom. As Laurence Olivier said to John Hurt in the 1983 version of Shakespeare’s King Lear, “i’m getting too old for this shit.” Still, at the risk of being labelled a big girl’s blouse, i did pull an all-nighter from 11AM Saturday to 1AM Monday, racking up a total of two and a half hour’s sleep. i still got it, baby.

Peer Pressure

When i got to the jam on Friday night, i had my plan down semi-solid: armed with a MacBook and a copy of Beginning iPhone Development (i’m on chapter four!), i was going to churn out a few small not-really-game iPhone apps by the end of the weekend. So i sat down, cracked the book, and started reading all about model view controllers and Interface Builder, and view states and multi-view panel buttons and snoooooooooooore. All around me, enthusiastic jammers were yelling stuff like “score!” and “player!” and “enemies!” and “hot coffee!” at each other, and i started to feel a little left out.

So i calmly closed the book, and opened up the trial copy of Unity that i’d just downloaded. i already knew how to make a box fall from the sky and land on the ground. That’s, like, halfway to a game … right? And all around me, the game banter continued: “extra lives!” “state machine!” “Robotron controls!” “EA spouse!” The din was deafening, and i’d forgotten my headphones.

This was no place to learn new software. This was no place to struggle with an unfamiliar operating system. This was the mother-effing Toronto Game Jam, and i was there to make a GAME. So i lit the MacBook on fire and threw it across the room, took off my pants and tied them around my hair like a headband, booted up my PC laptop and opened Flash. i was there to make a game, and nothing was going to stop me.

A Dark Room

i’d promised myself that this year, i was going to go into the game jam cold, with no game ideas and a commitment to the year’s theme. The theme this year was “scale”. Little did i realize that actually cooking up an idea right there on the spot was going to be challenging. A weekend-long jam requires a lot of planning; you have to choose a game idea that you can build in that tight amount of time, and what’s worse, it actually has to be playable. And on top of that, and completely optionally, it also has to be fun. Since fun is that just-out-of-reach jewel that we game developers stretch for when we have a lot more time to think it through, the jam presents a significant level of challenge.

So i went into a dark room and thought for nearly two hours. When i emerged, i had a concept, but i didn’t have any idea whether it was good or not. The only way to find out was to build it.

A Little Help

When i first attended the game jam, i didn’t have any libraries or prior code. i just opened up a fresh Flash project and started building. i knew that other people were using pre-existing libraries, and i considered that “cheating”. These days, though, i’ve caught glimpses of how other programs work, and i now appreciate the number of tasks that Flash automates for the developer. For example, other languages require lines and lines of code just to draw something to the screen. Flash handles this for you. So really, i had been using a tool to speed up development all along.

So from there, and with the enormous asspains presented by Actionscript 3, i was able to justify the use of a few more libraries this year, which helped me focus on the core game experience. Here are the snippets i used:

1. Corey O’Neil’s excellent Collision Detection Kit (thanks, Corey!)
2. Jeff Gold’s audio classes for playing music and sound effects (Jeff is our game developer here at Untold Entertainment, but he couldn’t make the jam this year. Something about nice weather and “having a life”.)
3. Our Game Screen Manager class, which handles switching between screens and popping up prompts and dialogues
4. Our Helper class, the guts of which you can copy-paste from our Flash 911 series to use in your own projects
5. A fireworks particle effect that i found online and ported from AS2 to AS3 for our fun, crime-themed puzzle game Kahoots™, which we modeled entirely in clay

The Result

i’m very happy with how Bloat. turned out! The biggest brainwave of the weekend was looking at all of the features i had in the game, and deciding to split them out across multiple tutorial levels. i remember watching in dismay at last year’s jam as people walked up to Here Be Dragons, clicked until they got some ship rigging stuck in the sea monster’s throat, couldn’t figure out what to do, and floated away to try another game. If there’s one thing i’ve learned is a weakness of mine as a designer, it’s getting what’s in my head out of my head.

The Closed Public Beta team for Kahoots™ is doing an excellent job of pointing out where Kahoots game needs more explanation. The best advice i can offer you, if you have this problem too, is:

1. Make your game more simple
2. Introduce escalations gradually
3. Treat your audience as if they ride the short bus

Your players aren’t stupid. (Well, most aren’t … ) But they can’t read minds either. By dumbing down your instructions and game progress into digestible chunks, you’re allowing the smart people to sail through to the more difficult content, without leaving your less savvy players in the dust. Either way, you ensure that absolutely everything that was in your brain is out of your brain, and everyone’s on the same footing.

Until i develop and convince everyone to purchase and install my mind control ray, this approach will have to do.

• Talk about Bloat. on the message boards!

This is a bit of structural/best-practices advice i gleaned when i was learning C# programming in XNA for the Xbox 360. Flash/Actionscript behaves a little differently than other programs. The way many games are programmed, there is one giant loop, and everything takes place in that loop.

Flash encourages you to throw code all over the place – on frames, on movie clips, in separate .as files – but Flash coders could really benefit from the sanity and cleanliness that a master loop brings.

Here Comes the Code

At its most basic, this is what we’re talking about:

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
36
37
38
39
40
41

package 
{
	import flash.display.MovieClip;
	import flash.events.Event;
 
	public class Main extends MovieClip
	{
		private var isPaused:Boolean; // This is the variable that holds our paused/unpaused state
 
		public function Main()
		{
			// Unpause the game:
			isPaused = false; 
			// Add an event listener to keep an eye (ear?) on the built-in ENTER_FRAME event.
			// Every time Flash processes a frame tick, doMasterGameLoop will execute:
			addEventListener(Event.ENTER_FRAME, doMasterGameLoop);
		}
 
		private function doMasterGameLoop(e:Event = null):void
		{
			// This is the main game loop that does all the work.  It's the
			// "gateway" to everything our game does.  If the game is paused,
			// nothing in the game loop happens.
			if (!isPaused)
			{
				update();
				draw();
			}			
		}
 
		private function update():void
		{
			// Tweak all your numbers and math stuff here
		}
 
		private function draw():void
		{
			// Update all your graphics here			
		}
	}
}

So all you need to do is rig up a “PAUSE” button that toggles the isPaused variable when you click it. When the game is paused, stuff won’t happen. Unpaused? Stuff happens.

Whiling Away the Hours

If you come from another programming language, you might be accustomed to seeing the game loop built in a while statement. Actionscript is a different beast when it comes to while. The whole program runs on frame ticks, meaning it will execute your code according to the frame rate you’ve set in your fla file. A framerate of 12 fps (frames per second) means that Flash will try to run your code 12 times a second. “Try” is the operative word – the code will only execute according to the processor’s ability.

There are ways to get your code to execute more quickly than the set frame rate, but for our purposes, since we’re talking about the ENTER_FRAME event, we’re talking about code executing on frame ticks according to the set frame rate.

If you try to put your master game loop in a while statement in Actionscript 3, here’s what’ll happen:

1. first frame tick: code is executed
2. interpreter hits the while statement
3. there is no escape or break condition in the while statement, so Flash keeps trying to execute those commands in the same frame tick
4. after a prescribed number of seconds, Flash poops out and you get an endless loop error

So instead, think of Flash as having one big automatic while loop, and you’re tucking all of your code inside it.

Keep Em Separated

To a native flashcoder, it may look odd to see two separate processes – update and draw – in the game loop. The way games in other languages work is that first, an update process figures out where everything in the game should be – bullets, enemies, the player character, the power-ups – and then in the draw process, all of the graphics for those things get refreshed on the screen in their (sometimes) new positions.

One mixed blessing with Flash is that code and graphics are married. If you update the x position of a movieclip, you’re updating both the logic and the display. They’re fused together. This is one of the reasons Flash makes for rapid prototyping, but it can also mess you up when you’re trying to do something complicated.

The hard lesson i’ve learned over many years of development is to divorce your code from your graphics, wherever it makes sense. Let’s say you have bullets in your game. You might be tempted to have all your little bullet01, bullet02 … bulletn movieclips on the stage, and then update their x/y co-ordinates to move them around. Then, when you want to find out where your bullets are, you loop through everything on the stage that’s of type “bullet” and have the bullet movieclips report their positions.

A better way to do it is to create a Bullet object (class). It has properties for xPosition, yPosition and graphic. In the update process, you change the xPosition and yPosition properties based on where the bullet should be. In the draw process, you set the positions of the bullets’ graphics:

1
2

graphic.x = xPosition;
graphic.y = yPosition;

There are better examples of where this separation of logic and display is useful – i’m just introducting the concept simply for now.

Pausing Sprites

One of the other things Flash does to save you time is to give nearly every on-screen object an automatically-looping timeline. If you create a 3-frame MovieClip object and put it on the stage, it will automatically animate. Good! But since it’s not controlled by code, but rather by some secret behind-the-scenes process, it won’t stop when you hit the “pause” button. Not so good!

What you really want to do, and it takes quite a bit more work, is to create a class to represent your on-screen object (we’ll call them “sprites”, although the term has slightly different connotations in ActionScript), and keep track of which frame the sprite should display. So on your update process, you figure out which frame to display, and on your draw process, you send the MovieClip to that frame. That’s a far better example of what i’m talking about re: separating code from display, but it’s a bit beyond the scope of this tutorial. Let’s just see our pause button simply doing what it does one more time:

Hooray! You can download the source code here:

http://www.untoldentertainment.com/blog/tutorials/gameLoop/gameLoop.zip

We’ll tackle programmatic sprites in another tutorial!

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

That’s right – i said “Fwitter”

It’s a very simple thing to display your Twitter updates in a Flash widget. We’re going to use the xml feed, because that’s what i’m most comfy with. Unfortunately, you can’t grab the xml feed from Twitter’s site, because they’ve locked their crossdomain policy file … but you can pull down the data using any other damned process. Here’s the basic flow you have to follow:

1. Hit a PHP page or javascript function from Flash (we’ll use PHP)
2. Parse the XML data that the call returns
3. Display the goodies in your Flash app

Here Comes the Code

This is the Actionscript 3 code you’ll need:

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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

package
{
	/**********************************************
	 * 
	 *  This fun Twitter widget is brough to you
	 *  by Untold Entertainment Inc, and 
	 *  peanut butter!  Peanut butter: a gooey,
	 *  yummy snack that might kill you.
	 * 
	 *  http://www.untoldentertainment.com
	 * 
	 **********************************************/
 
	// Here are all the goodies you're going to need 
	import flash.display.MovieClip;
	import flash.events.Event;
	import flash.net.URLLoader;
	import flash.text.TextField;
	import flash.text.TextFieldAutoSize;
	import flash.net.URLLoader;
	import flash.net.URLRequest;
	import flash.events.Event;
 
	public class Main extends MovieClip
	{
		private var twitterXML:XML; // This holds the xml data
 
		public function Main()
		{
			// Put your Twitter username here.  For example, ours is "untoldEnt" :
			var myTwitterID:String = "myTwitterID"; 
			// Put the path to your php script here:
			var twitterPHPScriptPath:String = "http://www.yourdomain.com/thePathToYourPHPScript";
			// Fire the loadTwitterXML method, passing it the url to your Twitter info:
			loadTwitterXML(twitterPHPScriptPath + "?twitterId=" + myTwitterID);
		}
 
		private function loadTwitterXML(URL:String):void
		{
			var urlLoader:URLLoader = new URLLoader();
			// When all the junk has been pulled in from the url, we'll fire finishedLoadingXML:
			urlLoader.addEventListener(Event.COMPLETE, finishLoadingXML);
			urlLoader.load(new URLRequest(URL));			
		}
 
		private function finishLoadingXML(e:Event = null):void
		{
			// All the junk has been pulled in from the xml!  Hooray!
			// Remove the eventListener as a bit of housecleaning:
			e.target.removeEventListener(Event.COMPLETE, finishLoadingXML);
 
			// Populate the xml object with the xml data:
			twitterXML = new XML(e.target.data);
			showTwitterStatus();
		}
 
		private function showTwitterStatus():void
		{
			// Uncomment this line if you want to see all the fun stuff Twitter sends you:
			//trace(twitterXML);
 
			// Prep the text field to hold our latest Twitter update:
			twitter_txt.wordWrap = true;
			twitter_txt.autoSize = TextFieldAutoSize.LEFT;
 
			// Populate the text field with the first element in the status.text nodes:
			twitter_txt.htmlText = twitterXML.status.text[0];
		}
	}
}

And here’s the PHP code:

1
2
3
4
5
6
7
8
9
10

<?php
 
$twitterId = isset($_REQUEST["twitterId"]) ? $_REQUEST["twitterId"]