InputDevice provides support for keyboard, mouse, and Xbox 360 gamepad input events. It queues input events received between consecutive calls to update(). When update() is called, the events are dispatched in order using the appropriate event handlers (onkeydown, onmouseup, etc.) and the event queue is cleared.
The InputDevice also allows the game to hide/show the mouse cursor and lock its position (by calling lockMouse).
In general, a human interface device (HID) such as a mouse or keyboard, has a number of “controls” which the user can interact with to produce input events. Each control (e.g. mouse button, keyboard key) has an associated “control code”. These allow the game to identify input consistently and clearly. Keyboard, mouse and pad control codes are referred to as KeyCodes, MouseCodes, and PadCodes respectively.
The keyboard is treated as a game controller rather than a text entry device. Each keyboard control code (KeyCode) therefore corresponds to an individual physical key on the keyboard (i.e. a control) and not the text character that would result from such a key press. For instance, pressing “Q” on the US keyboard will result in the same KeyCode as pressing “A” on a French keyboard (as they are in the same physical location on the keyboard). The names of the KeyCodes correspond to the names of the keys on the US keyboard and in the example above, the KeyCode generated would be “Q”.
Note
The Escape key is reserved for unlocking the user’s mouse and pressing it or releasing it causes no events to be sent. Keys which are not currently part of the mapping scheme will also not send events and cannot be used by the game.
Warning
Keyboards exist with a wide variety of different keys. It is strongly recommended to only use the most common keys as part of any default control scheme. A list of standard keys are shown in the KeyCode table section.
Using controls rather than characters for keyboard input has the advantage that game code written will work for all keyboard layouts without the need for localization; there is no need for multiple versions of input code for each keyboard layout a game wishes to support.
It may be necessary to convert from KeyCodes to the Unicode character which would result from pressing that physical key with the user’s keyboard layout e.g. when localizing the game controls displayed to the user. The InputDevice API provides the function convertToUnicode for this reason. In order to facilitate correct translation of in-game text, and correct formatting of dates and numbers, the locale of the player can be requested using the TurbluenzEngine.getSystemInfo function.
For each HID supported, there are usually three main event types: down events, up events, and move events. Down events occur when a button/key is pressed, up events when a button/key is released and move events occur when the HID is moved, or an analogue control on it (e.g. thumbstick) is adjusted. In addition, the following events are supported:
Focus and blur events occur when the TurbulenzEngine object gains or loses focus. Clicking on the TurbulenzEngine object gives it focus, and clicking elsewhere will or switching window causes it to lose focus.
For each device and event type there is a unique event handler which the game code can set to be called when an event of that type occurs.
Summary
Iterates through the events in the event queue calling the relevant callbacks. Once all events have been dispatched, the event queue is cleared.
Syntax
inputDevice.update();
Summary
Locks the mouse cursor position and hides the cursor. Fails if the cursor is not over the TurbulenzEngine object or if the TurbulenzEngine object is not focused. Returns true or false to indicate success or failure.
Note
When locked, mousemove events rather than mouseover events will be received for mouse movement.
Syntax
if (!inputDevice.lockMouse())
{
// Failed to lockMouse (mouse is not over the TurbulenzEngine object)
}
Summary
Frees and shows the mouse cursor (if locked). Fails if the cursor is not currently locked. Returns true or false to indicate success or failure.
Syntax
if (!inputDevice.unlockMouse())
{
// Failed to unlockMouse (mouse was not already locked)
}
Summary
Returns true if the mouse is currently locked, false otherwise.
Syntax
if (!inputDevice.isLocked())
{
inputDevice.lockMouse();
}
Summary
Hides the cursor if it is currently visible and over the TurbulenzEngine object. Fails otherwise. Returns true or false to indicate success or failure.
Syntax
if (!inputDevice.hideMouse())
{
// Failed to hideMouse (it was either already hidden, or outside of the TurbulenzEngine object)
}
Summary
Shows the cursor if it is currently hidden and not locked. Fails otherwise. Returns true or false to indicate success or failure.
Syntax
if (!inputDevice.showMouse())
{
// Failed to showMouse (it was either already visible, or locked)
}
Summary
Returns true if the TurbulenzEngine object is currently focused, false otherwise.
Syntax
var isFocused = inputDevice.isFocused();
Summary
Converts a given array of KeyCodes to an object of the Unicode characters which would result from pressing those physical keys with the user’s keyboard layout. Returns null if the argument passed in is not an array. For KeyCodes which do not have a corresponding Unicode character (e.g. the “alt” key), an empty string will be returned as the property value in the returned object.
The returned object has the form { keycode : unicode, ... }.
Syntax
var keyCodes = inputDevice.keyCodes;
var keyCodeArray = [keyCodes.Q, keyCodes.B];
var unicodeCharacterObject = convertToUnicode(keyCodeArray);
// On a US keyboard unicodeCharacterObject[keyCodes.Q] will be equal to 'q',
// while on a French keyboard, unicodeCharacterObject[keyCodes.Q] will be equal to 'a';
A JavaScript object, storing KeyCode enums for use in game code. These should be cached for best performance. See the KeyCode Table for the full list.
Syntax
var keyCodes = inputDevice.keyCodes;
A JavaScript object, storing MouseCode enums for use in game code. These should be cached for best performance. See the MouseCode Table for the full list.
Syntax
var mouseCodes = inputDevice.mouseCodes;
A JavaScript object, storing PadCode enums for use in game code. These should be cached for best performance. See the PadCode Table for the full list.
Syntax
var padCodes = inputDevice.padCodes;
Summary
Callback for key down events.
Syntax
// Cache keyCodes
var keyCodes = inputDevice.keyCodes;
inputDevice.onkeydown = function onkeydownFn(keycode)
{
if (keycode === keyCodes.LEFT || keyCodes.A)
{
character.left = 1.0;
}
else if (keycode === keyCodes.RIGHT || keyCodes.D)
{
character.right = 1.0;
}
else if (keycode === keyCodes.UP || keyCodes.W)
{
character.forward = 1.0;
}
else if (keycode === keyCodes.DOWN || keyCodes.S)
{
character.backward = 1.0;
}
};
Summary
Callback for key up events.
Syntax
// Cache keyCodes
var keyCodes = inputDevice.keyCodes;
inputDevice.onkeyup = function onkeyupFn(keycode)
{
if (keycode === keyCodes.LEFT || keyCodes.A)
{
character.left = 0;
}
else if (keycode === keyCodes.RIGHT || keyCodes.D)
{
character.right = 0;
}
else if (keycode === keyCodes.UP || keyCodes.W)
{
character.forward = 0;
}
else if (keycode === keyCodes.DOWN || keyCodes.S)
{
character.backward = 0;
}
else if (keycode === keyCodes.RETURN)
{
graphicsDevice.fullscreen = !graphicsDevice.fullscreen;
}
};
Summary
Callback for mouse down (e.g. mouse click) events. Provides the position (in coordinates local to the TurbulenzEngine) of the event (unless the mouse is locked in which case the position arguments are omitted).
Syntax
// Cache mouseCodes
var mouseCodes = inputDevice.mouseCodes;
inputDevice.onmousedown = function onmousedownFn(mouseCode, x, y)
{
eventPositionX = x;
eventPositionY = y;
if (mouseCode === mouseCodes.BUTTON_0)
{
mouseFireButtonDown = true;
}
else if (mouseCode === mouseCodes.BUTTON_1)
{
mouseAimButtonDown = true;
}
};
Summary
Callback for mouse up events. Provides the position (in coordinates local to the TurbulenzEngine) of the event (unless the mouse is locked in which case the position arguments are omitted).
Syntax
// Cache mouseCodes
var mouseCodes = inputDevice.mouseCodes;
inputDevice.onmouseup = function onmouseupFn(mouseCode, x, y)
{
eventPositionX = x;
eventPositionY = y;
if (mouseCode === mouseCodes.BUTTON_0)
{
mouseFireButtonDown = false;
}
else if (mouseCode === mouseCodes.BUTTON_1)
{
mouseAimButtonDown = false;
}
};
Summary
Callback for mouse wheel events. delta is the distance scrolled by the user, and is positive for upwards scrolling and negative otherwise.
Syntax
inputDevice.onmousewheel = function onmousewheelFn(delta)
{
if (delta > 0)
{
character.weapon += 1;
}
else
{
character.weapon -= 1;
}
};
Summary
Callback for mouse move events when the cursor is locked. deltaX and deltaY signify the distance the mouse has moved in the x and y directions respectively since the last mouse move event.
Syntax
inputDevice.onmousemove = function onmousemoveFn(deltaX, deltaY)
{
character.turn += deltaX;
character.pitch += deltaY;
};
Summary
Callback for mouse move events whilst the cursor is unlocked. Provides the position (in coordinates local to the TurbulenzEngine) of the event.
Syntax
inputDevice.onmousemove = function onmousemoveFn(x, y)
{
mousePosition.x = x;
mousePosition.y = y;
};
Summary
Called during update() to handle a pad (Xbox 360) button down event.
Syntax
// Cache padCodes
var padCodes = inputDevice.padCodes;
inputDevice.onpaddown = function onpaddownFn(padCode)
{
if (!character.dead)
{
if (padCode === padCodes.A)
{
character.jump = true;
}
else if (padCode === padCodes.B)
{
character.crouch = !character.crouch;
}
}
};
Summary
Called during update() to handle a pad button up event.
Syntax
// Cache padCodes
var padCodes = inputDevice.padCodes;
inputDevice.onpadup = function onpadupFn(padCode)
{
if (!character.dead)
{
if (padCode === padCodes.A)
{
character.jump = false;
}
}
};
Summary
Callback for pad thumbstick or trigger events. lX, lY, rX, and rY represent the position of the left and right thumbsticks respectively and have values in the range -1 to 1 inclusive. lZ and rZ represent the state of the left and right triggers and have values in the range 0 to 1 inclusive. Positive lX, lY, rX, and rY values correspond to right and up directions. Negative deltas correspond to left and down directions.
If a gamepad is connected, this function will be called for every call to update(). If the gamepad controls are not displaced, all arguments will have a value of 0.
A value of 0 denotes the edge of a deadzone and value of ±1 denotes the maximum possible displacement from rest position. The deadzones used are the defaults provided by XInput. Please see XInput on MSDN for further details.
Syntax
// Cache padCodes
var padCodes = inputDevice.padCodes;
inputDevice.onpadmove = function onpadmoveFn(lX, lY, lZ, rX, rY, rZ)
{
character.turn += lX * 10.0;
character.pitch += lY * 10.0;
if (rX >= 0)
{
character.padright = rX;
character.padleft = 0;
}
else
{
character.padright = 0;
character.padleft = -rX;
}
if (rY >= 0)
{
character.padforward = rY;
character.padbackward = 0.0;
}
else
{
character.padforward = 0.0;
character.padbackward = -rY;
}
};
Note
Pad input is only supported using the Xbox 360 Controller on Windows.
Summary
Callback for when the TurbulenzEngine object gains focus - e.g. when the user first clicks inside the game area.
Syntax
inputDevice.onfocus = function onfocusFn()
{
game.unpause();
};
Summary
Callback for when the TurbulenzEngine object loses focus - e.g. when the user clicks outside of the game area or switches windows/tabs.
Syntax
inputDevice.onblur = function onblurFn()
{
game.pause();
};
Summary
Callback for when the mouse lock is lost. E.g. if the user presses the Escape key when the mouse is locked, or unlockMouse() is called.
Syntax
inputDevice.onmouselocklost = function onmouselocklostFn()
{
game.pause();
};
Note
KeyCodes are named according to the names of the physical keys on the US keyboard. Click here for details.
Warning
It should be stressed that the numerical values of the KeyCodes should not be used directly in game code and are subject to change. The values below should be used only for debugging purposes.
The keys below represent the most common physical keys found on keyboards and are safe to use as part of a default control scheme.
| KeyCode Name | Value |
|---|---|
| A | 0 |
| B | 1 |
| C | 2 |
| D | 3 |
| E | 4 |
| F | 5 |
| G | 6 |
| H | 7 |
| I | 8 |
| J | 9 |
| K | 10 |
| L | 11 |
| M | 12 |
| N | 13 |
| O | 14 |
| P | 15 |
| Q | 16 |
| R | 17 |
| S | 18 |
| T | 19 |
| U | 20 |
| V | 21 |
| W | 22 |
| X | 23 |
| Y | 24 |
| Z | 25 |
| NUMBER_0 | 100 |
| NUMBER_1 | 101 |
| NUMBER_2 | 102 |
| NUMBER_3 | 103 |
| NUMBER_4 | 104 |
| NUMBER_5 | 105 |
| NUMBER_6 | 106 |
| NUMBER_7 | 107 |
| NUMBER_8 | 108 |
| NUMBER_9 | 109 |
| LEFT | 200 |
| RIGHT | 201 |
| UP | 202 |
| DOWN | 203 |
| LEFT_SHIFT | 300 |
| RIGHT_SHIFT | 301 |
| LEFT_CONTROL | 302 |
| RIGHT_CONTROL | 303 |
| LEFT_ALT | 304 |
| RIGHT_ALT | 305 |
| ESCAPE | 400 |
| TAB | 401 |
| SPACE | 402 |
| BACKSPACE | 403 |
| RETURN | 404 |
| GRAVE | 500 |
| MINUS | 501 |
| EQUALS | 502 |
| LEFT_BRACKET | 503 |
| RIGHT_BRACKET | 504 |
| SEMI_COLON | 505 |
| APOSTROPHE | 506 |
| COMMA | 507 |
| PERIOD | 508 |
The following are non-standard keys and should not be used as part of a default control scheme.
| KeyCode Name | Value |
|---|---|
| F1 | 600 |
| F2 | 601 |
| F3 | 602 |
| F4 | 603 |
| F5 | 604 |
| F6 | 605 |
| F7 | 606 |
| F8 | 607 |
| F9 | 608 |
| F10 | 609 |
| F11 | 610 |
| F12 | 611 |
| NUMPAD_0 | 612 |
| NUMPAD_1 | 613 |
| NUMPAD_2 | 614 |
| NUMPAD_3 | 615 |
| NUMPAD_4 | 616 |
| NUMPAD_5 | 617 |
| NUMPAD_6 | 618 |
| NUMPAD_7 | 619 |
| NUMPAD_8 | 620 |
| NUMPAD_9 | 621 |
| NUMPAD_ENTER | 622 |
| NUMPAD_DIVIDE | 623 |
| NUMPAD_MULTIPLY | 624 |
| NUMPAD_ADD | 625 |
| NUMPAD_SUBTRACT | 626 |
| LEFT_WIN | 627 |
| RIGHT_WIN | 628 |
| LEFT_OPTION | 629 |
| RIGHT_OPTION | 630 |
| CAPS_LOCK | 631 |
These are typically mapped to left, right and middle buttons respectively.
| MouseCode Name | Value |
|---|---|
| BUTTON_0 | 0 |
| BUTTON_1 | 1 |
| BUTTON_2 | 2 |
The PadCode names derive from the names of the Xbox 360 gamepad buttons.
| PadCode Name | Value |
|---|---|
| LEFT | 0 |
| RIGHT | 1 |
| UP | 2 |
| DOWN | 3 |
| A | 4 |
| B | 5 |
| X | 6 |
| Y | 7 |
| LEFT_SHOULDER | 8 |
| RIGHT_SHOULDER | 9 |
| LEFT_THUMB | 10 |
| RIGHT_THUMB | 11 |
| START | 12 |
| BACK | 13 |