README.md

KeyActionBinder

KeyActionBinder tries to provide universal game input control for both keyboard and game controllers in Adobe AIR, independent of the game engine used or the hardware platform it is running in.

While Adobe Flash already provides all the means for using keyboard and game input (via KeyboardEvent and GameInput), KeyActionBinder tries to abstract those classes behind a straightforward, higher-level interface. It is meant to be simple but powerful, while solving some of the most common pitfalls involved with player input in AS3 games.

Using KeyActionBinder — Reference — Version Changelog — Supported devices — Contribute

Goals

• Unified interface for keyboard and game controller input
• Made to be fast: memory allocation is kept to a minimum, and there are no device references or instances to maintain
• Abstract actual controls in favor of action ids: easier to configure key bindings through variables, with redundant input types (keyboard and gamepad)
• Automatic bindings on any platform by hiding away platform-specific controls over unified ids
• Self-containment and independence from any other system or framework

Usage

private var binder:KeyActionBinder;

// Setup (first frame/root of SWF)
KeyActionBinder.init(stage);

public function setup():void {
	// Create instance
	binder = new KeyActionBinder();
	
	// Setup as many action bindings as you want
	binder.addKeyboardActionBinding("move-left", Keyboard.LEFT);
	binder.addKeyboardActionBinding("move-right", Keyboard.RIGHT);
	binder.addGamepadActionBinding("move-left", GamepadControls.DPAD_LEFT);
	binder.addGamepadActionBinding("move-right", GamepadControls.DPAD_RIGHT);
}

function function gameLoop():void {
	// Evaluate actions
	if (binder.isActionActivated("move-left")) {
		// ...
	} else if (binder.isActionActivated("move-right")) {
		// ...
	}
}

Read more in the guide.

Tests/demos

KeyActionBinderTester
Web-based version, Android/OUYA APK
Source code

Read more

• Blog post: Known OUYA GameInput controls on Adobe AIR (July 2013)
• Blog post: Abstracting key and game controller inputs in Adobe AIR (July 2013)
• Blog post: KeyActionBinder updates: time sensitive activations, new constants (September 2013)
• Blog post: Big changes to KeyActionBinder: automatic game control ids, new repository (October 2013)
• Blog post: A GameInput testing interface (January 2014)
• Blog post: KeyActionBinder is growing up (February 2014)

GameInput problems

In case of problems with KeyActionBinder... know that Flash's GameInput API is still severely ridden with bugs. You may run into some of them. Here's some more information.

• Supported devices are not detected properly when added or removed (Bug #3709110): no workaround
• Using GameInput add Timer overhead every second in Windows (Bug #3660823): no workaround
• GameInput devices simply stop working when running on Android/OUYA: need to initialize things in the first frame of SWF (fixed in AIR 13.0.0.36/Flash Player 13.0.0.130?)
• Quick button presses may not be properly detected on Macs (Bug #3702039): no workaround (need to test sampling rate changes and if button activation can always be assumed from the up event)

I'll remove items from the list when they're fixed.

Credits and thanks

• James Dean Palmer for the original idea about auto-mapping controls and many bindings
• Patrick Bastiani for the NeoFlex controller mapping
• Rusty Moyher for the Buffalo SNES mapping, and several other mappings for Windows and OSX
• Eric Socolofsky for testing, bug fixes, and OSX mappings for the XBox 360 controller

License

KeyActionBinder uses the MIT License. You can use this code in any project, whether of commercial nature or not. If you redistribute the code, the license (LICENSE.txt) must be present with it.

To-do

• Use caching samples? Change sampling rate?
• Properly detect buttons that immediately send down+up events that cannot be detected by normal frames (e.g. HOME on OUYA)
• Allow detecting "any" gamepad key (for "press any key")
• More automatic gamepad mappings
• Still allow platform-specific control ids?
• Profile and test performance/bottlenecks/memory allocations
• A better looking KeyActionBinderTester demo
• Compile binary/stable SWC
• More bulletproof support for 2+ controllers