Tutorial: Introduction to game controllers

27 August 2013

Tutorial: Introduction to game controllers

It’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 HID (Human Interface Device) controllers to play games, in addition to the standard touchscreen and accelerometer. While this isn’t yet “utopia,” you can do some really cool things with your wireless device and modern technology.

Key event framework

For HID controllers, we decided to build upon the existing key event framework. Thus, programming for controllers won’t be too much different — no plugins are required for HID-compliant controllers, nor do you need 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", so 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 buttons/keys produce two phases, much like touch handlers. Those two phases are "up" and "down", where "down" means the user has pressed the button and "up" means they have released it. Like touch handlers, you do not “continuously” get events — once you press the button and get the "down" phase, you will not get another event until the button is released, thus dispatching 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 may be warranted.

Putting it together

Let’s look at an example 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 into play. This is handled using the inputDevice type.

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.

Conclusion

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 D-Pad. 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.