input

The input namespace — 21 functions.

input/emulateKeyDown

input.emulateKeyDown(code)

The input-emulation floor's write surface: mark code held by the floor. Merged into the default polling views (isDown, snapshot().keys) so Zin.state.keyDown cannot tell an emulated hold from a real one; tracked separately in snapshot().keys_emulated, and readable real-only via Zin.state.keyDownReal. Drained before the next frame's controller scripts run, like simulate* — but pushes no frame event and is never forwarded to the UI layer: emulated input exists for polling surfaces, and event-driven consumers already receive the real touch events the floor was driven from. Internal — backs the map-driven emulation floor.

input/emulateKeyUp

input.emulateKeyUp(code)

Release code from the input-emulation floor. Only lifts the held state if a real key-press hasn't since claimed the code (real press owns the key). No frame event, no UI forwarding. Internal — backs the map-driven emulation floor.

input/emulateMouseButton

input.emulateMouseButton(button, held)

Set emulated mouse button button (0=left, 1=right, 2=middle) held/released from the input-emulation floor. Mirrors emulateKeyDown/emulateKeyUp: a real mouse press owns the button thereafter. No frame event, no UI forwarding. Internal — backs the map-driven emulation floor.

input/emulateMouseDelta

input.emulateMouseDelta(dx, dy)

Accumulate an emulated mouse-delta contribution from the input-emulation floor into this frame's mouse_delta. No frame event, no UI forwarding. Internal — backs the map-driven emulation floor.

input/events

input.events() -> {table}

Get the current frame's input events as an array of { kind = '...', ... } records in dispatch order. Internal — Zin wraps this as Zin.events.frame(). Variants produced today: key.down { code, repeat }, key.up { code }, mouse.down { button, x, y }, mouse.up { button, x, y }, mouse.move { x, y, dx, dy }, mouse.wheel { dx, dy }, text { text }, touch.down { id, x, y, pressure }, touch.move { id, x, y, dx, dy, pressure }, touch.up { id, x, y }, touch.cancel { id }. Returns an empty array if no events have been published yet. Cleared at end of frame (PostRender). Reading does not consume.

input/frameId

input.frameId() -> integer

Get the engine's monotonic frame counter. Bumped once per frame at PostRender. Internal — used by Zin.tick to dedup cross-coroutine double-ticks within the same engine frame. Stable across multiple reads inside the same frame, strictly greater after a task.wait(0) yield. Returns 0 only before the very first frame has elapsed.

input/isAnyDown

input.isAnyDown({name, ...}) -> boolean, string?

Are any of the given keys currently held? Returns held, which: when any key in the array is held, held=true and which is the first matched code (in iteration order); otherwise false, nil. Internal — used by Zin.

input/isDown

input.isDown(name) -> boolean

Is the given key currently held this frame? Internal — Zin wraps this as Zin.state.keyDown(name). Direct lookup on the published snapshot's keys array.

input/releasePointerLock

input.releasePointerLock()

Release pointer lock (cursor ungrab + show). Internal — backs Zin.pointer.unlock().

input/requestPointerLock

input.requestPointerLock()

Request pointer lock (cursor grab + hide). Internal — backs Zin.pointer.lock().

input/simulateKeyDown

input.simulateKeyDown(key)

Queue a simulated key-down event. Drained before the next frame's controller scripts run. Internal — backs Zin.test.pressKey(); production code should not call this directly.

input/simulateKeyUp

input.simulateKeyUp(key)

Queue a simulated key-up event. Internal — backs Zin.test.releaseKey().

input/simulateMouseDown

input.simulateMouseDown(button?)

Queue a simulated mouse-button-down event. 0=left (default), 1=right, 2=middle. Internal — backs Zin.test.pressMouse().

input/simulateMouseMove

input.simulateMouseMove(x, y)

Set mouse position to screen coordinates. Internal — backs Zin.test.moveMouse().

input/simulateMouseUp

input.simulateMouseUp(button?)

Queue a simulated mouse-button-up event. Internal — backs Zin.test.releaseMouse().

input/simulateScroll

input.simulateScroll(dy)

Queue a simulated mouse-wheel event. Internal — backs Zin.test.scroll().

input/simulateTouchCancel

input.simulateTouchCancel(id)

Queue a simulated platform touch-cancel for an active finger id.

input/simulateTouchDown

input.simulateTouchDown(id, x, y, pressure?)

Queue a simulated touch-contact-begin event. id is any stable number identifying the finger until its matching simulateTouchUp/Cancel. Drained before the next frame's controller scripts run. The primary touch (slot 0) also drives the mouse path. Internal — backs Zin test touch helpers.

input/simulateTouchMove

input.simulateTouchMove(id, x, y, pressure?)

Queue a simulated touch-move event for an active finger id.

input/simulateTouchUp

input.simulateTouchUp(id)

Queue a simulated touch-lift event for an active finger id.

input/snapshot

input.snapshot() -> table

Get the current frame's input state as a table. Internal — Zin wraps this as Zin.state.get(). Fields: keys, keys_pressed, keys_released — ARRAYS of pressed key code strings (e.g. {"KeyD", "Space"}). NOT a {KeyD=true} dict; t.keys["KeyD"] is always nil. keys_emulated — array of key codes held by the input-emulation floor, a subset of keys (merged there for polling); Zin.state.keyDownReal reads keys minus keys_emulated. mouse_position, mouse_delta — [x, y]; mouse_buttons, mouse_pressed, mouse_released — [L, R, M] bool arrays (InputResource convention); scroll_delta — number; pointer_locked, ui_focused — booleans; touches — array of { id, slot, x, y, dx, dy, pressure, phase } per active finger contact (slot 0 = primary; phase: began|moved|stationary|ended|cancelled); touch_capable — boolean, true once the session has (or declares) a touch input source.