Using Adobe AIR to create OUYA games

Posted by Zeh Fernando on 30/June/2013 at 19:54

I’ve been toying around with creating OUYA content with Adobe AIR, and I’m happy to say it’s a pretty easy and straightforward development workflow. Information on it is hard to come by, though, and the official Adobe AIR support samples doesn’t seem to exist anymore, so here’s a few high-level notes on how to get it working. As a bonus, remember this can all be done with free tools (a big myth of Flash development is that it requires some proprietary, commercial-only IDE).

Setup

  1. Download the Adobe AIR SDK and unzip it somewhere. This has the compiler that you’ll use, called “ASC 2.0″. Normally you want to have that in a generic location, since it can be used by more than one project. Mine is always at a “D:\air” location – at any moment in time, I always have 3 or 4 copies of different versions of the compiler, each on a folder with a different name depending on its version.
  2. Download the latest version of the Flex SDK and unzip it somewhere. This is the compiler that you’ll use. Normally you want to have that in a generic location, since it can be used by more than one project. Mine is always at a “D:\flex” location – at any moment in time, I always have 3 or 4 copies of different versions of Flex SDK, each on a folder with a different name depending on its version.
  3. Download the Adobe AIR SDK and unzip it somewhere, but then move its contents over to the Flex folder. This will replace (old) AIR files that your Flex installation came with, updating it to the latest version of Adobe AIR.
  4. Set your workflow up to be able to edit and compile a pure AS3-based project, as well as using the compiler in that AIR version for compilation. This will vary depending on your IDE of choice. You can use any text editor (if you’re happy using the command line to compile). More focused IDEs exist, though. A good free one is FlashDevelop. Commercially, there’s also Adobe FlashBuilder and FDT (both based in Eclipse). I have to say the latter one is my favorite and it makes development easier by automating some tasks.
  5. Remember to setup your compiler parameters to use the most modern settings available, to avoid problems with legacy parameters. I especially recommend compiling your SWF as Flash version 11.7 or higher (that’s “SWF version” 20 or higher). Also, if you have used the Flex SDK before but are new to ASC 2.0, it’s very likely that you’ll have to do a few small changes to your code. Read this compatibility document for more information.

With this, you should be able to compile and run AIR applications on your desktop. There’s a lot more to it, like creating a descriptor file and embedding assets correctly, but it’s beyond the scope of this small post; read the online documentation for more information.

One last note: theoretically, you don’t need the Flex SDK installed, since the AIR SDK package already includes the tools necessary to compile AIR-only, ASC 2.0-only content. The Flex SDK is still required by some IDEs, however, so it’s wise to have it available too. I have updated the above instructions to ignore this altogether, as ASC 2.0 is now pretty mature and supported by most (all?) of the IDEs out there.

Development and debugging

The beauty of developing AIR applications is that you can test your content on the desktop most of the time, only deploying to the device when you need to make sure performance and memory usage is OK, or to make sure it works with the input interface of the target device. This is the workflow I use for Kana Mind, and it really speeds up development.

In that sense, what you should do is have a command line or a compilation profile for several different situations. How you do this will change depending on your IDE and project workflow, but in general these are the testing/deployment profiles I use:

  1. A desktop debug profile. You will use this for most development and testing. Things will compile and launch in seconds, and you don’t need to use the device or switch screens for testing since the application is launched on your computer.
  2. An Android debug profile. You will use this for testing elements of your game that can be constrained by the device’s capabilities. Overall performance, memory usage, and device input fall into this category. This can be used quite often too, depending on what you’re testing.
  3. An Android release profile. This will be used when compiling the final, optimized, non-debuggable version of your executable. This will also be faster and use less memory than a debug version, so it should be used for the final round of testings too.

Code-wise, make sure that you:

  1. Use a framework for hardware-accelerated graphics. While this is not a hard requirement, and it can make development more difficult (you lose some of the flexibility of using Flash’s typical vector drawings), it’s an absolute necessity if you want to unleash all the potential the OUYA can offer (or any other mobile device, for that matter). Starling is the standard recommended framework for 2d graphics. If you’re looking into 3d content, you should take a look at Stage 3D or any of the libraries that make use of it.
  2. Use the GameInput API to support the OUYA controller. Do not use “Native Extensions” for gamepad support. Native Extensions are a great way to add support of certain native features to Adobe AIR, and it was needed before the OUYA gamepad was officially supported, but it is not recommended anymore.

