Log inGet started
Package

surface.module

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

surface

Active input-surface classification. Answers "what device class is the player using right now" — "touch", "kbm" or "gamepad" — and notifies on change; backs Zin.surface. Virtual touch controls mount whenever the surface is "touch", in edit and play alike, so they leave the screen once the player picks up a pad, and button prompts read from the class follow the device in the player's hands.

The frame rule

Resolution runs once per engine frame from the Zin.tick pipeline: a per-event observer collects which device classes produced events this frame, and the frame resolver applies one rule — touch wins a frame that contains any touch event; otherwise the frame's last keyboard, mouse or pad event decides. A pad counts once it is used: a button pressed, or a stick or trigger pushed past half its travel. A pad that only connects, or a stick resting near its centre, decides nothing. The primary touch contact also drives the mouse path (a projected mouse.down/move/up in the same frame), so classifying by the latest single event would flip to kbm on every tap; the frame rule keeps projection-generated mouse events from masking the touch that caused them.

Capability default

Before any input arrives, the class defaults to "touch" on sessions with a touch device (touch_capable — latched by a device's first contact or declared at boot by Android / the web client) and "kbm" otherwise, so touch-first devices present touch controls from the first frame.

Simulated input

Input a script simulates (inputSim, Zin.test.*) presents its class while it lasts: a simulated contact presents "touch" while it is on the glass, a simulated key or mouse button presents "kbm" while the engine holds it down, and a simulated pad's use presents "gamepad" while that pad stays connected. The latest simulated input is the one presented. Once it ends, the class is the one it would be had the simulation never been made: what device input last resolved, else the capability default, and onChange reports the return. A simulated mouse move or wheel with nothing held, or a key pressed and released in one frame, lasts no time. A device's input of any class resolves the class and ends the simulation.

So a desktop a test or an agent taps on keeps presenting as keyboard and mouse, and its touch overlay comes down with the contact; a phone or tablet an agent types on keeps presenting as touch, its on-screen controls up once the key is released. A real keyboard, mouse or pad still takes a touch session out of touch. force pins a class whatever input arrives. A test that checks a whole touch session on a desktop declares one with input.simulateTouchCapable(true) (and false to take it back); a suite's input baseline puts the declaration back when the suite ends.

Exports

  • M.current() -> string — the active surface class, "touch", "kbm" or "gamepad".
  • M.onChange(fn: (string, string?) -> ()) -> number — subscribe to class flips; fn(now, prev) where prev is the previously reported class (the first-tick capability default when no event had resolved yet). Returns a handle.
  • M.off(handle: number) -> boolean — unsubscribe an onChange handle.
  • M._beginFrame() — internal: clear this frame's per-class flags; wired by Zin.tick.
  • M._observeEvent(ev: any) — internal: per-event observer; wired by Zin.tick.
  • M._resolveFrame() — internal: resolve this frame's class and fire onChange on a flip; wired by Zin.tick.
  • M._reset() — test-only: clear resolution state and subscriptions.

Types:

  • SurfaceClass = "touch" | "kbm" | "gamepad"

Usage

local Surface = require("@builtin::modules.zinput.surface")

if Surface.current() == "touch" then
    showTouchOverlay()
end

Surface.onChange(function(now, prev)
    print("surface flipped to", now)
end)

Notes

  • onChange fires from the Zin.tick pipeline on the frame the class flips; without a tick, resolution never advances and current() keeps returning the capability default.
  • The change signal compares against the last reported class, whose initial value is the capability default captured on the first tick of the session — a phone's first contact confirms the default silently, while a desktop touchscreen's first contact reports kbm→touch.
  • Handler errors during onChange dispatch are caught and logged, not propagated.