Skip to content

Input

The Input class provides access to the keyboard, mouse, gamepads, and the clipboard.

Synopsis

Static Methods

Mouse

Keyboard

Gamepad

Cursor

Clipboard

Static Members

Static Methods

Mouse Methods

Input.mouse([window])

Returns a table containing the mouse coordinates, wheel deltas, and related data.

Parameters:

Parameter Type Required Description
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: table: A table containing mouse values

Mouse Table

Field Type Description
x int Mouse X position on given window.
y int Mouse Y position on given window.
global_x int Mouse X position in screen space.
global_y int Mouse Y position in screen space.
wheel_x int Horizontal mouse wheel scroll delta.
wheel_y int Vertical mouse wheel scroll delta.
buttons table Table of mouse buttons statuses tables with pressed, released and down fields.

Input.mouse_down(button[, window])

Reports whether a specific mouse button is currently held down.

Parameters:

Parameter Type Required Description
button int Yes The mouse button identifier (e.g., Input.MouseLeft).
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: bool: true if the button is held down, false otherwise.

Input.mouse_global_x()

Returns the current global mouse X position in screen space.

  • Returns: int: Global screen X coordinate.

Input.mouse_global_y()

Returns the current global mouse Y position in screen space.

  • Returns: int: Global screen Y coordinate.

Input.mouse_pressed(button[, window])

Reports whether a mouse button was pressed during the current frame.

Parameters:

Parameter Type Required Description
button int Yes The mouse button identifier.
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: bool: true if pressed this frame, false otherwise.

Input.mouse_released(button[, window])

Reports whether a mouse button was released during the current frame.

Parameters:

Parameter Type Required Description
button int Yes The mouse button identifier.
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: bool: true if released this frame, false otherwise.

Input.mouse_wheel_x([window])

Returns the horizontal mouse wheel delta for the current frame.

Parameters:

Parameter Type Required Description
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: float: Horizontal scroll wheel displacement.

Input.mouse_wheel_y([window])

Returns the vertical mouse wheel delta for the current frame.

Parameters:

Parameter Type Required Description
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: float: Vertical scroll wheel displacement.

Input.mouse_x([window])

Returns the current mouse X position on given window.

Parameters:

Parameter Type Required Description
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: int: Local window X coordinate.

Input.mouse_y([window])

Returns the current mouse Y position on given window.

Parameters:

Parameter Type Required Description
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: int: Local window Y coordinate.

Keyboard Methods

Input.chars([window])

Returns any text characters entered or typed during the current frame.

Parameters:

Parameter Type Required Description
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: string: A UTF-8 sequence of typed input characters.

Input.key_down(key[, window])

Reports whether a specific keyboard key is currently being held down.

Parameters:

Parameter Type Required Description
key int Yes Key scancode constant identifier (e.g., Input.KeyA).
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: bool: true if held down, false otherwise.

Input.key_pressed(key[, window])

Reports whether a specific key was freshly pressed during the current frame.

Parameters:

Parameter Type Required Description
key int Yes Key scancode identifier.
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: bool: true if pressed this frame, false otherwise.

Input.key_released(key[, window])

Reports whether a specific key was released during the current frame.

Parameters:

Parameter Type Required Description
key int Yes Key scancode identifier.
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: bool: true if released this frame, false otherwise.

Input.key_repeat(key[, window])

Reports whether a system key-repeat flag is active for the given held key on this frame.

Parameters:

Parameter Type Required Description
key int Yes Key scancode identifier.
window Window | int No Target window context. Defaults to the currently focused window.
  • Returns: bool: true if repeating this frame, false otherwise.

Gamepad Methods

Input.gamepad_axis(axis[, slot])

Returns the displacement analog value for a given gamepad joystick axis.

Parameters:

Parameter Type Required Description
axis int Yes Gamepad axis constant identifier (e.g., Input.GamepadAxisLeftX).
slot int No Gamepad slot index identifier. Default: 0.
  • Returns: float: Axis displacement reading.

Input.gamepad_button_down(button[, slot])

Reports whether a button is currently held down on a specific gamepad controller.

Parameters:

Parameter Type Required Description
button int Yes Gamepad button constant identifier (e.g., Input.GamepadDPadUp).
slot int No Gamepad slot index identifier. Default: 0.
  • Returns: bool: true if held down, false otherwise.

Input.gamepad_button_pressed(button[, slot])

Reports whether a gamepad button was freshly pressed during the current frame.

Parameters:

Parameter Type Required Description
button int Yes Gamepad button constant identifier.
slot int No Gamepad slot index identifier. Default: 0.
  • Returns: bool: true if pressed this frame, false otherwise.

Input.gamepad_button_released(button[, slot])

Reports whether a gamepad button was released during the current frame.

Parameters:

Parameter Type Required Description
button int Yes Gamepad button constant identifier.
slot int No Gamepad slot index identifier. Default: 0.
  • Returns: bool: true if released this frame, false otherwise.

Input.gamepad_count()

