SDK Reference

Complete reference for every namespace, function, and hook available in Rebind scripts.

Globals

Run

local handle = Run(fn: function) -> TaskHandle

Launches a function as a coroutine. Returns immediately. The function executes concurrently with other script code.

Returns a TaskHandle with:

• handle:Cancel() – stop the coroutine
• handle:IsRunning() – returns boolean

Sleep

Sleep(ms: number)

Pauses the current coroutine for ms milliseconds. Only valid inside a Run() block. Calling Sleep() outside a coroutine will raise a clear error. Does not block anything else.

After

local handle = After(ms: number, fn: function) -> TaskHandle

Shorthand for running a function after a delay. Equivalent to Run(function() Sleep(ms) fn() end). Returns a TaskHandle.

After(2000, function()
    Log.Info("2 seconds later")
end)

Async

local wrappedFn = Async(fn: function) -> function

Returns a new function that automatically runs fn in a coroutine when called. This lets you use Sleep() and other coroutine features inside callbacks that are normally synchronous (like Bind handlers).

When the wrapped function is called from the main thread, it spawns a Run() and returns false (swallow). When called from inside an existing coroutine, it calls fn directly to avoid double-wrapping.

-- without Async: manual Run() wrapping
Bind("F10", function()
    Run(function()
        HID.Down("W")
        Sleep(500)
        HID.Up("W")
    end)
    return false
end)

-- with Async: Sleep() just works
Bind(
    "F10",
    Async(function()
        HID.Down("W")
        Sleep(500)
        HID.Up("W")
    end)
)

Hooks

Global functions your script defines. The runtime calls them when events occur.

Lifecycle

function OnStart()          -- script loaded
function OnStop()           -- script about to unload
function OnFocus(window)    -- target window gained focus ({ title, process, x, y, width, height })
function OnBlur(window)     -- target window lost focus ({ title, process, x, y, width, height })
function OnTick(delta)      -- per-frame update (delta = ms since last tick)

Top-level code runs immediately when the script file is loaded, before OnStart is called. Use it for constants, module initialization, and guards that must run before anything else.

-- top-level: runs at load time
local BASE_SENS = 0.8

function OnStart()
    -- runs after the script is fully registered
    Log.Info("ready, sensitivity = " .. BASE_SENS)
end

OnStart is the right place for anything that needs the script to be fully registered first — such as reading persisted UI values or starting timers.

Input

All input hooks can return false to block the event from reaching the PC, or return true to pass it through.

function OnDown(key)                -- key/button pressed
function OnUp(key, durationMs)      -- key/button released
function OnMove(dx, dy)             -- mouse moved
function OnScroll(delta)            -- vertical scroll

Other (reserved, not yet dispatched)

These hooks are recognized by the script validator but are not dispatched by the relay in the current release. Defining them will not cause errors; they simply won’t fire.

function OnScrollH(delta)           -- horizontal scroll (tilt wheel)
function OnReload()                 -- script reloaded from disk
function OnError(message)           -- runtime error in a hook or coroutine

System

Read-only methods updated automatically every tick.

System.Exec

local result = System.Exec(cmd: string, options?: { timeout?: number, cwd?: string })

Runs a shell command (cmd.exe /C on Windows, sh -c on Linux) and returns when it completes.

Returns: { exit: number, stdout: string, stderr: string }

Options:

• timeout – max execution time in ms (default: 5000). The process is killed if it exceeds this.
• cwd – working directory for the command.

Output is capped at 64KB per stream. The console window is suppressed on Windows.

-- list files
local result = System.Exec("dir /b", { cwd = "C:\\Users" })
Log.Info(result.stdout)

-- run a Python script
local result = System.Exec("python analyze.py", { timeout = 10000 })
if result.exit ~= 0 then
    Log.Error("Failed: " .. result.stderr)
end

Warning: System.Exec blocks the script tick while the command runs. Place long-running commands inside Run() to avoid stalling input processing.

