SDK Reference

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

Sleep(ms: number)

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

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

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

-- 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)
)

require(module: string) -> any

local helpers = require("helpers") -- helpers.luau next to the script
local m = require("lib.math") -- lib/math.luau

_REBIND: {
  name: string,
  version: string,
  min_sdk: string,
  tick_rate: number,
  runtime_uuid: string,
  instance: string,
}

Log.Info("Running " .. _REBIND.name .. " v" .. _REBIND.version)
Log.Info("SDK: " .. _REBIND.min_sdk .. ", tick rate: " .. _REBIND.tick_rate)

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(dtMs)       -- dtMs = ms elapsed since the previous OnTick (0 on the first)

-- 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

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

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

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

-- 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

local pid = System.ExecDetached(cmd: string, args?: string[], options?: { cwd?: string })

-- open a file in the default editor and keep going
local pid = System.ExecDetached("notepad.exe", { "notes.txt" })
Log.Info("launched editor, PID " .. pid)

-- 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

HID.Combo("LCtrl+V") -- Ctrl+V paste in one call (non-blocking, works anywhere)
HID.Combo("cmd+shift+r") -- ⇧⌘R (macOS aliases; non-blocking)

HID.Press("LCtrl+V") -- same effect, but coroutine-only and holds for a duration
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)

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

Log.Info(Hash.SHA256("abc")) --> "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"

-- sign an API request
local sig = Hash.HMAC("sha256", apiSecret, payload)

local encoded = Codec.Base64("hello") --> "aGVsbG8="
local decoded = Codec.Base64Decode(encoded) --> "hello"

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

-- 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,
})

local server = Net.Listen(port, handler)

local server = Net.WSListen(port, handlers)

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,
})

local conn = Net.WSConnect(url, handlers)

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,
})

-- find a dark-red pixel in a region of the screen
local match = Screen.SearchForColor({ 900, 500, 1100, 530 }, "8b0000", 0.05)
if match then
  Log.Info("found at " .. match.x .. ", " .. match.y)
end

-- sample a color, then search for it elsewhere
local color = Screen.GetPixelColor(960, 540)
local match = Screen.SearchForColor({ 0, 0, 1920, 1080 }, color, 0.1)

for _, m in ipairs(Screen.List()) do
  Log.Info(
    "Monitor "
      .. m.index
      .. ": "
      .. m.width
      .. "x"
      .. m.height
      .. (m.primary and " (primary)" or "")
  )
end

local cap = Screen.Capture() -- display under the cursor
local cap = Screen.Capture({ display = 2 }) -- a specific monitor
local cap = Screen.Capture({ region = { x = 0, y = 0, w = 320, h = 240 } })
Log.Info(
  "captured "
    .. cap.width
    .. "x"
    .. cap.height
    .. " from display "
    .. cap.display.index
)

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

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

-- wait for an application to launch
Run(function()
  local hw = Window.Wait("Untitled - Notepad", 30000)
  if hw then
    Window.Maximize(hw)
  end
end)

-- toggle Terminal: activate it, or hide it if it's already frontmost
if App.IsFront("Terminal") then
  HID.Combo("cmd+h")     -- hide the frontmost app (no Automation prompt)
else
  App.Activate("Terminal") -- launch-or-focus
end

-- app-conditional logic without a per-app scoped script
local front = App.Front()
if front and front.name == "Google Chrome" then
  -- ...
end

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

-- paste a multi-line message into a chat app
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

-- check if an application is running
local pid = Process.Exists("notepad")
if pid then
  Log.Info("Notepad is running (PID " .. pid .. ")")
end

-- list all chrome processes
for _, p in ipairs(Process.List("chrome")) do
  Log.Info(p.name .. " [" .. p.pid .. "]")
end

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)

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)

{
  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
}

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

-- 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"}

-- settings.toml:
-- [general]
-- sensitivity = 0.8
-- enabled = true
-- profile = "default"

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

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

local downloads = Env.Downloads()
local path = Dialog.OpenFile({ location = downloads })

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

Registry.CreateKey([[HKCU\Software\MyScript]])
Registry.Write([[HKCU\Software\MyScript]], "REG_SZ", "Profile", "default")

local profile = Registry.Read([[HKCU\Software\MyScript]], "Profile")
Log.Info(profile) --> "default"

Registry.DeleteKey([[HKCU\Software\MyScript]])

die("shutting down for maintenance")

-- 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")

-- multi-line block (recommended) — one rebind: per line
--[[
  rebind: min_sdk=3.0.0
  rebind: name=My Script
  rebind: process=chrome.exe
  rebind: process=firefox.exe
--]]

-- single-line, best for one or two keys
-- rebind: min_sdk=3.0.0 name="My Script" tick_rate=8000

-- inline block
--[[ rebind: min_sdk=3.0.0 name="My Script" tick_rate=8000 --]]

--[[
  rebind: min_sdk=3.0.0
  rebind: permission=exec
  rebind: permission=net
--]]