OUYA Setup

Finally, at some point you’ll need to test on the device.

  1. Turn on your OUYA, connect it to your computer via the micro USB input, and get it to be recognized as an Android device. You don’t need to download the ODK. Still, this is a somewhat involved process, but then again it’s nothing new if you’re already had to setup drivers for some random Android device.
  2. The OUYA has its own manifest requirements that you should be aware of before publishing. Search for “OUYA intent category” on the ODK setup page for more information.

Using the OUYA for debugging can be somewhat annoying, since you need a separate monitor, so keep that in mind. In any case, you can have both the OUYA and your computer connected to the same screen and then keep switching the input of your main monitor (as I’m doing until I can get an HDMI/DVI adapter for my second monitor… ugh).

While it is theoretically possible to run OUYA-like specs as an emulated device on your machine, I wouldn’t really recommend it. Unless you have the right combination of hardware (for performance acceleration) and spend a good amount of time getting the right virtual machine images, Android emulation always gives you terrible performance. It is instead much better and faster to test your game as a normal (desktop) AIR application, and then deploy and test in the device when necessary.



18 comments posted on “Using Adobe AIR to create OUYA games”

Nice Article! :D
I look forward to buying my ouya and start developing.
And with Adobe Scout everything is easier.


Posted by Rafael Lima on 1/July/2013 at 12:00 ·

    Just tested Scout now. Holy shit it is amazing. I knew about it but hadn’t tested it yet; didn’t expect it to be this awesome and easy. Very nice. Yes it’d be great for testing on the device. Thanks for reminding me to give it a try!


    Posted by Zeh on 1/July/2013 at 16:38 ·

Thank you for the nice recap :) it’s a long time since my last experiment (http://www.noriste.com/lg-smarttvs-adobe-air-3-0-and-app-test/) and I’m waiting for both Ouya and GameStick :)


Posted by NoriSte on 2/July/2013 at 4:08 ·

developing games still doesn’t look very fun on these platforms. too many API soup.


Posted by owen on 2/July/2013 at 13:50 ·

Great article!
I’ve been doing some tests with the GameInput class and I’m getting it to run fine on the OUYA, but it’s not very developer friendly.

You mention, and I agree, that it’s best to do testing in development on your desktop machine. Did you manage to get a working test environment? With controller support that is? It seems GameInput is not supported in AIR 3.7 for desktop.


Posted by Skavank on 3/July/2013 at 20:04 ·

    Yeah, GameInput is *only* supported on Android (personally I believe they’ll expand to desktop/iOS in the future, but for now it has isSupported set to false on these platforms).

    What I’ve been doing for my testing is just having a secondary input method (e.g. the Keyboard’s left arrow for left, ENTER for a given OUYA button, etc) just so I can test the basic functionality. It adds a layer of complexity since you track those events in a different way, but it’s good enough for testing.

    (I’ve been building a class specifically for this kind of stuff – uninspiredly called “UniversalBinder” right now – and I’ll publish it here as soon as it’s ready for prime time)


    Posted by Zeh on 4/July/2013 at 8:13 ·

      The beta version of AIR 3.8 actually supports GameInput on PCs. It registers both my Playstation 3 controller and the OUYA one. It looks very limited / unfinished right now though. I was unable to register any Event.CHANGE and all the controls seems to be mapped to the same non-existent control without values.

      I guess you could use something like JoyToKey (joypad to keyboard middleware) to mimic how the controls feel in the game instead of using the actual AIR classes.


      Posted by skavank on 4/July/2013 at 9:49 ·

      After further testing I noticed a typo caused all of my controllers to be traced as the same. Also, the PS3 controller apparently goes into some form of sleep mode if you don’t touch its middle button for a while (the controller is still detected by Flash, but none of the buttons are being sampled).

      So after some tinkering – mainly fixing my own mistakes – I got the controller responding on my Macbook like it should by using AIR 3.8!


      Posted by skavank on 4/July/2013 at 13:59 ·

        Awesome! Great to know, thanks. I was under the impression AIR would eventually support more devices/profiles with GameInput, but they didn’t mention anything on the changelog for 3.8, so I thought it’d still take some time. Good to know it didn’t!

        Can’t wait to play with this more.


        Posted by Zeh on 8/July/2013 at 10:25 ·

Beautiful article!

Well written, with a lot of references to useful information and guidelines.
Just when you thought that Flash is fading away and that during Adobe MAX this years they did not even mention it once, you came across such a great article.

Kudos !


Posted by Guy Shalev on 8/July/2013 at 6:04 ·

Great article. Actually all you need is FlashDevelop + Adobe AIR SDK + Andaired. :)


