Setting Up OUYA for Unity

(This article originally appeared at third-helix.com)

OUYA devkits have been in the hands of Kickstarter backers since the beginning of the year, but I’ve only just recently gotten around to setting mine up to work with Unity. I ran into a bunch of stumbling blocks along the way, but now that I’ve got everything up and running I thought I’d write up my experiences and fixes in an easy-to-use step-by-step guide.

More...

A couple notes first:

Ok, let’s get to it!

Android SDK

Since OUYA runs on Android, you’ll need the Android SDK. Go to http://developer.android.com/sdk/index.html and click the big blue button on the right, “Download the SDK (ADT Bundle for Mac)”. Unzip it directly to wherever you want to install it; I just dragged the adt-bundle-mac-x86_64-20130219 folder directly into Applications.

Open a Terminal instance and execute the following two commands (adjust the path if you installed the SDK somewhere else):

The Android SDK Manager will open. It looks like this:

Check the packages you want to install, as shown in the screenshot. They are:

Click “Install Packages”. A license window will pop up; check everything on the left and click “Accept Licenses”. Wait for everything to download and install.

Once that’s done, you’ll also need to install the Android NDK. Download it from http://developer.android.com/tools/sdk/ndk/index.html and unzip it somewhere; I simply dragged the ndk folder into Applications/adt-bundle-mac-x86_64-20130219 to keep it with the SDK.

There is a bug in NDK version r8d (current as of this writing) that you’ll need to fix manually. Navigate to ndk/build/gmsl and open the file __gmsl in a text editor. Replace line 512 with the following:

Save __gmsl, and you’re done setting up the Android SDK.

OUYA Development Kit (ODK)

Download the latest ODK from https://devs.ouya.tv/developers/odk and unzip it somewhere; I simply dragged the OUYA-ODK folder into Applications/adt-bundle-mac-x86_64-20130219, even though it’s not technically part of the Android SDK, just to keep all this stuff together.

For reference, this is what my final SDK install directory looks like:

Unity Project Setup

Launch Unity and create a new, blank project. Your first order of business will be to import the core ODK. Go to “Assets -> Import Package -> Custom Package” and navigate to OUYA-ODK/Packages/Unity. There are three packages here, but you only need one: OuyaSDK-Core.

(The other packages are OUYA samples and an NGUI distribution upon which they depend, in case you’re curious. For this guide, we are not.)

After importing the OuyaSDK-Core package you’ll probably see some script errors. Unfortunately package version 0.0.5.1d (current as of this writing) contains a few bugs that you’ll need to fix manually:

These should clear up any script errors, as well as inoculating us against a problem that otherwise would’ve killed our build dead in its tracks here in a few minutes.

Next, go to “File -> Build Settings”, then select Android as your platform and click “Switch Platform”. I also set Texture Compression to “DXT (Tegra)” and checked “Development Build”.

Click into “Player Settings” and pop open the “Resolution and Presentation” section, and set the Default Orientation to “Landscape Left”.

Now pop open the “Other Settings” section and set the Minimum API Level to “Android 4.1 ‘Jelly Bean’ (API Level 16)”, which matches the Android OS version on the OUYA hardware.

Bundle Identifier

Your game must have a unique “bundle identifier” which is used in a number of places. If it’s invalid or doesn’t match across the board, your game will either fail to build or fail to run, so it’s important to get this part right.

First, you need to come up with a bundle identifier. These are expressed in reverse-domain notation, usually something like com.CompanyName.ProductName. Note that you can only use alphanumeric characters and underscores, and the first character must be a letter.

Now you need to enter that bundle identifier in three places:

The OUYA Panel

Back in Unity, go to “Window -> Open OUYA Panel”. It looks like this:

This panel shows you a bunch of information about your build environment. If anything is grayed out, or displayed in red, then something is wrong. Most notably, if “App Java Pack” and/or “Manifest Pack” are shown in red, then that probably means there’s a bundle identifier mismatch somewhere: double-check the steps in the previous section and make sure there aren’t any dumb typos or anything.

Click through the five tabs across the top and make sure everything is in the clear: nothing grayed out, nothing highlighted red. (On the Android SDK and Android NDK tabs you may need to click “Select SDK Path…” and navigate to your SDK/NDK install folders; you should only need to do this once, ever.)

Once all that’s resolved, click back to the OUYA tab and click the “Compile” button. This will compile a bunch of, um… stuff. That you need. It’s rather opaque. You should only need to do it just the once, though (unless you change your bundle identifier in the future, in which case you’ll need to recompile everything).

Create a Test Scene

Create a new scene, and create an instance of the OuyaGameObject prefab in it. This object “communicates with the Ouya SDK” and it’s necessary to have one. You only need one, though: it’s got DontDestroyOnLoad set, so ultimately you can toss it in your intro/startup scene and never have to think about it again.

You need to make one change to it, though: on the instance you just added, set the DEVELOPER_ID field to your OUYA developer UUID. This is displayed on the landing page at https://devs.ouya.tv/developers once you sign in.

App Name and Icon

Your app’s display name — as displayed to players in the OUYA dashboard — is contained in Assets/Plugins/Android/res/values/strings.xml. There’s only the one string (called “app_name”) so this should be pretty straightforward.

Your app icon is located in Assets/Plugins/Android/res/drawable/app_icon.png. Simply replace it with a 96x96 icon of your own devising. (I recommend doing this soon if only because the default icon is shockingly ugly and I promise you don’t want it associated with your game any longer than it needs to be!)

Build and Deploy

Connect your OUYA to your computer using the supplied USB cable (note that it’s mini-USB at the OUYA end!) and turn it on. It probably goes without saying, but make sure it’s connected to some kind of display, too. ;)

In Unity, go to “File -> Build Settings” and add your test scene, then click “Build and Run”. If all goes well, your test scene should (finally!) come up on the OUYA in a few moments!

Once your application is running, double-tap the home button on the controller to return to the OUYA system menu. From here you can re-launch the game (or any other installed builds) by going to “Make -> Software”.

Have a Drink!

Seriously: after all that, maybe consider having two. ;)

Let me know in the comments if you run into any errors in this guide, particularly with respect to any ODK and/or Unity plugin updates I might've missed, and I'll update the article accordingly.

Happy OUYA-ing!

(Josh Sutphin is an indie game developer, former lead designer of Starhawk (PS3), and creator of the Ludum Dare-winning RTS/tower-defense hybrid Fail-Deadly. He blogs at third-helix.com and tweets nonsense at @invicticide.)