Libgdx on Ouya

Libgdx runs perfectly fine on Ouya, there are however a few things to note which are special. The following article will discuss these things.

Ouya Overview

Ouya is pretty much just like any other Android device. At the moment it runs Android 4.1 Jelly Bean. The biggest difference is that there is no normal application launcher. Instead, Team Ouya provides its own launcher, which is a user land application you can install on other Android devices for testing.

An Ouya is controlled by one or more Ouya controllers, which are connected via bluetooth. You can pair other bluetooth devices as well, such as mice or keyboards. The Ouya controllers have 2 joysticks, 2 triggers on the back, a d-pad, 4 buttons on the left, labeled O,U,Y and A, two shoulder buttons, and a system button which is used for pairing and other related things. The buttons are mapped to Android keys, e.g. the ‘A’ button maps to Android’s back button. Controllers also have a touchpad each, which will bring up a mouse cursor on screen when touched. Currently, there does not seem to be a way to disable this mouse cursor. Multiple controllers will compete for the cursor when their touchpads are used, which may look a tad bit weird in actual games.

An Ouya is assumed to be connected to the net via Wifi or the integrated ethernet port. I’m not 100% certain if both Wifi and ethernet will be available in consumer kits.

An Ouya also sports a standard USB port and a micro USB port to which you can connect devices, pair your Ouya with your development machine for debugging and so on. I’m again not certain which of these ports will end up in the consumer version.

The Ouya has 8GB internal storage, at least the dev kits do. This might be extended by connecting a mass storage device via USB, however, i did not test this yet.

The Ouya is powered by an overclocked NVIDIA Tegra 3 chip. It should be noted that Tegra 4 is to be released soon, and has already been demoed extensively. Ouya currently has no plans to upgrade to Tegra 4. Shouldn’t make a lot of difference for simpler games.

The Ouya can connect to displays via HDMI and supports 720p and 1080p. Note that an Ouya device can not correctly report the pixel density (pixels per inch) due to using HDMI, so don’t rely on that. Detect whether you run on an Ouya device, then check the screen resolution, select your assets accordingly.

At the moment it seems that applications can not be paused, but will be quit if you get back to the launcher via the system button on the controller. For some applications that fire up the integrated browser, this might be a problem. I’m not sure if this is on purpose and if and how one can prevent this from happening.

Games published on Ouya must have a trial/demo version. There are no paid apps on Ouya. Instead, one can integrate in-app purchases to monetize ones game. In-app purchases are handled through Ouya, Google Play is not available on Ouya. APKs can be side-loaded on dev-kits, whether this will work on the consumer version is unclear to me.

Here’s a small video demoing the Ouya and it’s controllers so you get a feel for what you are working with:

Ouya Development Kit

The Ouya Development Kit (ODK) provides you APIs for in-app purchases as well as handling controllers. If you use libgdx, you might prefer using our gdx-controllers API instead of the one provided in the ODK. It supports a few more features and does not produce garbage to be collected by the garbage collector. If you don’t care for in-app purchases, you do not have to include the ODK at all in your game.

Integrating in-app purchases with your libgdx game

In general you want to wrap the ODK APIs as outlined here. This allows you to have a stub implementation for your desktop testing environment. You will need to put the jar files from the ODK’s libs/ folder into your Android project’s libs/ folder.

How the IAP API of the ODK works is explained in the ODK documentation. If you don’t use IAPs, you can savely ignore the ODK all together.

Manifest Modifications and Launcher Image

Ouya has its own application launcher. For the launcher to recognize your game, you have to add an entry to your AndroidManifest.xml file of your Android project:

<activity android:name=".GameActivity" android:label="@string/app_name">
  <intent-filter>
    <action android:name="android.intent.action.MAIN"/>
    <category android:name="android.intent.category.LAUNCHER"/>
    <category android:name="ouya.intent.category.GAME"/>
  </intent-filter>
</activity>

Simply add the last filter called “ouya.intent.category.GAME” to your activity’s intent-filters and your game will show up in the Ouya launcher.

The image displayed by the launcher for your app is located at “res/drawable-xhdpi/ouya_icon.png”. It must be 732×412 for games or 412×412 for applications

Ouya Controllers

We warmly recommend using the gdx-controllers extension to interact with the Ouya controllers. One of the benefits is that it is cross-platform, and allows you to add controller support for the desktop as well as standard Android. It also supports disconnect/connect events for controllers as opossed to the ODK controller API. Judging by the decompiled source of the ODK, you might also run into GC issue, as it seems to generate quite a bit of garbage due to the use of boxed primitives. Long story short: use the gdx-controllers extension.

We won’t go into depth about the gdx-controllers extension as it is explained in more detail in the other article. Instead i’ll just reiterate the Ouya specific bits.

To detect that you are indeed running on an Ouya device, you can use this snippet:

if(Ouya.runningOnOuya) {
   // you are running on a real Ouya device
}

