.. _inputdevice: .. highlight:: javascript .. index:: single: InputDevice ---------------------- The InputDevice Object ---------------------- ``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 :ref:`lockMouse`). Control Codes ============= 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 :ref:`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 :ref:`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 :ref:`TurbluenzEngine.getSystemInfo ` function. Event Handling ============== 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: * Mouse wheel events * Focus/Blur events * MouseLockLost event 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. Methods ======= .. index:: pair: InputDevice; update .. _inputdevice-update: `update` -------- **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(); .. _inputdevice-lockmouse: `lockMouse` ----------- **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, :ref:`mousemove ` events rather than :ref:`mouseover ` events will be received for mouse movement. **Syntax** :: if (!inputDevice.lockMouse()) { // Failed to lockMouse (mouse is not over the TurbulenzEngine object) } .. _inputdevice-unlockmouse: `unlockMouse` ------------- **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) } .. _inputdevice-islocked: `isLocked` ------------- **Summary** Returns true if the mouse is currently locked, false otherwise. **Syntax** :: if (!inputDevice.isLocked()) { inputDevice.lockMouse(); } .. _inputdevice-hidemouse: `hideMouse` ------------ **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) } .. _inputdevice-showmouse: `showMouse` ------------ **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) } .. _inputdevice-ishidden: `isHidden` ------------- **Summary** Returns true if the mouse is currently hidden (including when locked), false otherwise. **Syntax** :: if (!inputDevice.isHidden()) { inputDevice.hideMouse(); } .. _inputdevice-isfocused: `isFocused` ------------- **Summary** Returns true if the TurbulenzEngine object is currently focused, false otherwise. **Syntax** :: var isFocused = inputDevice.isFocused(); .. _inputdevice-converttounicode: `convertToUnicode` ------------------ **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'; Properties ========== `keyCodes` ----------- A JavaScript object, storing KeyCode enums for use in game code. These should be cached for best performance. See the :ref:`KeyCode Table` for the full list. **Syntax** :: var keyCodes = inputDevice.keyCodes; `mouseCodes` ------------ A JavaScript object, storing MouseCode enums for use in game code. These should be cached for best performance. See the :ref:`MouseCode Table` for the full list. **Syntax** :: var mouseCodes = inputDevice.mouseCodes; `padCodes` ----------- A JavaScript object, storing PadCode enums for use in game code. These should be cached for best performance. See the :ref:`PadCode Table` for the full list. **Syntax** :: var padCodes = inputDevice.padCodes; .. _inputdevice-onkeydown: `onkeydown` ----------- **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; } }; .. _inputdevice-onkeyup: `onkeyup` --------- **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; } }; .. _inputdevice-onmousedown: `onmousedown` ------------- **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; } }; .. _inputdevice-onmouseup: `onmouseup` ----------- **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; } }; .. _inputdevice-onmousewheel: `onmousewheel` --------------- **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; } }; .. _inputdevice-onmousemove: `onmousemove` ------------- **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; }; .. _inputdevice-onmouseover: `onmouseover` ------------- **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; }; .. _inputdevice-onpaddown: `onpaddown` ------------- **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; } } }; .. _inputdevice-onpadup: `onpadup` ----------- **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; } } }; .. _inputdevice-onpadmove: `onpadmove` ------------- **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 :ref:`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. .. _inputdevice-onfocus: `onfocus` --------- **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(); }; .. _inputdevice-onblur: `onblur` -------- **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(); }; .. _inputdevice-onmouselocklost: `onmouselocklost` ----------------- **Summary** Callback for when the mouse lock is lost. E.g. if the user presses the Escape key when the mouse is locked, or :ref:`unlockMouse()` is called. **Syntax** :: inputDevice.onmouselocklost = function onmouselocklostFn() { game.pause(); }; .. _inputdevice-controlcodetables: Control Code Tables =================== .. _inputdevice-keycodetable: KeyCodes -------- .. 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. .. _inputdevice-standardkeys: Standard Keys ************* 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 =============== ===== Non-Standard Keys ***************** 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 =============== ===== .. _inputdevice-mousecodetable: MouseCodes ---------- These are typically mapped to left, right and middle buttons respectively. =============== ===== MouseCode Name Value =============== ===== BUTTON_0 0 BUTTON_1 1 BUTTON_2 2 =============== ===== .. _inputdevice-padcodetable: PadCodes -------- 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 =============== =====