Log inGet started
Package

touchControls.module

Newest version

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

README.md

touchControls

On-screen touch overlay: a renderer + worker, not an event-driven widget net. The worker reads raw touches (Zin.touch.slots()) and routes them into zone geometry derived from the live bindings, writing Zin.virtual (stick/button/drag). Zin.tick runs the worker early — after Virtual._beginFrame() clears the previous tick's drag deltas and before the binding evaluators read Zin.virtual — so the touch binding kinds consume those values on the SAME tick they're written. The renderer (a canvas screen declaring pointerEvents = "none") only draws and takes no pointer, so every widget beneath it, in any screen at any layer, still receives the presses that land on it. Backs Zin.touchControls.

Who a contact belongs to

  • A contact that begins on a drawn button, the fan or an open sheet entry is that control's alone. The overlay states those circles to the input layer with input.setTouchClaims (in the window's pixels, where the input layer meets a contact as it arrives), and a contact beginning inside one drives no pointer: no widget beneath the button is pressed by it, and no mouse button reads held.
  • Each contact is routed on its own, by where it began, so a thumb on the stick and a finger on a HUD button each do their own job. The overlay also states the stick and look zones to the input layer (setTouchClaims's zones). A contact beginning in a zone drives the pointer while no other contact does, and the UI decides whether a widget beneath it takes its press. When one does, the contact is the widget's: on the tick after it began, the zone that took it lets it go before it has moved anything. When none does, the input layer hands the contact to the overlay: it lets the pointer go, the scene reads no press from it, and the next finger to land drives the pointer, so it presses a content button while the thumb steers. A contact beginning in a zone while another contact drives the pointer is the zone's at once. Zin.touch states each contact's owner ("zin_touch_controls" for a contact the overlay holds).
  • A contact the input layer gives another owner (its owner names a claim owner other than the overlay's: a world that draws touch controls of its own states their regions with input.setTouchClaims too) is that owner's. The overlay routes it to none of its controls, so a press on a world's own button presses no button, stick or look area of the overlay's lying beneath it.
  • Everything left falls to the stick and look zones below.

Coordinate space

Touch contacts (Zin.touch.slots() — t.x/t.y/t.dx/t.dy) carry PHYSICAL pixels of the scene viewport the overlay draws over, measured from its top-left: the space Zin.state.get().mouse_position reads the pointer in. Every widget geometry computation — button/stick positions, the canvas root's style.width/height — lives in ui.screenSize()'s LOGICAL space (the space ui.registerScreen / ui.getLayoutInfo use), which differs from the physical space whenever the display's pixels_per_point ~= 1 (HiDPI). An internal logicalScale helper computes the screenSize / viewportSize ratio once per tick, and every touch coordinate this module reads is scaled by it before use.

Safe area

Every control keeps inside the part of the overlay no system bar, display cutout or on-screen keyboard covers. ui.safeArea() states that part of the picture the overlay's screen lays out in (the scene viewport's, at ui.screenSize()), and the overlay takes it into its own space, which leaves a safe rect L/T in from the left and top edges, SW x SH in size (the whole picture where the picture lies inside the window's safe area, as a Scene panel does). The zones, the button column and the stick all lie inside it, a contact beginning outside it starts none of them, and layout().safe reports it.

The space the controls leave a game screen

The overlay states the bounding square of every drawn button, the fan and the open sheet's entries with ui.setControlRegions("zin_touch_controls", rects), in the points of ui.screenSize(), the canvas a game's screens lay out on, and states them again whenever they change (a button added or removed, the context, the screen size or the safe area changing, the fan sheet opening) and withdraws them when the overlay leaves the screen. A game screen reads them as ui.safeArea().controls, and an anchor of any other screen moves clear of them on its own. The list holds the drawn controls alone: a widget laid out over the stick or look zone takes the presses that land on it.

Size on the glass

Every radius, inset and gap is in the points ui.screenSize() reports. On a phone or a tablet a point covers at least the display's density (ui.displayScale()), so the controls keep one physical size on every phone and in both orientations: a 40 point "small" button is 80 dp across, past the 48 dp touch target. layout() reports the radii in points; multiply by the pixels one of the overlay's points covers for their size on the glass: the width ui.getLayoutInfo("zin_touch_controls_canvas") gives its canvas, over layout().safe.width, times ui.pixelRatio(). Button labels are canvas text sized from the button's radius, so the user's text scale leaves them inside their circles.

Zone geometry (fractions of the safe rect, SW/SH)

  • stick - activation region x < L + 0.4*SW and y > T + 0.4*SH (left 40%, bottom 60%). A floating stick: the base spawns at the touch's start point, the thumb clamps to a 96px radius, and the vector fed to Zin.virtual.setStick is offset / 96 with y screen-down positive (matching setStick's documented convention).
  • buttons — one circle per touchButton binding among the LIVE bindings (Zin.scheme.bindings() — what awake components asked for, so every button corresponds to a control some world actually consumes), budgeted into a two-column band along the safe rect's right edge, between 45% of its height and its bottom edge less the inset. Buttons sort by (priority, id) - the touchButton's priority option, authored default 50, synthesized default 100 — with same-group buttons kept adjacent, then fill the two columns growing inward from the bottom-right corner. Each circle is the radius ITS OWN size option names (small 40px, medium 56px, large 72px), so a scheme mixing a large action button with a small pause pip draws them at 72 and 40 whatever else is live; the largest of those radii is the slot pitch and the row budget the column packs on, so the set decides where a button sits and the button's own declaration decides how big it is. More than 4 authored buttons walk every button one step down its own size, which layout() reports as appliedSize. Anything past the two-column budget doesn't render individually — the last slot becomes a ... fan button; tapping it opens a rows-of-3 grid sheet holding the overflow (same tap/hold behavior as a regular button), and tapping the fan again, or any layout-invalidating context/map change, closes it.
  • corner buttons - a touchButton whose place is "corner" sits in the top-right corner of the safe area instead, in a row growing leftward along the top edge in (priority, id) order, each at its own size. A row ends at the look area's left edge (L + 0.4*SW), so the top-left quadrant stays free, and the next button starts a row below it. Corner buttons count toward neither the column's budget nor its step-down, keep their place whatever the column holds, and the column's band starts below their lowest row. The app menu's Menu button (@builtin::inputMaps.app) is one.
  • drag - everything else in the safe rect at x >= L + 0.4*SW (accumulates into Zin.virtual.addDrag every tick from the contact's per-frame delta).
  • the remaining top-left quadrant (x < L + 0.4*SW and y <= T + 0.4*SH) is unclaimed - free for other UI.

A control is drawn only when it is live AND subscribed: a button offered for a control nothing listens to is an offer that cannot be kept, so the layout tracks Zin.scheme.subscriberEpoch() alongside Zin.scheme.generation().

Only bindings whose context matches the current input context (Zin.context.current()) contribute controls, so a vehicle-context Brake button neither renders nor claims touches while the default context is on top. The layout rebuilds when the live set, the subscriber count, the context, the screen size or the safe area changes.

A record-shaped map applied through Zin.map.activate contributes its touch classes too. A control whose name is already live as an asset is skipped, so a world carrying both never draws the same control twice under two ids.

A contact is assigned to a region on its began phase only (a contact-id -> assignment map) and released on ended / cancelled / vanishing from Zin.touch.slots(). Button circle hit-tests (visible buttons, the fan, the open sheet's entries) take precedence over the stick/drag zone checks — a button is a precise target and wins wherever it lands, including inside a zone (the open sheet grows leftward and can reach the stick zone on a narrow screen). A contact claimed by the stick or a button never also feeds the drag zone (a contact is assigned to exactly one region), so its projected-mouse / touchDrag state never competes with a look/aim consumer reading Zin.virtual.drag — no extra suppression is needed beyond the region assignment itself.

A pinch and the drag region share the same space, so the two are arbitrated once per tick. The contacts the stick and the buttons hold are published to Zin.gestures, which forms its two-finger pair out of what is left; while the active map declares a touchPinch control and that pair is down, the drag region reports nothing. A pinch made over the look surface therefore reaches the pinch control alone, a thumb resting on the movement stick is no part of a pinch so the other thumb keeps looking, and lifting one finger from a pinch drags again.

Rendering

One screen ("zin_touch_controls", layer 200) whose root is a single transparent canvas sized to the safe rect, taking no pointer. The screen lays out inside the safe area, so the canvas starts at the rect's corner and every command is drawn from there. Commands rebuild only when the draw state actually changed (a dirty flag) — buttons are always drawn while mounted; the stick draws only while a stick contact is live.

Auto-mount

Every _advance() checks Zin.surface.current() — "touch" registers (lazily, once) and shows the screen; anything else hides it. Visibility is purely the surface class, in edit and play alike. M._forceMount(true) bypasses the surface gate for headless testing. Touch routing runs on every tick a contact is down, held by a control or waiting on the UI's answer, and on every tick the overlay is on screen or coming up, whatever the mount state, so a forced or real touch always drives Zin.virtual even before the overlay is visible. A session nobody is touching, with the overlay off screen, routes nothing.

Adding a control while the world runs

The overlay draws a button for a control that is live and subscribed, so adding one at runtime is adding a control asset, activating it, and subscribing to it — the three steps a component takes in awake, in one call:

local h = Zin.touchControls.addControl({
    name = "cast", label = "Cast",
    kbm = Zin.bindings.key("KeyF"),
    gamepad = Zin.bindings.padButton("north"),
    onPressed = function() castSpell() end,
})
Zin.touchControls.removeControl(h)

The control becomes a real <name>.inputMap/<name>.inputBinding/ under /source/runtimeControls/, so it is inspectable, rebindable and publishable like any other, and its name is its id in Zin.scheme.bindings() / Zin.scheme.fired(). removeControl releases it — off the screen, out of the live set, every subscription dropped — and leaves the asset, so re-adding the same name reuses it and its guid.

M.button(opts) is the same idea against a record-shaped map applied through Zin.map.activate, in two flavors:

  • { action = "jump" } attaches an extra touchButton binding to an existing action on the active map.
  • { emit = "KeyF", label = "Cast" } registers an overlay-only button: a synthetic emit:KeyF action carrying both the kbm key binding and the touchButton, so the emulation floor drives KeyF through the same binding/emulation path every other control uses.

Both return a handle for M.removeButton(handle), which takes off the screen exactly the button M.button put there: the overlay draws what it drew before the pair of calls. A button attached to the floor (the builtin default map the input system armed itself) draws even while the floor's own controls stand down for a world's scheme.

Exports

  • M.addControl(opts: ControlOpts) -> number / M.removeControl(handle) -> boolean — add or release a control while the world runs.
  • M.controls() -> { { handle, name, path } } — every control addControl currently holds, in the order they were added.
  • M.button(opts) -> number / M.removeButton(handle) -> boolean — the button API described above.
  • M.claimed() -> { number } — the contact ids currently claimed by the stick, a button, or the drag zone.
  • M.primaryClaimed() -> boolean — whether an on-screen control owns the contact driving the pointer (Zin.touch pointer = true). Zin.bindings consults this so a thumb on the stick or the look area does not also fire whatever the world bound to left-click in the frames before the UI has decided its press, while a finger on bare scene beside a thumb on the stick reads as the press it is.
  • M.layout() -> { buttons, fan?, stick?, drag?, pinch?, width, height, safe } - the current control layout (a copy): buttons is the budgeted, VISIBLE stack in draw order, the corner rows after the column, each entry { id, label, actionName, priority, size, appliedSize, group, place, cx, cy, radius } in ui.screenSize() space: place is "column" or "corner", size is the step the binding declared and appliedSize the one radius came from, which differ only where a rich scheme's step-down moved a button one size down; fan is nil unless the button set exceeded the two-column budget, else { open, cx, cy, radius, buttons } — open is whether the overflow sheet is expanded, buttons the overflowed entries at their sheet positions (tappable only while open); stick / drag name the axis + virtual zone each region feeds, and pinch the axis the two-finger recognizer feeds; safe is the safe rect { x, y, width, height } every control keeps inside. Backs custom control-placement UI and headless tests that aim simulated touches at a button's (or the fan's) center.
  • M._advance() — internal: one tick (touch routing, layout, auto-mount, repaint). Wired into Zin.tick, before Zin.emulation._advance().
  • M._forceMount(on: boolean) — test-only: force mounting regardless of Zin.surface.current().
  • M._setViewportOverride(w?, h?) — test-only: override the logical screen size the layout budget/fan math reads, without resizing the real window. Pass nil/nil to clear.
  • M._reset() — test-only: unmount, clear routing/layout state, drop buttons, release every runtime control, close the fan, and clear the viewport override.