HID

Sends keyboard and mouse output through the active transport.

Keyboard

Important: HID.Press and HID.Type use Sleep() internally and must be called inside a Run() coroutine or an Async() handler. Calling them outside a coroutine (e.g. directly in OnDown) will raise an error. Use HID.Down/HID.Up for non-blocking key control in hooks, or wrap your logic with Async().

-- WRONG: Press in a hook blocks the hot path
function OnDown(key)
    if key == "F1" then
        HID.Press("A") -- ERROR: not in a coroutine
    end
end

-- CORRECT: use Async to wrap the handler
Bind("F1", Async(function()
    HID.Press("LCtrl+V") -- works: Async provides a coroutine context
end))

-- CORRECT: use Run inside a hook
function OnDown(key)
    if key == "F1" then
        Run(function()
            HID.Press("A") -- works: Run provides a coroutine context
        end)
        return false
    end
    return true
end

-- CORRECT: non-blocking alternative (no coroutine needed)
function OnDown(key)
    if key == "F1" then
        HID.Down("A") -- instant, non-blocking
        return false
    end
    return true
end

Combos

Down, Up, and Press all support + for modifier combos:

HID.Press("LCtrl+V") -- Ctrl+V paste (coroutine only)
HID.Press("LCtrl+LShift+T") -- Ctrl+Shift+T (coroutine only)

HID.Down("LCtrl+LShift") -- hold both modifiers (non-blocking, works anywhere)
HID.Up("LCtrl+LShift") -- release both in reverse order (non-blocking)

HID.Press with combos presses keys left-to-right, sleeps for the hold duration (default 50ms), then releases right-to-left. HID.Down presses left-to-right. HID.Up releases right-to-left.

The + key itself is spelled Equal (unshifted) or KpPlus (numpad), so there is no ambiguity.

Mouse

Mouse Mode

Relative mode (default): single-pass movement, fast (~0.5ms), may drift. Best for games.

Absolute mode: iterative correction with position validation, slower (1-3ms), sub-5px accuracy. Best for desktop automation.

Input

Reads the current physical state of input devices.

UI

Defines a settings panel rendered in the Rebind UI.

Schema

local cfg = UI.Schema({
    key = UI.Widget(default, options?),
    ...
})

Returns a proxy handle. Read values with cfg.key, write with cfg.key = value.

Widgets

Widget Options

Other

Persistence

Values are saved automatically on every change and restored at startup. Persistence is keyed to the script’s file path – no configuration required.

Macro

Record and play back input sequences.

Playback

Speed: 1.0 = normal, 0.5 = half speed, 2.0 = double speed. Default: 1.0.

Mode: "parallel" (default), "replace".

Handle methods:

• handle:Stop()
• handle:Pause()
• handle:Resume()
• handle:IsPlaying() – returns boolean
• handle:GetProgress() – returns 0.0 to 1.0
• handle:Wait() – blocks the current coroutine until playback ends. must be called inside Run()

Hardware Streaming

Macros containing "type" actions always play host-side, since firmware cannot render text. Macro.Play() automatically falls back to host-side execution when any Type action is present.

Recording

Record options: { ignoreMouse = false, ignoreKeyboard = false, precision = "normal" }

Format

Actions in a macro table:

Timer

Handle methods: handle:Cancel(), handle:Pause(), handle:Resume()

Math

Random

Transforms

All transform functions return a new table (original is unchanged).

Interpolate vs Resample:

• Resample changes all delays uniformly (normalizing recorded macros)
• Interpolate adds intermediate steps between existing points (smoothing patterns)

JSON

Log

Globals: print(...) and log(...) are both aliases for Log.Info. They accept multiple arguments, joined by tabs — identical to standard Lua print behaviour.

log("feature enabled, sensitivity =", sensitivity)
print("device ready")

Logs appear in the Rebind UI Logs tab.

File

