Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·originates fromworld 07158574-5…

debugViz

The shared edit-mode debug-visualization core. Owns the ONE anchor entity, the ONE vertex-colour line material, the ONE batched vertex/index compute-buffer pair, and the ONE render feature that every debug-visualization gizmo draws through. Individual gizmos (bounds boxes, camera…

byzero-proxy @ DESKTOP-DB3UJOJ·posted 4mo ago
What it does

debugViz

The shared edit-mode debug-visualization core. Owns the ONE anchor entity, the ONE vertex-colour line material, the ONE batched vertex/index compute-buffer pair, and the ONE render feature that every debug-visualization gizmo draws through. Individual gizmos (bounds boxes, camera frustums, ...) are providers — small modules that append their own geometry into the shared batch every tick, instead of each owning their own GPU state.

entity.spawn("DebugViz"):component.add("DebugViz")

How it fits together

  • DebugViz.component owns the lifecycle: registers the built-in providers and calls debugViz.update(dt) every edit-mode tick; onDisable/onDestroy call debugViz.teardown().
  • debugViz.registerProvider(name, fn) registers fn(emit) under name. Registering an existing name replaces its function.
  • debugViz.update(dt) calls every registered provider with an emit handle, which records what each call asked to draw, then uploads the combined vertex/index buffers (grow-only capacity). The upload follows what changed: a tick that drew the same thing writes nothing, a tick where some draws changed in place (the same commands, the same vertex counts) writes only their vertices, and a tick where a draw appeared, went or changed its vertex count writes the whole batch.
  • emit.section(changed, draw) marks a part of a provider's drawing that changes apart from the rest: draw(emit) runs when changed is true or the section has not drawn before, and otherwise its last recording is replayed without running draw.
  • debugViz.state() returns the latest { vtx, idx, anchor, indexCount, uploadedBytes, shapes, icons } for the render feature to draw.
  • @builtin::renderFeatures.debugViz reads state() every frame and draws the batch through one Draw pass, using @builtin::shaders.debugGeometry — a solid-colour shader that reads each vertex's baked colour, so every provider can use its own colour in the same draw call. Each instanced shape (below) draws in a Draw pass of its own.

The draw needs an anchor entity with an IDENTITY world transform and a render-object (so the Draw pass has a valid instance slot and a material to override) — this module owns one, spawned lazily, internal so it stays out of the inspector and excluded from scene saves.

Writing a provider

local debugViz = require("@builtin::modules.debugViz")

local function tick(emit)
    emit.box({ x = -1, y = -1, z = -1 }, { x = 1, y = 1, z = 1 }, { 1, 0, 1, 1 })
    emit.line({ x = 0, y = 0, z = 0 }, { x = 0, y = 5, z = 0 }, { 1, 0, 1, 1 })
end

debugViz.registerProvider("my_gizmo", tick)

emit.box(min, max, color?) and emit.line(a, b, color?) append world-space geometry into the shared batch for this tick; color is an {r, g, b, a} array baked per-vertex (defaults to amber if omitted). A provider that needs to exclude the shared anchor entity from its own scene queries reads debugViz.anchorId().

A provider that hands the same packed geometry back every tick (emit.rawLineSoup(bytes, vertexCount)) costs nothing to upload while the geometry stays the same string.

Instanced shapes

emit.shape(entityId, key, bytes, vertexCount) draws a line-list blob in the local space of entityId. The blob is uploaded once under key and drawn once per entity that asks for it, through that entity's own world transform: any number of entities sharing a shape cost one GPU buffer, and moving them costs no per-tick work. A key names immutable bytes (geometry that changes takes a new key), the buffer lives for as long as some entity asks for the key each tick, and the entity needs a render object (a Mesh). debug_wireframe draws every mesh this way.

API

  • debugViz.registerProvider(name, fn, opts?) — register (or replace) a provider. fn(emit) runs once per edit-mode tick. opts.label is the name the Debug menu and the Rendering panel list the overlay under: text as written, or an i18n.text value (i18n.text("hud.my_gizmo")), which reads in the editor's language. Without one the overlay is listed by name. opts.default is whether the overlay starts on, and opts.available() whether it currently has anything to show.
  • debugViz.providers() — every provider that currently has something to draw, in registration order, as { name, label, enabled } with the label in the editor's language.
  • debugViz.anchorId() — the anchor entity's id, or nil before the first tick.
  • debugViz.update(dt) — run every provider and upload what their drawing changed.
  • debugViz.state() — the latest batched draw, or nil before the first tick.
  • debugViz.teardown() — tear down the feature, material, buffers, and anchor entity. Registered providers stay registered.
  • debugViz.MATERIAL — the registry key of the shared vertex-colour line material the render feature draws with.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

strict

currentMode( ) → string

The engine's mode, as the visibility is keyed: `edit` or `play`.

providerAvailable(p: any) → boolean

Whether a provider currently has anything to show. A provider with no `available` predicate is always offered; one that declares it is offered only while the thing it draws exists in the scene, so the panel lists the overlays this scene can actually use rather than every overlay the engine knows how to draw.

argtypedescription
pany

registerProvider(name: string, fn: (Emit) → void

Register (or replace) a provider under `name`. `fn(emit)` runs once per edit-mode tick and appends its geometry via `emit`, unless `name`'s category is disabled (`setCategory`). Registering an existing name replaces its function; providers otherwise persist for the module's lifetime, so re-enabling the driving component doesn't need to re-register. A provider's category defaults on the first registration and is otherwise untouched by re-registration, so a category toggled by the panel survives a component disable/enable cycle. `opts.label` is the name the toggles show, as text or as an `i18n.text` value.

argtypedescription
namestring
fn(Emit

unregisterProvider(name: string) → boolean

Remove a provider and its category. A package that stops being able to draw (its system left the scene) withdraws its overlay so the panel stops offering a toggle for something with nothing behind it. The category's on/off state is dropped with it, so re-registering starts from its declared default.

argtypedescription
namestring

providers( ) → void

Every provider that currently has something to draw, in registration order: `{ name, label, enabled }`, the label in the editor's language. The toggle panel builds from this, so a provider appears the moment its subject exists in the scene and disappears with it.

setCategory(name: string, on: boolean) → void

Enable or disable a provider's category. A disabled category's provider is skipped by `update()` without unregistering it — re-enabling resumes drawing on the next tick.

argtypedescription
namestring
onboolean

isCategory(name: string) → boolean

Whether `name`'s category currently draws. Categories default per `CATEGORY_DEFAULTS` the first time their provider registers; an unregistered name reports its would-be default.

argtypedescription
namestring

categories( ) → void

Every registered provider's category name, in registration order — the stable order the toggle panel lists categories in.

knownCategories( ) → void

Every category this module carries a state for: the registered providers in registration order, then any category whose state was set before its provider registered, sorted so the order is stable. A provider registers when the thing it draws enters the scene, so the registered set grows through a session — a package's overlay appears only once that package has loaded. `setCategory` accepts a name at any time and `registerProvider` keeps the state it finds, so a preference set ahead of registration is honoured when the provider arrives. Reading only the registered set therefore misses categories that are live and settable, which is what a caller means by "every category".

isRegistered(name: string) → boolean

Whether `name` has a provider registered right now — the difference between a category that draws and one whose state is recorded for a provider that has not arrived.

argtypedescription
namestring

registerIcon(key: string, opts: { glyph: (string | number) → void

Register (or replace) an icon visual under `key`. `emit.icon(center, key)` then draws it. This is how both built-in systems and user code make an entity show a gizmo icon: register a visual once, then emit it wherever it belongs. `opts`: * `glyph` — a built-in procedural glyph name (`"camera"`, `"light"`, `"audio"`, `"probe"`, `"player"`) or its numeric id. Mutually exclusive with `texture`. * `texture` — a `.texture` asset identity/ref/`AssetRef`; the icon samples its alpha, so any authored image becomes an icon. The reference is read where the call was written, so `~.textures.x` in a package's code names that package's texture. One that names no texture is logged, and the icon draws without one. * `size` — on-screen scale as a fraction of the camera distance (default `0.06`), so the icon holds a roughly constant size regardless of range. Re-registering a key updates its visual (the material is rebuilt on the next draw). The per-entity tint comes from `emit.icon`'s `color`, not from here, so one icon can be tinted per entity.

argtypedescription
keystring
opts{ glyph: (string | number

iconKeys( ) → void

Every registered icon key, in registration order. For introspection.

anchorId( ) → string

The anchor entity's id, or nil before the first tick. Providers that need to exclude the anchor from their own scene queries (it carries a Mesh) read this rather than tracking their own copy.

adoptAnchor( ) → string

Adopt the anchor that is already in the scene, if there is one, and leave exactly one behind. `anchorId` is module state and the anchor is an ECS entity, so the two part company whenever this module is re-instantiated — a hot reload during an editor session, most often. The scene is the authority on how many anchors exist, so it is what gets asked: the first one found becomes this instance's anchor, and any others are despawned, which also drains anchors a previous instance left behind.

ensureAnchor( ) → string

The internal identity-transform entity the Draw pass resolves its instance slot + material override through. Temporary so it never lands in a scene/world save, internal so it never clutters the entity list, EditorOnly participation so world scans (bake selection, coverage reports) never see editor viz as world geometry.

ensureMaterial( ) → void

ensureIconMaterial(reg: IconReg) → void

Create (once, or after re-registration) the triangle-list material an icon draws through, from the debugBillboard shader with the icon's glyph/size (and texture, when texture-backed). Alpha-blended overlay that ignores depth, so icons read on top of the scene like the rest of the overlay.

argtypedescription
regIconReg

forgetGpuState( ) → void

Give up everything this module holds on the GPU, because the device holding it is gone. Every buffer here was made from the render device, and a lost device invalidates all of them; the handles cached above would otherwise name resources that no longer exist, and the grow-only sizing would keep them because the size still fits. The material and the render feature go with them: both are rebuilt from their spec by the `ensure*` calls the next tick makes, which is what puts the overlay back on the device the engine is now on. Nothing is destroyed here — a lost device took the resources already, and destroying a handle to one is a call into a device that is not there.

ensureFeature( ) → void

wordsFor(byteLen: number) → number

A buffer is a run of 32-bit words, so a byte count sizes one as that many quarters. Every debug payload is whole words — 92-byte vertex records and u32 indices — so this divides evenly.

argtypedescription
byteLennumber

stillThere(buf: any) → boolean

Internal: whether a cached handle still points at storage. A handle outlives the storage it points at: anything may release the buffer by the name it was created under, and every holder's handle answers `alive` false from that moment. The grow-only caches below drop such a handle, and the next call sizes a fresh buffer.

argtypedescription
bufany

adoptBuffer(name: string) → void

The buffer behind `name`, and the f32 words it holds, for a module that has lost its handle to it. Every buffer here is held by the substrate under a NAME, and a name outlives this module: a hot reload brings back empty bookkeeping while the storage and its name are both still there, and asking the substrate for a name it already holds is refused. So a lost handle is taken back from the name rather than asked for a second time, and a reloaded module carries on from the storage it left instead of from a refusal it has no way to clear.

argtypedescription
namestring

bytesHeld(buf: any) → number

Internal: the bytes the buffer behind a live handle holds, as the substrate states its length. Every buffer here is `f32`, one word per record. The length is read off the buffer each time, so the size a grow-only cache compares against is the size of the buffer it holds, whichever handle that is.

argtypedescription
bufany

ensureLineVtxCapacity(vtxBytesLen: number) → any

Grow-only sizing for the line vertex buffer, recreated only when the frame's bytes no longer fit. Returns the buffer to write into, nil when the allocation failed.

argtypedescription
vtxBytesLennumber

ensureIndexCapacity(vertCount: number) → void

Grow-only sizing for the shared static sequential index buffer (0,1,2,…). It backs every debug draw — the line soup and every icon quad list — so it is sized to the largest single draw's vertex count, with 2× headroom so growth (and the one-off sequential fill) is rare; a steady tick never touches it.

argtypedescription
vertCountnumber

uploadIconBuffer(key: string, bytes: buffer) → string

Upload one icon's triangle-soup bytes to its own grow-only vertex buffer. Returns the name the draw binds it by, nil when the allocation failed.

argtypedescription
keystring
bytesbuffer

uploadShape(key: string, bytes: string) → ShapeBuf

Upload one instanced shape's local-space bytes under its key and remember the buffer. Returns the record, nil when the allocation or the write failed.

argtypedescription
keystring
bytesstring

releaseShapes(keep: { [string]: ShapeBuf }?) → void

Free every instanced-shape buffer `keep` does not name.

argtypedescription
keep{ [string]: ShapeBuf }?

putColor(c: { any }, n: number, color: { number }?) → void

Record `color` (or the default) at `n + 1 .. n + 4` of the command list.

argtypedescription
c{ any }
nnumber
color{ number }?

sharedQuery(...: ?) → void

argtypedescription
...?

newSection( ) → Section

pack(s: Section) → void

Pack a section's commands into its own writers.

argtypedescription
sSection

record(held: Section, draw: (Emit) → void

Record a section by running `draw`, then keep what it drew: a recording that matches the section's last one keeps its vertices, any other is packed.

argtypedescription
heldSection
draw(Emit

section(changed: boolean, draw: (Emit) → void

Replay a section's recording, or draw it and record what it drew.

argtypedescription
changedboolean
draw(Emit

box(min: ?, max: ?, color: ?) → void

argtypedescription
min?
max?
color?

line(a: ?, b: ?, color: ?) → void

argtypedescription
a?
b?
color?

orientedBox(center: ?, rotation: ?, halfExtents: ?, color: ?) → void

argtypedescription
center?
rotation?
halfExtents?
color?

wireSphere(center: ?, radius: ?, color: ?) → void

argtypedescription
center?
radius?
color?

wireCapsule(center: ?, rotation: ?, radius: ?, halfHeight: ?, color: ?) → void

argtypedescription
center?
rotation?
radius?
halfHeight?
color?

cross(center: ?, size: ?, color: ?) → void

argtypedescription
center?
size?
color?

octahedron(center: ?, size: ?, color: ?) → void

argtypedescription
center?
size?
color?

rawLineSoup(vtxBytes: ?, _vertexCount: ?) → void

argtypedescription
vtxBytes?
_vertexCount?

shape(entityId: ?, key: ?, vtxBytes: ?, vertexCount: ?) → void

argtypedescription
entityId?
key?
vtxBytes?
vertexCount?

icon(center: ?, key: ?, color: ?) → void

argtypedescription
center?
key?
color?

sameLayout( ) → boolean

Whether this tick lays out the sections the current batch was laid out from.

update(_dt: number) → void

Run every registered provider and, when what they drew differs from the batch on the GPU, lay the sections out and upload the batch. Called each active frame by the debug-viz driver.

argtypedescription
_dtnumber

state( ) → DrawState

setVisible(on: boolean, mode: string?) → void

Show or hide the overlay in `mode` (the engine's current mode when omitted). Hiding the mode the engine is in drops the current batch so the overlay stops drawing at once.

argtypedescription
onboolean
modestring?

isVisible(mode: string?) → boolean

Whether the overlay draws in `mode` (the engine's current mode when omitted). The driver rebuilds the overlay only while this holds.

argtypedescription
modestring?

setPlaySession(on: boolean) → void

Show or hide the overlay in play mode: a debug session over the running game. `M.setVisible(on, "play")`.

argtypedescription
onboolean

isPlaySession( ) → boolean

Whether the overlay draws in play mode. `M.isVisible("play")`.

setScope(ids: { string }?) → void

Limit the overlay to a set of entities. Pass an array of ids (or nil/empty to clear). Providers consult `inScope` per entity, so this focuses every enabled category on the same objects. In-memory only, never persisted.

argtypedescription
ids{ string }?

clearScope( ) → void

Clear the scope so every entity draws again.

inScope(id: string) → boolean

Whether `id` is in scope. True when no scope is set (draw everything), else true only for ids in the scope set. Providers guard each entity with this.

argtypedescription
idstring

isScoped( ) → boolean

Whether a scope is currently set. Providers that behave differently when focused on specific objects (e.g. bounds drawing per-entity instead of one box per top-level object) branch on this.

scopeIds( ) → void

The current scope as an array of ids (empty when unscoped) — for introspection by the debug toolbox.

clear( ) → void

Drop the batched draw without tearing down GPU resources, so the render feature enqueues nothing until the next `update`. Used when leaving edit mode with no active play session — cheap enough to call every frame.

teardown( ) → void

Tear down the live feature, material, buffers, and anchor. Registered providers stay registered — re-enabling rebuilds GPU state without re-registering.

⌬ Types
Emit = {DrawState = {

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.

56+items
·
assettype · born here
❒asset
# 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. The body runs in an environment of the module's own: a name it declares without `local` is readable by the module's own functions and by no other script, so an export reaches its callers through the returned table and nothing else. Requiring a component's folder runs its chunk the same way, once, and its `update`, `start` and `public` stay in that environment; a component runs on an entity through `entity(id).component.add(name)`. 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()`. A name the body declares without `local` lives in the module's environment, which every run of the module shares: a function the previous run left in place reads what the reload assigned. 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
·
renderfeature · born here
❒asset
# debugViz render feature Draws the batched geometry buffer that `@builtin::modules.debugViz` rebuilds every edit-mode tick from every registered provider — bounds boxes, camera frustums, and any further gizmo the debugViz core gains. One Draw pass over the core-owned vertex/index buffer pair, rasterized as GPU lines through the shared vertex-colour unlit material (`@builtin::shaders.debugGeometry`). An empty state (no providers with geometry yet, or the driving `DebugViz` component not yet awake) enqueues nothing.
▲ 0↑ born
△
mesh · born here
❒asset
▲ 0↑ born
✦
shader · born here
❒asset
# debugBillboard Camera-facing billboard shader for the debug overlay's icon sprites. Each instance renders a procedural glyph (camera, light, audio, reflection probe, player) selected by glyph id — drawn analytically in the fragment shader, so icons stay crisp at any zoom with no texture atlas. Consumed by the debugViz icon system.
▲ 0↑ born
▣
module · born here
❒asset
# debugDraw Procedural geometry builders for GPU debug visualization: wireframe boxes, spheres, capsules, crosses, octahedra, line segments, and camera-facing icon billboards. Pure geometry: every builder writes packed vertices into a caller-supplied `Writer` and returns how many vertices it added. Line geometry is a non-indexed **line soup** (each line is two consecutive vertices) and billboards are a **triangle soup** (each quad is six consecutive vertices), so both draw through one static, grow-only sequential index buffer (0,1,2,…) that never needs re-uploading per frame; the topology comes from the material. Nothing here touches `compute.*` or `renderer.*`: callers own the buffers and the Draw pass. ```lua local debugDraw = require("@builtin::modules.debugDraw") -- Keep one writer and reset it for each build: a steady rebuild allocates nothing. local w = debugDraw.writer() debugDraw.reset(w) debugDraw.writeBox(w, -1, 0, -1, 1, 2, 1, 1, 0.8, 0, 1) debugDraw.writeLine(w, 0, 0, 0, 0, 3, 0, 0, 1, 1, 1) local vtx = substrate.createBuffer({ name = "my.vtx", type = "f32", len = buffer.len(w.buf) // 4, kind = "gpu", usage = { "vertex" }, }) vtx:writeBytes(w.buf) -- One static sequential index buffer, grown only when the vertex count does. local idx = substrate.createBuffer({ name = "my.idx", type = "f32", len = w.count, kind = "gpu", usage = { "index" }, }) idx:writeBytes(debugDraw.buildSequentialIndexBytes(w.count)) ``` The Draw pass draws `w.count` vertices; the bytes past them in `w.buf` are storage the writer keeps for its next build. ## Vertex layout Every packed vertex matches the engine's standard `Vertex` layout (position, normal, uv, joints, weights, node_index, tangent, color: 92 bytes, little-endian) so the resulting buffer draws through the ordinary vertex pipeline via a Draw pass. Debug geometry only needs position + color; every other field is filled with a default. ## Writer builders A `Writer` is `{ buf: buffer, count: number }`: `buf` grows by doubling and is kept across builds, `count` is how many vertices the current build holds. - `writer(capacity?)`: a new, empty writer with room for `capacity` vertices. - `reset(w)`: empty `w` for the next build, keeping its storage. Each builder takes its points, rotation and colour as plain numbers (a rotation is a unit quaternion `qx, qy, qz, qw`; a colour is `r, g, b, a`), writes at the writer's end and returns the vertex count it added: - `writeLine(w, ax, ay, az, bx, by, bz, r, g, b, a)`: one segment (2 verts). - `writeBox(w, minX, minY, minZ, maxX, maxY, maxZ, r, g, b, a)`: axis-aligned box, 12 edges (24 verts). - `writeOrientedBox(w, cx, cy, cz, qx, qy, qz, qw, hx, hy, hz, r, g, b, a)`: a posed box with half-extents `hx, hy, hz`. - `writeWireSphere(w, cx, cy, cz, radius, r, g, b, a)`: three orthogonal rings. - `writeWireCapsule(w, cx, cy, cz, qx, qy, qz, qw, radius, halfHeight, r, g, b, a)`: two rings + connectors. - `writeCross(w, cx, cy, cz, size, r, g, b, a)`: a 3-axis marker (6 verts). - `writeOctahedron(w, cx, cy, cz, size, r, g, b, a)`: a diamond marker (12 edges). - `writeBillboard(w, cx, cy, cz, r, g, b, a)`: one camera-facing quad (6 triangle-soup verts); every corner stores the centre and its uv corner, and the `debugBillboard` surface shader expands it toward the camera. - `writeWriter(dst, src)`: every vertex `src` holds, after the ones `dst` holds. - `writeRaw(w, bytes)`: pre-packed vertex bytes (whole `VERTEX_STRIDE` records). ## Parts-table builders The `append*` builders draw the same shapes through the writer builders and append them to a `{ string }` parts table, one packed string per vertex. They take points as `{ x, y, z }` tables, a rotation as an `{ x, y, z, w }` table, and a colour as an `{ r, g, b, a? }` table (alpha 1 when left out, the default colour when nil), and return the vertex count they added: ```lua local vtxParts = {} local verts = 0 verts += debugDraw.appendBox(vtxParts, bounds.min, bounds.max, { 1, 0.8, 0, 1 }) verts += debugDraw.appendLine(vtxParts, a, b, { 0, 1, 1, 1 }) vtx:writeBytes(debugDraw.buildVertexBytes(vtxParts)) ``` - `appendLine(vtxParts, a, b, color?)` - `appendBox(vtxParts, min, max, color?)` - `appendOrientedBox(vtxParts, center, rotation, halfExtents, color?)` - `appendWireSphere(vtxParts, center, radius, color?)` - `appendWireCapsule(vtxParts, center, rotation, radius, halfHeight, color?)` - `appendCross(vtxParts, center, size, color?)` - `appendOctahedron(vtxParts, center, size, color?)` - `appendBillboard(vtxParts, center, color?)` - `buildVertexBytes(vtxParts)`: the parts joined into buffer-ready bytes. ## Helpers - `packVertex(x, y, z, color)`: pack one vertex; for building cached geometry blobs. - `packVertexUV(x, y, z, u, v, color)`: pack one vertex carrying an explicit uv (a billboard corner). - `quatRotate(q, v)`: rotate a `{ x, y, z }` vector by a unit quaternion table. - `rotate(qx, qy, qz, qw, vx, vy, vz)`: `quatRotate` on scalars. - `defaultColor()`: the colour builders draw in when a caller states none. - `buildSequentialIndexBytes(count)`: the fixed `0,1,2,…,count-1` index buffer. - `VERTEX_STRIDE`: 92, the byte stride of one packed vertex. See `@builtin::modules.debug_bounds` for a caller and `@builtin::renderFeatures.debugViz` for the Draw pass that renders the batch.
▲ 0↑ born
✦
shader · born here
❒asset
▲ 0↑ born
·
assettype · born here
❒asset
# assetType (asset type) An asset type says what a kind of asset is: the files an asset of the kind is made of, the code that gives it behaviour, the interface a person uses to work with it, and how it is found, pictured and checked. A `<typename>.assetType/` folder declares a type called `<typename>`, and every `<name>.<typename>/` folder is an asset of it. `assetType` is itself a type, so a type is an asset like any other: it is created, versioned, installed and contributed the same way. ## Making a type `asset.create("assetType", "<typename>")` scaffolds a type. The type registers the moment its folder is written, anywhere under `/zero/source/`, and from then on `<name>.<typename>/` folders are its assets. An asset of a type that is not registered yet is not an asset, so make the type first. A type folder is a root: `~.x` in any file inside it names the type's own `x`, wherever the type is installed. Keep the type's whole implementation inside its folder and reach it that way. What a type folder must hold is set by this type's own `type.yaml`, the same way every type's `type.yaml` sets what its assets hold. `asset.validate` on a type reports anything missing, and the scaffold produces a folder that passes. ## What sets your type's schema (`type.yaml`) `type.yaml` is the structural contract every asset of the type is checked against. The keys below are the ones the engine reads; a key not listed here is ignored. | Key | What it controls | |---|---| | `suffix` | The folder suffix of the type's assets. Defaults to `.<typename>`. | | `primary` | The file or files that are the asset's content: what the asset resolves to when it is used. | | `entry_files`, `primary_aliases` | Further files that load as the asset or share its identity. | | `is_container` | Whether the suffix stays in the identities of what the asset holds. | | `is_opaque_walker` | Whether a walk of the tree stops at the asset and registers only its primary. | | `plural_dir`, `classify_exts` | Loose files in a folder of this name, or with these extensions, are assets of the type. | | `is_text_default` | Whether the asset's files are text unless stated otherwise. | | `broadcasts_subassets` | Whether assets nested inside an asset of the type are found by their own short name. | | `root` | `true` makes every asset of the type a root, so `~.x` inside one names that asset's own `x`. | | `contract_ref: { field, category }` | A key of the primary file that names another asset the asset is built on. | | `files: { required, optional }` | The files an asset holds (below). | | `allow_unlisted` | `false` reports every file the type does not declare. | | `aliases_from: [{ file, key }]` | Further names an asset answers to, read from its own files. | | `settings:` | Typed per-asset settings (below). | | `inspector:` | The interface people use for the type and its assets (below). | | `preview:` | How an asset is pictured (below). | | `references:` | Names of other assets the type's files carry (below). | | `indexing:` | What search reads for each asset (below). | | `describe:` | How a missing description is generated (below). | ### The files an asset holds Each entry under `files.required` or `files.optional` is `{ path, kind: file | folder, one_of_group?, content? }`. `*` in a path matches within one segment. Entries that share a `one_of_group` are satisfied by any one of them. `content` lists checks on the file's bytes: | Check | Passes when | |---|---| | `non_empty` | the file has content | | `json_field { key, type?, non_empty?, accept? }` | the JSON holds the key (a dotted path) with that shape | | `yaml_field { key, type?, non_empty?, accept? }` | the same for YAML | | `described { keys?, headings?, message? }` | the file says what the asset is (see "Ask your assets to say what they are") | Each check takes a `message`, which is what the author is told when it fails. ### Settings `settings: { values, schema: { type | instance, export? } }` gives every asset typed settings. `values` names the file an asset's values live in; `schema.type` declares one schema for the whole type, and `schema.instance` names a file each asset declares its own in. `asset.create` writes the resolved values, and a write to the values file reaches `onChange` with what changed. ## The human side (`inspector.luau`) A type is used by people through its Inspector, and without one the type is usable only from code. The Inspector is the type's interface for a person: for a procedural graph it is the graph editor, for a kit it is the tracking view of what the kit holds and what is still missing. Writing it is part of writing the type. `inspector: { type, instance? }` in `type.yaml` names the files. `type` is the interface for the type itself and for its assets; `instance` names a file an asset may ship to add its own. Each returns: ```luau return { sections = { { id = "graph", title = "Graph", build = function(ctx) ... end } }, replace = { contents = { ... } }, -- replace a default section by id order = { "graph", "contents" }, -- section order } ``` `build(ctx)` receives the asset and builds the section. A section's `title`, and the text its rows carry, is a string or an `i18n.text` value read from a catalog (`i18n.text("inspectors.mesh.title")`), which follows the editor's language. `asset.create("assetType", ...)` scaffolds a working `inspector.luau` to start from. `asset.validate` on a type that names no inspector, or names one that does not load, reports it. ## Say what your type is for (`about.yaml`) Every type carries an `about.yaml` that says what the type is for, in three plain-language texts: ```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, in the words a game maker uses. Up to 800 bytes. - **`function`** is how it works today: what an asset of it is made of and what the engine does with it. Up to 1500 bytes. - **`usage`** is what a person or an agent does with one. Up to 1200 bytes. Write about the type as a whole, not one asset of it, and say what it does now. Agents read these texts to learn when to reach for the type and how; people searching find the type by them. The scaffold starts each text with `[[describe]]` and a note on what to write; a text that still starts that way counts as not written. `services describe` can write them. They show up in `asset.inspect` as `detail.about`, in `assetTypeRef:getAbout()`, at the end of the type's `types/<typename>` guide, and at the top of the type's Inspector. ## Ask your assets to say what they are A type can require each asset to carry a description: a file, written by the author or generated, saying what the asset is and what it is for. Declare it with a `described` check: ```yaml files: required: - path: "README.md" kind: "file" content: - { check: "described", message: "Say what this widget is for and where it goes." } ``` A file that is missing, empty or still has a line starting with `[[describe]]` fails the check, and so does a YAML file whose named `keys` are missing or over their `max_bytes`, or a Markdown file missing a named heading. `asset.validate` names the asset, and a push that carries it is refused with `message`. `services describe` finds such assets and writes their descriptions. `describe:` steers what is generated: ```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>" ``` An example is an asset of your type whose description is a true, written one, never a placeholder and never the asset being described; with none, leave `examples` empty. A type whose assets the model cannot perceive (a sound, a motion) says so in `guidance`, and the description is drawn only from what the asset's own files state. Start the file unwritten in your `template/`: a heading and one line starting with `[[describe]]`, never example content, which every new asset would carry verbatim. A type whose assets say what they are through their own content (a mesh, a texture) declares no check. ## The type's code (`behavior.luau`) `behavior.luau` returns one table. These are the keys the engine reads from it; anything else on the table is the type's own. ### What the type's assets can do | Key | Shape | What the engine does with it | |---|---|---| | `ref` | `{ [name] = function(self, ...) }` | Every function becomes a method on every asset of the type: `ref:name(...)`. | | `modules` | `{ [name] = require(".x") }` | Code the type's assets reach with `asset.containing(__FILE__).modules.<name>`. | | `events` | an events schema | Events an asset fires. Readers subscribe through `ref.events.<name>:connect(...)`; the type fires them. | | `refShapes` | `{ [method] = function(self) -> (typeExpr, source?) }` | The result type of a `ref` method for one particular asset (below). | | `namePattern` | a Lua pattern | The names `asset.create` accepts for the type's assets. Default `^[A-Za-z][A-Za-z0-9_]*$`. | | `derive` | `{ output, module, compute, fingerprint, matches?, required?, timeout? }` | A file computed from the asset when it is committed; a `required` one holds the commit until it lands. | Some `ref` names mean the same for every type, and the engine calls them: - **`instantiate(self, target?, opts?) -> (root, idMap)`**: puts the asset in a scene. Defining it is what makes the type scene-instantiable. Its return is a contract (below). - **`inspect(self) -> detail`**: what `asset.inspect` reports for the asset beyond the common record (below). - **`preview(self, opts)`**: renders the asset's picture; it wins over the type's `preview:` recipe. - **`previewMaterial(self) -> { material }`**: the material a `surface` preview paints. - **`saveDefinition(self)`**: writes the asset's in-memory edits back to its files in edit mode. Some names are answered for every asset before the type is asked, so a `ref` entry of the same name is never reached: `getSource`, `getBytes`, `getText`, `exists`, `deps`, `canInstantiate`, `canPreview`, `preview` (which calls yours when you define one), `meta`, `runtime`, `events`, `typeRef`, `modules`, and the residency flags `has_backing_asset`, `has_runtime_changes`, `cpu_resident`, `gpu_resident`. ### When the engine calls the type | Hook | Signature | When it runs | |---|---|---| | `onCreate` | `(name, opts) -> { [path] = contents }` | On `asset.create`. Returns the files of the new asset, laid over the type's `template/`. Annotate `opts`: its type is the schema `asset.create` checks the caller's arguments against. A `""` key writes a single loose file. | | `onReplace` | `(dest, files) -> files` | On an `asset.create` over an asset already at `dest`, after `onCreate`, so what the author added can be carried into the replacement. | | `onRegister` | `(self)` | Once per asset, when it first registers: when the world loads, on a live `asset.create`, and when an asset arrives later (installed, pulled, synced). This is what makes an asset take effect the moment it is written. | | `onChange` | `(ref, change)` | On every write to a file inside an asset of the type. `change` is `{ path, asset, type, kind, origin }`, plus `settings` and `settingsChanged` for a write to the settings values file; `kind` is `edited` or `seeded`, `origin` is `local` or `remote`. Filter on `change.path`. Writes to one asset arrive in order, each after the hook for the one before has finished, and the hook may wait on what it reads. A write the hook makes inside its own asset arrives later like any other, so keep the hook convergent. | | `onDependencyChange` | `(ref, change)` | When a module the asset's code requires is re-run, or a name the asset carries starts resolving. `change.kind` is `dependency`. | | `onDelete` | `(ref)` | When an asset of the type leaves the world: deleted, or the world it is in is swapped away. | | `validate` | `(ref) -> { { code, message, severity?, path? } }` | On `asset.validate`, after the `type.yaml` checks, for the type's own rules. `severity` defaults to `error`. Runs on every push, so a type's rules hold at publish. A hook that fails reports `validate.hook_failed`. | ### Settings hooks | Hook | When it runs | |---|---| | `settingsDefaults(name, opts, asked) -> table` | Once per `asset.create`, for values the schema's defaults do not give. | | `settingsCorrections(values, name, opts) -> (corrections?, reasons?)` | On every settings write. A correction to a field the writer named refuses the write, giving the reason. | | `settingsDerivedDefaults(values, explicit, changed)` | On a settings write, for fields derived from others. | | `normalizeSettings(values, stored?)` | On every read and write, to map an earlier spelling of a field to the current one. | | `settingsHealed(values, stored)` | On a read, to repair stored values. | | `settingsSchemaProblem(schema, ref) -> string?` | When an asset's own schema is read; a returned string refuses the schema. | `creationInputs` (`{ [opt] = true | selectorOpt }`) names `asset.create` options that are inputs to the type rather than settings. ### Reloading An edit to `behavior.luau` reaches existing assets with no restart. ## How an asset is pictured (`preview:`) | `kind` | The picture is | The type provides | |---|---|---| | `instantiate` | the asset placed in the preview studio through its `instantiate` | `ref.instantiate` | | `image` | a file the asset holds, fitted to the frame | `source: { files }`, the candidate files in order | | `surface` | the asset painted on a mesh | `mesh`, and `ref.previewMaterial` | | `custom` | whatever `ref.preview` returns | `ref.preview` | ```yaml preview: kind: surface mesh: sphere ``` `angle: [yaw, pitch]` turns the camera. The studio owns the light, the backdrop and the framing, so an asset pictures the same in every world. A type with no `preview:` that defines `instantiate` still answers `ref:preview()`. A picture is rendered when something asks to view it (the editor showing the asset, `ref:preview()`), when previews are generated on request (`assets.generatePreviews`), and when the asset is staged. An edit alone renders nothing. The picture records what it was made from, so a stale one is told from a current one. ## The names your type's assets hold (`references:`) Where your type's own format or API carries the name of another asset, declare it here: ```yaml references: keys: # a top-level key of the type's files that holds a name, or a table of them - { key: "shader", type: "shader" } args: # an argument of a call, counting from 1 - { call: "g:node", position: 2, type: "procNode" } fields: # a field of the options table a call takes - { call: "fx.beam", field: "material", type: "material" } ``` `type` is the category the name resolves in. `asset.declareReferenceKey`, `asset.declareReferenceArg` and `asset.declareReferenceField` declare the same from a script. ## What search reads (`indexing:`) `indexing:` is how assets are found. Search reaches an asset only through what its type's `indexing:` names, and adds nothing of its own. That includes you: an asset indexed badly is one you cannot find later, when you are making something else and need it. A type whose assets are never looked for says `indexing: none`. ```yaml indexing: data: # text, read from the asset's files - role: identity extractor: verbatim source: { file: "README.md" } - role: interface extractor: symbols source: { files: ["init.luau"] } - role: implementation extractor: verbatim source: { files: ["init.luau"] } content: # the picture - role: identity modality: image source: { file: "preview.png" } facets: # what a query filters and re-ranks by file: ".metadata" rigged: { type: bool, from: { components: { contains: SkinnedModel } } } roughness: { type: number, filter: range, from: { file: "mat.yaml", field: "floats.roughness" } } ``` **Roles.** Each `data` and `content` entry has a `role`, and a query matches in two slots: - **`identity`**: what an asset is. For anything you look at, the picture; for anything else, the text that says what it is. - **`capability`**: what it does and how it is made. `interface` (the signatures or shape a caller uses) and `implementation` (the body) both count as capability, and a type with code usually declares both. Ask what a person would recognise an asset of the type by, and what it does, and point each role at the file that says it. For text, that is the asset's description: the file your template starts with a `[[describe]]` block, which the author writes or `services describe` fills in (see "Ask your assets to say what they are"). **`data`.** `extractor: verbatim` embeds a file's text as it is; `symbols` embeds the declared signatures of code. `source` is `{ file }` or `{ files: [...] }`. Never index a file name (`source: { field: name }`): one or two words carry nothing to match. **`content`.** `modality: image` embeds the picture itself, so a text query matches what the asset looks like. A type whose assets are looked at makes the picture its identity. **`facets`.** What a query narrows and re-ranks the matches by. `file` is embedded whole, so keys nobody declared in it are still found. Each further key is computed for every asset and states a value for every one, including `false`: a file can imply "not rigged" but never say it, and a query separates rigged from unrigged only because the unrigged ones say `rigged: false`. A key is `{ type: bool | number | enum, filter?: range, from }`, where `from` is `{ file, field }` (a field of one of the asset's files, dotted for nesting), `{ metadata: key }`, or `{ components: { contains | any_outside } }` (what the asset's entities carry). ## What blocks a push A push checks every asset it carries against its type. These refuse it: - a required file that is missing, a `content` check that fails, a `described` file not written yet; - an error from the type's `validate`. Unlisted files and warnings do not. A `described` file blocks only a push that changes the asset. When a push is refused, the message names each asset and what it lacks. `world.publishBlockers()` and `zm status` read the same list without pushing. ## Typing a result from the asset (`refShapes`) A `ref` method whose result depends on the asset (one entry per child folder, per row of a config, per control a map declares) can only be annotated as `{ [string]: Thing }`, which accepts any key. `refShapes` states the result for each asset instead: a function returning a Luau type expression for that asset, and the module whose types the expression uses. Read the asset; never run it. ```lua -- inputMap.assetType/behavior.luau 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)` is checked and `map.noexisting` is reported. A per-asset type applies where the call site names which asset: a component field whose default names it, or an annotation `AssetRef<"inputMap", "<identity>">`. `asset.resolve(name, category)` carries only the category, and a name computed at runtime carries nothing, so calls on those keep the declared return. The type belongs to the call's result: index it there, or bind what you need from it there, and the names stay checked. `require("@builtin::assetTypes.assetType.shared.refShapes").published()` shows what was published: `categories` (each type's method surface) and `returns` (per-asset results by identity, then method). An identity missing from `returns` was never published. Results are recomputed when an asset is written; at most 64 assets of one type are read. ## Putting an asset in a scene (`ref.instantiate`) A caller writes one piece of code against every instantiable type, so what `instantiate` returns is fixed: ```lua local Instantiable = require("@builtin::assetTypes.assetType.shared.instantiable") M.ref = { instantiate = function(self, target, opts) local root = Instantiable.root(self, target, opts) -- compose the asset under `root`, now return Instantiable.result(self, root, idMap) end, } ``` **In.** `target` is the entity the asset lands under, or onto for a hierarchy type; with none, the type spawns a new root. `position`, `rotation` (three numbers in degrees, or a quaternion), `scale`, `name` and `temporary` mean the same for every type: `Instantiable.root` applies them to a root you make, `Instantiable.place` to one you adopt. Document any options of your own in the hook's `--!arg` docs. **Out.** `(root, idMap)`. `root` is the composed root, live when you return: build synchronously, never defer to a component's `awake`. `idMap` maps each original id to the spawned one, so a component that composes the asset again on every load can pass it back in and keep references into the composition. Every call goes through `Instantiable.result`, which refuses a root that is not live and turns a missing `idMap` into `{}`. ## Inspecting an asset (`ref.inspect`) `asset.inspect(ref)` builds a record every asset shares (`identity`, `name`, `guid`, `source`, `typeName`, `typeDefinitionPath`, `scope`, `origin`, `description`, `tags`), then calls `ref.inspect(self)` for the type's own `detail`: ```lua M.ref = { inspect = function(self) -- read the asset's own files, never runtime state: inspect works on an asset -- that has not been compiled, uploaded or registered return { --[[ what makes this asset what it is ]] } end, } ``` Without it, the record is the shared part alone, and an agent inspecting the asset learns nothing of what it is. A hook that raises leaves `detail` empty and sets `record.warning`. ## Discovery - `asset.list("assetType")`: every registered type. - `asset.inspect("<typename>")`: the type, its README and its `about.yaml` texts. - `asset.resolve("<typename>", "assetType")`: the type itself.
▲ 0↑ born
·
assettype · born here
❒asset
# renderFeature A **render feature** inserts custom GPU passes into the frame pipeline. The engine provides one generic capability — a per-frame render-pass queue and a set of pipeline-phase insertion points — and a feature is the authored Luau that decides what passes to enqueue, and where, every frame. ## Authoring contract A `.renderFeature` folder holds an `init.luau` that returns a feature module: ```luau return { setup = function(ctx) -- optional; runs once when the feature goes live -- A "fragment" pass's `shader` names a POST EFFECT, not a `.shader` -- guid directly — postprocess.add compiles the shader asset under -- that name once, here. Enqueueing a name never passed to -- postprocess.add runs the pass as a no-op every frame (the log -- reads "effect '<name>' not compiled — pass skipped"). postprocess.add("my_effect", asset.resolve("my.shader.guid", "shader"), { enabled = false }) end, render = function(ctx) -- required; runs every frame -- enqueue one or more passes. The spec shape depends on `kind` (see -- "Pass kinds" below): this is a "fragment" pass (full-screen shader over -- input textures); a mesh effect (outline, x-ray) is a "geometry" pass -- with `material` + `select` (see "Geometry passes"). ctx.enqueue { phase = "afterTransparent", shader = "my_effect", inputs = { src = "@scene.color" }, output = myRenderTargetGuid, } end, teardown = function(ctx) end, -- optional; runs once when the feature is destroyed } ``` Optional `materials/` and `shaders/` subfolders hold shader source the feature constructs GPU programs from. A feature constructs its GPU programs (it does not reference `.material` surface assets). ## `ctx` Built fresh each frame and passed to `setup` / `render` / `teardown`: | Field | Meaning | |-------|---------| | `ctx.enqueue(spec)` | Queue one render pass for the current frame. | | `ctx.viewport` | `{ w, h }` — the **main viewport's** size in pixels. | | `ctx.time` | Seconds since boot. | | `ctx.frame` | Monotonic frame index. | | `ctx.renderPath` | `"forward"` / `"deferred"` / … — branch passes on the active path. | | `ctx.settings` | The feature's knobs as they stand this frame — see "Settings". | ## Settings A feature declares the knobs it takes as `settings`, each a Field descriptor with a default, the way a component declares its public fields: ```luau local Fields = require("@builtin::modules.field") local Field, NoSync = Fields.Field, Fields.NoSync return { settings = { intensity = Field.number(1.0, NoSync, "How much of the effect reaches the image."), quality = Field.enum({ "low", "high" }, "high", NoSync, "How many samples the pass spends."), }, render = function(ctx) local s = ctx.settings -- { intensity = 1.0, quality = "high" }, or what a caller set ... end, } ``` The engine holds one settings table per live feature — every declared default, overridden by what it was handed — and passes it as `ctx.settings` on every `setup` / `render` / `teardown`. A feature reads its knobs there and nowhere else, so any caller tunes any feature by name: ```luau local h = renderer.feature.create(ref, { settings = { intensity = 0.5 } }) renderer.feature.configure(h, { quality = "low" }) -- lays over the rest renderer.feature.settings(h) -- { intensity = 0.5, quality = "low" } renderer.feature.find(ref) -- the live handle, or nil renderer.feature.schema(ref) -- the declared knobs, unrun ``` A knob the feature does not declare, or a value of the wrong shape, is refused by name. A scene authors its features on one `RenderFeatures` entity — a list of features, each with its settings — which adopts a feature already live rather than stacking a second, and takes every one down on disable and destroy. `render` runs **once per frame**; the passes it enqueues run **once per render target** drawn that frame — the live viewport, every offscreen capture, every RTT camera — each at its own resolution. So `ctx.viewport` is the main viewport's size, not the size of the target a pass ends up drawing into. Size a full-screen scratch RT with `screen = true` and let the engine track the drawn target (see "Screen-sized targets") rather than deriving it from `ctx.viewport`. ## Screen-sized targets `renderer.texture.create { screen = true }` marks a feature RT as full-screen: before each render target's feature passes, the engine resizes it to that target's resolution. Create it once — the engine owns its size from then on: ```luau myRt = renderer.texture.create { width = ctx.viewport.w, height = ctx.viewport.h, -- initial size only screen = true, format = "rgba16f", name = "my_effect", } ``` A target that holds a picture of the scene is `rgba16f`, which is what the scene target itself carries: linear light with headroom above the display's white and no 256-step floor under a dark gradient. Omitting `format` on a screen-sized target asks for the same thing. `format = "rgba8"` is for a mask, a weight or an occlusion term, where 0..1 is the whole range — hand one of those back over `@scene.color` and the frame loses every highlight and bands every gradient, and the engine says so in the log. `screenScale` (default `1.0`) takes a fraction of the drawn target's resolution, for a scratch that runs below composite resolution (a half-res blur passes `0.5`). A screen-sized RT is what makes a full-screen effect composite correctly at any resolution. Deriving the size from `ctx.viewport` instead pins the RT to the main viewport, and every differently-sized render target then composites a mismatched scratch — the scene scaled into a corner with the rest black. `screenSpace` names WHICH image a screen-sized RT follows: | value | what it tracks | |---|---| | `"scene"` (default) | the scene render target, at whatever resolution the render scale asked for. Resized before EVERY render target's feature phases — the main frame and each offscreen one — and cleared to transparent before an offscreen render, so one sink never reads what another left behind | | `"composite"` | the image the post-scene phases draw into. Resized on the presented frame only, and never cleared for an offscreen render, since none of those phases run there | The two carry the same size until the render scale drops below 1. From there, while the renderer presents the viewport itself, the scene reaches the display's resolution through an upscale that runs before `afterScenePost` — so a composite-space RT is the display's size while a scene-space one is the smaller rasterized frame. Under a UI viewport panel the panel draws the scene target at its own rect, nothing upscales beforehand, and both spaces carry the scene's size. A scene-space target is scratch: whatever a pass does not rewrite this render is transparent black. A composite-space target survives an offscreen render untouched, but it follows the presented frame alone. ## History targets An accumulation across frames (temporal antialiasing, a temporal denoiser, any pass that reads what it wrote last time) lives in a history target: ```luau history = renderer.texture.create { width = ctx.viewport.w, height = ctx.viewport.h, -- initial size only history = true, format = "rgba16f", name = "my_accum", } -- in render(ctx): ctx.enqueue { kind = "compute", program = myResolve, inputs = { scene_color = "@scene.color", accum_previous = history.previous.guid }, buffers = { accum_state = history.state }, storage = { accum_out = history.guid }, phase = "afterLighting", } ``` The passes a feature enqueues run once for every view the frame draws (the viewport, each render-to-texture camera, each capture), so an accumulation has to be one per view. A history target keeps one pair of images per view, sized to that view: for the length of a view's render `history.guid` names the image the render writes and `history.previous.guid` the image the same view's previous render wrote. Another view never resizes, clears or overwrites them, and a view's images are freed when it stops drawing. It follows `screenSpace` and `screenScale` like any screen-sized target; a composite-space one is kept for the viewport, the one view that draws the post-scene phases. Before each render of a view the engine writes `history.state`, one `vec4<f32>` a pass binds through `buffers`: | field | holds | |---|---| | `x` | 1 when `previous` holds this view's previous image; 0 on the view's first render, its first after a camera cut or a change of size, or after a render of the view that ran without the target, and `previous` then reads transparent black | | `y` | how many renders in a row have carried the history | | `zw` | this render's sub-pixel projection offset, in pixels (`renderer.setProjectionJitter`) | `renderer.setProjectionJitter` is the matching per-view sample sequence: every view walks it by its own count of renders, so the sequence a temporal pass expects is the one each view's renders sampled. ## Post stages A post effect belongs to one of the frame's named **post stages**, in frame order, each stating what the picture holds there: the space an effect there reads and writes (`light`, the scene's own light ahead of the display transform's exposure and tone curve, `display`, code values, or `encoded`, the presented surface's own values) and the size the picture is held at (`raster`, the size the scene rasterized; `output`, the size the frame is composed and shown at): | Stage | Space | Resolution | Runs | |-------|-------|------------|------| | `lighting` | light | raster | screen-space lighting terms: occlusion, reflections, indirect light, contact shadows | | `medium` | light | raster | participating media: fog, volumetric light | | `preTemporal` | light | raster | effects reading the jittered raster before reconstruction: depth of field | | `temporal` | light | raster | the one temporal reconstruction of the raster (TAA); the stage holds one feature at a time | | `postTemporal` | light | raster | effects reading the reconstructed picture: motion blur | | `meter` | light | reduced | measuring the picture: the exposure histogram, a fraction of the raster | | `optics` | light | raster, then output | lens light: bloom, flare, streaks. Its render features run on the raster; the frame then carries the picture to the output size, and the post-process chain's `scene` layer runs there | | `display` | display | output | the display transform, then looks on code values; the chain's `display` layer | | `ui` | display | output | the UI, drawn over the finished picture, then what grades the picture with the UI on it: `afterUI` passes, the chain's `all` layer, then `afterPost` passes | | `output` | encoded | output | the renderer's output stage alone: the one write of the presented surface, in the surface's encoding, rounded to its bit depth with a blue-noise dither (`renderer.output`). It takes no render feature and no chain effect | A feature declares the stage it belongs to, and each pass it enqueues with no `phase` runs in that stage, at the stage's phase and its band of orders plus the pass's own local `order` (a whole number from 0 to 99): ```luau return { stage = "postTemporal", render = function(ctx) ctx.enqueue { kind = "fragment", shader = "my_effect", inputs = { src = "@scene.color" }, order = 0 } end, } ``` A pass may name a `stage` of its own in place of the feature's, placed the same way; a pass naming both a `stage` and a `phase` is refused. A stage the frame does not have is refused by `renderer.feature.create`, naming the stages there are, and a second feature declaring the `temporal` stage while one stands in it is refused naming both; the `temporal` stage takes the passes of the feature declaring it alone. A pass that names a `phase` runs at that phase and `order`, as below. `renderer.post.stages()` reports every stage and what stands in it: a feature by the stage its passes' position falls in, marked `declared` where that is the stage the feature declares. ## Pass phases `enqueue` runs a pass at a named pipeline boundary — a real seam between the scene's discrete passes — ordered within a phase by `order`. Each phase is the point where the scene colour holds a specific, nameable state: | Phase | Scene colour there | |-------|--------------------| | `afterDepthPrepass` | the visibility raster written: `@scene.depth` holds this frame's complete opaque depth, and `@scene.motion` its opaque motion, before anything shades. Scene colour is not yet drawn; `@scene.colorHistory` holds the previous frame's lit colour, and the deferred g-buffer the previous frame's surfaces (`readsPrevious`) | | `afterShadows` | shadow maps populated; scene colour/depth not yet drawn | | `afterSky` | sky only; depth empty | | `afterOpaque` | opaque drawn, before transparents. `@scene.depth` (and the deferred G-buffer) are populated. Forward: lit opaque. Deferred: lit opaque too, which the geometry pass shades straight into the scene colour, on a render no pass reads or writes `@scene.shaded` in; on one that does, the opaque surfaces are in the G-buffer's shaded channel, so the colour is still sky only until the composite (use `afterOpaqueLit`). Radiance stamped into `@scene.emissive` reaches the colour at the composite | | `afterOpaqueLit` | the lit opaque scene, still before transparents, on **both** paths — the forward opaque draw, or the deferred geometry pass and composite. The background a refractive or transmissive surface samples: the one phase whose colour holds what is behind such a surface without holding the surface itself | | `afterTransparent` | transparents drawn, before the OIT composite | | `afterLighting` | deferred-lighting + OIT composite done — fully lit, final geometry on **both** paths | | `afterScenePost` | the chain's `scene` layer and the display transform done: display code values, before the chain's `display` layer and the UI | | `afterUI` | scene + UI composited | | `afterPost` | the chain's `all` layer done — the finished picture in display code values, before the output stage writes it to the surface. A pass here reads that picture as `@scene.color` and draws over a copy of it | The last three are the post-scene phases, and they work on the COMPOSITED image: `@scene.color` there is the target the UI lands on, not the scene render target. `@scene.depth` and `@scene.motion` still bind — they are the scene's own buffers for the frame just drawn, which is what lets a pass at these phases reproject the composite it is handed — but they keep the SCENE's resolution. Whenever the render scale is below 1 on the presented frame, that is smaller than `@scene.color`, so a pass here maps between the two by uv rather than by texel index, and takes its own output size from the target it writes. The `@scene.*` inputs (`@scene.color`, `@scene.depth`, …) bind the live frame buffers; the deferred g-buffer channels (`@scene.normal`, `@scene.shaded`, …) resolve only on the deferred path. Before the pass that shades has drawn — at `afterDepthPrepass` — a g-buffer channel holds the previous frame's surfaces, and a pass reading it there names the slot in `readsPrevious` (`readsPrevious = { "scene_normal" }`); one that does not is held back rather than handed a stale normal. `@scene.colorHistory` is the lit colour the target's previous render ended with, kept by the engine per render target and never cleared by a frame: what a pass tracing at `afterDepthPrepass`, against this frame's depth, takes its light from — reprojected through the previous view-projection `@frame.camera` carries. A capture drawn once, or a camera drawn again after a pause, is drawn lit first when a pass reads the history, so its first frame holds one. Every `@scene.*` channel, what it holds, its format, the phase it is first valid from, and the other names it answers to: | Name | Holds | Format | Valid from | Also named | |---|---|---|---|---| | `@scene.color` | the scene's lit colour; the display composite at a post-scene phase | the scene target's format at a scene phase, the display composite's at a post one | every phase | — | | `@scene.depth` | opaque depth, reversed (1.0 near, 0.0 far/empty sky) | `Depth32Float` — binds through a `texture_depth` compute slot, not `texture2d` | `afterDepthPrepass` on | — | | `@scene.motion` | screen-space NDC velocity since the previous frame | `Rg16Float` | `afterOpaque` on | — | | `@scene.normal` | world-space normal + the per-pixel surface-flag field | `Rgb10a2Unorm` | deferred path, `afterOpaque` on (previous frame's before — declare `readsPrevious`) | — | | `@scene.shaded` | what a surface SENT — its shaded colour, linear and scene-referred | `Rgba16Float` | deferred path, `afterOpaque` on (previous frame's before) | `@scene.albedo` | | `@scene.material` | what a surface IS — base colour (RGB565) + metallic + perceptual roughness | `Rgba8Uint` | deferred path, `afterOpaque` on (previous frame's before) | `@scene.mr` | | `@scene.emissive` | radiance a pass stamped on the surface, added at the composite | `Rgba16Float` | deferred path, `afterOpaque` on (previous frame's before) | — | | `@scene.ao` | scene occlusion a feature wrote, read back by shading | `Rgba8Unorm` | every scene phase (cleared at the top of the scene render) | — | | `@scene.reflection` | traced reflection radiance (`.rgb`) + confidence (`.a`) | `Rgba16Float` | every scene phase (cleared at the top of the scene render) | — | | `@scene.colorHistory` | the lit colour the target's previous render ended with | `Rgba16Float` | every phase | — | | `@scene.lights` | the punctual-light storage buffer: 64 light entries of twelve vec4s each (the light, then its punctual shadow record), followed by the virtual shadow map's region. A loop runs over the first `@frame.camera[4].w` entries, the lights in use; the buffer's length counts the shadow region too, so `arrayLength` does not size a light loop | storage buffer | every phase | — | | `@scene.environment` | the reflection-probe cube array | texture cube array | scene phases only | — | | `@scene.environmentSampler` | the filtering sampler for `@scene.environment` | sampler | scene phases only | — | | `@scene.reflectionProbes` | the environment buffer: the probe blend data naming which probe reaches a point, then the irradiance light-probe volumes | storage buffer | scene phases only | — | The rendering and ray-tracing guides (`guides { path = "topics/rendering" }`, `guides { path = "topics/raytracing" }`) point here rather than repeating this table. **Two g-buffer channels describe the surface, and they answer different questions.** `@scene.shaded` is what a surface SENT — the colour the geometry pass shaded it to, linear and scene-referred, so a surface lit above the display's peak reads above 1 there. `@scene.material` is what the surface IS: the base colour it reflects, its metallic and its perceptual roughness, each in [0, 1] and each independent of how brightly the surface happens to be lit. A pass that multiplies incoming light by a reflectance — a bounce multiplier, a Fresnel tint, an ambient floor — reads `@scene.material`; a pass that filters the picture reads `@scene.shaded`. `@scene.material` is an `Rgba8Uint` channel packing all three into 32 bits, so its slot declares `sample: uint` and the module unpacks it: ```yaml # bindings.yaml - { name: scene_material, kind: texture2d, sample: uint } ``` ```wgsl #include "@builtin::shaderModules.gbuffer_material" let m = zero_gbuffer_material(scene_material, coord); let bounce = incoming * m.base_color; ``` `@scene.albedo` is another name for `@scene.shaded` (the SHADED lit colour) and `@scene.mr` for `@scene.material` (the material channel). The engine logs the substitution once per name, naming the canonical one to write. `@scene.motion` carries screen-space velocity: the NDC displacement each pixel's surface underwent since the previous frame, so a still surface under a still camera reads `(0, 0)`. Opaque geometry contributes it on both render paths: the visibility raster writes it for every surface it records, and an opaque surface whose depth state the raster cannot express writes its own where it draws. A moving entity, a moving camera and an animated pose all reach it in the viewport; transparents, particles and sky carry none. A surface a material's `vertex()` hook displaces carries the displacement's own velocity. A render target's own camera and a capture keep no view history, so velocity there is the entity's motion with no camera term. `@frame.camera` is a reserved **buffer** input carrying the camera CURRENTLY being drawn: 10×`vec4<f32>` = the inverse view-projection (columns `[0..4)`, column-major) + camera world position (`[4].xyz`) + the previous render's view-projection (columns `[5..9)`), which projects a point into the picture that render left. A compute pass declares a `buffer` binding and binds it via `inputs = { name = "@frame.camera" }`, then reconstructs a pixel's world position from `@scene.depth`: ```wgsl let inv_vp = mat4x4<f32>(cam[0], cam[1], cam[2], cam[3]); // ndc.z is the `@scene.depth` sample itself. Scene depth is reversed — 1.0 is // the near plane, 0.0 the far plane and empty sky — and this matrix inverts // that same range, so a sample goes in unmodified. let wh = inv_vp * vec4<f32>(ndc, 1.0); let world_pos = wh.xyz / wh.w; ``` Like `@scene.*`, the engine resolves it **per render target** — so the same pass reconstructs against the live viewport's camera on screen and against an offscreen capture's / RTT camera off screen. (Pack a camera matrix into your own buffer instead and the offscreen render reconstructs against the wrong camera.) > Render-feature passes run in the main viewport render **and** in offscreen > captures / render-to-texture, each against its own camera. The `capture` tool's > `source = "position"` / `"entity"` therefore run the pass queue too; using > `@frame.camera` is what keeps those captures matching the live viewport. ### The environment A compute pass reads the scene's captured surroundings — the reflection-probe cube array, its sampler and the environment buffer (the probe blend data, then the irradiance light-probe volumes) — through three reserved inputs, bound to bindings of the shapes group(0) binds them in: ```yaml bindings: - { name: environment_map, kind: textureCubeArray } - { name: environment_sampler, kind: sampler } - { name: zero_environment, kind: buffer, access: read, element: ZeroEnvironment, array: false } ``` ```luau inputs = { environment_map = "@scene.environment", environment_sampler = "@scene.environmentSampler", zero_environment = "@scene.reflectionProbes", } ``` Named like that, `#include "zero::environment"` in the shader resolves the environment at a world point along a direction — `zpbr_sample_environment(world_pos, dir, lod)`, the probes whose radius reaches the point blended by rank and proximity, each through its proxy volume, and the sky under them — exactly as a material's environment term does, so a reflection a pass draws and one a material draws agree about the room they are in. The three bind at the scene phases; a post or UI phase carries none. A `textureCubeArray` binding takes `@scene.environment` alone, and a fragment pass has no slot of that shape. ## Pass kinds `enqueue` runs one of five kinds (the `kind` field; default `"fragment"`): - **`"fragment"`** — a full-screen shader over input textures. The program is a GPU **material** (or `shader`) the feature constructed; `inputs` bind live textures (`@scene.*` or RT guids), `output` is the target RT (omit = the phase's default scene target). Post-process, blur, edge effects. **Writing named G-buffer channels (`outputs`).** Instead of the single `output` RT, a fragment pass may declare an `outputs` array — one or more targets, each a named engine channel (`@scene.shaded` / `@scene.normal` / `@scene.emissive` / `@scene.color`) or an RT guid — each with its own blend mode: ```luau ctx.enqueue { kind = "fragment", shader = myShaderKey, outputs = { { target = "@scene.shaded", blend = "under" }, -- premultiplied dst-over-src { target = "@scene.emissive", blend = "additive" }, -- one fullscreen pass, two targets (MRT) }, phase = "afterOpaque", -- deferred: G-buffer filled, before the composite } ``` Blend modes: `"replace"` (overwrite), `"alpha"` (source-over), `"additive"` (sum), `"under"` (premultiplied dst-over-src — accumulates coverage-weighted contributions). A `@scene.*` channel resolves only where it exists (the deferred G-buffer at a pre-composite phase); a pass whose targets are all unavailable at its phase is skipped (logged). `output` + `blend = true` remains the shorthand for a single alpha-blended target. The shader's returned colour is written to every target in the set. A fragment shader returns `vec4<f32>`, so the channels it can target are the float ones. `@scene.material` (also named `@scene.mr`) is `Rgba8Uint`, which binds as `uint` — naming it as an output is refused by name, with the channel's format and class in the log, and the rest of the frame draws. A fragment pass's `inputs` reads through the same fixed float slot, so naming `@scene.material` there is refused the same way; a compute pass reads that channel through a `sample: uint` slot instead. **What a pass with no `inputs` samples.** A fragment pass that declares no `inputs` reads `@scene.color` — the shape of an effect that filters the scene image. A pass that names `@scene.color` among its own `outputs` samples a 1x1 transparent texel instead, because the scene colour is that pass's render target and one texture is a colour attachment or a sampled resource in a render pass, never both. Declare `inputs = { src = "@scene.color" }` and write an RT to read the scene image and write somewhere else in one pass. - **`"compute"`** — a workgroup dispatch (`shader`, `storage`, `buffers`, `dispatch`; see "Compute passes"). - **`"geometry"`** — draw scene geometry with a constructed pipeline. The program is a **material** the feature built (`renderer.material.create`); the engine draws the scene's render-objects with that material's pipeline + uniforms. - **`"draw"`** — rasterize the feature's OWN geometry: `geometry` names a buffer created with `usage = { "vertex" }`, `storage.index` one created with `usage = { "index" }`, and `select` the one entity whose transform and material the draw lands through. `params[0]` is how many indices to submit — or name a buffer under `storage.indirect` (created with `usage = { "indirect" }`, holding a `DrawIndexedIndirectArgs` block: index count, instance count, first index, base vertex, first instance) and the count comes from the GPU instead, so a compute pass that compacts geometry pays only for what it kept and nothing waits on a read-back. `first_instance` must be 0; the engine resolves the entity's per-instance data another way, because a non-zero one needs a device feature WebGPU does not guarantee. - **`"splat"`** — rasterize a compute buffer of particle records as instanced camera-facing billboards into feature RTs (see "Splat passes"). ### Geometry passes A geometry pass re-draws the scene's meshes with a material you supply — the generic primitive for mesh-space effects (the engine names none of them): ```luau ctx.enqueue { kind = "geometry", material = myMaterial, -- the HANDLE renderer.material.create -- returned (or its registry-key string) geometry = "@geometry.opaque", -- which drawables: "@geometry.opaque" | -- "@geometry.transparent" | "@geometry.all" select = { entityA, entityC }, -- OPTIONAL: restrict to these entities -- (entity refs); omit = every matching mesh phase = "afterLighting", -- afterLighting = lit scene + valid depth } ``` `select` restricts the draw to the given entities — the per-instance signal that turns a whole-scene pass into a chosen-meshes effect. The **material** decides how those meshes are drawn; you control three things: - **Pipeline render-state.** `renderer.material.create` takes a `render` block — `cull` (`back`/`front`/`none`), `depthWrite` (bool), `blend` (`opaque`/`alpha`/`additive`) — so the pass can rasterize differently from the surface pass: ```luau local myMaterial = renderer.material.create({ shader = myShaderKey, -- a .shader you authored (identity, not guid) render = { cull = "none", depthWrite = false }, properties = { outline_color = { 1, 0.4, 0, 1 } }, -- seed the shader's uniforms }, "my_pass_mat") -- pass `myMaterial` (or "my_pass_mat") as the pass `material` ``` - **The shader.** A geometry `.shader` is a surface shader: author `fn vertex(v: VertexData) -> VertexData` to move vertices (object-local `v.position` / `v.normal`) and `fn fragment(input: FragmentData) -> vec4<f32>` for the colour. - **Its properties.** A shader reads ONLY the uniforms IT declares in `properties.yaml`, via `material.<yourProp>`. Referencing a field it didn't declare (e.g. a StandardMaterial `material.base_color`) fails to compile and the mesh renders **magenta** — declare the property or use a constant. What effect those three produce (outline, x-ray, wireframe, highlight, …) is yours to design — the engine just draws the selected geometry with your pipeline. ### Compute passes A compute pass dispatches a `.computeShader` program over a workgroup grid: ```luau ctx.enqueue { kind = "compute", program = myComputeShader, storage = { outTex = myStorageRtGuid }, -- slot -> storage-texture RT guid buffers = { particles = "my_particle_buf" },-- slot -> named compute buffer inputs = { camera = "@frame.camera" }, -- slot -> @frame.*/@scene.* buffer dispatch = { x = 64, y = 1, z = 1 }, } ``` **`dispatch` is optional.** Omit it and the pass is dispatched over what it WRITES: a grid covering its first `storage` texture, at the `@workgroup_size` the shader's entry point declares. With a screen-sized storage target that grid tracks the render target being drawn, so a screen-space effect covers the live viewport, an offscreen capture and an RTT camera without the feature knowing any of their resolutions: ```luau ctx.enqueue { kind = "compute", program = myComputeShader, inputs = { scene_color = "@scene.color", cam = "@frame.camera" }, storage = { outTex = myScreenSizedRt.guid }, -- screen = true phase = "afterLighting", } ``` State an explicit `dispatch` for a grid that is not one thread per output texel (a reduction, a particle sim), or when the shader's `@workgroup_size` is an override/const expression the engine cannot read. Each WGSL storage-buffer binding in the shader resolves its bound slot in this order: an explicit `buffers` mapping (the handle a buffer's owner holds, or a name), then `inputs` (`@frame.camera` / `@scene.lights` / `@scene.reflectionProbes`), then — when a slot has neither — a buffer whose engine-side name equals the slot's own name. `buffers` is the seam a pass binds through: the buffers a shader works over are the ones handed to it, whatever each is called. `storage` binds storage TEXTURES (RT guids) the same way, one map per resource kind. ### Splat passes A splat pass draws every record of an f32 buffer as a camera-facing billboard — the raster primitive behind screen-space particle surfaces (the `fluidSurface` system is built entirely on it): ```luau ctx.enqueue { kind = "splat", phase = "afterLighting", output = depthRt.guid, -- or `outputs` for the thickness+color MRT splat = { buffer = "my_particles", -- compute-buffer name stride = 12, -- floats per record posOffset = 0, -- float offset of the position count = 200000, -- records to draw radius = 0.3, -- world particle radius channel = "depth", -- "depth" | "thickness" | "sprite" | "gaussian" velOffset = 4, -- optional: velocity → screen-space stretch stretch = 0.04, -- seconds of motion elongating the billboard colorOffset = 8, -- optional (thickness): + per-particle RGB → MRT weightOffset = 7, -- optional (sprite): per-particle intensity minY = -60.0, -- records below this y collapse (parked/dead) maxRadiusPx = 120, -- optional: cap on the projected pixel radius }, } ``` The `"gaussian"` channel draws the engine's packed splat records — what `renderer.splat.components` decodes a `.spz` or `.ply` capture into — as elliptical-weighted-average Gaussians, and takes fields of its own: ```luau splat = { buffer = "cloud_records", stride = 6, -- the packed record is six u32 words posOffset = 0, count = 1200000, radius = 1.0, -- multiplies each splat's stored scale channel = "gaussian", orderBuffer = "cloud_order", -- back-to-front permutation; "over" needs one shBuffer = "cloud_sh", -- optional: quantized higher-order SH shStride = 24, -- u32 words of SH per record shDegree = 3, transform = model, -- object -> world, column-major, 16 floats prevTransform = prevModel, -- where `transform` stood last frame opacityScale = 1.0, } ``` `transform` places the cloud: each Gaussian's covariance is conjugated by its upper-left 3×3, so a non-uniform scale shears the cloud the way it shears a mesh. `prevTransform` plus a second entry in `outputs` makes the channel write an MRT pair — the colour into the first target, and the screen-space displacement each splat underwent between the two placements into the second, premultiplied by the same alpha the colour composites under. That second target therefore resolves to `(coverage-weighted mean displacement, coverage)`, which is what folds a moving cloud into `@scene.motion`. Naming one target, or leaving `prevTransform` out, renders the colour alone. The other three channels write different fragments: `"depth"` writes nearest-surface linear view depth (R32Float, hardware-depth-tested on the target's own depth buffer), `"thickness"` accumulates additive optical thickness (with `colorOffset` and a two-entry `outputs` list it also accumulates thickness-weighted color into the second target), and `"sprite"` accumulates a soft additive disc scaled by `weightOffset`. Every channel discards fragments behind opaque scene geometry by sampling the scene depth at the fragment's own NDC. `maxRadiusPx` scales down billboards whose projected major radius would exceed that many pixels, so particles crossing the near plane stay droplet-sized instead of filling the screen. Targets clear at the pass; `blend = true` on the spec loads them instead to accumulate over a prior splat pass. `renderer.feature.create(featureRef)` instantiates a feature and returns a live handle (`featureRef` may be an `AssetRef<renderFeature>` or its identity string). The handle appears under `/zero/runtime/generated_features/<guid>/` for exactly as long as the framework runs the feature's `render`. Its `info` names the feature and its guid, and its `setup:` line states how `setup` ended: `ok`, `none` for a feature that declares no `setup`, or `raised: <error>`. Re-creating the SAME feature asset replaces the live one (hot-reload after editing `init.luau`) rather than stacking a duplicate. A feature whose `render` raises is logged (`[renderer.feature] '<identity>' render error: ...`) and released the way `renderer.feature.destroy` releases one: its `teardown` runs, its passes are withdrawn, it leaves `renderer.feature.list()`, its runtime folder and registry row go, and every handle to it reads `released`. `renderer.feature.find(handle)` answers nil for it, which is how a module holding a handle tells that its feature stopped. - `renderer.feature.list()` → `{ {guid, identity} }` for every live feature. - `renderer.feature.destroy(handleOrGuid)` (or `renderer.destroy(handle)`) tears one down — by handle OR by guid string, so you can stop a feature even after losing its handle (e.g. across separate `execute` calls). ## In the Inspector Selecting a render feature opens its **Feature** section: whether the feature runs in this session, an Enable or Disable action, and its settings as typed controls. While it runs, the controls hold its live values and an edit reconfigures the running feature (`renderer.feature.configure` checks it against the schema first). Those edits are session state: they change the running feature only, they are not undoable (Ctrl+Z never reaches them), and Disable or a restart ends them; the feature's declared defaults are what the next Enable starts from. While it does not run, the controls show the declared defaults, read-only, and a write reaching it then is refused. A feature enabled, disabled or reconfigured from a script shows in the section as it happens. A feature that declares no settings says so.
▲ 0↑ born
·
assettype · born here
❒asset
# mesh A mesh is renderable geometry — vertices and triangle indices, and, for a skinned mesh, the per-vertex skinning data that binds it to a skeleton. A component that draws geometry references a mesh, and the renderer binds the mesh's GPU resource for that entity. > New to how a mesh exists as an asset, as CPU-side vertex data, and as a live > GPU resource (and how `renderer.mesh.*` moves between them)? Read > `core/resource-model` first. Geometry is stored in `data.zmsh`; the GPU resource is keyed by the asset's guid. ## Create `asset.create("mesh", name, opts)` writes the geometry and registers the mesh. `opts` is raw geometry — flat arrays; `positions` and `indices` are required, `normals` and `uvs` optional: ```luau asset.create("mesh", "tri", { positions = { 0,0,0, 1,0,0, 0,1,0 }, -- [x,y,z, ...] (required) indices = { 0, 1, 2 }, -- [i0,i1,i2, ...] (required, 0-based) normals = { 0,0,1, 0,0,1, 0,0,1 }, -- [x,y,z, ...] (optional) uvs = { 0,0, 1,0, 0,1 }, -- [u,v, ...] (optional) }) ``` The full authorable geometry, all flat arrays unless noted: | Field | Shape | Notes | |---|---|---| | `positions` | `[x,y,z, ...]` | required | | `indices` | `[i0,i1,i2, ...]` | required; 0-based, counter-clockwise for the front face (see Conventions) | | `normals` | `[x,y,z, ...]` | optional; the surface's outward direction | | `uvs` | `[u,v, ...]` | texture UVs, optional; `(0,0)` is the image's top-left | | `colors` | `[r,g,b,a, ...]` | optional | | `tangents` | `[x,y,z,w, ...]` | optional (`w` = handedness) | | `uvs1` | `[u,v, ...]` | the lightmap UV set, optional | | `unwrapUvs` | boolean | generate `uvs1` when it is absent | | `skinning` | `{ joints, weights }` | per-vertex skin binding (four each per vertex) | | `skins` | array of skin tables | the skeleton (see `renderer.mesh.decode` for the shape) | | `morphTargets` | array of `{ name?, positions, normals? }` | the shapes the mesh blends towards, each a per-vertex displacement | `encode` / `decode` round-trip every one of these, so a **skinned** mesh can be built in engine, not only imported. Pass `unwrapUvs = true` to generate a lightmap UV set at creation time. ## Conventions Geometry is read against these whether it arrived through `asset.create`, `renderer.mesh.create`, or an importer. | Convention | How the engine reads the geometry | |---|---| | Index base | `indices` count vertices from **0** — index `0` is the first `positions` triple. The Luau array carrying them is 1-based like any other, so `indices[1]` is the first triangle's first index, and vertex `v` has its x at `positions[v * 3 + 1]`. | | Triangle winding | A triangle's **front** face is the one whose three vertices turn **counter-clockwise** as the viewer sees them. Put another way, `cross(v1 - v0, v2 - v0)` points out of the front face. | | Back faces | A material culls its back faces by default, so a triangle turned away from the camera draws nothing where it stands and whatever is behind it shows through. | | Normals | `normals` give the surface its outward direction and shade the face. Which side of a triangle draws comes from the index order alone, so a normal pointing away from the side the winding draws leaves that face standing and shades it as if the light were behind it. | | UVs | `(0, 0)` samples the first texel of an image — its top-left corner — and `v` grows downward through it. | | Axes | Model space carries the world's basis: `+X` right, `+Y` up, and `-Z` the direction an entity's `transform.forward` points. | Winding is what the author states: the inward faces of a room and a sky shell seen from inside are geometry meant to be wound the other way, and `asset.create` writes the index order it is handed. Two levers turn a face around: ```luau indices = { 0, 2, 1 } -- the same three vertices, reversed asset.create("material", "two_sided", { -- or keep the order and draw both sides shader = "@builtin::shaders.pbr", render = { cull = "none" }, }) ``` `cull = "front"` draws the far side by itself, which is what an inverted-hull outline is built on, and `"back"` is the default. `.shader` documents the whole `render` block a material's `mat.yaml` carries. A mesh states which way its own triangles face, so the question is answerable off the geometry — every triangle whose cross product agrees with the normal it carries is wound to draw the side that normal points at: ```luau local cpu = meshRef:load() local g = cpu:geometry() local function facesOutward(t: number): boolean -- t counts triangles from 0 local i = { g.indices[t * 3 + 1], g.indices[t * 3 + 2], g.indices[t * 3 + 3] } local function p(k: number, c: number): number return g.positions[i[k] * 3 + c] end local ax, ay, az = p(2,1) - p(1,1), p(2,2) - p(1,2), p(2,3) - p(1,3) local bx, by, bz = p(3,1) - p(1,1), p(3,2) - p(1,2), p(3,3) - p(1,3) local cx, cy, cz = ay*bz - az*by, az*bx - ax*bz, ax*by - ay*bx local n = i[1] * 3 return cx * g.normals[n+1] + cy * g.normals[n+2] + cz * g.normals[n+3] > 0 end local inward = 0 for t = 0, #g.indices // 3 - 1 do if not facesOutward(t) then inward += 1 end end cpu:unload() ``` ## Built-in primitive meshes The engine ships blockout geometry every world references by bare name (`{ model = "cube" }`). Each one is centred on its local origin, so an entity's `scale` reads directly as the size the mesh covers in the world: | Mesh | Extent (x, y, z) | Local AABB | |---|---|---| | `cube` | 1 x 1 x 1 | `-0.5, -0.5, -0.5` .. `0.5, 0.5, 0.5` | | `sphere` | 1 x 1 x 1 | `-0.5, -0.5, -0.5` .. `0.5, 0.5, 0.5` | | `cylinder` | 1 x 1 x 1 | `-0.5, -0.5, -0.5` .. `0.5, 0.5, 0.5` | | `cone` | 1 x 1 x 1 | `-0.5, -0.5, -0.5` .. `0.5, 0.5, 0.5` | | `octahedron` | 1 x 1 x 1 | `-0.5, -0.5, -0.5` .. `0.5, 0.5, 0.5` | | `rounded_box` | 1 x 1 x 1 | `-0.5, -0.5, -0.5` .. `0.5, 0.5, 0.5` | | `capsule` | 0.5 x 1 x 0.5 | `-0.25, -0.5, -0.25` .. `0.25, 0.5, 0.25` | | `torus` | 1 x 0.3 x 1 | `-0.5, -0.15, -0.5` .. `0.5, 0.15, 0.5` | | `plane` | 1 x 0 x 1 | `-0.5, 0, -0.5` .. `0.5, 0, 0.5` | | `ground_quad` | 1 x 0.1 x 1 | `-0.5, -0.05, -0.5` .. `0.5, 0.05, 0.5` | | `ground_hex` | 1.732 x 0.1 x 2 | `-0.866, -0.05, -1` .. `0.866, 0.05, 1` | | `shader_ball` | 0.933 x 1 x 0.933 | `-0.467, -0.5, -0.467` .. `0.467, 0.5, 0.467` | `plane` is a flat quad in the XZ plane, so it has no vertical extent at all and scaling it on Y moves nothing. `meshRef:load():getBounds()` reads the same numbers back off any mesh, built-in or authored. ## Put a mesh on an entity A component draws a mesh through a `resource("mesh")` field, which accepts the mesh **by name, by ref, or as a `MeshHandle`** — the component resolves whatever you give it. The builtin `Model` and `SkinnedModel` both expose a `model` field: ```luau entity.find("box").component.add("Model", { model = "tri" }) -- by name entity.find("box").component.add("Model", { model = asset.ref("tri") }) -- by ref entity.find("box").component.add("Model", { model = meshHandle }) -- a MeshHandle (below) ``` ## Runtime mesh — no asset Build geometry straight onto the GPU and render it without creating an asset. The `resource("mesh")` field takes the returned `MeshHandle` directly: ```luau local h = renderer.mesh.create({ positions = {0,0,0, 1,0,0, 0,1,0}, indices = {0,1,2} }) entity.find("box").component.add("Model", { model = h }) ``` Its geometry reads back off the handle. `renderer.mesh.geometry(mesh)` returns the same flat-array `MeshGeometry` `create` takes, carrying every stream the mesh has — so a runtime mesh can be inspected, edited, and rebuilt without ever becoming an asset: ```luau local geom = renderer.mesh.geometry(h) -- { positions, indices, tangents?, ... } geom.positions[1] = 0.5 local h2 = renderer.mesh.create(geom) ``` An optional stream is present only when the mesh carries one, so `geom.tangents` answers whether the mesh has a tangent basis and `geom.uvs1` whether it has a second UV set. ## Read geometry — `meshRef:load()` `:load()` decodes `data.zmsh` into the CPU store and returns a CPU handle carrying `vertexCount` / `indexCount`: | Method | Returns | |---|---| | `cpu:getVertices()` | array of `{ pos = {x,y,z}, normal = {x,y,z}, uv = {u,v} }`, one per vertex | | `cpu:getTriangles()` | array of `{ v1, v2, v3 }`, each a full vertex (the shape above) | | `cpu:getBounds()` | `{ min = {x,y,z}, max = {x,y,z} }` — the local-space AABB | | `cpu:geometry()` | the complete `MeshGeometry` — flat arrays, every stream the mesh carries | | `cpu:encode()` | the `data.zmsh` bytes | | `cpu:unload()` | drop this guid's CPU copy | ```luau local cpu = meshRef:load() local v = cpu:getVertices()[1] -- { pos = {x,y,z}, normal = {x,y,z}, uv = {u,v} } local aabb = cpu:getBounds() cpu:unload() ``` By default the CPU copy is transient (decode → read → `unload`). Set `keepCpu` to keep it resident — see Settings. ## Write geometry back — `meshRef.primary` The inverse of reading: encode a `MeshGeometry` and write it to the asset's primary content file. The assetType picks the write up and re-uploads the live GPU mesh, so the change shows without a reload: ```luau local geom = renderer.mesh.geometry(meshRef) geom.tangents = computeTangents(geom) -- add a stream it did not carry vfs.write(meshRef.primary, renderer.mesh.encode(geom), { overwrite = true }) ``` `meshRef.primary` is the asset's `data.zmsh` path. This is the route for a stream with no setting of its own; `keepCpu` + `meshRef:setVertices` moves positions in place, and `lightmapUvs` regenerates the second UV set (both below). ## GPU handle — `meshRef:handle()` `:handle()` uploads the geometry (Disk → CPU → GPU) and returns a `MeshHandle`, cached on the asset so every consumer shares ONE GPU entry. A component does this for you when you pass it the mesh; call it directly only for the runtime/low-level path. ## Settings — `meshRef:settings()` / `meshRef:setSettings(patch)` A mesh's settings are declared in `settings.luau` and live in `settings.yaml`. `:settings()` returns them with every declared default filled in. `:setSettings(patch)` writes any subset — sibling settings are preserved, and a patch that fails the schema is refused, naming the field and why. | Setting | Type | Default | Meaning | |---|---|---|---| | `keepCpu` | boolean | `false` | Keep the CPU geometry copy resident — for an in-use mesh — so geometry can be read repeatedly without re-loading. | | `lightmapUvs` | string | `"keep"` | The mesh's second (lightmap) UV set. `"keep"` leaves the stored geometry's set as-is; `"generate"` unwraps a fresh non-overlapping set; `"none"` strips it. See below. | | `clusterLod` | boolean | `true` | How deep the cluster set is built. Every static mesh draws through clusters, from the frame it materialises (its `lod0` set) until its bake lands. `true` (default) builds the LOD hierarchy; `false` builds one level, drawn at full detail. | ```luau local s = meshRef:settings() -- { keepCpu = false } meshRef:setSettings({ keepCpu = true }) ``` `keepCpu` is an active lifecycle control, and only ever holds geometry for a mesh that is **in use** (GPU-resident): - Setting it **on** while the mesh is in use loads the CPU copy immediately. - Setting it **on** for a mesh that is **not** in use loads nothing — the copy is retained the next time the mesh is materialised, so an unused mesh is never pinned in memory. - Setting it **off** drops a resident CPU copy (the renderer keeps drawing from the GPU). `clusterLod` is the same kind of lifecycle control, for the depth of the cluster set rather than the CPU copy: - Setting it **off** on a mesh in use rebakes it as one level of clusters (`single`), drawn at full detail. - Setting it **on** on a mesh in use rebakes the LOD hierarchy (`dag`). - A mesh that is not in use bakes at the depth the setting asks for when it next materialises. Acting on either setting for a mesh in use can read the mesh's stored geometry, and where the geometry is fetched on first read that read spans frames. `meshRef:settingsPending()` answers whether one is still in flight; once it answers `false`, every settings change made so far has reached the mesh. ### Second UV set (`lightmapUvs`) A mesh can carry a **second**, independent UV set (`uv1`) alongside its texture UVs (`uv`) — a distinct per-vertex channel, non-overlapping where the texture UVs tile and reuse charts. `lightmapUvs` controls whether the stored geometry keeps one, generates one, or drops it: | Value | Effect | |---|---| | `"keep"` | Leave the stored geometry's `uv1` as-is (the default). | | `"generate"` | Unwrap a fresh non-overlapping `uv1` (near-planar charts packed into `[0,1]` with gutters). | | `"none"` | Strip the `uv1` set. | ```luau meshRef:setSettings({ lightmapUvs = "generate" }) ``` Changing the setting reprocesses the asset's geometry in **edit** mode; a change in play mode never rewrites the source. The reprocess round-trips the geometry through the codec, so positions, normals, tangents, skinning, and the skeleton are preserved — only the `uv1` set changes. A runtime mesh carries `uv1` the same way: pass `uvs1` (or `unwrapUvs = true`) to `renderer.mesh.create`. ## Read vertices — `meshRef:getVertices()` With `keepCpu` on for an in-use mesh, read its vertices straight from the resident CPU copy: ```luau meshRef:setSettings({ keepCpu = true }) -- on an in-use mesh local verts = meshRef:getVertices() -- { { pos = {x,y,z}, normal = {x,y,z}, uv = {u,v} }, ... } ``` If the CPU copy isn't resident — `keepCpu` is off, or the mesh isn't in use — it errors loudly, naming the reason and the remedy, rather than silently loading a throwaway copy: ``` mesh:getVertices: cannot read vertices — keepCpu is off, so no CPU copy is kept. Turn on CPU retention for an in-use mesh first: meshRef:setSettings({ keepCpu = true }). ``` ## Morph targets — `meshRef:morphTargets()` A mesh can carry morph targets: shapes it blends towards, each a per-vertex displacement from the base geometry. Every target carries the name it was authored under, and an imported model keeps the one its source file gave its blend shapes, so content addresses a shape as the thing it means rather than as the ordinal it happened to import at. ```luau for i, name in meshRef:morphTargets() do print(i, name) end -- 1 Eyes_Blink ``` An entity blends them with `ecs.MorphWeights`, weight `i` driving target `i`. `renderer.mesh.morphWeights(mesh, { Eyes_Blink = 1 })` builds that ordered array from weights named by shape — shapes left out sit at 0, and an unknown name errors listing the ones the mesh carries. ## Discovery | Call | Shows | |---|---| | `asset.list("mesh")` | every registered mesh | | `asset.inspect("<name>")` | a text report about the mesh (metadata, source, status) | | `meshRef:settings()` | the resolved settings | | `meshRef:settingsPending()` | whether a settings change is still reading the stored geometry | | `meshRef:morphTargets()` | the shapes it blends towards, named, in target order | For the on-disk shape of a mesh asset, run `asset.inspect("<name>")` or read the type's `type.yaml` — those are the live source of truth. ## Related - `renderer.mesh.*` — the GPU/CPU resource layer (`create` a runtime GPU mesh, `encode`/`decode` the `ZMSH` payload, `readback` GPU → CPU). `:load`/`:handle` wrap it; see `man renderer`. - `.material` + `.shader` — what shades the geometry. - `.bundle` — container assets that carry `.mesh` interiors. ## In the Inspector Selecting a mesh opens its **Geometry** section, after the asset's identity and before its Settings. It reports what `data.zmsh` holds, decoded once per payload version: vertices, triangles, the bounds and their size, the vertex streams beyond positions (normals, uvs, uvs1, colors, tangents, skinning), and, when the mesh has them, its skin joints and morph targets. While the renderer holds the mesh's cluster hierarchy, the section also reports its cluster and level counts. A payload is one index stream, so the section names no submeshes. A mesh folder with no `data.zmsh` says so.
▲ 0↑ born
▣
module · born here
❒asset
# 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
▣
module · born here
❒asset
# assetType.shared.ref Builds the metatable every `AssetRef` (the `{ __ref, type, name, guid, identity, path }` envelope returned by `asset.resolve` / `asset.ref`) carries. Replaces the per-call C metatable that used to live in `crates/zero_scripting/src/ffi/bindings/asset.rs::attach_asset_ref_metatable`. ## Public API ```lua local assetRef = require("@builtin::assetTypes.assetType.shared.ref") -- Called by the Rust factory (push_asset_ref_handle) via -- _G.__build_asset_ref_proxy after the envelope fields are set. assetRef.build(envelope) -- attaches AssetRefMT, returns the table ``` The module exposes no invalidation surface — discovery is registry-driven and hot-reload is transparent (see "Discovery and hot-reload" below). ## Method dispatch order `ref.foo` is resolved in this order: 1. **Default methods** — `getSource` / `getBytes` / `getText` / `exists` / `inspect` and the lazy `meta` property. Per-type definitions cannot override these (engine contract from gh#1889). 2. **Per-type `ref` table** — discovered through `asset.resolve(<typename>, "assetType")` + `require(<identity>.behavior)`. The lookup resolves to whichever `<typename>.assetType/` folder is currently registered for the typename (built-in, user, or library-vendored) and pulls its `ref` methods. 3. **Nil** — unknown key, same shape as the original C metatable. ## Adding methods for a new asset type Drop a `behavior.luau` into the type folder: ``` src/lua/lib/assetTypes/<typename>.assetType/ ├── type.yaml -- structural spec (existing) ├── behavior.luau -- ref + global behaviour (new) └── template/ -- placeholder body (existing) ``` `behavior.luau` returns: ```lua return { ref = { --!desc Per-instance method on every `<typename>` AssetRef. myMethod = function(self, ...) ... end, }, global = { -- Reserved for the asset.<typename>.* surface — not consumed -- yet; included so the contract from gh#1889 lands cleanly. }, } ``` Within `ref` methods, `self` is the AssetRef envelope: `self.path`, `self.identity`, `self.guid`, `self.type`, `self.name` are available. Engine-required fields (`guid`, `path`, `identity`, `type`) must not be redefined. ## Discovery and hot-reload Type discovery uses the asset registry, so it doesn't matter where a `<typename>.assetType/` folder lives — engine built-ins under `@builtin::assetTypes.<X>`, user types dropped under `/zero/source/<X>.assetType/`, or types vendored inside an imported library all resolve identically. The dispatcher walks `asset.resolve(<typename>, "assetType")` → canonical identity → `require <identity>.behavior` on every miss; the asset registry is the cache for the resolve half and Luau's `_LOADED` is the cache for the require half. Hot-reload is transparent. When a `<typename>.assetType/behavior.luau` is rewritten through VFS, the engine's `invalidate_require_cache_for_state` re-runs the module and mutates the cached `_LOADED[<identity>.behavior]` table in place. Dispatch reads `mod.ref` on every access (rather than caching a sub-pointer), so existing AssetRefs see the new methods on the very next access — no Rust-side hook into this module is needed, and no invalidation API is exposed for callers to call. The same registry-driven path also handles type **registration** correctness: dropping a new `<typename>.assetType/behavior.luau` updates the asset registry, the next `asset.resolve(<typename>, "assetType")` returns the new ref, and AssetRefs of that type immediately gain the new methods. ## Why Luau, not Rust The asset surface needed per-category behaviour (`material:getProperties()`, `bundle:instantiate(entityId)`, `tool:run(args)`) and the old shape couldn't grow without an FFI change per method. Owning the proxy in Luau means: - Type-specific methods ship as content (the `<typename>.assetType/` folder), not engine code. - Adding a new asset type drops in a new folder; no Rust rebuild. - Methods can call any other Luau global (`vfs`, `asset`, `Material`, `entity`, etc.) directly, instead of going through narrow FFI primitives. ## Consumers - `crates/zero_scripting/src/ffi/bindings/asset.rs::attach_asset_ref_metatable` — the Rust factory that pushes envelopes invokes `_G.__build_asset_ref_proxy` once per push. - Every Luau call site of `asset.resolve` / `asset.ref` / `entity(id).component.X.material` / any binding declared `AssetRef<...>` — they all receive envelopes built through this module.
▲ 0↑ born
▣
module · born here
❒asset
# yaml.module YAML decode + encode for authored engine content. Pure Luau, no engine dependencies — a general parsing library, not data-system plumbing. ```luau local Yaml = require("@builtin::modules.yaml") local doc = Yaml.decode(vfs.read(path)) vfs.write(path, Yaml.encode(doc)) ``` ## Supported subset - Block mappings (`key: value`) and block sequences (`- item`), nested to any depth. - Compact sequence-of-mapping entries (`- path: x` / ` kind: y`). - Flow collections — `{ a: 1, b: 2 }` and `[1, 2, 3]` — single line. - Plain scalars with type inference: `~` / `null` → nil, `true` / `false` → boolean, numeric literals → number, everything else → string. - Single- and double-quoted strings (`''` escapes a literal quote inside a single-quoted string; `\n` `\t` `\r` `\\` `\"` inside a double-quoted one). A quote opens a quoted scalar where a scalar begins — after `key:`, after a `- ` entry marker, or inside a flow collection — so a plain scalar carries an apostrophe as data (`note: the world's rules`). Quoted keys are read in flow mappings. - `#` comments — honored outside quotes, so a `#` inside a quoted string is kept as data. - Literal (`|`) and folded (`>`) block scalars, with a chomping indicator (`-` strips the final newline, `+` keeps every trailing blank line, none keeps one newline) and an indentation indicator (`1`-`9`: the content's indent past the parent's), in either order (`|-`, `>+`, `|2`, `>1-`). A block scalar's content is literal text: quotes (balanced or not), `#`, `key: value` and `---` inside it are data. - An optional leading `---` document marker. ## Loud-error contract Constructs outside the subset above raise instead of misparsing: anchors/aliases (`&`, `*`), tags (`!`), directives (`%`), multi-document streams (a second `---`), a block-scalar header it cannot read (`|x`, `|-+`, `|0`), tab indentation, and inconsistent indentation (both block structure and block-scalar bodies). Every error carries the offending line number (`yaml: line N: ...`), so a bad config points straight at the line to fix. Tab indentation is rejected everywhere — including block-scalar body lines whose leading whitespace contains a tab. A tab after the first non-space character of a line is content and passes through. ## API - `Yaml.decode(text: string): any` — decode a YAML document into a Luau value (table, scalar, or nil for an empty document). Raises on malformed input or an unsupported construct. - `Yaml.decodeWithComments(text: string): (any, boolean)` — decode as `decode` does, and report whether the text carries a comment by the decoder's own rule: a `#` at a line's start or after whitespace, outside a quoted scalar and outside a block scalar. Re-encoding the value drops such comments, so an editor that writes a document back reads this first. - `Yaml.encode(value: table): string` — encode a Luau table as YAML (block style, two-space indent, alphabetically sorted keys). Raises on values YAML can't represent (functions, userdata, non-string mapping keys). A top-level empty table encodes to an empty document, which decodes back to `nil` (the YAML empty-document ambiguity).
▲ 0↑ born
▣
module · born here
❒asset
# json JSON encode/decode library for Luau. Encodes Lua values to JSON strings and decodes JSON strings back to Lua values. Used for communication with the Rust side of the engine, the VFS read/write bridge, and any wire-format that needs JSON. Pure Luau, no engine dependencies. Compact and pretty-printed encoders, plus a hand-rolled decoder that streams the input by position so it works under WASM as well as native. ## Exports - `Json.encode(value: any, indent?: string, currentIndent?: string) -> string` — compact encode. Functions / unknown types and NaN/Inf encode as `null`. - `Json.encodePretty(value: any, indentStr?: string) -> string` — pretty-printed encode with sorted object keys (diff-friendly). - `Json.encodeArgs(...: any) -> string` — encode varargs as a JSON array. - `Json.decode(str: string) -> any` — decode a JSON string. Returns the decoded value, or `nil` + error message on failure. ## Usage ```luau local Json = require("@builtin::modules.json") local widget = { type = "button", text = "Click Me" } local compact = Json.encode(widget) -- '{"text":"Click Me","type":"button"}' local pretty = Json.encodePretty(widget, " ") local decoded = Json.decode(compact) local v, err = Json.decode("oops") -- v = nil, err = error message ``` ## Notes - Object keys are sorted alphabetically in both encoders for consistent output across runs. - Numeric keys on objects are stringified at encode time (JSON has no numeric keys). Pure-integer key sets get detected as arrays via `isArray` and encoded with brackets. - NaN, +Inf, -Inf encode as `null` — JSON has no representation. Round trips through `decode` recover `null` (Lua `nil`), so they don't preserve. - Unicode `\uXXXX` escapes decode to UTF-8 by hand to stay WASM-safe. Only the BMP is covered; supplementary planes via surrogate pairs are not. - Functions encode as `null`. - Decode is character-streamed — no regex, no `string.match` patterns on the whole input — so the line-and-column information needs to be reconstructed from the position offset.
▲ 0↑ born
▣
module · born here
❒asset
# 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
·
assettype · born here
❒asset
# Shader (asset type) A shader is a WGSL program that runs on the GPU. Materials reference shaders and supply property values; renderable entities reference materials, not shaders directly. This README is the canonical reference for writing **every** kind of shader — it covers all domains, the surface authoring contract, the material property schema, the engine library functions you can call, and how a shader registers and compiles. > New to how shaders, materials, meshes, and textures relate as assets and live > GPU resources? Read `core/resource-model` first. ## Folder shape A `.shader` is a folder asset: ``` <name>.shader/ shader.wgsl # the WGSL body (required) properties.yaml # the material property schema (optional; surface shaders) README.md # a one-paragraph description of THIS shader (required) .metadata # asset metadata ``` Each file carries a committed `.meta` sidecar pinning its stable guid. The identity is `<name>` (the `.shader` suffix strips). A shader's material properties are exactly the ones its `properties.yaml` declares: a shader with no `properties.yaml` declares none, and the engine reads no property from the WGSL body. A `.wgsl` file standing on its own, outside a `.shader` folder, is WGSL source rather than a shader: a material draws with the `.shader` folder that holds it as `shader.wgsl`. Materials and other assets reference a shader by **AssetRef** (a typed, guid-backed handle), never by a raw string. ## Domains The first line of `shader.wgsl` declares the domain: ```wgsl // @domain: surface ``` | Domain | What it is | You write | |---|---|---| | `surface` | A material on a mesh (the common case). | `fragment()` (+ optional `vertex()`/`vertex_clip()`). The engine generates everything else. | | `post-process` | A full-screen pass over the rendered frame, in the space it declares (bloom, vignette, grade). | `fragment(in: PostInput) -> vec4` only. The engine generates the fullscreen `vs_main`/`fs_main` and the group(1) interface from `properties.yaml`. | | `screen` | A standalone full-screen visual (UI background, procedural). | `fragment(in: ScreenInput) -> vec4` only. The engine generates the fullscreen `vs_main`/`fs_main` and the group(1) interface from `properties.yaml`. | | `sky` | The sky background (a fullscreen material). | `fragment(in: SkyInput) -> vec4` only. The engine generates the fullscreen `vs_main`/`fs_main` and the group(1) interface from `properties.yaml`. | | `compute` | GPU data processing, no rasterization. | An `@compute @workgroup_size(...)` entry over storage buffers; you write the `@group/@binding` lines yourself. For compute work, the `.computeShader` assetType (see below) generates them for you. | `// @domain:` resolves the names above and `postprocess` / `screenspace` / `ui` as further spellings of `post-process` and `screen`. A body carrying no `@domain:` line is `surface`. `shaderRef:domain()` answers the domain a body declares, a further spelling as the domain it names. Any other name is refused where the shader registers, with an error naming the spellings that resolve, so a shader reaches the renderer only under a domain the compiler scaffolds. Particles are drawn and simulated through these domains like anything else: the particle package's `particle_sprite` and `particle_mesh` are `surface` shaders, and its simulation, culling and sorting steps are `.computeShader` assets. ## Texture coordinate space A shader that samples a texture through a coordinate it builds itself declares which space that coordinate lives in, on a line beside `@domain:`: ```wgsl // @domain: surface // @uv_space: world ``` | Value | The coordinate | A material's `uv_scale` means | |---|---|---| | `mesh` (the default) | The mesh's own UV attribute, `input.uv`. | How many times the texture repeats across a surface. | | `world` | The fragment's world position, as a triplanar projection samples. | How many times the texture repeats per world unit, so a larger surface carries more. | Texture residency reads the declaration to work out how finely a frame samples each texture: a material laying eight copies of its texture across a surface samples each copy at an eighth of the surface's size, and the mip level that serves it is three levels coarser than the surface's own footprint implies. Leaving the line out puts the shader in mesh space, which is what sampling `input.uv` is. `renderer.textureStreaming().textures` reads back the span each texture was measured at and the level that span asked for. **Compute shaders have their own assetType.** A `.computeShader/` folder gives compute the same zero-scaffolding contract surface/sky/post/screen get: you write only `@compute fn main` (+ helper fns/structs, **no `@group/@binding` lines**) and declare bindings in a sibling `bindings.yaml` (storage buffers, textures, samplers, storage textures, plus a `params:` uniform); the engine generates the `@group(0)/@binding(N)` declarations. Dispatch it through a resolved reference (`asset.resolve("name", "computeShader"):dispatch(...)`). See the `.computeShader` assetType README and `man compute`. **Surface**, **sky**, **post-process**, and **screen** shaders all get engine-generated scaffolding — you write only `fragment()` and declare properties in `properties.yaml`; the engine generates the entry points and the group(1) material interface. (Each domain's `fragment` takes a domain-specific input instead of `FragmentData`: `SkyInput`, `PostInput`, or `ScreenInput` — see "Sky shaders" and "Post-process & screen shaders" below.) Compute shaders get the same treatment via the separate `.computeShader` assetType (write only `@compute fn main`, declare bindings in `bindings.yaml`). The `compute` domain here writes its own entry points directly — see `man compute`. ## Surface shaders A surface shader writes **only** the parts that are unique to it. The engine owns all the scaffolding — the vertex stage, every render-mode entry point (`vs_main` / `fs_forward` / `fs_gbuffer`), group(0) (camera, transforms, lights, shadows, and the material rows), and the material interface generated from `properties.yaml` (`material` and your texture slots). Adding a render path never touches your shader. Inside `fragment()` you have access to exactly four things — nothing is hidden: 1. **`input: FragmentData`** — the interpolated per-fragment surface data the engine hands you: world position, world normal, uv, view direction, vertex colour, and more. Every field is in the `FragmentData` table below. 2. **`material.*` and your textures** — the material inputs **you** declare in `properties.yaml`. The mapping is mechanical: a scalar property named `foo` becomes `material.foo`; a texture property named `bar` becomes `bar` (the texture) and `bar_sampler` (its sampler). `material` has **exactly** the fields your `properties.yaml` declares and no others — to add an input, add a property. List what a shader exposes with `shaderRef:getProperties()` or `asset.inspect("<name>")`. 3. **Engine state** — the scene's camera, lights, time, and shadows that the renderer binds for every surface shader. `uniforms.*` (sun direction/colour, ambient, `camera_pos`, `time`) and the punctual lights (`zero_point_light(i)`) are always in scope; the shadow functions come from `#include "@builtin::shaderModules.shadows"`. This is how you light a surface **without** the prebuilt PBR — see "Engine state" and "Writing your own shading" below. 4. **Library functions** you `#include` (see "Library includes"). A shader and its property schema go together. The two files below are a complete surface shader: `properties.yaml` — declares the material inputs: ```yaml properties: - { name: base_color, type: color, default: [1, 1, 1, 1] } - { name: roughness, type: float, default: 0.5, min: 0, max: 1 } - { name: metallic, type: float, default: 0.0, min: 0, max: 1 } - { name: base_color_texture, type: texture, default: white } ``` `shader.wgsl`; those declarations are read as `material.base_color`, `material.roughness`, `material.metallic`, and the `base_color_texture` / `base_color_texture_sampler` pair: ```wgsl // @domain: surface #include "@builtin::shaderModules.pbr_shading" // the PBR helpers — see "Library includes" fn fragment(input: FragmentData) -> vec4<f32> { var s = zero_pbr_default_surface(input); s.albedo = material.base_color.rgb * textureSample(base_color_texture, base_color_texture_sampler, input.uv).rgb; s.perceptual_roughness = material.roughness; s.metallic = material.metallic; return vec4<f32>(zero_pbr_shade(input, s), material.base_color.a); } ``` `fragment()` returns the final colour. The engine forces no lighting model on you — flat, toon, PS1, dithered, or PBR are all just different `fragment()` bodies. Calling `zero_pbr_shade` is opt-in. ### The two surface bodies, and what each gives up A surface shader exposes one of two entry points, and which one decides how much of the shader the engine can see: | Body | The engine gets | PBR debug passes read | |---|---|---| | `fn fragment(input: FragmentData) -> vec4<f32>` | the finished pixel, and the `PbrSurface` too when the body hands one to `zero_pbr_shade` | the real channel where a surface was handed over; magenta, the "no data here" marker, where the body shades by its own math | | `fn surface(input: FragmentData) -> PbrSurface` | the surface (albedo, roughness, metallic, emissive, normal, occlusion), which the engine then lights | the real channel | Both are first-class: `fragment()` is what you want when the shader owns its own look, `surface()` when you want engine lighting. `capture { pass = "albedo" }` (and `roughness` / `metallic` / `ao` / `emissive`) answers about your material for either body wherever the engine has the surface — writing the same `PbrSurface` behind `surface()` or behind `fragment()` + `zero_pbr_shade` gives one answer per channel. A body that lights itself by its own math draws those channels magenta. `pbr.shader` exposes `surface()`. `capture { pass = "normal" }` is a geometry read rather than a material one, so it answers for every shader: the normal of the surface where one was handed over, and the interpolated normal of the triangle where none was. It is the same normal the frame's normal buffer carries, which is what a screen-space pass reading `@scene.normal` sees. `shaderRef:shadingModel()` reports which one a shader ended up with — `"engine-lit"` for `surface()`, `"self-shading"` for `fragment()`. ### Optional vertex hooks ```wgsl // Displace geometry in OBJECT space. Runs on skinned meshes too (it sees the // already-skinned, morph-applied local position). Return the modified vertex. // The `v` parameter is immutable (WGSL function params are), so copy it into a // `var` first and modify that. fn vertex(v: VertexData) -> VertexData { var out = v; out.position += out.normal * sin(out.time) * 0.1; return out; } // Post-transform vertex hook (runs AFTER the engine's world/skin/projection). Two // things you can do here, separately or together: // * move `clip_position` — vertex jitter, PS1 snapping, render-resolution lowering; // * write `color` — PER-VERTEX (Gouraud) shading: light the vertex from its // world_normal + the light context and the engine forwards the result into the // interpolated `vertex_color` the fragment reads. fn vertex_clip(v: ClipVertex) -> ClipVertex { var out = v; // Gouraud: Lambert sun + ambient, evaluated once per vertex (flat-banded shading). let n_dot_l = max(dot(v.world_normal, -normalize(v.light_direction)), 0.0); let lit = v.ambient_color * v.ambient_intensity + v.light_color * v.light_intensity * n_dot_l; out.color = vec4<f32>(v.color.rgb * lit, v.color.a); out.clip_position = round(out.clip_position * 80.0) / 80.0; // PS1 snap return out; } ``` #### Geometry built per instance: grass, kelp, hair cards, debris `vertex()` knows which vertex of which instance it places: `VertexData.vertex_index` is the vertex's index in its mesh and `VertexData.instance_id` the instance's slot, whose lanes `zero_object_data(v.instance_id, lane)` reads. A hook can therefore build its geometry rather than displace it: a strip mesh drawn thousands of times by `renderer.mesh.drawInstanced`, each copy shaped, sized and bent from the lanes of its `instanceDataBuffer`, becomes a field of grass blades, kelp fronds or hair cards that sway with `v.time`. Being a surface shader, it is lit, shadowed (it casts the shape the hook built), motion-vectored and fogged like the rest of the scene. The rendering-instance-data guide (`guides { path = "topics/rendering-instance-data" }`) has a worked blade field; a render feature's raster pass (`types/rasterShader`) is the hand-written alternative, a vertex and fragment program with its own pipeline. #### Declaring how far a hook moves geometry: `vertexBoundsDilation` Static geometry is culled per cluster against its bounds as authored. A hook that moves vertices — wind sway, an outline hull, a vertex wave — can move them outside those bounds, and the cull then drops clusters whose displaced triangles are still on screen. Declare the farthest the hook moves any vertex, in world units, as a `vertexBoundsDilation` float property, with a default that covers the shader's own properties across their ranges: ```yaml properties: - { name: sway, type: float, default: 0.5, min: 0, max: 4 } # 0.4 x sway, at sway's largest value. - { name: vertexBoundsDilation, type: float, default: 1.6, min: 0, max: 100 } ``` Each material sets its own value — a material that sways less can set less, one moved farther sets more — and a material that sets none takes the default. The cull adds the material's value to every bound in its frustum and occlusion tests (not to the level-of-detail cut). A shader with a hook and no `vertexBoundsDilation` property is named once in the engine log when it compiles; its geometry is culled against its undisplaced bounds. ### Structs the engine passes you `FragmentData` (input to `fragment()`): | Field | Type | Meaning | |---|---|---| | `world_position` | `vec3<f32>` | fragment world-space position | | `world_normal` | `vec3<f32>` | interpolated geometric normal (normalized) | | `world_tangent` | `vec4<f32>` | xyz = world tangent, w = handedness (mikktspace) | | `uv` | `vec2<f32>` | primary texture coordinates (perspective-correct) | | `affine_uv` | `vec2<f32>` | the same UVs interpolated **without** perspective correction — the PS1 texture "swim". Always available; sample with it instead of `uv` for affine texture mapping | | `vertex_color` | `vec4<f32>` | interpolated per-vertex colour (white if unset; carries per-vertex lighting if `vertex_clip()` wrote it — see Gouraud below) | | `view_position` | `vec3<f32>` | camera world position | | `view_direction` | `vec3<f32>` | normalized world-space direction the camera sees this point from: toward the camera's position under a perspective projection, against its forward axis (the same for every point) under an orthographic one | | `light_direction` | `vec3<f32>` | directional (sun) travel direction, unit length; surface→sun is `-light_direction`. Where no sun reaches the camera it points straight down | | `light_color` | `vec3<f32>` | sun colour | | `light_intensity` | `f32` | sun intensity; 0 where no sun reaches the camera | | `ambient_color` | `vec3<f32>` | ambient colour | | `ambient_intensity` | `f32` | ambient intensity as it reaches this pixel: the scene's ambient occlusion is already in it (times `ambient_visibility`), so a crease darkens under the ambient with no work in the shader | | `ambient_visibility` | `f32` | the share of the light of its surroundings that reaches this pixel: 1 minus the scene's ambient occlusion here, 1 where nothing occludes it. Multiply it into any light of the surroundings you gather yourself (a sky colour, a reflection-probe or environment sample); `ambient_intensity` already carries it. `zero_scene_bent_normal(input.frag_coord.xy, n)` names the direction the open part of the hemisphere faces, `n` where no pass wrote one | | `frag_coord` | `vec4<f32>` | framebuffer pixel coords (xy) + depth (z) — for screen-space dither | | `receives_shadows` | `f32` | per-instance: > 0.5 if this surface receives shadows | | `material_index` | `u32` | per-instance: the index standing for the material this surface draws with — the number `renderer.materialIdentity()` maps to a name | | `shader_data` | `array<vec4<f32>, 4>` | per-instance: this entity's own four `vec4` lanes — its `ecs.ShaderData` component's `lane0`..`lane3`, or what `renderer.instanceData.set` put in them (zero until something does). A procedural graph's elements set them through the `data0`..`data3` attributes | | `front_facing` | `bool` | true for front faces (double-sided shading) | | `time` | `f32` | gameplay seconds: advances with the world at `engine.timeScale` and stands still while gameplay is paused (edit mode starts paused), so an effect slows and stops with the world | `shader_data` is the per-instance channel, and it is what lets ONE material serve many entities that differ in a value — a dissolve at its own progress per subject, a hit flash at its own age, a fill level per instance. The alternative is a material per entity, which is a separate pipeline binding and a separate row in the material table for every one of them. ```wgsl const DISSOLVE_LANE: u32 = 0u; fn fragment(input: FragmentData) -> vec4<f32> { let progress = input.shader_data[DISSOLVE_LANE].x; ... } ``` ```lua -- one material on twenty entities, each at its own progress renderer.instanceData.set(subject, 0, progress) renderer.instanceData.clear(subject) -- back to zero lanes ``` The engine attaches no meaning to a lane: a shader and whatever writes it agree what each one carries. Name the indices in the module that writes them. `renderer.instanceData.laneCount()` is how many there are. The same lanes reach a hardware-instanced population through `renderer.mesh.drawInstanced`'s `instanceDataBuffer`, on slots no entity owns. `VertexData` (in/out of `vertex()`): `position` (object-local, model-scale + morph applied), `normal`, `uv`, `color`, `time`, and which vertex of which instance it is: `instance_id` (`u32`, the instance's slot — `zero_object_data(v.instance_id, lane)` reads the lanes the fragment gets as `shader_data`) and `vertex_index` (`u32`, the vertex's index in its mesh). Both hold the same values in the colour pass, the depth views, every shadow page and the previous-frame evaluation, so geometry a hook builds from them — a blade placed and bent by its instance's lanes, a strip shaped by its vertex's index — lands in the same place in each. The rendering-instance-data guide has a worked blade field. `ClipVertex` (in/out of `vertex_clip()`) — the post-transform vertex. Read context: `clip_position`, `world_position`, `world_normal`, `uv`, `view_position`, `view_direction`, `light_direction`, `light_color`, `light_intensity`, `ambient_color`, `ambient_intensity`, `time`, `view_proj` (the view-projection of the frame being evaluated), and where the vertex stands on its instance: `local_position` (its position in the mesh, after `vertex()` and before the instance's world transform), `object_origin` (the world position of the instance's origin), `object_scale` (the world length of the instance's x, y and z axes) and `object_axes` (`mat3x3<f32>`, the world direction of those axes, unit length) — what a camera-facing card, a shard grown about its own base, or anything placed per instance is built from. **Writable:** `clip_position` (snap / jitter) and `color` (write a lit colour here for per-vertex Gouraud shading; the engine forwards it to the interpolated `vertex_color` — left untouched, the mesh's own vertex colour passes through). `vertex()` and `vertex_clip()` run in the vertex stage, which reads the frame uniforms (`uniforms.*`, and the `ClipVertex` members built from them), the scene buffer (`zero_object_data`, `zero_object_visuals`, the node transforms), the material interface and a `read` buffer property. The point, spot and area lights (`zero_point_light`, `zero_punctual_projection`), the shadow maps, the environment and light probes, the feature textures, the scene depth, colour and reflection copies and a `@group(2)` buffer the shader declares `read_write` are visible to the fragment stage alone: read them in `fragment()` or `surface()`. A shader whose vertex hook reaches one fails to compile, and the error names the stage, the binding and the calls that reach it. ### Each hook runs twice: this frame and the one before it A vertex hook decides where the surface IS, so it also decides where the surface WAS. The engine runs every hook a shader declares a second time, over the same vertex standing one frame back — the previous-frame position stream, with `time` = the clock that frame was drawn at and (for `vertex_clip()`) `view_proj` = the view-projection it was drawn with. The motion vector the renderer publishes is taken between the two results, so a displacement that moves with time reports the velocity of the displaced surface, and a displacement that does not move reports the motion of the transform alone because the identical offset appears on both evaluations and cancels. What that asks of a hook: - **Take the frame from the argument.** `v.time` is the clock of the evaluation being run; `uniforms.time` is always this frame's. A displacement built on `uniforms.time` is identical on both evaluations, so its motion vector cancels to exactly zero. The same holds for `v.view_proj` against `uniforms.view_proj`: a clip hook that rebuilds its position from world space through `uniforms.view_proj` reprojects the previous frame with this frame's camera, and reports no camera motion at all. The wind helpers come in both shapes for this reason — `zero_wind_sway_at_time(world_pos, stiffness, v.time)` inside a hook, `zero_wind_sway(world_pos, stiffness)` outside one. - **Anchor a wrap to `uniforms.time`.** A displacement that jumps discontinuously — a falling drop that restarts at the top, a looping offset — differences its jump as velocity on whichever frame it wraps. Compute the wrap COUNT from `uniforms.time` and the position within the cycle from `v.time`, and both evaluations share the same cycle, so the surface reports the speed it fell at. `@builtin::shaders.rain_material` and `snow_material` do exactly that. The per-vertex attributes (`world_normal`, `uv`, `color`) and the lighting and camera-position context are this frame's on both evaluations, so a hook that displaces along its normal reports the motion of the transform plus this frame's displacement. ## Engine state — point lights & shadows The common lighting state — the sun (`input.light_direction` / `light_color` / `light_intensity`), the ambient (`input.ambient_color` / `ambient_intensity`), the camera (`input.view_position` / `view_direction`), and `input.time` — is already on `FragmentData`, so most shaders never touch the raw engine state. The one thing not on `FragmentData` is the punctual-light array (its length varies), which is always in scope. A scene can hold up to 1024 lights, so a fragment walks the ones the light grid lists where it stands, which hold every light that can reach it: | Expression | Type | Meaning | |---|---|---| | `zero_lights_near(world_pos)` | `ZeroLightsNear` | the lights that can reach a fragment at `world_pos`; `.count` of them | | `zero_light_near(near, k)` | `u32` | the index of the `k`th of them, for `zero_point_light` | | `uniforms.point_light_count` | `u32` | number of lights the frame shades under, every one of them | | `zero_point_light(i)` | `PointLightData` | one point or spot light (fields below) | | `zero_punctual_projection(i)` | `PunctualProjection` | a spot or area light's projection: `view_proj`, the frustum its cookie and shadow are placed by, and `cookie_layer` | `PointLightData`: `position`, `radius`, `color`, `intensity`, `direction`, `cone_outer_cos`, `cone_inner_cos`, `kind` (0 = point, 1 = spot). Shadows come from `#include "@builtin::shaderModules.shadows"`: - `compute_directional_shadow_factor(world_pos, normal, light_dir) -> f32` — 1.0 lit, 0.0 fully shadowed. - `compute_spot_shadow_factor(...)` / `compute_point_shadow_factor(...)` / `compute_area_shadow_factor(...)` — one shadow shape each. - `compute_punctual_shadow_factor(light_index, world_pos, normal) -> f32` — the row's own shape, read off its `kind`, for a loop that walks the punctual lights and does not want the switch. - `zshadow_light_reach(light_index, world_pos, normal, object_channels) -> f32` — how much direct light that row puts on a surface on those light channels: the channel mask, falloff, cone or rect orientation, and the cosine, times intensity. Zero exactly where the light contributes nothing. ## Writing your own shading The engine forces no lighting model — `zero_pbr_shade` is just one option. You can light a surface yourself from the state above. Here is a complete custom-lit (Lambert diffuse) surface with no PBR: ```wgsl // @domain: surface #include "@builtin::shaderModules.shadows" // exposes compute_directional_shadow_factor fn fragment(input: FragmentData) -> vec4<f32> { let n = normalize(input.world_normal); let albedo = material.base_color.rgb; // Directional (sun) light: Lambert N·L, attenuated by its shadow. let sun = normalize(-input.light_direction); // surface -> sun let sun_shadow = compute_directional_shadow_factor(input.world_position, n, input.light_direction); var lit = input.light_color * input.light_intensity * max(dot(n, sun), 0.0) * sun_shadow; // Point + spot lights: the ones that can reach this fragment. let near = zero_lights_near(input.world_position); for (var k = 0u; k < near.count; k = k + 1u) { let pl = zero_point_light(zero_light_near(near, k)); let to_light = pl.position - input.world_position; let dist = length(to_light); let l = to_light / max(dist, 1e-4); let atten = max(1.0 - dist / max(pl.radius, 1e-4), 0.0); lit += pl.color * pl.intensity * max(dot(n, l), 0.0) * atten; } // Ambient fill, with the scene's ambient occlusion already in it. lit += input.ambient_color * input.ambient_intensity; return vec4<f32>(albedo * lit, material.base_color.a); } ``` - **Unlit:** skip the lights and return your colour directly. - **Toon / PS1 / custom:** start from the loop above and band, quantize, or warp it however you like. - **PBR:** build a `PbrSurface` and call `zero_pbr_shade` (see "Library includes") instead of writing the BRDF by hand. ## Material properties — `properties.yaml` A surface shader declares its material properties in a sibling `properties.yaml`. The engine GENERATES the entire group(1) interface from it — the uniform struct (`material.<name>`) plus a texture/sampler pair per declared texture. You write no `@group`/`@binding` lines. ```yaml properties: - { name: base_color, type: color, default: [1, 1, 1, 1] } - { name: roughness, type: float, default: 0.5, min: 0, max: 1 } - { name: metallic, type: float, default: 0.0, min: 0, max: 1 } - { name: emissive, type: color, default: [0, 0, 0, 1] } - { name: base_color_texture, type: texture, default: white } - { name: normal_texture, type: texture, default: flat_normal } ``` | `type` | WGSL field type | Notes | |---|---|---| | `float` | `f32` | optional `min`/`max` for editor sliders | | `float2`/`float3`/`float4` | `vec2/3/4<f32>` | | | `color` | `vec4<f32>` | linear RGB colour and alpha, default is `[r,g,b,a]`; the shader reads it as written | | `int` | `i32` | | | `bool` | `u32` | | | `texture` | `texture_2d<f32>` + `sampler` | `default:` is a built-in texture name (`white`, `black`, `flat_normal`) | A `color` holds linear RGB, the space lighting is computed in, the way `base_color` multiplies a colour texture's linear sample. A colour picked from a picture or written as a hex code is sRGB, and written as it is it reads paler and less saturated than picked: convert it first, `color.toLinear(assert(color.hex("#ff8800")))` (`{ r, g, b, a }`: `#ff8800` is `{ r = 1, g = 0.246, b = 0, a = 1 }`), and write that. In the shader you read scalars as `material.<name>` and sample textures as `textureSample(<name>, <name>_sampler, uv)`. A texture slot with no bound texture samples its default, so a shader can always sample — no presence flag needed. `vertex()` reads the same material interface, so a height or deformation map drives displacement from the slot it was bound to. A vertex stage has no implicit derivatives, so sample it at an explicit mip there: `textureSampleLevel(<name>, <name>_sampler, uv, 0.0)`. ## Sky shaders A `// @domain: sky` shader draws the sky as a fullscreen pass. You write **only** `fn fragment(in: SkyInput) -> vec4<f32>` — the colour along the view ray for each pixel — and declare tunables in `properties.yaml` exactly like a surface shader (read as `material.<name>`, textures via `textureSample(<name>, <name>_sampler, uv)`). The engine generates the fullscreen `vs_main`/`fs_main`, the group(1) interface, and reconstructs the world-space ray; there is no separate sky renderer — a sky material runs through the same material pipeline, just on a fullscreen triangle. A sky pipeline binds group(0) and the group(1) interface alone, so a sky that reads a `buffer` property or any other `@group(2)` binding fails to compile, and the error names the binding and the calls that reach it. `SkyInput` (the only argument) carries: | Field | Type | Meaning | |---|---|---| | `ray_dir` | `vec3<f32>` | normalized world-space ray through this pixel | | `ndc` | `vec2<f32>` | screen position in NDC `[-1, 1]` | | `sun_direction` | `vec3<f32>` | unit vector TOWARD the sun (from the directional light) | | `camera_pos` | `vec3<f32>` | world-space camera position | | `time` | `f32` | gameplay seconds: advances with the world at `engine.timeScale` and stands still while gameplay is paused (edit mode starts paused), so an effect slows and stops with the world | | `constants` | `SkyConstants` | what the shader's `sky_constants()` returned for this draw (zeros when it declares none) | ```wgsl // @domain: sky fn fragment(in: SkyInput) -> vec4<f32> { let up = max(in.ray_dir.y, 0.0); let col = mix(material.horizon_color.rgb, material.zenith_color.rgb, up); return vec4<f32>(col * material.exposure, 1.0); } ``` Day/night comes from `sun_direction.y` (the directional light's elevation), so a sky shader never needs a time-of-day uniform — orient the light and the sky follows. The builtin sky shaders (`procedural_sky`, `solid_sky`, `cubemap_sky`, `equirect_sky`) are all authored this way; author a custom sky material and point a `Skybox` component at it. `fragment()` runs once for every pixel of the view and every texel of each environment-capture face. A value that holds for the whole draw (a colour mixed from the material and the sun's elevation, a `cos` of an angular size, an exponent derived from a property) goes in an optional `fn sky_constants(in: SkyConstantsInput) -> SkyConstants`, which the generated vertex stage evaluates once per draw. `fragment()` reads its result as `in.constants`. `SkyConstantsInput` carries `sun_direction`, `camera_pos` and `time` (the same values `SkyInput` holds), `sky_constants()` reads the material as `material.<name>` like `fragment()`, and `SkyConstants` is eight `vec4<f32>` slots, `v0` to `v7`, packed however the sky likes: ```wgsl // @domain: sky fn sky_constants(in: SkyConstantsInput) -> SkyConstants { let day = clamp(in.sun_direction.y * 2.0, 0.0, 1.0); var c: SkyConstants; c.v0 = vec4<f32>(mix(vec3<f32>(0.02), material.zenith_color.rgb, day), day); c.v1 = vec4<f32>(mix(vec3<f32>(0.01), material.horizon_color.rgb, day), 0.0); return c; } fn fragment(in: SkyInput) -> vec4<f32> { let up = max(in.ray_dir.y, 0.0); return vec4<f32>(mix(in.constants.v1.rgb, in.constants.v0.rgb, up), 1.0); } ``` A branch on an `in.constants` value is taken or skipped by every pixel of the draw together, so a term that only contributes some of the time (stars at night) costs nothing while it is off. The vertex stage has no implicit derivatives, so a texture read in `sky_constants()` is `textureSampleLevel`. ## Post-process & screen shaders `// @domain: post-process` and `// @domain: screen` shaders are authored exactly like surface and sky — you write **only** `fn fragment(in: PostInput) -> vec4<f32>` (post) or `fn fragment(in: ScreenInput) -> vec4<f32>` (screen) and declare tunables in `properties.yaml` (read as `material.<name>`, textures via `textureSample(<name>, <name>_sampler, uv)`). The engine generates the fullscreen `vs_main`/`fs_main` and the group(1) material interface. **There are no `uniforms.params[i]` slots** — that convention is retired; every input is a named property. A **post-process** shader's `properties.yaml` carries one further, top-level key beside `properties:` — `space`, either `light` (the default) or `display`: ```yaml space: display properties: - { name: amount, type: float, default: 1.0, min: 0, max: 1 } ``` `light` is the scene's linear radiance — what every surface, the sky and every `afterLighting` feature write, unbounded above 1.0. `display` is the code values the `__display__` pass leaves behind after applying exposure and its tone curve — the 0-1 range a colourist's tool and a dithered or quantized effect expect. `postprocess.add`'s `opts.space` overrides what the asset declares for one registration. The chain converts at both ends of an effect that runs on a segment in the other space, so a light-space vignette still darkens a frame graded after `__display__`, and a lookup table built from a `.cube` export always sees the code values it was authored against, wherever the chain runs it. `space` also decides which layer a registration that names none lands on: a `light` shader grades `scene`, the segment holding the scene's own light, and a `display` shader grades `display`, the picture after `__display__` and before the UI lands on it. So `postprocess.add("glow", asset.resolve("~.shaders.bloom", "shader"))` thresholds highlights that still stand above 1.0, and a lookup table registered the same way reads the code values it was built for and leaves every screen in the colours it declares. `opts.layer` names one explicitly — `"all"`, after the UI, is what an effect that must grade the interface says. A post-process shader may also declare the post stage of the frame it runs in, `stage:` — `optics` (the `scene` layer), `display` (the `display` layer) or `ui` (the `all` layer); `renderer.post.stages()` lists every stage with the colour space and resolution its picture is held in. A registration takes the declared stage unless `opts.stage` or `opts.layer` names another seam, and a stage the frame does not have, or one only render features run in, is refused naming the stages there are: ```yaml space: display stage: display properties: - { name: amount, type: float, default: 1.0, min: 0, max: 1 } ``` A **post-process** shader's `properties.yaml` carries a further, optional top-level key — `passes:`, the pass list the frame draws through, in order: ```yaml space: light passes: - { name: bright, entry: bright, scale: 0.5, inputs: [scene] } - { name: down1, entry: downsample, scale: 0.25, inputs: [bright] } - { name: up0, entry: upsample, scale: 0.5, inputs: [down1, bright] } - { name: composite, entry: composite, inputs: [scene, up0] } ``` Every pass's entry — `fn <entry>(in: PostInput) -> vec4<f32>` — lives in the one `shader.wgsl` the assetType recompiles on. `scale` is the fraction of the view a pass draws at; the LAST pass takes none, since it draws at the view's size and writes the chain's output. `inputs` names what a pass reads — `"scene"`, the chain's input for this effect, or the name of an EARLIER pass — and `inputs[0]` is what `zero_sample_scene(uv)` reads inside that pass's body; every input, `inputs[0]` included, is also reachable by index through `zero_pass_input(i, uv)` and `zero_pass_input_size(i)`, below. The one place the two reads of `inputs[0]` disagree: in an effect whose declared space differs from the segment it draws on, `zero_sample_scene` converts a `scene` input into that space while `zero_pass_input(0, uv)` hands back the segment's own, unconverted value. A shader declaring no `passes:` is one pass whose entry is `fragment`, and its generated WGSL is byte-identical to what it is without the key. A pass that is not the last writes a scratch target the effect owns — in the space the shader declared, view-sized times its own `scale` — allocated on the first draw and replaced whenever the size changes. `engine.params`, below, carries the drawing pass's own index, its scale, and its first input's texel size, so one shader body serves every level of a chain built this way. The worked example is the bloom: `@builtin::shaders.post.bloom` declares twelve passes — a threshold pass, five downsamples, five tent upsamples and a composite — out of four entries, since the five downsamples share one and the five upsamples share another, each level reading the one below it through `zero_pass_input` and telling itself apart by `engine.params`. Its own README walks the declaration. A declaration is refused at compile time — reported through `compileStatus()`, `postprocess.add`'s second return value, or a live effect's `status()[i].error` — for: an entry `passes:` names that `shader.wgsl` does not define; an input naming a later pass, or naming neither `scene` nor an earlier pass; a `scale` outside `(0, 1]`; a `scale` declared on the last pass; a `buffer` property (group(2) carries the pass inputs); or a shader whose group(0) plus declared texture slots plus widest pass's inputs ask for more than the 16 FRAGMENT sampled textures one shader stage has. A **post-process** shader runs as a full-screen pass over the already-rendered frame. Its `fragment` argument and framework helpers: `PostInput`: | Field | Type | Meaning | |---|---|---| | `frag_coord` | `vec4<f32>` | framebuffer pixel coords (`@builtin(position)`) | | `uv` | `vec2<f32>` | screen UV, `(0,0)` top-left … `(1,1)` bottom-right | Framework helpers (always in scope — no include needed): | Call | Returns | Meaning | |---|---|---| | `zero_sample_scene(uv)` | `vec4<f32>` | the rendered scene colour at `uv`, converted into the space this effect declared (`zero_scene_light` is the same call, for content that reads it by that name) | | `zero_scene_depth(uv: vec2<f32>)` | `f32` | scene depth at `uv` — a screen UV here, where the surface domain's `zero::scene_depth` module takes a pixel coordinate under the same name (exact texel — an R32Float copy). Reversed: 1.0 is the near plane, 0.0 the far plane and empty sky, so a nearer surface reads GREATER and `d > 0.0` means "a surface was drawn here" | | `zero_linear_depth_through(d, near, far, engine.view_proj)` | `f32` | that sample as a distance in metres along the camera's view axis, under a perspective or an orthographic camera — the one inversion of the reversed range (`zero_linear_depth(d, near, far)` is its perspective case alone) | | `zero_scene_motion(uv)` | `vec2<f32>` | per-pixel screen-space motion vector at `uv` | | `zero_pass_input(i, uv)` | `vec4<f32>` | the pass's declared input `i`, at `uv`. Input 0 is what `zero_sample_scene` reads | | `zero_pass_input_size(i)` | `vec2<f32>` | that input's size in texels, so one entry serves every level of a chain | | `zero_display_exposure()` | `f32` | the exposure in force: the gain `__display__` multiplies the scene's light by before its curve, the value this frame's display pass draws with (1 where the chain carries none). Light times it is light in the units the picture shows it at, so a threshold judged against `light * zero_display_exposure()` picks the same highlights at every exposure | Engine data uniform `engine` (a `PostEngineData`): | Field | Type | Meaning | |---|---|---| | `resolution` | `vec4<f32>` | `x`=width, `y`=height, `z`=1/width, `w`=1/height | | `time` | `vec4<f32>` | `x`=elapsed seconds, `y`=dt, `z`=frame index | | `view_proj` | `mat4x4<f32>` | this frame's view-projection | | `prev_view_proj` | `mat4x4<f32>` | last frame's view-projection (motion) | | `inv_view_proj` | `mat4x4<f32>` | inverse view-projection (world-space reconstruction) | | `params` | `vec4<f32>` | `x`=this pass's own index, `y`=the scale it draws at, `zw`=1/size of its first input — for a pass the post-process chain draws. A pass a `renderFeature` fragment pass draws carries that feature's `spec.params` here instead; a shader declaring `passes:` is always drawn by the chain, so the two never meet in one shader. | | `exposure` | `vec4<f32>` | `x`=the exposure in force (what `zero_display_exposure()` reads) | The engine fills all of it **per render target**. A registered effect runs over the live viewport's frame AND over every offscreen one — a `capture` from a world-space station or orbiting an entity, a capture of a named camera, a render-to-texture camera — and in each of those, `view_proj`, `prev_view_proj` and `inv_view_proj` are the camera THAT render was drawn from, while `resolution` is that target's own pixel size. So a pass reconstructing world space from `zero_scene_depth(uv)` reconstructs against the station and lens the capture asked for, and an offscreen frame is a picture of the effect as it stands at that station. (A render feature's passes reach an offscreen render the same way, against the same camera — the `renderFeature` assetType README carries that half, including `@frame.camera`, its own per-target camera input.) An offscreen render keeps no view history of its own, so `prev_view_proj` there holds that same matrix rather than the frame before it, and a pass taking camera motion from the two reads none. On the viewport the pair is a frame apart, so camera motion is the one reading a capture answers differently from the screen. `postProcessing = false` on a capture is the one control that takes the chain off the frame it returns; it names the camera property the ephemeral capture camera is built with, so it scopes to that one capture. What a capture opts out of is the registered effects; `__display__` still runs on it, so the exposure and tone curve that turn the scene's light into a picture are on what a capture returns. A diagnostic capture (`albedo`, `normal`, `motion_vectors`, …) bypasses `__display__` itself, since a channel like that is a reading of the scene rather than a graded picture of it. The environment-cube capture bypasses it too, and for the same reason: a probe face carries radiance into the cube array, and `__display__` would fit that radiance to a display's code values — a picture of it rather than the value the PBR indirect term multiplies into its lighting. A complete post-process effect — a vignette via `fragment()` + `properties.yaml`: `properties.yaml`: ```yaml properties: - { name: intensity, type: float, default: 0.5, min: 0, max: 1 } - { name: radius, type: float, default: 0.75, min: 0, max: 1 } - { name: softness, type: float, default: 0.45, min: 0, max: 1 } ``` `shader.wgsl`: ```wgsl // @domain: post-process fn fragment(in: PostInput) -> vec4<f32> { let color = zero_sample_scene(in.uv); let intensity = max(material.intensity, 0.01); let radius = max(material.radius, 0.01); let softness = max(material.softness, 0.01); let center = in.uv - vec2<f32>(0.5); let dist = length(center); let vignette = smoothstep(radius, radius - softness, dist); let darkened = color.rgb * mix(vec3<f32>(1.0), vec3<f32>(vignette), intensity); return vec4<f32>(darkened, color.a); } ``` The asset above **defines** the effect. It enters the frame when something registers it: ```luau postprocess.add("vignette", asset.resolve("~.shaders.vignette", "shader"), { priority = 200 }) ``` The registration names no layer, so the effect grades the layer its `space` belongs to: this vignette reads light, so it runs on `scene`, over the picture before the UI reaches it. Registering it is the one step that makes it render, so a world's chain holds exactly the passes its content asked for. Editing the shader body afterwards recompiles every effect registered from it, in place — the pass keeps its enabled state, priority, layer, tuned property values and bound textures, and draws the new pixels on the next frame. `postprocess.remove(name)` takes it back out of the chain and leaves the asset alone. Drive the named properties at runtime with `postprocess.setProperty(name, prop, value)` and bind texture properties with `postprocess.setTexture(name, prop, path)` (both keyed by the **property name**, never a slot index — see the post-process section of `man shaders` / the `postprocess.*` API). Read them back with `postprocess.describe(name)`: it carries the chain state `postprocess.status()` lists for that effect, the `properties` schema it was registered with, and the `values` each of those properties currently holds. Before the effect exists, `shaderRef:getProperties()` on the asset names the same schema, so what a pass takes is answerable either side of the registration. A **screen** shader is a standalone full-screen visual (UI background, procedural pattern). `ScreenInput` mirrors `PostInput` (`frag_coord` + `uv`); there is no scene to sample, so it has no `zero_sample_scene` helpers. Its `engine` uniform is a `ScreenEngineData`: | Field | Type | Meaning | |---|---|---| | `time` | `f32` | gameplay seconds: advances with the world at `engine.timeScale` and stands still while gameplay is paused (edit mode starts paused), so an effect slows and stops with the world | | `scroll` | `f32` | UI scroll offset | | `resolution` | `vec2<f32>` | render-target size in pixels | | `mouse` | `vec2<f32>` | mouse position | | `velocity` | `f32` | scroll velocity | ```wgsl // @domain: screen fn fragment(in: ScreenInput) -> vec4<f32> { let t = engine.time * 0.5; let col = vec3<f32>( sin(in.uv.x * 3.14159 + t) * 0.5 + 0.5, sin(in.uv.y * 3.14159 + t * 0.7) * 0.5 + 0.5, material.brightness ); return vec4<f32>(col, 1.0); } ``` ## Library includes A library module is a **`.shaderModule` asset**: it only EXPOSES functions and structs and does nothing on its own (exactly like a Unity `.cginc`). You must call what you include. Include one by its identity, the same string you would hand `asset.resolve`: | Include | Exposes | |---|---| | `@builtin::shaderModules.pbr_shading` | `struct PbrSurface { albedo, normal (world), metallic, perceptual_roughness, emissive, occlusion }`; `zero_pbr_default_surface(FragmentData) -> PbrSurface`; `zero_pbr_shade(FragmentData, PbrSurface) -> vec3<f32>` (the full forward PBR lighting); `zero_pbr_indirect_visibility(FragmentData, PbrSurface) -> ZpbrIndirectVisibility` (the share of the surroundings' light each indirect lobe takes from the scene's ambient occlusion: `diffuse` with the light a crease bounces back, `specular` from the open cone around the bent normal); `zero_pbr_shade_with_visibility(FragmentData, PbrSurface, ZpbrIndirectVisibility) -> vec3<f32>` (the same lighting with that share stated by the caller) | | `@builtin::shaderModules.shadows` | `compute_directional_shadow_factor(...)`, `compute_spot_shadow_factor(...)`, `compute_point_shadow_factor(...)`, `compute_area_shadow_factor(...)`, `compute_punctual_shadow_factor(...)`, `zshadow_light_reach(...)`; each light's `_with_kernel` form takes a shared `ZShadowKernel` (`zshadow_kernel()`) so several lookups of one fragment derive its filter rotation once | | `@builtin::shaderModules.engine_bindings` | the group(0) declarations (camera, transforms, lights, shadow maps) — surface shaders get this implicitly; include it directly only for advanced raw access | | `@builtin::shaderModules.shadow_bias` | `zshadow_offset_receiver(...)`, `zshadow_directional_depth_bias(...)` and the rest of the bias math, as pure functions | | `@builtin::shaderModules.texturing` | `ztex_stochastic(...)` (tile without a visible repeat grid), `ztex_blend_normals(...)` (reoriented normal blending) | | `@builtin::shaderModules.depth` | `zero_linear_depth_through(depth, near, far, view_proj)` — the one reading of a stored depth, for the projection the view-projection states; `zero_linear_depth` and `zero_linear_depth_orthographic` are its two cases | | `@builtin::shaderModules.ambient_light` (`zero::ambient_light`) | `zpbr_surroundings_irradiance(world_pos, n, flat_ambient)` (the diffuse light the surroundings hand a surface with normal `n`: the flat ambient, the captured sky and reflection probes, and the baked light-probe volumes, as the PBR model reads it) and `zpbr_surroundings_in_scatter(world_pos, flat_ambient)` (that light averaged over every direction: what a participating medium scatters). A compute pass binds `environment_map`, `environment_sampler` and `zero_environment` to `@scene.environment`, `@scene.environmentSampler` and `@scene.reflectionProbes` | | `@builtin::shaderModules.gbuffer_material` (`zero::gbuffer_material`) | `struct ZeroGbufferMaterial { base_color, metallic, perceptual_roughness }`; `zero_gbuffer_unpack_material(texel: vec4<u32>) -> ZeroGbufferMaterial`; `zero_gbuffer_material(t: texture_2d<u32>, coord: vec2<i32>) -> ZeroGbufferMaterial`, `zero_gbuffer_base_color`/`zero_gbuffer_metallic`/`zero_gbuffer_roughness(t, coord)` — the one unpacking of `@scene.material`'s `Rgba8Uint` texel into what a surface reflects | | `zero::scene_depth` | `zero_scene_depth(px: vec2<f32>)`, `zero_scene_depth_uv(uv: vec2<f32>)`, `zero_scene_depth_texel(px: vec2<i32>)`, `zero_scene_depth_size()`, `zero_scene_depth_is_sky(d: f32)`, `zero_scene_world_position(px: vec2<f32>)`, `zero_scene_world_normal(px: vec2<f32>)`, `zero_scene_depth_fade(px: vec2<f32>, world_position: vec3<f32>, fade_distance: f32)` — every `px` is a pixel coordinate in two components, so a surface fragment passes `input.frag_coord.xy`, not the `vec4<f32>` `FragmentData.frag_coord` holds. The depth already drawn UNDER a surface fragment, and the world position and geometric normal of the surface standing there. What a decal projector box, a soft particle, a forcefield or water intersection foam shades against. Surface domain; the depth belongs to the view being drawn | | `zero::scene_color` | `zero_scene_color(px: vec2<f32>)`, `zero_scene_color_uv(uv: vec2<f32>)`, `zero_scene_color_texel(px: vec2<i32>)`, `zero_scene_color_size()`, `zero_scene_color_refract(px: vec2<f32>, offset_px: vec2<f32>)`, `zero_scene_color_refract_uv(px: vec2<f32>, offset_fraction: vec2<f32>)` — every `px` is a pixel coordinate in two components, so a surface fragment passes `input.frag_coord.xy`, not the `vec4<f32>` `FragmentData.frag_coord` holds. The scene colour already composed BEHIND a surface fragment, and the displaced read that bends it. What heat haze, a refraction shockwave, a cloaking or shield warp, glass and ice shade with. Surface domain; the colour belongs to the view being drawn, and is the lit opaque scene as it stood immediately before the transparent pass — so a `blend`-queue surface reads this frame's, an opaque one reads the previous frame's, and two overlapping blended surfaces both read the same picture and do not bend each other | | `zero::projection` | `zero_projection_is_orthographic(view_proj: mat4x4<f32>) -> bool`, `zero_projection_parallel_ray(view_proj: mat4x4<f32>) -> vec3<f32>`, `zero_projection_view_direction(view_proj: mat4x4<f32>, camera_position: vec3<f32>, world_position: vec3<f32>) -> vec3<f32>`: what a view-projection states about how it projects: whether it is orthographic, the direction an orthographic one sees along (pointing back toward the camera), and the direction a camera sees a world point from under either projection, the value `FragmentData.view_direction` holds. Pure math with no bindings, so a surface, post-process or compute shader passes the view-projection it holds (`uniforms.view_proj`, `engine.view_proj`, or a uniform of its own) | `asset.list("shaderModule")` enumerates the `.shaderModule` assets in this engine, builtin and world-authored alike, and each one's README says what it exposes. Those are the `@builtin::shaderModules.*` rows above; a module you write is included exactly the same way, by its own identity or by the `~.name` form. The `zero::`-named rows come from the renderer itself. Their WGSL is baked into the engine binary and registered under those names before any asset exists, so they answer an `#include` in every engine and appear in no asset index. A shader that includes one records no dependency on it: the engine reading the shader is the engine that already holds the module. Two spellings reach the same `.shaderModule`: a module's declared alias answers as well as its identity, so a shader written against `zero::pbr` compiles and pins the asset that name resolves to. Prefer the identity: it says which asset travels with the content. Whichever punctuation an include is written with — `#include "name"`, `#include 'name'` or `#include <name>` — names the same module and records the same dependency. The engine's own scaffolding — `zero::surface`, `zero::sky`, `zero::post`, `zero::screen` — is injected by the compiler around the matching domain and is never written by hand. The surface framework puts `safe_normalize`, `mat3_from_mat4` and `apply_normal_map(FragmentData, tangent_normal)` in scope for every surface shader. ## Shader features — compile-time variants A **property** is runtime uniform data (a colour, a float, a texture): set per material, read as `material.<name>`, no recompile. A **feature** decides which code is in the program at all. Use a property when the value changes at runtime, a feature when it changes what the shader is. Declare features in `properties.yaml`, alongside the properties: ```yaml properties: - { name: base_color, type: color, default: [1, 1, 1, 1] } features: - { name: PARALLAX, default: false, description: silhouette parallax march } - { name: DETAIL, default: true, description: detail-normal overlay } ``` Guard the code each feature owns with `#ifdef`: ```wgsl fn surface(input: FragmentData) -> PbrSurface { var s = zero_pbr_default_surface(input); #ifdef PARALLAX s.normal = parallax_normal(input); // absent when PARALLAX is off #else s.normal = input.world_normal; #endif return s; } ``` `#ifdef` / `#ifndef` / `#else` / `#endif`, one per line, and they nest. The directives resolve before the WGSL reaches the compiler, so the program holds exactly the lines its feature set selected and every other line is an empty one, which keeps a compiler message on the line number the file shows. An unbalanced block is a compile error naming its line. A material is what chooses a feature set, so `features:` shapes the shaders a material draws with — the surface, sky and screen-space domains. A material names the features it wants in its `mat.yaml`: ```yaml name: worn_rock shader: "@builtin::shaders.pbr_layered" features: PARALLAX: true # on, over the shader's default DETAIL: false # off, against the shader's default ``` or through `asset.create`: ```lua asset.create("material", "worn_rock", { shader = "@builtin::shaders.pbr_layered", features = { PARALLAX = true, DETAIL = false }, }) ``` ### A property that switches a feature on A feature can also be switched on by a material's property values. List the properties under the feature's `properties:`, and the feature is on for every material whose value for one of them stands away from that property's declared default: ```yaml properties: - { name: clearcoat, type: range, default: 0.0, min: 0, max: 1 } features: - { name: CLEARCOAT, properties: [clearcoat], description: the coat lobe } ``` ```wgsl #ifdef CLEARCOAT s.clearcoat = material.clearcoat; #endif ``` A material at `clearcoat: 0` draws a program holding none of the coat's code; one that sets `clearcoat: 0.6`, in its `mat.yaml`, through `asset.create` or with `renderer.material.setProperty`, draws the `CLEARCOAT` variant, and setting it back to 0 returns it to the base program. The property stays a runtime value the program reads; the feature decides only whether the code reading it is there. This is how a shader with costly optional parts keeps every material that leaves them at rest on the cheap program without each material having to name a feature. A material naming the feature off under `features:` keeps it off whatever the property holds. Write the guarded code so that, with the feature off, the shader computes what it would with the property at its default: the material sees one look either way, and pays for the part only where it shows. Each distinct set of switched-on features is a program to compile the first time a material reaches it. A material keeps the programs its values switched it onto compiled while it lives, so a property crossing back and forth reuses them; when the shader's variant budget is spent, the ones no material draws with are given back first. A `properties:` entry is a value property (`float`, `range`, `int`, `bool`, `color`, `float2` to `float4`) the shader declares; one naming no declared property, or a texture or buffer, is refused by name. ### A texture that switches a feature A feature can be switched by the textures a material binds. `textures:` lists texture slots, and the feature is on for every material binding a texture in one of them other than the slot's declared default; `shared_texture:` lists two or more slots, and the feature is on for every material binding one and the same texture in all of them. This is how a shader samples only the maps a material binds: ```yaml properties: - { name: base_color_texture, type: texture, default: white } - { name: rm_texture, type: texture, default: white } - { name: ao_texture, type: texture, default: white } features: - { name: BASE_MAP, default: true, textures: [base_color_texture], description: the base colour map } - { name: AO_MAP, default: true, textures: [ao_texture], description: the occlusion map } - { name: PACKED_AO, shared_texture: [rm_texture, ao_texture], description: occlusion read from the rm map } ``` ```wgsl var base_texel = vec4<f32>(1.0); // what the white default stands for #ifdef BASE_MAP base_texel = textureSample(base_color_texture, base_color_texture_sampler, uv); #endif ``` A switched feature, by value or by texture, is decided by what the material holds: on where one of its switches holds, off where none does, and a material naming the feature under `features:` decides it over the switch. A map feature declared `default: true` keeps the shader's own default configuration sampling every map, so a material whose feature set the variant budget has no room for still draws its maps. A `textures:` or `shared_texture:` entry naming no declared texture slot, and a `shared_texture:` listing one slot, are refused by name. The engine compiles one program per feature set its materials ask for, named `<shader>#<features>`. Materials sharing a set share that program. A feature the shader does not declare selects nothing, so a stray name cannot make the engine compile anything, and the compile names both halves of a mismatch: a guard on a name `features:` does not declare, and a declared name no guard tests. **Permutations are the cost.** A shader with n features can express 2^n programs, each its own compile and pipeline. One shader holds at most 32 variants; a material asking for a set past that draws with the shader's default features and the engine logs which shader ran out. Read what a scene is spending: ```lua for _, s in renderer.shaderVariants() do print(s.shader, #s.variants, "of", s.budget) print(renderer.variantSource(s.base.program)) -- what it ships as for _, v in s.variants do print(v.program, renderer.variantSource(v.program)) -- what one asked for end end ``` A shader registers under every key it answers to — its identity, its guid, each alias — and each key is a row. A variant lands on the row for the key the material named, which for authored content is the guid, so take a program name from the report rather than composing one. ## Materials reference shaders A `.material` applies a shader to entities. Its `mat.yaml` references the shader by its identity string and supplies property values: ```yaml name: my_material shader: "@builtin::shaders.pbr" render: blend: alphaBlend cull: back depth_write: false properties: roughness: 0.5 base_color: [1.0, 1.0, 1.0, 1.0] textures: base_color_texture: { ref: "default:white" } ``` `shader:` is a plain identity string, and a colour is an array. A key's value is the rest of its line, so every value above stands alone on one. ### The render block Render behaviour (the blend equation, alpha cutout, which faces are drawn) lives in the `render:` block and drives the pipeline, not the fragment. These are the keys that reach the pipeline from both authoring routes, and the values each one takes: | Key | Values | Sets | |-----|--------|------| | `blend` | `opaque` `transparent` `alpha` `alphaBlend` `additive` `add` `cutout` `alphaCutout` `premultiplied` `premultipliedAlpha` `multiply` | the equation the fragment composites with | | `cull` | `back` `front` `none` `off` `disabled` | which faces the rasterizer keeps | | `depth_write` | `true` `false` | whether the draw writes depth | | `depth_compare` | `less` `lessEqual` `lequal` `equal` `greater` `greaterEqual` `gequal` `always` `never` | the test a fragment's depth passes | | `topology` | `triangleList` `lineList` `lines` `line` | what consecutive vertices assemble into | | `queue` | a whole number: `2000` opaque, `3000` transparent, `4000` overlay | the draw order of the material; a number inside a queue orders within it | `blend` is also spelled `type`, and the two name one key. Its equations, over the fragment the shader returned (`src`) and the value already in the target (`dst`): `opaque` is `src`; `transparent`, `alpha` and `alphaBlend` are `src * src.a + dst * (1 - src.a)`; `additive` and `add` are `src + dst`, the mode a glow, a light shaft or a spark card is written for; `premultiplied` and `premultipliedAlpha` are `src + dst * (1 - src.a)`, taking a source that already carries its own coverage; `multiply` is `src * dst`, which is how a soot, grime or shadow card darkens what stands behind it. `cutout` and `alphaCutout` keep the fragment or discard it on its alpha and go on writing depth. The same block is what `asset.create`'s `render` argument takes, key for key and value for value, so one material named in Luau and the same material standing on disk ask for their pipeline with the same words. `depth_write` is the one key whose value takes the shape of its route: the word `false` on a `mat.yaml` line, the boolean `false` in the Luau table. ```lua asset.create("material", "heat_plume", { shader = "@builtin::shaders.pbr", render = { blend = "alphaBlend", cull = "none", depth_write = false }, }) ``` Where a value outside a key's set is reported is what the two routes differ on. `asset.create` refuses the call on any of these keys and names the set it measured the value against, or for `queue`, that it takes a number. A `mat.yaml` standing on disk registers either way, each key falling back to a value of its own: `blend` to `opaque`, `cull` to `back`, `depth_write` to `true`, `depth_compare` to `less`, `topology` to `triangleList` and `queue` to `2000`. The engine log carries the blend fallback, naming the value and the set it was measured against, so a `mat.yaml` value is worth putting through `asset.create` once — that is where every key answers with its set. ## Registration & hot reload A `.shader` is compiled by the asset system, not by the renderer: writing `shader.wgsl` or `properties.yaml` fires the `.shader` assetType's `onChange`, which compiles it: the body + the property schema are read, the group(1) interface and (for surface) every render-mode entry point are generated, `#include`s are expanded, the result is **validated**, and the shader is registered. Validation happens at this compile step — the whole point of "compile". A shader with invalid WGSL (an unknown field, a type mismatch, an undefined function) **fails to compile** with the real reason — readable directly from Luau via `shaderRef:compileStatus()` (`{ status = "compiled" | "failed" | "pending", error?, pending? }`), and also in the author log and `asset.inspect`; it is **not** registered. This fires on create and on every edit, so saving a `.wgsl` recompiles with no world reload; the change is visible on the next frame. Compilation is async, so a `compileStatus()` of `"pending"` immediatel
▲ -1↑ born
backing path · modules/debugViz.module

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

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.