User Input > Keyboard & Mouse


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


Keyboard

Key Status

control is down

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

shift key is down

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

isShiftDown()
isCtrlDown()

Simulate Keys

simulate key press using control

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

key code of enter key

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.DELETE
Key.SHIFT
Key.CONTROL

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

mouse is down

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

mouse is down on actor

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()
[ACTOR].isMouseOver()

Mouse / Touch Position

x of mouse

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

hide mouse cursor

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();