Requirements
Prerequisite knowledge
Understanding of ActionScript and building Adobe AIR applications for mobile devices. Familiarity with Flash Builder.
Required products
Adobe AIR
Sample files
GameInput.zip (119 KB)
Additional required other products
A mobile device:
  • that supports game controllers
  • running a minimum Android OS version of 4.1 or iOS version of 9.0
User level
All

The ever-evolving gaming arena presents users with a variety of game controllers. As a game developer, you may want to ensure that your applications are well-suited for multiple input devices with varying capabilities and controls. Adobe AIR 3.7 (for Android)/AIR 23.0 (for iOS) offers support for game input devices like joysticks, game pads, and multi-axis controllers, among others. The latest Adobe AIR offering includes the GameInput API for communication with several different types of devices and has provisions for new device types that may be available in the future. You can also choose to use the GameInput SWC for high-level access to the physical controls of the input device.
 
(Android) This feature supports a minimum Android OS version of 4.1 and requires the minimum SWF version 20 and namespace 3.7.
 
(iOS) This feature supports a minimum iOS version of 9.0 and requires the minimum SWF version 34 and namespace 23.0.
 
The design and architectural information, along with the code snippets presented in this article apply to all types of game controllers.
 

 
GameInput API

The GameInput API provides an interface for applications to communicate with the input devices attached to your platform. The API design makes it easy to add support for new controller types whenever you desire to do so.
 
The GameInput API includes classes and methods to interface both at the device level as well as the control level. The API includes properties and methods for operations like retrieving values, enabling devices, sampling control values, among others. The API, however, does not provide mapping between the physical controls (for example, buttons) and their logical counterparts (for example, the DPAD right button or left trigger).
 
See Figure 1 for an illustration of the GameInput API architecture:
 
Figure 1: GameInput API architecture
Figure 1: GameInput API architecture
 
The following classes are included in the GameInput API:
 
  • GameInput class
  • GameInputControl class
  • GameInputDevice class
  • GameInputEvent class
 
GameInputclass
The GameInput class is a static class that provides access to supported input devices. This class is not a singleton in the strictest sense, however, there are no compelling reasons for instantiating more than one instance. Events can be registered on the instance of the class. The methods of the class are static and their scope is restricted to the class and not the instance.
 
The GameInput class enumerates the connected input devices into a list. To access a device from the list, use the getDeviceAt(index:int) method. The numDevices property specifies the number of input devices currently connected to your platform. Use this value to determine the number of devices connected to your platform. The class also features the isSupported flag that you can use for checking compatibility of the GameInput API with your platform. The isSupported flag returns the value true for an Android device running a minimum version of 4.1 and iOS device running a minimum version of 9.0. All other platforms result in isSupported returning the value, false.
 
The following snippet is a depiction of the properties and methods of the class:
 
trace("GameInput.isSupported - " + GameInput.isSupported); trace("GameInput.numDevices - " + GameInput.numDevices); trace("GameInput.getDeviceAt- " + GameInput.getDeviceAt(0));
Each time an input device is added or removed, the corresponding event is dispatched. To listen for these events notifying you about the addition and removal of devices:
 
  1. Create an instance of the GameInput class.
  2. Add event listeners for the GameInputEvent.DEVICE_ADDED and GameInputEvent.DEVICE_REMOVED events. (Events can only be registered on an instance of the class.)
var gameInput:GameInput = new GameInput(); gameInput.addEventListener(GameInputEvent.DEVICE_ADDED, handleInputEvent); gameInput.addEventListener(GameInputEvent.DEVICE_REMOVED, handleDeviceRemovedEvent);
For more information about the class, its properties, and methods, see http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/ui/GameInput.html.
 
 
GameInputDevice class
The GameInputDevice class represents a single input device. This class includes methods and properties to:
 
  • Enable or disable an input device: Devices are disabled by default (enabled is set to false). You must explicitly enable a device, by setting enabled to true, before you retrieve control values from the device.
  • Retrieve the name and ID of an input device: For Android devices, the name and id properties together, uniquely identify a device. The device manufacturer supplies these values. But for iOS devices, the id may change each time you connect the device.
  • Enumerate the controls on an input device: The physical controls on a device are mapped to logical GameInputControl objects and stored in a list. Use the getControlAt() method to access a control in the list.
  • Manage caching of sampled control values: One of the ways to retrieve control values is to sample a set of control values directly from a device object. Sample caching is useful when you need to access control values at a rate faster than the frame rate of the application. The sampleInterval property determines the frequency of sampling and the numSamples parameter specifies the number of samples to cache. The cached sample values are written to a ByteArray in the order they were retrieved.
The following snippet is a depiction of the properties of the class:
 
trace("device.enabled - " + device.enabled); trace("device.id - " + device.id); trace("device.name - " + device.name); trace("device.numControls - " + device.numControls); trace("device.sampleInterval - " + device.sampleInterval); trace("device.MAX_BUFFER - " + GameInputDevice.MAX_BUFFER_SIZE);
To start data caching:
 
var vec:Vector.<String> = new Vector.<String>(); vec[0] = device.getControlAt(0).id; device.sampleInterval = 10; device.enabled = true; device.startCachingSamples(5, vec); // numSamples = 5
Ensure that you always set up a listener for the GameInputEvent.DEVICE_REMOVED event. The listener notifies you when a device is unexpectedly disconnected or powered off. When a device is disconnected, free the associated GameInputDevice object. An Android device that is removed and then reconnected retains the ID it was assigned when it was first connected. You can, therefore, reconnect to a device by matching its ID. But For iOS devices, the ID may change on reconnecting the device.
 
