Handling Input

Flash has a lot of powerful input handling capabilities, but they tend to be too much for a game. The InputManager and InputMap classes work together to provide a few focused capabilities to make it simple to implement controls for your game.

Note that for general UI building tasks, you will want to use the normal Flash events.

InputManager and InputMap

The InputManager is a clearing house for input events. Mostly, InputMap instance subscribe to it, although your code can do that as well. It also tracks if keys are down, so you can write code like:

   if(InputManager.isKeyDown(InputKey.UP))
      moveItemUp();

However, this idiom generally results in brittle, complicated input handling code. A much better option is to use an InputMap, which lets you expose named input events you want to bind, and configure what keys should trigger them. That way if you want to allow users to reconfigure what keys they use, you can do so without having to modify your code.

InputMap also lets you handle input in a uniform way. You simply provide it with input names, and callback functions that take a single numerical parameter. Digital inputs (buttons) will be called back with 0 or 1 based on if the button is up or down. Analog inputs (mouse) will be called back with the change in position of the input. In most cases this means you can write code that handles buttons or mouse input identically.

In addition, the InputManager gives you an opportunity to handle more exotic input sources in a consistent manner. You might extend it to use a 3rd party utility to handle joystick or Wiimote input events - these would simply be exposed as other input options that can be selected when configuring the InputMap.

The following is source code for a simple component that handles input using an InputMap:

   public class MyInputHandlingComponent extends TickedComponent
   {
      public function get input():InputMap
      {
         return _inputMap;
      }
      
      public function set input(value:InputMap):void
      {
         _inputMap = value;
         
         if (_inputMap != null)
         {
            _inputMap.addBinding("GoLeft", _onLeft);
            _inputMap.addBinding("GoRight", onRight);
         }
      }

      public override function onTick(tickRate:Number):void
      {
         // Normally you would update your position based on this; for simplicity
         // we just print the direction we are being indicated to move.
         var direction:Number = right - left;
         Logger.print(this, "I am moving " + direction);
      }
      
      private function onLeft(value:Number):void
      {
         left = value;
      }

      private function onRight(value:Number):void
      {
         right = value;
      }
      
      
      private var _inputMap:InputMap;
      private var _left:Number = 0;
      private var _right:Number = 0;
   }

And here is the level XML to set it up as part of an entity. Notice that you specify the inputs as part of the level, making it easy to support multiple players on the same keyboard or other customizations of input.

   <entity name="InputHandlingEntity">
      <component class="MyInputHandlingComponent" name="Input"/>
         <Input>
            <!-- These correspond to the calls to AddBinding above. -->
            <GoLeft>LEFT</GoLeft>
            <GoRight>RIGHT</GoRight>
         </Input>
      </component>
   </entity>

Notice that you could also bind to mouse movement by doing the following:

   <entity name="MouseInputHandlingEntity">
      <component class="MyInputHandlingComponent" name="Input"/>
         <Input>
            <!-- These correspond to the calls to AddBinding above.  Only GoLeft needs to be bound because MOUSE_X gives negative as well as positive results. -->
            <GoLeft>MOUSE_X</GoLeft>
         </Input>
      </component>
   </entity>

That's all there is to know about InputMap and InputManager! The rest of this chapter is a reference to the supported key names for InputMap.

InputMap Key Names

This section lists all the keys that can be used with the InputMap class. The label for each key is used both as the name of the constant in the InputKey class and the name to use when defining an InputMap in XML. Additionally, some keys may have one or more aliases listed in parentheses. For the most part these exist to provide compatibility with the names that Flash uses in the flash.ui.Keyboard class. All names are case-insensitive.

Navigation Keys

Number Keys

Letter Keys

Number Pad Keys

Function Keys

Punctuation Keys

Other Keys

Mouse