Input

Keyboard, mouse, and clipboard input detection and simulation.

The Input API uses standard Windows Virtual Key Codes for keyboard input functions. While common keys are listed below, you can find the complete reference in the Microsoft Virtual Key Codes Documentation

input.simulate_mouse

Signature: input.simulate_mouse(dx, dy, flag)

Description: Simulates mouse input using relative movement (dx, dy) and an event flag (bitmask defined by the platform/integration). Use (dx, dy) to move the cursor; use flag to indicate move/press/release actions.

Parameters:

dx (number): Horizontal movement delta in pixels.
dy (number): Vertical movement delta in pixels.
flag (number): Mouse event flag (implementation-defined bitmask). Common patterns include move-only, left-button down/up, right-button down/up.

Returns: None

Example (press & release over successive ticks, no timers):

local click_phase = -1
local MOUSE_LEFT_DOWN, MOUSE_LEFT_UP = 0x02, 0x04

function left_click_over_two_ticks()
    if click_phase == -1 then
        input.simulate_mouse(0, 0, MOUSE_LEFT_DOWN)
        click_phase = 1
    elseif click_phase == 1 then
        input.simulate_mouse(0, 0, MOUSE_LEFT_UP)
        click_phase = -1
    end
end

engine.register_on_engine_tick(left_click_over_two_ticks)

input.simulate_keyboard

Signature: input.simulate_keyboard(key, flag)

Description: Simulates keyboard input using a virtual-key code and an event flag.

Parameters:

key (number): Virtual-key code to simulate.
flag (number): Keyboard event flag (1 = key down, 2 = key up).

Returns: None

Example (press & release over successive ticks):

local VK_A, phase = 0x41, -1

function press_A_over_two_ticks()
    if phase == -1 then
        input.simulate_keyboard(VK_A, 1) -- press down
        phase = 1
    elseif phase == 1 then
        input.simulate_keyboard(VK_A, 2) -- release
        phase = -1
    end
end

engine.register_on_engine_tick(press_A_over_two_ticks)

input.is_key_pressed

Signature: input.is_key_pressed(key)

Description: Returns true once on the transition from up→down (edge-triggered) for the specified key.

Parameters:

key (number): Virtual-key code to check.

Returns:

boolean: true if the key was just pressed this frame/tick; otherwise false.

Example:

-- Fire once when Space is pressed (VK 32)
function check_spacebar()
    if input.is_key_pressed(32) then
        engine.log("Spacebar pressed!", 255, 255, 255, 255)
    end
end

engine.register_on_engine_tick(check_spacebar)

input.is_key_down

Signature: input.is_key_down(key)

Description: Returns true while the key is currently held (level-triggered).

Parameters:

key (number): Virtual-key code to check.

Returns:

boolean: true if the key is held; otherwise false.

Example:

-- Report while Ctrl is held (VK 17)
function check_ctrl_key()
    if input.is_key_down(17) then
        engine.log("Ctrl is down", 255, 255, 255, 255)
    end
end

engine.register_on_engine_tick(check_ctrl_key)

input.is_key_toggled

Signature: input.is_key_toggled(key)

Description: Returns true when a key's toggle state is active (e.g., Caps Lock).

Parameters:

key (number): Virtual-key code to check.

Returns:

boolean: true if the key's toggle state is active; otherwise false.

Example:

-- Caps Lock toggle (VK 20)
function check_caps_lock()
    if input.is_key_toggled(20) then
        engine.log("Caps Lock is ON", 255, 255, 255, 255)
    else
        engine.log("Caps Lock is OFF", 255, 255, 255, 255)
    end
end

engine.register_on_engine_tick(check_caps_lock)

input.get_mouse_position

Signature: input.get_mouse_position()

Description: Gets the current cursor position.

Parameters: None

Returns:

x (number): Current mouse X coordinate (pixels).
y (number): Current mouse Y coordinate (pixels).

Example:

function track_mouse_position()
    local x, y = input.get_mouse_position()
    engine.log(("Mouse: %d, %d"):format(x, y), 255, 255, 255, 255)
end

engine.register_on_engine_tick(track_mouse_position)

input.get_mouse_move_delta

Signature: input.get_mouse_move_delta()

Description: Gets (dx, dy) movement since the last frame/tick.

Parameters: None

Returns:

dx (number): Change in X since the last tick.
dy (number): Change in Y since the last tick.

Example:

function track_mouse_movement()
    local dx, dy = input.get_mouse_move_delta()
    if dx ~= 0 or dy ~= 0 then
        engine.log(("Delta: %d, %d"):format(dx, dy), 255, 255, 255, 255)
    end
end

engine.register_on_engine_tick(track_mouse_movement)

input.get_scroll_delta

Signature: input.get_scroll_delta()

Description: Gets the scroll-wheel delta since last tick (positive = up, negative = down).

Parameters: None

Returns:

number: Scroll delta value since the last tick.

Example:

function track_scroll_wheel()
    local d = input.get_scroll_delta()
    if d ~= 0 then
        engine.log("Scroll: " .. d, 255, 255, 255, 255)
    end
end

engine.register_on_engine_tick(track_scroll_wheel)

input.get_clipboard

Signature: input.get_clipboard()

Description: Reads the current text content of the system clipboard.

Parameters: None

Returns:

string: Clipboard text (empty string if none).

Example:

function read_clipboard()
    local t = input.get_clipboard()
    if t ~= "" then
        engine.log("Clipboard: " .. t, 255, 255, 255, 255)
    end
end

input.set_clipboard

Signature: input.set_clipboard(text)

Description: Sets text into the system clipboard.

Parameters:

text (string): Text to place on the clipboard.

Returns: None

Example:

function copy_coordinates()
    local x, y = input.get_mouse_position()
    input.set_clipboard(("%d,%d"):format(x, y))
    engine.log("Copied coordinates to clipboard", 0, 255, 0, 255)
end

input.is_menu_open

Signature: input.is_menu_open()

Description: Indicates whether the in-overlay menu is currently open.

Parameters: None

Returns:

boolean: true if the menu is open; otherwise false.

Example:

function check_menu_state()
    if input.is_menu_open() then
        engine.log("Menu is open", 255, 255, 0, 255)
    else
        engine.log("Menu is closed", 0, 255, 0, 255)
    end
end

input.set_overlay_force_cursor_active

Signature: input.set_overlay_force_cursor_active(state)

Description: Forces the overlay cursor to remain active/visible (or returns to normal behavior).

Parameters:

state (boolean): true to force the cursor active; false to restore normal behavior.

Returns: None

Example:

local state = false
function manage_cursor_visibility()
    if input.is_key_pressed(17) then  -- Ctrl
        state = not state
        input.set_overlay_force_cursor_active(state)
    end
end

engine.register_on_engine_tick(manage_cursor_visibility)

PreviousFilesystem NextRendering

Last updated 18 days ago

Was this helpful?