Input

Keyboard, mouse, and clipboard input detection and simulation.

input.simulate_mouse

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

Description: Simulates mouse input using location or flags.

Parameters:

dx (number): Horizontal movement delta in pixels
dy (number): Vertical movement delta in pixels
flag (number): Mouse event flag (0: move, 1: left down, 2: left up, 4: right down, 8: right up)

Returns: None

Example:

-- Simulate mouse movement
input.simulate_mouse(5, 3, 0)  -- Move 5 pixels right, 3 pixels down

-- Simulate left mouse click (down and up)
input.simulate_mouse(0, 0, 1)  -- Left button down
engine.delay(16, function()
    input.simulate_mouse(0, 0, 2)  -- Left button up
end)

-- Simulate right mouse click at current position
input.simulate_mouse(0, 0, 4)  -- Right button down
engine.delay(16, function()
    input.simulate_mouse(0, 0, 8)  -- Right button up
end)

input.simulate_keyboard

Signature: input.simulate_keyboard(key, flag)

Description: Simulates keyboard input using virtual key codes and flags.

Parameters:

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

Returns: None

Example:

-- Simulate pressing and releasing the 'A' key (Virtual key code 65)
input.simulate_keyboard(65, 1)  -- Key down
engine.delay(16, function()
    input.simulate_keyboard(65, 2)  -- Key up
end)

-- Simulate pressing Enter (Virtual key code 13)
input.simulate_keyboard(13, 1)  -- Key down
engine.delay(16, function()
    input.simulate_keyboard(13, 2)  -- Key up
end)

input.is_key_pressed

Signature: input.is_key_pressed(key)

Description: Detects if a key is pressed once (triggers only on the initial press).

Parameters:

key (number): Virtual key code to check.

Returns:

boolean: true if the key was just pressed, false otherwise.

Example:

-- Check if the spacebar (key code 32) was just pressed
function check_spacebar()
    if input.is_key_pressed(32) then
        engine.log("Spacebar was just pressed!", 255, 255, 255, 255)
        -- Execute action once on press
    end
end

engine.register_on_engine_tick(check_spacebar)

input.is_key_down

Signature: input.is_key_down(key)

Description: Detects if a key is being held down continuously.

Parameters:

key (number): Virtual key code to check.

Returns:

boolean: true if the key is being held down, false otherwise.

Example:

-- Check if the Ctrl key (key code 17) is being held down
function check_ctrl_key()
    if input.is_key_down(17) then
        engine.log("Ctrl key is being held down", 255, 255, 255, 255)
        -- Execute continuous action while key is down
    end
end

engine.register_on_engine_tick(check_ctrl_key)

input.is_key_toggled

Signature: input.is_key_toggled(key)

Description: Checks if a key's toggle state is active (useful for keys like Caps Lock).

Parameters:

key (number): Virtual key code to check.

Returns:

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

Example:

