Mouse API

Simulate mouse movements, clicks, and scrolling with human-like behavior.

mouse:move_to(x: number, y: number, duration_ms: number?) -> ()

Move mouse to position with human-like behavior.

Parameters:

Parameter	Type	Required	Description
x	number	Yes	Target X coordinate
y	number	Yes	Target Y coordinate
duration_ms	number	No	Movement duration in milliseconds

Example:

mouse:move_to(400, 300)  -- Move to (400, 300)
mouse:move_to(400, 300, 500)  -- Move over 500ms

---

mouse:left_click(x: number, y: number, duration_ms: number?) -> ()

Left click at position.

Parameters:

Parameter	Type	Required	Description
x	number	Yes	Click X coordinate
y	number	Yes	Click Y coordinate
duration_ms	number	No	Movement duration before click

Example:

mouse:left_click(300, 250)

---

mouse:right_click(x: number, y: number, duration_ms: number?) -> ()

Right click at position.

Parameters:

Parameter	Type	Required	Description
x	number	Yes	Click X coordinate
y	number	Yes	Click Y coordinate
duration_ms	number	No	Movement duration before click

---

mouse:click() -> ()

Click at current mouse position.

---

mouse:position() -> Point

Gets current mouse position.

Returns:

• Point - Current position with x, y

Example:

local x, y = mouse:position()
logger:info("Mouse at: " .. x .. ", " .. y)

---

mouse:scroll(delta: number, x: number, y: number) -> ()

Scroll vertically.

Parameters:

Parameter	Type	Required	Description
delta	number	Yes	Positive to scroll up, negative to scroll down
x	number	Yes	X position to scroll at
y	number	Yes	Y position to scroll at

Example:

mouse:scroll(5, 400, 300)  -- Scroll up 5 notches
mouse:scroll(-3, 400, 300)  -- Scroll down 3 notches

---

mouse:scroll_horizontal(delta: number, x: number, y: number) -> ()

Scroll horizontally.

Parameters:

Parameter	Type	Required	Description
delta	number	Yes	Positive for right, negative for left
x	number	Yes	X position
y	number	Yes	Y position

---

mouse:set_speed(multiplier: number) -> ()

Set mouse movement speed multiplier.

Parameters:

Parameter	Type	Required	Description
multiplier	number	Yes	Speed multiplier (1.0 = normal)

Example:

mouse:set_speed(0.5)  -- Half speed
mouse:set_speed(2.0)  -- Double speed

---

mouse:get_speed() -> number

Get current speed multiplier.

Returns:

• number - Speed multiplier

---

mouse:is_in_window(x: number, y: number) -> boolean

Check if position is in game window.

Parameters:

Parameter	Type	Required	Description
x	number	Yes	X coordinate
y	number	Yes	Y coordinate

Returns:

• boolean - True if in window

---

mouse:track(entity: LuaNpc | LuaPlayer | LuaGameObject | LuaGroundItem, options?: table) -> ()

Start tracking a live entity: a dedicated thread keeps moving the mouse to hover over the entity. Tracking continues until the entity is no longer valid (e.g. despawns, moves out of view), another mouse API call is made (move_to, left_click, right_click, click, scroll, etc.), or an optional timeout is reached. Call mouse:stop_track() to stop without performing another action.

Parameters:

Parameter	Type	Required	Description
entity	LuaNpc | LuaPlayer | LuaGameObject | LuaGroundItem	Yes	The entity to track
options	table	No	{ timeout = number } — stop tracking after this many milliseconds

Example:

local cow = npcs:nearest("Cow")
if cow then
    mouse:track(cow)                    -- Track until entity invalid or another mouse call
    mouse:track(cow, { timeout = 5000 }) -- Track for up to 5 seconds
end

-- Later: stop tracking without clicking
mouse:stop_track()

---

mouse:stop_track() -> ()

Stop mouse tracking without performing any other mouse action. Has no effect if no entity is currently being tracked.

---

mouse:move_off_screen() -> ()

Move the mouse to a random off-screen position with human-like movement. This is useful for reducing on-screen distractions or simulating natural behavior when the player is idle.

The mouse will move to a random edge (top, right, bottom, or left) at a random distance (20-100 pixels) beyond the game window bounds.

Example:

-- Move mouse off-screen before waiting
mouse:move_off_screen()
sleep(5000)

-- Move off-screen after completing a task
bank:close()
mouse:move_off_screen()

Use Cases:

• Reducing visual clutter during idle periods
• Simulating natural player behavior when AFK
• Moving cursor away before taking screenshots
• Preventing accidental hovers during waits

---

Per-entity methods: LuaNpc, LuaPlayer, LuaGameObject, LuaGroundItem, Tile, LocalTile, LuaComponent, and LuaItem each have move_mouse_to() and track(). See NPC, Player, GameObject, GroundItem, Tile, LocalTile, Component, and Item.

---

local function safe_click(x, y)
    if mouse:is_in_window(x, y) then
        mouse:left_click(x, y)
        return true
    else
        logger:warn("Click target out of bounds: " .. x .. ", " .. y)
        return false
    end
end

---

local function right_click_and_select(x, y, action_text)
    mouse:right_click(x, y)
    sleep(300)  -- Wait for menu
    
    local menu_items = menu:items()
    for _, item in ipairs(menu_items) do
        if item:action():find(action_text) then
            mouse:left_click(
                menu:slot_center(item:index()).x,
                menu:slot_center(item:index()).y
            )
            return true
        end
    end
    
    return false
end

---

local function click_random_in_area(x1, y1, x2, y2)
    local x = math.random(x1, x2)
    local y = math.random(y1, y2)
    
    -- Add slight movement delay for human-like behavior
    local delay = math.random(50, 150)
    mouse:left_click(x, y, delay)
end

-- Click random point in component
local comp = components:get(149, 0)
click_random_in_area(
    comp:x(),
    comp:y(),
    comp:x() + comp:width(),
    comp:y() + comp:height()
)

---

local function click_bank_item(item)
    local x = item:x()
    local y = item:y()
    local w = item:width()
    local h = item:height()
    
    -- Click center with random offset
    local center_x = x + w / 2
    local center_y = y + h / 2
    
    local offset_x = math.random(-w * 0.25, w * 0.25)
    local offset_y = math.random(-h * 0.25, h * 0.25)
    
    mouse:left_click(center_x + offset_x, center_y + offset_y, 100)
end

---

-- Move mouse off-screen during longer waits to reduce visual clutter
local function safe_wait(duration_ms)
    mouse:move_off_screen()
    sleep(duration_ms)
end

-- Use in scripts
safe_wait(5000)  -- Wait 5 seconds with mouse off-screen

-- Move off-screen after banking
if bank:open() then
    bank:deposit_all()
    bank:close()
    mouse:move_off_screen()  -- Natural behavior: move cursor away
    sleep(1000)
end

---

• Menu API - Right-click menus
• Keyboard API - Keyboard input
• Components API - UI elements