All paths are relative to your script’s directory. Path traversal (..) is rejected.

Net

Client

Response: { status: number, body: string, headers: table }

Options: { timeout = milliseconds } – optional trailing table for convenience methods.

Net.Request options: { method: string, url: string, body?: string, headers?: table, timeout?: number }

-- simple GET
local resp = Net.Get("https://api.example.com/data")

-- POST with headers
local resp = Net.Post(
    "https://api.example.com/data",
    JSON.Stringify({ key = "value" }),
    { ["Content-Type"] = "application/json", ["Authorization"] = "Bearer token" }
)

-- DELETE with timeout
local resp = Net.Delete("https://api.example.com/item/123", nil, { timeout = 5000 })

-- generic request
local resp = Net.Request({
    method = "PATCH",
    url = "https://api.example.com/item/123",
    body = JSON.Stringify({ name = "updated" }),
    headers = { ["Content-Type"] = "application/json" },
    timeout = 10000,
})

Custom headers (including User-Agent) can be set on any request via the headers table.

HTTP Server

local server = Net.Listen(port, handler)

Handler: receives request, returns { status, body, headers? }.

Server handle: server:Stop()

Example:

local server = Net.Listen(8080, function(req)
    if req.method == "POST" then
        local data = JSON.Parse(req.body)
        return { status = 200, body = "OK" }
    end
    return { status = 404, body = "Not Found" }
end)

WebSocket Server

local server = Net.WSListen(port, handlers)

Handlers table: all optional.

Client handle (passed to handlers): client.id, client:Send(text), client:SendBinary(bytes), client:Close().

Server handle: server:Broadcast(text), server:BroadcastBinary(bytes), server:ClientCount(), server:Stop().

The server binds 0.0.0.0:<port>. Events are dispatched to Lua handlers on the script’s tick loop. Up to 32 events are processed per tick per server; excess messages backlog into the next tick. There is no built-in rate limiting — scripts exposed to untrusted networks should implement their own.

Performance characteristics (localhost, Windows host):

Each connection uses a dedicated reader thread that blocks on the socket and a writer thread that blocks on the outbound queue — writes dispatch with zero polling latency. TCP_NODELAY is set on all accepted sockets so small request/response traffic does not pay Nagle’s algorithm cost. On Windows the relay raises the system timer resolution to 1 ms so the tick loop actually runs at its declared rate.

Example:

local server = Net.WSListen(19561, {
    OnMessage = function(client, payload, is_binary)
        if payload == "hello" then
            client:Send("world")
        else
            server:Broadcast("someone said: " .. payload)
        end
    end,
})

WebSocket Client

local conn = Net.WSConnect(url, handlers)

URL: ws://host:port/path or wss://host:port/path. TLS via rustls (webpki roots).

Handlers table: all optional.

Connection handle: conn:Send(text), conn:SendBinary(bytes), conn:Close().

Example:

local conn = Net.WSConnect("wss://echo.websocket.events", {
    OnOpen = function()
        conn:Send("hello from rebind")
    end,
    OnMessage = function(payload, is_binary)
        Log.Info("got: " .. payload)
    end,
})

Screen

Note: ~500us latency per call. Use sparingly.

Window

Window manipulation functions. Handles are integer values obtained from Window.Find() or Window.List(). Passing nil for a handle targets the active (foreground) window.

Query

Activation

Movement / Sizing

State Control

Appearance

Waiting

Examples

-- find and reposition a window
local hw = Window.Find("Notepad")
if hw then
    Window.Move(hw, 0, 0, 800, 600)
    Window.Activate(hw)
end

-- pin active window on top
local hw = Window.Find(System.Window().title)
if hw then
    Window.SetAlwaysOnTop(hw, true)
end

-- list all windows
for _, w in ipairs(Window.List()) do
    Log.Info(w.title .. " [" .. w.process .. "]")
end