-- Check if Caps Lock (key code 20) is toggled on
function check_caps_lock()
    if input.is_key_toggled(20) then
        engine.log("Caps Lock is toggled on", 255, 255, 255, 255)
        -- Perform action based on Caps Lock state
    else
        engine.log("Caps Lock is toggled 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: Returns the current mouse cursor position.

Parameters: None

Returns:

x (number): The x-coordinate of the mouse cursor.
y (number): The y-coordinate of the mouse cursor.

Example:

-- Get the current mouse position
function track_mouse_position()
    local x, y = input.get_mouse_position()
    engine.log("Mouse Position: " .. x .. ", " .. y, 255, 255, 255, 255)
    
    -- Use position for cursor-based features
    if x < 100 and y < 100 then
        -- Mouse is in the top-left corner
        engine.log("Mouse in top-left corner", 255, 255, 0, 255)
    end
end

engine.register_on_engine_tick(track_mouse_position)

input.get_mouse_move_delta

Signature: input.get_mouse_move_delta()

Description: Returns the mouse movement delta (change) since the last tick.

Parameters: None

Returns:

dx (number): The change in x-coordinate since the last tick.
dy (number): The change in y-coordinate since the last tick.

Example:

-- Track mouse movement delta
function track_mouse_movement()
    local dx, dy = input.get_mouse_move_delta()
    
    if dx ~= 0 or dy ~= 0 then
        engine.log("Mouse Movement Delta: " .. dx .. ", " .. dy, 255, 255, 255, 255)
        
        -- Detect quick movements
        local movement_distance = math.sqrt(dx*dx + dy*dy)
        if movement_distance > 50 then
            engine.log("Fast mouse movement detected!", 255, 0, 0, 255)
        end
    end
end

engine.register_on_engine_tick(track_mouse_movement)

input.get_scroll_delta

Signature: input.get_scroll_delta()

Description: Returns the mouse scroll wheel delta since the last tick.

Parameters: None

Returns:

number: The scroll wheel delta (positive for scrolling up, negative for scrolling down).

Example:

-- Track mouse scroll wheel
function track_scroll_wheel()
    local scroll_delta = input.get_scroll_delta()
    
    if scroll_delta ~= 0 then
        if scroll_delta > 0 then
            engine.log("Scrolled up: " .. scroll_delta, 0, 255, 0, 255)
            -- Perform scroll up action
        else
            engine.log("Scrolled down: " .. scroll_delta, 255, 0, 0, 255)
            -- Perform scroll down action
        end
    end
end

engine.register_on_engine_tick(track_scroll_wheel)

input.get_clipboard

Signature: input.get_clipboard()

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

Parameters: None

Returns:

string: The text content of the clipboard.

Example:

-- Read clipboard content
function read_clipboard()
    local clipboard_text = input.get_clipboard()
    
    if clipboard_text and clipboard_text ~= "" then
        engine.log("Clipboard content: " .. clipboard_text, 255, 255, 255, 255)
        
        -- Process clipboard data
        if clipboard_text:match("^https?://") then
            engine.log("URL detected in clipboard!", 0, 255, 0, 255)
            -- Process URL
        end
    end
end

-- Check clipboard when a key is pressed
function clipboard_check_on_key()
    if input.is_key_pressed(86) and input.is_key_down(17) then  -- Ctrl+V
        read_clipboard()
    end
end

engine.register_on_engine_tick(clipboard_check_on_key)

input.set_clipboard

Signature: input.set_clipboard(text)

Description: Sets new text content to the system clipboard.

Parameters:

text (string): The text to set to the clipboard.

Returns: None

Example:

-- Copy text to clipboard
function copy_to_clipboard(text)
    input.set_clipboard(text)
    engine.log("Copied to clipboard: " .. text, 0, 255, 0, 255)
end

-- Example usage: Copy coordinates
function copy_coordinates()
    if input.is_key_pressed(67) and input.is_key_down(17) then  -- Ctrl+C
        local x, y = input.get_mouse_position()
        local coords_text = string.format("X: %d, Y: %d", x, y)
        copy_to_clipboard(coords_text)
    end
end

engine.register_on_engine_tick(copy_coordinates)

input.is_menu_open

Signature: input.is_menu_open()

Description: Checks if the menu is currently open.

Parameters: None

Returns:

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

Example:

-- Check menu state
function check_menu_state()
    if input.is_menu_open() then
        -- Menu is open, disable certain features
        engine.log("Menu is open - some features disabled", 255, 255, 0, 255)
    else
        -- Menu is closed, enable all features
        engine.log("Menu is closed - all features enabled", 0, 255, 0, 255)
    end
end

engine.register_on_engine_tick(check_menu_state)

input.set_overlay_force_cursor_active

Signature: input.set_overlay_force_cursor_active(state)

Description: Forces the overlay cursor to be active or inactive.

Parameters:

state (boolean): true to force the cursor active, false to allow normal behavior.

Returns: None

Example:

-- Force cursor to be visible when a key is held
function manage_cursor_visibility()
    if input.is_key_down(16) then  -- Shift key
        -- Force cursor to be visible while shift is held
        input.set_overlay_force_cursor_active(true)
    else
        -- Return to normal cursor behavior
        input.set_overlay_force_cursor_active(false)
    end
end

engine.register_on_engine_tick(manage_cursor_visibility)

Common Key Codes Reference

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

Common Keys:

Letters: A-Z (65-90)
Numbers: 0-9 (48-57)
Function keys: F1-F12 (112-123)
Backspace (8), Tab (9), Enter (13), Escape (27), Space (32)

Navigation:

Arrows: Left (37), Up (38), Right (39), Down (40)
Page Up (33), Page Down (34), Home (36), End (35)

Modifiers:

Shift (16), Ctrl (17), Alt (18)
Caps Lock (20), Num Lock (144)

PreviousFilesystem NextRendering

Last updated 2 months ago

Was this helpful?