bindings
Binding primitives and evaluators. A binding names which physical input satisfies a control on one device class — the value a `.inputBinding` record's `kbm` / `gamepad` / `touch` field holds. A binding is a plain descriptor table (e.g. `{ kind = "key", code = "KeyW" }`); the eval…
bindings
Binding primitives and evaluators. A binding names which physical input
satisfies a control on one device class — the value a .inputBinding
record's kbm / gamepad / touch field holds. A binding is a plain
descriptor table (e.g. { kind = "key", code = "KeyW" }); the evaluators
(evalHeld, evalPressed, evalReleased, evalAxis, evalVector)
dispatch on kind and read Zin.state / Zin.virtual to produce the live
signal. Zin.scheme runs them once per tick for every live binding, and
they are public so chords, axes and library authors can evaluate a binding
without reimplementing the dispatch.
-- boost.inputBinding/init.luau
local B = require("@builtin::modules.zinput.bindings")
return {
label = "Boost",
kind = "button",
kbm = { B.key("ShiftLeft") },
gamepad = { B.padButton("left_shoulder") },
touch = { B.touchButton({ zone = "right-lower" }) },
}
Two frames, and which binding speaks which
- Stick bindings (
vector,touchStick,padStick) report the direction the player means — forward is+y. Amovecontrol carrying a keyboard class and a stick class drives both devices the same way. - Delta bindings (
mouseDelta,touchDrag,scroll) report movement that happened — down is+y, because that is what the pointer did.
They also differ in magnitude: a stick is a position bounded at 1.0, a
delta is however far the device moved this frame. A control carrying both —
look, zoom — declares as = "delta" on its held class with the
unitsPerSecond a full deflection is worth, and scale on a delta class
that counts in its own units (a pinch in pixels beside a wheel in notches).
Zin.scheme applies both, so one sensitivity covers every device.
Exports
Keyboard and mouse constructors:
M.key(code: string) -> BindingM.mouse(button: string) -> Binding—"left"/"right"/"middle".M.modKey(spec: string) -> Binding—"Ctrl+S","Shift+Alt+P","Escape".M.axis(plus: Binding, minus: Binding, opts: StickOpts?) -> BindingM.vector(right, left, up, down: Binding) -> BindingM.wasd() -> BindingM.arrowKeys() -> BindingM.mouseDelta(axis: string?) -> Binding— this frame's mouse delta.M.scroll(axis: string?) -> Binding— scrollwheel delta.M.pointerLocked() -> Binding— boolean, true while locked.
Touch constructors (fed by Zin.virtual, which the on-screen controls write):
M.touchStick(opts: { zone, axis? }) -> Binding— vector.M.touchButton(opts: { zone?, label?, icon?, priority?, size?, group? }) -> Binding— boolean.M.touchDrag(opts: { zone, axis? }) -> Binding— per-frame delta vector.M.touchPinch(opts: StickOpts?) -> Binding— scalar pinch delta.
Gamepad constructors (addressed by canonical position, or by the device's own
0-based element index for a wheel, pedals, a flight stick or any element past
the canonical layout; slot names one pad by number or a device by a piece of
its name, omitting it means any connected pad; rest / full calibrate an
axis so rest reads 0 and full reads 1):
M.padButton(button: string | number, slot: (number | string)?) -> BindingM.padAxis(axis: string | number, opts: PadAxisOpts?) -> BindingM.padStick(stick: string, opts: StickOpts?) -> BindingM.padTrigger(trigger: string, slot: number?) -> Binding
Predicates:
M.isBoolean(b) -> booleanM.isAxis(b) -> booleanM.isVector(b) -> boolean
Evaluators:
M.evalHeld(b) -> booleanM.evalPressed(b) -> booleanM.evalReleased(b) -> booleanM.evalAxis(b) -> numberM.evalVector(b) -> Vec2
Pretty-printers:
M.format(b: any) -> string— single binding ("Space", "Ctrl+S", "WASD").M.formatAll(bindings: any?, sep: string?) -> string— joined summary; non-table arg returns"<no bindings>".
Types:
Binding = { [string]: any }— descriptor table withkindplus type-specific fields.Vec2 = { x: number, y: number }StickOpts = { slot: number?, as: string?, unitsPerSecond: number?, scale: number? }
Notes
- Bindings are pure data tables — they serialize cleanly, compare with
Json.encode, and have no metatables. modKeynormalises modifier order informat()so a key written asShift+Ctrl+KeySdisplays the same asCtrl+Shift+KeyS. The internalmods = { ctrl, shift, alt }flags are the canonical representation.- Mouse-delta, scroll, drag and pinch values are raw physical deltas, not
clamped to
[-1, 1].as = "delta"+unitsPerSecondon the stick class beside them is what puts every class in one unit. as = "delta"needsunitsPerSecondand has no default: the number that makes a pad feel right is the point of declaring the conversion, and a default would be right for one control and quietly wrong for the next.- Reading a member this module does not have raises immediately, naming the
nearest members and the full list — a wrong guess at a constructor
surfaces at the call rather than as
attempt to call a nil valuelater. format()always returns a string, never throws — returns"<invalid>"for malformed input.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2ZinputBindings Module Binding primitives. A binding names which physical input satisfies a control on one device class — the value a `.inputBinding` record's `kbm` / `gamepad` / `touch` field holds. Backs `Zin.bindings`. Bindings are *data*, not objects. Each constructor returns a plain table with a `kind` field and type-specific fields. `Zin.scheme` interprets them by dispatching on `kind` and reading the underlying state via `Zin.state`. Plain tables let bindings be inspected, serialized, compared, and composed without metatable surprises. Keyboard and mouse: { kind = "key", code = "KeyW" } { kind = "mouse", button = "left"|"right"|"middle" } { kind = "modKey", code = "KeyS", mods = { ctrl, shift, alt } } { kind = "axis", plus = <binding>, minus = <binding> } { kind = "vector", right, left, up, down = <binding>, ... } { kind = "mouseDelta", axis = nil|"x"|"y" } -- vector (nil) / scalar { kind = "scroll", axis = nil|"x"|"y" } -- vector (nil) / scalar { kind = "pointerLocked" } -- boolean (held = locked) Touch — fed by `Zin.virtual` (on-screen controls write it): { kind = "touchStick", zone = "left" } -- vector { kind = "touchButton", id?, zone?, label?, icon?, priority?, size?, group?, place?, fill?, stroke?, strokeWidth?, textColor?, fontFamily?, fontScale?, iconFont?, iconScale? } -- boolean { kind = "touchDrag", zone = "right" } -- vector { kind = "touchPinch" } -- scalar Gamepad — addressed by canonical position, so one binding evaluates against any pad on any platform, or by the device's own element index, so a wheel's pedals, a flight stick's throttle and a button past the canonical seventeen bind too. `slot` names one pad by number or a device by a piece of its name; omitting it means any connected pad: { kind = "padButton", button = "south" | <index>, slot? } -- boolean { kind = "padAxis", axis = "left_stick_x" | <index>, slot?, rest?, full?, as?, unitsPerSecond? } -- scalar { kind = "padStick", stick = "left"|"right", slot?, as?, unitsPerSecond? } -- vector Two frames, and which binding speaks which: * STICK bindings (`vector`, `touchStick`, `padStick`) report a direction the player means — forward is +y. A `move` axis carrying a keyboard class and a stick class drives both devices the same way. * DELTA bindings (`mouseDelta`, `touchDrag`, `scroll`) report movement that happened — down is +y, because that is what the pointer did. The two frames also differ in MAGNITUDE: a stick is a position bounded at 1.0, a delta is however far the device moved this frame. A control carrying both — look, zoom — declares `as = "delta"` on its held class with the `unitsPerSecond` a full deflection is worth, and `scale` on a delta class that counts in its own units (a pinch in pixels beside a wheel in notches). The scheme applies both, so one sensitivity covers every device. `as = "delta"` moves a stick into the delta frame as well as the delta units: it says this stick drives a control measured in movement, and movement is what the mouse and the dragging finger beside it report. A `look` carrying a mouse and a right stick then turns the same way from both. Return shapes: key, mouse, modKey → boolean (held/pressed/released) axis → number in [-1, 1] vector → { x, y } numbers in [-1, 1] Evaluators (eval*): Each binding kind has a public evaluator that resolves the descriptor against the current frame's snapshot. They are the dispatch `Zin.scheme` runs each tick, and are public so chords, axes, and library authors can evaluate a binding without reimplementing it.
normalizeStickOpts(who: string, opts: StickOpts?) → StickOpts
| arg | type | description |
|---|---|---|
| who | string | |
| opts | StickOpts? |
key(code: string) → Binding
Bind to a single key. Code is a web-style identifier (e.g. "KeyW", "Space", "ShiftLeft", "ArrowUp") — same vocabulary as `Zin.state.keyDown(code)`.
| arg | type | description |
|---|---|---|
| code | string | The key code identifier. |
examples
local b = Zin.bindings.key("Space")mouse(button: string) → Binding
Bind to a single mouse button by name ("left", "right", or "middle").
| arg | type | description |
|---|---|---|
| button | string | The mouse-button name. |
examples
local b = Zin.bindings.mouse("right")modKey(spec: string) → Binding
Parse a modifier-decorated key spec like "Ctrl+S", "Shift+Alt+P", or just "Escape". Recognized modifier tokens (case-insensitive): "Ctrl", "Control", "Shift", "Alt". Anything else is treated as the base key code. The last segment is the base key.
| arg | type | description |
|---|---|---|
| spec | string | The modifier-decorated key spec. |
examples
local b = Zin.bindings.modKey("Ctrl+S")axis(plus: Binding, minus: Binding, opts: StickOpts?) → Binding
Bind to a 1-D axis composed of two opposing bindings. Each arm contributes how far it is pushed, 0..1, so a key gives 1 while held and a trigger gives its travel — which is what separates easing a car forward from flooring it. Value = plus travel - minus travel.
| arg | type | description |
|---|---|---|
| plus | Binding | The binding whose travel contributes positively. |
| minus | Binding | The binding whose travel contributes negatively. |
| opts | StickOpts? |
examples
local b = Zin.bindings.axis(B.key("KeyD"), B.key("KeyA"))vector(right: Binding, left: Binding, up: Binding, down: Binding) → Binding
Bind to a 2-D vector. Each arm is a binding that contributes to one axis when held. The returned vector is `{ x = right - left, y = up - down }`.
| arg | type | description |
|---|---|---|
| right | Binding | The binding that drives `+x`. |
| left | Binding | The binding that drives `-x`. |
| up | Binding | The binding that drives `+y`. |
| down | Binding | The binding that drives `-y`. |
examples
local b = Zin.bindings.vector(B.key("KeyD"), B.key("KeyA"), B.key("KeyW"), B.key("KeyS"))wasd( ) → Binding
Convenience: WASD as a vector binding. Identical to `vector(key("KeyD"), key("KeyA"), key("KeyW"), key("KeyS"))`.
examples
local move = Zin.bindings.wasd()
arrowKeys( ) → Binding
Convenience: arrow keys as a vector binding. Identical to `vector(key("ArrowRight"), key("ArrowLeft"), key("ArrowUp"), key("ArrowDown"))`.
examples
local move = Zin.bindings.arrowKeys()
mouseDelta(axis: string?) → Binding
Bind to the mouse delta this frame. - `axis = nil` → vector binding returning `{ x = dx, y = dy }` - `axis = "x"` → scalar binding returning `dx` - `axis = "y"` → scalar binding returning `dy` Values are not normalised to `[-1, 1]` — mouse delta is a physical pixel count. A control carrying this beside a stick declares `as = "delta"` with `unitsPerSecond` on the stick class, so both classes reach the consumer measured in these pixels.
| arg | type | description |
|---|---|---|
| axis | string? | Optional. `"x"` / `"y"` for a scalar binding; omit for a vector. |
examples
local look = Zin.bindings.mouseDelta()
local lookX = Zin.bindings.mouseDelta("x")scroll(axis: string?) → Binding
Bind to the scrollwheel delta this frame. - `axis = nil` → vector binding returning `{ x = 0, y = scroll_delta }` - `axis = "y"` → scalar binding returning the wheel delta - `axis = "x"` → scalar binding returning `0` (no horizontal-scroll surface today; reserved for future hardware support)
| arg | type | description |
|---|---|---|
| axis | string? | Optional. `"x"` / `"y"` for a scalar binding; omit for a vector. |
examples
local zoom = Zin.bindings.scroll("y")pointerLocked( ) → Binding
Bind to pointer-lock state. `evalHeld` is true while the pointer is locked. `evalPressed` / `evalReleased` always return false (use `Zin.events.on` for edge events).
examples
local locked = Zin.bindings.pointerLocked()
isLabel(label: any) → boolean
Whether `label` is something a control can be labelled with: a non-empty string or an `i18n.text` value.
| arg | type | description |
|---|---|---|
| label | any | Any value. |
examples
Zin.bindings.isLabel(i18n.text("controls.control.jump")) -- truelabelText(label: any) → string
The words `label` reads as now: a string as written, an `i18n.text` value in the player's language at this moment, `""` for anything else. Every listing that hands a label to a caller (a scheme row, the touch layout, `inputMap:controls()`) gives it this way.
| arg | type | description |
|---|---|---|
| label | any | A string or an `i18n.text` value. |
examples
print(Zin.bindings.labelText(record.label))
labelSource(label: any) → string
The Luau source that evaluates to `label` where it is written into a `.inputBinding`: `"Horn"` for a string, `i18n.text("controls.control.jump")` for an `i18n.text` value, so a control written by a tool reads in the player's language the way the one it was written from did.
| arg | type | description |
|---|---|---|
| label | any | A string or an `i18n.text` value. |
examples
Zin.bindings.labelSource(i18n.text("controls.control.jump")) -- 'i18n.text("controls.control.jump")'controlLabel(name: string) → any
The catalog label of a control named `name`, when a catalog the caller reads holds `controls.control.<name>`: an `i18n.text` value, else nil. The built-in library's catalog names the engine's own controls (`jump`, `sprint`, `crouch`, ...), and a world's `locales/<tag>/controls.json` can name its own, so a control that came without a label (a touch button synthesized from a keyboard binding, a map baked from a registry) still reads in the player's language.
| arg | type | description |
|---|---|---|
| name | string | The control's name. |
examples
local label = Zin.bindings.controlLabel("jump") or "Jump"touchStick(opts: { zone: string, axis: string? }) → Binding
Virtual-stick binding: a vector fed by the on-screen stick in `opts.zone` (components -1..1). Evaluates {x=0,y=0} while no control writes the zone.
| arg | type | description |
|---|---|---|
| opts | { zone: string, axis: string? } | { zone: string } — the stick's zone id (e.g. "left"). |
examples
B.touchStick({ zone = "left" })appearanceKeys( ) → string
Internal: the appearance vocabulary as an error can print it.
touchButton(opts: TouchButtonOpts) → Binding
Virtual-button binding: a boolean fed by the on-screen button whose identity in `Zin.virtual` is `opts.id`. A button of a `button` control in an activated `.inputMap` takes the control's name as its id when it states none; otherwise the id falls back to a string `opts.label`, then to the catalog key of an `i18n.text` label, then to `opts.zone` (`Zin.bindings.touchButtonId`). Code that presses, tests or gates on a button (`Zin.virtual.button`, `Zin.arming.gate { virtualButtons }`, `Zin.test.tapTouchButton`) names it by that id. `priority` (lower renders first/more prominent on the touch overlay; defaults to 50 when omitted), `size` (`"small"|"medium"|"large"`, defaults to `"medium"` - this button's own circle radius, whatever else the overlay is drawing), `group` (buttons sharing a group render adjacently) and `place` shape the overlay's layout - see `Zin.touchControls`. `place` is `"column"` (the default: the action column growing inward from the bottom-right corner, where a game's actions go) or `"corner"` (the top-right corner of the safe area, rows along the top edge over the look area, for a control that works the app around the game rather than the game, such as the app menu's pause action). A corner button keeps its place whatever the column holds, so the controls a game draws in the column's place stay clear of it. `label` is what the circle reads: text, or an `i18n.text` value that reads in the player's language (`Zin.bindings.labelText`). A control in an `.inputMap` shows its own `label` on its buttons. `icon` is a glyph drawn in its place - `modules.icons` names the phosphor set the default `iconFont` selects, and any string the face holds a glyph for draws. `fill`, `stroke`, `strokeWidth`, `textColor`, `fontFamily`, `fontScale`, `iconFont` and `iconScale` state THIS button's appearance over whatever `Zin.touchControls.setAppearance` set for the overlay. A colour takes the CSS forms the canvas accepts; a family takes the list `style.fontFamily` takes (`ui.listFonts()` names them); a scale is the share of the button's radius the glyph is set at.
| arg | type | description |
|---|---|---|
| opts | TouchButtonOpts | { id: string?, zone: string?, label: (string | i18n.text)?, icon: string?, priority: number?, size: string?, group: string?, place: string?, fill: string?, stroke: string?, strokeWidth: number?, textColor: string?, fontFamily: string?, fontScale: number?, iconFont: string?, iconScale: number? } - at least one of id, zone or label. |
examples
B.touchButton({ zone = "right-lower", label = "Jump", priority = 10 })B.touchButton({ id = "up", zone = "right-lower", label = i18n.text("controls.button.up") })B.touchButton({ zone = "right-lower", label = "Fire", icon = Icon.Bomb, fill = "#7d1d1d", stroke = "#e8b33a" })B.touchButton({ id = "pause", label = "Pause", place = "corner", size = "small" })touchDrag(opts: { zone: string, axis: string? }) → Binding
Touch-drag binding: a per-frame delta vector fed by drags in `opts.zone` (mouseDelta semantics — px this frame).
| arg | type | description |
|---|---|---|
| opts | { zone: string, axis: string? } | { zone: string } — the drag zone id (e.g. "right"). |
examples
B.touchDrag({ zone = "right" })touchPinch(opts: StickOpts?) → Binding
Pinch binding: a scalar axis fed by the two-finger pinch delta (px this tick; positive = spreading).
| arg | type | description |
|---|---|---|
| opts | StickOpts? |
examples
B.touchPinch()
sortedKeys(t: { [string]: boolean }) → string
Internal: the sorted vocabulary, for an error that names what IS accepted instead of only what was not.
| arg | type | description |
|---|---|---|
| t | { [string]: boolean } |
checkPadSelector(who: string, slot: any) → void
Internal: check a pad selector: a slot number, or a piece of a device's name or id.
| arg | type | description |
|---|---|---|
| who | string | |
| slot | any |
isElementIndex(n: any) → boolean
Internal: whether `n` is a device element index (a whole number from 0).
| arg | type | description |
|---|---|---|
| n | any |
padButton(button: string | number, slot: (number | string) →
Gamepad button binding, addressed by canonical position rather than by any vendor's letter — `south` is the lower face button on every pad, whatever it is printed with, or by the device's own button index (0-based, `Zin.gamepad.device(slot).buttons`), which binds every button a wheel, a shifter, a flight stick or a button board reports. With no `slot`, ANY connected pad drives it, which is what a single-player scheme wants; name a slot for local multiplayer, or a piece of a device's name to bind that device whatever slot it took. right_shoulder, left_trigger, right_trigger, left_stick, right_stick, select, start, guide, dpad_up, dpad_down, dpad_left, dpad_right; or a 0-based device button index.
| arg | type | description |
|---|---|---|
| button | string | number | Canonical name: south, east, west, north, left_shoulder, |
| slot | (number | string | Pad slot, a device name to match, or nil for any pad. |
examples
B.padButton("south")B.padButton(12, "shifter")
padAxis(axis: string | number, opts: PadAxisOpts?) → Binding
Gamepad axis binding, one axis as a scalar: a canonical axis, or the device's own axis by its 0-based index (`Zin.gamepad.device(slot) .axes`), a wheel, a pedal, a throttle, a rudder. Canonical stick axes run -1..1 in the frame the binding declares — forward positive by default, matching the touch stick and `B.wasd()`, and screen-down positive under `as = "delta"`, matching the mouse and the dragging finger it is measured against. Trigger axes run 0..1. A device axis reads -1..1 across its native range. `rest` and `full` calibrate the reading: the binding reports `(reading - rest) / (full - rest)`, clamped to -1..1, so `rest` reads 0 and `full` reads 1. A pedal that reads -1 released and 1 floored binds with `{ rest = -1 }` and reports 0..1; one wired the other way with `{ rest = 1, full = -1 }`; a wheel whose centre sits off zero with `{ rest = 0.02 }`. With no connected device reporting the axis the binding reads 0, so a pedal map stays quiet until the pedals are plugged in. One axis carrying a throttle and a brake splits with `B.axis(B.padAxis(i), B.padAxis(i, { full = -1 }))`, each arm counting its own side. right_stick_y, left_trigger, right_trigger; or a 0-based device axis index. `full` (calibration, each -1..1; `rest` 0 and `full` 1 when omitted), and `as` / `unitsPerSecond` / `scale` as for any stick binding.
| arg | type | description |
|---|---|---|
| axis | string | number | Canonical name: left_stick_x, left_stick_y, right_stick_x, |
| opts | PadAxisOpts? | `slot` (a pad slot, or a piece of a device's name), `rest` / |
examples
B.padAxis("right_stick_x")B.padAxis(2, { slot = "pedals", rest = -1 })padStick(stick: string, opts: StickOpts?, slot: ?) → Binding
Gamepad stick binding: the 2-D vector of one thumbstick. The vector shape a movement or look axis wants, without naming its two components separately.
| arg | type | description |
|---|---|---|
| stick | string | "left" or "right". |
| opts | StickOpts? | |
| slot | ? | Pad slot, or nil for any pad. |
examples
B.padStick("left")padTrigger(trigger: string, slot: number?) → Binding
Gamepad trigger binding: one trigger's analog travel, 0..1. The same trigger also latches a digital `padButton` at half throw, so a scheme binds whichever of the two it means.
| arg | type | description |
|---|---|---|
| trigger | string | "left" or "right". |
| slot | number? | Pad slot, or nil for any pad. |
examples
B.padTrigger("right")touchButtonId(b: any) → string
A touch button's identity in `Zin.virtual`: its `id`, else a string `label`, else the catalog key of an `i18n.text` label, else its `zone`. A button of a `button` control takes the control's name as its `id` when its map activates, so two controls whose buttons share a zone stay distinct. A label read from a catalog names the button by its key, which is the same in every language, and two buttons in one zone whose labels read from different messages stay two buttons.
| arg | type | description |
|---|---|---|
| b | any | A `touchButton` binding. |
examples
Zin.virtual.button(Zin.bindings.touchButtonId(binding))
isBoolean(binding: ?) → boolean
True for binding descriptors that resolve to a boolean (key, mouse, modKey, pointerLocked, touchButton).
| arg | type | description |
|---|---|---|
| binding | ? | The binding to test. |
examples
assert(Zin.bindings.isBoolean(Zin.bindings.key("Space")))isAxis(binding: ?) → boolean
True for the binding descriptors `evalAxis` resolves to a scalar: `axis`, `touchPinch` and `padAxis`, plus a `mouseDelta`, `scroll`, `touchDrag` or `touchStick` naming one axis of its two-axis surface.
| arg | type | description |
|---|---|---|
| binding | ? | The binding to test. |
examples
assert(Zin.bindings.isAxis(Zin.bindings.mouseDelta("x")))surfacesOf(binding: ?) →
Which device surface a binding reads from: `pointer` (mouse, wheel or finger), `keyboard` (keys and composed text), or `gamepad`. A composite binding (`axis`, `vector`) answers with the surfaces of every binding it combines.
| arg | type | description |
|---|---|---|
| binding | ? | The binding to classify. |
examples
local s = Zin.bindings.surfacesOf(Zin.bindings.wasd())
visit(b: ?) → void
| arg | type | description |
|---|---|---|
| b | ? |
readsMouse(b: any) → boolean
| arg | type | description |
|---|---|---|
| b | any |
_pointerTakenBy( ) → string
Internal: who a person's pointer belongs to this frame, when it is not the scene's — `"ui"` while the UI is using it (a widget that answers for the pointer stands under it or holds the press, or a shown screen holds the pointer), `"undecided"` while a finger's press waits for the UI to say whose it is — and `nil` while the scene reads it.
examples
local owner = Zin.bindings._pointerTakenBy()
_keyboardTakenBy( ) → string
Internal: whose a person's keyboard is this frame, when the UI takes any of it — `"ui"` while a widget taking every key holds focus (a text field with the caret, a terminal, a widget with its own `onKey`), `"shared"` while a focused widget takes some keys (Space and Enter for a button, the stepping keys as well for a slider) and the scene reads the rest — and `nil` while the scene reads every key.
examples
local owner = Zin.bindings._keyboardTakenBy()
collectKeys(b: any, out: { string }) → void
| arg | type | description |
|---|---|---|
| b | any | |
| out | { string } |
_keysTakenByUi(bindings: { any }) →
Internal: the keys these bindings read that the UI takes from a person's keyboard this frame: every key they read while a widget taking every key holds focus, the ones the focused widget takes while the keyboard is shared, none while the scene reads every key. A key the UI takes reaches the bindings with nothing until the widget lets go.
| arg | type | description |
|---|---|---|
| bindings | { any } | The binding descriptors to test. |
examples
local taken = Zin.bindings._keysTakenByUi({ Zin.bindings.key("Space") })collectPad(b: any, out: { string }) → void
Internal: the canonical pad controls a binding reads, by the names a pad's `ui_buttons` lists them under.
| arg | type | description |
|---|---|---|
| b | any | |
| out | { string } |
_padTakenByUi(bindings: { any }) →
Internal: the pad controls these bindings read that a game menu on screen takes this frame, on any connected pad: the d-pad, `south` and `east` while the menu moves and presses with them, and the left stick while a menu is up. A control the menu takes reaches the bindings released and centred until the menu lets go.
| arg | type | description |
|---|---|---|
| bindings | { any } | The binding descriptors to test. |
examples
local taken = Zin.bindings._padTakenByUi({ Zin.bindings.padButton("south") })_readMouse(bindings: { any }) → boolean
Internal: whether any of these bindings reads a person's mouse — a button, its motion or its wheel — directly or through an `axis` / `vector` arm.
| arg | type | description |
|---|---|---|
| bindings | { any } | The binding descriptors to test. |
examples
if Zin.bindings._readMouse({ Zin.bindings.mouseDelta() }) then ... endisVector(binding: ?) → boolean
True for the binding descriptors that resolve to a 2-D vector: `vector` and `padStick`, plus a `mouseDelta`, `scroll`, `touchDrag` or `touchStick` reporting its whole surface. Naming one axis of those four makes the binding a scalar, which `isAxis` answers for, so no binding answers both.
| arg | type | description |
|---|---|---|
| binding | ? | The binding to test. |
examples
assert(Zin.bindings.isVector(Zin.bindings.wasd()))
primaryContactClaimed( ) → boolean
A finger the on-screen controls have claimed reads as a held left mouse button until the UI has decided its press, because the engine projects the contact driving the pointer onto the mouse where the contact arrives. A `mouse` binding means the player pressed a mouse button. A thumb on the stick is not that, so a claimed contact driving the pointer suppresses every mouse binding for as long as it is claimed; otherwise one touch on the stick moves AND fires whatever the world bound to left-click. Required lazily: touchControls requires this module.
mouseDeltaNow( ) → void
The same projection moves the mouse, not just its buttons: a finger dragging the look zone also reads as mouse movement. Both classes then report the drag, and the control is credited to whichever the reader checks first — so a phone's look drag shows up as keyboard-and-mouse. A claimed contact is the overlay's, so the mouse it projects is not a mouse the player moved. The emulation floor synthesizes a mouse delta ON PURPOSE, for controls the scheme does not cover, and writes it to the same place. That one is a delta a reader should see; the platform's projection is not. The floor reports what it emitted, so the two are told apart rather than dropped together.
stickFrameY(binding: any, raw: number) → number
A stick's y in the frame its binding declares. The platform reports a stick screen-down positive. A stick left in its own frame reports the direction the player means, so forward is positive and one `move` axis drives a keyboard and a stick the same way. A stick declared `as = "delta"` drives a control measured in movement instead, beside a mouse and a dragging finger, so it keeps the screen-down sign those report.
| arg | type | description |
|---|---|---|
| binding | any | |
| raw | number |
armTravel(arm: any, surface: string?) → number
Resolve a binding descriptor against the current frame's input state. Available to library authors who want to evaluate user-supplied bindings without reaching into the dispatch logic themselves. How far one arm of an `axis` binding is pushed, 0..1. A key is pushed or it is not. A trigger is pushed by an amount, and that amount is the difference between easing a car forward and flooring it, so an arm that reports a magnitude contributes the magnitude. An arm that is itself signed contributes only the half that pushes this arm's way — the other half is what the opposing arm is for.
| arg | type | description |
|---|---|---|
| arm | any | |
| surface | string? |
modsMatch(mods: ?, surface: string?) → boolean
Internal: are the current modifier flags consistent with the binding's spec?
| arg | type | description |
|---|---|---|
| mods | ? | |
| surface | string? |
evalHeld(b: ?, surface: string?) → boolean
Is this binding currently delivering a held signal? key/mouse/modKey/pointerLocked → boolean held. axis/vector/mouseDelta/scroll → magnitude non-zero. `"editor"`. An input map declared for the editor surface evaluates with `"editor"`.
| arg | type | description |
|---|---|---|
| b | ? | The binding to evaluate. |
| surface | string? | Whose keys a key binding reads: `"scene"` (the default) or |
examples
if Zin.bindings.evalHeld(b) then ... end
evalPressed(b: ?, surface: string?) → boolean
Did this binding's press edge fire this frame? Boolean bindings only. Axis/vector return false (use evalAxis/evalVector with a held-time threshold for edge tracking). `"editor"`. An input map declared for the editor surface evaluates with `"editor"`.
| arg | type | description |
|---|---|---|
| b | ? | The binding to evaluate. |
| surface | string? | Whose keys a key binding reads: `"scene"` (the default) or |
examples
if Zin.bindings.evalPressed(b) then print("jump") endevalReleased(b: ?, surface: string?) → boolean
Did this binding's release edge fire this frame? `"editor"`. An input map declared for the editor surface evaluates with `"editor"`.
| arg | type | description |
|---|---|---|
| b | ? | The binding to evaluate. |
| surface | string? | Whose keys a key binding reads: `"scene"` (the default) or |
examples
if Zin.bindings.evalReleased(b) then ... end
evalAxis(b: ?, surface: string?) → number
Resolve a 1-D axis binding to a scalar. For `axis` bindings the result is in `[-1, 1]`. For `mouseDelta` / `scroll` bindings the result is a raw physical delta (pixels, wheel clicks) and may exceed that range — shape it with `Zin.axes`. `"editor"`. An input map declared for the editor surface evaluates with `"editor"`.
| arg | type | description |
|---|---|---|
| b | ? | The binding to evaluate. |
| surface | string? | Whose keys a key binding reads: `"scene"` (the default) or |
examples
local x = Zin.bindings.evalAxis(Zin.bindings.mouseDelta("x"))formatKeyCode(code: any) → string
A key code as a legend writes it: "KeyW" as "W", "Digit7" as "7", a key with a name (Space, Escape, ArrowUp, ShiftLeft, ...) in the player's language, and anything else (F1, Numpad4, ...) as the code.
| arg | type | description |
|---|---|---|
| code | any |
marker(key: string) → string
A marker legend: the catalog's words between angle brackets.
| arg | type | description |
|---|---|---|
| key | string |
isVectorShape(b: any, right: string, left: string, up: string, down: string) → boolean
Internal: does a vector binding match a fixed WASD/Arrow shape?
| arg | type | description |
|---|---|---|
| b | any | |
| right | string | |
| left | string | |
| up | string | |
| down | string |
format(b: any) → string
Render a single binding descriptor as a user-readable string, in the player's language: the words come from the `controls` catalog, and in English they read `Space`, `Left Ctrl`, `Ctrl+S`, `Right mouse button`, `Mouse movement`, `Mouse wheel`, `E / Q`, `WASD`, `Pad-A`. A pad binding is named for the pad the person holds (`Zin.gamepad.label`): on a headset's hand controllers it reads as the controls printed on them, `X`, `Right grip`, `Left thumbstick`, `Right thumbstick up/down`. The rebinding UI shows it verbatim. Returns `"<invalid>"` for malformed input (does not throw).
| arg | type | description |
|---|---|---|
| b | any | The binding to format. |
examples
local s = Zin.bindings.format(B.modKey("Ctrl+S")) -- "Ctrl+S"formatAll(bindings: any?, sep: string?) → string
Render an array of bindings joined by `sep` (default `", "`). Returns `"<no bindings>"` if the argument isn't a table, `"<empty>"` for an empty array, each in the player's language. What a summary row listing one control's bindings for a device class shows.
| arg | type | description |
|---|---|---|
| bindings | any? | The bindings to format. |
| sep | string? | Optional join separator (default `", "`). |
examples
Zin.bindings.formatAll({ B.key("Space"), B.modKey("Ctrl+S") })evalVector(b: ?, surface: string?) → Vec2
Resolve a 2-D vector binding to `{ x, y }`. For `vector` bindings the result is in `[-1, 1]`. For `mouseDelta` / `scroll` bindings (with no `axis` set) the result is the raw frame delta — `mouseDelta` = `{ x = dx, y = dy }`, `scroll` = `{ x = 0, y = wheel_delta }` (x reserved for future h-scroll). `"editor"`. An input map declared for the editor surface evaluates with `"editor"`.
| arg | type | description |
|---|---|---|
| b | ? | The binding to evaluate. |
| surface | string? | Whose keys a key binding reads: `"scene"` (the default) or |
examples
local mv = Zin.bindings.evalVector(Zin.bindings.wasd())
headsetLook(binding: any, v: Vec2, dt: number, signal: any?) →
What a stick binding reads in a headset, when the look action is the control it drives: the frame units of the binding's control and nothing on the vertical axis. Applies to a right-stick `padStick` declared `as = "delta"` while an XR session holds input focus. Under snap turning the horizontal axis is the steps flicked this frame, each worth the signal's `snapDegrees`; under smooth turning it is the stick's deflection integrated as the binding states.
| arg | type | description |
|---|---|---|
| binding | any | The binding being read. |
| v | Vec2 | The binding's reading in its own frame, from `evalVector`. |
| dt | number | Seconds the frame covers. |
| signal | any? | What the headset reports: `{ turnMode, turnSteps, snapDegrees }`, or nil outside a session. |
examples
local x, y = Zin.bindings.headsetLook(b, v, dt, { turnMode = "snap", turnSteps = 1, snapDegrees = 45 })availableMembers( ) → void
Reading a member this surface does not have raises here, naming what it does have. Without it a wrong guess at a binding constructor -- `mouseButton` for `mouse` -- surfaces later as `attempt to call a nil value` at whatever line consumed the binding, with nothing pointing at the real name.
nearestMembers(wanted: string) → void
A guess is usually a longer or shorter spelling of the real thing, so offer any member whose name contains the guess or is contained by it.
| arg | type | description |
|---|---|---|
| wanted | string |
__index(_: ?, key: any) → void
| arg | type | description |
|---|---|---|
| _ | ? | |
| key | any |
Binding = { [string]: any }Vec2 = { x: number, y: number }StickOpts = {PadAxisOpts = {TouchButtonOpts = {Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.