Returns the total count of currently connected gamepads.

  • Returns: int: Number of active gamepads.

Input.gamepad_flush(slot)

Wipes input mapping for a given logical slot.

Parameters:

Parameter Type Required Description
slot int No Gamepad slot index identifier. Default: 0.

Input.gamepad_name(index)

Returns the hardware name of given gamepad.

Parameters:

Parameter Type Required Description
index int No Gamepad hardware index identifier. Default: 0.
  • Returns: string: The name of the gamepad hardware.

Input.gamepad_reassign_slot(index, slot)

Reassign a gamepad to another slot. Use -1 to unbind a gamepad.

Parameter Type Required Description
index int No Gamepad hardware index identifier. Default: 0.
slot int No Gamepad slot index identifier. Default: 0.
  • Returns: bool: true if reassignement succeeded, false otherwise.

Input.gamepad_slot(index)

Returns the logical slot of given gamepad.

Parameters:

Parameter Type Required Description
index int No Gamepad hardware index identifier. Default: 0.
  • Returns: int: Active slot or -1 if unassigned.

Cursor Methods

Input.cursor_visible()

Reports whether the system pointer cursor is currently visible over application windows.

  • Returns: bool: true if visible, false otherwise.

Input.set_cursor(path)

Changes the look of the system mouse cursor using an image path or a standard system cursor constant.

Parameters:

Parameter Type Required Description
path string Yes Image path or system cursor string constant.

Input.set_cursor_visible(visible)

Configures the screen mouse cursor display visibility state.

Parameters:

Parameter Type Required Description
visible bool Yes true to make it visible, false to hide it.

Clipboard Methods

Input.clipboard([text])

Interacts with the system clipboard to either copy text content or read the text it currently holds.

Parameters:

Parameter Type Required Description
text string No Text content to copy into the clipboard system. If omitted, performs a read query instead.
  • Returns: string | null: The string text contained inside the clipboard if called without arguments; otherwise returns null.

Static Members

Mouse Constants

Constant Type Description
Input.MouseLeft int Left mouse button.
Input.MouseMiddle int Middle mouse button.
Input.MouseRight int Right mouse button.
Input.MouseX1 int Extended X1 mouse side button.
Input.MouseX2 int Extended X2 mouse side button.

Cursor Constants

Constant Type Description
Input.CursorDefault string Standard system arrow pointer.
Input.CursorText string Text insertion I-beam pointer.
Input.CursorWait string Hourglass or system busy wait cursor.
Input.CursorCrosshair string Precision crosshair selector cursor.
Input.CursorProgress string Background task progress pointer.
Input.CursorMove string Omnidirectional generic move cursor.
Input.CursorNotAllowed string Action forbidden standard symbol cursor.
Input.CursorPointer string Context link selection hand pointer.
Input.CursorResizeNorth string Upwards edge resize arrow.
Input.CursorResizeNorthEast string Diagonal Upwards/Rightwards edge resize arrow.
Input.CursorResizeEast string Rightwards edge resize arrow.
Input.CursorResizeSouthEast string Diagonal Downwards/Rightwards edge resize arrow.
Input.CursorResizeSouth string Downwards edge resize arrow.
Input.CursorResizeSouthWest string Diagonal Downwards/Leftwards edge resize arrow.
Input.CursorResizeWest string Leftwards edge resize arrow.
Input.CursorResizeNorthWest string Diagonal Upwards/Leftwards edge resize arrow.
Input.CursorResizeNorthSouth string Vertical Upwards/Downwards arrow.
Input.CursorResizeEastWest string Horizontal Leftwards/Rightwards arrow.
Input.CursorResizeNorthWestSouthEast string
Input.CursorResizeNorthEastSouthWest string

Gamepad Constants

Constant Type Description
Input.GamepadAxisLeftX int Left stick horizontal axis.
Input.GamepadAxisLeftY int Left stick vertical axis.
Input.GamepadAxisRightX int Right stick horizontal axis.
Input.GamepadAxisRightY int Right stick vertical axis.
Input.GamepadAxisLeftTrigger int Left trigger axis.
Input.GamepadAxisRightTrigger int Right trigger axis.
Input.GamepadButtonBack int Back button.
Input.GamepadButtonDPadDown int Directional Pad down button.
Input.GamepadButtonDPadLeft int Directional Pad left button.
Input.GamepadButtonDPadRight int Directional Pad right button.
Input.GamepadButtonDPadUp int Directional Pad up button.
Input.GamepadButtonEast int East button.
Input.GamepadButtonGuide int Guide button.
Input.GamepadButtonLeftPaddle1 int Upper or primary paddle, under left hand
Input.GamepadButtonLeftPaddle2 int Lower or secondary paddle, under left hand
Input.GamepadButtonLeftShoulder int Left bumper control shoulder.
Input.GamepadButtonLeftStick int Left thumbstick analog button.
Input.GamepadButtonMisc1 int Additional button
Input.GamepadButtonMisc2 int Additional button
Input.GamepadButtonMisc3 int Additional button
Input.GamepadButtonMisc4 int Additional button
Input.GamepadButtonMisc5 int Additional button
Input.GamepadButtonMisc6 int Additional button
Input.GamepadButtonNorth int North button.
Input.GamepadButtonRightPaddle1 int Upper or primary paddle, under right hand
Input.GamepadButtonRightPaddle2 int Lower or secondary paddle, under right hand
Input.GamepadButtonRightShoulder int Right bumper control shoulder.
Input.GamepadButtonRightStick int Right thumbstick analog button.
Input.GamepadButtonSouth int South button.
Input.GamepadButtonStart int Start button.
Input.GamepadButtonTouchpad int Touchpad button.
Input.GamepadButtonWest int West button.
Input.GamepadSlots int Count of gamepad slots.

