touch

Per-finger touch contacts. Thin wrapper over the touches array of the internal __zero_input.snapshot() FFI plus pre-baked touch.* event listeners; backs Zin.touch.

Exports

• M.slots() -> { TouchPoint } — all active contacts this frame, in begin order.
• M.count() -> number — number of active contacts this frame.
• M.byId(id: number) -> TouchPoint? — look up an active contact by finger id.
• M.primary() -> TouchPoint? — the primary contact (slot 0), if a finger is down.
• M.capable() -> boolean — whether the session has (or has declared) a touch source.
• M.onBegan(fn, opts?) -> handle — subscribe to touch.down events.
• M.onMoved(fn, opts?) -> handle — subscribe to touch.move events.
• M.onEnded(fn, opts?) -> handle — subscribe to touch.up events.
• M.onCancelled(fn, opts?) -> handle — subscribe to touch.cancel events.
• M.off(handle) — unsubscribe a handle returned by any on* function.

Types:

• TouchPoint = { id: number, slot: number, x: number, y: number, dx: number, dy: number, pressure: number, phase: string, pointer: boolean }

Contact record fields

Field	Meaning
id	The platform's stable finger id for the contact.
slot	Lowest index free when the contact began; 0 = primary (also drives the mouse path).
x, y	Screen position.
dx, dy	This frame's accumulated delta.
pressure	Normalized 0..1 (1 when the platform reports none).
phase	"began" | "moved" | "stationary" | "ended" | "cancelled" (ended/cancelled contacts survive exactly one frame).
pointer	Whether the contact drives the UI's pointer, so a widget under it can take its press. The primary contact does, unless it began on a region an on-screen control holds (input.setTouchClaims) or is a simulated contact for the game alone.

Usage

local Touch = require("@builtin::modules.zinput.touch")

for _, t in ipairs(Touch.slots()) do
    print(t.slot, t.x, t.y)
end

local h = Touch.onBegan(function(ev, gpe)
    print(ev.id, ev.x, ev.y)
end)

Notes

• onBegan / onMoved / onEnded / onCancelled are pre-baked kind filters over Zin.events.on — handlers dispatch from the Zin.tick pipeline and receive (ev, gpe) where gpe is the UI-focus flag at fire time. Return "sink" to stop lower-priority handlers from seeing the same event.
• All entry points return empty / falsy values when __zero_input is missing (off-host execution).