Log inGet started
Package

zinput.module

Newest version

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

README.md

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, owner: string?, widget: boolean }

Contact record fields

FieldMeaning
idThe platform's stable finger id for the contact.
slotLowest index free when the contact began; 0 = primary.
x, yScreen position.
dx, dyThis frame's accumulated delta.
pressureNormalized 0..1 (1 when the platform reports none).
phase"began" | "moved" | "stationary" | "ended" | "cancelled" (ended/cancelled contacts survive exactly one frame).
pointerWhether the contact drives the UI's pointer (and the mouse path), so a widget under it can take its press. One contact at a time does: the one that began while no other contact drove it, outside every region an on-screen control holds (input.setTouchClaims), and that is no simulated contact for the game alone. A contact a control takes lets it go, so the next finger to land drives it.
ownerThe on-screen controls holding the contact, by the owner name they state their regions under, or nil while none does. A contact beginning on a control's region is held from the start; one beginning on a control's zone (a movement stick's or a look area's) is held once the UI leaves its press, or at once while another contact drives the pointer, and is never held when a widget beneath it takes the press. So a thumb on the stick is held by the controls while a second finger presses a HUD button.

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).