pointer.module
This package holds more than this page lists. See all of its files in its world.
README.md
pointer
Pointer lock: who asks for it, and what the engine made of the ask. Wraps
the internal __zero_input.requestPointerLock / releasePointerLock
primitives and backs Zin.pointer.
The ask is held by named holders, and the engine's request stands while
any holder does. The scheme holds it as Zin.scheme for the live,
unsuppressed maps that declare pointerLock; a Zin.controllers free or
fps controller holds it for itself; an ask that names no holder is held as
Zin.pointer.lock.
Exports
M.lock(holder?, reason?)— ask for pointer lock (cursor grab + hide) underholder. Asking again under the same name restates the request and replaces the reason.M.unlock(holder?)— withdrawholder's ask; the cursor is released once no holder is left. With no holder, every ask goes and the cursor is released.M.holders() -> { { holder, reason } }— who is asking, in the order they first asked.M.holds(holder) -> boolean— whetherholderis asking.M.requested() -> boolean— whether the engine's request stands (Zin.state.pointerLockRequested()).M.locked() -> boolean— whether the surface granted it (Zin.state.pointerLocked()).M.status() -> { requested, locked, suppressed, armed, holders, why }— all of it in one read;suppressedis the cursor belonging to the person (gameplay paused, or the editor sharing the window with no scene picture on it),armeda click having armed the capture, andwhya sentence saying which answers.
Each read leaves the input observation as it stands.
Usage
local Pointer = require("@builtin::modules.zinput.pointer")
Pointer.lock("myGame.aim", "the aiming camera steers with the mouse")
print(Pointer.status().why)
Pointer.unlock("myGame.aim")
Notes
- The request records intent; the cursor is captured once the surface is active. Native: the window is focused and clicked. WASM: the next user gesture (browser policy). Escape or focus loss releases the capture and the next click takes it again.
requested(),locked()and the engine's half ofstatus()read the input snapshot the engine publishes once a frame, so an ask reads there from the frame after it;holders()answers at once.- A request written around
Zin.pointer(a simulated device event, a device reading put back) is the engine's alone:requested()can stand withholders()empty, andstatus().whysays so.