surface.module
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)whereprevis the previously reported class (the first-tick capability default when no event had resolved yet). Returns a handle.M.off(handle: number) -> boolean— unsubscribe anonChangehandle.M._beginFrame()— internal: clear this frame's per-class flags; wired byZin.tick.M._observeEvent(ev: any)— internal: per-event observer; wired byZin.tick.M._resolveFrame()— internal: resolve this frame's class and fireonChangeon a flip; wired byZin.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
onChangefires from theZin.tickpipeline on the frame the class flips; without a tick, resolution never advances andcurrent()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
onChangedispatch are caught and logged, not propagated.