User Input > Keyboard & Mouse


Read our article on Controls for more information on handling user input.


Keyboard

Key Status

key-block

Returns true if the given control [is down, was pressed, was released].

State Description
is down Key is currently pressed down.
was pressed Key was just pressed down. Called once per press-release cycle.
was released Key was just released. Called once per press-release cycle.
isKeyDown([CONTROL])
isKeyPressed([CONTROL])
isKeyReleased([CONTROL])

Special Key is Down

special-block

Returns true if [shift / ctrl] is currently being held down. On a Mac, ctrl is equivalent to command.

isShiftDown()
isCtrlDown()

Simulate Keys

special-block

Simulates a key [press / release] using the given control. Primarily used for implementing virtual controls as on-screen buttons in mobile games. Could also be used to make cutscenes.

simulateKeyPress([CONTROL]);
simulateKeyRelease([CONTROL]);

Get Key Code

special-block

Returns the hardware code for certain keys [enter, backspace, shift, delete, ctrl / command]. Compare this number with the code returned by an Any Key event. Could be used to implement a text field.

Key.ENTER
Key.BACKSPACE
Key.SHIFT
Key.DELETE
Key.CTRL

Example

keycode-example

A simple implementation of a text-field behavior. See the "Example: Text Input" section of our Controls guide for an explanation.


Mouse / Touch

Mouse and Single Touch (vs. Multi-Touch) are handled using the same blocks, as described in our Touch article.

Mouse / Touch Status

status-block

Returns true if the mouse [is down, was pressed, was released].

State Description
is down Mouse button is currently pressed down.
was pressed Mouse button was just pressed down. Called once per click-release cycle.
was released Mouse button was just released. Called once per click-release cycle.
isMouseDown()
isMousePressed()
isMouseReleased()

Mouse on Actor / Touched Actor

actor-block

Returns true if the mouse [is down on, was pressed on, was released on] the given actor.

State Description
is down Mouse button is currently pressed down.
was pressed Mouse button was just pressed down. Called once per click-release cycle.
was released Mouse button was just released. Called once per click-release cycle.
[ACTOR].isMouseDown()
[ACTOR].isMousePressed()
[ACTOR].isMouseReleased()

Mouse / Touch Position

position-block

Returns the last known (x, y) position of the [mouse (cursor), mouse press, mouse release]. Before using mouse press/release, first check if the mouse has been pressed or released.

On mobile, only mouse press/release are available since there's no concept of a mouse hovering over the screen.

getMouseX()
getMouseY()
getMousePressedX()
getMousePressedY()
getMouseReleasedX()
getMouseReleasedY()

Mouse Cursor

cursor-block

Shows or hides the mouse cursor. Doesn't apply to mobile games. Useful for implementing custom cursors (using an actor that follows the mouse).

hideCursor();
showCursor();