Patterns

Every core Rebind script pattern in one place — each a minimal, correct snippet. For full signatures see the SDK reference; for the package manifest see Package format.

Style

Rebind scripts are Luau. Follow these conventions — every snippet below does.

Indent with 2 spaces. Never tabs, never 4.
Naming:
- Runtime hooks and SDK calls are PascalCase — dictated, not a choice (OnDown, HID.Press, Input.IsDown).
- Your locals and local functions are snake_case (dwell_start, local function set_virt).
- Module-level constants are UPPER_SNAKE (local OPPOSITE = {...}).
- The UI config table is conventionally named cfg.
local everything. The only globals are the runtime hooks (OnStart, OnDown, …); declare everything else local, including functions.
Double-quoted strings. Use [[ ]] long strings for regex patterns and multi-line text.
Stay flat — early return. Guard and return rather than nesting; use a and b or c for a ternary.
Types are optional but welcome. Luau is typed; annotate where it clarifies (local count: number = 0), don’t annotate the obvious.
Comments: explain why, not what, and stay sparse. Write them in lowercase. Use -- for a single line; for anything longer, use one --[[ ]] block instead of stacking several -- lines.
Keep lines to roughly 80 characters. Wrap long calls and tables across lines rather than running well past it.
Space after commas and around operators; one statement per line.

-- rebind: min_sdk=3.0.0 name=Example
local MAX_STEP = 10

--[[ a multi-line note goes in one block comment, lowercase, not several
     stacked -- lines. keep it to why, not what. ]]
local cfg = UI.Schema({
  enabled = UI.Toggle(true, { label = "Enable" }),
})

local function status_label(name: string, on: boolean): string
  if on then return name .. " (on)" end -- flat guard, not a nested block
  return name .. " (off)"
end

function OnDown(key)
  if not cfg.enabled then return true end
  return true
end

Handling input: Bind vs hooks

There are two ways to react to input, and they use opposite blocking defaults. Pick by the verb:

Bind — you’re claiming a key. Blocks by default (the original key is swallowed). Intercepts only its declared trigger. Use for remaps and per-key actions.
On* hooks — you’re watching the input stream. Pass through by default; return false to swallow. Defining OnDown/OnUp makes Rebind intercept every key. Use when you need to read or transform arbitrary input.

--[[ bind: blocks by default — never write `return false` here, it's already
     the default. the original CapsLock never reaches the PC. ]]
Bind.Remap("CapsLock", "Escape")

