◇
component · drop-in viewer
first_person
First-person camera controller. Positions the camera at an entity's location (+ eye-height offset) and rotates with mouse look.
byzero-proxy @ DESKTOP-DB3UJOJ·posted 2mo ago
What it does
controller.first_person
First-person camera controller. Positions the camera at an entity's location (+ eye-height offset) and rotates with mouse look.
It resolves its follow target in this order: its own target field, then Camera.follow when target is empty, then the static posX/posY/posZ when neither is set. Camera.follow is the standard slot every behavior reads, so a first-person camera selected through Camera.behavior tracks whatever Camera.follow points at — the correct source for a player camera, whose body id is minted fresh per spawned clone and cannot be authored onto the behavior ahead of time.
Public fields: target (entity id to follow, empty = use Camera.follow, then posX/Y/Z), posX, posY, posZ, offsetX, offsetY (eye height above target origin), offsetZ, sensitivity, minPitch, maxPitch.
Controls: pointer lock to rotate (yaw + pitch), which the standard scheme takes while the world runs. With the cursor handed back, an RMB drag rotates too — for as long as nothing else in the world binds the right button.
-- Track the Camera's follow target (set Camera.follow, no id authored here):
entity(id).component.add("controller.first_person", { offsetY = 1.6 })
-- Or a static camera at a fixed position:
entity(id).component.add("controller.first_person", { posX = 0, posY = 1.6, posZ = 3 })
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2First Person Camera Controller Positions the camera at an entity's location (+ eye-height offset) and rotates with mouse look. Reads its follow target from `Camera.follow` — the standard slot every behavior reads — when its own `target` field is empty, so a first-person camera selected through `Camera.behavior` tracks whatever `Camera.follow` points at with no per-entity id authored here. With neither set it parks at the static `posX/posY/posZ`. Usage: entity(id).component.add("controller.first_person", { target = "player", offsetY = 1.6 }) entity(id).component.add("controller.first_person", { posX = 0, posY = 1.6, posZ = 3 }) Controls: The `look` control of the map on `inputMap` — mouse while steering, right stick on a pad, a finger dragging the look zone on a phone.
takeLook( ) → void
quatFor(y: number, p: number) → void
This controller measures pitch downward — positive looks down, which is the direction `minPitch` / `maxPitch` bound and the direction mouse-look adds in. `Transform` measures it upward, so the sign flips crossing between them. These two are the only place that conversion happens, which is what keeps reading a rotation back the exact inverse of writing one.
| arg | type | description |
|---|---|---|
| y | number | |
| p | number |
yawPitchOf(qx: number, qy: number, qz: number, qw: number) → void
| arg | type | description |
|---|---|---|
| qx | number | |
| qy | number | |
| qz | number | |
| qw | number |
armInput( ) → void
Take the controls, and give them up. A paused world belongs to the editor camera: releasing names this rig's own claim, so it takes this rig's subscriptions and nobody else's, and the pointer returns to the cursor.
releaseInput( ) → void
awake( ) → void
update(dt: ?) → void
| arg | type | description |
|---|---|---|
| dt | ? |
onDestroy( ) → void
Releasing the map takes this camera's controls out of the live set when it goes away. It releases this rig's claim alone, so a camera and a character sharing a map is fine — the character keeps hearing its own. The pause registration goes with them: it exists to arm this rig when gameplay resumes, and a rig that has gone away has nothing to arm.
Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
93+items
# Component (asset type)
A component is a reusable behavior + data unit attached to an entity.
The component file declares public fields, methods, and lifecycle
callbacks; the engine instantiates one per attachment and drives its
hooks every frame. Components are the primary unit of gameplay code —
movement, AI, animations, UI panels, network sync, and per-entity state
all live here.
## When to use one
- You need per-entity state that survives across frames.
- You need per-entity behavior driven by engine lifecycle hooks
(`start`, `update`, `destroy`).
- You want to expose configurable fields to designers / `entity.spawn`
callers / scenes without code changes.
If you need a global service that outlives any entity, use a `.service`
instead. If you need a stateless pure-function library, use a `.module`.
## Where it lives
- Source: `/zero/source/.../<Name>.component/`
- Identity: `<Name>` (the `.component` suffix strips from the
identity, but the folder retains the suffix on disk).
- Folder shape:
- `init.luau` (or `init.lua`) — declares the component. **Required.**
- `README.md` — instance-level documentation. **Required.**
- `.metadata` — agent-editable tags + free-form fields. **Required.**
The structural contract is enforced by `asset.validate` against this
type's `type.yaml`.
## How to create one
Always start with the scaffold — it guarantees the folder shape
matches `type.yaml` from the moment it's on disk:
```luau
asset.create("component", "<Name>")
-- Creates: /zero/source/<Name>.component/
-- init.luau (canonical declare + public block + hooks stubbed)
-- README.md (instance README template)
```
After scaffolding, edit `init.luau` to fill in the actual fields and
behaviour. The component registers as soon as the file is written —
hot-reload is automatic; no engine restart required.
## How it operates
1. **Registration.** Writing `init.luau` into a `.component/` folder
indexes the asset, mints a guid (in the `.meta` sidecar), and
surfaces the type to the engine's component registry. Same-frame
visible to `entity.component.add`.
2. **Attachment.** `entity(id).component.add(name, data)` (or the
batch form `tools.use("entityOps", "addComponents", targets,
{ [name] = data })`) attaches an instance.
The `data` table's fields override the component's declared
defaults; omitted fields take the declared default. The `data`
values are copied into `public.*` BEFORE `awake()` runs.
3. **Lifecycle.** The hooks run in this order:
- `awake()` — same frame as attach, immediately after the data
copy. Initialise state, set up native bridges, register with
other systems. Other components on the same entity may not have
awoken yet.
- `start()` — the next frame. Every component on the entity has
completed `awake()` by then, so cross-component setup is safe
here.
- `update(dt)` — same frame as `start()`, then every frame after,
for as long as the gameplay clock is running. `fixedUpdate(dt)`
runs beside it on the fixed timestep; `editorUpdate(dt)` runs
while the clock is held. Which of them ticks is decided by
`engine.mode` AND `engine.paused` together — see **Per-frame
hooks and the two axes** below, and `man modes`.
- `onDestroy()` — when the component is removed via
`component.remove` or when the owning entity is despawned.
Release resources, drop native ECS components.
For the full list (`onEnable`, `onDisable`, `fixedUpdate`,
`editorUpdate`, `onPropertyChanged`, `onAssetReload`,
`onModuleReload`,
`onBeforeSave`, …) and the timing details, **read `man components`
— that is the canonical lifecycle reference. Generic component
patterns (declare blocks, public fields, sync, ECS bindings,
typed methods) all live there.**
4. **Public surface.** Fields declared in `public` are inspectable,
editable in the inspector, and persist with the entity. Methods are
declared on that same table with a colon —
`typed function public:method(args)` — and every one of them takes
the component ref as `self`, so a caller invokes it with a colon
too: `entity(id).component.get(name):method(args)`. That is the one
calling convention a component ref answers to: the reflection
methods `ref:fields()` / `ref:getField(name)` /
`ref:setField(name, value)` take the same spelling. A function the
chunk declares at file scope (`function helper()`) is the
component's own, reachable from its hooks under its bare name;
`public` is what the ref carries.
5. **Settings and the Inspector card.** `type.yaml` names the component's
settings schema as `settings: { schema: { instance: "init.luau",
export: "public" } }`: the `public` table IS the schema, and its values
live on each entity the component is on, so `asset.schema(componentRef)`
answers the Field descriptors and no values file exists. On an entity
the Inspector shows the component as a card whose generic `settings`
section edits those fields as typed controls, each edit checked against
the schema and written to the live component as one undoable operation.
`type.yaml` also names `inspector: { instance: "inspector.luau" }`: a
component that ships an `inspector.luau` beside its `init.luau` shapes
its card — the file returns `{ sections, replace, order }` (see
`assetTypes/README.md`, "`inspector:`"), each section's `build(ctx)`
reading `ctx.component` (the live component) and `ctx.selection.id` (the
entity). `SceneModule.component/inspector.luau` replaces `settings` with
the bound module's declared inputs.
6. **Events.** An `events` block declares typed moments the component
fires from inside — `events = { onHit = Event({ dmg =
Field.number(0, NoSync) }) }`. The owner fires with
`events.onHit:fire({ dmg = 10 })`; outside code subscribes through
the proxy's subscribe-only facade,
`entity(id).component.get(name).events.onHit:connect(fn)`
(`:once` / `:wait` too). Pass `Sync` as the event's second argument
to replicate a fire to other peers. Events let one component react
to another's moments without polling. Full reference: **`man
components`**, Events section.
7. **Hot reload.** Editing `init.luau` reloads the component
definition; live instances are reconciled with the new declaration
in-place, and each crosses one lifecycle boundary: `onDestroy()`
ends the running life, then `awake()` and `start()` construct the
one that replaces it, and `update()` resumes on the next frame.
`public` and `private` values carry across; module-level `local`s
belong to the chunk, so the new life starts with them at their
initial values and its `awake`/`start` are what fill them in.
Whatever the old life handed elsewhere — a subscription, a shared
registration, a spawned entity — is released in `onDestroy`, the
call that pairs with the construction about to run. An edit that
leaves the source byte-identical crosses no boundary at all.
A field carries its value across when something stated it: a key of
the `data` table the instance was attached with (a scene record's
data is that table), or a write made since. Every other field takes
the edited source's declared default, so changing a default reaches
every instance that left the field to it. An instance that states
its own value for a field whose default the edit changed keeps that
value, and the reload logs a `[HotReload]` warning naming the field,
the entity, the value kept and both defaults.
## Discovery
- `asset.list("component")` — every registered component (engine +
world + libraries).
- `asset.inspect("<name>")` — identity, scope, public fields,
lifecycle methods, source path, and this type README. `detail`
carries the component's declared `fields`, `methods`, and `events`,
parsed from its source — `tools.use("assets","describe", "<name>")`
renders it as markdown, so a component's events are visible without
opening its source.
- `ls /zero/source/<Name>.component` lists the files the folder holds.
- `entity(id).component.list()` — components attached to an entity.
## Per-frame hooks and the two axes
`engine.mode` (`"edit"` / `"play"`) and `engine.paused` (the gameplay
clock) are independent, and the per-frame hooks read them separately:
- `update(dt)` / `fixedUpdate(dt)` tick while **the gameplay clock is
running** — whichever mode the engine is in.
- `editorUpdate(dt)` ticks while **the clock is held** — because the
mode is `edit`, or because play is paused — and also alongside
`update` whenever edit is running.
Which gives four states, and this table is the contract:
| `engine.mode` | `engine.paused` | hooks that tick |
|---|---|---|
| `edit` | `true` | `editorUpdate` |
| `edit` | `false` | `update`, `fixedUpdate`, `editorUpdate` |
| `play` | `false` | `update`, `fixedUpdate` |
| `play` | `true` | `editorUpdate` |
Entering edit sets `paused = true` and entering play sets it back to
`false`, so a session that never writes `engine.paused` only ever sees
rows 1 and 3 — which is where the shorthand "`update` is the play tick,
`editorUpdate` is the edit tick" comes from. It is the two default rows
of a four-row table, not the rule.
**Row 2 is the one that surprises.** With `engine.paused = false` in
edit — set by hand, or by a tool that advances the gameplay clock to
sample it, such as a `capture.collage` given a `duration` — `update` and `editorUpdate`
both fire, once each, every frame. A component that declares both and
routes them to one body therefore runs that body **twice per frame**:
```luau
local function drive(dt) ... end
function update(dt) drive(dt) end
function editorUpdate(dt) drive(dt) end -- twice per frame in row 2
```
Nothing reports the doubling; it reads as an animation running at twice
its intended speed. To get exactly one tick per frame in every row, ask
which axis you meant and answer it in the body:
```luau
function update(dt) drive(dt) end
function editorUpdate(dt) if engine.paused then drive(dt) end end
```
A scene `entrypoint.luau` declaring the same two hook names is dispatched
by the scene loader, not by this table: there `update` needs play AND
running, `editorUpdate` needs edit, and play-paused ticks neither. Read
`man scenes` before carrying a component's rule to an entrypoint.
## Authoring conventions
- Annotate public fields with `--!desc` so the inspector + LSP show
documentation alongside the field name.
- Declare lifecycle hooks (`start`, `update`, `destroy`) explicitly
rather than relying on engine defaults — readers can see at a glance
what runs when.
- Keep `update(dt)` cheap — it runs every frame per instance. Move
heavy work to `start`, to a service, or behind a job (`man jobs`).
- For multi-entity batching, prefer
`tools.use("entityOps", "addComponents", targets, components)` over
a loop of `entity(id).component.add` — it takes many targets and
many components in one call.
## Common pitfalls
- **Naming.** The component identity is the folder stem with
`.component` stripped (e.g. `<Spinner>.component/` → identity
`Spinner`). Don't repeat the suffix in the identity passed to
`component.add`.
- **`init.lua` vs `init.luau`.** Either is accepted (it's a
`one_of_group: "entrypoint"`), but `.luau` is canonical. Mixing both
in one folder is invalid.
- **`update` in edit mode.** It runs whenever the gameplay clock is
running, and entering edit stops that clock — so `update` is idle in
a freshly-entered edit session and ticks again the moment anything
sets `engine.paused = false`. Use `tools.use("wld", "play")` to test
update logic under the mode it ships in; `tools.use("wld", "edit")`
to return. See **Per-frame hooks and the two axes** above.
- **Renaming.** Renaming the folder changes the identity. Update
every `component.add(<oldname>, ...)` call and the scene JSON
entries that reference it.
## Related types
- `.module` — pure-function library, no per-entity state.
- `.service` — globally-scoped behavior, no per-entity state.
- `.preset` — a captured component configuration, replayable into
`component.add` without re-typing fields.
- `.bundle` — entity hierarchies that may carry component attachments
as part of the bundle.
## In the Inspector
Fields: its execution order, hooks, and how many methods and events it declares, then the fields its `public` table declares as read-only typed controls holding their defaults, with **Check** and **Open** for its entry file. Instances: a link to every entity carrying it. What its card shows on an entity comes from the component's own `inspector.luau`.
▲ 0↑ born
# default.inputMap
The engine's standard control scheme, and the map a world activates for a
player who is the one moving. Its group is `player`, so a map that names
that group — `vehicle.inputMap` does — stands these controls down for as
long as it is live.
## Controls
The `<name>.inputBinding/` folders beside `init.luau` are the controls. A
component activates the map and subscribes to the ones it drives:
| Control | Kind | kbm | gamepad | touch |
|---|---|---|---|---|
| `move` | axis2 | WASD | left stick | left stick |
| `look` | axis2 | mouse delta | right stick | right drag zone |
| `jump` | button | Space | south | button |
| `sprint` | button | Shift | left stick click | button |
| `crouch` | button | Ctrl | east | button |
| `interact` | button | E | west | button |
| `zoom` | axis1 | wheel | shoulders | pinch |
| `pointerLock` | button | Escape | — | — |
| `lookDrag` | button | right mouse | — | — |
`pointerLock` and `lookDrag` refuse gamepad and touch outright, in the
record where a reader sees it: capture belongs to a cursor, and a stick or
a dragging finger says it is steering by being pushed at all.
Vertical movement lives in `flight.inputMap`, which composes beside this
one and belongs to the same `player` group. Driving lives in
`vehicle.inputMap`, which stands this group down while somebody has the
wheel.
## Compatibility registry
The `actions` / `axes` tables in `init.luau` are the registry read by
`Zin.actions` / `Zin.axes`. They are keyboard and mouse only, and they are
what keeps a world written against `Zin.actions.held(...)` working.
The engine's standard control scheme. Every action and axis carries explicit
`kbm` bindings; movement, look, and the primary held actions (sprint, crouch,
jump, vehicle brake) also carry explicit `touch` bindings so the scheme works
identically on a phone with no synthesis needed.
- **Movement** — `move` (WASD, or the left virtual stick on touch),
`move_vertical` (Space/Ctrl, kbm-only — no vertical touch stick in this
scheme).
- **Fly** — `fly_up` (E/Space) and `fly_down` (Q/ShiftLeft), kbm-only with
touch synthesis suppressed — fly-camera vertical movement for controllers
that read actions rather than the `move_vertical` axis.
- **Look** — `look` (mouse delta on kbm, the right drag zone on touch), plus
`look_x` / `look_y` single-axis kbm variants for controllers that want one
component. `look`'s gate passes on pointer-lock or held right-mouse-button
(kbm), OR whenever the touch drag zone is producing input — a phone has
neither a locked pointer nor a right mouse button, so the touch path needs
no arming gesture.
- **Held actions** — `sprint`, `crouch`, `jump` each carry a `right-lower`
zone `touchButton` alongside their kbm keys.
- **Zoom** — `scroll_y` (wheel on kbm, the two-finger pinch delta on touch).
- **Vehicle context** — `vehicle_throttle` / `vehicle_reverse` /
`vehicle_steer` / `vehicle_brake`, active only while the `"vehicle"`
input context is pushed.
Activating any OTHER map's axis with a touch class beyond its primary
registers a `<axis>@<class>` sibling axis (e.g. `look@touch`) — this map's
own `look` axis carries an explicit `touch` binding, so it follows the same
convention once flattened by `Zin.map.activate`.
`Zin.map.ensureActive()` activates this map when no other map is active —
it is the map every kbm-only world already runs, now carrying its explicit
touch classes for phones and tablets. This is also the map a cold
`Zin.actions` / `Zin.axes` read activates automatically, so any world
reading actions plays with zero setup.
▲ 0↑ born
# camera_rig
Shared internals for the camera rigs — the parts every follow camera needs
before it gets to have a personality.
`third_person_follow` (a shoulder rig) and `orbital_follow` (a three-ring
orbit) resolve their follow target the same way, damp toward a goal the same
way, avoid geometry the same way, and write their pose the same way. Only the
placement of the camera relative to the subject differs, so everything else
lives here and the rigs stay small enough to read in one screen.
```lua
local CameraRig = require("controller.camera_rig")
function update(dt)
local target = CameraRig.resolveFollow(public.entity.id, public.follow)
if target == nil then return end
local t = entity(target)
local px, py, pz = t.position.x, t.position.y + public.height, t.position.z
local h, radius = CameraRig.ringAt(public.rings, public.orbitT)
local cx = px + math.sin(public.yaw) * radius
local cy = py + h
local cz = pz + math.cos(public.yaw) * radius
cx, cy, cz = CameraRig.pullIn(px, py, pz, cx, cy, cz, 0.3,
CameraRig.pullInExclude(target, public.cameraIgnore))
smoothX = CameraRig.damp(smoothX, cx, public.followTau, dt)
CameraRig.applyPose(public.entity.id, smoothX, cy, cz, px, py, pz)
end
```
## Exports
- `CameraRig.damp(current, goal, tau, dt) -> number` — exponential convergence
toward `goal`. `tau` is the time constant in seconds: the smaller it is the
tighter the camera tracks, and `0` snaps. Frame-rate independent, so a hitched
100 ms frame and six clean 16 ms frames land in the same place, and no frame
length overshoots the goal. Damp each component separately.
- `CameraRig.ringAt(rings, t) -> (number, number)` — height and radius of the
orbit at `t` along the three-ring spline, where `rings` is
`{ bottom = { height, radius }, center = ..., top = ... }`. `t` runs 0 at the
bottom ring to 1 at the top, passing exactly through the centre ring at 0.5;
adjacent rings are blended with a smoothstep so the seam has no visible kink.
Out-of-range `t` clamps rather than extrapolating.
- `CameraRig.resolveFollow(selfId, followField) -> string?` — the entity this
rig follows. Takes the rig's own `follow` field (an entity id or an entity
reference) when it is set, and otherwise falls back to the `Camera.follow`
slot, which is the standard place every camera behavior reads its target
from — that is what makes "swap the behavior, keep the follow target" work.
Returns `nil` when nothing is set AND when the resolved id has no live
entity, which is the normal state for the first frames of play mode while
the avatar is still spawning.
- `CameraRig.pullIn(pivotX, pivotY, pivotZ, camX, camY, camZ, radius, exclude?) -> (number, number, number)`:
the camera position moved in along the pivot-to-camera line until no
collider is between the two. A sphere of `radius` is swept from the pivot,
and every collider in the world stops it, whether or not anything draws it:
an invisible walk bound and a trigger volume pull the camera in exactly as a
wall does. `radius` is also the distance kept off the surface the camera
lands on; `0` turns the pull-in off and returns the input untouched.
`exclude` is an entity id, or a list of them, whose colliders the sweep
passes through: the subject the camera is looking at, plus anything the
camera should see through.
- `CameraRig.pullInExclude(subjectId, ignore) -> { string }`: the exclude
list a rig hands `pullIn`: the subject first, then every entity in the rig's
`cameraIgnore` list (ids or entity proxies). `orbital_follow` and
`third_person_follow` both build theirs with it from their `cameraIgnore`
field. A rig written on this module gives its authors the same control by
declaring a `cameraIgnore` list of its own
(`Field.list(Field.entityRef(nil, Sync), Sync)`) and passing it here.
- `CameraRig.applyPose(selfId, camX, camY, camZ, lookX, lookY, lookZ)` — place
the camera and aim it at a point. Both the pose and the aim point are in the
camera entity's own transform frame: parent-relative when the camera is
parented to its subject, world space when it is standalone. The write goes
to the local transform, so transform propagation composes the world matrix
from `parent_world * local` instead of being fought by a world-space write.
▲ 0↑ born
# transform
Math helpers for positions, rotations, and directions on transforms.
Exposed as the global `Transform` table via `--!global Transform` — no
explicit require needed in user code. Functions that take an entity
accept either an entity ID string or an entity proxy table from
`entity("id")`.
## Exports
Look-at and entity-aware helpers:
- `Transform.lookAtQuat(fx, fy, fz, tx, ty, tz) -> (qx?, qy?, qz?, qw?)` — quaternion from origin toward target. Nil when degenerate.
- `Transform.lookAt(entity, txOrTarget, ty?, tz?) -> (boolean, string?)` — make an
entity face a world position or another entity. Both slots read world space:
the subject and an entity target are read as `entity(id).position` and the aim
is written as `entity(id).rotation`, so a parent under either one still leaves
the aim on the point named. Returns whether the rotation was written, and the
reason when it was not.
- `Transform.distance(x1, y1, z1, x2, y2, z2) -> number` — Euclidean distance between two points.
- `Transform.distanceBetween(entityA, entityB) -> number?` — distance between two entities' world positions. Nil when either is unresolvable.
- `Transform.direction(fromX, fromY, fromZ, toX, toY, toZ) -> (dx, dy, dz)` — unit direction vector.
- `Transform.directionBetween(entityA, entityB) -> (dx, dy, dz)` — unit world-space direction between two entities' world positions.
Rotation shapes:
A quaternion **constructor** here returns the four components as four separate
values, so a caller either names them or braces the call to make one table:
```lua
local qx, qy, qz, qw = Transform.quatFromAxisAngle(0, 1, 0, math.rad(90))
entity("cam").localRotation = { Transform.quatFromAxisAngle(0, 1, 0, math.rad(90)) }
```
A rotation-taking **surface** reads that table through
`Transform.toQuaternion`, which also takes euler DEGREES — so
`{ qx, qy, qz, qw }`, `{ x =, y =, z =, w = }`, `{ pitch, yaw, roll }` and
`{ pitch =, yaw =, roll = }` all mean the same thing wherever a rotation is
assigned: `entity(id).rotation` / `.localRotation`, `entityOps.spawn`,
`entityOps.transform`, and the capture viewpoints.
- `Transform.toQuaternion(rotation, label?) -> { qx, qy, qz, qw }` — the shared reading of a rotation a caller wrote. Raises when the value matches no form, naming what arrived; a value that is one of the shapes a quaternion helper returns is named as such along with the packing it goes in as.
- `Transform.tryQuaternion(rotation, label?) -> ({ qx, qy, qz, qw } | nil, message?)` — the same reading without raising, for a surface that wants to raise the message at its own caller's line.
- `Transform.readVec3(value, label?) -> { x, y, z }` — the same for a vector.
- `Transform.snapVec3(v, step) -> { x, y, z }` — quantize a vector to a step grid.
Quaternion construction / conversion:
- `Transform.quatFromYaw(yaw)`, `Transform.quatFromYawPitch(yaw, pitch)`, `Transform.quatFromAxisAngle(ax, ay, az, angle)` — quaternion constructors.
- `Transform.quatIdentity()` — identity quaternion.
- `Transform.euler(qx, qy, qz, qw) -> (yaw, pitch, roll)` and the named alias `Transform.quatToEuler`.
- `Transform.eulerToQuat(yaw, pitch?, roll?)` — euler-to-quaternion in YXZ order.
Lerps and interpolation:
- `Transform.lerp(ax, ay, az, bx, by, bz, t) -> (x, y, z)` — vec3 lerp.
- `Transform.lerp1(a, b, t) -> number` — scalar lerp.
- `Transform.normalizeAngle(a) -> number` — wrap angle into `[-pi, pi]`.
- `Transform.lerpAngle(a, b, t) -> number` — shortest-arc angle lerp.
- `Transform.slerp(ax, ay, az, aw, bx, by, bz, bw, t) -> (qx, qy, qz, qw)` — quaternion slerp with shortest-path and near-parallel fallback.
Quaternion operations:
- `Transform.quatMul(...) -> (qx, qy, qz, qw)` — `qa * qb` composition.
- `Transform.quatInverse(qx, qy, qz, qw) -> (qx, qy, qz, qw)` — inverse (= conjugate for unit quats).
- `Transform.quatRotateVec(qx, qy, qz, qw, vx, vy, vz) -> (x, y, z)` — rotate a vec3 by a quaternion.
Pose helpers:
- `Transform.orbit(centerX, centerY, centerZ, radius, height, angle) -> (x, y, z, qx, qy, qz, qw)` — orbital pose facing the center.
- `Transform.worldToLocal(...)` / `Transform.localToWorld(...)` — pose-space conversions.
Nested `Transform.vec.*` namespace (component-wise vec3):
- `Transform.vec.add`, `sub`, `scale`, `dot`, `cross`, `length`, `normalize`.
Types:
- `Vec3 = { x: number, y: number, z: number }`
- `EntityRef = string | { entityId: string }`
## Usage
```luau
-- Look-at by coordinates or by target entity:
Transform.lookAt("cam", 0, 1, 0)
-- an entity target resolves to that entity's world position
local aimed, why = Transform.lookAt("cam", "box")
-- Orbit pose around a point:
local x, y, z, qx, qy, qz, qw = Transform.orbit(0, 1, 0, 5, 2, t)
entity.find("cam").localPosition = { x, y, z }
entity.find("cam").localRotation = { qx, qy, qz, qw }
-- Quaternion math:
local qx, qy, qz, qw = Transform.quatFromYawPitch(math.pi / 4, 0)
local sx, sy, sz, sw = Transform.slerp(0, 0, 0, 1, qx, qy, qz, qw, 0.5)
-- Component-wise vec3 helpers:
local nx, ny, nz = Transform.vec.normalize(1, 1, 0)
```
## Notes
- The `--!global Transform` directive promotes the module's typed
functions onto the runtime universe's globals bucket, so `Transform.*`
is available without any per-source `require`.
- Entity-aware functions (`lookAt`, `distanceBetween`,
`directionBetween`) report a missing entity or a missing transform in
their return value rather than raising: `lookAt` answers
`false, "unresolved"` / `"no-transform"` / `"incomplete-target"` /
`"degenerate"`, `distanceBetween` answers `nil`, and
`directionBetween` answers zeros.
- Quaternion APIs operate on raw `(qx, qy, qz, qw)` tuples for parity
with the entity proxy's `localRotation.get`/`set`. Use
`Transform.quatIdentity()` rather than hand-rolling `(0, 0, 0, 1)`.
- `Transform.slerp` flips the second quaternion if `dot < 0` to take
the shortest path, and falls back to lerp+normalize when the inputs
are within `dot > 0.9995` to avoid `1/0` near-parallel issues.
▲ 0↑ born
# Camera
Manages viewport priority, render-to-texture, and capture. State is stored in the native `Camera` ECS component; the Rust camera system handles render scheduling and render targets.
Public fields: `fov`, `near`, `far`, `priority`, `textureHandle` (the guid of the texture the camera renders into; empty = main viewport), `renderLayers` (which render layers this camera draws — a space-separated spec of names, e.g. `"all"`, `"all !ui"`, or `"default sky"`; `ui`/`sky`/`debug`/`EditorUI` are built-in layers), `postProcessing` (whether this camera runs the post-process chain), `debugChannel`, plus the behavior slot below.
Methods: `:lookAt(target)` (entity id string OR `{x, y, z}` table), `:render()`, `:capture()`, `:setTargetTexture(tex?)` (a `renderer.texture.create` handle to render into, or nil for the viewport).
```luau
entity(id).component.add("Camera", { fov = 90, priority = 10 })
entity(id).component.get("Camera"):capture()
```
The scene's play-mode camera is reached as `layers.active.camera`, a handle that
reads and writes the fields above on whichever entity currently carries them.
`layers.active.camera.entity` is the entity ref for that camera and
`layers.active.camera.entityId` its id string, so a script that needs to attach
something to the camera — an `AudioListener`, a child entity — goes through the
ref:
```luau
local cam = layers.active.camera
cam.fov = 70 -- the camera's settings
cam.entity.component.add("AudioListener") -- the entity carrying them
```
## How the camera moves: `behavior` and `follow`
A `Camera` does not move itself. `behavior` names a component that does, and setting it attaches that component to this entity. Clearing it detaches whatever was attached.
```luau
local cam = entity(id).component.get("Camera")
cam.behavior = asset.ref("@builtin::controller.orbital_follow", "component")
cam.follow = playerBody
```
The attached behavior is an ordinary component on the camera's entity, so it is tuned the way any component is: read it with `component.get` and set its fields there. A `component.add` of the same type configures the instance the slot attached instead of adding a second one: the values it passes are written onto that instance and its proxy is returned. That add is the form a scene `build.luau` tunes the behavior with, because its values are saved with the scene and the loaded Camera's behavior takes them back. A key the component reads only as it is created (one of its `initKeys`, a private field) refuses the add and names the key.
```luau
cam.behavior = asset.ref("@builtin::controller.third_person_follow", "component")
local rig = entity(id).component.get("third_person_follow")
rig.cameraDistance = 6
-- the same, as an add of the type the slot attached
entity(id).component.add("third_person_follow", { cameraDistance = 6 })
```
`follow` is the standard slot every shipped behavior reads. Set the follow target on the **Camera**, not on the behavior, so swapping behaviors keeps it. A behavior that finds its own `follow` field empty falls back to this one, which is what lets a rig keep tracking the player across a behavior swap.
`followResolves` answers whether that slot names an entity that is live — `true` while it names a live one or names nothing at all, `false` once the target is despawned or the id names no entity. A rig whose target does not resolve holds its last pose, and this is the field that tells it from a rig posed correctly on a subject that has not moved. `camera.get` carries the same value beside `follow`, and a write naming an id with no entity behind it draws a warning where it lands.
```luau
cam.followResolves -- false once the followed entity is gone
tools.use("camera", "get", id).followResolves -- the same answer off the tool
```
The shipped behaviors live under `@builtin::controller.*`: `orbital_follow`, `third_person_follow`, `first_person`, `free`, `orbit`, `chase`, `isometric`, `rts`, `birds_eye`, `side_scroller`, `cinematic`, `menu`.
## Writing your own
Any component can be a camera behavior. Write one that moves its own entity and attach it the same way:
```luau
cam.behavior = asset.ref("MyChaseCam", "component")
```
`follow` lives on the Camera, so a behavior gets no property notification of its own when the target changes. Declare `onFollowChanged(newFollow, oldFollow)` to be told the moment it does — the Camera calls it on the component it attached, which is what lets a rig re-pose on the new subject at once. A behavior that reads `Camera.follow` on its own schedule declares nothing and is attached the same way.
```luau
typed function public:onFollowChanged(newFollow: any, oldFollow: any)
-- pose this entity against the new target
end
```
To make it appear in the discovery catalog alongside the shipped ones, declare the `cameraBehavior` tag in the component's `.metadata`:
```json
{ "tags": ["cameraBehavior"] }
```
The tag governs **discovery**, not attachment. A tagged component is listed by `layers.active.camera.behaviors` and is what tooling offers when something asks "which camera behaviors exist"; an untagged component attaches just as well and simply stays out of that list. Tag the ones you want other people (and agents) to find.
```luau
for name, ref in pairs(layers.active.camera.behaviors) do
print(name, ref.identity)
end
```
## Texture colour space
`textureColorSpace = "display"` applies the display transform when rendering into a texture. `"linear"` writes scene-linear values instead. `postProcessing` independently controls the effects chain in either mode. Floating-point targets retain values above one; normalized targets clamp to their representable range. The main viewport uses display encoding.
▲ 0↑ born
# zinput
zinput is the engine's Luau-side input framework and the **only** public
Luau input API. It sits on top of the internal `__zero_input.*` FFI
(snapshot, events, frameId, pointer-lock, simulate\*) and builds the
control model above it in pure Luau: control assets grouped into maps, the
live set of activated maps and its per-frame dispatch, per-device-class
binding evaluation, the on-screen touch overlay, gesture recognisers, and
the tick coordinator that advances all of it.
The top-level module re-exports every submodule under a single table and
owns the tick coordinator (`Zin.tick`) plus the unified handle namespace
for `Zin.disconnect`.
## The control model
A control is a `<name>.inputBinding/` folder inside a `<name>.inputMap/`
folder. It carries a `label`, a `kind` (`button` / `axis1` / `axis2`), and
a binding for each of the three device classes — `kbm`, `gamepad`, `touch`.
A class set to `false` is a deliberate refusal.
Nothing is live until something activates a map. A world activates the map
it needs and subscribes to the controls it uses:
```luau
public = {
inputMap = Field.assetRef("inputMap", "@builtin::inputMaps.default", NoSync, "The controls this component reads."),
speed = Field.number(5, NoSync, "World units per second at full deflection."),
jumps = Field.number(0, NoSync, "How many times the jump control was pressed."),
}
local controls
function awake()
controls = public.inputMap:activate()
controls.move:onInput(function(v, dt, active)
if not active then return end
local p = public.entity.position
local step = public.speed * dt
public.entity.position = { p.x + v.x * step, p.y, p.z - v.y * step }
end)
controls.jump:onPressed(function() public.jumps += 1 end)
end
function onDestroy()
public.inputMap:deactivate(controls)
end
```
What `activate` returned is this holder's claim on the map, and handing it
back to `deactivate` disconnects the subscriptions made through it while
the map stays live for whoever else holds it. Every activation reads the
map's binding children again, so a control edited since it came up reaches
the running set and the holders already standing on it.
Several maps are live at once and compose: the player's surface is the
union of them, so picking up a gun adds Fire beside the movement stick and
dropping it takes away Fire alone. A map declares the `group` its controls
belong to and the groups it `suppresses` while live, which is how a car
stands walking down without owning the walk map. `Zin.scheme` holds the
live set and runs the dispatch.
`man topics/input` is the full walkthrough.
## Exports
Subsystems (re-exported from the corresponding submodule):
- `M.scheme` — the live set of activated maps and their per-frame dispatch.
- `M.bindings` — binding constructors, evaluators, and the legend formatter.
- `M.state` — per-frame snapshot reads plus held-time and synthetic repeat.
- `M.events` — frame-event readers and `on`/`off` edge subscriptions.
- `M.input` — `onBegan` / `onEnded` / `onChanged` / `onTextInput` listeners
and `lastInputType()`.
- `M.context` — the input context stack.
- `M.chords` — sequence and simultaneous recognisers.
- `M.gestures` — tap / double-tap / long-press / swipe / pinch / pan
recognisers.
- `M.touch` — per-finger contacts and `touch.*` listeners.
- `M.surface` — touch-vs-kbm device-class classification.
- `M.gamepad` — connected pads, family, and button legends.
- `M.virtual` — the per-tick virtual-control store on-screen controls write.
- `M.touchControls` — the on-screen touch overlay (stick, drag-look zone,
buttons) and the API that adds a control while a world runs.
- `M.emulation` — the map-driven key-emulation floor.
- `M.pointer` — pointer-lock mutations.
- `M.back`: Back, claims a world holds while Back means something to it,
and `press` to issue one. The engine routes each press to the topmost
dismissible overlay, else the most recent claim, else the platform's own
default (an Android app moves to the background).
- `M.test` — synchronous test-input helpers.
- `M.controllers` — `free` / `orbit` / `fps` controller factories.
- `M.profile` — binding profiles, saved as JSON and loadable from
`@builtin::profiles.<name>`.
- `M.rebind` — interactive binding-capture sessions.
- `M.conflicts` — the binding-collision reverse index.
- `M.autoTick` — the opt-in per-frame tick worker.
- `M.utils` — pure helpers.
- `M.actions` / `M.axes` / `M.map` — the name-registered action, axis and
map registry. A control asset replaced them; each carries its own
`--!deprecated` message naming the replacement.
Tick coordinator:
- `M.tick(dt: number?)` — advance every stateful subsystem.
- `M.lastTickAt() -> number` / `M.lastTickFrameId() -> number` — test/debug accessors.
- `M._resetTickGuard()` / `M._resetLiveArmed()` — test-only.
Handles:
- `M.disconnect(handle: number) -> boolean` — accepts any Zin handle (input listener OR action handler) and routes to the right `disconnect`.
Constants:
- `M.VERSION` — the library version string.
- `M.SPEC` — the VFS path of the architecture spec.
- `M.ROADMAP` — the VFS path of the roadmap document.
## Raw state
`Zin.state` and `Zin.events` are the snapshot and event layer that
bindings evaluate against — the layer the emulation floor, rebind capture,
and dev tooling operate on directly. Gameplay code subscribes to controls;
polling `Zin.state.keyDown` from a world makes that world keyboard-only and
draws the `engine-raw-key-poll` diagnostic at author time.
## Notes
- `Zin.tick(dt)` is the single hub that advances every stateful subsystem
each frame. Stateless features (state / events / utils / bindings /
context) work without ticking; the live binding dispatch, axes, chords,
subscriptions, held-time, repeat, and rebind are dormant until something
ticks.
- The first real input read arms the input system on its own: it starts
`Zin.autoTick`, so dispatch, the touch overlay and the emulation floor
advance with no host component and no explicit tick call. A host script
component can still call `Zin.tick(dt)` from its `update(dt)` hook, and
`Zin.autoTick.start()` remains available directly; both stay idempotent
alongside the self-arming path. `Zin.test` engagement suppresses the
arming so suites keep explicit control over tick cadence.
- Same-frame re-tick dedup: `__zero_input.events()` is non-draining, so
running the observe-and-dispatch pipeline twice in one engine frame would
double-fire subscribers. The frame-id guard in `M.tick` and the autoTick
worker keeps this from happening.
- The handle namespace is unified: every handle from `Zin.input.on*` and
`Zin.actions.bind` is drawn from a single counter, and `Zin.disconnect`
routes any of them to the correct `disconnect`. `Zin.input.disconnect`
and `Zin.actions.disconnect` are also wired to the unified dispatcher.
- Library users can either grab the whole table
(`require("@builtin::modules.zinput")`) or pull one submodule
(`require("@builtin::modules.zinput.state")`).
- `__zero_input` is an internal namespace — reachable from Luau but hidden
from `/docs/api/`; production game code goes through Zin.
▲ 0↑ born
# assetType (asset type)
The `assetType` is the **type of types** — the meta-type that every
`<typename>.assetType/` folder is an instance of, including itself. A
`<typename>.assetType/` folder declares a new asset type called
`<typename>`: its on-disk shape, its identity rule, and the structural
contract instances of the type must satisfy.
This type is self-hosting. `assetType.assetType/` conforms to its own
schema — a `type.yaml` plus a `README.md` — so the type system is
defined in terms of itself rather than a hidden engine special-case
(the same way a C compiler is written in C). Every asset in the engine,
including each `.assetType` definition, now resolves to a registered
assetType: a `.material` resolves to `material.assetType`, and
`material.assetType` resolves to `assetType.assetType`, which resolves
to itself.
## Why it exists
Assets used to be mapped to their type *implicitly*, by matching the
folder suffix against a name-keyed registry. That match carried no
stored link: nothing on a `Foo.material` recorded *which*
`material.assetType` it was written against, so two worlds shipping a
same-named type could silently disagree. Making `assetType` a real,
resolvable asset closes that gap — the link from an asset to its type is
now an explicit reference pinned in the asset's `.refs` sidecar
(`via: "asset_type"`), exactly like every other dependency.
## Where it lives
- Source: `/zero/source/.../<typename>.assetType/`
- Identity: `<typename>` (the `.assetType` suffix strips from the
identity; the folder retains the suffix on disk).
- Folder shape:
- `type.yaml` — the structural spec the validator reads. **Required.**
- `README.md` — type-level documentation. **Required.**
- `about.yaml` — three short plain-language texts saying what the type
is for (see "Say what your type is for" below). Every built-in type
ships one.
- `behavior.luau` — optional behavior/scaffolding module.
- `template/` — optional canonical placeholder body the templater
copies into a new asset of the type.
- `<name>.module/` — optional shared code the type ships to **every
instance** of it, conventionally `shared.module/` (see below).
## Shared code its instances reach (`asset.containing` + `.modules`)
A type ships code every instance of it uses by declaring the modules in
its own `behavior.luau`, as a map of tracked `require`s:
```luau
-- inside <typename>.assetType/behavior.luau
M.modules = { shared = require(".shared") } -- the sibling shared.module/
```
An instance reaches it with one location-independent line:
```luau
-- inside any foo.<typename>/init.luau
local api = asset.containing(__FILE__).modules.shared
```
`__FILE__` is the chunk's own VFS path; `asset.containing` resolves the
calling asset, and `.modules.<name>` follows the instance's pinned
`typeRef` (the type's **guid**, recorded in the instance's `.refs` as
`via = "asset_type"`) to the module its type declares. Because
resolution follows that link rather than a category name, the same line
in an instance of a different type resolves to that type's module, and
identically-named modules in two types never collide. `asset.typeRef(target)`
reads that guid for any target; `asset.resolve(asset.typeRef(target))`
gives the full `AssetRef<assetType>`. See `assetTypes/README.md`
§ "Shared code: type-owned modules" for the full mechanism.
## How to create one
Authoring a new asset type is just creating a `<typename>.assetType/`
folder under `/zero/source/`. The engine registers `<typename>` as a
category **the moment the folder is written** — no engine restart, no
Rust change, and it works for built-in (`@builtin/assetTypes/`) and
user-defined types identically. Once `<typename>` is registered,
`<name>.<typename>/` folders are recognised as assets of that type and
resolve their `asset_type` link back to this definition.
Creating a `<name>.<typename>/` folder *before* its
`<typename>.assetType/` exists fails fast: the suffix has no registered
type, so the folder can't be a valid asset. Author the type first.
## Say what your type is for (`about.yaml`)
Every type carries a small `about.yaml` beside its `type.yaml`, and the README
you write for the type documents how to author an asset of it. Both are
required, and both are meant to be written as you make the type, while you know
what it is for. `about.yaml` answers three questions in plain words, one key
each:
```yaml
intent: "Sets the typeface of the text in your game: UI, labels, signs and 3D lettering."
function: "A font, from a TTF, OTF or WOFF file, made available to all of Zero's text, including 3D text."
usage: "You choose it by name for your UI or your text, and the text appears in that typeface."
```
- **`intent`** is what the type is for in someone's game. Name the whole range
of things it covers, in the words a game maker would use for them.
- **`function`** is how it works today: what an asset of the type is made of and
what the engine does with it.
- **`usage`** is what a person or an agent does with one: how they pick it, place
it, call it, or hand it to something else.
A few habits keep it useful. Write about the type as a whole, so the text holds
for every asset of it, and leave out any one asset's name. Say what the type
does right now. Stay with words a game maker would say, and mention a file name
or a call only where a game maker would know it. The limits are in bytes:
`intent` 800, `function` 1500, `usage` 1200. Each is generous, and a few
sentences usually say it.
Why bother: agents working in a world read these three texts to learn what your
type is for, so they reach for it when it fits and use it the way you meant. People
searching find the type by what they want to make, and the three texts let them
tell at a glance whether it is the one they need.
`asset.create("assetType", name)` scaffolds the file with all three keys, and a
README whose first paragraph is a `[[describe]]` note. Each value starts with
`[[describe]]` followed by a note on what to write; replace the whole value with
your own words. A value or a README line that still starts with `[[describe]]`
counts as not written yet, which the push's check of each asset it carries against
its type reports, naming the file. A type you leave as it was is not asked, so
older types stand.
Many types at once, or one you would rather not write by hand: `services
describe` lists the types that lack these texts and what filling them costs, and
`{ mode = "all" }` writes them into the same files, where you edit them like
anything else you wrote.
Where the texts show up: `asset.inspect("<typename>", "assetType")` returns them
as `detail.about`, `assetTypeRef:getAbout()` returns them as a table with the
keys `intent`, `function` and `usage`, the type's `types/<typename>` guide page
ends with an "About this type" section holding them, and the Inspector's Type
section lists them at the top. The guide page is this README plus that section,
so a README that explains the type well and an `about.yaml` that says what it is
for read well together.
## Ask your assets to say what they are
A type can ask each of its assets to carry a description: a file, written by the
author or generated, that says what that asset is and what it is for. The people
and agents who find an asset read it to decide whether it fits, and the author
knows what it is for at the moment of making it.
**1. Declare the file with a `described` check.** This is the whole requirement:
```yaml
files:
required:
- path: "README.md" # any file name works
kind: "file"
content:
- { check: "described", message: "Say what this widget is for and where it goes." }
```
With that in place:
- An asset whose file is missing, empty, or still has a line starting with
`[[describe]]` does not meet the type's requirements. `asset.validate` names it,
`zm status` and `world.publishBlockers()` list it, and a push that carries it is
refused with `message`.
- `services describe` finds it (`mode = "find"` lists it and the price) and can
write the description for it (`mode = "all"`). It writes only this file.
For a YAML file that holds several texts, name the keys and their limits in bytes,
the way this type does for `about.yaml`:
```yaml
content:
- check: "described"
keys:
- { key: "intent", max_bytes: 800 }
- { key: "usage", max_bytes: 1200 }
message: "Write intent and usage."
```
`headings` names sections a Markdown file must have. `assetTypes/README.md` has the
full check.
**2. Optionally, steer what gets generated with a `describe:` block:**
```yaml
describe:
guidance: "Say what the widget shows, what input it reacts to, and where it fits in a UI."
examples:
- "<identity of an asset of this type whose description reads well>"
```
`guidance` says what a description of your type covers, and `examples` names assets
whose descriptions show the shape you want. Without the block, generation still
works from the general describing guide and the check's `message`.
An example is an asset of your type in the library whose description is a true,
written one, never a scaffold's placeholder, and never the asset being described.
When the library has none, leave `examples` empty rather than name one that is not.
A type whose assets the model cannot perceive (a sound it cannot hear, a motion it
cannot see) says so in `guidance`: the description comes only from what the asset's
own files state, such as its name and the `.metadata` where a generation service
records the prompt that made it, and when they state nothing the model answers
`cannot` with that reason. `services describe` then fails that one asset with the
reason and leaves its file as it was.
**3. Start the file unwritten in your template.** Put a heading and one line that
starts with `[[describe]]` and a short note on what to write, in
`template/<file>`, so a new asset starts unwritten rather than with text that only
looks written. Do not put example content in it: every new asset carries the
template verbatim, and the same text on many assets makes them impossible to tell
apart in search.
Types whose assets say what they are through their own content (a mesh, a texture,
a sound) leave this out: declare nothing and nothing is asked.
## The `behavior.luau` contract
`behavior.luau` is the type's code. It returns ONE table, and the keys below
are the ones the framework reads off it for EVERY type — the surface you get
by declaring them. Anything else on the table is your own: reachable by name
through `require("@builtin::assetTypes.assetType.shared.ref").loadTypeModule("<typename>")` for a
system that knows your type (`computeShader` publishes `dispatchKey` that
way), and never called by the framework.
```luau
local M = {}
M.ref = { ... } -- methods on every AssetRef of this type
M.modules = { ... } -- shared code the instances reach
M.global = {} -- reserved key; ship the empty table
function M.onCreate(name, opts) ... end
return M
```
### The tables
| Key | Shape | What the engine does with it |
|-----|-------|------------------------------|
| `M.ref` | `{ [name] = function(self, ...) }` | Every function becomes a method on every `AssetRef` of this type: `ref:name(...)`, with `self` the ref. This is how a type gives its instances an API. Two names in here are contracted — see below. |
| `M.modules` | `{ [name] = require(".sibling") }` | Shared code the type's instances reach through `asset.containing(__FILE__).modules.<name>`, resolved by the instance's pinned `typeRef` guid. See the section above. |
| `M.refShapes` | `{ [method] = "TypeName" }` | Declares the result type of a `M.ref` method so the LSP can check what a call site does with it. See the `M.refShapes` section below. |
| `M.events` | an events schema | The events an ASSET of this type fires, declared the way a component declares its own. Readers subscribe through `ref.events.<name>:connect(...)`; firing authority stays with the type. Keyed by the asset's guid, so every resolver of the same asset shares the signals and a re-resolved ref re-attaches to subscriptions already there. |
| `M.namePattern` | a Lua pattern string | The name shape `asset.create` enforces for instances of this type, replacing the default `^[A-Za-z][A-Za-z0-9_]*$`. |
| `M.global` | `{}` | Reserved. Ship the empty table. |
### The lifecycle hooks
Each is optional; a type that omits one costs nothing. The engine calls them:
| Hook | Signature | When it fires |
|------|-----------|---------------|
| `M.onCreate` | `(name, opts) -> { [filename] = contents }` | On `asset.create("<type>", name, opts)`. Returns the files that scaffold the new instance, as a map of relative path to contents; the framework writes them. The `opts` type annotation is the schema `asset.create` validates the caller's arguments against, so annotate it. |
| `M.onReplace` | `(dest, files) -> { [filename] = contents }` | On an `asset.create` that writes over an asset already at `dest`, after `onCreate`. Receives the files `onCreate` produced and returns the files to write, so a type that re-derives its content (a rig re-imported from its source file) can carry what an author added to the asset it replaces. Optional. |
| `M.onRegister` | `(self)` | Once per instance, the first time it registers: on `engine.onWorldLoaded` for instances already in the world, immediately on a live `asset.create`, and when an instance arrives after that sweep (installed, pulled, or synced from a peer). Guarded by the instance's path, so a double trigger never double-registers. An instance that leaves the runtime releases the guard, so one arriving at the same path again registers. This is what makes "write an asset into the world and it takes effect live" work for content that registers into a runtime registry. The `@builtin` library is excluded from the sweep. |
| `M.onChange` | `(ref, change)` | On every VFS write to a file INSIDE one of this type's instances. `change` is `{ path, asset, type, kind, origin }`: `kind` is `"edited"` or `"seeded"`, `origin` is `"local"` or `"remote"` (an importer runs on the originator only). **Filter on `change.path`**: the hook fires for any file under the folder, so act on the one you care about. It runs as its own task and may wait on what it reads: a `vfs.read` of bytes only the blob store holds (a binary file on the web build) fetches them. The writes to one asset reach the hook in the order they were made, each once the hook before it has finished. A re-entrancy guard suppresses writes back into the same asset routed inline from the hook, and a write the hook makes is routed on a later frame like any other, so the hook must be convergent on its own: diff the meaningful state and short-circuit while your own regeneration is in flight. |
| `M.onDelete` | `(ref)` | When an instance of this type leaves the runtime: it is deleted, or the engine swaps away from the world binding that held it. Its files are gone from `/zero/source` by then. A removal routed while the instance's `onChange` is waiting reaches `onDelete` once that hook, and every write queued behind it, has finished. On a swap the instance still exists in the world it belongs to, and a VFS write the hook makes reaches the world now bound. |
| `M.validate` | `(assetRef) -> { { code, message, severity? } }` | On `asset.validate`, after the structural `type.yaml` check, for the type's own SEMANTIC validation. `severity` defaults to `"error"`; error-severity problems flip `ok` to false, warnings do not. A hook that raises or returns a non-table is itself reported as a `validate.hook_failed` error. `world.push` runs this per user asset, so declaring it enforces your type's rules at publish time with no further wiring. |
### The two contracted `M.ref` names
Most `M.ref` methods are your type's own surface: name them what you like,
return what you like. Two are read by the engine and mean the same thing for
every type, so their shape is fixed:
- **`instantiate(self, target?, opts?) -> (root, idMap)`** — makes an instance
part of the scene. Defining it is the whole opt-in: `ref:canInstantiate()`
is true exactly when it exists. Its **return is a contract** — see the next
section.
- **`inspect(self) -> detail`** — the type-specific half of `asset.inspect`.
See its section below.
### Names a type cannot shadow
Some keys resolve on every `AssetRef` before per-type dispatch, so an `M.ref`
entry of the same name is never reached: `canInstantiate`, `getSource` /
`getBytes` / `getText`, `exists`, `deps`, `meta`, `runtime`, `events`,
`modules`, `typeRef`, and the residency flags `has_backing_asset`,
`has_runtime_changes`, `cpu_resident`, `gpu_resident`. These are the
behaviours every asset must expose identically, which is why they win.
### Reloading
A `behavior.luau` edit ripples to existing refs with no restart: dispatch
reads `mod.ref` fresh each time and `require`'s cache is re-run in place. A
type whose folder appears at runtime is picked up on the next dispatch —
negative results are not cached either.
## The names your type's assets hold (`references:`)
An asset that names another asset by a string depends on it: the named asset
travels with it into a pack or a pull, and a name nothing answers to is an
unresolved dependency `worldValidation` reports and the push gate refuses. The
engine reads `require(...)` and the asset lookups on its own; a name your type's
format or API carries anywhere else is one you declare, in `type.yaml`:
```yaml
references:
# A top-level key of this type's own files that holds a name (or a table of them).
keys:
- { key: "shader", type: "shader" }
# A call's argument, counting from 1, wherever the call is written.
args:
- { call: "g:node", position: 2, type: "procNode" }
# A field of the options table a call takes.
fields:
- { call: "fx.beam", field: "material", type: "material" }
```
`type` is the category the name resolves in, one of `asset.categories()`. An
argument declared once per category, at the same `call` and `position`, takes
the name from whichever category answers. A key or a field holds one category:
declared again with another `type`, it takes the later one. The block is
declared as the type registers, when the library or the world holding it is
laid into the VFS, so every reference table reads it whatever script has or has
not run. `asset.declareReferenceKey`, `asset.declareReferenceArg` and
`asset.declareReferenceField` declare the same things from a script, for a
surface that is no type's.
## What search does with your type (`indexing:`)
A type declares what search embeds for its instances. **This is not optional
and there is no useful default**: ZeroMind runs your declaration and adds
nothing of its own, so anything you do not point at is absent from the index —
silently, and for every instance of the type forever. Twenty types once shipped
with no `indexing:` block and every instance of them was unfindable.
A type whose instances are never searchable (a run record, a log) says so with
`indexing: none`; every other type declares a recipe.
A type without an `about.yaml` beside its `type.yaml` refuses every push that
carries it, whether or not the push edited the type. Texts in it that are not
written yet follow the rule every `described` file follows: they refuse the
push that edits, stages or commits the type.
Two words carry the whole thing, and they are the same two the search tool
exposes:
- **`identity`** — what an instance IS. For anything you can look at, that is
the picture (`content:` + `modality: image`, matched directly by a text
query). For everything else it is the authored text that says what it is.
- **`capability`** — what it DOES and how it is made. Code, settings, the
model-written summary of them.
A type with no behaviour has no `capability` entry. A type with nothing to look
at has no image. Leaving a slot empty is a statement; filling it with whatever
happens to be lying around is not.
The one you have to decide when authoring a type is: *for an instance of this,
what is the thing a person would recognise it by, and what is the thing it
does?* A texture answers "the image" and "its compression settings". A module
answers "its README" and "its code". Write those two answers into `indexing:`
and the rest follows.
Three specifics worth knowing before you write one:
- **`derive` is instructed by this type's own `README.md`.** A model reads an
instance's source and writes a description; what it embeds is the
description, not the source. It follows your README to know what it is
looking at, so a type whose README says what its instances are gets good
derivations for free. There is no prompt to name.
- **`derive` loses detail.** It keeps the main technique and drops secondary
ones. If the source is code you want searchable by its own vocabulary,
declare the same files a second time as `capability` with
`extractor: verbatim`. Two entries, same role, different failure modes.
- **Never `source: { field: name }`.** A filename is one or two words with no
usable embedding, and a corpus indexed that way answers "language runtime"
with `say_runtime_2.soundClip`.
`facets:` is the second stage: a `file:` embedded whole (`.metadata`, so keys
nobody declared still get indexed) plus computed keys that state a value for
every instance including `false` — the raw file can imply "not rigged" and can
never say it.
The full schema, every extractor and the facet sources are in
[`assetTypes/README.md`](../README.md); the scaffolded block with inline
guidance is in [`template/type.yaml`](template/type.yaml).
## A container whose contents work together (`system: true`)
A type that is a container can say its contents are one working whole by
declaring `system: true` at the top level of its `type.yaml`. `package` declares
it: the components, modules, scenes and tools a package ships are parts of one
system. The declaration is plain data, read from the decoded `type.yaml`
(`require("@builtin::assetTypes.assetType.shared.declaration").of("package").system`),
and a type that leaves it out is an ordinary type.
## What your type looks like (`preview:`)
A type declares how its instances are pictured, and the engine makes the
picture when something needs it: staging an instance whose `preview.png` is
missing or pictures content it no longer holds queues a render, a view that
shows the instance asks for one, and `ref:preview()` renders one on demand. An
edit renders nothing on its own. Each `preview.png` records the content it
pictured, which is how a stale one is told from a current one. The preview studio owns the light, the
backdrop, the framing and the camera, and nothing in the world reaches it, so
an instance pictures the same in every world. Declare one of four recipes:
| `kind` | The picture is | Your type provides |
|---|---|---|
| `instantiate` | the asset stood in the studio through its own `instantiate` | `ref.instantiate` |
| `image` | a file the instance holds, fitted to the frame, nothing rendered | `source.files`, the candidate files in order |
| `surface` | the asset painted on a builtin mesh | `mesh`, and `ref.previewMaterial(self) -> { material }` |
| `custom` | whatever `ref.preview(self, opts)` returns | `ref.preview` |
```yaml
preview:
kind: surface
mesh: sphere
```
A scene-instantiable type that declares nothing still answers `ref:preview()`
through its `instantiate`, but persists no picture: the declaration is what
makes the engine keep one. List `preview.png` among the type's files so an
instance may hold it.
The picture is findable only when `indexing.content` names it. The two are
separate statements, and neither is derived from the other:
```yaml
indexing:
content:
- role: identity
modality: image
source: { file: "preview.png" }
```
`@builtin::assetTypes.assetType.shared.previewRecipe` reads the declaration;
the scaffolded block with inline guidance is in
[`template/type.yaml`](template/type.yaml).
## Typing a result from the instance (`M.refShapes`)
Every method on `M.ref` is checked against the type its `--!return` names,
and every asset of the type gets the same one. That is right for most
methods and wrong for the ones whose result is shaped by the ASSET: a
method answering one entry per child folder, per row of a config, per
binding an input map declares. The widest true annotation for those is
`{ [string]: Thing }`, and an indexer accepts every key — so a caller's
typo reads as valid and nothing reports.
`M.refShapes` lets the type state the result per instance. Each entry is
`function(self) -> (typeExpression, source?)`: a Luau type expression for
THIS asset, and the module whose type vocabulary the expression uses.
Read the asset; never run it — stating a type must not take effect.
```lua
-- inputMap.assetType/behavior.luau — the shipped example.
-- `activate()` hands back one handle per control the map declares.
M.refShapes = {
activate = function(self): (string, string)
local names = {}
for _, control in ipairs(M.ref.controls(self)) do
table.insert(names, control.name .. ": Handle")
end
if #names == 0 then return "", "" end
return "{ " .. table.concat(names, ", ") .. " }",
"@builtin::modules.zinput.scheme"
end,
}
```
With it, `map.jump:onPressed(fn)` resolves and `map.noexisting` is
reported with the map's real controls. Without it, both pass silently.
### What the call site has to say
A per-instance type is matched by the asset's IDENTITY, so it applies only
where the reference the method is called on says WHICH asset. Two spellings
do:
```lua
-- a component field, whose declared default names the asset
public = { map = Field.assetRef("inputMap", "@builtin::inputMaps.default", Sync) }
local controls = public.map:activate() -- typed for THAT map
-- an annotation, naming category and identity
local m: AssetRef<"inputMap", "@builtin::inputMaps.default">
```
`asset.resolve("<identity>", "<category>")` carries the CATEGORY, so the
methods the category defines are checked on the result — but not which
asset it found, so a per-instance result keeps the category's declared
return. A reference that names no asset (`asset.resolve(someVariable)`, a
value passed in as a parameter) carries neither, and calls on it are
unchecked. That is the same rule everywhere: the checker states what the
code states, and a name computed at runtime states nothing.
### The result is a value, not a binding
The type belongs to the expression, so it travels the way any inferred type
travels. Indexing the call's result is checked; stashing it in a module
local and indexing it from another function is not, because the local's
declared type is what carries across — and `any` (or no annotation) carries
nothing:
```lua
-- checked: `d.greting` is reported
function awake()
local d = public.dialogue:lines()
d.greeting:say()
end
-- NOT checked: `lines` is a module local typed `any`
local lines: any = nil
function awake() lines = public.dialogue:lines() end
function start() lines.greting:say() end
```
Bind what you need at the call site and the names stay checked in both
places — the asset-derived type at the boundary, ordinary scoping after it:
```lua
local lineGreeting = nil
function awake()
local d = public.dialogue:lines()
lineGreeting = d.greeting -- `d.greting` is reported here
end
function start() lineGreeting:say() end
```
### When nothing is reported and you expected something
From a call site, a type that is correct and a type that was never published
look the same: no diagnostic either way.
`require("@builtin::assetTypes.assetType.shared.refShapes").published()` answers which it
is. It returns two maps — the category surfaces, and the per-asset results
keyed by identity and then by method:
```lua
local shapes = require("@builtin::assetTypes.assetType.shared.refShapes").published()
shapes.categories.dialogue
--> "{ lines: () -> any, lineNames: () -> { string } }"
shapes.returns.Shopkeeper.lines
--> "{ browsing: Line, farewell: Line, greeting: Line, wares: Line }"
```
An identity absent from `returns` was never published for, which is a
different thing from published-and-correct — and the reason to look here
rather than at the call site.
The answers are recomputed when an instance is written, so a control added
to a map reaches the checker with no restart. Only types that declare
`refShapes` are read per instance, and at most 64 assets of one type are —
past that the type keeps its declared return and the engine log names what
was dropped.
## The instantiate hook (`M.ref.instantiate`) — a contracted return
A type opts into becoming part of the scene by defining `instantiate` on its
`ref` table. That is the whole opt-in: `ref:canInstantiate()` is true exactly
when the hook exists, so consumers offer a scene path — an `Asset.source`
field, a viewport drop, a tool argument — by CAPABILITY rather than by a list
of type names.
Unlike `inspect`, this hook's **return is a contract**. A caller writes one
piece of code against every instantiable type, so what comes back cannot vary
by type:
```lua
-- behavior.luau
local Instantiable = require("@builtin::assetTypes.assetType.shared.instantiable")
local M = {}
M.ref = {
instantiate = function(self, target, opts)
local root = Instantiable.root(self, target, opts) -- IN: the base opts
-- ... compose whatever this type is, under `root`, NOW ...
return Instantiable.result(self, root, idMap) -- OUT: the contract
end,
}
return M
```
**IN.** `target` is an owning entity ref: the instance lands under (or, for a
hierarchy type, onto) that owner. With no target the type spawns a fresh root.
`position`, `rotation`, `scale`, `name` and `temporary` mean the same for every
type — `Instantiable.root` applies them to a root you mint, `Instantiable.place`
to one you adopt, so you never re-read the spec. Honour more opts of your own if
your type needs them, and document them in the hook's `--!arg` docs.
**OUT.** Return `(root, idMap)` through `Instantiable.result`:
- **`root`** — the composed root, as an `EntityRef`. Composition is
**synchronous**: everything your type builds is live when you return, so the
caller can parent to it and read its components in the same statement. Do not
defer the work to a component's `awake` and return an empty shell — a root
that is not live is refused.
- **`idMap`** — the `originalId -> runtimeId` map naming what you spawned, or
nil for a type with no addressable children (`result` normalises it to `{}`).
**A caller never receives nil.** A component that re-composes your asset on
every load keeps this map and passes it back in, which is how a cross-entity
reference into the composition survives a reload.
`AssetRef` runs every `instantiate` through `result` on the way out whether or
not your type called it, so returning something else fails at your own call
rather than handing a caller a nil root. Calling it yourself is still how you
say what you return, and running it twice changes nothing.
`@builtin::assetTypes.assetType.shared.instantiable`'s README is the full reference for both halves.
## The inspect hook (`M.ref.inspect`)
`asset.inspect(ref)` resolves `ref`, builds a common envelope shared by
every asset (`identity`, `name`, `guid`, `source`, `typeName`,
`typeDefinitionPath`, `scope`, `origin`, `description`, `tags`), then
calls the resolved type's own inspect hook — `M.ref.inspect(self)` on
`behavior.luau` — for the type-specific `detail`. The hook returns
*only* `detail`; the framework fills in everything else:
```lua
-- behavior.luau
local M = {}
M.ref = {
inspect = function(self)
-- self.path is the asset's own folder. Parse the asset's OWN
-- files — source text, a native payload header, its `.metadata`
-- — never runtime state (a live component instance, a GPU
-- upload, a compiled schema): inspect must work on an asset that
-- hasn't been compiled, uploaded, or registered yet.
return {
-- type-specific fields, whatever this type wants to surface
}
end,
}
return M
```
A type that omits `M.ref.inspect` yields the generic record: the
envelope alone, `detail = nil`. That's a valid, working state — not an
error — but it means agents calling `asset.inspect` /
`tools.use("assets","describe", ...)` on an instance of the type see
only identity and scope, none of what makes an instance of it
meaningful. Declaring the hook is what makes a type's instances
inspectable for what they actually are.
A hook that raises leaves `detail = nil` and sets `record.warning` to
the error text — `asset.inspect` itself never raises for a resolved
ref.
## Discovery
- `asset.list("assetType")` — every registered asset type.
- `asset.inspect("<typename>")` — the type's identity, source path, and
this README, plus its `about.yaml` texts as `detail.about`.
- `asset.resolve("<typename>", "assetType")` — the `<typename>.assetType`
asset itself (used by the validator to find the type's `type.yaml`).
## Related
- `assetTypes/README.md` — the full `type.yaml` schema and validator
rules.
- `@builtin::assetTypes.assetType.shared.instantiable` — the instantiation contract's shared
implementation, both halves.
- Every other `*.assetType/` here — the concrete types built on this
meta-type.
## The Inspector a type ships
Every type names the file its Inspector sections come from with `inspector: { type: "inspector.luau" }` in its type.yaml. `asset.create("assetType", name)` scaffolds the block and an `inspector.luau` whose Contents section lists an asset's files, built from `ctx.parts`. `asset.validate` on a type that names none reports `assetType.inspector_required` (an error for a `@builtin` type the engine's library authors; a warning for a world's own, and for one the library carries by reference, which the world that published it answers for), and one whose file does not load `assetType.inspector_invalid`.
## In the Inspector
Type: what the type.yaml declares (suffix, container, primary files, the settings and inspector blocks), whether the type ships a behavior, how many instances it has, and **Open** for its files. Schema: the settings every instance carries, as read-only typed controls at their defaults (a type whose schema is per instance says where it is declared). Instances: a link to each of the first 20 assets of the type, and how many there are when there are more.
▲ 0↑ born
# interact
Use whatever is in front of the player.
▲ 0↑ born
# lookDrag
Held while the mouse is meant to steer the camera.
▲ 0↑ born
# pointerLock
Releases the captured cursor so the pointer can leave the game.
▲ 0↑ born
# Zoom
Pulls the camera in and pushes it out.
| Device | Control |
|---|---|
| Keyboard + mouse | Scroll wheel |
| Gamepad | Shoulder buttons — right pulls in, left pushes out |
| Touch | Pinch |
The control is counted in wheel notches, because that is the unit a
player's scroll arrives in. A held shoulder is worth six notches a second
and a pinch is worth one notch per fifty pixels, so a camera applying one
`zoomSpeed` moves the same amount per gesture on every device.
▲ 0↑ born
# inputMap assetType
A control scheme, expressed as an asset. A `<name>.inputMap/` folder whose
`init.luau` returns the map record, and whose **controls are the
`<name>.inputBinding/` child folders beside it** — the same containment a
`.toolbox` has with its `.tool` children. Containment records the
reference, so a scene carrying its map carries every control it declares.
```
racer.inputMap/
init.luau -- what the map is, and how it composes
boost.inputBinding/
init.luau
steer.inputBinding/
init.luau
```
```luau
-- racer.inputMap/init.luau
return {
name = "racer",
description = "Throttle, steering and boost.",
-- The group these controls belong to, and the groups this map stands
-- down while it is live. Declaring neither composes with everything.
group = "vehicle",
suppresses = { "player" },
}
```
Each control carries `kbm`, `gamepad` and `touch`; the `inputBinding`
assetType covers the record shape.
## Reading it
A controller activates the map it needs and subscribes to the controls it
drives. Nothing is live until something asks for it.
```luau
public = {
inputMap = Field.assetRef("inputMap", "@builtin::inputMaps.default", NoSync, "The controls this component reads."),
speed = Field.number(5, NoSync, "World units per second at full deflection."),
jumps = Field.number(0, NoSync, "How many times the jump control was pressed."),
}
local controls
function awake()
controls = public.inputMap:activate()
controls.move:onInput(function(v, dt, active)
if not active then return end
local p = public.entity.position
local step = public.speed * dt
public.entity.position = { p.x + v.x * step, p.y, p.z - v.y * step }
end)
controls.jump:onPressed(function() public.jumps += 1 end)
end
function onDestroy()
public.inputMap:deactivate(controls)
end
```
What `activate` returned is this holder's **claim** on the map. Keep it and
hand it back: releasing the claim disconnects the subscriptions made
through it, and the map stays live for whoever else holds it.
A control the map does not declare reads as `nil`, so a typo raises at the
subscribe call. A controller written against more than one map tests for
an optional control first — `if controls.crouch then controls.crouch:onInput(...) end`.
Several maps can be live at once, and the player's surface is the union of
them. `group` / `suppresses` are how one map stands another down — a car
takes the player over by naming the `player` group, and walking resumes the
moment the car releases. `Zin.scheme.live()` reports each live map's
`group`, `suppresses` and `suppressedBy`, and `heldBy` — who opened each
activation still standing on it, so a control that goes quiet under a
suppression leads to the activation doing it rather than to the map.
## Whose keys a map reads
A key belongs to the surface it was pressed on. In the editor, where the
scene shares the window with panels, the scene holds the keys pressed while
it was the active input context — the last click landed on the viewport, or
play just started. A key pressed after a click on a panel is the editor's,
and a game's controls never see it. A map reads the scene's keys unless it
declares otherwise:
```luau
return {
label = "Editor",
group = "editor",
surface = "editor", -- every key no focused widget took
}
```
`surface = "editor"` is for controls that belong to the editor around the
scene — its hotkeys, its viewport camera — and answer wherever the author
last clicked. Pads and touch belong to no panel and read the same on either
surface. `Zin.scheme.live()` reports each map's `surface`.
## Ref methods
- `:activate(label?)` — load every `<name>.inputBinding/` child, validate
them, add them to the live binding set, and return the handles keyed by
control name. Every fault across every child is reported in one error.
Activating a map already live adds a holder, so two components sharing
one map read one set of controls — each through its own handles, which
are the claim it releases by. Every activation reads the children again,
so a binding added, edited or removed since the map came up reaches the
running set here and reaches the holders already standing on it. `label`
names this activation in `Zin.scheme.live()`.
- `:deactivate(claim)` — release one holder's claim, disconnecting every
subscription that claim made. The map stays live while another holder
remains; the last one out takes the controls out of the live set. Name
no claim and the caller's own most recent one goes.
- `:controls()` — `{ name, label, kind, classes, problems }` per child,
read without activating anything, so an authoring tool can show a map's
whole surface and everything wrong with it before it goes live.
- `:record()` — the raw record its `init.luau` returns.
- `:effective()` — the materialized effective map, without activating it.
- `:bindingsFor(name, class)` — the bindings a named entry has for one
device class in this map's effective form.
## Writing one
The `inputAuthor` toolbox writes a map and its controls together, filling
in canonical defaults for a control whose name it recognises:
```luau
tools.use("inputAuthor", "map", "racer", { "throttle", "steer", "boost" },
{ group = "vehicle", suppresses = { "player" } })
tools.use("inputAuthor", "check", "/zero/source/inputMaps/racer.inputMap")
```
`asset.create("inputMap", name, { record = ... })` bakes a record into both
shapes a map is read in — `init.luau` beside one `<name>.inputBinding/`
child per entry, each carrying all three device classes, a class the record
had nothing for written as `false` with the reason beside it. That is the
hook `Zin.map.bake(name)` drives to turn the active effective map into an
editable asset.
The engine's built-in schemes live at `@builtin::inputMaps.default`,
`.editor`, `.editorMeta`, `.vehicle` and `.flight`.
## In the Inspector
Controls: whether this map is the one taking input now, how many controls it declares, and each control's name, label, kind, device classes and problem count.
▲ 0↑ born
# Module (asset type)
A module is a reusable, stateless (or globally-stateful) Luau library
that other code pulls in with `require()`. Modules are the unit of
factored-out logic in a world: helpers, math libraries, format
parsers, registries, shared algorithms.
## When to use one
- You have logic you want to share across multiple components,
services, scenes, or tools.
- You have a registry, lookup table, or shared cache that callers all
read from / write to.
- You want a stable API surface (`M.fn`) other code can depend on.
If the logic is bound to one entity, use a `.component`. If you want a
named UI of fields rather than functions, use a `.preset`.
## Where it lives
- Source: `/zero/source/.../<name>.module/`
- Identity: the source path with `/` written as `.` and each segment's
type suffix dropped — `/zero/source/demo/beats.module` is
`demo.beats`, and `/zero/source/kit.package/beats.module` is
`kit.beats`, the container's name kept and its `.package` suffix
gone. `asset.create` returns this string, `asset.resolve(...).identity`
reads it back, and the `require` forms below write it as
`<identity>`.
- Folder shape:
- `init.luau` (or `init.lua`) — module body. **Required.** Returns
a table (conventionally named `M`).
- `README.md` — instance-level documentation. **Required.**
- `.metadata` — agent-editable tags + free-form fields. **Required.**
## How to create one
```luau
asset.create("module", "<name>")
-- Creates: /zero/source/<name>.module/
-- init.luau (canonical `local M = {} … return M`)
-- README.md (instance README template)
-- `folder` places it in a subfolder of /source, and that subfolder
-- leads the identity: `{ folder = "lib" }` produces `lib.<name>`.
-- `into` authors it inside a resolved container (a package, a toolbox),
-- whose own identity leads the same way:
asset.create("module", "<name>", { folder = "lib" })
asset.create("module", "<name>", { into = asset.resolve("myPkg.package") })
```
## How it operates
1. **Registration.** Writing `init.luau` into a `.module/` folder
indexes the asset and registers the module path with the resolver.
2. **Loading.** The first `require("<identity>")` runs
the file's body and caches the returned table. Subsequent requires
from anywhere return the **same table** — this is the
shared-state lever for "module-local" registries.
3. **Hot reload.** Editing the file re-runs the module body and folds
what it returns into the table already loaded, so that table keeps
its identity: a caller that captured it with `require` reads the new
source's functions and values through the reference it already
holds, and a later `require` returns that same table. A key the new
source drops goes away; a key something set at runtime stays. The
body's own `local`s start again from their initial values, so state
that must outlive an edit lives in `modules.state()`
(`guides { path: "core/scripting-and-tasks" }`).
4. **Identity resolution.** A module is reached by its `<identity>`,
and where the caller lives decides which spelling of it resolves.
For a module in a **world**, from a caller in that same world —
another module, a component, a scene entrypoint, or an `execute`
chunk:
- `require("<identity>")` — the identity on its own, resolved
against the caller's own root. It carries every folder segment,
so a module created with `{ folder = "demo" }` is
`require("demo.beats")`.
- `require("@root::<identity>")` — the same root-relative
resolution, written out.
- `require(".sibling")` — a module in the same folder, by its bare
name; `..name` steps up one folder, `...name` two.
Logs, stack traces and hot-reload notices name that same module
`@local.source.<identity>` — its key under the world source root.
The `<identity>` tail of that key is the form above, so a trace
reading `@local.source.demo.beats` is `require("demo.beats")`.
For a module in a **library** — content under
`/zero/source/libs/@<lib>/` — `@<lib>::` addresses that library's
root from anywhere: `require("@builtin::modules.transform")`.
Mounting a world as a library moves its files under such a root and
flips the caller root to `@<lib>::`, which is what keeps the
root-relative forms above resolving across the move.
## Discovery
- `asset.list("module")` — every registered module.
- `asset.inspect("<name>")` — public functions, source path, this
type README.
- `ls /zero/source/<name>.module` lists the files the folder holds.
## Authoring conventions
- Return a single `M` table from `init.luau`. Top-level statements
with side effects run on first require — useful for one-time
initialization, dangerous if they touch the engine before it's
ready.
- Write exported functions as `typed function`, not `function`: the
argument types are enforced at the call and the checker knows the
signature, so a caller's mistake is reported where they made it.
- Annotate exported functions with `--!desc` / `--!arg` / `--!return`
/ `--!example` so the LSP, `tools.list`, and `asset.inspect`
surface them. A function with no `--!desc` is reachable only by
someone already reading this file.
- Declare a VALUE with `Field.<kind>(default, mode, description)`, and
a table whose members are reached through a metatable with
`--!members <TypeName>` — the latter gives the surface its accepted
member set, its type, and its documentation from one table. See
`guides { path: "core/authoring" }` for all four rules and
`modules/api/engine/entity.module/members.module` for a worked
member table.
- Keep module state in module-local upvalues or in `modules.state()`.
Globals leak across reloads. Module-locals start again from their
initial values with each hot reload; the table `modules.state()`
returns is the same table on both sides of every reload.
- Prefer focused modules over kitchen-sink modules. If two halves of a
module have no shared state, split them.
## Common pitfalls
- **Cyclic requires.** A `require` chain that loops will return the
partial table (the half built before the cycle was detected).
Design for one-way dependencies.
- **Engine-time side effects.** Don't `entity.spawn` at module
top-level — the engine may not be ready. Expose an `M.init` and
call it from a scene entrypoint.
- **Hot-reload + module-local cache.** A module that caches
expensive computation in upvalues loses that cache on reload —
fine for dev, but be aware in performance work.
- **`init.lua` vs `init.luau`.** Either works, `.luau` is canonical.
- **Writing one while play runs.** A `/source` write made while play is
running lands on the play shadow, and a guarded play-exit discards it
unless it is kept. One `.module` write shadows `init.luau`, the
`README.md` and the `.metadata` together.
`vfs.write(path, bytes, { durable = true })` skips the shadow, and
`vfs.promotePlayShadow` keeps what is already on it — the `core/vfs`
guide has the model and what each route costs.
## Related types
- `.component` — for entity-bound state + lifecycle hooks.
- `.service` — generates content you don't have yet (a mesh, sound, texture, …) via a metered provider.
- `.tool` — for a single agent-callable function with a YAML schema.
- `.package` — to group several modules + components + scenes into
one shippable folder.
## In the Inspector
Exports: what the module exports (name, kind, signature), parsed from its source without running it, with **Check** (the LSP's diagnostics for its entry file) and **Open**.
▲ 0↑ born
# actions
A name-registered action registry over `Zin.bindings` + `Zin.context`.
A name maps to a list of binding descriptors and one declared context;
polling queries (`held`, `pressed`, `released`, `value`, `heldTime`,
`repeated`) evaluate those bindings against the live snapshot, and the
handler surface (`bind` / `onPressed` / `onReleased` / `onChanged` /
`onHeld`) fires the same state from inside `Zin.tick`, after axes and
chords advance.
A control asset replaced this. A `<name>.inputBinding/` folder inside an
`.inputMap/` carries the label, the kind, and a binding for
keyboard-and-mouse, gamepad and touch, and a world activates the map and
subscribes to the controls it uses:
```luau
public = {
inputMap = Field.assetRef("inputMap", "@builtin::inputMaps.default", NoSync, "The controls this component reads."),
speed = Field.number(5, NoSync, "World units per second at full deflection."),
jumps = Field.number(0, NoSync, "How many times the jump control was pressed."),
}
local controls
function awake()
controls = public.inputMap:activate()
controls.move:onInput(function(v, dt, active)
if not active then return end
local p = public.entity.position
local step = public.speed * dt
public.entity.position = { p.x + v.x * step, p.y, p.z - v.y * step }
end)
controls.jump:onPressed(function() public.jumps += 1 end)
end
function onDestroy()
public.inputMap:deactivate(controls)
end
```
`Zin.map.bake(name)` writes the currently active map out as an `.inputMap`
asset. `man topics/input` covers the control model.
## Exports
Registry:
- `M.define(spec: ActionSpec)` — define / replace actions.
- `M.remove(name: string)` — remove one action (also tears down handlers).
- `M.clear()` — wipe every action + handler.
- `M.has(name: string) -> boolean`
- `M.names() -> { string }`
- `M.get(name: string) -> ActionEntry?` — the registry record behind a name.
- `M.active(name: string) -> boolean` — true iff the action's context matches the top of the stack.
Polling queries (gated by context):
- `M.held(name) / pressed(name) / released(name) -> boolean`
- `M.value(name) -> number | Vec2 | 0/1`
- `M.heldTime(name) -> number?`
- `M.repeated(name, opts?) -> boolean`
Event-driven handlers:
- `M.bind(name, fn, opts?) -> ActionHandle?` — register a handler.
- `M.disconnect(handle: ActionHandle) -> boolean`
- `M.onPressed / onReleased / onChanged / onHeld(name, fn, opts?) -> ActionHandle?`
- `M.handlerCount(name) -> number`
Internal hooks (wired by `zinput/init.luau`):
- `M._setAllocator(fn: () -> number)` — shared id allocator.
- `M._setEnsureBindingsFn(fn)` / `M._setEnsureLiveFn(fn)` — the cold-read hooks.
- `M._owns(handle: number) -> boolean`
- `M._dispatchHandlers(firstTickThisFrame: boolean?)` — called by `Zin.tick`.
- `M._clearHandlers()` — test isolation.
Types:
- `ActionEntry = { context: string, bindings: { any } }`
- `ActionSpec = { [string]: any }` — define-spec entry shapes.
- `ActionState = "Begin" | "Change" | "End" | "Held"`
- `BindOpts = { priority: number?, fire: { ActionState }?, once: boolean? }`
- `ActionHandle = number`
## Notes
- Define-spec shorthand:
- `binding` — single binding under the default context.
- `{ binding1, binding2 }` — multiple bindings under the default context.
- `{ context = "...", binding = ... }` / `{ context, bindings = {...} }` — explicit context.
- Context gating is strict: the action's context string must equal
`Zin.context.current()`. There is no inheritance up the stack.
- Handlers run from `Zin.tick` after axes/chords advance. With no tick
host (or `Zin.autoTick.start()`), handlers never fire.
- Returning `"sink"` from a handler stops further (lower-priority)
handlers on the same action this tick. Anything else continues.
- A handler also ends with the context that bound it: one a component
binds ends when that component instance goes (removed, hot-reloaded, or
its entity despawned), one a module body binds at the module's next run.
`scopes.list()` names each as a `luau` row under the context it follows.
- `remove(name)` and `clear()` also wipe handlers bound to those
actions — handler state never outlives its action.
- The handler allocator is swapped at boot (`_setAllocator`) so handles
drawn here share one namespace with `Zin.input.on*`.
▲ 0↑ born
# arming
The predicate a look-style control hands to its `gate`, in the one place it
is written. Backs `Zin.arming`.
A mouse always has a delta, so an ungated mouse-look turns the camera
whenever the cursor crosses the window. The gate answers "is the player
steering?" — and every scheme answers it with the same list of gestures in a
different combination. `Zin.arming.gate(opts)` takes the combination and
returns the predicate.
```luau
local Arming = require("@builtin::modules.zinput.arming")
return {
label = "Look",
kind = "axis2",
gate = Arming.gate({ dragZone = "right", stick = "right" }),
kbm = B.mouseDelta(),
gamepad = B.padStick("right", { as = "delta", unitsPerSecond = 1200 }),
touch = B.touchDrag({ zone = "right" }),
}
```
A locked pointer always arms: a cursor the scheme took is one the player
gave to the camera. The rest is named in `opts` — `dragZone` for a finger
inside a touch zone, `stick` for a deflected pad stick, `padButtons` for a
trigger, `virtualButtons` for an on-screen button.
## The right mouse button
`rightButton` is the field the schemes disagree about, because the button
means two different things.
| Value | Arms while | Used by |
|-------|-----------|---------|
| `"free"` (default) | the button is down and no other control that can answer on it declares it | the player scheme |
| `"held"` | the button is down | the editor scheme, where holding it IS the fly gesture |
| `"off"` | never | a control that reads the button through nothing but pointer lock |
`"free"` is what lets a world bind the right button to a game action. The
engine's default scheme arms mouse-look on that button, and a world that
also binds it would otherwise get the camera turn and its own action from
one gesture, with no way to decline the camera half short of standing down
its whole control group. Under `"free"` the world's binding is the claim:
declare the button in a live `.inputMap` control, or in the `Zin.actions` /
`Zin.axes` registry, and the arming stands down for as long as that control
can answer on it. A control whose map is standing down for a suppressor, or
whose context is not the one on top, is one the player cannot reach — the
same two terms the tick's own dispatch reads before it evaluates a control —
so the button is free of it while that holds and the camera keeps the drag.
`Zin.arming.rightButtonClaimants()` names who is holding it, which is the
answer to "why did my right-drag stop turning the camera":
```luau
Zin.arming.rightButtonClaimants() --> { "map:torch.torchToggle" }
```
The engine's own arming gesture — the `lookDrag` control on the standard
scheme, and the `look_drag` action beside it in the registry — is what
`"free"` arms FROM, so those two names are passed over by the search.
A claim is decided on the frame the button goes down and holds until it
comes up. A map activating mid-drag therefore cannot take a gesture away
from the camera halfway through it, and the search runs once per press
rather than once per gated control per frame.
▲ 0↑ born
# autoTick
Opt-in per-frame tick loop for zinput. Spawns a `task.spawnSystem` worker
that invokes a registered tick function (`Zin.tick`) once per frame, so
code-mode snippets and tests without a host script component still drive
the stateful subsystems — live binding dispatch, the touch overlay, the
emulation floor, axes, chords, rebind, action handlers, event subscribers.
`task.spawnSystem` (not `task.spawn`) makes the loop system-owned, so it
keeps ticking while the editor pauses gameplay.
The first real input read arms this worker on its own. A host script
component can also call `Zin.tick(dt)` from its `update(dt)` hook, and
`autoTick.start` can be called directly; all three are idempotent
alongside each other.
## Exports
- `M.start() -> boolean` — spawn the worker if not already running. Returns true when a new loop was started.
- `M.stop()` — flag the loop to exit on its next yield. No-op if not running.
- `M.isRunning() -> boolean` — current status.
- `M._setTickFn(fn: (number?) -> ())` — internal hook. Called once by `zinput/init.luau` to register `Zin.tick`.
- `M._setLastTickFrameIdFn(fn: () -> number)` — internal hook. Wires the frame-id accessor so the worker can dedup itself against explicit ticks within the same engine frame.
## Usage
```luau
local Zin = require("@builtin::modules.zinput")
-- One-shot test / code-mode setup:
Zin.autoTick.start()
-- ... later ...
Zin.autoTick.stop()
```
## Notes
- Single-flight: calling `start()` twice is a no-op — there is at most
one worker per VM.
- Cross-coroutine dedup: when an explicit `Zin.tick` ran in the same
engine frame, the worker skips that frame so `onHeld` handlers and
event subscribers don't double-fire.
- Module-local `_running` survives Luau require-cache reload, so a
re-required `autoTick.module` still reports the loop is live.
`restart_instance` resets the VM and clears everything.
- `start()` raises if `_setTickFn` hasn't been wired yet — always
`require("@builtin::modules.zinput")` first.
▲ 0↑ born
# axes
A name-registered axis registry over `Zin.bindings`. Any axis or vector
binding becomes a `Zin.axes` entry with optional deadzone, exponential
smoothing, curve shaping, invert, context gating, and a per-frame gate
function. Stateful — `Zin.tick` calls `advance(dt)` each frame to evolve
the smoothed reading.
A control asset replaced this. An `axis1` / `axis2` `<name>.inputBinding/`
inside an `.inputMap/` carries a binding for keyboard-and-mouse, gamepad
and touch, so one control reads a stick and a dragging thumb as well as a
key, and the binding's own `as` / `unitsPerSecond` / `scale` bring every
class into one unit. It declares the same `deadzone`, `smoothing`, `curve`
and `invert`, applied by `Zin.scheme` through the same `Zin.utils` maths
this reads:
```luau
public = {
inputMap = Field.assetRef("inputMap", "@builtin::inputMaps.default", NoSync, "The controls this component reads."),
speed = Field.number(5, NoSync, "World units per second at full deflection."),
jumps = Field.number(0, NoSync, "How many times the jump control was pressed."),
}
local controls
function awake()
controls = public.inputMap:activate()
controls.move:onInput(function(v, dt, active)
if not active then return end
local p = public.entity.position
local step = public.speed * dt
public.entity.position = { p.x + v.x * step, p.y, p.z - v.y * step }
end)
controls.jump:onPressed(function() public.jumps += 1 end)
end
function onDestroy()
public.inputMap:deactivate(controls)
end
```
`Zin.map.bake(name)` writes the currently active map out as an `.inputMap`
asset. `man topics/input` covers the control model.
## Exports
Lifecycle:
- `M.define(spec: AxisSpec)` — define / replace axes.
- `M.remove(name: string)` / `M.clear()` — drop one / all axes.
- `M.has(name) -> boolean` / `M.names() -> { string }` / `M.get(name) -> AxisDef?`
Reads:
- `M.value(name: string) -> any` — smoothed value (`number` for scalar, `{ x, y }` for vector).
- `M.raw(name: string) -> any` — raw unsmoothed binding value.
Tick hook:
- `M.advance(dt: number)` — internal; called by `Zin.tick`.
- `M._setEnsureBindingsFn(fn)` / `M._setEnsureLiveFn(fn)` — internal cold-read hooks.
- `M._resetGateWarnings()` — test helper.
Types:
- `Curve = string | (number) -> number` — `"linear"` / `"quadratic"` / `"cubic"` / custom.
- `AxisDef = { binding, deadzone, smoothing, curve, invert, context, gate, kind }`
- `AxisSpec = { [string]: any }` — define-spec.
## Notes
- `smoothing` is the exponential time constant in seconds. `0` means
"snap to target instantly". Higher = laggier.
- `deadzone` is radial for vector bindings — magnitude under the
threshold zeros both axes — and scalar for scalar bindings.
- Context gating is strict: the axis's declared context must equal
`Zin.context.current()`. Mismatch snaps target to 0, and `advance`
smooths current down toward 0.
- A throwing `gate` falls through to "ungated" for that frame and
logs one warning per axis per session (state cleared via
`_resetGateWarnings()`).
- Without a tick host (or `Zin.autoTick.start()`), `value()` returns
the last computed snapshot; `raw()` always reads live.
▲ 0↑ born
# back
Back, and the claims a world holds on it. Backs `Zin.back`.
Back is the platform's own Back: Android's Back button and back gesture, and
a keyboard's Back key (`BrowserBack`, which a browser names the same). A
world binds any control of its own to it with `Zin.back.press`, which is how
Escape or a pad's button becomes Back too.
The engine routes every Back press to the first of these that stands:
1. the topmost overlay on screen that states how it is dismissed: an open
`popup` carrying `onDismiss`, or an open, dismissible `modal` carrying
`onClose`. Its dismissal runs, the way Escape runs it.
2. the claim held that takes it (`Zin.back.claim`: the highest priority,
and the most recent among equals): its handler runs.
3. nothing: the platform's own default answers. On Android the app moves to
the background; a desktop window and a browser page stay where they are.
A claim says ahead of the press that the world takes Back, which is what
Android's predictive back asks for: the system decides before a back gesture
begins whether it previews going home. Hold a claim while Back means
something to the world and release it when Back should leave.
Every press is a `back` event in `input.events()`:
`{ kind = "back", taker = "overlay" | "claim" | "none" }`.
## Exports
- `M.claim(handler, { priority? }) -> Claim`: take Back. Of the claims held,
the highest priority (0 when omitted) takes a press no overlay takes, and
the most recent among equals. The editor's claim that leaves play is held
at -1, under every claim a played world makes. `claim:release()` gives it up, `claim:held()` says
whether it is held. A claim a component makes is released when its entity
is destroyed.
- `M.press()`: press Back, routed as above.
- `M.claims() -> number`: how many claims are held.
## Usage
```luau
local Zin = require("@builtin::modules.zinput")
local claim
local function closeMenu()
menu.close()
if claim then claim:release() claim = nil end
end
local function openMenu()
menu.open()
claim = Zin.back.claim(closeMenu)
end
-- Escape as Back too, through the world's own control.
controls.pause:onPressed(Zin.back.press)
```
▲ 0↑ born
# bindings
Binding primitives and evaluators. A binding names which physical input
satisfies a control on one device class — the value a `.inputBinding`
record's `kbm` / `gamepad` / `touch` field holds. A binding is a plain
descriptor table (e.g. `{ kind = "key", code = "KeyW" }`); the evaluators
(`evalHeld`, `evalPressed`, `evalReleased`, `evalAxis`, `evalVector`)
dispatch on `kind` and read `Zin.state` / `Zin.virtual` to produce the live
signal. `Zin.scheme` runs them once per tick for every live binding, and
they are public so chords, axes and library authors can evaluate a binding
without reimplementing the dispatch.
```luau
-- boost.inputBinding/init.luau
local B = require("@builtin::modules.zinput.bindings")
return {
label = "Boost",
kind = "button",
kbm = { B.key("ShiftLeft") },
gamepad = { B.padButton("left_shoulder") },
touch = { B.touchButton({ zone = "right-lower" }) },
}
```
## Two frames, and which binding speaks which
- **Stick bindings** (`vector`, `touchStick`, `padStick`) report the
direction the player *means* — forward is `+y`. A `move` control carrying
a keyboard class and a stick class drives both devices the same way.
- **Delta bindings** (`mouseDelta`, `touchDrag`, `scroll`) report movement
that happened — down is `+y`, because that is what the pointer did.
They also differ in magnitude: a stick is a position bounded at 1.0, a
delta is however far the device moved this frame. A control carrying both —
look, zoom — declares `as = "delta"` on its held class with the
`unitsPerSecond` a full deflection is worth, and `scale` on a delta class
that counts in its own units (a pinch in pixels beside a wheel in notches).
`Zin.scheme` applies both, so one sensitivity covers every device.
## Exports
Keyboard and mouse constructors:
- `M.key(code: string) -> Binding`
- `M.mouse(button: string) -> Binding` — `"left"` / `"right"` / `"middle"`.
- `M.modKey(spec: string) -> Binding` — `"Ctrl+S"`, `"Shift+Alt+P"`, `"Escape"`.
- `M.axis(plus: Binding, minus: Binding, opts: StickOpts?) -> Binding`
- `M.vector(right, left, up, down: Binding) -> Binding`
- `M.wasd() -> Binding`
- `M.arrowKeys() -> Binding`
- `M.mouseDelta(axis: string?) -> Binding` — this frame's mouse delta.
- `M.scroll(axis: string?) -> Binding` — scrollwheel delta.
- `M.pointerLocked() -> Binding` — boolean, true while locked.
Touch constructors (fed by `Zin.virtual`, which the on-screen controls write):
- `M.touchStick(opts: { zone, axis? }) -> Binding` — vector.
- `M.touchButton(opts: { zone?, label?, icon?, priority?, size?, group? }) -> Binding` — boolean.
- `M.touchDrag(opts: { zone, axis? }) -> Binding` — per-frame delta vector.
- `M.touchPinch(opts: StickOpts?) -> Binding` — scalar pinch delta.
Gamepad constructors (addressed by canonical position; `slot` names one pad,
omitting it means any connected pad):
- `M.padButton(button: string, slot: number?) -> Binding`
- `M.padAxis(axis: string, opts: StickOpts?) -> Binding`
- `M.padStick(stick: string, opts: StickOpts?) -> Binding`
- `M.padTrigger(trigger: string, slot: number?) -> Binding`
Predicates:
- `M.isBoolean(b) -> boolean`
- `M.isAxis(b) -> boolean`
- `M.isVector(b) -> boolean`
Evaluators:
- `M.evalHeld(b) -> boolean`
- `M.evalPressed(b) -> boolean`
- `M.evalReleased(b) -> boolean`
- `M.evalAxis(b) -> number`
- `M.evalVector(b) -> Vec2`
Pretty-printers:
- `M.format(b: any) -> string` — single binding ("Space", "Ctrl+S", "WASD").
- `M.formatAll(bindings: any?, sep: string?) -> string` — joined summary; non-table arg returns `"<no bindings>"`.
Types:
- `Binding = { [string]: any }` — descriptor table with `kind` plus type-specific fields.
- `Vec2 = { x: number, y: number }`
- `StickOpts = { slot: number?, as: string?, unitsPerSecond: number?, scale: number? }`
## Notes
- Bindings are pure data tables — they serialize cleanly, compare with
`Json.encode`, and have no metatables.
- `modKey` normalises modifier order in `format()` so a key written as
`Shift+Ctrl+KeyS` displays the same as `Ctrl+Shift+KeyS`. The
internal `mods = { ctrl, shift, alt }` flags are the canonical
representation.
- Mouse-delta, scroll, drag and pinch values are raw physical deltas, not
clamped to `[-1, 1]`. `as = "delta"` + `unitsPerSecond` on the stick
class beside them is what puts every class in one unit.
- `as = "delta"` needs `unitsPerSecond` and has no default: the number that
makes a pad feel right is the point of declaring the conversion, and a
default would be right for one control and quietly wrong for the next.
- Reading a member this module does not have raises immediately, naming the
nearest members and the full list — a wrong guess at a constructor
surfaces at the call rather than as `attempt to call a nil value` later.
- `format()` always returns a string, never throws — returns
`"<invalid>"` for malformed input.
▲ 0↑ born
# chords
Chord and sequence state machines. Two kinds:
- `sequence` — ordered steps with a per-step window and an overall
window (Konami-style codes).
- `simultaneous` — N bindings pressed inside a tolerance window,
order-insensitive (piano-chord / fighter-combo style).
Chords are edge-triggered — `fired(name)` is `true` for exactly one
frame when the full pattern completes. A continuous combo like "Ctrl+S
held" is a `button` control whose `kbm` class is `B.modKey("Ctrl+S")`: a
chord recognizes a pattern over time, which is a different question from
whether a combination is down right now.
## Exports
Lifecycle:
- `M.define(spec: ChordSpec)` — define / replace chords.
- `M.remove(name) / M.clear()`
- `M.has(name) -> boolean` / `M.names() -> { string }` / `M.get(name) -> ChordDef?`
Queries:
- `M.fired(name) -> boolean`
- `M.progress(name) -> number` (0..1)
- `M.cancel(name)` — reset state.
Subscriptions:
- `M.onFire(name, callback, opts: OnFireOpts?) -> OnFireHandle`
- `M.off(handle: OnFireHandle)`
Tick hooks (called by `Zin.tick`):
- `M._beginTick()` — clears per-frame fire flags.
- `M._observeEvent(ev)` — advance state machines on an input event.
- `M._advanceTime(dt)` — age out stale recognizers.
- `M._dispatchFires()` — invoke onFire callbacks for chords that fired this tick.
Types:
- `ChordDef = { kind, context, steps?, stepWindowSec?, windowSec?, bindings?, toleranceSec? }`
- `ChordSpec = { [string]: any }`
- `OnFireOpts = { context: string?, once: boolean? }`
- `OnFireHandle = { id: number, name: string, off: () -> () }`
## Usage
```luau
local Zin = require("@builtin::modules.zinput")
local B = Zin.bindings
Zin.chords.define({
konami = {
kind = "sequence",
steps = { B.key("ArrowUp"), B.key("ArrowUp"), B.key("ArrowDown"),
B.key("ArrowDown"), B.key("ArrowLeft"), B.key("ArrowRight"),
B.key("ArrowLeft"), B.key("ArrowRight"),
B.key("KeyB"), B.key("KeyA") },
stepWindowSec = 0.5,
windowSec = 4.0,
},
})
Zin.chords.onFire("konami", function() unlockBonus() end)
```
## Notes
- Without a tick host (or `Zin.autoTick.start()`) chords never fire —
every state machine is dormant until `Zin.tick` drives it.
- A wrong key in a sequence resets to step 0. If the wrong key
happens to match step 1, the recogniser restarts from step 1 on the
same event (so a long input run can self-recover).
- For simultaneous chords, the tolerance window starts on the first
matched press. If all bindings haven't matched before
`toleranceSec` elapses the state resets — `firstPressAt` is reset
too so the next press starts a fresh window.
- Subscriber errors are caught and logged via `log.warn`.
▲ 0↑ born
# zinput / clock
The wall-clock time source for zinput's time-window features — held-time and
synthetic key repeat (`state`), chord step / total windows (`chords`), and the
tick's fallback delta (`init`).
`nowSeconds()` reads the engine's per-frame `getTime()` (seconds since engine
start, published from the native clock), which advances with wall time on every
platform. `os.clock` measures CPU time and barely moves across scheduler yields
on wasm, so it is only the fallback for contexts with no engine time surface.
## API
- `nowSeconds() -> number` — current wall-clock seconds for input timing.
- `_setClock(fn: (() -> number)?)` — internal; override the clock with `fn`
(returns seconds) or `nil` to restore the default. For deterministic timing:
fixed-step replay and tests that need a controllable clock.
▲ 0↑ born
# conflicts
Binding-conflict detection — reverse index over the `Zin.actions` /
`Zin.axes` registries. Two bindings "conflict" when they map to the same
canonical leaf key (e.g. both bind `Space`, or an action binds `Space` and
an axis's `plus` side is `Space`). Backs `Zin.conflicts`.
Rows carry a `kind = "real" | "intentional"` classification: two or
more action owners in the *same context* are `real`; action + axis
overlaps, cross-context actions, and explicitly marked pairs are
`intentional`. `realOnly()` is the noise-filtered view the Input tab
uses; `forActiveProfile()` is the full audit list.
## Exports
Marking:
- `M.markIntentional(actionA: string, actionB: string) -> (boolean, string?)`
- `M.unmarkIntentional(actionA: string, actionB: string) -> boolean`
- `M.isIntentional(actionA: string, actionB: string) -> boolean`
- `M.listIntentional() -> { { string } }`
Probing:
- `M.bindingKey(b: any) -> string?` — `"key:Space"`, `"modKey:Ctrl+KeyS"`, `"mouse:left"`, or `nil`.
- `M.find(binding: any) -> { Owner }` — owners that share any leaf key with the probe.
- `M.forActiveProfile() -> { ConflictRow }` — every shared-key row.
- `M.realOnly() -> { ConflictRow }` — subset where `kind == "real"`.
Internal (wired by `zinput/init.luau`):
- `M._setPersistFn(fn)` — registers the save-back closure.
- `M._loadIntentionalPairs(pairs_)` — seed on profile activate.
- `M._serializeIntentional() -> { { string } }` — for profile save.
- `M._resetIntentional()` — test isolation.
Types:
- `Owner = { target: string, name: string, slot: any }` — `target` is `"action"` or `"axis"`.
- `ConflictRow = { key: string, owners: { Owner }, kind: string }` — `kind` is `"real"` or `"intentional"`.
## Usage
```luau
local Zin = require("@builtin::modules.zinput")
-- Audit view (e.g. inside the Input tab):
for _, row in ipairs(Zin.conflicts.forActiveProfile()) do
print(row.key, row.kind, #row.owners)
end
-- Suppress an intentional same-context overlap:
Zin.conflicts.markIntentional("crouch", "slide")
```
## Notes
- `modKey` leaf keys list modifiers alphabetically (`Alt+Ctrl+Shift`),
so `Shift+Ctrl+KeyS` and `Ctrl+Shift+KeyS` compare equal.
- Continuous-source bindings (`mouseDelta`, `scroll`, `pointerLocked`)
never appear in conflict reports — two axes reading `mouseDelta` is
by-design.
- Persistence: `_setPersistFn` is wired by `zinput/init.luau` so
marks flow into the active profile JSON without conflicts needing a
hard dep on profile.
- The classifier counts every same-context action pair. If even one
pair is unmarked, the row is `"real"`; otherwise `"intentional"`.
▲ 0↑ born
# context
The input context stack. Pushing a named context ("ui", "menu",
"vehicle", ...) stands down everything whose declared context doesn't
match the top of the stack; popping restores the previous mode. The bottom
is permanently `"default"` so unbalanced pops never leave the stack empty.
A control, an action, an axis or an event subscriber can declare one
context. `Zin.scheme` honours it on every live binding, so a
vehicle-context Brake neither fires nor draws its touch button while the
default context is on top.
A map standing another map's `group` down is the coarser instrument beside
this one: `group` / `suppresses` on an `.inputMap` decides which whole
schemes answer, while a context decides which entries within a live scheme
do.
## Exports
- `M.default() -> string` — the always-on context name (`"default"`).
- `M.push(name: string)` — push a context. No-op when `name` is not a non-empty string.
- `M.pop() -> string?` — pop the top context; returns `nil` when only `default` remains.
- `M.current() -> string` — name at the top of the stack.
- `M.contains(name: string) -> boolean` — true if `name` is anywhere in the stack.
- `M.stack() -> { string }` — a copy of the live stack, bottom→top.
- `M.reset()` — pop everything except `default`.
- `M.with<T...>(name: string, fn: () -> T...) -> T...` — run `fn` with `name` pushed, pop guaranteed.
## Usage
```luau
local Zin = require("@builtin::modules.zinput")
-- menuClose.inputBinding/init.luau declares `context = "ui"`, so it reads
-- only while "ui" is on top.
Zin.context.push("ui")
Zin.context.current() -- "ui"
Zin.context.pop()
Zin.context.with("ui", function()
-- inside this block the "ui" controls are the ones that read
end)
```
## Notes
- The stack lives in the module's upvalues, so it persists across
Luau script runs that share the require cache. A `restart_instance`
resets it (matches the standard caching contract).
- Pushing the same context twice requires two pops to fully remove —
matches typical UI nesting (a sub-menu pushes "ui" again).
- A declared context is compared strictly equal to `current()`; there's no
inheritance up the stack.
▲ 0↑ born
# controllers
Reusable controller factories on top of the `Zin.actions` handler,
`Zin.context` and `Zin.state` surfaces. Each factory returns a stateful
controller object with the `:start / :stop / :update / :isActive`
lifecycle and a small set of intent readers. `free`, `orbit` and `fps` read
keyboard and mouse, and their `gamepadIndex` opt is accepted and ignored.
`vehicle` reads an input map, so every control answers to keyboard, gamepad
and touch.
## Exports
Factories (module-level):
- `M.free(opts: FreeOpts) -> FreeController` — free-fly designer/debug camera (WASD plane + Q/E vertical + Shift sprint + mouse-look). Writes the entity transform directly.
- `M.orbit(opts: OrbitOpts) -> OrbitController` — orbit camera around a target (drag-rotate, scroll-zoom, optional pan).
- `M.fps(opts: FpsOpts) -> FpsController` — first-person walker. Produces motion intent for the host (`getDesiredVelocity`, `consumeJumpRequest`, `isSprinting`, `isCrouching`); convenience `applyToTransform` writes directly.
- `M.vehicle(opts: VehicleOpts?) -> VehicleController`: driving intent for a ground vehicle, read from `opts.inputMap` (an inputMap ref or its path; `@builtin::inputMaps.vehicle` by default): `getThrottle` (-1..1, positive forward), `getSteer` (-1..1, positive right), `getBrake` (0..1), `isHandbrakeHeld`, `isBoosting`, `consumeRecoverRequest` (true once per press), `consumeZoom` (wheel notches since the last read). `:start` activates the map, which stands the walking scheme down for as long as it is live; `:stop` releases it. The `VehicleController` component drives a car's `WheelCollider`s from this intent.
Controller-object methods (returned by the factories; called with `:`):
- `:start()` — define actions, push context, optionally request pointer-lock.
- `:stop()` — drop actions, pop context, release pointer-lock if `:start` took it.
- `:isActive() -> boolean`
- `:update(dt: number)` — per-frame; no-op when context doesn't match.
- `:actionNames() -> { string }`
- `FreeController`: `:setMoveSpeed`, `:setLookSensitivity`, `:getCameraYaw`, `:getCameraPitch`, `:getVelocity`.
- `OrbitController`: `:getDistance`, `:getYaw`, `:getPitch`, `:setDistance`, `:setTarget`.
- `FpsController`: `:setMoveSpeed`, `:setLookSensitivity`, `:getCameraYaw`, `:getCameraPitch`, `:getDesiredVelocity`, `:isSprinting`, `:isCrouching`, `:consumeJumpRequest`, `:applyToTransform`.
Types:
- `FreeOpts`, `OrbitOpts`, `FpsOpts` — opts tables; `entity` is the only required field.
- `VehicleOpts`: `{ inputMap?, label? }`; every field is optional.
- `FreeController`, `OrbitController`, `FpsController` — opaque (typed as `any` so the metatable plumbing doesn't fight the LSP).
## Usage
```luau
local Zin = require("@builtin::modules.zinput")
local cam = Zin.controllers.free({ entity = cameraEntityId })
cam:start()
-- per frame:
Zin.tick(dt)
cam:update(dt)
```
## Notes
- Each controller's actions are namespaced under `actionPrefix` (default
`"free_fly."`, `"orbit."`, `"fps."`). Two co-existing controllers
with overlapping prefixes will trample each other — override the
prefix when stacking.
- The context push/pop pair makes `Zin.context.push("ui")` cleanly
suppress every controller without `:stop`. The controller's
`:update` early-outs when `Zin.context.current()` doesn't match.
- Rotation convention: yaw=0, pitch=0 → `(0, 0, -1)` (-Z forward).
Mouse Δx adds to yaw; mouse Δy subtracts from pitch (invert with
`invertY = true`). Pitch is clamped to `[-π/2 + ε, π/2 - ε]`.
- `FpsController` produces *intent* — gravity, collision, and the
jump impulse are the host's responsibility. The
`consumeJumpRequest()` accessor returns `true` once per press, so
the physics step can fire its impulse exactly once.
- Free / FPS request pointer-lock at `:start` (opt out with
`requestPointerLock = false`) and only release it on `:stop` when
they were the ones who acquired it.
▲ 0↑ born
# emulation
Map-driven input-emulation floor. Reads `Zin.virtual` (the store on-screen
touch controls write) each tick and emulates the equivalent kbm keys / mouse
delta, so raw-key-polling worlds (`Zin.state.keyDown`) move from touch input
without themselves reading `Zin.virtual` or `Zin.bindings`. Backs
`Zin.emulation`.
## What it derives, per tick, from the active effective map
Only entries whose `context` matches the current input context
(`Zin.context.current()`) participate — the same activity rule
`Zin.actions` applies, so a vehicle-context Brake button emulates nothing
while the default context is on top.
- **touchButton actions** — the OR of every touchButton binding in an
action's touch class drives its first kbm `key` binding's code, emulated
on the held state's transitions. Actions with no kbm key binding are
skipped.
- **touchStick axes** whose kbm class is a `vector` of four `key` arms (the
`B.wasd()` / `B.arrowKeys()` shape) — each stick component thresholded at
`+-0.5` drives the matching direction key. The stick's y is screen-down
positive (`Virtual.setStick`'s convention), so negative y (stick pushed
up) drives the vector's `up` arm and positive y its `down` arm.
- **touchDrag axes** whose kbm class is `mouseDelta` — the drag delta,
scaled by `M.setSensitivity`, emulated via `input.emulateMouseDelta`
whenever it's non-zero.
A control that is already a live binding (`Zin.scheme.has(name)`) is
skipped: its touch class drives it directly, and synthesising a key for it
as well drives it twice, from opposite conventions. The judgement is per
control, because a world can subscribe to some things and poll raw keys for
others.
Emitted keys are tracked locally and diffed each tick — a held key is
emulated once, on the press transition, never re-emitted every tick a
control stays held. Switching the active map (name change between ticks)
or the input context (top-of-stack change) releases everything emitted
under the previous map/context.
## Exports
- `M.setSensitivity(n: number)` / `M.getSensitivity() -> number` — the
touchDrag -> mouse-delta multiplier (default `1.0`).
- `M._advance()` — internal: one tick of the floor, called by `Zin.tick`.
- `M._reset()` — test-only: release everything emitted, clear state.
## Usage
```luau
local Zin = require("@builtin::modules.zinput")
Zin.map.ensureActive()
Zin.emulation.setSensitivity(1.5)
-- Zin.tick(dt) advances the floor; a virtual Jump press then reads as
-- Zin.state.keyDown("Space") for any world that only polls kbm state.
```
▲ 0↑ born
# events
Frame-event readers and edge-event subscriptions. Wraps the internal
`__zero_input.events()` FFI with per-kind filters and a push-style
`on/off` API that fires from `Zin.tick`. Backs `Zin.events`.
`__zero_input.events()` returns the current frame's events in
dispatch order; reading does not consume them. Subscription dispatch
happens during `Zin.tick` (or `Zin.autoTick.start()`'s worker), so
without a tick host `on()` callbacks never fire.
## Exports
- `M.frame() -> { InputEvent }` — this frame's events in dispatch order.
- `M.iter() -> iterator` — `ipairs` over `frame()`; reads better at call sites.
- `M.keysDown / keysUp / mouseDowns / mouseUps / mouseMoves / mouseWheels / texts() -> { InputEvent }` — per-kind filters.
- `M.on(filter: EventFilter, callback, opts: SubOpts?) -> SubHandle` — register an edge subscriber, returns handle.
- `M.off(handle: SubHandle | number)` — cancel a subscriber.
- `M.clearSubscribers()` — drop all subscribers (test isolation).
- `M.subscriberCount() -> number` — current subscriber count.
- `M._dispatch(events)` — internal; called by `Zin.tick`.
Types:
- `InputEvent = { [string]: any }` — one entry of the frame event log.
- `EventFilter = string | { [string]: any } | (any) -> boolean`
- `SubOpts = { context: string?, once: boolean?, priority: number? }`
- `SubHandle = { id: number, off: () -> () }`
## Usage
```luau
local Zin = require("@builtin::modules.zinput")
for _, ev in ipairs(Zin.events.frame()) do
if ev.kind == "key.down" and ev.code == "Space" then
-- jump on the press edge, not on every frame the key is held
end
end
local h = Zin.events.on({ kind = "key.down", code = "Escape" }, function(ev, gpe)
if not gpe then closeMenu() end
end, { context = "ui" })
-- later: h.off()
```
## Notes
- Reading `frame()` is non-destructive — multiple consumers can iterate
the same frame's events. The log clears at end-of-frame and is rebuilt
next frame.
- Subscribers dispatch in priority-desc order; equal priorities preserve
insertion order. Returning `"sink"` from a callback halts further
dispatch for that single event (lower-priority subscribers skipped).
- `once = true` subscribers auto-unsubscribe after their first matching
dispatch.
- A subscription ends with the context that made it as well as with
`off`: one a component makes ends when that component instance goes
(removed, hot-reloaded, or its entity despawned), one a module body makes
at the module's next run. `scopes.list()` names each as a `luau` row
under the context it follows.
- Subscriber errors are caught and logged via `log.warn`; one bad
handler doesn't break dispatch.
▲ 0↑ born
# gamepad
The pad-facing surface: which controllers are connected, what family they
belong to, and what a legend should call a canonical button on them. Backs
`Zin.gamepad`.
Bindings never come through here. A scheme binds `B.padButton("south")` and
evaluates against whichever pad is connected; this module answers the
questions a UI asks — how many players have controllers, and which letter to
draw on a prompt.
## Position, not letter
The canonical layout names a button by POSITION, because position is what
every pad shares — `south` is the lower face button on all of them. The
letter printed on it is not shared: `south` is `A` on an Xbox pad, `Cross`
on a PlayStation one, and `B` on a Nintendo one. `label()` resolves that
from the device name the platform reported, so a binding stays
device-independent and only the drawn glyph changes.
Anything unrecognised reads as `xbox`, because the standard mapping every
backend normalises to is the Xbox layout.
## Exports
- `M.list() -> { Pad }` — every connected pad, in slot order.
- `M.count() -> number` — how many pads are connected.
- `M.get(slot) -> Pad?` — the pad in one slot.
- `M.family(slot?) -> string` — `"xbox"` | `"playstation"` | `"nintendo"`.
- `M.label(button, slot?) -> string` — the legend for a canonical button.
- `M.available() -> boolean` — whether the session has ever seen a pad.
Latched by the first connection, so unplugging one does not flip a
scheme's prompts back to keyboard glyphs on a cable knock.
Types:
- `Pad = { slot, name, buttons, buttons_pressed, buttons_released, axes,
simulated }` — the button fields are arrays of canonical names, `axes` a
map of canonical axis name to number, and `simulated` marks a pad that
came from the `inputSim` toolbox rather than a device.
## Usage
```luau
local Zin = require("@builtin::modules.zinput")
if Zin.gamepad.count() >= 2 then
startLocalCoop()
end
ui.text("Press " .. Zin.gamepad.label("south") .. " to jump")
```
▲ 0↑ born
# gestures
Touch-gesture recognizers over the touch event stream + contact
snapshot; backs `Zin.gestures`. Discrete gestures (tap, double-tap,
long-press, swipe) fire subscriptions; continuous gestures (pinch, pan)
expose per-tick deltas computed from the two-finger contact state.
Advanced by the `Zin.tick` pipeline — dormant until ticked.
## Discrete vs continuous
- **Discrete** (tap / double-tap / long-press / swipe) — recognized on
a release or hold-duration edge, delivered via `on*` subscriptions on
the tick they fire.
- **Continuous** (pinch / pan) — recomputed every tick from the
two-finger contact positions; read via `pinchDelta()` / `panDelta()`,
reset to zero at the start of each tick. The pair is formed from the
contacts no on-screen widget is working, the ones `Zin.touchControls`
says its stick and buttons hold having been left out, so a thumb on a
movement stick is no part of a pinch.
## Config
`Zin.gestures.configure` overrides recognition thresholds (unspecified
fields keep their current values):
| Field | Default | Meaning |
|---|---|---|
| `tapMaxDuration` | `0.25` s | press→release within this = tap candidate |
| `tapMaxMovement` | `16` px | total movement below this = tap candidate |
| `doubleTapWindow` | `0.3` s | two taps within this = double-tap |
| `longPressDuration` | `0.5` s | held past this (still) = long-press |
| `swipeMinDistance` | `60` px | release travel at/above this = swipe candidate |
| `swipeMinVelocity` | `800` px/s | release velocity at/above this = swipe |
## Exports
- `M.configure(opts: { [string]: number })` — override recognition thresholds.
- `M.getConfig() -> GestureConfig` — current thresholds (a copy).
- `M.onTap(fn) -> number` — subscribe to taps; `fn(ev)` with `ev = { x, y, id, duration }`.
- `M.onDoubleTap(fn) -> number` — subscribe to double-taps; `ev = { x, y, id }`.
- `M.onLongPress(fn) -> number` — subscribe to long-presses (fires once per contact); `ev = { x, y, id }`.
- `M.onSwipe(fn) -> number` — subscribe to swipes (fires on release); `ev = { direction, dx, dy, velocity, id }`.
- `M.off(handle: number) -> boolean` — unsubscribe a handle from any `on*` function.
- `M.pinchDelta() -> number` — this tick's two-finger pinch delta in px (positive = spreading).
- `M.panDelta() -> (number, number)` — this tick's two-finger pan delta `(dx, dy)` in px.
- `M._beginTick()` — internal: clear per-tick continuous deltas; wired by `Zin.tick`.
- `M._observeEvent(ev: any)` — internal: builds contact tracks and classifies discrete gestures on release; wired by `Zin.tick`.
- `M._advanceTime(dt: number)` — internal: time-based recognition (long-press) + continuous deltas; wired by `Zin.tick`.
- `M._setWidgetContacts(ids: { [number]: boolean })` — internal: the contacts an on-screen widget is working; published each tick by `Zin.touchControls`.
- `M._pairDown() -> boolean` — internal: whether two contacts no widget is working are down, which is the pair a two-finger gesture reads.
- `M._dispatchFires()` — internal: deliver this tick's discrete gesture fires; wired by `Zin.tick`.
- `M._reset()` — test-only: clear all tracks, fires, deltas, and subscriptions.
Types:
- `GestureConfig = { tapMaxDuration, tapMaxMovement, doubleTapWindow, longPressDuration, swipeMinDistance, swipeMinVelocity }` (all `number`)
## Usage
```luau
local Gestures = require("@builtin::modules.zinput.gestures")
Gestures.onTap(function(ev)
print("tap at", ev.x, ev.y)
end)
Gestures.onSwipe(function(ev)
if ev.direction == "left" then nextPage() end
end)
-- inside a per-frame update:
local zoom = Gestures.pinchDelta()
local dx, dy = Gestures.panDelta()
```
## Notes
- Pinch and pan deltas are zero unless exactly two contacts are down
this tick that no on-screen widget is working.
- Long-press fires once per contact — the contact must stay within
`tapMaxMovement` for the full `longPressDuration` and is marked so it
never also fires a tap on release.
- Every qualifying release fires `tap`; the second tap of a double-tap
fires `doubleTap` and `tap` on the same tick.
- Handler errors during dispatch are caught and logged, not propagated.
▲ 0↑ born
# input
Event-driven listeners for whole categories of raw input, on top of
`Zin.events.on`. Sugar for the most-common filter shapes (`onBegan` /
`onEnded` / `onChanged` / `onTextInput`) plus a `lastInputType()`
accessor. Backs `Zin.input`.
These sit beneath the control model: they answer "any key went down"
rather than "the Jump control fired", which is what rebind capture, dev
tooling and text-adjacent UI need. Gameplay subscribes to controls through
an activated map — `man topics/input` covers that path.
## Exports
- `M.lastInputType() -> string?` — userInputType of the most recent input event (`"Keyboard"` / `"Mouse"` / `"Touch"` / `nil`).
- `M.onBegan(fn, opts?) -> Handle` — fires on `key.down` / `mouse.down`.
- `M.onEnded(fn, opts?) -> Handle` — fires on `key.up` / `mouse.up`.
- `M.onChanged(fn, opts?) -> Handle` — fires on `mouse.move` / `mouse.wheel`.
- `M.onTextInput(fn, opts?) -> Handle` — fires on committed text input; handler signature is `(text, gpe)`.
- `M.disconnect(handle: Handle) -> boolean` — tear down a subscription; idempotent.
- `M.subscriberCount() -> number` — number of active composite subscriptions.
- `M._reset()` — test-only: clear `lastInputType`.
- `M._disconnectAll()` — test-only: tear down every subscription this session.
- `M._observeEvent(ev: any)` — internal observer driven by `Zin.tick`.
- `M._setAllocator(fn: () -> number)` — internal: wire the shared handle-id allocator.
- `M._owns(handle: number) -> boolean` — internal: handle-ownership check for cross-API disconnect.
Types:
- `Filter = string | { [string]: any } | (any) -> boolean`
- `SubOpts = { priority: number?, context: string?, once: boolean? }`
- `Handle = number` — composite-handle id, drawn from a shared allocator with `Zin.actions`.
## Usage
```luau
local Input = require("@builtin::modules.zinput.input")
local h = Input.onBegan(function(io, gpe)
if io.kind == "key.down" and io.code == "Space" then
print("jumped")
end
end, { priority = 10 })
Input.disconnect(h)
```
## Notes
- Handler signatures: `fn(io, gpe)` for `onBegan` / `onEnded` /
`onChanged`; `fn(text, gpe)` for `onTextInput`. `gpe` is the
event's own `consumed_by_ui` marker, stamped as the event arrived
against the focus the UI holds over that event's surface: pointer focus
for a mouse or touch event, keyboard focus for a key or text event, and
never for a pad.
- Return `"sink"` from a handler to stop further (lower-priority)
handlers receiving the same event.
- A single `on*` call installs N underlying `Zin.events.on` subscribers
but returns ONE composite handle — `disconnect` tears them all down
together.
- A composite handle also ends with the context that made it: one a
component registers ends when that component instance goes (removed,
hot-reloaded, or its entity despawned), one a module body registers at
the module's next run. `scopes.list()` names each as a `luau` row under
the context it follows.
- Handle ids share a namespace with `Zin.actions` (`_setAllocator` wires
this at boot), so `Zin.actions.disconnect` accepts handles returned
here.
- `lastInputType` is updated by the tick observer; text events do not
bump it (the preceding key.* event already did).
▲ 0↑ born
# map
A record-shaped map: `Zin.actions` / `Zin.axes` entries organized per
device class (`kbm` | `gamepad` | `touch`) with single-parent `extends`,
materialized into an EFFECTIVE map and applied as one binding set at a
time. Backs `Zin.map`.
An `.inputMap` asset with `.inputBinding` children is the map, and
`Zin.scheme` is the live set: several maps are live at once and compose,
each declaring the `group` its controls belong to and the groups it
`suppresses` while live. `Zin.map.bake(name)` writes the map active here
out as an `.inputMap` asset, with synthesis made explicit and editable.
`man topics/input` covers the control model.
Resolution order per action/axis and device class:
1. the map's own class bindings
2. the `extends` parent's (recursively)
3. synthesis from the `kbm` shape (touch class only)
A vector `kbm` binding synthesizes a `touchStick`; a boolean `kbm` binding
synthesizes a `touchButton`; a vector-shaped `mouseDelta` synthesizes a
`touchDrag`; `scroll` synthesizes a `touchPinch`; an `axis`-kind `kbm`
binding and a single-axis `mouseDelta` are left unsynthesized (ambiguous
which touch shape to guess). A synthesized `touchButton` carries
`priority = 100` — an authored `B.touchButton`'s default priority (50)
always outranks synthesis on the touch-controls overlay, so a hand-tuned
scheme's own layout hints win over whatever filled a gap automatically.
A profile record (actions with `bindings`, axes with `binding`) is accepted
anywhere a map record is — its bindings are treated as the `kbm` class.
## Activation and the `<axis>@<class>` convention
`activate` flattens every class's bindings into each action/axis's single
bindings list and applies it through `Zin.profile`, so any device fires the
action. For axes — which evaluate exactly one binding — the primary slot is
the first of `kbm` / `touch` / `gamepad` present; any OTHER class's binding
registers as a class-suffixed sibling axis (`look` + `look@touch`). A
consumer that wants both device values reads both names; a kbm-only world's
primary axis (`Zin.axes.value("move")`) behaves identically whether or not a
touch class exists.
`Zin.profile.ensureActive("default")` delegates to `Zin.map.ensureActive()`
when the resolved scheme is the builtin default, so it carries every device
class rather than kbm alone. `Zin.map.ensureActive()` / `Zin.map.activate`
win regardless of call order (`activate` re-registers the flattened profile
under the same name and forces a reactivate).
## Exports
- `M.materialize(record: any) -> effective map` — resolve `extends` +
synthesize, without activating.
- `M.activate(record: any) -> effective map` — materialize + apply as the
live binding set (registers/activates a `Zin.profile`).
- `M.effective() -> effective map?` — the active map's materialized form.
- `M.activeName() -> string?` — the active map's name.
- `M.bindingsFor(eff, name, class) -> bindings?` — one action/axis's
bindings for one device class.
- `M.ensureActive() -> effective map` — keep the current map, else activate
`@builtin::inputMaps.default`.
- `M.bake(name: string) -> AssetRef` — write the active effective map as a
new `.inputMap` instance (`asset.create("inputMap", name, { record = ... })`).
- `M.addTouchButton(actionName, buttonOpts, emitKey?) -> binding` — add a
touchButton binding to an action's touch class on the live effective map
(creating the action if absent) and re-activate. Used by
`Zin.touchControls.button`.
- `M.removeTouchButton(actionName, binding) -> boolean` — remove a binding
added via `addTouchButton` and re-activate; drops the action entry once
every class is empty.
- `M._reset()` — test-only: clear active-map state.
## Usage
```luau
local Zin = require("@builtin::modules.zinput")
Zin.map.ensureActive()
local eff = Zin.map.effective()
print(eff.actions.jump.classes.touch ~= nil) -- synthesized or explicit
-- Write the active scheme out as a control-asset map:
Zin.map.bake("my_scheme")
```
▲ 0↑ born
# observe
What became of a device event, and why a live control did not fire. Backs
`Zin.observe`.
A control can be live, its device can be producing input this frame, and the
game can still receive nothing. The input layer works out why every frame —
a gate said no, a live map stood the group down, the UI took the pointer,
nothing subscribed — and until something reads that decision it is thrown
away. This module keeps it.
## The one question
```luau
local Zin = require("@builtin::modules.zinput")
Zin.observe.whySilent("look")
--> {
-- name = "look",
-- layer = "scheme",
-- map = "default",
-- reason = "gateRefused",
-- means = "the control's own gate answered no. A look control gates on
-- the player steering, so a cursor crossing the window reads
-- nothing.",
-- kind = "axis2",
-- subscribers = 1,
-- declaredClasses = { "kbm", "gamepad", "touch" },
-- carriedBy = { "scheme" },
-- }
```
One reason, from a closed set, with the particulars behind it.
`Zin.observe.reasons()` lists the whole set with a sentence each, so what an
answer means is readable from inside the engine rather than only from the
source.
## The closed set, nearest cause first
| Reason | What it says |
|---|---|
| `noMapActive` | No input map is activated at all, so there are no controls. |
| `unknownControl` | No live map declares a control under that name. |
| `groupSuppressed` | A live map stands this control's group down. |
| `contextInactive` | The control declares a context that is not on top of the stack. |
| `heldOnArrival` | A device the control binds was already held when the control went live. The control reads the hold as held; `pressed` and `released` wait for the next press. |
| `gateErrored` | The control's own gate raised. |
| `gateRefused` | The control's own gate answered no. |
| `noBindingForDevice` | The control declares no binding for any device class this session has. |
| `belowDeadzone` | The devices produced a reading and the control's own deadzone zeroed it. |
| `noSubscriber` | The control is delivering and nothing subscribed to it. |
| `atRest` | The control is live and its devices are not being driven. |
| `delivering` | The control is delivering its value to its subscribers. |
`atRest` and `unknownControl` are the two an outside reader could never tell
apart: a value reader answers `0` for both. This is where they separate.
## Which layer answered
Three naming layers coexist: the live maps' controls, and the `Zin.actions`
and `Zin.axes` registries a control asset replaced. Their name sets are
separate — `toolMove` is a live control and not an action, `move_forward` is
an action and not a control — so a name that is live in one reads as silence
in the others. Every answer carries `layer` (the one that answered) and
`carriedBy` (every layer that has the name at all).
## One control, everything about it
```luau
Zin.observe.control("move")
--> {
-- name = "move", live = true, carriedBy = { "scheme" },
-- entries = { { map = "default", kind = "axis2", subscribers = 1,
-- gated = false, classes = { kbm = {...}, gamepad = {...} } } },
-- lastTick = { value = { x = 1, y = 0 }, active = true, delivered = true },
-- why = { reason = "delivering", ... },
-- }
```
## The frame
```luau
Zin.observe.frame()
--> { frameId = 41207, window = "one tick of binding dispatch — the most
-- recent one", context = "default", maps = {...}, controls = {...},
-- cost = { frameId = 41207, maps = 3, controls = 27, ms = 0.09 } }
```
The window is **one tick** — the most recent one — rather than a sum since
anything last looked, and reading takes nothing away from the next reader.
Two observers in the same frame both get the truth.
`cost.ms` is that one tick's own milliseconds. The same number lands in
`profiler.stats("*zin.scheme.advance*")` as `script.zin.scheme.advance`,
where it carries the average and the peak across every tick as well.
## Reading it without running a script
`/runtime/input` serves the same answers as a file, beside the engine's own
account of the frame's device events:
```
/runtime/input the whole document
/runtime/input/events the frame's device events, each with `consumed_by_ui`
/runtime/input/device pointer lock, UI focus, the session's device classes
/runtime/input/mapping this module's account of the tick
/runtime/input/controls/<name> one control's entry from that account
```
`input.observe()` returns the same document to a script.
Building this layer's half costs a frame of work, so it is built only while
something is reading: a read of either surface arms it for a window of
frames, and the document's `mappingStatus` says whether the half it carries
is `current`, `stale`, `arming` (this read armed it — read again), or
`unarmed`. `Zin.observe.armedFrames()` is how many frames that window has
left; each frame that passes takes one off it, and the per-frame publish
spends the window rather than renewing it, so it runs out once the last
reader stops asking. A window that runs out — or that `Zin.observe.arm(false)`
closes — drops the report the engine was carrying with it, so a frame nobody
observes costs what it cost before anything ever read. `Zin.observe.arm(true)`
holds it open for a tool that wants it continuously.
## Which frame an answer covers
`Zin.observe.frame()` and `Zin.observe.control()` report the most recent
tick of binding dispatch. `Zin.observe.whySilent()` resolves against the
devices as they are at the moment of the call, so it answers for a control
the tick has never reached and for a name that does not exist.
The engine publishes its own half at the end of a frame, after the frame has
been drawn and before the frame's events are cleared. A read taken from a
script during frame N therefore answers for frame N-1.
▲ 0↑ born
# pointer
Pointer-lock mutation API. Wraps the internal
`__zero_input.requestPointerLock` / `releasePointerLock` primitives and
backs `Zin.pointer`. The read side lives on `Zin.state.pointerLocked()`;
this module owns the write side plus a convenience read alias.
## Exports
- `M.lock()` — request pointer lock (cursor grab + hide). Native takes effect immediately; WASM queues for the next user gesture.
- `M.unlock()` — release pointer lock (cursor ungrab + show).
- `M.locked() -> boolean` — convenience read alias, identical to `Zin.state.pointerLocked()`.
## Usage
```luau
local Pointer = require("@builtin::modules.zinput.pointer")
Pointer.lock()
if Pointer.locked() then
-- pointer captured
end
Pointer.unlock()
```
## Notes
- Native: `lock()` takes effect immediately. WASM: queued for the next
user gesture (browser policy). Both routes share the same underlying
FFI mutation; the platform enforces the difference.
- Write side and read side are intentionally split: `Zin.state.pointerLocked()`
stays alongside the rest of the per-frame snapshot accessors; mutation
lives here for discoverability.
- All entry points are no-ops when the `__zero_input` FFI is absent
(off-host script execution).
▲ 0↑ born
# profile
Binding profile registry — bundles of named actions / axes / chords that
can be loaded from `@builtin::profiles.<name>` Luau modules or saved as
JSON under `/zero/profiles/<name>.json`. Activating a profile
reconfigures `Zin.actions` / `Zin.axes` / `Zin.chords` in one shot. The
active profile is per-client session state held in memory — each session
resolves it fresh from the device-appropriate default (or an explicit
`activate`), so it is never written to the world source tree.
This is the persistence and activation layer for those three registries;
`Zin.map.activate` applies a materialized map through it. A scheme is
authored as an `.inputMap` of `.inputBinding` controls and goes live
through `Zin.scheme` — `man topics/input` covers that path.
## Exports
- `M.register(name: string, profile: any) -> (boolean, string?)` — validate + register a profile descriptor.
- `M.load(name: string) -> (boolean, any?)` — load + register a profile from `@builtin::profiles.<name>` or `/zero/profiles/<name>.json`.
- `M.activate(name: string, opts: ActivateOpts?) -> (boolean, string?)` — apply a profile's sections + set the active name for this session.
- `M.current() -> string?` — active profile name for this session, or nil.
- `M.get(name: string?) -> any?` — descriptor for the active profile or the named profile.
- `M.ensureActive(fallback: string?) -> (boolean, string?)` — bootstrap helper for controllers.
- `M.save(name: string, opts: SaveOpts?) -> (boolean, string?)` — capture current Zin.actions / Zin.axes / Zin.chords to JSON.
- `M.delete(name: string) -> (boolean, string?)` — remove a user profile's JSON file (built-ins refused).
- `M.export(name: string, vfsPath: string) -> (boolean, string?)` — write a serializable JSON snapshot to any VFS path.
- `M.import(vfsPath: string, opts: ImportOpts?) -> (boolean, string)` — read + register a profile JSON from any VFS path.
- `M.list() -> { string }` — sorted union of built-in + user profile names.
- `M.onChange(cb: ChangeCallback) -> number` — subscribe to activation / re-register events; returns a handle.
- `M.off(handle: number)` — drop a subscription.
- `M._reset()` — test-only: clear in-memory state.
Types:
- `Profile = { name, description?, actions?, axes?, chords?, intentional_pairs? }`
- `ActivateOpts = { reactivate: boolean? }`
- `SaveOpts = { description: string?, overwrite: boolean? }`
- `ImportOpts = { overrideName: string?, activate: boolean? }`
- `ChangeCallback = (string, any) -> ()`
## Usage
```luau
local Profile = require("@builtin::modules.zinput.profile")
Profile.register("my-bindings", {
name = "my-bindings",
actions = { jump = { context = "default", bindings = { { kind = "key", code = "Space" } } } },
})
Profile.activate("my-bindings")
local h = Profile.onChange(function(name) print("active:", name) end)
Profile.off(h)
```
## Notes
- Built-in profiles ship as Luau modules at `@builtin::profiles.<name>`
and can include functions (gate, curve). User profiles are pure JSON
at `/source/profiles/<name>.json` — function fields are dropped on save.
- Activation is no-op when the requested name is already active unless
`opts.reactivate = true`.
- `save` / `export` VFS writes use the bare `/source/...` mount — the
`/zero/...` prefix is read-only and silently drops writes.
- The conflicts module's `_setPersistFn` hook is wired here so
mark/unmark of intentional pairs persists into the active user
profile automatically.
▲ 0↑ born
# quiesce
The dirty signal `Zin.tick`'s quiescence gate reads. A mutation of the
mapping layer's structure outside the tick itself — a map activation, a
context change, a virtual-control write, a forced surface class, a new axis
over an already-held key — calls `mark()`, and the tick runs a full pass
while a mark is pending. A tick with no pending mark and no live input
events skips its pass.
`mark()` raises the signal, `pending()` answers whether a full pass is owed,
and the generation pair (`generation()` / `ack(g)`) keeps a mark raised
DURING a full pass pending for the next one, so a mutation racing a tick is
never lost.
Internal to the zinput package: the mapping-layer modules mark it, the tick
drains it.
▲ 0↑ born
# rebind
Interactive binding-capture sessions. A session listens for the next
keyboard or mouse event and produces a binding descriptor; the host can
then `apply()` it back into a `Zin.actions` action or a `Zin.axes` axis.
Backs `Zin.rebind`. Drives the editor's Input tab rebinding UI and is
usable from any Luau code. Modifier-aware (captures `modKey` when
Ctrl/Shift/Alt is held) and timeout-bounded (default 30 s).
## Exports
- `M.begin(opts: BeginOpts?) -> Session` — start a capture session; subscribes to `Zin.events.on` and returns a session table.
- `M.cancelAll()` — cancel every live session.
- `M.liveCount() -> number` — number of capturing sessions still active.
- `M._advanceTime(dt: number)` — internal: per-frame timeout sweep wired by `Zin.tick`.
Types:
- `Session = { target, name, slot, mode, status, timeoutSec, result, consume, apply, cancel, conflicts, ... }`
- `Owner = { target: string, name: string, slot: any }`
- `BeginOpts = { target?, name, slot?, mode?, timeoutSec?, filter?, applyOnCommit?, onCommit?, ... }`
## Usage
```luau
local Rebind = require("@builtin::modules.zinput.rebind")
local s = Rebind.begin({
target = "action",
name = "jump",
timeoutSec = 10,
applyOnCommit = true,
onCommit = function(session)
print("captured:", session.result())
end,
})
-- The session subscribes itself; just wait for the next tick.
if s.status == "capturing" then
-- ...
end
```
## Notes
- Press Escape during a capture to cancel; a pure modifier press is
ignored (the session waits for the base key).
- A session that captures with Ctrl/Shift/Alt held returns a `modKey`
binding rather than a plain `key` binding.
- `session.conflicts()` is self-filtered — rebinding an action to a key
it already owns reports no conflict.
- Hot-reload safety: the live-sessions list survives require-cache
reload; the `_advanceTime` wiring from `zinput/init.luau` keeps
timeouts firing across re-requires.
- `applyOnCommit = true` calls `apply()` automatically after commit;
errors during apply are still visible via `result()` and
`conflicts()`.
▲ 0↑ born
# scheme
The live set of activated input maps, and the per-frame dispatch that turns
their bindings into the events a controller subscribed to. Backs
`Zin.scheme`.
## Nothing is live until something activates a map
A controller holds an `inputMap` ref, activates it when it takes control,
and releases it when it gives control up. The live binding set is exactly
the union of what current holders asked for, so an empty world has an empty
input surface and an empty screen — no scheme is active by default, and
nothing appears on a phone that no component consumes.
For a component that drives the thing it lives on, taking control and being
awake are the same moment, so `awake` / `onDestroy` are the hooks. For
anything a player enters and leaves — a car, a turret, a menu — they are
not: the car is still there after the player gets out, so the map goes live
on entry and stands down on exit.
```luau
public = {
inputMap = Field.assetRef("inputMap", "@builtin::inputMaps.default", NoSync, "The controls this component reads."),
speed = Field.number(5, NoSync, "World units per second at full deflection."),
jumps = Field.number(0, NoSync, "How many times the jump control was pressed."),
}
local controls
function awake()
controls = public.inputMap:activate()
controls.move:onInput(function(v, dt, active)
if not active then return end
local p = public.entity.position
local step = public.speed * dt
public.entity.position = { p.x + v.x * step, p.y, p.z - v.y * step }
end)
controls.jump:onPressed(function() public.jumps += 1 end)
end
function onDestroy()
public.inputMap:deactivate(controls)
end
```
What `activate` returned is this holder's **claim** on the map. Keep it and
hand it back: releasing the claim disconnects the subscriptions made through
it, and the map stays live for whoever else holds it.
A claim also ends with the context that opened it. A component's claim is
released when that component instance goes, whether or not it writes an
`onDestroy`: the component is removed from its entity, the entity despawns,
or the component hot-reloads (its new life's `awake` activates again). A
claim a module body opens ends at the module's next run. `scopes.list()`
names each standing claim as a `luau` row under the context it follows, and
`scopes.release(tag)` ends it with everything else that context holds.
## Several maps compose by all being live
The player's surface is the union of every live map, which is what a game
needs: picking up a gun activates a weapon map and Fire appears beside the
movement stick; dropping it takes away Fire and nothing else. Two
controllers that each activate a map with a movement stick produce two
sticks — visible, attributable to the second controller, and the importer's
to resolve.
Two components activating the *same* map read one set of controls, each
through its own claim. A claim's release disconnects what that holder
subscribed and leaves the other holders' handlers attached; the map leaves
the live set when its last claim goes. `Zin.scheme.live()` reports each live
map's `holders` — how many claims are still standing on it — and `heldBy`,
which says who each of them is: `kind` (`"component"` or `"execute"`),
`entity`, `source` as the `chunk:line` the activation was opened at, and the
`label` the caller passed to `activate("weapon-swap")`.
## An activation reads the map's children as they stand now
Every `activate` re-reads the map's `<name>.inputBinding/` children, so a
control added, edited or removed since the map came up reaches the running
set on the next activation. The controls are edited in place, so it reaches
the holders already standing on the map too: their handles keep working and
every subscription they made carries on across the edit.
## A map can stand another one down
Composition cannot say "not while this is happening". A map declares the
`group` its controls belong to and the groups it `suppresses` while live:
```luau
-- driving.inputMap/init.luau
return { group = "vehicle", suppresses = { "player" } }
```
Every live map in a suppressed group reads nothing and draws nothing for as
long as the suppressor is live. It is **not** released: it keeps its
holders, its handles and every subscription, and resumes untouched when the
suppressor goes. So a car stands down walking without ever finding, owning
or releasing the walk map — and a menu stands down the whole game with one
declaration.
A map that declares no `group` belongs to one named after itself, so it
collides with nothing and can still be named by something that wants to
stand it down. Declaring neither field composes with everything.
The drop frame runs on the tick a map stands down, so a stick held at that
moment reports its neutral value once and whatever it drove stops rather
than sticking.
## Dispatch
`_advance(dt)` evaluates every live binding once per tick, across every
device class it carries — a tablet with a keyboard attached and a desktop
with a pad plugged in both answer to whichever the player actually used,
rather than to a nominated primary.
| Event | Fires | Cadence |
|---|---|---|
| `input` | Once while the binding is active with `(value, dt, true)`, and once more on the frame it goes inactive with the neutral value and `false` | Per engine frame |
| `pressed` / `released` | A button's edges | Per engine frame |
| `changed` | When the value differs from the previous tick | Per tick |
`input` firing on the drop frame is what lets one handler both start and
stop the motion it drives, without a second subscription to notice the
release.
A frame carries more than one tick whenever a host calls `Zin.tick` beside
the tick the engine already runs, or fast-forwards several ticks to
converge smoothing. Evaluation follows the tick, so the smoothing lands and
`changed` reports each step of it. `input`, `pressed` and `released` are
stamped with the engine frame they were reported for, so the frame carries
one of each however many ticks ran in it. Both edge sources hold this
frame's edge for as long as the frame lasts: the input snapshot's `pressed`
flag, and `Zin.virtual`'s previous-frame button table. That is what a
second reporting pass reads as another press.
`Zin.scheme.fired`'s `count` is the number of engine frames a control was
active since it last cleared, so a button held across two frames reads 2
for one press. The `pressed` / `released` subscriptions are what count
edges.
A binding that declares a `context` is live only while that context is on
top, the same activity rule actions apply.
An `axis1` / `axis2` control's own `deadzone`, `curve`, `invert` and
`smoothing` are applied here, in that order, to the reading its classes
produced — after `as` / `unitsPerSecond` / `scale` have brought every class
into the control's unit, so one deadzone written in that unit covers the
stick, the mouse and the finger together. A deadzone is per value on an
`axis1` and **radial** on an `axis2`. The shaping maths is `Zin.utils`',
shared with the axis registry.
`smoothing` is the one piece of the four that is stateful: the value is
held per control across frames and approaches whatever the devices report
next over the declared time constant. A control that leaves its context,
whose group stands down, or whose gate closes has a neutral target, so it
drains rather than cutting — and reports its drop frame when it arrives.
## Validation happens before anything registers
Activation reads every child binding, collects every fault across all of
them, and raises once with the lot. A map with three broken bindings names
all three rather than one per attempt, and a map that fails validation
registers nothing — a half-live map is worse to debug than one that refused
to come up.
## Exports
- `M.activate(mapRef, label?) -> { [name]: Handle }` — activate a map,
return its handles. `label` names this activation in `M.live()`.
- `M.deactivate(mapRef) -> boolean` — release a claim on a map.
- `M.live() -> { { guid, name, group, suppresses, suppressedBy, holders,
heldBy, bindings } }` — every live map in activation order. What tells an
author why two sticks are on screen, or why the controls they activated
answer to nothing, or who is holding the map standing them down.
- `M.bindings() -> { { map, group, name, label, kind, context, suppressedBy,
subscribers, record } }` — every live binding in activation order. The
touch overlay builds from this, so what is on screen is exactly what some
awake component asked for and nothing is standing down.
- `M.suppressed() -> { [group]: mapName }` — which groups are standing down
and what put each one down.
- `M.has(name) -> boolean` — whether a named control is live anywhere.
- `M._advance(dt)` — one tick of dispatch; wired into `Zin.tick`.
- `M._childBindings(mapRef) -> { ref }` — the map's `.inputBinding`
children, in name order.
- `M._reset()` — test-only: drop every live map without firing anything.
Types:
- `Handle = { onInput, onPressed, onReleased, onChanged, label, kind }` —
a thin view over the binding asset's own event facade, so a subscription
made through a handle is the same one `ref.events.input:connect` would
make and ends the same way.
▲ 0↑ born
# state
Synchronous per-frame input state. Thin wrapper over the internal
`__zero_input.snapshot()` FFI; backs `Zin.state`. Pointer-lock mutations
live on `Zin.pointer`; the read-side `pointerLocked()` query lives here
with the rest of the snapshot accessors. Held-time and synthetic-repeat
state is owned by this module and updated via `_observeEvent` from the
`Zin.tick` coordinator.
## Exports
- `M.get() -> Snapshot` — full per-frame snapshot table; empty when the FFI is unavailable.
- `M.keyDown(key: string) -> boolean` — held this frame.
- `M.keyPressed(key: string) -> boolean` — edge-pressed this frame.
- `M.keyReleased(key: string) -> boolean` — edge-released this frame.
- `M.mousePosition() -> (number, number)` — current mouse `(x, y)`.
- `M.mouseDelta() -> (number, number)` — `(dx, dy)` since last frame.
- `M.scrollDelta() -> number` — wheel delta this frame.
- `M.mouseButtonDown(idx: number?) -> boolean` — held; default idx = 0.
- `M.mouseButtonPressed(idx: number?) -> boolean` — edge-pressed.
- `M.mouseButtonReleased(idx: number?) -> boolean` — edge-released.
- `M.pointerLocked() -> boolean` — pointer-lock query (writes are on `Zin.pointer`).
- `M.uiWantsPointer() -> boolean` — `true` when the UI layer claims pointer focus.
- `M.uiTookPress() -> boolean?`: `true` while a UI widget sensing a click or a drag holds the pointer press in progress; `false` with no press held and for a press on empty space; `nil` from the moment a press arrives until a UI pass has decided it.
- `M.setRepeatDefaults(opts: RepeatOpts?)` — set default delay / period for synthetic repeat.
- `M.getRepeatDefaults() -> RepeatDefaults` — read the active synthetic-repeat defaults.
- `M.keyHeldTime(code: string) -> number?` — seconds since the key was pressed (or nil).
- `M.mouseButtonHeldTime(idx: number?) -> number?` — seconds since a mouse button was pressed.
- `M.keyRepeatFired(code: string, opts: RepeatOpts?) -> boolean` — should a synthetic key-repeat fire this frame?
- `M._observeEvent(ev: any)` — internal: per-event observer, wired from the tick coordinator.
- `M._reset()` — test-only: clear held-time and synthetic-repeat state.
Types:
- `Snapshot = { [string]: any }`
- `RepeatOpts = { delay: number?, period: number? }`
- `RepeatDefaults = { delay: number, period: number }`
## Usage
```luau
local State = require("@builtin::modules.zinput.state")
-- Rebind-capture-style probe: how long has a key been held, and is a
-- synthetic repeat due this frame?
local heldFor = State.keyHeldTime("Space")
if heldFor and State.keyRepeatFired("Space", { delay = 0.4, period = 0.08 }) then
-- charge-attack tick, key-repeat menu navigation, etc.
end
```
## Notes
- Mouse-button indices are 0-based and follow `InputResource.mouse_buttons[]`
(0=left, 1=right, 2=middle). Winit's `0=L, 1=M, 2=R` is converted in Rust
before reaching Luau.
- `mousePosition` / `mouseDelta` return two numbers, not a table.
- Held-time / repeat state is updated by the `Zin.tick` coordinator via
`_observeEvent` — without a tick, those queries return `nil` / `false`.
- `keyRepeatFired` advances state on every call — call once per frame per
consumer.
- All entry points are no-ops or return zero values when `__zero_input` is
missing (off-host execution).
- Gameplay subscribes to controls through an activated `.inputMap`; this
module is the raw snapshot layer those bindings evaluate against, used
directly by rebind capture, the emulation floor, and dev tooling.
Polling it from a world makes that world keyboard-only and draws the
`engine-raw-key-poll` diagnostic at author time.
▲ 0↑ born
# surface
Active input-surface classification. Answers "what device class is the
player using right now" — `"touch"` or `"kbm"` — and notifies on
change; backs `Zin.surface`. Virtual touch controls mount whenever the
surface is `"touch"`, in edit and play alike.
## The frame rule
Resolution runs once per engine frame from the `Zin.tick` pipeline: a
per-event observer collects which device classes produced events this
frame, and the frame resolver applies one rule — **touch wins a frame
that contains any touch event**. The primary touch contact also drives
the mouse path (a projected `mouse.down`/`move`/`up` in the same
frame), so classifying by the latest single event would flip to `kbm`
on every tap; the frame rule keeps projection-generated mouse events
from masking the touch that caused them.
## Capability default
Before any input arrives, the class defaults to `"touch"` on sessions
with a touch source (`touch_capable` — latched by the first contact or
declared at boot by Android / the web client) and `"kbm"` otherwise, so
touch-first devices present touch controls from the first frame.
## Exports
- `M.current() -> string` — the active surface class, `"touch"` or `"kbm"`.
- `M.onChange(fn: (string, string?) -> ()) -> number` — subscribe to class flips; `fn(now, prev)` where `prev` is the previously reported class (the first-tick capability default when no event had resolved yet). Returns a handle.
- `M.off(handle: number) -> boolean` — unsubscribe an `onChange` handle.
- `M._beginFrame()` — internal: clear this frame's per-class flags; wired by `Zin.tick`.
- `M._observeEvent(ev: any)` — internal: per-event observer; wired by `Zin.tick`.
- `M._resolveFrame()` — internal: resolve this frame's class and fire `onChange` on a flip; wired by `Zin.tick`.
- `M._reset()` — test-only: clear resolution state and subscriptions.
Types:
- `SurfaceClass = "touch" | "kbm"`
## Usage
```luau
local Surface = require("@builtin::modules.zinput.surface")
if Surface.current() == "touch" then
showTouchOverlay()
end
Surface.onChange(function(now, prev)
print("surface flipped to", now)
end)
```
## Notes
- `onChange` fires from the `Zin.tick` pipeline on the frame the class
flips; without a tick, resolution never advances and `current()`
keeps returning the capability default.
- The change signal compares against the last reported class, whose
initial value is the capability default captured on the first tick of
the session — a phone's first contact confirms the default silently,
while a desktop touchscreen's first contact reports kbm→touch.
- Handler errors during `onChange` dispatch are caught and logged, not
propagated.
▲ 0↑ born
# test
Test-input helpers that simulate keyboard / mouse / scroll events and
yield one engine frame so the queued events drain into the next
snapshot. Backs `Zin.test`. Helpers do NOT call `Zin.tick()` —
explicit dispatch control is left to the caller.
## Exports
- `M.runFrame()` — yield one engine frame so simulated events drain.
- `M.pressKey(code: string)` — hold the key DOWN and leave it held. A second
`pressKey` on a held key produces no new press edge — pair every `pressKey`
with a `releaseKey`, or use `tapKey` for a full press.
- `M.releaseKey(code: string)` — simulate a key release.
- `M.tapKey(code: string, duration: number?)` — press + optional hold +
release. The helper for "the player taps a key".
- `M.pressMouse(button: (number | string)?)` — simulate a mouse button press
(default 0 = left). The index and the name (`"left"`/`"right"`/`"middle"`)
reach the same button.
- `M.releaseMouse(button: (number | string)?)` — simulate a mouse button release.
- `M.clickMouse(button: (number | string)?, x: number?, y: number?, duration: number?)`
— full click, optionally moving the cursor to `(x, y)` first and holding for
`duration` seconds.
- `M.moveMouse(x: number, y: number)` — set absolute cursor position.
- `M.moveMouseBy(dx: number, dy: number, steps: number?)` — move the pointer by
a relative motion. The motion lands in this frame's `mouse_delta` and the
position advances by the same amount, so the same `(dx, dy)` repeated keeps
producing look movement. `steps` spreads it over that many frames, each
carrying its share; 1 when omitted.
- `M.scroll(dy: number)` — simulate a wheel scroll.
## Usage
```luau
local Test = require("@builtin::modules.zinput.test")
Test.tapKey("KeyM") -- press + release
Zin.tick(1 / 60) -- explicit dispatch
assert(#Zin.scheme.fired() > 0)
Test.pressKey("Space") -- key goes DOWN and stays held...
Zin.tick(1 / 60)
Test.releaseKey("Space") -- ...until released
Test.clickMouse(0, 100, 200)
```
## Notes
- Each helper queues the simulated event and yields one frame
(`task.wait(0)`) so the snapshot reflects the input on return.
- Simulated key state persists like real key state: after `pressKey` the key
stays held until `releaseKey`, and only the release re-arms the next press
edge. `tapKey` is the edge-per-call helper.
- Helpers do NOT call `Zin.tick()` — a test that relies on a control's
handlers, or on `Zin.input.on*` / `Zin.actions.bind`, must run a tick
itself. `Zin.scheme.fired()` is what turns a simulated input into an
assertion: it reports which controls fired since it last read, and from
which device class.
- Mouse button index is 0-based (0=left, 1=right, 2=middle) following the
`InputResource.mouse_buttons` convention.
- All helpers are no-ops when the `__zero_input.simulate*` FFI is missing
(off-host execution).
▲ 0↑ born
# text
Requiring this module raises a fatal error: `zinput.text` is not
available in this build.
## Exports
None — the module raises on `require`.
▲ 0↑ born
# 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
```luau
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).
▲ 0↑ born
# 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 pixels contacts arrive in), and a
contact beginning inside one drives no pointer: no widget beneath the
button is pressed by it, and no mouse button reads held.
- A contact that begins anywhere else drives the pointer as the primary
contact always does, and the UI decides whether a widget takes its press.
When one does, the contact is the widget's: on the tick after it began, the
stick or look zone that took it lets it go before it has moved anything.
- 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 framebuffer pixels — `InputResource` keeps the raw platform
coordinates unconverted, the same space `getViewportSize()` reports. 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.
## 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.
- **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 itself is
unconditional: it runs every tick regardless of mount state, so a forced or
real touch always drives `Zin.virtual` even before the overlay is visible.
## 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:
```luau
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)`.
## 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
primary contact. `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.
- `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, each entry `{ id, label, actionName, priority, size,
appliedSize, group, cx, cy, radius }` in `ui.screenSize()` space — `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.
▲ 0↑ born
# utils
Pure helpers for the `Zin` input library. Mouse-button name↔index
conversion, key-code normalization, held-modifier matching against a frame
snapshot, and the shaping a reading passes through on its way to a
consumer. No FFI; safe to call from any context. Stateless.
## Exports
- `M.buttonName(idx: number) -> string?` — convert a 0-based mouse button index to its name.
- `M.buttonIndex(name: string) -> number?` — convert a mouse button name to its 0-based index.
- `M.normalizeKey(code: string) -> string` — canonicalize a key code: a single ASCII letter becomes its `Key<L>` code, a single digit its `Digit<N>` code; multi-character codes pass through.
- `M.matchModifiers(snapshot: Snapshot, mods: Modifiers) -> boolean` — test whether the snapshot's held keys match the requested modifier set.
- `M.applyCurve(curve, x: number) -> number` — apply a response curve to a reading.
- `M.applyDeadzoneScalar(x: number, deadzone: number?) -> number` — 0 below the threshold, the reading at or above it.
- `M.applyDeadzoneVector(v: Vector2, deadzone: number?) -> Vector2` — the same, measured **radially** on the magnitude of the pair.
- `M.shapeScalar(x: number, deadzone: number?, curve, invert: boolean?) -> number` — deadzone, then curve, then inversion.
- `M.shapeVector(v: Vector2, deadzone: number?, curve, invert: boolean?) -> Vector2` — the same for a pair.
- `M.smoothToward(current: number, target: number, dt: number, tau: number) -> number` — one step of an exponential approach with time constant `tau`.
A `curve` is `"linear"`, `"quadratic"`, `"cubic"`, a function of the
reading, or `nil` for linear.
Types:
- `Snapshot = { [string]: any }` — the raw frame-snapshot table returned by `Zin.state.get()`.
- `Modifiers = { ctrl: boolean?, shift: boolean?, alt: boolean? }` — modifier subset to require in `matchModifiers`.
- `Vector2 = { x: number, y: number }` — a two-component reading.
## Shaping
The order is deadzone, curve, invert, then the approach toward the shaped
target. A scalar takes its deadzone per value; a pair takes it radially, so
a diagonal is not clipped into a cross by two independent thresholds.
`"quadratic"` squares while keeping the sign, so a half-pushed stick reads
a quarter in the direction it was pushed. A curve function that raises, or
answers with anything other than a number, leaves the reading as it was.
This is the one implementation of that shaping: `Zin.axes` reads it for a
registered axis and `Zin.scheme` for an `axis1` / `axis2` control, so an
axis and a control declaring the same numbers read the same.
## Usage
```luau
local Utils = require("@builtin::modules.zinput.utils")
local name = Utils.buttonName(0) -- "left"
local idx = Utils.buttonIndex("right") -- 1
local key = Utils.normalizeKey("w") -- "KeyW"
local hit = Utils.matchModifiers(snap, { ctrl = true, shift = false })
```
## Notes
- Pure functions — no state, no side effects.
- Mouse-button indexing is 0-based and matches `Zin.state.mouseButtonDown(idx)` (0=left, 1=right, 2=middle).
- `matchModifiers` ignores fields set to `nil` in `mods` — only `true`/`false` are constraints.
- `normalizeKey` rejects any other single character: no bound key code is
one character long, so `"?"` raises rather than resolving to a phantom
key nothing consumes.
▲ 0↑ born
# virtual
Per-tick virtual-control values. On-screen controls (and tests) write stick
vectors, button states, and drag deltas here; the `touchStick` / `touchButton`
/ `touchDrag` / `touchPinch` binding kinds in `Zin.bindings` read them. Backs
`Zin.virtual`.
Three families, each keyed by the control's binding identity:
- **Sticks** — zone string (`"left"`, `"right"`, ...). A vector clamped to
`[-1, 1]` per component, persisting until set again or reset.
- **Buttons** — id string: a `touchButton`'s `id` (stamped with the
control's name when its map activates), else its `label`, else its
`zone`. A held boolean; `buttonPressed` / `buttonReleased` derive edges
from the previous frame boundary.
- **Drags** — zone string. A delta vector that accumulates within a tick
(`addDrag` sums repeated calls) and clears at the next frame boundary —
the same per-frame-delta semantics as `Zin.state.mouseDelta()`.
## Edge-at-frame-boundary semantics
`_beginFrame()` shifts `_buttons` into `_buttonsPrev` and clears drag deltas.
It runs once per engine frame from the `Zin.tick` coordinator's gated begin
block, before any binding evals happen. On-screen overlay code (script phase)
calls `setButton` earlier in the same frame it wants the press recognized;
`buttonPressed` reads true starting the frame `_beginFrame` next observes the
transition — matching how a real key's press edge surfaces on the frame
after the OS event, not the same frame the write happened.
## Exports
- `M.setStick(zone: string, x: number, y: number)` — set a stick's vector (clamped).
- `M.stick(zone: string) -> (number, number)` — read a stick's `(x, y)`; `(0, 0)` when unset.
- `M.setButton(id: string, held: boolean)` — set a button's held state.
- `M.button(id: string) -> boolean` — held state.
- `M.buttonPressed(id: string) -> boolean` — press edge this frame.
- `M.buttonReleased(id: string) -> boolean` — release edge this frame.
- `M.addDrag(zone: string, dx: number, dy: number)` — accumulate a drag delta.
- `M.drag(zone: string) -> (number, number)` — read a zone's accumulated `(dx, dy)` this frame.
- `M._beginFrame()` — internal: frame-boundary edge shift + drag clear, called by `Zin.tick`.
- `M._reset()` — test-only: clear all virtual state.
## Usage
```luau
local Virtual = require("@builtin::modules.zinput.virtual")
Virtual.setStick("left", 0.4, -0.9)
local x, y = Virtual.stick("left")
Virtual.setButton("Jump", true)
if Virtual.buttonPressed("Jump") then
-- fires once, on the frame after the set
end
```
▲ 0↑ born
# luau_introspect (module)
Parses Luau/asset source TEXT into structured declarations. Pure
string/pattern parsing (`string.find` / `string.match` / `string.gmatch`)
over the literal source — no compiling, no VM spawn, no runtime state, no
engine FFI. Given source text, it extracts what is written in the file.
This is the shared parser every per-assetType `M.ref.inspect` hook uses to
turn a component/module/tool's own source into the structured record
`asset.inspect` returns.
## Exports
- `docstrings(src) -> DocMap` — scans `--!desc` / `--!arg` / `--!return` /
`--!example` comment runs and binds each run to the name of the
declaration on the next non-comment line (the identifier after
`function`, `public:`, `local function`, or `M.`).
- `publicFields(src) -> { FieldEntry }` — parses `public = { name =
Field.<kind>(default, mode), ... }` table-literal entries and
module-scope `public.<name> = Field.<kind>(...)` assignments.
- `events(src) -> { EventEntry }` — parses `events = { name =
Event(payloadSchema?, syncMode?), ... }` table-literal entries.
- `methods(src) -> { MethodEntry }` — parses `function public:<name>(...)`
/ `typed function public:<name>(...)` declarations (params + optional
return type).
- `lifecycleHooks(src, catalog) -> { string }` — top-level `function
<name>(` declarations whose name is in the caller-supplied `catalog`
array.
- `moduleExports(src) -> { ExportEntry }` — parses `M.<name> = function`
assignments, `function M.<name>(...)` declarations, and a trailing
`return { foo = foo, ... }` export table.
- `forSource(src, computeFn) -> any` — memoises `computeFn(src)` keyed on
`src` itself in a module-local table. The same source text returns the
cached result without re-running `computeFn`; different source text
recomputes. Keyed on the source content (not an asset checksum) because
composite/container assets (component folders, scene folders, etc.) all
hash to the empty-string checksum — a checksum-keyed cache collapses
every such asset's detail onto whichever one was inspected first.
## Usage
```luau
local Introspect = require("modules.luau_introspect")
local src = self:getInitScript()
local detail = Introspect.forSource(src, function(s)
return {
fields = Introspect.publicFields(s),
events = Introspect.events(s),
methods = Introspect.methods(s),
hooks = Introspect.lifecycleHooks(s, lifecycleCatalog),
}
end)
```
## Notes
- Every function is a pure string→table transform: same source text in,
same structured table out, every time. No reads of live component
state, no entity/world queries.
- Structural scanning runs over a comment- and string-aware **mask** of
the source (a same-length copy where comment bodies and string-literal
contents are blanked to spaces, delimiters and newlines preserved).
Pattern matches and brace/paren balancing run on the mask — so a brace,
`Field.`, `Event(`, or a whole entry that appears inside a comment or a
string literal never registers — while captured values are sliced from
the original source at the same (aligned) indices. This makes the
parser robust to apostrophes in comments, commented-out entries, string
defaults containing `}` / `Field.` / `Event(`, and `[[ ]]` long
strings.
- `default` / `category` are raw trimmed source-text slices (with any
trailing comment stripped), not evaluated values.
- For a **ref constructor** (`Field.assetRef` / `dataRef` / `resource`
/ `componentRef`) the FIRST positional argument is the category /
contract / componentType selector, captured under `category`; the
SECOND argument is captured under `default`.
- For every **other** Field kind the first argument is the `default`
and `category` is nil.
- A trailing `Sync` / `NoSync` identifier is captured as `sync`,
tolerating a trailing comma or a trailing comment after the last
argument.
- Field/Event entries whose key is a computed or indirect expression
(`[expr] = Field.number(...)`) are omitted — only literal identifier
keys are recognised.
- `methods` captures a `...` variadic parameter (as `name = "..."`), with
its `: <type>` annotation when present.
- A `--!desc` written above a field/event declaration (`<name> =
Field.<kind>(...)` / `<name> = Event(...)`) or a `public.<name> =`
assignment binds to that name in `docstrings`, and is folded into the
corresponding `publicFields` / `events` entry's `desc`.
- `lifecycleHooks` never hardcodes the lifecycle-callback catalog; the
caller passes the list of names to match against.
- `forSource`'s memo is bounded (oldest-key eviction) so a long session
touching many distinct asset versions can't grow it without limit.
▲ 0↑ born
# assetType.shared.settings
Resolves four questions about an asset's typed settings, all answered from its
type's `type.yaml` — nothing here is found by convention.
```lua
local Settings = require("@builtin::assetTypes.assetType.shared.settings")
-- or, from inside the assetType runtime:
local Settings = require("@builtin::assetTypes.assetType.shared").settings
```
## Where does a type's schema live?
`type.yaml` names it in a `settings:` block:
```yaml
settings:
values: "settings.yaml" # where an instance's own values live
schema: { type: "settings.luau" } # one schema for every asset of this type
```
or, for a type whose settings differ per instance (an importer):
```yaml
settings:
values: "settings.yaml"
schema: { instance: "settings.luau" }
```
or, for a type whose schema is a table its instance's own source declares and
whose values live elsewhere (a component: its `public` fields, valued on each
entity it is on):
```yaml
settings:
schema: { instance: "init.luau", export: "public" }
```
Whether an instance may lack its schema file is what the type's `files:`
block says of that file. Listed under `files.optional`, it may be absent, and
an instance without it declares no settings — the importer type lists it
there, since most importers take none. Listed under `files.required`, or not
listed at all, it must load, and an instance missing it is a broken
declaration and is logged.
`schema.type` is required at the folder relative to the TYPE's own
`.assetType/` directory (one schema shared by every instance).
`schema.instance` is required relative to each INSTANCE's own folder (`init`
resolves the instance's own identity; anything else is a sibling module under
it). Without `schema.export`, the file is required as a module and its return
value IS the schema. With `schema.export`, the file is run in an environment
of its own and `export` is read from a returned table carrying it, or else
from the globals the file assigned — a component's `public` is such a global.
That environment reads through to `_G` and takes every write itself; its own
`_G` is itself, its `declare` and `computed` record into it, and its `task`
records spawned, deferred and delayed work instead of starting it. Every other
global is the real one, so a call the file makes through one runs as it does
anywhere. The schema is the declared table's Field descriptors. A schema that
resolves to nothing says why through `Settings.schemaProblemOf(ref)`: the file
could not be read, compiled or run, or declared no such table. An instance
schema is read again when its file, its type's `type.yaml`, or the entry file
of any module the asset `require`s changes. `Settings.blockFor(typeName)`
returns the raw block; `Settings.schemaForType(typeName)` and
`Settings.schemaOfInstance(ref)` resolve the two schema shapes respectively;
`Settings.schemaFor(ref)` tries the type-level schema first, falling back to
the instance-level one. `ref` naming an assetType asset itself — e.g.
`asset.resolve("texture", "assetType")`, rather than an instance of it —
reports that type's own declared schema, the same one every instance of it
reports.
## Where do an asset's values live?
`settings.values` names a file living beside the asset's own content —
`Settings.valuesPathOf(ref)` joins it onto the asset's path.
`Settings.valuesOf(ref)` / `Settings.writeValues(ref, values)` read and write
it; this module only names where it is. A type that declares its schema with
no `settings.values` keeps no values in the asset — a component's live on each
entity it is on — so `valuesOf` answers nil for it, `asset.create` refuses a
`settings` table for it, and `asset.setSettings` refuses a write.
`Settings.recordedWrite(path, text)` writes a file the way every values file
is written, and an editor uses it for any other file it writes. It writes the
whole contents, records the write into the open undo operation when one is
open (so undoing it restores what the file held), and raises when the write
does not land.
## In what order are a schema's fields declared?
Every `Field.*` constructor stamps its descriptor with `declaredOrder`, one
more than the last. Luau evaluates a table constructor's entries in the order
they are written, so `Settings.orderedNames(schema)` lists a schema's fields —
and a struct's subfields — in the order the source writes them.
A values file, or a legacy `.metadata` settings block, may hold an older
spelling — a renamed field, an older enum member. Every read passes what is
stored through the type's `normalizeSettings` (`Settings.normalizeFor`), so
it answers in the fields the schema declares today, and writes nothing. The
next local edit of that asset rewrites the file in the declared spelling
(`Settings.healLegacyIfNeeded`).
`asset.setSettings(ref, patch)` writes a partial patch:
`Settings.resolvePatch(ref, patch)` normalises it, merges it over the current
values and applies the type's derived defaults for the fields it changed, and
`Settings.writeValues(ref, values, patch)` applies the corrections, checks the
schema and writes the file.
## How is a new asset's settings resolved at creation?
`asset.create` calls `Settings.resolveForCreate(typeName, name, destPath,
creationOpts, callerSettings, importerSettings)` before running the type's
`onCreate`, checks the result against the schema, writes it to the values
file, and hands `onCreate` a COPY of it as `opts.settings` (`Settings.
cloneValues`) — never the same table the values file gets, so nothing
`onCreate` does to its own copy can reach what was stamped. `onCreate` reads
settings from `opts.settings` and never writes to it. `asset.create` also
seeds the change baseline with the stamped values
(`Settings.seedChangeBaseline`), so the values file's own first dispatch
reports nothing changed and the payload `onCreate` encoded is the only
encode a create runs.
The layers, lowest priority first, each overriding the ones before it field
by field:
1. The schema's own declared defaults (`Settings.defaultsOf`).
2. The type's own `settingsDefaults(name, opts, asked)` hook, when its
`behavior.luau` exports one. `asked` holds what layers 3 to 5 name, so a
default can follow a field one of them sets.
3. The Preset Manager's matching row (`Settings.presetLayerFor`).
4. The creating importer's settings for this type.
5. The `settings` table the caller passed to `asset.create`.
6. The type's own `settingsDerivedDefaults(values, explicit, changed)` hook,
when its `behavior.luau` exports one — a field whose default follows
another field, set only when no layer from 2 to 5 named it.
7. The type's own `settingsCorrections(values, name, opts)` hook, when its
`behavior.luau` exports one — applied last, once every other layer has
merged.
Layers 2 to 5 are each read through the type's `normalizeSettings`, so a
layer naming a field in an older spelling sets the field it names today.
`asset.create`'s top-level settings alias accepts those older names too
(`Settings.acceptedFieldNames`).
Layer 7 is `Settings.applyCorrections(typeName, values, explicit, context)`,
the one corrections path every settings write takes — this create chain, and
`Settings.writeValues` for every later write (`asset.setSettings`, a type's
first-encode seed, the legacy heal). `explicit` names the fields the writer
asked for: the caller's `settings` table here, the patch for
`asset.setSettings`. A correction lands SILENTLY on a field the writer did not
name — nobody asked for that value, so overriding it just states a fact. A
correction that contradicts a field the writer named REFUSES the write,
naming the field, the value asked for, and why it cannot hold — the same as
every other place this codebase refuses an explicit request it cannot satisfy
(a `Field.checkSchema` violation, a BC7 alignment error) rather than silently
rewriting it into something else. So `asset.setSettings(tex, { compression =
"rgba16" })` on a mipped texture stores `generateMipmaps = false` beside it,
while `asset.setSettings(tex, { compression = "rgba16", generateMipmaps = true })`
is refused.
`Field.checkSchema` runs once, over the result AFTER the corrections hook has
applied — a bad value nothing corrects refuses the creation.
### Four hooks, four different jobs
Every hook is an optional export on a type's `behavior.luau`, alongside
`onCreate` / `onChange`. **None is ever handed a table to mutate** — each
reads what it's given and RETURNS a table of what it wants changed (or nil);
`resolveForCreate`, `resolvePatch`, `applyDerivedDefaults` and
`applyCorrections` are the only places that write to the values, by merging
what a hook returns the same way every other layer merges.
- **`normalizeSettings(values) -> values`** maps every older spelling a
stored file or a write may carry to the field and member the schema
declares now, returning a new table; a table naming both an older field
and its replacement keeps the replacement. The companion export
**`normalizedSettingNames = { ... }`** lists the older field names it
accepts beyond the schema, so a write naming one is not refused as an
undeclared field. `texture.assetType`'s maps the fields its earlier schema
stored to `colorSpace` + `compression`, and the older `filter` keywords to
`linear` / `nearest`.
- **`settingsDerivedDefaults(values, explicit, changed) -> partial?`**
answers the values of fields whose default follows another field. At
creation `changed` holds every field; on a write it holds the fields the
write moved. A returned field applies only where `explicit` — the fields
the writer named — does not name it.
- **`settingsDefaults(name, opts, asked) -> partial?`** supplies a DEFAULT
the schema itself has no syntax for — something only knowable at creation
time, like a naming convention, a fact read off a payload the caller handed
in, or a value that follows a field a higher layer sets (`asked` holds what
the Preset Manager, the importer and the caller name, the higher one's
value where two name a field). It runs early (layer 2 above), so any later
layer — Preset Manager, importer, caller — freely overrides it.
`texture.assetType`'s returns the `textureType` the name suggests (a
`_normal`-suffixed name is a `normalMap`), `compression = "uastc"` and
`maxDimension = 4096`, with `rgba8` for a `textureType` of `sprite` that a
higher layer names; for a pre-encoded ZTEX payload it returns the colour
space, compression and sampler the payload's own header carries. Either
way, an explicit `settings = { ... }` from the caller still wins.
- **`settingsCorrections(values, name, opts) -> (partial?, reasons?)`**
enforces a CROSS-FIELD CONSTRAINT the schema itself has no syntax for — a
fact about one field that depends on another field's resolved value, true
regardless of which layer produced that value. It runs last (layer 7
above), over the fully merged `values`, and again on every later write of
the values file. Nothing is left unmet in what gets
validated and stamped — but a value the caller explicitly asked for is
never silently rewritten to satisfy it; `applyCorrections` refuses instead
(see above). The optional second return, `{ [field]: reason }`, supplies
the "why" for that refusal message; a field with no reason falls back to a
generic one. `texture.assetType`'s returns `{ generateMipmaps = false,
maxDimension = 8192, colorSpace = "linear" }` whenever the RESOLVED
`compression` is high-precision (the encoder stores one verbatim, linear,
and refuses a mip chain or a downsample for it outright), paired with a
reason naming the compression, and `nil` otherwise.
## What does a declarer declare?
`Field.settingsOf(identity, mode)` embeds another declarer's schema as a
struct field without restating it. The identity names one of two kinds of
declarer, and `Settings.schemaOfDeclarer(identity)` tells them apart by what
`identity` resolves to:
- **An assetType** (e.g. `"@builtin::assetTypes.texture"`) — embeds the
schema every instance of that type carries, resolved via
`schemaForType`. This is the type-level shared schema from the section
above, not a per-instance one — an assetType has no settings of its own
to declare per instance.
- **Anything else** (an importer, or any other asset that declares settings
of its own) — embeds that asset's own schema, resolved via
`schemaOfInstance`.
Every schema this module serves has already run its `Field.settingsOf`
fields through this resolution — a caller reading `schema.someField.fields`
never sees an unresolved `declarer` with no `fields`. Resolution descends
into an already-literal struct's `fields` and a list's `element` the same
way, so a declarer embedded several fields deep is still reached. A declarer
that embeds itself, directly or through another declarer, stops one level
short of the loop instead of recursing forever.
## What are the defaults?
`Settings.defaultsOf(schema)` reads every field's declared `default` into a
plain table — a field declared without one is absent from the result rather
than holding a `nil` value.
▲ 0↑ born
# AreaLight
A rectangular light source on an entity. The rect is centred on the entity's
world position, faces along the entity's world rotation applied to `face`
(default "Front", the entity-local -Z that `transform.forward` reports and that
`entity:lookAt` aims), and spans `width` by `height`. A rect under a carrier moves
and turns with it. Its light arrives from a surface rather than
a point, so shading falls off gradually across a wall, highlights stretch to the
shape of the source, and shadows carry a penumbra that widens with the rect's
size and the caster's distance.
▲ 0↑ born
# BoxCollider (component)
A box collision shape. Works with or without a `Physics` component: on its own
it is static collision geometry, and alongside one it moves with the body.
## Sizing
`half` is the box's half-extents in the entity's local space, multiplied by the
entity's world scale. Leave it unset and the box derives from the entity's model
bounds, so a bare `BoxCollider` matches what is rendered at any scale.
```lua
entity.find("crate").component.add("BoxCollider", {}) -- fits the mesh
entity.find("wall").component.add("BoxCollider", { half = { 2, 4, 0.2 } }) -- authored
```
## Fields
| Field | Meaning |
|-------|---------|
| `half` | Half-extents. Unset derives from model bounds. |
| `isTrigger` | Report overlaps without blocking. |
| `friction` | Surface friction. |
| `restitution` | Bounciness. |
## Composing
A collider on a child entity attaches to the nearest ancestor carrying a
`Physics` component, so a body made of several shapes puts each on its own
entity and each keeps its own material and trigger flag.
Past a few dozen boxes sharing one material, `CompoundCollider` is cheaper: it
is a single broadphase volume where separate components are one each.
▲ 0↑ born
# assetType runtime
The machinery that reads a `<typename>.assetType/behavior.luau` and turns its
declarations into live behaviour.
A `behavior.luau` is a table of declarations — `ref` methods, `modules` shared
code, an `events` schema, a `namePattern`, `refShapes`, and the `onCreate` /
`onRegister` / `onChange` / `onDelete` / `validate` / `settingsDefaults` /
`settingsCorrections` hooks. None of it runs itself. This is the code that
runs it, and it lives here because reading a type's declarations is the
**assetType type's own behaviour** — the same way `material.assetType` owns
what a `.material` does.
## Sub-modules
| Module | Reads | Responsibility |
|---|---|---|
| `ref.module` | `ref`, `modules` | Builds every `AssetRef` envelope, attaches the shared metatable, and dispatches per-type methods and shared modules onto it. Also owns edit-mode write-behind persistence. |
| `create.module` | `onCreate`, `namePattern`, `validate` | Backs `asset.create`: resolves the type, checks the name against its pattern, runs `onCreate` (or clones `template/`), and writes the instance. `validate.module` beside it checks a creation `opts` table against the type's `createSchema`. Before running `onCreate`, resolves the type's settings chain (below) and hands the result to the hook as `opts.settings`. |
| `settings.module` | `settings`, `settingsDefaults`, `settingsCorrections` | A type's declared settings schema and where its values live (`type.yaml`'s `settings:` block). `Settings.resolveForCreate` layers the schema's own defaults, the type's own `settingsDefaults(name, opts, asked)` hook (a DEFAULT the schema can't express — a name-derived convention, a fact read off a payload the caller handed it, a value following a field `asked` shows a higher layer naming; any later layer overrides it), the Preset Manager, an importer's settings, the caller's `settings` table, then the type's own `settingsCorrections(values, name, opts)` hook (a CROSS-FIELD CONSTRAINT the schema can't express, applied last over the fully merged values). A correction over a default/preset/importer value lands silently; a correction that would override what the caller's own `settings` table explicitly asked for refuses the creation instead, naming the field and why. Neither hook is ever handed a table to mutate; each returns what it wants changed (`settingsCorrections` may also return a `{ [field]: reason }` table for that refusal message). `Settings.cloneValues` deep-copies a values table — `create.module` hands `onCreate` a copy, never the table it stamps. `Settings.valuesOf` / `writeValues` read and write an asset's own values file. |
| `typeYaml.module` | `type.yaml` | The folder a type lives in and its parsed `type.yaml`, decoded once per content version of the file. `settings.module` and `inspector.module` read their blocks through it. `about` / `aboutAt` read a type's `about.yaml` (`intent`, `function`, `usage`), leaving out any key that is empty or still starts with `[[describe]]`; `aboutRows` and `aboutMarkdown` lay the texts out for the Inspector and the `types/<name>` guide. |
| `inspector.module` | `type.yaml`'s `inspector:` block | Which inspector a type declares for its assets (`inspector: { type: ... }` or `{ instance: ... }`), and the declaration that file returns — the sections it adds, the generic ones it replaces, and their order — or the problem that kept it from loading. |
| `onRegister.module` | `onRegister` | Fires an instance's once-only registration hook — on arrival, on world load, and for `@builtin` library instances. |
| `changeDispatch.module` | `onChange`, `onDelete`, `refShapes` | Routes a VFS source write or a folder delete to the enclosing typed asset's type hooks. |
| `refShapes.module` | `refShapes`, `ref` | Publishes what every `AssetRef<category>` answers to, so a member read on an asset-typed value is checked against that category's real surface. |
| `events.module` | `events` | The per-asset event runtime behind `ref.events`. |
| `instantiable.module` | `ref.instantiate` | The instantiation contract an asset type opts into: `root` stands the root entity, `place` applies the base placement opts to one the type adopted, and `result` shapes the `(root, idMap)` every `instantiate` returns. Also registers the `sceneInstantiable` field-constraint validator. |
| `declaration.module` | `type.yaml` | The type's decoded declaration, read once and held until a write inside an `.assetType` folder; what every question about a type as a whole reads. |
| `previewRecipe.module` | `type.yaml` `preview:` | How an instance's `preview.png` is produced: which of the four recipes (`instantiate`, `image`, `surface`, `custom`) the type declares, and what that recipe needs. |
## Reaching it
```luau
local rt = require("@builtin::assetTypes.assetType.shared")
rt.ref.loadTypeBehavior("material")
```
Fields resolve lazily. The prelude requires the sub-modules directly, in
dependency order (`ref`, then `changeDispatch`, `onRegister.install()`,
`refShapes.install()`) — a table that required all six on load would take that
ordering away from it.
▲ 0↑ born
backing path · controller/first_person.component
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
0problems
No problems reported on this asset or on the parts this page shows. Parts it leaves out are not counted here.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up
agent_score is exposed.usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor
+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
—%no reports yet
Sign in to report whether this part worked for you.
Discussion
Scoped to this part · feeds back into the world's score.
0comments
Sign in to post.sign in
No comments yet. Be the first.