-- wait for a game to launch
Run(function()
    local hw = Window.Wait("Counter-Strike 2", 30000)
    if hw then
        Window.Maximize(hw)
    end
end)

Audio

Audio.Play

local sound = Audio.Play("alert.wav")
local music = Audio.Play("bgm.mp3", { volume = 0.5, loop = true })

Options:

File paths are relative to the script directory (same sandboxing rules as File).

SoundHandle

The object returned by Audio.Play:

Always call Audio.StopAll() in OnStop and OnBlur to clean up playing sounds.

Clipboard

Read and write the system clipboard.

-- paste a multi-line message into Discord
local msg = "Line one\nLine two\nLine three"
Clipboard.Set(msg)
HID.Press("LCtrl+V")

-- read clipboard contents
local text = Clipboard.Get()
if text then
    Log.Info("Clipboard: " .. text)
end

Clipboard paste is the most reliable way to input multi-line or long text. Applications handle pasted newlines correctly, and there are no per-character timing concerns.

Dialog

Native OS dialogs for messages, confirmations, and file selection. All functions must be called inside Run() — they yield the coroutine while the dialog is open. Input processing, timers, and other coroutines continue running uninterrupted.

Linux/BSD: requires Zenity, KDialog, or YAD to be installed.

Message and Confirm

Options: { title?: string, level?: string }

level controls the icon: "info" (default), "warning", "error".

Run(function()
    Dialog.Message("Script finished.", { title = "Done" })

    local ok = Dialog.Confirm("Overwrite existing file?", { title = "Confirm", level = "warning" })
    if not ok then
        return
    end
end)

File Dialogs

Options: { title?: string, location?: string, filters?: { { name: string, extensions: { string } } } }

• location – initial directory the dialog opens in.
• filters – restrict the file types shown. Each entry has a display name and a list of extensions (without leading dot).

Run(function()
    -- open a single Lua file
    local path = Dialog.OpenFile({
        title = "Open Script",
        filters = {
            { name = "Lua Scripts", extensions = { "lua", "luau" } },
        },
    })
    if path then
        local code = File.Read(path)
    end

    -- save a file
    local dest = Dialog.SaveFile({
        title = "Save As",
        location = File.GetScriptDir(),
        filters = {
            { name = "JSON", extensions = { "json" } },
        },
    })
    if dest then
        File.WriteJSON(dest, data)
    end

    -- pick a directory
    local dir = Dialog.OpenDir({ title = "Select Output Folder" })
    if dir then
        Log.Info("Output: " .. dir)
    end
end)

Regex

Pattern matching using regular expressions (PCRE-style syntax via the Rust regex crate). Backtracking-free by design – no risk of catastrophic backtracking.

Use [[ ]] long strings for patterns to avoid Luau escape interpretation: [[\d+]] instead of "\\d+".

Match result

Regex.Find and Regex.FindAll return tables with:

{
    match = "full matched text",
    captures = { "group1", "group2" },  -- positional capture groups
    start = 8,    -- 1-indexed byte offset of match start
    finish = 11,  -- 1-indexed byte offset of match end
}

Replacement syntax

Replacements use $1, $2, etc. for capture group references:

Regex.ReplaceAll("John Smith", [[(\w+) (\w+)]], "$2, $1") --> "Smith, John"

Examples

-- test a pattern
if Regex.IsMatch(win.process, "discord|slack|teams") then
    -- chat app behavior
end

-- extract data
local m = Regex.Find("Price: 500g", [[(\d+)g]])
if m then
    local amount = tonumber(m.captures[1]) --> 500
end

-- split CSV
local fields = Regex.Split("a,b,,d", ",") --> {"a", "b", "", "d"}

Note: Luau also has built-in Lua patterns (string.find, string.match, string.gmatch) which use different syntax (%d instead of \d). The Regex namespace uses standard regex syntax and supports features Lua patterns lack: alternation (|), non-greedy quantifiers, lookahead, and more.