Diamond pattern

For controllers that use a diamond pattern for the face buttons, the Input.GamepadButtonSouth / Input.GamepadButtonEast / Input.GamepadButtonWest / Input.GamepadButtonNorth buttons correspond to the locations in the diamond pattern.

Console Controller South East North West
PlayStation Cross Circle Triangle Square
Nintendo (Except GameCube) B A X Y
Nintendo GameCube A X Y B
XBox A B Y X

Without diamond

For controllers that don't use a diamond pattern for the face buttons, the Input.GamepadButtonSouth / Input.GamepadButtonEast / Input.GamepadButtonWest / Input.GamepadButtonNorth buttons indicate the buttons labeled A, B, C, D, or 1, 2, 3, 4, or for controllers that aren't labeled, they are the primary, secondary, etc. buttons.

Keyboard Constants

Basic keys

Constant Type Description
Input.KeyBackspace int
Input.KeyTab int
Input.KeyReturn int
Input.KeyEscape int
Input.KeySpace int
Input.KeyExclaim int
Input.KeyQuoteDbl int
Input.KeyHash int
Input.KeyPercent int
Input.KeyDollar int
Input.KeyAmpersand int
Input.KeyQuote int
Input.KeyLeftParen int
Input.KeyRightParen int
Input.KeyApostrophe int
Input.KeyPlus int
Input.KeyComma int
Input.KeyMinus int
Input.KeyPeriod int
Input.KeySlash int
Input.Key0 int
Input.Key1 int
Input.Key2 int
Input.Key3 int
Input.Key4 int
Input.Key5 int
Input.Key6 int
Input.Key7 int
Input.Key8 int
Input.Key9 int
Input.KeyColon int
Input.KeySemicolon int
Input.KeyLess int
Input.KeyEquals int
Input.KeyGreater int
Input.KeyQuestion int
Input.KeyAt int
Input.KeyLeftBracket int
Input.KeyBackslash int
Input.KeyRightBracket int
Input.KeyCaret int
Input.KeyUnderscore int
Input.KeyBackquote int
Input.KeyA int
Input.KeyB int
Input.KeyC int
Input.KeyD int
Input.KeyE int
Input.KeyF int
Input.KeyG int
Input.KeyH int
Input.KeyI int
Input.KeyJ int
Input.KeyK int
Input.KeyL int
Input.KeyM int
Input.KeyN int
Input.KeyO int
Input.KeyP int
Input.KeyQ int
Input.KeyR int
Input.KeyS int
Input.KeyT int
Input.KeyU int
Input.KeyV int
Input.KeyW int
Input.KeyX int
Input.KeyY int
Input.KeyZ int
Input.KeyDelete int
Input.KeyCapsLock int
Input.KeyF1 int
Input.KeyF2 int
Input.KeyF3 int
Input.KeyF4 int
Input.KeyF5 int
Input.KeyF6 int
Input.KeyF7 int
Input.KeyF8 int
Input.KeyF9 int
Input.KeyF10 int
Input.KeyF11 int
Input.KeyF12 int
Input.KeyPrintScreen int
Input.KeyScrollLock int
Input.KeyPause int
Input.KeyInsert int
Input.KeyHome int
Input.KeyPageUp int
Input.KeyEnd int
Input.KeyPageDown int
Input.KeyRight int
Input.KeyLeft int
Input.KeyDown int
Input.KeyUp int

Keypad keys

Constant Type Description
Input.KeyNumLockClear int
Input.KeyKPDivide int
Input.KeyKPMultiply int
Input.KeyKPMinus int
Input.KeyKPPlus int
Input.KeyKPEnter int
Input.KeyKP1 int
Input.KeyKP2 int
Input.KeyKP3 int
Input.KeyKP4 int
Input.KeyKP5 int
Input.KeyKP6 int
Input.KeyKP7 int
Input.KeyKP8 int
Input.KeyKP9 int
Input.KeyKP0 int
Input.KeyKPPeriod int

Modifiers keys

Constant Type Description
Input.KeyLCtrl int
Input.KeyLShift int
Input.KeyLAlt int
Input.KeyLGUI int
Input.KeyRCtrl int
Input.KeyRShift int
Input.KeyRAlt int
Input.KeyRGUI int