PestoForce - as3 gameInput API tutorial and examples

I recently implemented the Actionscript 3 GameInput API in my AIR game Super Chibi Knight.

This class lets you detect input from typical USB game pads like an "Xbox 360 PC Controller" or a "Logitech Dual Action Controller." So, you no longer have to use programs like Joy2Key (or others) that map controller input to keyboard presses. AWESOME! Plug and play!

I found that there weren't many clear examples of how to use this API, so I decided to put this together with hopes that it might help people who are trying to figure it out!

First off, this will only work in AIR 3.7 or later and Flash Player 11.8 or later! If your Flash Player version or AIR version is older than that, NO DICE!

BASICS TO SET UP THE CLASS:
First you need to import the class and detect if your AIR or Flash version supports the class:



					import flash.ui.GameInput;



					trace("GAME INPUT SUPPORTED?: " + GameInput.isSupported);



					//outputs true if your version supports GameInput, false if not

Next we create an instance of the GameInput class and add GameInputEvent listeners (directly to the gameInput class) to handle when a gamepad is plugged in, removed, or has problems:

var gameInput:GameInput = new GameInput();
gameInput.addEventListener(GameInputEvent.DEVICE_ADDED, controllerAdded);
gameInput.addEventListener(GameInputEvent.DEVICE_REMOVED, controllerRemoved);
gameInput.addEventListener(GameInputEvent.DEVICE_UNUSABLE, controllerProblem);



				function controllerAdded(e:GameInputEvent)


				{


					 //put code here to handle when a device is added


					

				}



				function controllerRemoved(e:GameInputEvent)


				{


					 //put code here to handle when a device is removed


					

				}



				function controllerProblem(e:GameInputEvent)


				{


					 //put code here to handle when there is a problem with the controller


					

				}

DETECTING AND HANDLING CONTROLLER INPUT:
When your gamepad is added, it will not yet be "enabled" so we need to enable it to detect its input. We can also get other values related to the controls that will help us detect and use the inputs. We'll put this code in the "controllerAdded" function:



				function controllerAdded(e:GameInputEvent)


				{


					 //put code here to handle when a device is added



					 trace(GameInput.numDevices);//tells you how many gamepads are plugged in


					 var myDevice = GameInput.getDeviceAt(0);//1st gamepad is "0" - more gamepads would be "1", "2", "3", etc.


					 trace(myDevice.numControls); //tells you how many inputs/controls the device has


					 myDevice.enabled = true; //enables the device


					 var cont = myDevice.getControlAt(0);//input reference (AXIS STICK, BUTTON, TRIGGER, etc) "0" is the 1st input


					 trace("id: "+cont.id);//the name of this control. Ex: "AXIS_0"


					 trace("value: " + cont.value); //value of this control - Axis: -1 to 1, Button: 0 OR 1, Trigger: 0 to 1


					 trace("cont: " + cont.device.name); //the name of the device. ie: "XBOX 360 Controller"


					 trace("device: " + cont.device);


					 trace("minValue: " + cont.minValue);//the minimum possible value for the control/input


					 trace("maxValue: " + cont.maxValue);//the maximum possible value for the control/input


				}

That's basically it! You can now create an ENTER_FRAME listener to detect changes in the "control" values and use those changes to control your game!

If you have any questions, feel free to send me a message here.

Here is a .swf file that detects gamepad connections and allows assigning of button functions (from Super Chibi Knight) to the different controls.

The source .fla (cs5.5) is here.