--[[ hook: passes by default — you must `return false` to swallow. this
     intercepts every key, so return true for the ones you don't handle. ]]
function OnDown(key)
  if key == "CapsLock" then
    HID.Press("Escape")   -- wrong context — see "Output needs a coroutine"
    return false          -- swallow the original CapsLock
  end
  return true             -- everything else passes through
end

Rule of thumb: specific keys → Bind; reading/transforming the whole stream → hooks. A hook that never blocks anything can add key_block=false to its modeline to observe input without intercepting it.

Bind patterns

-- simple 1:1 remap — no hook, no return value.
Bind.Remap("Mouse4", "4")

-- per-key action. blocks the trigger by default.
Bind("F8", function()
  Audio.Play("ding.wav", { volume = 0.5 })
end)

-- output that types or presses must run in a coroutine — wrap with Async.
Bind("F1", Async(function()
  local hw = Window.Find("Notepad")
  if hw then Window.Activate(hw) end
end))

Do not put return true/return false inside an Async(...) body passed to Bind — the return value has no effect on propagation there.

Hook patterns

-- OnDown(key) / OnUp(key, duration) — key events. return true=pass, false=swallow.
function OnDown(key)
  if key == "Mouse4" then
    HID.Press("LCtrl+Z")   -- (needs coroutine — see below)
    return false
  end
  return true
end

-- OnScroll(delta) — wheel. gate on a held key with Input.IsDown.
function OnScroll(delta)
  if Input.IsDown("LAlt") then
    HID.Press(delta > 0 and "RightBracket" or "LeftBracket")
    return false
  end
  return true
end

-- OnTick() — runs every tick (set tick_rate in the modeline). poll state here.
function OnTick()
  local pos = Input.GetMousePos()   -- { x, y }
  -- ...
end

Mouse movement (requires a Rebind device)

Any script that defines OnMove or sets mouse_block=true requires a Rebind device (Rebind Link) — the relay refuses to load it in software mode, because the OS draws the cursor upstream of anything a host process could intercept.

-- rebind: min_sdk=3.0.0 mouse_block=true
-- rebind: name=Precision Mouse

local cfg = UI.Schema({
  hold_key = UI.Keybind("Mouse3", { label = "Precision Key" }),
  slowdown = UI.Slider(25, { min = 5, max = 75, suffix = "%" }),
})

function OnMove(dx, dy)
  if Input.IsDown(cfg.hold_key) then
    HID.Move(dx * (cfg.slowdown / 100), dy * (cfg.slowdown / 100))
    return false   -- swallow the raw move, emit the scaled one
  end
  return true      -- pass unmodified moves through
end

Keep OnMove minimal — it fires on every movement.

Output needs a coroutine

HID.Press, HID.Type, and HID.Combo call Sleep() internally, so they must run inside a coroutine context (Run, Async; OnTick is not one). Inside a Bind action, wrap with Async. HID.Down/HID.Up are non-blocking and work anywhere (hooks included).

-- in a hook, defer coroutine work to Run():
function OnDown(key)
  if key == "F5" then
    Run(function() HID.Type("boilerplate text") end)
    return false
  end
  return true
end

-- chord output: `+` presses in order, releases in reverse.
Run(function() HID.Combo("LCtrl+LShift+Esc") end)   -- Task Manager

-- long / multi-line text: clipboard paste beats HID.Type.
Bind("F9", Async(function()
  Clipboard.Set("a long block of text…")
  HID.Press("LCtrl+V")
end))

Modifiers

Canonical names LCtrl/LShift/LAlt/LWin; shorthands Ctrl/Shift/Alt/ Win/Meta/Cmd/Opt also work in combos. Read live state with Input.GetModifiers() → { ctrl, shift, alt, win } or Input.IsDown("LShift").

Software-mode gotcha: a physical modifier the user is holding is merged into your synthetic output (so a swallowed key re-emitted while Shift is down still carries Shift). That’s correct for remaps, but means a macro that types text while a modifier is held will inherit it. For output that must be clean of physical modifiers, prefer hardware mode (the device isolates the stream) or gate on Input.GetModifiers() first.

Timing and async

-- Run(): a coroutine you can Sleep in and Cancel.
local task = Run(function()
  while Input.IsDown("Mouse3") do
    HID.Scroll(-1)
    Sleep(100)          -- ms
  end
end)
-- later: if task and task:IsRunning() then task:Cancel() end

Timer.After(500, function() UI.Notify("half a second later") end)
Timer.Every(1000, function() Log.Info("tick") end)

Lifecycle and cleanup

Always release what you hold. Cancel tasks, stop audio, and HID.Up any keys you pressed with HID.Down — in both OnStop (script stopped) and OnBlur (target window lost focus).

function OnStart()
  Log.Info("loaded")
end

function OnStop()
  if task and task:IsRunning() then task:Cancel() end
  Audio.StopAll()
end

function OnBlur()
  if locked then
    HID.Up("LShift")
    locked = false
  end
end

Targeting a specific app

Restrict a script to one process/window via the modeline. When targeted, always add OnBlur cleanup so held keys release when focus leaves.

-- rebind: min_sdk=3.0.0 name=Photoshop Shortcuts process=Photoshop.exe

function OnDown(key)
  if key == "Mouse4" then
    HID.Press("LCtrl+Z")
    return false
  end
  return true
end

Config and UI

-- in-app settings panel — prefer cfg.key access over UI.Get/UI.Set.
local cfg = UI.Schema({
  enabled = UI.Toggle(true, { label = "Enable" }),
  speed   = UI.Slider(50, { min = 0, max = 100, suffix = "%" }),
  hotkey  = UI.Keybind("F9", { label = "Toggle Key" }),
})

-- external TOML file (for values you edit outside the app).
local settings = Config.ReadTOML("settings.toml")

Multi-file packages

When a script outgrows one file, make it a package: a folder with a rebind.toml. The [package].entry (default main.luau) is what runs; other files are libraries you require. Only ever run/start the entry, never a library.

mytool/
  rebind.toml
  main.luau          # entry
  lib/text.luau      # library — require("lib/text")

# rebind.toml — package truth; overrides the entry's modeline.
[package]
name = "mytool"
version = "0.1.0"
min_sdk = "3.0.0"

[runtime]            # any modeline key works here
# process = ["cs2.exe"]
# permissions = ["net"]

-- lib/text.luau — a library MUST return its table.
local Text = {}

function Text.truncate(s: string, n: number): string
  if #s <= n then return s end
  return s:sub(1, n) .. "…"
end

return Text

-- main.luau — the entry. require resolves from the package root.
local text = require("lib/text")

Bind("F1", function()
  UI.Notify(text.truncate("a very long status line", 10))
end)

require paths use / or . separators and resolve <mod>.luau, <mod>.lua, then <mod>/init.luau. A one-shot helper can exit() (alias for Script.Exit()) when done.

Modeline reference

The -- rebind: comment at the top of a standalone script is its manifest. In a package, rebind.toml owns these and overrides the modeline.

Key	Purpose
`name`, `version`, `min_sdk`	identity (required on a standalone script)
`process` / `window`	activate only for a matching app (`process=cs2.exe`)
`tick_rate`	`OnTick` frequency, Hz
`mouse_block`	intercept/modify mouse movement — needs a device
`key_block`	set `false` to observe keys without intercepting
`permission`	gate `Net.*` / `System.Exec` (`permission=net`)
`instance`	`replace` \| `single` \| `multiple`
`hardware_only`	require an authenticated device to load

Getting Started

Concepts

Cookbook

Reference

Remote Control

Help

Style

Handling input: Bind vs hooks

Bind patterns

Hook patterns

Mouse movement (requires a Rebind device)

Output needs a coroutine

Modifiers

Timing and async

Lifecycle and cleanup

Targeting a specific app

Config and UI

Multi-file packages

Modeline reference

​Style

​Handling input: Bind vs hooks

​Bind patterns

​Hook patterns

​Mouse movement (requires a Rebind device)

​Output needs a coroutine

​Modifiers

​Timing and async

​Lifecycle and cleanup

​Targeting a specific app

​Config and UI

​Multi-file packages

​Modeline reference

Style

Handling input: Bind vs hooks

Bind patterns

Hook patterns

Mouse movement (requires a Rebind device)

Output needs a coroutine

Modifiers

Timing and async

Lifecycle and cleanup

Targeting a specific app

Config and UI

Multi-file packages

Modeline reference