Posted by Jenifer on 9/July/2013 at 18:04 ·

Brasileiro não é?


Posted by Pikachu on 30/July/2013 at 13:25 ·

This might be a dumb question. I’ve been using Flash for years – but mainly to export exe and swf files. I’m a little confused as to how or if Flash (i.e. Flash CS 5.5 Pro) fits into the mix. I mean is it possible to create games in Flash and export them for use in Ouya?


Posted by Dave on 19/August/2013 at 16:49 ·

    Yes. You do so in the same way you’d export an Android application (an APK). If you can do that, you can compile something for the OUYA. This might help:

    http://help.adobe.com/en_US/air/build/WS901d38e593cd1bac-2ae4ef8612b2d078909-8000.html

    You may also need some tinkering to include OUYA icons so it’ll be a valid APK:
    http://forums.ouya.tv/discussion/1771/icon-using-air-flash-pro

    But, as I side note: I really, really, really don’t like that approach. I believe using the Flash IDE to create projects is, in the long term, more trouble than it’s worth. I’ve used the IDE for the longest time, since Flash 2, but then I moved to other editors to edit my .AS files and then finally moved to an external compiler to compile my work (Flex SDK, ASC 2.0) , and I think it’s a much better worflow. For one thing, you don’t depend on a clunky IDE. For another, you can update it/do whatever via the command line without expecting the IDE to support it (not to mention it’s free).

    I do use the IDE from time to time to create static, code-less SWFs to hold symbols that I later [Embed] on my classes. But that’s about it (and those SWFs could be created with a lot of other tools too). But As far as creating a .FLA project inside the IDE that holds my executable logic, I’d really stay away from it.

    I understand why people use it (it’s quick and easy, and setting up Flex can be a pain in the ass) but it’s a sort of a dead end.

    This video shows a bit of my workflow (using FDT to develop and debug, and Flash to create SWFs):
    http://www.twitch.tv/zehfernando/b/329945809

    It’s sort of super long (5 hours!) but at around 40-50 min you can see the whole process.


    Posted by Zeh on 19/August/2013 at 18:11 ·

Update about Joystick in Flash Player:

Example GameInput API FlashPlayer:

http://ics-web.jp/lab/archives/512 ( Google Translator in English )

Live Demo:
http://ics-web.jp/lab-data/130729_gameinput_demo/gameInputChara.html

;)


Posted by Rafael Lima on 21/August/2013 at 9:08 ·

Great article. I have gotten an AS3 based project working but the size/orientation is wrong when I run it on the Ouya. It runs it in a small vertical slice of the screen (like a phone) and then runs my horizontal app in that – making it really small. Any ideas on getting the width, height and orientation right for the Ouya? When I run it locally with -profile tv it looks fine.


Posted by hslice on 21/August/2013 at 10:04 ·

    I had that problem too. It’s likely a problem with your AIR descriptor XML. For reference, what I’m using for the “initialWindow” part of the XML:

    * fullScreen: true
    * autoOrients: false
    * aspectRatio: none (empty/no tag)

    Interestingly enough, depending on the IDE you’re using, this may make the *desktop preview* wrong. In that case you may need to fix the preview window sizes to the correct dimensions. In FDT, I have a “OUYA” simulator resolution with a size of 960×540 as I normally preview at half the resolution. This is the opposite ratio of how resolutions are handled in FDT since normally you have a taller pixel dimension (since you’re dealing with phones). Should be more or less the same for other IDEs or for command line arguments I think.


    Posted by Zeh on 21/August/2013 at 10:59 ·