Welcome, please login or register

PushButton Engine: Table of Contents » Handling Input

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

  • PAGE_UP
    The page up key.
  • PAGE_DOWN
    The page down key.
  • END
    The end key.
  • HOME
    The home key.
  • LEFT (LEFT_ARROW)
    The left arrow key.
  • RIGHT (RIGHT_ARROW)
    The right arrow key.
  • UP (UP_ARROW)
    The up arrow key.
  • DOWN (DOWN_ARROW)
    The down arrow key.

Number Keys

  • ZERO (0, NUMBER_0)
    The '0' key at the top of the keyboard (not the number pad).
  • ONE (1, NUMBER_1)
    The '1' key at the top of the keyboard (not the number pad).
  • TWO (2, NUMBER_2)
    The '2' key at the top of the keyboard (not the number pad).
  • THREE (3, NUMBER_3)
    The '3' key at the top of the keyboard (not the number pad).
  • FOUR (4, NUMBER_4)
    The '4' key at the top of the keyboard (not the number pad).
  • FIVE (5, NUMBER_5)
    The '5' key at the top of the keyboard (not the number pad).
  • SIX (6, NUMBER_6)
    The '6' key at the top of the keyboard (not the number pad).
  • SEVEN (7, NUMBER_7)
    The '7' key at the top of the keyboard (not the number pad).
  • EIGHT (8, NUMBER_8)
    The '8' key at the top of the keyboard (not the number pad).
  • NINE (9, NUMBER_9)
    The '9' key at the top of the keyboard (not the number pad).

Letter Keys

  • A
    The A key.
  • B
    The B key.
  • C
    The C key.
  • D
    The D key.
  • E
    The E key.
  • F
    The F key.
  • G
    The G key.
  • H
    The H key.
  • I
    The I key.
  • J
    The J key.
  • K
    The K key.
  • L
    The L key.
  • M
    The M key.
  • N
    The N key.
  • O
    The O key.
  • P
    The P key.
  • Q
    The Q key.
  • R
    The R key.
  • S
    The S key.
  • T
    The T key.
  • U
    The U key.
  • V
    The V key.
  • W
    The W key.
  • X
    The X key.
  • Y
    The Y key.
  • Z
    The Z key.

Number Pad Keys

  • NUM0 (NUMPAD_0)
    Zero on the number pad.
  • NUM1 (NUMPAD_1)
    One on the number pad.
  • NUM2 (NUMPAD_2)
    Two on the number pad.
  • NUM3 (NUMPAD_3)
    Three on the number pad.
  • NUM4 (NUMPAD_4)
    Four on the number pad.
  • NUM5 (NUMPAD_5)
    Five on the number pad.
  • NUM6 (NUMPAD_6)
    Six on the number pad.
  • NUM7 (NUMPAD_7)
    Seven on the number pad.
  • NUM8 (NUMPAD_8)
    Eight on the number pad.
  • NUM9 (NUMPAD_9)
    Nine on the number pad.
  • MULTIPLY (ASTERISK, NUMMULTIPLY, NUMPAD_MULTIPLY)
    The asterisk key on the number pad (*).
  • ADD (NUMADD, NUMPAD_ADD)
    The add key on the number pad (+).
  • SUBTRACT (NUMSUBTRACT, NUMPAD_SUBTRACT)
    The subtract key on the number pad (-).
  • DECIMAL (NUMDECIMAL, NUMPERIOD, NUMPAD_DECIMAL, NUMPAD_PERIOD)
    The decimal key on the number pad (.).
  • DIVIDE (NUMDIVIDE, NUMPAD_DIVIDE)
    The divide key on the number pad (/).
  • NUMENTER (NUMPAD_ENTER)
    The enter key on the number pad.

Function Keys

  • F1
    The first function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F2
    The second function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F3
    The third function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F4
    The fourth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F5
    The fifth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F6
    The sixth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F7
    The seventh function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F8
    The eighth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F9
    The ninth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F11
    The eleventh function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F12
    The twelfth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F13
    The thirteenth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F14
    The fourteenth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.
  • F15
    The fifteenth function key. Some keyboards map the function keys to special commands, and thus can't be relied upon.

Punctuation Keys

  • PLUS (EQUAL)
    The equals key (=). This is not the add key on the number pad.
  • MINUS (UNDERSCORE)
    The minus key (-). This is not the subtract key on the number pad.
  • COLON (SEMICOLON)
    The semi-colon key (;).
  • COMMA (LESS_THAN)
    The comma key (,).
  • PERIOD (GREATER_THAN)
    The period key (.). This is not the decimal on the number pad.
  • BACKSLASH (QUESTION_MARK)
    The backslash key (/). This is not the divid key on the number pad.
  • SLASH (FORWARD_SLASH, PIPE)
    The forward slash key (\).
  • TILDE (BACKQUOTE)
    The tilde key (~).
  • LEFT_BRACKET (LEFT_BRACE)
    The left bracket key ([).
  • RIGHT_BRACKET (RIGHT_BRACE)
    The right bracket key (]).
  • QUOTE
    The quote key (').

Other Keys

  • BACKSPACE
    The backspace key. Labeled 'delete' on Apple keyboards.
  • TAB
    The tab key.
  • SPACE (SPACE_BAR)
    The space bar key.
  • ENTER (RETURN)
    The enter key. Labeled 'return' on Apple keyboards. This is not the enter key on the number pad.
  • SHIFT
    Either the left or right shift key.
  • CONTROL
    Either the left or right control key.
  • COMMAND
    The command key. Only available on OSX.
  • ALT (OPTION, ALTERNATE)
    The alt key. Labeled 'option' on Apple keyboards.
  • PAUSE
    The pause key. Sometimes this is labeled 'break'.
  • ESCAPE
    The escape key.
  • INSERT
    The insert key.
  • DELETE
    The delete key. This is the forward delete key on Apple keyboards.
  • CAPS_LOCK
    The caps lock key.
  • NUM_LOCK
    The num lock key.
  • SCROLL_LOCK
    The scroll lock key.

Mouse

  • MOUSE_BUTTON
    The left mouse button.
  • MOUSE_X
    Horizontal mouse movement.
  • MOUSE_Y
    Vertical mouse movement.