Important Controller Considerations

Our Recommendations

Always allow users the option of using a game controller instead of touch.
When using SHIELD, use it as a proxy for an Android set-top box with a game controller.
Auto-detect the presence of controllers, and when present, default to them. (If they are using a game controller, they could be nine feet from a screen that doesn’t have touch.)
When using controllers, hide any on-screen “virtual controls."
Provide on-screen guidance regarding which buttons do what. Compliant controllers all have the buttons that are outlined in The Amalgamated Gamepad. (A, B, X, Y, etc. are all expected.)
As an example, a good game to reference is Quell Reflect from Fallen Tree Games.
Expect that multiple controllers are possible, and that a user may decide not to use the first enumerated controller (just like on PlayStation).
Do not specifically support one brand or Product ID controller. Tell the user that your game supports Built for NVIDIA Tegra (and other Android HID-compliant) controllers.
Your Android Manifest must include the following:
```
<uses-feature android:name="android.hardware.touchscreen" android:required="false"/> 
```
The importance of this cannot be over-stated. If this code is not in your Android Manifest, then Google Play will hide your games from the tens of millions micro-console and set-top box style devices that will begin shipping in the next few months.

Controllers in the NDK

This section is currently in development.

In the Tegra Android Development Pack, there is a sample (native_gamepad) showing controller support in native code.

The native game controller sample shows how to discover (at the Java level) the available game controllers, buttons and axes, and how to handle gamepad buttons and axes in native code. The NVIDIA support library, nv_input is used to query a non-NDK Android function to add native support for analog joystick axes.

Backward Compatibility

Honeycomb 3.1 (API 12) is where game controllers really became available to Android developers. The goal of this document is to show how to easy it is to add game controller support which requires the use of API 12 or better.

We realize that some older applications are not developed with Honeycomb 3.1+ in mind. Since we want to have the ability to use the latest that 3.1 has to offer but still be able to run on a breadth of older Android devices, we need some forethought before designing our control system. At a high level, this means having touch controls for pre-3.1 devices and game controller controls for 3.1+ devices.

One simple way is to create two separate applications: one for pre-3.1 and one for 3.1 and above. A common split uses higher definition graphics on the 3.1+ version since most devices running 3.1+ are more powerful and the "normal" graphics on the pre-3.1 version.

Another way is to use the "Multiple APK" support in Android. In short, this allows you to use multiple APKs for different APK levels, in turn allowing your application to be under one entry in Google Play. An excellent guide is here:

http://developer.android.com/training/multiple-apks/api.html

The above methods may not be desirable, especially when retro-fitting older applications with controller support.

The presumption, going forward, is we’d like touch controls on pre-3.1 devices but still be able to use all that 3.1+ provides like controller support in a single APK. Honeycomb 3.1+ allows for both USB Controllers and Bluetooth HID Controllers. Fortunately, the code path for both is the same. Android takes care of how a controller is connected for you.

In order for this approach to work with devices from API 12+ to API 1, a game would need to compile under API 12+ even though its manifest claims an earlier API. This is perfectly valid as long as care is taken in calling only APIs that are available, given the OS. Part of the page below discusses checking the Android Build Version at runtime:

http://developer.android.com/training/search/backward-compat.html

For instance, a game running on pre-3.1 would not want to react to anything but touch type events. A check during initialization for what API level the OS is would be helpful. Then appropriate action could be taken when the game’s input system is run.