Tag Archives: AS3

Flash to iOS: A Step-by-Step Tutorial (Part 2)

Flash to iOS: A Step-by-Step Tutorial

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:

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.

Gravy

Thick, delicious 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.

OpenSSL

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.

Adobe Help Page

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.

Instructions

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.)

CMD

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.

CLI Commands

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.

RANDFILE command

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:

    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:

    response

    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:

    Certificate Signing Request file

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.

    Certificates

  2. Click Request Certificate.

    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.

    Generate Certificate

  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:

    Certificate Pending

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

    Certificate Ready

  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.

Save Certificate

Save Certificate 2

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.

    Adobe Help Page 2

  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!

    p12 Signing Certificate

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.

    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.

    New App ID

  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.

    App Description

  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.

    App ID Results

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.

    Apple Provisioning Portal

  2. Click on New Profile.

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

    New Apple Provisioning Portal

  3. Give your provisioning profile a Profile Name.

    Apple Name Your Provisioning Profile

  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.

Apple Provisioning Profile

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

Flash to iOS: A Step-by-Step Tutorial (Part 1)

Flash to iOS: A Step-by-Step Tutorial

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:

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.

Saying stuff is dead is dead

Saying stuff is dead, is dead. You heard it here first.

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.

Butter Churn

Thank God Flash is dead! Now we can finally move forward.

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)

Macs are not free

A Mac: not free.

Introducing Sina

Sina looks like Prince of Persia

He’s the spitting image of this guy – i swear.

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”.

It ain't free

“Free” as in “Free Beer … that you have to pay for.”

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.

    iOS Provisioning Portal

  2. click Devices in the sidebar.

    iOS Devices menu

  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.

    iOS Add Devices

  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.

    iOS 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

Hooray! It’s Ponycorn P’toosday!

Today marks the iPad release of Sissy’s Magical Ponycorn Adventure! Now you can take Poo-Pants, Fluffybuns, Lady Fuzzwuzzle, Orangeboy, and (inaudible) with you wherever you go. Impress your extended family! Accost sour-looking strangers in waiting rooms! Play it for a pick-me-up when the boss isn’t watching!

To celebrate, we’re showcasing the work of some dyed-in-the-wool ponycorn fans.

Ponycorns at Anime North

Mike Barltrop is an educator who showed Sissy’s Magical Ponycorn Adventure to his high school students so they’d be without excuse – if a 5-year-old could pull off a game, he can expect a lot more from them. Mike enjoyed ponycorns so much that he painstakingly re-created a number of Cassie’s drawings and dressed up as the game for the Anime North nerdfest in Toronto:

Sissy's Magical Ponycorn Adventure Anime North costume

For serious.

To put Mike’s ponycorns passion into perspective, the game was released on May 25th. Anime North started the following Friday and ran the length of the weekend. And people at the conference recognized Mike’s costume. Awesomazing!

The Star’s Crayon Forgery Shenanigans

We spotted one piece of fan art that was no less hilarious than Mike’s costume, but unbelievable for a different reason. When the Toronto Star posted its story about the ponycorns’ meteoric rise to prominence, the online piece had two images in its gallery: a shot of Cassie playing the game, and THIS:

Sissy's Magical Ponycorn Adventure Toronto Star forgery

Also for serious.

It doesn’t take a keen eye to see that this image is actually a forgery, created by an adult employed at the Star. When we saw this image on the site, we were a little baffled. We have a stack of original crayon art from the game that we could have sent to the newspaper at a moment’s notice. This kind of thing is in keeping with some of my other dealings with news media, like my interview with CityTV from a while back where they grabbed one tiny soundbite from me to prove the point they were trying to make, and completely discarded everything else i said. Hilarious! If you don’t already watch the news and read the paper with a cocked eye, i hope you’ll start today.

We asked the Toronto Star to correct the article, and the picture was removed in short order.

UPDATE

Now it’s ME doing the retracting. The wacky lads over at Shh-Mom.com have confessed to penning the offending artwork which, in its original context, isn’t offending at all. The folks at the Star must have grabbed it, thinking it to be genuine. i’m glad we got to the bottom of this. Has it restored my faith in traditional news media? No. Question everything!

Flannery’s Fanfic

We’re saving the best for last on Ponycorn P’toosday. 9-year-old Flannery, proud owner of a plush ponycorns mega-pack, sent us this fantastic storybook featuring the extended adventures of the ponycorns gang. Enjoy your face off!

Ponycorns Fanfic

Ponycorns Fanfic

Ponycorns Fanfic

Ponycorns Fanfic

Ponycorns Fanfic

Ponycorns Fanfic

Ponycorns Fanfic

Ponycorns Fanfic

Ponycorns Fanfic

Ponycorns Fanfic

Get Some

If this is your first exposure to ponycorns, pick up your copy on the iPad today! The game is also available on the BlackBerry Playbook and in your browser.

Dear RIM Blackberry Playbook People: Please Put that Shit on a Button

Dear RIM Blackberry Playbook People,

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

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

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

    Click here

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

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

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

    Developing for the Playbook: Chapter 3

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

    Playbook Development Slider

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

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

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

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

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

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

    blackberry-signer -csksetup -cskpass DesiredCSKPassword

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

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

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

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

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

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

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

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

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

    YOU WILL NEED:

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

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

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

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

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

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

    N’awesome.

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

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

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

Sincerely,

Ryan Henson Creighton

President, Untold Entertainment Inc.

Understanding Functions – Return Values

There is a very short list of programming structures you have to learn to be reasonably comfortable in most modern object-oriented languages. Functions are one of them.

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

Vending Machine

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:

Punctuation refresher

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

Return Values

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?

Call a Function

The code interpreter recognizes this as a Function call …

Bring the Arguments

… and takes the arguments with him in his suitcase.

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

Unpack the arguments

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

Pack the return value

Get packing, Pac Man.

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:

[swf]http://www.untoldentertainment.com/blog/img/2010_12_02/returnValueFlow.swf, 600, 500[/swf]

(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.

Psycho Girlfriend

You said we would have BABIES! And ints!!!

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

The Labyrinth

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.