This is the reference to all methods, functions and properties available to KeyActionBinder. Refer to the guide for practical examples.
Initializes the KeyActionBinder class. This is necessary to allocate global references needed by KeyActionBinder instances.
Due to bugs in Flash's GameInput API (especially on OUYA and Android), this initialization should be done in the first frame of your SWF, preferably in the root class of your movie.
- stage: Flash's global stage, used for adding event listeners.
Create a new KeyActionBinder instance.
Each instance has its own input bindings and actions.
More than one KeyActionBinder instance can exist and be active at the same time.
Starts listening for input events.
This happens by default when a KeyActionBinder object is instantiated; this method is only useful if
called after stop() has been used.
Calling this method when a KeyActionBinder instance is already running has no effect.
Stops listening for input events.
Action bindings are not lost when a KeyActionBinder instance is stopped; it merely starts ignoring
all input events, until start() is called again.
This method should always be called when you don't need a KeyActionBinder instance anymore, otherwise it'll be listening to events indefinitely.
Calling this method when this a KeyActionBinder instance is already stopped has no effect.
addKeyboardActionBinding(action:String, keyCode:int = KeyActionBinder.KEY_CODE_ANY, keyLocation:int = KeyActionBinder.KEY_LOCATION_ANY):void
Adds an action bound to a keyboard key. When a key with the given keyCode is pressed, the desired action is activated. Optionally, keys can be restricted to a specific keyLocation.
- action: An arbitrary String id identifying the action that should be dispatched once this key combination is detected.
- keyCode: The code of a key, as expressed in AS3's Keyboard constants.
- keyLocation: The code of a key's location, as expressed in AS3's KeyLocation constants. If the default value is passed, the key location is never taken into consideration when detecting whether the passed action should be fired.
// Left arrow key to move left
myBinder.addKeyboardActionBinding("move-left", Keyboard.LEFT);
// SPACE key to jump
myBinder.addKeyboardActionBinding("jump", Keyboard.SPACE);
// Any SHIFT key to shoot
myBinder.addKeyboardActionBinding("shoot", Keyboard.SHIFT);
// Left SHIFT key to boost
myBinder.addKeyboardActionBinding("boost", Keyboard.SHIFT, KeyLocation.LEFT);
removeKeyboardActionBinding(action:String, keyCode:int = KeyActionBinder.KEY_CODE_ANY, keyLocation:int = KeyActionBinder.KEY_LOCATION_ANY):void
Removes an action bound to a keyboard key.
- action: An arbitrary String id identifying the action that should be dispatched once this key combination is detected.
- keyCode: The code of a key, as expressed in AS3's Keyboard constants.
- keyLocation: The code of a key's location, as expressed in AS3's KeyLocation constants. If the default value is passed, the key location is never taken into consideration when detecting whether the passed action should be fired.
// Left arrow key to move left
myBinder.addKeyboardActionBinding("move-left", Keyboard.LEFT);
// SPACE key to jump
myBinder.addKeyboardActionBinding("jump", Keyboard.SPACE);
// Any SHIFT key to shoot
myBinder.addKeyboardActionBinding("shoot", Keyboard.SHIFT);
// Left SHIFT key to boost
myBinder.addKeyboardActionBinding("boost", Keyboard.SHIFT, KeyLocation.LEFT);
addGamepadActionBinding(action:String, controlId:String, gamepadIndex:int = KeyActionBinder.GAMEPAD_INDEX_ANY):void
Adds an action bound to a game controller button, trigger, or axis. When a control of id controlId is pressed, the desired action can be activated, and its value changes. Optionally, keys can be restricted to a specific game controller location.
- action: An arbitrary String id identifying the action that should be dispatched once this input combination is detected.
- controlId: The id code of a GameInput control, as an String. Use one of the constants from
GamepadControls. - gamepadIndex: The int of the gamepad that you want to restrict this action to. Use 0 for the first gamepad (player 1), 1 for the second one, and so on. If the default value is passed, the gamepad index is never taken into consideration when detecting whether the passed action should be fired.
// Direction pad left to move left
myBinder.addGamepadActionBinding("move-left", GamepadControls.DPAD_LEFT);
// Action button "down" (O in the OUYA, Cross in the PS3, A in the XBox 360) to jump
myBinder.addGamepadActionBinding("jump", GamepadControls.ACTION_DOWN);
// L1/LB to shoot, on any controller
myBinder.addGamepadActionBinding("shoot", GamepadControls.LB);
// L1/LB to shoot, on the first controller only
myBinder.addGamepadActionBinding("shoot-player-1", GamepadControls.LB, 0);
// L2/LT to shoot, regardless of whether it is sensitive or not
myBinder.addGamepadActionBinding("shoot", GamepadControls.LT);
// L2/LT to accelerate, depending on how much it is pressed (if supported)
myBinder.addGamepadActionBinding("accelerate", GamepadControls.LT);
// Direction pad left to move left or right
myBinder.addGamepadActionBinding("move-sides", GamepadControls.STICK_LEFT_X);
removeGamepadActionBinding(action:String, controlId:String, gamepadIndex:int = KeyActionBinder.GAMEPAD_INDEX_ANY):void
Removes an action bound to a game controller button, trigger, or axis.
- action: An arbitrary String id identifying the action that should be dispatched once this input combination is detected.
- controlId: The id code of a GameInput control, as an String. Use one of the constants from
GamepadControls. - gamepadIndex: The int of the gamepad that you want to restrict this action to. Use 0 for the first gamepad (player 1), 1 for the second one, and so on. If the default value is passed, the gamepad index is never taken into consideration when detecting whether the passed action should be fired.
Reads the current value of an action.
- action: The id of the action you want to read the value of.
- controlId: The id code of a GameInput control, as an String. Use one of the constants from
GamepadControls. - gamepadIndex: The int of the gamepad that you want to restrict this action to. Use 0 for the first gamepad (player 1), 1 for the second one, and so on. If the default value is passed, the gamepad index is never taken into consideration when detecting whether the passed action should be fired.
A numeric value based on the bindings that might have activated this action. The maximum and minimum values returned depend on the kind of control passed via addGamepadActionBinding().
// Direction pad left to move left or right
var speedX:Number = myBinder.getActionValue("move-sides"); // Generally between -1 and 1
// L2/LT to accelerate, depending on how much it is pressed
var acceleration:Number = myBinder.getActionValue("accelerate"); // Generally between 0 and 1
Checks whether an action is currently activated.
- action: An arbitrary String id identifying the action that should be checked.
- timeToleranceSeconds: Time tolerance, in seconds, before the action is assumed to be expired. If < 0, no time is checked.
True if the action is currently activated (i.e., its button is pressed), false if otherwise.
// Moves player right when right is pressed
// Setup:
myBinder.addGamepadActionBinding("move-right", GamepadControls.DPAD_RIGHT);
// In the game loop:
if (myBinder.isActionActivated("move-right")) {
player.moveRight();
}
// Check if a jump was activated (includes just before falling, for a more user-friendly control)
// Setup:
myBinder.addGamepadActionBinding("jump", GamepadControls.ACTION_DOWN);
// In the game loop:
if (isTouchingSurface && myBinder.isActionActivated("jump"), 0.1)) {
player.performJump();
}
- GamepadControls
- addGamepadActionBinding()
- getActionValue()
- http://zehfernando.com/2013/keyactionbinder-updates-time-sensitive-activations-new-constants/
Consumes an action, causing all current activations and values attached to it to be reset. This is the same as simulating the player releasing the button that activates an action. It is useful to force players to re-activate some actions, such as a jump action (otherwise keeping the jump button pressed would allow the player to jump nonstop).
- action: The id of the action you want to consume.
// On jump, consume the jump to avoid constant jumping
if (isTouchingSurface && myBinder.isActionActivated("jump")) {
myBinder.consumeAction("jump");
player.performJump();
}
Returns the number of devices currently connected, regardless of whether they're valid or not.
Returns the GameInputDevice associated with a player index, if any.
The value returned from this function can be null, especially if maintainPlayerPositions is set to true and the index refers to a gamepad that has been removed.
Returns the built-in id of the gamepad type at a certain position.
The value returned from this function can be null if maintainPlayerPositions is set to true and the index refers to a gamepad that has been removed, or if the gamepad at that location has not been properly identified by KeyActionBinder.
Check the controllers.json file for a list of supported gamepads, and their ids.
Returns the current identified platform. This is a list of strings that can contain more than one platform id.
Check the controllers.json file for a list of supported platforms, and their ids.
A signal-like event/callback that gets dispatched when an action is assumed to be activated. You add() or remove() listening functions to this property.
Notice that the function added must receive a single String parameter.
// Create a function to handle action activations
private function myOnActionActivated(__action:String):void {
trace("The user activated the " + __action + " action by pressing a key or button.");
}
// Add that function to the signals list
binder.onActionActivated.add(myOnActionActivated);
A signal-like event/callback that gets dispatched when an action is assumed to be deactivated. You add() or remove() listening functions to this property.
Notice that the function added must receive a single String parameter.
// Create a function to handle action deactivations
private function myOnActionDeactivated(__action:String):void {
trace("The user deactivated the " + __action + " action by releasing a key or button.");
}
// Add that function to the signals list
binder.onActionDeactivated.add(myOnActionDeactivated);
A signal-like event/callback that gets dispatched when the activation value of an action changes. You add() or remove() listening functions to this property.
Notice that the function added must receive a String parameter and a 'Number' parameter.
// Create a function to handle action value changes
private function myOnActionValueChanged(__action:String, __value:Number):void {
trace("The user activated the " + __action + " action's value. The new value is " + __value);
}
// Add that function to the signals list
binder.onActionValueChanged.add(myOnActionValueChanged);
Todo...
Todo...
Toggles whether KeyActionBinder tries to maintain each player's gamepad index based on the unique id of each device.
When this is set to false, the list of connected devices (via getNumDevices() and others) will always reflect Flash's list of connected GameInputDevices. This means that the connected gamepads can be shuffled around when a device is added or removed, potentially causing players on a multi-player game to have their respective gamepad references swapped.
When this is set to true, KeyActionBinder uses the device ids to keep a more consistent list of devices, avoiding shuffling them around. This has several implications:
- When removed, a device will continue to exist in the list as a
nulldevice (unless it's the last device in the GameInputDevice list, in which case it gets removed entirely) - An added device will try to be re-added to its previously existing position, if one can be found (that is, if it was present before and then removed)
- If a previously existing position cannot be found for a new device, the device takes the first available (
null) position if one can be found, or is added to the end of the list of devices otherwise
In general, you should set this option before gameplay starts.
If you set this to false after it was set to true, it will cause a refresh of the gamepad order, potentially shuffling player positions around if devices were added or removed previously.
The default is false.
// Test 1 binder.maintainPlayerPositions = false; // Add controller XBOX1; List is [XBOX1] // Add controller XBOX2; List is [XBOX1, XBOX2] // Remove controller XBOX1; List is [XBOX2] // Add controller XBOX1; List is [XBOX2, XBOX1] // Remove controller XBOX2; List is [XBOX1] // Remove controller XBOX1; List is []
// Test 2 binder.maintainPlayerPositions = true; // Add controller XBOX1; List is [XBOX1] // Add controller XBOX2; List is [XBOX1, XBOX2] // Remove controller XBOX1; List is [null, XBOX2] // Add controller XBOX1; List is [XBOX1, XBOX2] // Remove controller XBOX2; List is [XBOX1] // Remove controller XBOX1; List is []
Whether this KeyActionBinder instance is running, or not. This property is read-only.
Whether to run preventDefault() on Keyboard events or not.
When this is set to false, KeyActionBinder doesn't try stopping the propagation of standard Keyboard behavior. In general, this is a bad idea, as certain keys (such as A on the OUYA) tend to trigger a Keyboard.BACK key event, potentially closing your application. Only set this to false if you are handling Keyboard events in your own code.
The default is true.
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...
Todo...