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:

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:

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:

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

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!

Gdx Controllers Extension & Ouya Support

Nate and I have been working on a new extension for gamepads and joysticks. The endresult is gdx-controllers, our first extension to have different backend implementations per platform (other extensions were usually just cross-compiled JNI wrappers, using the same Java code on each platform).

The goal of this extension is to provide the following functionality:

  • Enumerate connected controllers
  • Support for buttons, axes, sliders, POVs and accelerometers per controller
  • Listen for controller events globally or per controller
  • Poll controller state

We tried to keep the API as small as possible, with the potential for future additions. No initialization is necessary, the underlying backend will initialize automatically.

Enumerating Controllers

One or more controllers might be attached to your PC/device. The Controllers class has methods to to query for currently connected devices:

The order of controllers in the Array returned by Controllers#getControllers() is usually the order in which the controllers were connected. However, you should not rely on this. See the section on (dis-)connecting devices below.

All methods of the Controllers class must be executed on the rendering thread, that is, in any of the methods of ApplicationListener.

Polling Controller State

Once you have a Controller instance, you can ask it for its current state. A controller can have different components:

  • Buttons: this includes your usual ‘X’, ‘Y’ buttons as well as the d-pad on some controllers. A button can be pressed or released.
  • Axes: usually provided via analogue sticks. An axes has a value between -1 and 1, with one being the neutral center position.
  • POVs (aka hat switches): provide discrete directional state, e.g. north, east, west, south-east and so on.
  • Sliders and accelerometers: these are in the API but currently untested.

A classic controller example is the XBox 360 controller:

It has a left and a right analogue stick, each with an x- and a y-axis, triggers on the back, each representing a single axis and various buttons and a d-pad, which might either be reported as buttons or as axes.

Polling for the state of a specific component is pretty simple:

Each component has its own code (analogous to key codes or scan codes for keyboad keys). This code is controller specific, e.g. the X button on an XBox controller likely has a different code than the X button on a PS3 controller. We’ll come back to this issue later.

Event based Controller Input

When polling a controller, you might lose some input events. For some tasks, event based input is also more suited than polling based input. We hence provide you a way to register listeners to receive controller events, either globally for all controllers, or for a specific controller. The interface you have to implement to listen for controller events is called ControllerListener:

Each method receives the Controller instance for which the event was triggered. The first two methods are called when a controller is connected or disconnected. The next two methods report button press and release events. Both receive a buttonCode identifying the button that was pressed or released. The axisMoved method is called when an axis value changed, and so on. The methods should be pretty self-explanatory.

A ControllerListener can be either added to Controllers, in which case it will listen for events from all controllers, or to a specific Controller, in which case it will only receive events from that controller:

If you don’t want to implement all these methods, but only a select few, you can subclass ControllerAdapter

You might have noticed that some of the listener methods return a boolean. This is used if multiple listeners were registered globally or with a specific controller. If such a method returns false, the event will be handed to the next listener. If the method returns true, the event will not be propagated any further.

All listener methods will be called on the rendering thread, just like in case of a normal InputProcessor.

Mappings and Codes

As stated above, different components have different codes. These codes are not standardized, so we have two options when dealing with controllers:

  • Hardcode the codes for a specific controller, e.g. the Ouya controller
  • Let the player configure the controller bindings, e.g. running through each action and asking the player to press the corresponding controller button, axis, POV, etc.

We currently have the codes for the Ouya controller buttons and axes. To check if a controller is an Ouya controller, you can do this:

You can also check if you are currently running on an Ouya device:

You can pair Ouya controllers with normal Android devices as well, that’s why it might be interesting to know whether you are actually running on an Ouya device.

We’ll add more mappings in the future for popular controllers, e.g. the Xbox 360 and PS3 controllers.

Note that those codes can be different for the same type of controller depending on the operating system. My cheap Logitech controller gets code 0 assigned for its x-axis on Windows, and code 1 on Linux and Mac OS X. For mappings and codes found in the com.badlogic.gdx.controllers.mappings package, like the Ouya class above, we’ll make sure the codes work on all operating systems.

In the end its best to let the user decide how she wants to use her gamepad with your. Writting a simple config dialog that runs through actions and asks the user to press a button is easy to do. You can then save those mappings to a file, in combination with the controller name, and reload and reuse them for the next session of that user.

Controller (Dis-)connects

Currently controller (dis-)connects are not reported on the desktop. However, they work on Android. If your game supports gamepads, make sure to handle device disconnects and connects! E.g. if a controller disconnects during a game, pause the game and ask the user to reconnect the controller. Note that you will get a brand new Controller instance in that case, so make sure to wire up any listeners correctly. The old controller instance will be reported as disconnected.

Integration into your project

The core API is found in gdx-controllers.jar, add this to all your Eclipse projects. For the desktop you’ll need to add gdx-controllers-desktop.jar and gdx-controllers-desktop-natives.jar to your desktop project. For Android, you need to add the gdx-controllers-android.jar to your Android project. Make sure you export these jars for your Android project, by going to the properties of the project in Eclipse, Java Build Path -> Order & Export, and make sure all jars are checked. Note that Android +3.1 is necessary for gamepads to be detected, and Android 4.1 is necessary to get connect/disconnect events. For older Android versions, nothing will get reported.

Tests & Demos

I wrote a new little test that lets you display the currently connected controllers and event data, called GamepadTest. I also augmented the gdx-invaders demo to support Ouya controllers. Note that the integration is a quick and dirty affair which doesn’t handle disconnects or provides any configuration options.

Win 20.000$ in OUYA/Kill Screen game jam with libgdx

Kill Screen and OUYA are collaborating on a game jam with tons of price money price money.

Libgdx is already working nicely with OUYA, however, we haven’t officially released the support (which basically includes a nice crossplatform gamepad/joystick library). Nate and I plan on publising the following information tomorrow:

  • Docs for the gamepad API
  • How to get up and running with libgdx and OUYA (wiki article)
  • A short video showing you how the OUYA works in real-life, and what to expect

Since pretty much nobody has a dev kit, i offer to test your APKs on the one that the OUYA folks kindly sended to us. Stay tuned for more information and goodies tomorrow.