hid-vendorsIt’s an exciting time to be a mobile app developer. Through the magic of mobile and Bluetooth support on devices, it’s now possible to use controllers to play games, in addition to the standard touchscreen and accelerometer.

To be clear, this isn’t yet utopia, but you can do some really cool things with your wireless device and modern technology. Before we get to the goodies, let’s talk about what we can do today, and what we will be able to do soon.

Current HID Devices

At the time of this writing, game controllers reside in the world of Android using a host of HID (Human Interface Device) controllers that are compatible with Android 3.1 or later. This isn’t just game controllers, but keyboard, mice, etc. That means that a hardware manufacturer could build a child-friendly controller/case inside which an Android phone or tablet could fit.

Yet the big news, to date, has come from four vendors: OUYA, Green Throttle, GameStick, and NVIDIA SHIELD. Green Throttle allows you to connect certain HDMI-compatible Android devices to a TV and turn them into a gaming console. You can even run it on some Android devices that do not connect to a TV, like the Google Nexus 7, to develop on or even use as a small console. In contrast, the OUYA, NVIDIA SHIELD, and GameStick are standalone gaming consoles. The OUYA is a small cube no more than 3 inches in size that plugs into your TV’s HDMI port and talks to HID-compatible controllers, including the OUYA-specific controller. GameStick goes even smaller, with the entire gaming console in a form factor not much bigger than a USB memory stick — it just plugs into and draws its power from the TV. All of these devices run a customized version of Android designed around a gaming console interface and they support an open development platform that lets indie developers and small studios build games to be played on them.

Corona Support

And now for the best part, at least from the Corona development standpoint: you can now build your own games for these platforms! Even non-game apps could be created for these devices. Over the past few months, Corona’s engineers have been rolling out HID support in phases as part of Daily Builds, available to Pro and Enterprise subscribers. When the next public release arrives, Starter developers will also have ability to program for these devices.

Green Throttle

Let’s start with Green Throttle who does a proprietary implementation for their controllers. To use this system, you need to include the Green Throttle plugin in your build.settings file:

Then in your program, simply require the module:

Finally, code your input system similar to the following. Note that Green Throttle uses a polling system where you need to check for various button and stick states and then react to them.


For OUYA, SHIELD, GameStick and other HID controllers, we decided to build upon the existing key framework that Android users have been using to listen for the hardware “back” button and volume controls. Thus, programming for controllers won’t be too much different — no plugins are required for HID compliant controllers, nor do you have to require() anything special.

Of course, we haven’t provided any code other than returning true because it all depends on what you want to do. The button names may also vary from controller to controller — for example, they may not always be called “buttonA” or “buttonX”. If you are working with a new controller, it’s useful to check the value of the buttons that are pressed.

Button Phases

Note that each of these buttons produces two phases, much like touch handlers. Those phases are “up” and “down”, where “down” means the player has pressed the button and “up” means they have released it. Like touch handlers, you do not continue to get events — once you press the button and get the “down” phase, you will not get another event until the button is released, queuing the “up” phase. Similar to touch events, it’s generally best practice to use the “down” state for time-sensitive actions like movement or firing weapons. However, for UI elements that typically respond like a mouse click, or touch events that trigger when the touch is complete, the “up” state would be warranted.

Putting it Together

Let’s look at a movePlayer() function using event-based buttons:

Detecting Controllers

Most likely, you will also need to know if the controller is attached and also know when it’s detached, or if a new controller comes up during play. This is handled using the inputDevice APIs.

Here are a few notes regarding controller detection:

  • For multiplayer apps, the event.descriptor (i.e. “Joystick 1″, “Joystick 2″) can be used as a unique key that binds a particular controller to a player. This will scan for active devices and set up a table of devices that are currently connected.
  • You should watch for connections and disconnections during gameplay and handle “losing” a controller or adding a controller. You may also want to pause the game if a controller drops out.
  • You might want to hide any UI elements that are specific to one controller, or hide “touchscreen” features when there are controllers present.

And here’s some sample code to handle this:

Note that these status changes will not register if the app is suspended. It’s your responsibility to poll the controllers if you’re resuming back to gameplay state.

On-Screen Button Graphics

Both OUYA and Green Throttle provide graphics to developers for each of the respective device’s buttons. It’s important when building an “in-game tutorial” to include an image of the button that should be pressed for a particular action. While this concept may seem foreign to app developers adapting from the touchscreen, it shows the user which button to press at a quick glance. Note that both vendors offer usability documents about how buttons are expected to behave.


Most game controllers offer both digital inputs (buttons) and analog inputs called sticks or joysticks. Because the typical joystick moves both up and down and left and right, we measure the movement based on which “axis” it’s moving on. An analog stick moving up and down will be measured along its Y axis, while side-to-side movement is measured on the X axis.

Axis input will be covered in a future blog post, but it’s important to know that many game controllers will map the left analog stick to the dPad. As such, moving the left stick will frequently generate “up”, “down”, “left” and “right” events. Also, the bottom shoulder buttons are considered “analog” inputs, but they will generate “button” events when they are squeezed past a certain threshold. If your app needs to know precisely what value those triggers are producing, you would use the axis method of measuring things, for fine-tuned control.

And that concludes today’s tutorial. While this just touches on the basics of HID controllers, you can see why it’s an exciting time to be using Corona SDK!

Taken from: 

Tutorial: Introduction to Game Controllers