Config

Read and write TOML configuration files. TOML is a superset of INI for common use cases – simple key = value files work as-is, with support for typed values (booleans, numbers, strings), arrays, and nested tables.

File paths are relative to the script directory (same sandboxing rules as File).

-- settings.toml:
-- [general]
-- sensitivity = 0.8
-- enabled = true
-- weapon = "ak47"

local cfg = Config.ReadTOML("settings.toml")
Log.Info(cfg.general.sensitivity) --> 0.8
Log.Info(cfg.general.weapon) --> "ak47"

-- modify and save
cfg.general.sensitivity = 1.0
Config.WriteTOML("settings.toml", cfg)

For JSON config files, use the File.ReadJSON / File.WriteJSON functions in the File namespace.

Pipe

Shared memory IPC for communicating with external processes (Python, Node.js, etc).

Opening

local pipe = Pipe.Open(name, options?)

Creates or opens a shared memory region. Options: { size = 65536 } (min 1024, max 16MB).

Methods

Properties

Script

Globals: exit(reason?) and die(reason?) are aliases for Script.Exit.

die("shutting down for maintenance")

Bind

Declarative key binding as an alternative to writing OnDown/OnUp handlers.

-- simple binding (action on press, key is blocked by default)
local handle = Bind("F10", function()
    HID.Type("Hello!")
end)

-- explicitly pass the key through to the PC
local handle = Bind("F10", function()
    Log.Info("F10 was pressed")
    return true -- pass through (must be explicit)
end)

-- binding with condition, press, and release handlers
local handle = Bind("Mouse1", {
    when = function()
        return Input.IsDown("LAlt") -- only activate when Alt is held
    end,
    action = function()
        Log.Info("pressed")
    end,
    release = function()
        Log.Info("released")
    end,
})

-- toggle a UI boolean on keypress
local handle = Bind.Toggle("F9", "enabled")

-- simple remap (no logic needed)
local handle = Bind.Remap("Mouse4", "4")

Blocking

Bind blocks by default. This is the opposite of OnDown/OnUp.

Most binds remap or trigger actions where blocking the original key is what you want. To pass the key through, you must explicitly return true.

When using Async() with Bind, the wrapper always returns false (block) immediately when it spawns the coroutine. Any return value inside the coroutine body has no effect on propagation – the decision was already made.

Handle

Handle methods: handle:unbind(), handle:disable(), handle:enable(), handle.enabled (read-only).

Routing

Keys claimed by Bind do not reach OnDown/OnUp. If a bind’s when guard returns false, the key falls through to the next bind or to OnDown/OnUp.

Modeline

-- rebind: key=value [key=value ...]

Rules:

• String-valued keys (name, description, author, window, process) must appear alone on their line
• Scalar keys (tick_rate, z_index, etc.) can share a line
• List fields use repeated keys: one window= per pattern, one process= per process, one permission= per permission

Permissions

By default, scripts can access all namespaces. If any permission= line is present, only the listed permissions are granted and all others are denied.

-- rebind: permission=exec
-- rebind: permission=net

-- now only exec and net are allowed; other restricted namespaces are open

Scripts published to the marketplace should declare the minimum permissions they need. Scripts without any permission= line have full access (backward compatible default).

Key Reference

Key names are case-insensitive. "F1", "f1", and "F1" are all identical. Use these strings with HID.Down, HID.Up, HID.Press, Bind, and in OnDown/OnUp hooks.

Letters

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Numbers

0 1 2 3 4 5 6 7 8 9

Function Keys

F1 through F24. F13-F24 are HID output only (they work with HID.Press but will not appear in OnDown/OnUp hooks).

Mouse Buttons

Modifiers

Editing and Control

Navigation

System

Punctuation

These names refer to the physical key, regardless of shift state.

Numpad

Media Keys (HID Output Only)

These can be sent via HID.Press but will not appear in input hooks.