To uniquely identify a device, ensure that you use the id property and not the index value in the device list. Using the index value can result in errors because this order is likely to change when devices are added or removed.
 
For more information about the class, its properties, and methods, see http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/ui/GameInputDevice.html.
 
 
GameInputControl class
The GameInputControl class represents a control on an input device. The GameInputControl class maps the physical controls on a device to simple logical controls.
 
The value property of the GameInputControl class specifies the current value of a control. This method does not return the latest value, but the value that was cached the last time the control was sampled. Use the id, maxValue, minValue properties to access information about each of the device controls.
 
The following snippet is a depiction of the properties of the class:
 
trace("control.device - " + control.device); trace("control.name - " + control.name); trace("control.minValue - " + control.minValue); trace("control.maxValue - " + control.maxValue); trace("control.id - " + control.id);
You can retrieve values from the controls using any of the following:
 
  • Polling: The easiest way to retrieve values from the controls is to poll the controls. Query the control to get the last known value. When you query a control for its value, the hardware is not queried but the last retrieved value is returned.
    trace("control.value - " + control.value);
     
  • Change Events: Register a change event for a controller and query it when there is a change in value. The Event.CHANGE event is dispatched when the value of the control changes. The change event does not return the value of the control. You need to explicitly query the control to retrieve the new value. This change event does not occur for devices that are disabled. The values of disabled controls are therefore, not updated.
    control.addEventListener(Event.CHANGE, handleChangeEvent);
     
  • Caching Sample Values: You can cache sampling data for a particular input device, not for individual controls.  Sampling takes place at specified intervals which may be different from the game frame rate. Use sample caching when you need to access control values at a rate faster than the frame rate of the application.
    Caching for a single control:
     
var ba:ByteArray = new ByteArray(); var device:GameInputDevice = GameInput.getDeviceAt(0); var num:int = device.getCachedSamples(ba, false); for(var i:int=0; i<num; i++) { trace("samplevalue " + ba.readDouble()); }
Attempting to read control values on a disabled device results in an IOError, error. You can, however, access properties like id, minValue, and maxValue even when the device is disabled. This means that you need not enable a device to determine if it meets all your application requirements.
 
For more information about the class, its properties, and methods, see http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/ui/GameInputControl.html.
 
 
GameInputEvent class
The GameInputEvent class represents an event that is dispatched when a game input device has either been added or removed from the application platform. A game input device also dispatches events when it is turned on or off.
 
For more information about the class, its properties, and methods, see http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/events/GameInputEvent.html.
 
 
Detecting a Game Input device from a set of identical devices
When developing games that have more than one player, you need to be able to identify individual players. This means that you may need to detect one device from a set of identical devices.
 
To identify individual devices:
 
  1. Add event listeners to every control on all undetected input devices. These listeners listen for Event.CHANGE events, which are dispatched whenever a control value changes.
  2. The first time a control is activated (for example a button press or trigger pull), the application labels that device.
  3. Remove all of the event listeners from the remaining undetected input devices.
Repeat steps 1-3, as required, to identify the remaining undetected input devices.
 

 
GameInput SWC

The GameInput API provides an interface for applications to communicate with the input devices attached to your platform. The API, however, does not provide mapping between the physical controls (for example, buttons) and their logical counterparts (for example, the DPAD right button or left trigger). You can also choose to use the GameInput SWC for high-level access to the physical controls of the input device. The SWC design makes it easy to add support for new controller types as and when required.
 
 
GameInputControlName
The GameInputControlName class associates information about the physical controls with the input devices from different vendors, and their underlying platforms. The class adds a name to every control associated with the input device. Use this control name to identify the physical controls on a device.
 
GameInputControlName.initialize(device);
 

 
Sample project for GameInput API

 
 
To get started with the GameInput API, see the .zip file attached with this article. This attachment includes the SWC, samples, and the documentation that has been created specifically for the Ouya TV/iOS platform.
 
Ensure that you meet the following pre-requisites before uploading your application to the Ouya store:
 
  • Include an OUYA intent category in your application descriptor for your application or game to be recognized as built for OUYA.
 
 
<intent-filter> <action android:name="android.intent.action.MAIN"/> <category android:name="android.intent.category.LAUNCHER"/> <category android:name="tv.ouya.intent.category.GAME"/> </intent-filter>
  • Ensure that the size of ouya_icon.png, the image displayed in the application launcher, is 732x412. You also need to include an OUYA intent category in your application descriptor.
<icon> < image732x412>ouya_icon.png</image732x412> </icon>
To use the sample provided with this article:
 
  1. Import the GameInputOuyaSample project into Flash Builder.
  2. Build the project by selecting Export Release Build from the Project menu.
  3. Provide the certificate and password information. For iOS device, also provide the provisioning profile.
  4. Install GameInputOuyaSample.apk on the OUYA device or GameInputSample.ipa on the iOS device.
  5. Launch GameInputOuyaSample.apk (OUYA device) or GameInputSample.ipa (iOS device) from the menu.

 
Where to go from here

To learn more about the GameInput API and the Adobe Gaming SDK, use the following resources: