How To: Support Android Game Controllers

Important Use Notes

This document tends to stop its focus around API14. API functionality after API14 is not contained in this document. However, the basics of Device Input have not changed and all information contained below is relevant learning. A developer will gain a strong foundation on Android Device Input.
This document currently focuses on controllers in Android. In the examples below the Android Java APIs are used extensively. Even for developers that are not using the Java APIs, the concepts are important for someone unfamiliar with controller input on Android, and translate well to using the NDK.
As of this writing, using Java is the only officially supported method to get controller events. However, there is a section under Important Controller Considerations describing controller use and the NDK.
Developers experienced in controller/device input may want to jump right to the Important Controller Considerations chapter as this has practical and important information not covered in the Android documentation. This chapter is designed to be useful for all levels of developer.
Game controller support was added in Honeycomb 3.1, which is API Level 12. This document relies on API Level 12. If your title needs to be compatible with pre-API 12 games while supporting game controllers, please see the Important Controller Considerations chapter.

Introduction

Mobile gaming applications that add support for alternate control methods like keyboard or joystick can transform the gaming experience from that of a basic tablet into a compelling, immersive gaming experience. The intention of this document is to help Android game developers add support for such controllers. The document will outline the process of coding for basic use of keyboard, wired controllers, and Bluetooth controllers in gaming applications. We will use a fictitious 2-player game’s controller system as a guide for learning the new methods. The idea is to focus on the parts of code related specifically to controller use. Note that when we use the word “controllers,” we include keyboards along with the more obvious joysticks and gamepads.

First, we will review a class that saves the controller state. This class can return data to the application such as whether the B button pressed or the current position of the joystick. This provides a basic foundation for many controller concepts without clouding the discussion with the complexity of game logic.

Having reviewed the lower-level input device support code, we will discuss how the application receives and dispatches the events in the first place; the application’s Activity class. This class is where all of our game logic exists, as well as where all the controller inputs are received and initially processed prior to passing to the processing functions. The Activity is where the player’s input is translated to in-game actions on screen.

Now that we have a good foundation on device input, we will move on to exploring practical issues that a developer may run into. This final section called Important Controller Considerations will contain common developer pain points, advanced topics, and other issues pertaining to device input. This chapter should not be skipped by any developer, advanced or otherwise. From version to version of this document, this will be the chapter that will change the most.

Why add game controller support?

A 2012 report by the market research firm, The NPD Group, has shown some massive growth in mobile gaming. This report showed that close to 50% of gamers have opted to explore gaming apps exclusively deployed on mobile devices. It also showed that 23% of gamers declared their intention to focus on mobile gaming.

It’s likely that console-style hardware will further accelerate hard-core gamers' shift to the mobile platform, a Credit Suisse report states. Software is becoming, "less tethered to dedicated console hardware."

Now that we can see the tide of both casual and hard-core gaming coming toward the mobile platform, controller support can add real gaming differentiation. In the near future, for higher-end gaming, controllers may be essential.

Consumers seem ready. On Kickstarter, a Bluetooth connectable gamepad called iMpulse reached its funding goals 25 days ahead of its deadline. Further, in 2012, at least three major controller manufactures will be releasing gaming controllers specifically for the mobile market. All of these manufactures have worked with NVIDIA and its "Built for Tegra" program to come up with a controller specification to ease development (see Important Controller Considerations).