The ApplicationType reported by Applitation#getType() will still return ApplicationType.Android, as Ouya is in fact an Android system.

Note that simply detecting that an Ouya controller is connected is not enough, these can be paired for normal Android devices as well.

We provide Ouya button and axis codes for use with the gdx-controllers extension via the Ouya class.

To check if a controller is an Ouya controller you can do this:

if(controller.getName().equals(Ouya.ID)) {
   // controller is an Ouya controller
}

Once you know that it’s an Ouya controller, you can use the constants from the Ouya class like so:

boolean buttonO = controller.getButton(Ouya.BUTTON_A)
float leftXAxis = controller.getAxis(Ouya.AXIS_LEFT_X);

Note that the joystick axis of the Ouya controller might not snap back to their zero position entirely. That’s a common problem with joysticks. You should use a dead zone, meaning, you ingore any absolute axis values < 0.3.

Note that a user can connect other input devices to the Ouya as well. For keyboards and mice you'll get your standard input events as reported by Gdx.input and InputProcessor. They might be reported by the gdx-controllers extension, so make sure to ignore those if they are not Ouya controllers! The ODK controller API does not ignore those and will happily return them to you as well.

UI Guidelines

The Ouya team has put together interface guidelines for games to be run on Ouya. The button mappings you see there should be used in menus if applicable.

Where’s the Pause Button?

Ouya controllers have no dedicated pause button. The system button is reserved for bluetooth pairing and turning the controller off. There was some pretty intense discussion of this issue on the Ouya developer forums. Suggestions ranged from each game assigning a button to the pause functionality, to overloading the system button. Thankfully, the overloading solution won and was officially embraced by the Ouya team. A short press of the system button will send an intent to your Android activity, telling it to bring up a pause menu. A long press of the system button will bring the user back to the Ouya launcher.

This solution has not been implemented yet. We’ll integate this functionality into the gdx-controllers package. In all likeliness, we’ll send the libgdx application a “pause” key event to which you can react.

Note that this sort of pause is not the same as the application losing focus. Your game will still be running, and you should display a pause menu!

  • dix

    I wonder if you can plug in a usb device on that port, like.. a keyboard a mouse a joypad a joystick a webcam(I think I saw some kinect-like opensource project using a webcam some where on the Net) etc… but mostly I’m curious either a controller would work just fine or not

    thanks for your report and the video =)
    I didn’t notice they removed the pause button in the other videos I checked out
    That’s big. I wonder what were they thinking

  • http://badlogicgames.com Mario

    Should have been more clear in the video. You can attach and HID to the Ouya via USB or Bluetooth and it will generally just work. This is especially true for keyboards and mice.

  • http://www.binarygalactic.com Greg

    Mario,

    Thank you very much for adding Ouya support to libgdx. I didn’t imagine it would happen so quickly! I have the hardware so I’ll be working with this soon!

    Thanks again.
    Greg

  • Relu

    Very thanks to add this :) I have much to learn ! :) i don’t have the hardware yet too but i could simulate my game in desktop version thanks libgx.
    Great job guys!

    Cris =)

  • rumplestilzken

    Just wanted to let you guys know (incase you already didn’t), the latest change log says they removed the auto boxing of primitives in their OuyaController class. However they don’t mention fixing the input issue with keyboards and such. Keep up the great work guys!

  • http://badlogicgames.com Mario

    All the Ouya controller stuff does is build on the existing Android peripheral APIs. It does so in a way that it’s unusable for non-Ouya controllers. There’s no real incentive for us to use their library. Thanks for the heads-up!

  • rumplestilzken

    I was under the impression that the OuyaController class also interfaced well with the Xbox360 controller. However i haven’t had a chance to test it, i will not be getting my Ouya until June :/.

    But i have started using your controller extension in my framework/engine i am building, and its working very all. All but the non-focus crash, however i saw that that issue was fixed, and i assume is in the nightly build.

  • http://www.redantgames.com/ Jason McMillen

    Using libGDX for our premier commercial release this spring/summer and also backed Spine. (with goodies!) You guys rock. Sweet article!

    Subject 33 (http://www.redantgames.com/subject33/) will be rockin’ the libgdx and will be out for mobiles and the OUYA sometime this year.

  • http://alchemedium.com Ryan Brolley

    I am also using libGDX and the recently purchased Spine for release on OUYA, desktop, and hopefully more!

    “A Tofu Tail” (http://alchemedium.com/games/) is our first game and libGDX has really been a huge help in learning how to build a game and coding everything. :D

    Thank you (and everyone else who has contributed to this project) for providing us all with the tools to make awesome games!

    -Ryan

  • http://semtiko.com/ SEMTiKO

    Hi. As i understand my previous comment not posted, don’t know why. Anyway i’ll try again:
    “ouya.intent.category.GAME” must be “tv.ouya.intent.category.GAME”, docs – https://devs.ouya.tv/developers/docs/setup