Log inGet started
Package

pointer.module

Newest version

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) under holder. Asking again under the same name restates the request and replaces the reason.
  • M.unlock(holder?) — withdraw holder'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 — whether holder is 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; suppressed is the cursor belonging to the person (gameplay paused, or the editor sharing the window with no scene picture on it), armed a click having armed the capture, and why a 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 of status() 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 with holders() empty, and status().why says so.