rebind

Interactive binding-capture sessions. A session listens for the next keyboard or mouse event and produces a binding descriptor; the host can then apply() it back into a Zin.actions action or a Zin.axes axis. Backs Zin.rebind. Drives the editor's Input tab rebinding UI and is usable from any Luau code. Modifier-aware (captures modKey when Ctrl/Shift/Alt is held) and timeout-bounded (default 30 s).

Exports

• M.begin(opts: BeginOpts?) -> Session — start a capture session; subscribes to Zin.events.on and returns a session table.
• M.cancelAll() — cancel every live session.
• M.liveCount() -> number — number of capturing sessions still active.
• M._advanceTime(dt: number) — internal: per-frame timeout sweep wired by Zin.tick.

Types:

• Session = { target, name, slot, mode, status, timeoutSec, result, consume, apply, cancel, conflicts, ... }
• Owner = { target: string, name: string, slot: any }
• BeginOpts = { target?, name, slot?, mode?, timeoutSec?, filter?, applyOnCommit?, onCommit?, ... }

Usage

local Rebind = require("@builtin::modules.zinput.rebind")

local s = Rebind.begin({
    target = "action",
    name = "jump",
    timeoutSec = 10,
    applyOnCommit = true,
    onCommit = function(session)
        print("captured:", session.result())
    end,
})

-- The session subscribes itself; just wait for the next tick.
if s.status == "capturing" then
    -- ...
end

Notes

• Press Escape during a capture to cancel; a pure modifier press is ignored (the session waits for the base key).
• A session that captures with Ctrl/Shift/Alt held returns a modKey binding rather than a plain key binding.
• session.conflicts() is self-filtered — rebinding an action to a key it already owns reports no conflict.
• Hot-reload safety: the live-sessions list survives require-cache reload; the _advanceTime wiring from zinput/init.luau keeps timeouts firing across re-requires.
• applyOnCommit = true calls apply() automatically after commit; errors during apply are still visible via result() and conflicts().