# 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**.
# volumetrics
Volumetric (3D-texture) rendering, end to end, in one package. Built
entirely on the engine's generic `compute.*` GPU primitives — no
Rust changes are needed to author new volumetric content.
## Layout
| Asset | Identity | Role |
|---|---|---|
| `Volume.component` | `@builtin::systems.volumetrics.Volume` | Attach a 3D voxel texture to an entity; stands it in the scene through the entity's transform AABB, hidden by what stands in front of it. |
| `VolumetricSky.component` | `@builtin::systems.volumetrics.VolumetricSky` | Clouds in the sky: one per scene, the procedural cloud layer lit by the scene's sun, drawn by `volumetricSky.renderFeature` with no composite authored. |
| `VolumetricLighting.component` | `@builtin::systems.volumetrics.VolumetricLighting` | Light shafts, god rays and glowing air: light scattering between the camera and the scene, drawn by `lightScattering.renderFeature`. |
| `ParticipatingMedium.component` | `@builtin::systems.volumetrics.ParticipatingMedium` | Mark an entity as fog/smoke/dust the camera sees through and that shades the sun on what is under it. |
| `mediaTransmittance.module` | `@builtin::systems.volumetrics.mediaTransmittance` | The registry of media and the settings every media pass reads. |
| `mediaShadow.renderFeature` | `@builtin::systems.volumetrics.mediaShadow` | Writes the sun the media take to `@scene.sunOcclusion` and marches each view ray through the media. |
| `volume.module` | `@builtin::systems.volumetrics.volume` | Builders (`noise`/`sphere`/`box`/`wrap`) + the `.zvol` header reader + occupancy + brick paging + the per-entity raymarch dispatch + the draws standing in the scene (`Volume:draw`). |
| `volume.renderFeature` | `@builtin::systems.volumetrics.volume` | Runs every standing draw's march and composite for each view the frame draws, against its camera and depth. |
| `VolumeSequence.component` | `@builtin::systems.volumetrics.VolumeSequence` | Play an open volume sequence through an entity's transform AABB. |
| `volumeSequence.module` | `@builtin::systems.volumetrics.volumeSequence` | A run of `.zvol` frames streamed through a fixed ring of resident volumes. |
| `volumeDemos.module` | `@builtin::systems.volumetrics.volumeDemos` | Shared pipeline for the showcase scenes (fill + emissive raymarch + composite). |
| `volumetricSky.module` | `@builtin::systems.volumetrics.volumetricSky` | Cloud volume + raymarch + TAA + composite orchestration. |
| `volumetricSky.renderFeature` | `@builtin::systems.volumetrics.volumetricSky` | The cloud layer's passes for every view the frame draws, brought up by `VolumetricSky`. |
| `volumetricLighting.module` | `@builtin::systems.volumetrics.volumetricLighting` | The light-scattering settings, set from code. |
| `lightScattering.renderFeature` | `@builtin::systems.volumetrics.lightScattering` | The light-scattering passes, brought up by `VolumetricLighting`. |
| `shaders/*` | `@builtin::systems.volumetrics.shaders.*` | Compute shaders `volume_raymarch`, `volume_draw`, `volume_pages`, `volume_pack`, `cloud_noise[_v3/_v5]`, `cloud_raymarch[_v3/_v4/_v5]`, `cloud_taa`, `cloud_layer_surfaces`; shaders `volume_draw_composite`, `cloud_layer_composite`, `cloud_layer_blit`, `cloud_sky_composite`; shader modules `volume_march`, `cloud_light`, `cloud_surface`. |
| `importers/vdb_to_zvol.importer` | (auto-discovered) | `.vdb` → dense `.zvol` via the `openvdb` WASM plugin (procedural fallback when the plugin isn't loaded). |
| `presets/cumulus_default.preset` | `@builtin::systems.volumetrics.cumulus_default` | Canonical full `VolumetricSky` weather preset. |
| `demo/*.scene` | `@builtin::systems.volumetrics.demo.*` | `sdf_solids`, `smoke_plume`, `nebula`, `godrays`, `zvol_viewer`, `sky`, `showcase`, with their fill shaders. |
The guide `systems/volumetrics/documentation/README` (`guides { path = ... }`)
names the component for each effect, clouds, fog, light shafts, a fog or smoke
volume and the sky, with what each does and costs.
## Path convention — fully-qualified builtin identities
Every intra-package reference uses the asset's fully-qualified builtin
identity, the same convention every other builtin package follows:
```luau
local Volume = require("@builtin::systems.volumetrics.volume")
local Sky = require("@builtin::systems.volumetrics.volumetricSky")
local V = require("@builtin::systems.volumetrics.volumeDemos")
-- shader identities, e.g. asset.resolve("@builtin::systems.volumetrics.shaders.volume_raymarch")
```
Qualified identities are caller-independent: they resolve identically
from a module, a scene entrypoint, or a component. Caller-relative
(`.sibling`) requires are deliberately avoided here because the
component runtime caller identity is `@builtin::components.<Name>`, so a
`.sibling` require from a component resolves against the wrong root.
(An earlier revision of this package used a `~volumetrics` package-root
alias for relocatability; that alias is not resolvable on current main,
so the package uses qualified identities throughout.)
## Usage
```luau
-- Per-entity volume. The component resolves the name through `Volume.get`,
-- so a volume paged into a brick pool renders from the pool under the same
-- name:
local Volume = require("@builtin::systems.volumetrics.volume")
local cloud = Volume.noise({ name = "cloud", size = 64, scale = 4 })
cloud:buildSparse({ brickSize = 8 })
cloud:releaseDense()
entity(id).component.add("Volume", { volumeName = "cloud", density = 6.0 })
-- Procedural sky:
local sky = entity.spawn("sky")
sky.component.add("VolumetricSky", {})
preset.apply("cumulus_default", { entity = sky.id, component = "VolumetricSky" })
-- VDB import: drop a `.vdb` into the VFS; the importer writes a `.zvol`
-- alongside it. Load it with the zvol_viewer demo scene.
-- Animated run: one `.zvol` per frame, played through a bounded ring.
local Seq = require("@builtin::systems.volumetrics.volumeSequence")
Seq.open({ name = "plume", frames = framePaths, resident = 3, fps = 24 })
entity(id).component.add("VolumeSequence", { sequenceName = "plume", density = 6.0 })
```
## Plugin dependency
The VDB importer delegates real OpenVDB parsing to the `openvdb` plugin
in the builtin library, `@builtin::plugins.openvdb`. Without the plugin
the importer falls back to a deterministic procedural torus so the
pipeline stays functional.
# target
The declarer a preset's values are for: resolved by the guid its target
envelope names (pinned in the preset's `.refs`) or by the identity string a
hand-written target names, checked against that declarer's current schema,
and compared with the checksum the pin recorded.
## Exports
- `Target.literalFor(ref) -> string` — the guid a preset pins for `ref`.
- `Target.describe(ref) -> string` — `ref`'s identity.
- `Target.envelopeFor(ref) -> Envelope` — `{ __ref, type, name }` for `ref`.
- `Target.resolve(presetRef, doc) -> Resolved`
- `Target.resolveLiteral(literal: string) -> Resolved`
- `Target.declarerOfAsset(ref) -> (declarer, schema)`
- `Target.isComponentTarget(v) -> boolean` — true for `{ entity = <id>, component = <name> }`.
- `Target.declarerOfComponent(t) -> (component, schema, proxy)` — the component asset governing a component on an entity, its schema, and the live component.
- `Target.check(schema, values) -> (valid, rejected)`
- `Target.valuesOf(presetRef, doc) -> (values, report, resolved?)` — what `preset.values` answers, from a document already read.
- `Target.merge(schema, current, patch) -> values`
- `Target.refuse(prefix: string, violations)` — raises.
Types:
- `Resolved = { literal: string, name: string, ref: any?, guid: string?, schema: any?, pinned: boolean, changed: boolean }`
- `Violation = { path: string, message: string }`
- `Report = { format, target, targetGuid?, pinned, targetChanged, rejected }`
## Usage
```luau
local Target = require("@builtin::modules.preset.target")
local declarer, schema = Target.declarerOfAsset(texRef)
```
# document
A preset's `preset.yaml`: decoding it, reading it and writing it.
The typed form names the declarer the values are for and the values:
```yaml
target: { __ref: "<guid>", type: assetType, name: texture }
values:
filter: nearest
```
`target` is written as a guid envelope, which the preset's `.refs` pins by
guid; `type` and the target's plain `name` say what it points at to a person
reading the file, and `name` is never an identity, so the guid is the one link.
A `target` written as an identity string (`"@builtin::assetTypes.texture"`,
or a world asset's identity) is accepted on read. The component-only form,
`component:` + `properties:`, reads as authored.
## Exports
- `Document.pathOf(ref) -> string`
- `Document.decode(body: string) -> Doc`
- `Document.read(ref) -> Doc`
- `Document.encode(envelope: Envelope, values) -> string`
- `Document.write(ref, envelope: Envelope, values)`
Types:
- `Envelope = { __ref: string, type: string?, name: string? }`
- `Doc = { format: "typed" | "legacy", target: string?, envelope: Envelope?, component: string?, title: string?, values: { [string]: any } }`
## Usage
```luau
local Document = require("@builtin::modules.preset.document")
local doc = Document.read(presetRef)
```
# editorSelection
Named selection scopes for the editor. A scope is an independently
tracked, ordered set of typed refs plus a primary (the last ref added
or clicked). Distinct scopes never clobber each other, so viewport,
outliner, inspector and asset browser share one answer to "what is
selected" per kind.
A ref is `{ kind: string, id: string }` — a stable id, never a display
string, so rename/move never invalidates a selection.
## Exports
- `M.scope(name) -> Scope` — get/create a named scope handle.
- `M.set(scope, refs)` — replace refs in order; primary becomes the last.
- `M.get(scope) -> { Ref }` — refs in click order (fresh array).
- `M.primary(scope) -> Ref?` — last-clicked ref, or nil.
- `M.clear(scope)` — empty a scope.
- `M.toggle(scope, ref)` — add if absent, remove if present.
- `M.add(scope, refs)` — add each ref not already present; primary becomes the last added.
- `M.remove(scope, refs)` — remove each of `refs`; primary becomes the last remaining or nil.
- `M.contains(scope, ref) -> boolean` — membership by `(kind, id)`.
- `M.count(scope) -> number` — the scope's selection size.
- `M.subscribe(scope, fn) -> handle` / `M.unsubscribe(scope, handle) -> boolean`.
- `M.context() -> { scope, refs, primary }` — last-focused scope, for command ctx.
## Usage
```luau
local Selection = require("@builtin::modules.api.editor.selection")
local scope = Selection.scope("entity")
Selection.set(scope, { { kind = "entity", id = "player_1" } })
Selection.subscribe(scope, function() refreshInspector() end)
```
## Notes
- State lives in a fixed `_G` slot, seeded pre-seal by the boot chain
(`prelude.luau`); it survives hot-reload and edit↔play flips. Mutations
after boot write into nested tables only.
- `set` / `toggle` / `clear` mark their scope as last-focused, which drives
`context()` and therefore which scope commands act on.
- The service holds the editor's selection state in Luau. Refs handed back by
`get` / `primary` / `context` are copies, so a caller can hold or mutate them
without touching internal state.
# 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.
# ParticipatingMedium
Marks its entity as a volume of fog, smoke, dust or steam — something light has
to travel through. What is behind the volume comes out dimmer than what is
beside it, and overlapping volumes stack.
```luau
local id = entity.spawn("fog_bank").id
entity(id).component.add("ParticipatingMedium", {
sizeX = 30, sizeY = 8, sizeZ = 30,
density = 0.15,
})
```
## Fields
| Field | Meaning |
|---|---|
| `shape` | `"box"` (default) or `"sphere"` |
| `density` | Extinction per world unit. `0` releases the medium. |
| `sizeX` / `sizeY` / `sizeZ` | Half-extents, for a box |
| `radius` | Radius, for a sphere |
`density` is the physical knob: a ray crossing `d` world units of a medium of
density `k` leaves with `exp(-k * d)` of the light it entered with. A 20-unit
bank at `0.15` therefore passes about 5% of the light straight through it.
The entity's position places the volume; move the entity and the shadow moves
with it.
## Notes
- The light-space map is sized to the bounding sphere of everything registered.
A small bank sharing a scene with a very large one lands on few texels — set
`extent` and `centre` through `mediaTransmittance.set` to bias the map toward
the region you care about.
- Attenuation applies to surfaces. The sky keeps its own colour.
- The attenuated light is the sun's: `sunDirection` sets which way the map's
rays travel.
See `mediaTransmittance` for the scene-wide settings and the direct API.
# Volume
Per-entity attachment that renders a 3D voxel texture (cloud, smoke,
nebula, imported VDB grid) into the scene as a volumetric body. The
component does NOT own the volume's lifetime — producers (the
`volume` module, a custom compute fill, or `compute.writeTexture3D`)
build the texture and pass its name in `volumeName`. The entity's
world transform defines the AABB the raymarcher samples.
`volumeName` is resolved through `Volume.get`, so a volume the `volume`
module built is rendered as it stands — at its own dimensions, from its own
density channel, through its occupancy grid, and out of its brick pool if it
is paged. A name no volume answers to is taken as a bare 3D texture some
other system owns, and `occupancyName` / `isRgba` describe it.
## Usage
```luau
local Volume = require("@builtin::systems.volumetrics.volume")
local cloud = Volume.noise({ name = "cloud", size = 64, scale = 4 })
cloud:buildOccupancy({ brickSize = 8 })
local e = entity.spawn("cloud_entity")
e.localScale.set(8, 4, 8)
e.component.add("Volume", {
volumeName = "cloud",
occupancyName = cloud.occupancyName,
density = 6.0,
})
```
A paged volume costs what it holds and is named the same way:
```luau
local cloud = Volume.noise({ name = "cloud", size = 128, threshold = 0.6 })
cloud:buildSparse({ brickSize = 8, threshold = 0.01 })
cloud:releaseDense() -- the brick pool is now the only copy
local e = entity.spawn("cloud_entity")
entity(e.id).localScale = { 8, 4, 8 }
e.component.add("Volume", { volumeName = "cloud", density = 6.0 })
```
## Public fields
| Field | Type | Sync | Default | Meaning |
|---|---|---|---|---|
| `volumeName` | string | Sync | `""` | Required. Name of the volume, or of a bare 3D texture, to render. |
| `occupancyName` | string | Sync | `""` | R8 occupancy texture for a bare texture's empty-space skipping. Empty = no occupancy. A volume the module built carries its own, and a name set against one is reported as left aside. |
| `density` | number | Sync | `1.0` | Density gain multiplier. |
| `absorption` | number | Sync | `1.0` | Beer-Lambert absorption coefficient. |
| `emission` | number | Sync | `1.0` | Emission gain. |
| `color` | color | Sync | `{1,1,1,0}` | RGB tint + density floor in alpha. |
| `stepSize` | number | NoSync | `0` | World units per ray step. `0` = auto-derive from volume extent. |
| `maxSteps` | number | NoSync | `256` | Ray-march step cap. |
| `target` | string | Sync | `"scene_volume_rt"` | Output render target name (composite key). |
| `targetWidth` | number | NoSync | `1280` | Output width (px). |
| `targetHeight` | number | NoSync | `720` | Output height (px). |
| `useOccupancy` | boolean | NoSync | `true` | Toggle empty-space skipping. |
| `isRgba` | boolean | Sync | `true` | `false` reads density from the red channel. Left `true`, a volume the module built is read from the channel it was built with, and a bare texture as RGBA. |
All public fields use the `Field.<kind>(default, Sync|NoSync)` schema
(PR #3019). Visual params (look, tint, density) propagate Sync;
quality knobs (stepSize, maxSteps, target resolution, useOccupancy)
are NoSync — each client picks its own perf/quality point.
## Lifecycle
- **`awake`** — no-op. The volume texture is owned by the producer
and looked up lazily on the first `update`.
- **`update(dt)`** — resolves `volumeName` through `Volume.get`, falling
back to a wrapper over a bare texture of that name, and dispatches the
compute raymarcher into `target`. The resolution runs every frame, so a
volume built, paged or destroyed after this component attached is picked
up on the next one.
- **`onPropertyChanged(key, value, old)`** — drops the resolved volume
when `volumeName`, `occupancyName`, or `isRgba` changes, forcing a
re-resolve on the next frame.
## Related
- `volume` module — texture builders and name lookup (`Volume.noise`,
`Volume.get`, `Volume.wrap`, `:buildSparse`, `:render`).
- `vdb_to_zvol.importer` — VDB → dense voxel pipeline that produces
textures consumable by this component.
- `volumeDemos` / `volumetricSky` packages — worked examples.
# VolumeSequence
Plays an open volume sequence through an entity's transform AABB.
The sequence is opened by a producer and named here — the same split the
`Volume` component makes between "what data to render" and "where it appears
in the world". Each tick the component advances the playhead and raymarches
the frame that is resident into the shared `scene_volume_rt` target, in both
play and edit mode, so the run animates while it is being authored.
```luau
local Seq = require("@builtin::systems.volumetrics.volumeSequence")
Seq.open({ name = "plume", frames = paths, resident = 3, fps = 24 })
local id = entity.spawn("plume_entity").id
entity(id).localScale = { 8, 8, 8 }
entity(id).component.add("VolumeSequence", { sequenceName = "plume", density = 6.0 })
```
`fps` and `playing` are pushed into the sequence when they change, so a
script calling `seq:setFps()` / `seq:pause()` between two ticks is left
standing until the authored value itself moves.
The component does not own the sequence: despawning the entity leaves the
ring allocated, and `volumeSequence.close(name)` is what frees it.
## Sharing
The playhead, the rate and the ring belong to the sequence, so several
entities naming one run play the same frame from the same three textures:
the playhead advances once per engine frame however many components tick it,
and the rate is whichever component's `fps` moved last. Give each entity its
own run when they should play independently.
`target` is a render target, and a raymarch writes the whole of it — two
volumes visible at once (a sequence beside a `Volume`, or two sequences) need
a `target` name each, or the later write replaces the earlier one and only
one of them appears. Composite each target the way any volume render is
composited — see `volume.compositeShaderSource()`.
# VolumetricLighting
The air between the camera and the scene, as a component. Add it to an entity
and light travelling through that air scatters toward the viewer, so a lamp
becomes a glow rather than an invisible point and the sun cuts shafts where
something crosses it.
```lua
local id = entity.spawn("air").id
entity(id).component.add("VolumetricLighting", {
density = 0.06,
anisotropy = 0.7,
})
```
Every field is live — editing one in the inspector changes the air on the next
frame, and the values persist with the scene. Setting `density` to 0 empties the
air and releases the passes while keeping the rest authored; removing the
last one in the scene clears it.
| field | effect |
|---|---|
| `density` | How much medium there is per world unit at the reference altitude. 0 is off. |
| `heightFalloff` / `heightRef` | How fast density thins with altitude, and the altitude `density` is quoted at. 0 falloff fills the scene evenly. |
| `steps` | Samples along each view ray. More resolves a beam's edge more cleanly. |
| `colorR/G/B` | What the medium scatters. Warm dust and cold mist differ here. |
| `anisotropy` | How forward-biased the scattering is, in (-1, 1). Positive values throw light onward, so haze blooms around a source you look toward. |
| `sunIntensity` / `sunColorR/G/B` | The sun's contribution to the medium. |
| `lightScale` | The scene lights' contribution to the medium. |
| `shadowSteps` / `shadowDistance` | Samples taken back toward the sun to decide whether a point in the air is lit, and how far they reach. **0 leaves the sun's contribution unshadowed**, so the haze glows evenly and no shafts form. |
| `maxDistance` | How far along the view ray the march runs. A ray that escapes to sky stops here. |
The lights are the scene's own, each scattering on the terms its kind emits on:
a point fills the air around it, a spot fills its cone, a rect reaches the air on
the side its face emits along, and a parallel light lays an even glow across the
whole medium. One added, moved, re-aimed or recoloured at runtime changes the
glow it throws with nothing to keep in step here.
One body of air fills the scene, so one of these per scene is enough — the last
one to push wins.
The work runs in `lightScattering.renderFeature`; the settings live in
`@builtin::systems.volumetrics.volumetricLighting`, which is also how to drive
them from a script.
# VolumetricSky
Clouds in the sky, as a component. Add it to one entity and the sky gets a
volumetric cloud layer lit by the scene's own sun: cumulus by default, its
coverage, altitude, wind and look set by a preset. The component owns the
cloud volume, bakes its noise field when what it is baked from changes, and
the `volumetricSky` render feature it brings up draws the layer into every
view the frame draws, over the sky and over the surfaces under it. Adding
the component is the whole set-up: no composite is authored. The layer draws
in edit mode as well as in play, and drifts with the wind once play runs.
## Usage
```luau
-- Defaults (the v4-tuned cumulus look — `Sky.defaultPreset()` hands out a
-- copy of the same table this field defaults to)
local sky = entity.spawn("sky")
sky.component.add("VolumetricSky", {})
-- Or apply a captured preset:
preset.apply("cumulus_default", { entity = sky.id, component = "VolumetricSky" })
-- Inline tweak. `component.add` writes the `preset` field as it is given,
-- so a table handed here carries the whole configuration:
local p = require("@builtin::systems.volumetrics.volumetricSky").defaultPreset()
p.noiseScale, p.octaves, p.coverage = 9.0, 5, 0.20
p.densityGain = 0.04 -- v5 σ_t
sky.component.add("VolumetricSky", { shaderVariant = "v5", preset = p })
```
`volumetricSky.module`'s `M.spawn` / `M.configure` take the same parameters
by name, folding each into the current configuration and leaving the rest
where they stand:
```luau
local Sky = require("@builtin::systems.volumetrics.volumetricSky")
Sky.spawn({ shaderVariant = "v5", noiseScale = 9.0, coverage = 0.20 })
```
## Schema (Field<T> / Sync / NoSync)
The 28 shaping / weather / lighting params travel as ONE Sync field
— `preset = Field.table(DEFAULT_PRESET, Sync)` — so replicating a
sky change is **one mutation, not 28**, and copying a sky between
scenes is **copying one field, not 28**. Per-client quality knobs
sit outside the preset as NoSync fields so each client picks its
own tier without disturbing peers.
`SkyPreset` and `DEFAULT_PRESET` are declared by `volumetricSky.module`,
which this component reads its default from and which routes an option by
that same key set — so the shape below and the module's `M.spawn` options
are one declaration.
| Field | Type | Sync | Default | Meaning |
|---|---|---|---|---|
| `preset` | `SkyPreset` table | Sync | `DEFAULT_PRESET` (v4 cumulus) | All shaping / weather / lighting (see below). |
| `shaderVariant` | string | Sync | `"v4"` | `"v3" \| "v4" (default) \| "v5"`. |
| `wind` | vec3 | Sync | `{0,0,0}` | Animated drift offset (advanced per frame from `preset.windSpeed`). |
| `cloudSize` | number | NoSync | `256` | Volume W,D resolution. |
| `cloudHeight` | number | NoSync | `128` | Volume H resolution. |
| `stepSize` | number | NoSync | `4.0` | World units per ray step. |
| `maxSteps` | number | NoSync | `224` | Ray-march step cap. |
| `shadowSteps` | number | NoSync | `8` | Shadow ray step count. |
| `alphaCutoff` | number | NoSync | `0.99` | Early-exit α threshold. |
| `jitter` | number | NoSync | `1.0` | Ray-origin jitter strength. |
| `taaBlendAlpha` | number | NoSync | `0.1` | TAA current-sample weight. |
| `targetWidth` | number | NoSync | `0` | Render target width (`0` = the width of the view the scene is drawn into, `getViewportSize()`). |
| `targetHeight` | number | NoSync | `0` | Render target height (`0` = the view's height). |
| `noiseRegenRate` | number | NoSync | `10` | Times per second wind drift re-bakes the cloud volume (`0` = every frame the wind moved). |
### Preset (`SkyPreset`) shape
Noise / shaping: `noiseScale, octaves, coverage, densityGain,
altitudeLow, altitudeHigh, anvilBias, detailScale, detailOctaves,
detailStrength, detailThreshold, baseLowRemap, baseHighRemap, color,
windSpeed, seed`.
Volume placement: `horizExtent, cloudBaseAltitude, cloudTopAltitude`.
Look (visual, not perf): `phaseG`.
Sun / sky: `sunColor, sunIntensity, sunDiscSize, horizonColor, zenithColor,
groundColor, ambient`. The clouds are lit by the scene's own sun every frame: the sun's direction, its colour, and its intensity up to a
unit sun, which scales these too, so a night leaves the clouds dark and a sun at
zero leaves them black. `sunDir` is deprecated and kept so a stored preset
still loads.
v5-only: `cloudType, worleyBlend`.
See `presets/cumulus_default.preset/preset.yaml` for the canonical
full preset shape, and the `init.luau` `DEFAULT_PRESET` table for
the runtime defaults.
## Where the frame time goes
Two passes carry the cost, and different fields reach each:
- **The bake** (`cloud_noise_*`) fills every voxel of the
`cloudSize × cloudHeight × cloudSize` volume with layered noise. It is
the most expensive pass the layer has (around 10 ms at 256×128×256 on a
desktop GPU), and it runs only when the volume's inputs move: at once
for a change to `preset`, `cloudSize`, `cloudHeight`, `shaderVariant`
or the render device, once the program it compiles is resident for an
edit to the noise shader's own source, and at most `noiseRegenRate`
times per second for wind drift. A sky whose `preset.windSpeed` is zero
bakes once. `cloudSize` / `cloudHeight` set what one bake costs;
`noiseRegenRate` and `windSpeed` set how often it is paid.
- **The raymarch** (`cloud_raymarch_*`) runs for every view of every
frame. `stepSize`, `maxSteps`, `shadowSteps`, `alphaCutoff` and
`targetWidth` / `targetHeight` set its cost.
`profiler.gpuFrame()` reports both as `compute.<shader>` spans; a span's
`frames` count is how many frames of its window the pass ran in, and
`volumetricSky.volumeBakes()` counts the bakes themselves.
## Field-mutation gotcha (and why `update()` reassigns the whole vec3)
Under the new Field<T> / Sync / NoSync schema, `public` is not a
plain Lua table — it's wrapped in a proxy whose `__newindex`
metamethod performs type-checks, marks the field dirty, and queues
Sync replication. Writing `public.wind = {x,y,z}` triggers all four
steps. Writing `public.wind[1] = x` reads `public.wind` (getter),
mutates the returned table directly, and **bypasses the setter** —
no Sync replication, no dirty flag, no `onPropertyChanged`. Always
assign the whole vec3 / preset / color table; never index-mutate.
The same caveat applies to `public.preset`: `public.preset.coverage = 0.2`
won't replicate. To change one preset field, copy the table, mutate,
reassign:
```luau
local p = public.preset
local next = {}
for k, v in pairs(p) do next[k] = v end
next.coverage = 0.2
public.preset = next
```
## Lifecycle
- **`awake`** / **`onEnable`**: start the sky's clock and hold the cloud
layer up (`volumetricSky.holdLayer`), which brings up the render feature
that runs the layer's passes.
- **`update(dt)`**: advances `wind` (reading `preset.windSpeed`),
hands the noise inputs to `volumetricSky.fillClouds`, which bakes the
volume when they moved (see "Where the frame time goes"), then queues
the raymarch dispatch for the frame's deferred phase.
- **`editorUpdate(dt)`**: the same bake and dispatch in edit mode, so the
editor viewport, an edit-mode capture and a probe baked in edit mode show
the clouds. The wind stands where the scene holds it; drift runs in play.
- **`onDisable`** / **`onDestroy`**: let go of the layer
(`volumetricSky.releaseLayer`). When the last sky lets go, the render
feature comes down and `M.destroy` releases the volume, the render targets
and the programs, so the next frame is drawn with no cloud layer and no
cloud pass runs.
- **`onModuleReload(path)`**: a reload of `volumetricSky.module` starts it
with no holders, so a sky holding the layer holds it again on the reloaded
module.
The layer is one per engine: every sky standing holds it, and it comes down
with the last one.
### Why the raymarch is dispatched from `task.defer`
The raymarch produces ONE full-screen layer for ONE view, and the frame
composites it over everything that frame drew — so it has to be rendered
from the view the frame ends up drawn with. Which view that is settles
only once the frame's script work is finished: a cutscene walking the
camera from a task loop, a camera controller, a component ordered after
this one, an editor tool — each writes the camera after `update` has
run, while the renderer reads the camera once all of them are done.
Taking the camera snapshot in the deferred phase reads what every one of
them has already written, and still queues the dispatch ahead of the
frame's render. Snapshotting in `update` instead renders the layer for
whatever the camera was midway through the frame; on a hard cut that is
a different place entirely, and the frame the cut lands on composites a
cloud layer belonging to the shot it just left.
A caller driving `volumetricSky.dispatchRaymarch` directly owes the same
discipline.
## Related
- `volumetricSky.module` — orchestration backend.
- `presets/cumulus_default.preset` — canonical full preset; copy
to author named weather (storm, overcast, dawn, …).
- `Volume.component` — per-entity flow for non-cloud volumetric content.
- `demo/sky.scene` — worked example.
·computeshader · born here
❒asset # godrays_fill
Fills a volume with shafted light. One invocation per voxel.
## Bindings
| name | kind | what it is |
|------|------|------------|
| `vol` | `storage3d` (rgba16f) | the volume written — RGB emission, A density |
| `U` | `buffer` (read, f32) | the demo's fill parameters |
·computeshader · born here
❒asset # nebula_fill
Fills a volume with a spiral nebula: RGB carries emission, A carries density.
One invocation per voxel at workgroup size 4x4x4.
## Bindings
| name | kind | what it is |
|------|------|------------|
| `vol` | `storage3d` (rgba16f) | the volume written, read-write so a pass can accumulate |
| `U` | `buffer` (read, f32) | the demo's fill parameters, in the order the shader reads them |
`U` holds: elapsed time, spiral frequency, arm thickness, core brightness, edge
brightness, dust density, noise strength.
·computeshader · born here
❒asset # sdf_solids_fill
Fills a volume with signed-distance solids. One invocation per voxel.
## Bindings
| name | kind | what it is |
|------|------|------------|
| `vol` | `storage3d` (rgba16f) | the volume written — RGB emission, A density |
| `U` | `buffer` (read, f32) | the demo's fill parameters |
·computeshader · born here
❒asset # smoke_plume_fill
Fills a volume with a rising smoke plume. One invocation per voxel.
## Bindings
| name | kind | what it is |
|------|------|------------|
| `vol` | `storage3d` (rgba16f) | the volume written — RGB emission, A density |
| `U` | `buffer` (read, f32) | the demo's fill parameters |
·computeshader · born here
❒asset # zvol_viewer_fill
Leaves the volume as it is. The ZVOL viewer uploads voxels straight into the
volume's 3D texture from the CPU, so the fill stage this shader occupies has
nothing to compute — it reads one value from each binding so both stay live.
## Bindings
| name | kind | what it is |
|------|------|------------|
| `vol` | `storage3d` (rgba16f) | the volume the viewer writes into from the CPU |
| `U` | `buffer` (read, f32) | the fill parameters the spawn API supplies |
·computeshader · born here
❒asset # emission_raymarch
Marches a camera ray through an emissive volume and writes the result to a 2D
target. Emission accumulates along the ray and density attenuates what is behind
it, so a volume reads as light rather than as a surface.
## Bindings
| name | kind | what it is |
|------|------|------------|
| `vol` | `texture3d` | the volume marched — RGB emission, A density |
| `smp` | `sampler` | how `vol` is filtered along the ray |
| `out_tex` | `storage2d` (rgba16f) | the image the march writes |
| `U` | `buffer` (read, f32) | camera, volume placement and march settings |
`U` carries the inverse view-projection, the volume's world transform, the step
count, density and emission gains, and the target's inverse size.
# VDB → ZVOL importer
Claims `.vdb` (OpenVDB) writes and produces a sibling `.zvol` — the
engine-native dense RGBA8 volumetric format consumed by the volumetrics
system.
This is a standard `importer` asset: `init.luau` returns a
`{ canImport, import }` module that the importer dispatcher
(`@builtin::assetTypes.importer`) loads lazily and runs only when a matching
file is written. It does **not** execute anything at load time.
## Pipeline
1. **Real parse** — if the `openvdb` plugin in the builtin library
(`@builtin::plugins.openvdb`) is loaded, the VDB B-tree is parsed into a
dense RGBA8 voxel buffer and wrapped in a 64-byte ZVOL header.
2. **Procedural fallback** — without the plugin, a deterministic
noise-modulated torus is synthesised (FNV-1a hash of the first 256 source
bytes seeds it) so the importer + demo wiring stays functional. The
`produced_by` field in the result distinguishes the two paths.
## ZVOL header (64 bytes)
| offset | size | field |
|--------|------|-------|
| 0 | 4 | magic `ZVOL` |
| 4 | 4 | u32 version (1) |
| 8 | 4 | u32 width |
| 12 | 4 | u32 height |
| 16 | 4 | u32 depth |
| 20 | 4 | u32 format (1 = rgba8) |
| 24 | 12 | f32[3] aabb_min |
| 36 | 12 | f32[3] aabb_max |
| 48 | 16 | reserved |
| 64 | … | voxel data, `w*h*d*4` bytes, XY-major Z-slowest |
·renderfeature · born here
❒asset # lightScattering
The render passes behind the `VolumetricLighting` component and the
`volumetricLighting` module.
Two compute passes after lighting.
**`vol_scatter`** marches each view ray at half resolution, from the camera to
the surface the ray hits — or to the medium's reach when it escapes to sky, since
an unbounded march would integrate the whole horizon into every sky pixel. At
each step it evaluates the medium's density, gathers the light arriving there,
and accumulates the fraction sent toward the camera, attenuating by everything
already crossed.
A surface-only renderer draws the pool of light a lamp throws on the floor but
not the beam that carried it there, because nothing between the lamp and the
floor is ever shaded. Marching the ray shades that space.
The lights are the scene's own. `@scene.lights` is the same buffer the lit passes
read, so a light added, moved or recoloured at runtime changes the beam it throws
with no bookkeeping here. It holds **twelve vec4s per light** — the light, then
its punctual shadow record — read as raw words so no struct declaration has to
mirror the engine's layout. A spot's cone gate is
evaluated at the sample itself rather than at a surface, which is what makes the
cone visible as a volume instead of only where it lands. Attenuation matches the
lit passes' windowed falloff, so a beam and the pool of light it lands in agree
about how far the source reaches. Area lights are skipped — their contribution to
a medium is an integral over the rect rather than a single direction.
The sun's contribution is gated by a short march back toward it, tested against
the depth buffer. That is what turns uniform haze into shafts: the medium is lit
only where the path back to the sun is clear, so an occluder carves a dark volume
out of the beam rather than only shading the surface behind it. Because the test
reads the depth buffer, an occluder outside the view frustum does not cast into
the medium.
Scattering follows Henyey-Greenstein, so the medium brightens toward a source you
are looking at and stays dim when it is behind you — the difference between haze
that reads as air and haze that reads as a grey wash.
Each ray's first sample is offset by a per-pixel fraction of a step, trading the
banding a fixed step pattern produces for noise.
**`vol_composite`** upsamples that result and composites it. The taps are weighted
by how closely their depth matches the full-resolution pixel's, which keeps a beam
from bleeding across a silhouette — the halo a plain bilinear upsample leaves
behind.
The camera comes from `@frame.camera`, the camera of the render target being
drawn, and the forward matrix is derived by inverting it in the shader rather than
passed in from script — so an offscreen capture or an RTT camera marches through
its own matrix at its own resolution.
Parameters arrive through the `vol_params` buffer, packed by the
`volumetricLighting` module.
·renderfeature · born here
❒asset # mediaShadow
The shadow a fog bank casts on what is behind it.
Two compute passes run after lighting:
| Order | Pass | Work |
|---|---|---|
| 36 | `media_tau_map` | One ray per texel of a light-space map; accumulate optical depth |
| 37 | `media_shadow_apply` | Attenuate each surface by the density in front of it |
| 38 | composite | Blit the result |
## Why not a shadow map
A depth-based shadow map answers one question per texel: is this point nearer
the light than the first thing the light hit? Density has no first thing. What
a medium does to light is continuous — a ray crossing `d` units of extinction
`k` keeps `exp(-k*d)` of its energy — so what a receiver needs is the optical
depth between it and the light, not a depth to compare against.
The first pass therefore stores optical depth rather than distance, at four
points down each ray. Two consequences fall out of that choice:
- **Overlapping media stack.** Optical depth is additive, so two volumes that
intersect contribute to the same running total with nothing to resolve.
- **Geometry inside a volume is lit correctly.** A receiver looks up its own
position along the ray and reads the depth accumulated *up to that point*, so
a post standing in the middle of a fog bank is dimmed by the half in front of
it rather than by the whole column.
## Inputs
`@scene.color`, `@scene.depth`, `@frame.camera`, and the `media_params` /
`media_volumes` buffers packed by
`@builtin::systems.volumetrics.mediaTransmittance`.
Sky pixels are passed through untouched.
# mediaTransmittance
Light attenuation through participating media, in a form both media and
surfaces can sample.
A shadow map stores one depth per texel and answers a yes/no question, so
nothing made of density can cast with it. This module owns the other
representation: a light-space map holding the **optical depth** accumulated
along each light ray, recorded at four points down its length.
Optical depth is additive. Every medium a ray crosses contributes to the same
texel, so overlapping volumes stack with nothing to resolve between them. And
because four points are stored rather than one total, a receiver standing
halfway through a fog bank is attenuated by the half in front of it, not by the
whole column.
## Direct use
```luau
local Media = require("@builtin::systems.volumetrics.mediaTransmittance")
Media.set({ sunDirection = { 0.55, 0.55, 0.55 }, steps = 32 })
Media.setMedium("bank", {
position = { 0, 8, 0 },
size = { 20, 6, 20 },
density = 0.15,
})
```
Most scenes attach `ParticipatingMedium` to an entity instead and let it drive
this module.
## API
| Call | Effect |
|---|---|
| `set(opts)` | Scene-wide settings; omitted fields keep their value |
| `setMedium(key, opts)` | Register or move a medium under a stable key |
| `removeMedium(key)` | Drop one medium |
| `get()` | A copy of the settings in force |
| `clear()` | Drop everything and release the passes |
| `active()` | Whether the passes are running |
### Settings
| Field | Meaning |
|---|---|
| `sunDirection` | Points **toward** the sun; light travels the other way |
| `strength` | How much of the computed attenuation is applied, `[0, 1]` |
| `steps` | Samples along each light ray, `[4, 128]` |
| `extent` | Half-width of the map in world units; `0` sizes it to the media |
| `centre` | Point the map is centred on; omit to centre it on the media |
### Media
| Field | Meaning |
|---|---|
| `position` | World-space centre |
| `shape` | `"box"` (default) or `"sphere"` |
| `size` | Half-extents, for a box |
| `radius` | Radius, for a sphere |
| `density` | Extinction per world unit |
Up to 32 media are packed into the records buffer.
## Cost and limits
The map is 512×512 and is rebuilt each frame; `steps` sets the march length.
With nothing registered the passes are released entirely, so a scene with no
media pays nothing.
The map is sized to the bounding sphere of everything registered, so a small
bank sharing a scene with a much larger one lands on few texels — set `extent`
and `centre` explicitly to bias the map toward the region that matters.
Attenuation applies to surfaces. The sky keeps its own colour.
# media_common
The media-shadow passes' shared ground: the volume record layout, the transmittance
accumulation along a ray, and the cap on how many volumes one frame carries
(`MAX_VOLUMES` = 32). That cap sizes a fixed array, so it is a constant here
rather than a param.
·computeshader · born here
❒asset # media_shadow_apply
Applies the media's transmittance to the lit scene.
## Bindings
| name | kind |
|------|------|
| `source_map` | `texture2d` |
| `scene_depth` | `texture_depth` |
| `tau_map` | `texture2d` |
| `frame_cam` | `buffer` |
| `media_params` | `buffer` |
| `media_out` | `storage2d (rgba16f)` |
·computeshader · born here
❒asset # cumulus_default
Default weather preset for `VolumetricSky.component`. Captures the
v4-tuned cumulus look: visible discrete clouds, warm-afternoon sun,
moderate coverage.
## Use
```luau
local sky = entity.spawn("sky")
sky.component.add("VolumetricSky", {})
preset.apply("cumulus_default", { entity = sky.id, component = "VolumetricSky" })
```
The values set the component's `preset` Field.table as a unit — one
Sync replication carries every shaping/lighting parameter to peers. Tweak
by reading the values and changing them before the component is added:
```luau
local values = preset.values("cumulus_default")
values.shaderVariant = "v5" -- swap raymarcher
values.preset.coverage = 0.6 -- sparser sky
sky.component.add("VolumetricSky", values)
```
## Authoring more presets
Capture a sky you have tuned with
`preset.capture({ entity = sky.id, component = "VolumetricSky" }, "<name>")`,
or drop another `<name>.preset/` folder next to this one (or anywhere under
`/zero/source/`); the asset indexer registers it and `preset.values("<name>")`
resolves it. Common alternatives:
- `stratocumulus.preset` — broad overcast layer (`coverage ~= 0.15`,
`cloudType = 0.5`, `altitudeHigh ~= 0.65`).
- `clear.preset` — barely any cloud (`coverage ~= 0.7`,
`densityGain ~= 0.2`).
- `storm.preset` — dense black anvils (`coverage ~= 0.1`,
`densityGain ~= 0.85`, `sunColor ~= [0.6, 0.55, 0.5]`).
`preset` is one `Field.table`: applying a preset replaces it whole, so
provide every field.
# scattering_common
The light-scattering passes' shared ground: the phase function, the shadow lookup along a ray, and the froxel-to-world mapping.
Included with `#include "@builtin::systems.volumetrics.scattering_common"`.
·computeshader · born here
❒asset # cloud_layer_surfaces
The cloud layer over the surfaces. Writes each cell of the layer whose scene
pixel a surface stands on, by the frame's depth once the transparent phase has
drawn (`@scene.depth`, the sea's included), and nothing in the cells over sky.
`cloud_layer_composite` lays what it writes over the frame at the head of the
`medium` stage; the sky's cells were laid before the transparent phase.
Bindings (see bindings.yaml): `layer` (texture2d, the accumulated layer),
`scene_depth` (texture_depth, `@scene.depth`), `out_tex` (storage2d rgba16f, the
size of the layer; the dispatch grid covers it).
# cloud_light
The light the cloud layer is lit by, read by every cloud raymarcher: the
scene's own sun (`@frame.light`, through
`@builtin::shaderModules.frame_light`), with the layer's preset stating how
brightly the sun lights the clouds and what colour the sky around them is.
- `cloud_sun_dir()` — the direction toward the scene's sun.
- `cloud_sun_radiance()` — the preset's sun colour and brightness over the scene
sun's colour and share (its intensity up to a unit sun).
- `cloud_sky_share()` — how much of the preset's sky (the sky of a high sun)
the scene's sun lights: its share, times the daylight its height gives (all
of it from about 20 degrees up, none once it is about 6 degrees under the
horizon).
- `cloud_sky(o)` — the preset's horizon (`40u`), zenith (`44u`) or ground
(`48u`) colour, scaled by `cloud_sky_share()`.
- `cloud_ambient()` — the preset's ambient scaled by `cloud_sky_share()`.
The layer is lit by the scene's sun alone: a sunset lights the clouds low and
warm, a night leaves them dark, and with the sun at zero the layer is black.
The including shader binds `scene_light` (`@frame.light`) and the uniform `U`
with its `u_vec3` reader, and includes `@builtin::shaderModules.frame_light`.
·computeshader · born here
❒asset # cloud_noise
Procedural volumetric-cloud noise fill (Schneider/Hillaire style). A low-frequency
FBM gives the base blob silhouette, a high-frequency FBM erodes it near the surface
for the fluffy cumulus look, plus altitude shaping (round bottom, full middle, anvil
top). Writes the 3D cloud density texture.
Bindings (see bindings.yaml): `clouds` (storage3d rgba16f — the cloud volume), `U`
(read `array<f32>` uniforms).
Usage: dispatch by identity with `compute.dispatchEx("@builtin::systems.volumetrics.shaders.cloud_noise", ...)` (storage texture requires resource binding, not positional buffers) —
it resolves to the shader's stable guid and auto-compiles on first use (no setup).
·computeshader · born here
❒asset # cloud_raymarch
Volumetric-sky cloud raymarcher with Frostbite-style lighting: Wrenninge/Hillaire
multi-scatter approximation (3 octaves), a 5-sample cone-traced soft self-shadow,
and combined Beer-Lambert + Powder so cloud edges glow toward the sun. Reads the
cloud volume + occupancy textures and writes the lit raymarch result.
Bindings (see bindings.yaml): `clouds` (texture3d), `occupancy` (texture3d),
`cloud_smp` (sampler), `out_tex` (storage2d rgba16f), `U` (read `array<f32>`
uniforms).
Usage: dispatch by identity with `compute.dispatchEx("@builtin::systems.volumetrics.shaders.cloud_raymarch", ...)` (textures/sampler/storage texture require resource binding, not positional buffers) —
it resolves to the shader's stable guid and auto-compiles on first use (no setup).
# cloud_shell
The cloud layer as a shell around the planet: the band between two altitudes
over the ground, centred on a planet whose centre stands straight below the
camera being drawn. The layer reaches the horizon in every direction, recedes
into a thin band where it meets it, and curves away under a camera high above
it. The radius is the one `PhysicalAtmosphere` integrates over (6360 km times
its `worldUnitsPerKm`), so clouds and sky share one horizon.
- `cloud_shell_sphere(alt0, dir_y, radius, a)` — the nearer and farther
distances along a ray to the sphere of altitude `a`.
- `cloud_shell_span(alt0, dir_y, radius, base, top)` — the stretch of a ray
inside the layer, from a camera below, inside or above it.
- `cloud_shell_altitude(offset, alt0, radius)` — the altitude of a point given
as its offset from the camera.
Every sum is taken relative to the camera, which keeps an f32 precise at a
planet's radius.
# cloud_surface
Where a cloud ray meets the scene. Every cloud raymarcher includes it and ends
each ray at the surface the scene drew under its cell (`@scene.depth`), so a
cloud between the camera and the ground covers the ground and the part of the
layer behind a surface adds nothing.
- `cloud_cell_scene_pixel(cell, cells, scene)` names the scene pixel a layer
cell reads its surface from. `cloud_layer_composite` reads the same pixel for
the same cell when it lays the layer over the frame.
- `cloud_surface_distance(cell, cells, cam_pos, inv_view_proj)` is the world
distance to that surface, or the largest finite f32 over sky.
The including shader binds `scene_depth` as `kind: texture_depth`.
·computeshader · born here
❒asset # cloud_taa
Cloud TAA composite — temporal anti-aliasing for the raymarch output. Reprojects
last frame's blended output through the previous view-projection, color-clamps the
history to the current sample's neighborhood to suppress ghosting, and exponentially
blends the two. Writes both the next-frame history slot and the externally-sampled
`scene_volumetric_sky` texture the composite path reads.
Reprojection runs through the world point named by uniform `[37]`, the NDC z of the
range the cloud stands at along the view ray — `volumetricSky.reprojectionDepthNdc`
computes it. The weight the history carries falls to zero across the last
`REPROJECT_BORDER_TEXELS` of the reprojected frame, so a pixel whose history lies
off the previous frame reaches the raymarch's own output down a gradient rather
than across a line.
Bindings (see bindings.yaml — slot order must match the Luau dispatch): `cur_tex`
(texture2d), `hist_prev` (texture2d), `smp` (sampler), `out_hist` (storage2d
rgba16f), `out_scene` (storage2d rgba16f), `U` (read `array<f32>` uniforms).
Usage: dispatch by identity with `compute.dispatchEx("@builtin::systems.volumetrics.shaders.cloud_taa", ...)` (textures/sampler/storage textures require resource binding, not positional buffers) —
it resolves to the shader's stable guid and auto-compiles on first use (no setup).
·computeshader · born here
❒asset # cloud_weather
Fills the cloud layer's weather map: coverage, cloud type and density over
each place in the world, one texel per patch of ground, repeating every
`weatherExtent` world units.
Each texel starts from the sky's `coverage`, `cloudType` and density, varied
by a smooth field of weather over a few kilometres (`weatherVariation`), and
then takes each of the sky's `weatherRegions` in turn: inside a region's
radius its values hold, and across its falloff they blend into what surrounds
it, so a storm over one valley and clear sky over the next stand in one frame
with a gradual edge between them.
The map is a few hundred texels on a side, so a change to the weather fills it
again in a fraction of a millisecond; the raymarcher reads it every frame.
Bindings (see bindings.yaml): `out_map` (storage3d rgba16f, `width x 1 x
depth`) and `U` (the layout is stated at the top of `shader.wgsl`).
·computeshader · born here
❒asset # volume_draw
The march of a volume standing in the scene, run as a render-feature pass for
every view the frame draws. Each ray leaves the drawn camera (`@frame.camera`),
is clipped against the volume's box and ends at the scene's depth
(`@scene.depth`), so opaque geometry in front of the volume hides it and
geometry inside it cuts the march where it stands. The march itself is the
shared `volume_march` module's, the one `volume_raymarch` runs too.
Bindings (see bindings.yaml): `volume` and `occupancy` (texture3d), `volume_smp`
(sampler), `out_tex` (storage2d rgba16f, sized to the drawn view), `U` (one
`VolumeUniforms`), `frame_cam` (`@frame.camera`) and `scene_depth`
(`@scene.depth`).
The `volume` module enqueues it, with the composite that lays its output over
the frame, for every draw `Volume:draw` stands up.
# volume_march
The volume march `volume_raymarch` and `volume_draw` share: the
`VolumeUniforms` layout, the lookup of a point in a dense texture or a paged
volume's brick pool, the empty-space skip through the occupancy grid or page
table, and `volume_march(ro, dir, t_enter, t_exit, pix)`, which marches a ray
front to back and returns premultiplied colour in rgb and accumulated alpha in
a. The last step ends at `t_exit`, so a march cut short by a surface stops
where the surface stands.
The including shader binds `volume` and `occupancy` (texture3d), `volume_smp`
(sampler) and `U` (one `VolumeUniforms`).
·computeshader · born here
❒asset # volume_pack
Fills the brick pool from the volume `volume_pages` has just paged.
One invocation per pool voxel. The pool is a grid of blocks, one block per
slot; a block holds a brick plus a one-voxel apron taken from the neighbouring
bricks, so a trilinear sample inside a brick reads what the dense volume would
have given it rather than whatever brick the pool stores next door.
## Bindings
| # | name | what |
|---|---|---|
| 0 | `source` | the dense volume being paged (sampled 3D texture) |
| 1 | `atlas` | the brick pool (`rgba16f` storage) |
| 2 | `page_slots` | four words per slot, written by `volume_pages` |
| 3 | `K` | `PackParams` — volume dimensions and brick edge |
## Why the pool is always `rgba16f`
A pool is written as a storage texture and sampled with filtering. `rgba16f` is
the format that is both: the one-channel formats cannot be written as storage
textures, and `r32f` cannot be filtered without a device feature the engine
does not require. So a scalar volume's density rides in the pool's red channel
— which is where the raymarcher reads density from in density mode — and pays
`rgba16f` per resident voxel. `Volume:sparseStats()` reports the dense and
resident sizes side by side rather than assuming paging is the smaller of the
two.
The pass writes every voxel of the pool, including blocks whose slot was never
handed out: those hold whatever brick their stale slot entry names, and the
page table never points at them.
·computeshader · born here
❒asset # volume_pages
Decides which bricks of a volume are worth storing, and where each one lives.
One invocation per brick. It scans the brick's voxels in the source volume,
and a brick holding anything over `threshold` claims a slot from an atomic
counter. The slot number lands in the page table (`slot + 1`, so 0 keeps
meaning "empty"), and the brick's grid coordinates land in the slot list so
`volume_pack` knows what to copy into that slot.
Nothing is read back to the CPU and no brick waits on another, so the pass can
run every frame — which is what makes the page table usable as the acceleration
structure for a volume whose contents change while it renders.
## Bindings
| # | name | what |
|---|---|---|
| 0 | `source` | the dense volume being paged (sampled 3D texture) |
| 1 | `pages` | page table, one texel per brick (`rgba16f` storage) |
| 2 | `page_alloc` | `[0]` slots handed out, `[1]` bricks that found the pool full |
| 3 | `page_slots` | four words per slot: the brick's x, y, z, and 1 |
| 4 | `P` | `PageParams` — volume dimensions, brick edge, threshold, channel, capacity |
`page_alloc` must be zeroed before each run; the counter is what allocates, so
a stale count hands out slots past the pool.
## The page value
A resident brick's page value is `slot + 1`, split into two digits base 1024
across the texel's red and green channels. The page table is `rgba16f` because
that is the format that is both storage-writable and filterable — the
raymarcher binds it where a sampled 3D texture is expected — and a half float
only carries integers exactly up to 2048, which one digit stays under. A brick
holding nothing writes zero in both channels, so "is anything here" is the sum
against zero, the same test the older single-channel occupancy grid answers.
## Overflow
A brick that arrives after the pool is full is counted in `page_alloc[1]` and
written as empty. The volume renders without it rather than sharing a slot.
`page_alloc[0]` keeps counting past the capacity, so a caller that reads it
back learns the capacity the volume actually needs.
·computeshader · born here
❒asset # volume_raymarch
Generic volume raymarcher. One invocation per output pixel: builds a world-space
ray from the camera inverse view-projection, clips against the volume AABB, and
marches front-to-back, using the occupancy grid to skip empty bricks. Output is
RGBA16F (premultiplied RGB, accumulated alpha) for the caller to composite.
A paged volume marches through the same shader: `volume` is then the brick pool
and `occupancy` the page table, whose texel per brick carries the pool slot that
brick lives in (0 for a brick holding nothing, which is what the empty-space
skip already reads it as). `VolumeUniforms.paged` carries the flag and the
volume's own dimensions, which the pool no longer describes.
Both the skip and the pool lookup find a point's brick by the voxel it lands on
divided by the brick edge — the way the page table and the occupancy grid were
written. A volume that is not a whole number of bricks across has a grid wider
than `dims / brick`, so dividing the normalized coordinate by the grid instead
would name a different brick for the same point. When the dimensions are unknown
(a wrapper was never told them) the grid times the brick edge stands in for them.
Bindings (see bindings.yaml): `volume` (texture3d), `occupancy` (texture3d),
`volume_smp` (sampler), `out_tex` (storage2d rgba16f), `U` (read buffer, a single
`VolumeUniforms` struct).
Usage: dispatch by identity with `compute.dispatchEx("@builtin::systems.volumetrics.shaders.volume_raymarch", ...)` (textures/samplers/storage texture require resource binding, not positional buffers) —
it resolves to the shader's stable guid and auto-compiles on first use (no setup).
·computeshader · born here
❒asset # vol_composite
Composites the scattered light over the scene, depth-aware so geometry occludes it.
## Includes
- `scattering_common`
## Bindings
| name | kind |
|------|------|
| `scene_color` | `texture2d` |
| `scene_depth` | `texture_depth` |
| `scatter_map` | `texture2d` |
| `vol_params` | `buffer` |
| `vol_out` | `storage2d (rgba16f)` |
·computeshader · born here
❒asset # vol_lights
Marches the view rays `vol_scatter` marches for the scene's lights that stand
somewhere (point, spot, rect), accumulating the light they scatter toward the
camera through the same medium and at the same samples.
A light lights nothing past its radius, so the work follows the light that
reaches the medium:
- each 8x8 tile of rays gathers the lights whose reach meets the cone its rays
fill, once for the whole tile;
- each ray keeps the tile's lights whose reach it crosses, and marches only the
stretch between the first place one of them reaches and the last, starting
from the transmittance the medium holds there (the density falls off
exponentially with altitude, so the medium crossed before a sample is a
geometric series in closed form);
- each sample takes a light only where its radius reaches it.
A ray no light reaches marches nothing. Consecutive renders of a view share the
samples the way `vol_scatter`'s do.
## Includes
- `scattering_common`
## Bindings
| name | kind |
|------|------|
| `scene_depth` | `texture_depth` |
| `frame_cam` | `buffer` (`@frame.camera`) |
| `lights` | `buffer` (`@scene.lights`) |
| `vol_params` | `buffer` |
| `lights_prev` | `texture2d` (the previous render's half) |
| `length_prev` | `texture2d` (how long each of the previous render's rays was, written by `vol_scatter`) |
| `lights_state` | `buffer` (the history target's state) |
| `history_out` | `storage2d (rgba16f)` |
| `lights_out` | `storage2d (rgba16f)` |
·computeshader · born here
❒asset # vol_scatter
Accumulates in-scattered light through the volume, one froxel at a time.
## Includes
- `scattering_common`
## Bindings
| name | kind |
|------|------|
| `scene_depth` | `texture_depth` |
| `frame_cam` | `buffer` |
| `lights` | `buffer` |
| `vol_params` | `buffer` |
| `scatter_out` | `storage2d (rgba16f)` |
·computeshader · born here
❒asset # volume
High-level Luau API for 3D textures and volumetric rendering. Composes
the engine's generic `compute.*` primitives into volume-specific
helpers — procedural builders (`sphere`, `box`, `noise`), a sparse
NanoVDB-style occupancy grid for empty-space skipping, volumes standing in
the scene through any entity's transform (`draw`), and a one-call raymarcher
into a 2D target of the caller's own (`render`).
Pairs with the `Volume` component which attaches a built (or imported)
texture to an entity.
## Exports
- `M.create({name, width, height, depth, format?, storage?}) -> Volume` — allocate a fresh, zero-filled 3D texture and return a Volume wrapper.
- `M.wrap({name, format, occupancyName?, occupancyBrick?}) -> Volume` — wrap an existing named texture without recreating it (used by the .zvol viewer).
- `M.get(name) -> Volume?` — the live volume built under that texture name, with its dimensions, channel count, occupancy grid and brick pool.
- `M.names() -> {string}` — every name `M.get` answers to, sorted.
- `M.register(volume) -> Volume` — publish a wrapped volume under its own texture name.
- `M.unregister(name) -> Volume?` — stop answering for a name and hand back the volume that held it, leaving its GPU resources alone.
- `M.releaseTarget(name) -> boolean` — destroy a render target this module built for `render` and forget its size.
- `M.sphere(opts) -> Volume` — procedural Volume filled with a soft sphere SDF.
- `M.box(opts) -> Volume` — procedural Volume filled with a soft box SDF.
- `M.noise(opts) -> Volume` — procedural Volume filled with FBM noise.
- `M.raymarchShaderIdentity() -> string` — absolute identity of the shared raymarch shader.
- `M.compositeShaderSource() -> string` — WGSL source for the post-process composite blending `scene_volume_rt` over the scene.
- `M.FORMATS` — table of canonical format strings (`R8`, `R16F`, `R32F`, `RGBA8`, `RGBA16F`, `RGBA32F`).
- `volume:destroy()` — release the GPU texture + occupancy.
- `volume:writeBytes(bytes) / :writeFloats(floats)` — upload payload to the 3D texture (matches the texture's format).
- `volume:fill(fn)` — CPU procedural fill via `fn(x,y,z) -> color`.
- `volume:readback() -> bytes` — pull the texture's current contents back to Luau.
- `volume:buildOccupancy({brickSize, sampler?})` — build an R8 occupancy companion for empty-space skipping.
- `volume:buildSparse({brickSize?, threshold?, headroom?, capacity?, mode?})` — page the volume into bricks, keeping only the ones holding something. Yields while the brick count reads back — twice unless `capacity` says how many slots to take.
- `volume:refreshSparse()` — re-page from the volume's current contents; two dispatches and no wait.
- `volume:releaseDense()` — free the dense texture and render from the brick pool alone.
- `volume:releaseSparse()` — free the brick pool and page table and go back to rendering the dense texture.
- `volume:readSparseCounts()` — `{ bricks, wanted, overflow, capacity }` off the GPU; yields.
- `volume:sparseStats()` — byte accounting: `denseBytes`, `poolBytes`, `pageBytes`, `residentBytes`, `ratio`.
- `volume:fillCompute(shaderName, opts)` — drive a custom fill shader against this volume.
- `volume:render(opts)` — dispatch the shared compute raymarcher into a 2D storage target, using `opts.entity` for AABB. A paged volume renders through its pool with no change at the call site.
- `volume:draw(key, opts)` — stand the volume in the scene under `key`, through `opts.entity`'s AABB: the `volume` render feature marches it for every view the frame draws, against that view's camera (`@frame.camera`) and depth (`@scene.depth`), at the view's resolution, and lays it over the frame in the `medium` stage. Call it again each frame to keep the box and settings current. The `Volume` and `VolumeSequence` components draw through it.
- `M.withdraw(key) -> boolean` — take a draw down, releasing its uniforms; the last one releases the draws' target and takes the render feature down.
- `M.draws() -> { {key, volume, target} }` — the draws standing, sorted by key; `target` is the one screen-sized target every draw marches into in turn.
- `M.drawKey(prefix, id?) -> string` — a key no other draw stands under.
- `M.enqueueDraws(ctx)` — the render feature's `render`: each draw's march and composite, both stating the centre of the draw's box as their `sortPoint`, so every view runs the draws farthest from its own camera first.
## Usage
```luau
local Volume = require("@builtin::systems.volumetrics.volume")
-- Build a procedural noise cloud + occupancy.
local cloud = Volume.noise({
name = "cloud", size = 64, scale = 4, octaves = 4, threshold = 0.55,
})
cloud:buildOccupancy({ brickSize = 8 })
-- Stand it in the scene through an entity's box: every view the frame draws
-- marches it against its own camera and depth, so what stands in front of it
-- hides it. Call it each frame to keep the box current.
local key = cloud:draw(Volume.drawKey("cloud"), {
entity = entity(id),
density = 8.0, absorption = 1.2, emission = 0.9,
color = { 1.0, 0.9, 0.7 },
})
Volume.withdraw(key) -- takes it down
-- Or raymarch it into a 2D target of your own (here scene_volume_rt) for a
-- pass of yours to read. The target is the size of the view the frame draws
-- unless targetWidth / targetHeight name one, and the rays leave from the
-- drawn camera's world pose unless `camera` names another.
cloud:render({
entity = entity(id),
target = "scene_volume_rt",
density = 8.0, absorption = 1.2, emission = 0.9,
color = { 1.0, 0.9, 0.7 },
maxSteps = 256, mode = "rgba",
})
```
The `Volume.component` is the per-entity wrapper around this module — it
resolves the name it carries through `Volume.get` and stands it in the scene
with `volume:draw` from its `update` and `editorUpdate` hooks while it is
enabled.
## Addressing a volume by name
Every volume this module builds answers to its texture name, so anything
holding only the name — an entity's `Volume` component, a second script, a
tool — reaches the volume itself:
```luau
local cloud = Volume.noise({ name = "cloud", size = 128 })
cloud:buildSparse({ brickSize = 8 })
cloud:releaseDense()
-- somewhere else entirely
Volume.get("cloud"):render({ entity = entity.find("cloud_host") })
```
What the name alone cannot express is what makes this matter: the voxel
dimensions, which channel holds density, and whether the volume is paged into
a brick pool. A holder that reconstructs a wrapper from the name gets a dense
volume that the paging may already have released.
One volume owns a name at a time: the 3D texture, the page table and the brick
pool all address it, so `create` over a name a live volume holds releases that
volume first and says so in the log. `destroy` clears the entry. A wrapper
around a texture another system owns is published with `Volume.register` and
dropped with `Volume.unregister`, which hands the volume back so it can still
be destroyed. The names live where this module is loaded — one set per Luau
VM, alongside the raymarch target registry.
`render` builds its `target` on the first call that names one and keeps its
size, so repeated renders reuse it; `Volume.releaseTarget(name)` destroys that
target and forgets the size, and the next render builds it again.
## Paging a volume into bricks
A dense volume costs its bounding box. `buildSparse` splits it into bricks,
keeps only the ones holding anything over `threshold`, and stores those in a
brick pool; a page table one texel per brick says which slot each resident
brick took, and 0 says the brick holds nothing. That page table is also the
grid the raymarcher already skips empty space with, so paging and empty-space
skipping are the same structure.
```luau
local cloud = Volume.noise({ name = "cloud", size = 128, threshold = 0.6 })
local stats = cloud:buildSparse({ brickSize = 8, threshold = 0.01 })
print(stats.bricks, "of", stats.grid[1] * stats.grid[2] * stats.grid[3], "bricks")
print(stats.poolBytes, "vs dense", stats.denseBytes)
cloud:releaseDense() -- the pool is now the only copy
cloud:render({ entity = entity.find("cloud_host") })
```
Both passes run on the GPU with no readback between them, so a volume a
compute shader rewrites keeps a matching page table for the cost of two
dispatches:
```luau
cloud:fillCompute(myFillShader, { extraResources = { { kind = "buffer", name = fillU } } })
cloud:refreshSparse()
```
The pool is fixed at the size the build measured, so a volume that grows past
it loses the surplus bricks. `refreshSparse` asks the GPU for the counts
without waiting on them and folds them in on a later call, so `sparseStats()`
reports the overflow — and the log carries a warning naming the capacity to
page at — a frame or two after the refresh that caused it. `buildSparse`'s
`headroom` buys the slots up front for a volume that is expected to grow.
What it costs:
- A block in the pool is the brick plus a one-voxel apron on every side, so a
resident brick costs `(brick + 2)³` voxels. At `brickSize = 8` that is 1.95x
per resident brick, at 16 it is 1.42x. The apron is what makes a trilinear
sample inside a brick read exactly what the dense volume would have given
it.
- A pool is always `rgba16f`: it has to be writable as a storage texture and
sampled with filtering, and that is the format that is both. A scalar volume
therefore spends more per resident voxel than it did dense (its density rides
in the pool's red channel), so `sparseStats()` reports `denseBytes` and
`residentBytes` side by side rather than assuming paging is the smaller of
the two.
- `refreshSparse` re-pages from the dense volume, so a volume that will keep
changing keeps its dense copy; `releaseDense` is for one that is finished.
- Classification reads one channel: alpha for a four-channel volume, red for a
scalar one. A four-channel volume that carries density in red — the one
`render`'s `mode = "density"` marches — has to say so, with the same word:
`buildSparse({ mode = "density" })`. A `render` that names no `mode` marches
a paged volume from the channel its pool was filled from, so the two agree
without the caller repeating the choice.
## Notes
- Volumes are GPU-owned; the Luau wrapper just holds the named handle.
`volume:destroy()` releases both the texture and any occupancy
companion.
- `render` writes one named target, and a second `render` into the same
target replaces the first one's picture. `draw` marches every draw into one
screen-sized `rgba16f` target in turn, each composited over the frame
before the next draw's march, so any number of draws costs one view-sized
image and the frame lays them over each other.
- Occupancy grids use a brick size (default 8) — smaller = more
precise skipping at the cost of grid memory.
- The `vdb_to_zvol.importer` in this package produces dense voxel
buffers consumable by `compute.writeFloatsTexture3D`, which can be
wrapped via `Volume.wrap` (see the `zvol_viewer.scene/` demo for the
full path).
·renderfeature · born here
❒asset # volume (render feature)
Runs the passes of every volume standing in the scene (`Volume:draw`, which the
`Volume` and `VolumeSequence` components call each frame): for each view the
frame draws, a `volume_draw` march against that view's camera and depth into a
screen-sized target, then `volume_draw_composite` blending it over the frame,
draw after draw, the draws furthest from the active camera first. Every draw
marches into the same target, each one composited before the next marches. It runs in the
`medium` stage, after the cloud layer's surfaces and ahead of the aerial
perspective and the height fog.
The `volume` module brings it up with the first draw and takes it down with the
last `Volume.withdraw`, so a scene with no volume standing runs none of its
passes. `Volume.draws()` lists what stands.
# volumeDemos
Shared orchestration backend for the `volumeDemos.package` showcase
scenes. Owns the per-demo resource pack (3D texture, 2D render target,
two uniform buffers) and the auto-registered composite, exposing a
small public surface the demo scenes drive once per frame.
## Exports
- `M.spawn({name, size, fillShader, fillUniformBytes}) -> ()` — register a new demo pipeline. Creates the 3D volume, the 2D storage target, registers the per-demo fill shader, ensures the shared raymarcher is registered, and auto-installs the depth-aware composite.
- `M.destroy(name) -> ()` — release everything `spawn` created (texture + render target + buffers + composite registration).
- `M.dispatchFill(name, fillUniforms) -> ()` — pack `fillUniforms` (Lua array of f32) into the demo's fill UBO and dispatch the fill shader against the volume.
- `M.dispatchFrame(name, {camera, aabbMin, aabbMax, width, height, stepSize, maxSteps, alphaCutoff, densityGain, emissionGain}) -> ()` — pack camera + raymarch params into the shared 40-float UBO and dispatch the raymarcher into the demo's render target.
- `M.NAMES(name) -> {volume, rt, composite}` — engine-side resource names for the demo (used by the `.zvol` viewer to bypass the helpers and upload voxels via `compute.writeFloatsTexture3D` directly).
## Usage
```luau
-- From a demo scene at <pkg>/demo/<name>.scene/entrypoint.luau,
-- `...` climbs to the package root, then resolves volumeDemos.module:
local V = require("@builtin::systems.volumetrics.volumeDemos")
-- onLoad: spin up the pipeline.
V.spawn({
name = "smoke_plume",
size = { 96, 192, 96 },
fillShader = SMOKE_FBM_WGSL,
fillUniformBytes = 64,
})
-- update(dt): repaint the volume + raymarch into the RT. The rays leave
-- from the drawn camera's world pose and the RT is the size of the view the
-- frame draws; `camera`, `width` and `height` override them.
V.dispatchFill("smoke_plume", { elapsed, density_amp, spread, ... })
V.dispatchFrame("smoke_plume", {
aabbMin = { -40, 0, -40 },
aabbMax = { 40, 160, 40 },
stepSize = 0.9, maxSteps = 240,
densityGain = 2.5, emissionGain = 1.0, alphaCutoff = 0.995,
})
-- onUnload: free GPU resources.
V.destroy("smoke_plume")
```
## Notes
- `dispatchFrame` packs 40 f32s into the raymarch UBO:
`[0..16)` inv_view_proj (mat4 row-major), `[16..19)` aabb_min,
`[19..22)` aabb_max, `[22..23)` step_size, `[23..24)` max_steps,
`[24..25)` alpha_cutoff, `[25..26)` density_gain, `[26..30)`
target_width/height + inv reciprocals, `[30..31)` emission_gain,
`[31..40)` padding.
- `lastFrame(name)` reports the target size and the eye the last
`dispatchFrame` of that demo marched with.
- Pipeline state lives in module-locals keyed by `name` — the same
module instance can host many demos in parallel, but two scenes
must not pick the same `name`.
- Each demo scene supplies its own fill shader; the raymarcher is
shared (one shader name, one compiled pipeline). Replacing
`fillShader` between frames is supported; replacing the raymarcher
isn't (use the volumetrics package for that use case).
# volumeSequence
Playback for a run of `.zvol` frames, through a ring of resident volumes.
A sequence names its frames as VFS paths in playback order. It allocates
`resident` 3D textures — one frame each — and nothing else: the frames the
playhead is about to reach are read off the VFS on their own tasks and
uploaded into whichever ring slot the playhead has travelled furthest past.
So a 240-frame run and a 4-frame run cost the same on the GPU, and what a
sequence costs is decided when it is opened rather than by how long it is.
```luau
local Seq = require("@builtin::systems.volumetrics.volumeSequence")
local frames = {}
for i = 0, 239 do
frames[#frames + 1] = string.format("/source/sim/plume_%04d.zvol", i)
end
local seq = Seq.open({ name = "plume", frames = frames, resident = 3, fps = 24 })
local s = seq:stats()
print(s.residentBytes, s.allBytes) --> 3145728 251658240
```
Drive it from a component, which is also what makes it visible:
```luau
entity(id).component.add("VolumeSequence", { sequenceName = "plume", density = 6.0 })
```
or by hand, if the caller already has a tick of its own:
```luau
seq:tick(dt)
local frame = seq:current()
if frame then
frame:render({ entity = entity(id), density = 6.0 })
end
```
The playhead advances once per engine frame however many callers tick the
sequence — a component and a script, or two entities naming one run, share
one playhead rather than each moving it. Every call still promotes the frame
that has landed and starts the reads ahead of it.
## Residency
Every frame of a run has the dimensions frame 1 declares, so one ring serves
the whole run. `stats()` reports both what the ring holds (`residentBytes`)
and what holding every frame at once would cost (`allBytes`); `residency()`
says which frame each slot holds right now.
The ring needs at least two slots for a multi-frame run — one holds the
picture on screen while the other takes the read — and `open` raises the
count to two if it was asked for less. `prefetch` says how many frames ahead
of the playhead reads are started, and defaults to every slot the ring has
spare — a slot left empty is a frame that gets waited on later. It is bounded
by those same slots, so asking for more than fits reads as far ahead as it can.
## Keeping up
A tick that wants a frame no slot holds yet keeps showing the frame it had
and counts a `stall`. Playback is therefore never blank and never blocks, and
`stats().stalls` is the number that says whether the ring and the prefetch
distance are big enough for the rate: a run whose reads keep up shows a stall
count that stops rising once the ring has filled.
`errors` counts frames that failed to read or whose header disagreed with the
ring. Each one is counted and logged once, with the path and what was wrong
with it, and the run steps over it from then on rather than re-reading it
every tick — so `errors` answers how many frames of the run are broken, and a
mistyped path costs one line in the log rather than one per frame.
The rate and the playhead are the sequence's, not a caller's: `setFps` keeps
the frame the playhead stands on and the fraction of the way through it, and
`seek` lands on exactly the frame asked for.
# volumetricLighting
The settings behind the `VolumetricLighting` component, and the way to drive the
scene's participating medium from a script — fog that rolls in over a cutscene, a
quality slider that drops the step count, a room that fills with smoke.
```lua
local volumetricLighting = require("@builtin::systems.volumetrics.volumetricLighting")
volumetricLighting.set({ density = 0.06, anisotropy = 0.7 })
volumetricLighting.get() -- a copy of the settings in force
volumetricLighting.active() -- whether the march is running
volumetricLighting.clear() -- empty the air, keep the settings
```
`set` takes any subset of the fields; whatever is omitted keeps its current
value. A `density` of 0 releases the render feature rather than marching a medium
that scatters nothing, and `clear` is the named way to say the same thing.
`sunDirection` tracks the scene's sun on its own. Pin it through `set` when a
scene wants the medium lit from somewhere else.
The module packs the settings into the `vol_params` buffer the passes read, so a
change lands on the next frame without recompiling anything.
## Cost
The march is the expensive part, and its cost is `steps` × (`shadowSteps` + the
number of live scene lights) per marched pixel. Those are the two knobs to reach
for on a budget: `steps` controls how cleanly a beam's edge resolves,
and `shadowSteps` controls whether the sun's contribution is shadowed at all.
Setting `shadowSteps` to 0 removes the per-sample visibility work entirely, which
is the single largest saving available — at the cost of the shafts, since the
medium is then lit evenly wherever it reaches.
# volumetricSky
Orchestration backend for the `VolumetricSky.component`. Owns the
GPU resources the cloud layer needs (cloud volume, raymarch render
target, the per-view accumulation history, post-process composite) and
exposes a small public surface the component drives every frame.
## Exports
- `M.spawn(opts?) -> id` — spawn the singleton sky entity, or configure the one already standing, and return its id. Every weather parameter (`coverage`, `sunColor`, `sunIntensity`, `windSpeed`, …) is settable at the top level or inside a `preset` sub-table; every `VolumetricSky` component field (`shaderVariant`, `cloudSize`, `taaBlendAlpha`, …) by its own name; `name` names the entity. Parameters left out keep their current values. An option that names neither raises, listing both sets, and leaves no entity behind. A weather parameter takes the shape its default carries — a number, or an array of that many numbers — and a value of another shape raises naming the parameter.
- `M.configure(opts) -> boolean` — apply those same weather parameters and component fields to the sky already standing. Returns `false` when none has been spawned.
- `M.defaultPreset() -> table` — a fresh copy of the weather configuration a sky spawned with no options carries. The copy is the caller's to edit.
- `M.destroy() -> ()` — release every resource `spawn` created.
- `M.fillClouds(noiseParams) -> boolean`: bake the cloud volume with the active `cloud_noise_*` shader when what it holds is not what `noiseParams` describe, and return whether this call baked. A change to a shaping parameter, the colour, the seed, the size, the variant or the render device bakes at once, and a write to the noise shader's `shader.wgsl` or `bindings.yaml` bakes once the program it compiles is resident; a change to the wind alone bakes at most `noiseParams.noiseRegenRate` times per second (default `M.DEFAULT_NOISE_REGEN_RATE`, `0` = every call the wind moved) on `noiseParams.clock` (default `getTime()`). `noiseParams` is the flat table produced by `VolumetricSky.component`'s `snapshotNoiseParams()`.
- `M.volumeBakes() -> number`: how many times the cloud volume has been baked since the module loaded.
- `M.dispatchRaymarch(renderParams, viewport) -> ()` — pack the frame the layer's passes draw (the raymarch's and the accumulation's uniforms, the layer's targets), which `M.enqueueCloudPasses` hands the renderer for every view it draws. `renderParams` is the flat table from `snapshotRenderParams()`.
- `M.find() -> id?` — return the id of the entity carrying the scene's `VolumetricSky`, whatever the entity is named, or `nil` when no entity carries one.
- `M.despawn() -> ()` — despawn the entity `M.find` names. Its component lets go of the cloud layer as it goes, and the last sky to let go releases the layer's GPU resources.
- `M.setCoverage(c) / M.setDensity(g) / M.setSun(dir, color, intensity?) / M.setWind(v)` — convenience setters that route through the active component's `public` fields. The clouds are lit by the scene's sun, so `setSun`'s direction moves the scene's sun; its colour and intensity are the preset's `sunColor` and `sunIntensity`, how brightly and in what tint that sun lights the clouds.
- `M.enqueueCloudPasses(ctx) -> ()` — enqueue the layer's passes for the frame; the renderer runs them for every view it draws. Every pass declares `atmospherics`, so a camera stating an isolated environment draws no clouds.
## Usage
```luau
-- The component drives this module automatically. Direct M.* use is
-- rare; the canonical entry point is attaching VolumetricSky to an
-- entity (or loading a preset and passing it to component.add):
local sky = entity.spawn("sky")
sky.component.add("VolumetricSky", {})
-- Driving the layer by hand instead, a frame at a time. Each dispatch
-- creates the resources it needs at the size its own arguments name —
-- the cloud volume from `noiseParams.cloudSize / cloudHeight`, the
-- render target and composite from the viewport:
local Sky = require("@builtin::systems.volumetrics.volumetricSky")
Sky.fillClouds(noiseParams)
Sky.dispatchRaymarch(renderParams, { width = 1280, height = 720 })
```
## Notes
- `shaderVariant` selects which compute shader pair (`cloud_noise_v3 +
cloud_raymarch_v3` / `cloud_noise + cloud_raymarch_v4` /
`cloud_noise_v5 + cloud_raymarch_v5`). The module resolves the
variant strings to absolute identities — relative paths don't work
from a module body (the chunkname retains an `.init` segment that
throws off the rsplit-to-parent step in `resolve_relative_dot`).
- The cloud volume is RGBA16F — 256×128×256 ≈ 32 MiB VRAM. Drop to
192/96 via `cloudSize` / `cloudHeight` if tight.
- The accumulation is a history target (`renderer.texture.create` with
`history = true`): each view the frame draws (the viewport, every
camera rendering into a texture, every capture) keeps its own pair of
RGBA16F images at its own size scaled by `renderScale`, and the pass
reprojects them through that view's own camera (`@frame.camera`). A
view's first render, and its first after a cut or a change of size,
starts from its own raymarch. Set `taaBlendAlpha = 1.0` to disable
while still going through the same code path (useful for
benchmarking).
- All public setters write through to `VolumetricSky.component`'s
`public` fields, which means they replicate as Sync if the
component is sync-enabled. Tweaks survive scene reloads as long as
the same entity is alive.
- `SkyPreset` and its defaults are declared here, and the component
declares its `preset` field from them. `M.spawn` / `M.configure` read
that same key set to tell a weather parameter from a component field, so
a parameter added to the preset reaches the schema and the option routing
in one edit.
·renderfeature · born here
❒asset # volumetricSky
The cloud layer's render passes.
The layer is raymarched for the camera being drawn, each ray ending at the
surface the opaque scene drew along it (`@scene.depth`), copied into the target
the composite reads, temporally accumulated where there is a previous frame of
that view to accumulate against, and laid over the frame in two passes:
- over the pixels the opaque scene left as sky, once the opaque scene is lit
(`afterOpaqueLit`) and ahead of the transparent phase, so a particle, a glass
pane or any see-through surface that writes no depth stands in front of the
clouds behind it;
- over the pixels a surface stands on, the water a transparent draw wrote depth
for included, at the head of the `medium` stage, ahead of the air (aerial
perspective, height fog, volumetric light): `cloud_layer_surfaces` picks the
layer's cells a surface stands on out by the frame's own depth, and the
composite lays them.
A cloud in front of a surface covers it at any distance, so from above the layer
the clouds cover the ground and the sea below them, and a surface in front of a
cloud keeps it out.
Every pass but the accumulation runs for each view the frame draws, an
environment cube's six faces included — which is what puts the clouds into
reflections. The accumulation blends against the previous frame of the same
view, and a cube face is rendered once with no previous frame, so it declares
`environmentCapture = false` and the copy before it is what those faces read.
`VolumetricSky` creates this feature; it is not meant to be created by hand.
# Package (asset type)
A package is an asset — a `<Name>.package/` folder that bundles
components, modules, scenes, presets, tools, and any other typed
sub-assets under one identity, installed into a world as one unit.
Packages are how authoring sets get distributed across worlds.
A **library** is the addressable root scope content resolves under
(`@builtin`, `@<name>`) — a whole world mounted into this one under a
namespace, via `zeromind.installLib` / `world.installLibrary`. A package is
an asset that lives inside such a root, and one library holds as many
packages as its author put there. A package is installed by guid the
way every asset is (`zeromind.installAsset`).
## When to use one
- You're authoring a coherent feature suite (character controller
stack, voxel engine, UI kit, animation library) and want to ship
it as one install target.
- You want a stable identity worlds can install and resolve sub-assets
against (`@<lib>::pkg.sub_module`).
- You want versioning + a per-package metadata layer that travels with
the contents.
If you're authoring inside a single world and don't need a separate
install lifecycle, you don't need a package — drop your `.component`
/ `.module` / etc. directly in `/zero/source/`. Packages are for
cross-world distribution.
## Where it lives
- Source: `/zero/source/.../<Name>.package/` (or, for legacy
packages, a folder containing `package.yaml` at its root).
- Identity: `<Name>` (the `.package` suffix collapses in identity —
mirrors `.module`). A file at `<Name>.package/<sub>/init.luau`
resolves under the same identity it would at `<Name>/<sub>/init.luau`.
- Folder shape (container-style — open child set):
- `package.yaml`: metadata (name, version, description) and the
packages it depends on (`dependencies`). **Required.**
- `README.md` — instance documentation. **Required.**
- `.metadata` — agent-editable tags + free-form fields. **Required.**
- Sub-asset folders: any combination of `.component/`,
`.module/`, `.scene/`, `.preset/`, `.tool/`, `.toolbox/`,
`.material/`, `.shader/`, etc.
The validator permits unlisted children (`allow_unlisted: true`) by
design — packages are open containers.
## How to create one
```luau
asset.create("package", "<Name>")
-- Creates: /zero/source/<Name>.package/
-- package.yaml (metadata scaffold)
-- README.md (instance README template)
-- `folder` places it in a subfolder of /source instead of the root:
asset.create("package", "<Name>", { folder = "systems" })
```
Then scaffold sub-assets inside it:
```luau
local pkg = asset.resolve("<Name>.package")
asset.create("component", "Spinner", { into = pkg })
asset.create("module", "util", { into = pkg })
```
## `package.yaml`
```yaml
name: inkBlocks # optional; the folder stem when absent
version: "1.0.3"
description: "Ink and paper style blocks"
dependencies:
- { name: starterBlocks, version: "1.0.8" }
- styleKit # a bare name states no version
```
`dependencies` lists the packages this package needs. Each entry's `name` is
a reference the package records, the same kind of reference a `require` or an
asset name in a data file makes:
- **It resolves in the author's world.** Install the dependency here first
(`zeromind.installAsset`); the entry then names the copy this world holds.
A push refuses a package whose dependency resolves to nothing, naming it.
- **An install brings it along.** Installing the package installs every
dependency it lists, at the version this world holds when the package is
pushed, under `/source/deps/<owner world>/`, deduplicated against what the
installing world already holds. `zeromind.preview` lists each one before
anything is written, and the install's `deps` lists what it brought.
Uninstalling the package leaves a dependency that another installed
package still uses.
- **`version` is checked, not chosen.** A stated `version` has to equal the
`version` the dependency's own `package.yaml` states in this world;
`asset.validate` (and so the push) refuses the package naming both when
they differ. To depend on another version, install that version here. An
install lands one release of each dependency its closure names, so in a
world the package is installed into, itself or as a dependency of the
package installed, it runs the release the install placed, and
`asset.validate` names a stated `version` that release does not state as
a warning.
## How it operates
1. **Registration.** Writing `package.yaml` indexes the package with
the package registry.
2. **Install.** A package is read before it is installed: `zm ls-tree
@<guid>` in the shell lists what it contains, and `zm show
@<guid>:<path>` and `zm grep <pattern> @<guid>` read it, so candidates
are compared by what they do. The one that fits is installed by guid,
the way every asset is: `zeromind_install` over the engine's MCP, or
`tools.use("zeromind", "installAsset", <guid>)` inside the engine. The
install writes the package's files (and the deps its `.refs`
record, the packages its `package.yaml` lists under `dependencies`
included) into this world's source, so its sub-assets resolve here.
`tools.use("zeromind", "preview", <guid>)` reports what an install would
write before it writes anything.
3. **Sub-asset resolution.** Because `.package` collapses in
identity, sub-asset paths work whether the package folder is
suffixed (`<Name>.package/<sub>`) or not (`<Name>/<sub>`).
4. **Updates.** `tools.use("zeromind", "updates")` lists installed content
with upstream changes available; re-running the install pulls them.
5. **Metadata.** `package.yaml::name` overrides the folder stem if
present (rare); `version` + `description` are surfaced in the
package index.
6. **Hot reload.** Edits to sub-assets hot-reload as normal; edits to
`package.yaml` reload package metadata.
## Discovery
- `asset.list("package")` — every registered package.
- `asset.inspect("<name>")` — sub-asset catalog, source, this type
README.
- `ls /zero/source/<Name>.package` lists the files the folder holds.
- `library.list()` — the library assets registered in this world,
including the ones packages under an installed library contribute.
## Authoring conventions
- Name packages by their feature (`voxels`, `cameraRigs`,
`dialogSystem`), not by their owner — the host library is the
`@<lib>::` scope prefix.
- Cluster cohesive sub-assets together. A "character controller"
package should ship the controller component, its preset configs,
its supporting modules, and a demo scene — not just the component.
- Document the package's surface in `README.md` — what install
installs, what each sub-asset does, how they relate. Agents reading
`cat /zero/source/<Name>.package/README.md` get the full picture in one shot.
- Version conservatively — breaking a package means breaking every
world that installed it. Use semantic version bumps.
## Common pitfalls
- **Missing `package.yaml`.** Without it the folder isn't recognized
as a package even if it has a `.package/` suffix.
- **A dependency named only by a string the code builds.** A package
whose files reach another package only through a name assembled at
runtime records no reference to it, so an install arrives without it.
List that package under `dependencies` in `package.yaml`.
- **Identity collapse.** Sub-asset paths skip the `.package` suffix.
Don't include `.package` in `require` strings.
## Referencing inside a package: the `~` rule
`~` means **this package**, resolved structurally from the referring file's own
location. It is the only package-specific syntax. It is rename-safe (no package
name is ever written) and library-agnostic (it never names the host library, so
it survives `@builtin` being renamed or the package being mounted elsewhere).
`~.tail` maps to `<pkg>.package/tail` from anywhere inside the package.
| Referencing from | Use | Example |
|---|---|---|
| An asset/module **inside this package** | `~.tail` | `require("~.modules.myThing")`, `shader: "~.shaders.myThingBlend"` |
| A **different package** under the same root | root-relative identity | `require("@root::systems.otherPkg.modules.x")` |
| A **different library's** public API (a deliberate external dependency) | `@otherlib::…` | `require("@physics::modules.rigidbody")` |
**Never write `@builtin::` (or any host-library name) to reference your own
package** — that couples the package to the library it currently lives in and
breaks if the library is renamed or the files move. Use `~.`. It works from
Luau `require()` and from asset-reference strings in data files (a material's
`mat.yaml` `shader:` field, a component's default asset ref); the engine
resolves it against the referring file's own package. `asset.resolve` takes a
`~.` name the same way, against the package of the file that calls it:
`asset.resolve("~.materials.myThingStandard", "material")`.
`~.` is the package-relative self-reference; `@root::` is the root-relative one
(the library root, or the world source tree for non-library content). The
`core/requiring-modules` guide covers the root model in full.
A package that ships substantial functionality should include a `.guide` asset
(a `<name>.guide/guide.md` folder anywhere under the package); the `guides` tool
discovers it live, so collaborators find the system the way they find built-in
guides. A package's test suite reaches the shared `Test` framework through its
enclosing asset: `local Test = asset.containing(__FILE__).modules.shared`
(`asset.containing` returns the deepest enclosing typed asset, the `.testSuite`,
not the outer `.package`).
## Related types
- Any of `.component`, `.module`, `.scene`, `.preset`, `.tool`,
`.toolbox`, `.material`, `.shader`, `.style`, `.service`,
`.importer` — packages bundle these.
## In the Inspector
Package: the name, version and description package.yaml declares, how many things the package holds and what they are, and **Open** for package.yaml. A package.yaml that does not decode is listed under Problems with the decoder's error.
# preset
A preset holds typed values for one declarer's settings schema: an
assetType's, an importer's, a component's, or any asset that declares its
own settings. `preset.capture` saves the settings something has now,
`preset.apply` writes a preset's values into something its target governs,
`preset.values` reads them checked against the target's current schema, and
`preset.setValues` replaces them, checked first. Exposed as the `preset`
global via `--!global preset`.
A preset's `preset.yaml` names its target as a guid envelope,
`target: { __ref: <guid>, type: <type>, name: <name> }`, which the
preset's `.refs` pins by guid with the target's checksum. A target written
as an identity string is accepted on read, resolves by identity, reads as
unpinned, and is rewritten as the envelope on the preset's next local
edit.
## Exports
- `preset.values(source: AssetRef<preset>) -> ({ [string]: any }, Report)` — the values that pass the target's current schema, and a report naming every one that does not.
- `preset.apply(source: AssetRef<preset>, into: AssetRef | ComponentTarget) -> ApplyResult` — write the valid values into an asset the target governs, or into a component on an entity whose component is the target. Struct groups merge field by field. Raises when another declarer governs `into`.
- `preset.capture(from: AssetRef | ComponentTarget, name: string, opts?: CaptureOpts) -> AssetRef<preset>` — save an asset's settings, or a component's live values on an entity, as a new preset targeting the declarer that governs them. A bare name lands in `/source/presets/`; an absolute `.preset` path lands where it says.
- `preset.setValues(source: AssetRef<preset>, values: { [string]: any })` — replace the whole values table; any violation refuses the write, naming every one.
- `preset.defaults() -> { DefaultRow }` — the world's Preset Manager rows, in order, each resolved with its problems.
- `preset.setDefaults(rows: { DefaultRowInput })` — replace every row; every row is checked first and any problem refuses the write, naming every one.
- `preset.addDefault(source: AssetRef<preset>, opts?: { filter: string?, at: number? }) -> number` — add a row for the declarer the preset targets; returns its index.
- `preset.removeDefault(index: number)` — remove one row, keeping every other row as written.
- `preset.defaultFor(declarer: AssetRef | string, path: string) -> ({ [string]: any }?, Match?)` — the values a new thing at `path` would take from the rows, and the row that gives them.
Types:
- `ComponentTarget = { entity: string, component: string }` — a component on an entity.
- `Report = { format: string, target: string, targetGuid: string?, pinned: boolean, targetChanged: boolean, rejected: { Violation } }` — `target` is the target's identity; `pinned` is true when `.refs` pins the target's guid; `targetChanged` is true while the pinned checksum differs from the target's current one.
- `Violation = { path: string, message: string }`
- `ApplyResult = { applied: { string }, rejected: { Violation }, targetChanged: boolean }`
- `CaptureOpts = { overwrite: boolean? }` — `overwrite = true` re-authors an existing preset, keeping its guid.
- `DefaultRowInput = { preset: any, target: any?, filter: string? }` — a preset, its declarer (the preset's own target when omitted) and a filter (empty matches everything).
- `DefaultRow = { index, target, preset, filter, targetGuid, presetGuid, targetName, presetName, problems }`
- `Match = { index, target, preset, path, rejected, problem? }` — the row a creation took and the path it read.
## Usage
```luau
-- Capture a texture's settings, then apply them to another texture
local p = preset.capture("hero_sprite", "pixel_art")
preset.apply(p, "enemy_sprite")
-- Apply a component preset to a component on an entity
preset.apply("synty", { entity = id, component = "Locomotion" })
-- Capture a component's live values
local tint = preset.capture({ entity = id, component = "Model" }, "red_tint")
-- Read the values and what the target rejects
local values, report = preset.values("pixel_art")
for _, v in ipairs(report.rejected) do print(v.path, v.message) end
-- Replace the values
preset.setValues("pixel_art", { filter = "nearest", generateMipmaps = false })
```
## Notes
- Every read re-checks the values against the target's current schema, so a value a later schema drops or retypes is reported by path rather than applied.
- `asset.create("preset", name, { target = <identity or guid>, values = { ... } })` authors a preset directly, with the same checks as `preset.capture`.
- The Preset Manager rows are documented in `preset.defaults`; the filter grammar in `preset.glob`.
- Submodules: `preset.document` (the `preset.yaml` format), `preset.target` (target resolution and checking), `preset.heal` (rewriting an older preset document in the current form on a local edit).
# AnimDebug
Demo component for inspecting character-controller animation state during the character controller demo.
# CharacterController
Kinematic mover. Integrates velocity against gravity, walls, ceilings and
ground, and writes the result to the entity's position every frame.
## Driving it
The character moves on a public input bus: `inputX`, `inputZ` and
`inputJump`. Each frame the controller reads the bus, moves on what it found,
and then refills it for the next frame.
**Only the local player's body answers the player's controls.** The character
the local player is bound to (`layers.active.players.localPlayer.avatar`)
refills its bus from the `move` axis and the `sprint` / `jump` actions of its
input map, so the map drives it whenever nothing else does. Every other
character holds no map and refills its bus with no movement: an NPC, a
mannequin, a preview or another player's body stands where it is until
something writes its bus. The player's spawn binds the body for you; to hand
the controls to a character you made, bind it:
```luau
layers.active.players.localPlayer.avatar = entity(bodyId)
```
The character takes the map up on the frame after the bind and gives it back
when the binding moves to another body.
Anything else takes the character over by writing those three fields from its
own `update()` — an AI brain, a networked peer, a replay, or gameplay code
that wants the character committed during an attack. The write works from
**any** `executionOrder`, because the refill happens after the read: whatever
is in the bus when the controller next reads it is what the character does.
- A writer ahead of the controller (`executionOrder` below `-100`) is acted on
the same frame.
- A writer behind it is acted on the next frame.
- Stop writing, and the character stops one frame later; on the local
player's body the map has it back instead.
- Pausing gameplay empties the bus, so a character frozen mid-stride stands
where it was paused and a writer that had it committed says so again.
`inputX` / `inputZ` are a world-space velocity in units per second — the
controller applies them as they are, so scale them yourself rather than
expecting `moveSpeed` to. `inputJump` asks for one jump and the next update
consumes it.
A component that walks the character due north, whatever the input map says:
```lua
-- Northbound.component/init.luau
declare { executionOrder = 50 } -- anywhere works; 50 runs after the controller
public = {
speed = Field.number(4.0, Sync),
}
function update(_dt: number)
local cc = public.entity.component.get("CharacterController")
if cc == nil then return end
cc.inputX = 0
cc.inputZ = -public.speed
end
```
`WASDInput` is the same pattern shipped as a component: it reads an input map
of its own and writes the bus of whatever component `targetComponent` names,
which is how a mover that reads no controls of its own gets driven. On a
CharacterController — which reads `move`, `sprint` and `jump` from its own
`inputMap` — a WASDInput writes the bus every frame at its own `speed`, and
that is the speed the character walks at. `CharacterController.install` adds
one when `input = true` asks for it.
## The control scheme
`inputMap` is the scheme the character answers to. It reads three controls from it, each on its own:
- `move` — an axis2, projected against the active viewport camera so "forward" is into the screen.
- `sprint` — held, multiplies `moveSpeed` by `sprintMultiplier`.
- `jump` — pressed, asks for one jump.
A map declaring only some of the three drives the character with those: a scheme with no `sprint` holds one gait, a scheme with no `jump` stays on the ground. The character logs which controls the map left out and names the map, so a game with three verbs ships a three-control scheme. A field naming no map leaves the character answering nothing, and logs that too.
**Repointing it on a live character takes on the next frame.** The map the character was holding is stood down — its controls leave the live set and its touch buttons leave the screen — and the map named here is taken up in its place:
```luau
entity(bodyId).component.get("CharacterController").inputMap = asset.resolve("mygame.input.run", "inputMap")
```
Assigning the map the character already holds changes nothing, so re-stating the scheme leaves the live set where it is. While gameplay is paused the character holds no map at all (the editor's camera has the controls), and it takes whatever `inputMap` names when play resumes. A character that is not the local player's body holds no map either, and takes whatever `inputMap` names when it is bound as that body.
## Platforms, belts and the contact filter
The character meets the surfaces content declares on colliders the way a
rigid body does. Its ground, wall and ceiling queries are cast for the
character's own entity as their mover (`Physics.raycast(..., { mover = id })`
and the same option on the shape casts), so the contact rules the physics
step applies to bodies apply to it too:
- **One-way platforms.** A collider whose `oneWay` points up holds the
character from above only: it jumps up through the platform from below and
lands on top of it, and walks through its sides.
- **Dropping through.** `Physics.passThrough(character)` drops it through the
one-way colliders it stands on (or, with a second argument, only those that
entity owns). It falls through under its own gravity and meets each again
once it is clear of it.
```luau
Physics.passThrough(player) -- drop through what it stands on
Physics.passThrough(player, platform) -- drop through this platform alone
```
- **Moving surfaces.** Standing on a collider whose `surfaceVelocity` moves (a
conveyor belt, a treadmill, an escalator) carries the character at that
velocity on top of its own walk. It keeps the carry as momentum when it
jumps or walks off, and air control (`airControlFactor`) takes it back
toward the walk it asks for.
- **Moving bodies.** Standing on a body that itself moves or turns (a lift, a
moving platform, a turntable, a raft, a ship's deck, a train car) carries
the character with it: each frame the point under its feet goes where the
body took it, and the character turns with the body's turn about up, with
its own walk on top. It rises and descends with a lift without leaving the
ground, and keeps the body's motion at its feet as momentum when it jumps or
walks off. In the air it goes on moving with that motion until it lands, the
way a crate thrown off the deck does: air control (`airControlFactor`) steers
its walk relative to it, so a jump in place on a moving deck comes down on
the spot it left, and a wall it meets in the air stops the part of it the wall
is in the way of. A kinematic body a script moves (`localPosition` writes,
`Physics.setVelocity`), a dynamic body the simulation moves and a transform
something animates all carry it alike. The body is read where the frame
draws it (`Physics.drawnPose`), and the character is seated on the ground as
drawn, so the two stay in step on screen at any frame rate and physics tick
rate. A body a script moves after this component's `update` (an
`executionOrder` above -100, or a task) carries the character on the next
frame. The momentum a kinematic body or an animated transform leaves the
character with is how fast it carried the feet over the last tenth of a
second (and at least the last six frames), however the frames fell against
the physics ticks, and a body that vanishes from under the character
leaves it the same. A character something else moves (a teleport, a
respawn, a script writing its position) stands where it was put and rides
nothing until it stands on a body again.
```luau
local lift = entity.spawn("lift")
lift.component.add("BoxCollider", { half = { 1.5, 0.1, 1.5 } })
lift.component.add("Physics", { kind = "kinematic" })
Physics.setVelocity(lift.id, 0, 1, 0) -- the character on it rides up
Physics.setAngularVelocity(lift.id, 0, 1, 0) -- and turns with it
```
- **The contact filter.** Give the character a collider with a `contactTag`
(a trigger capsule is enough) and `Physics.setContactFilter` answers its
pairs: a collider whose tag the filter answers `"ignore"` or `"sensor"`
with the character's tag is one the character walks through.
```luau
player.component.add("CapsuleCollider", { isTrigger = true, contactTag = "player" })
Physics.setContactFilter("player", "ghostWall", "ignore")
```
## Other characters
Characters meet one another as solid bodies. Every entity carrying a
`CharacterController` is an upright capsule of its `radius` and `height` to
every other character's wall pass (`physics.characters`), so two characters
walking into each other stop a skin apart, a character meeting another off
centre slides around it, and `blocked` reads true while a walk presses into
another character. The same holds for the local player, an NPC and another
player's body.
A character is a body while its entity is active and its controller enabled:
one set inactive (`entity(id):setActive(false)`) or with its controller
disabled (`enabled = false`) lets the others walk through it until it is
switched back on.
The push rule:
- A walk never moves another character. Each peer moves only the characters
it owns, against where it sees the others, so two players' bodies meet on
both peers' screens.
- Two characters that overlap (placed into one another, two spawned at one
point, a body the network shows a frame late) move apart at up to 2 m/s
each, each taking half of the overlap, and never through a wall. A pair
pressed together stands still a skin apart.
- A character gives way to no body moving into it: the one walking in is the
one stopped, on the peer that moves it, so a player walking into a standing
one never drives it along, however late each peer sees the other.
- Only bodies sharing some height meet: a character jumping over another
passes above it, and one coming down onto another's head is moved off it to
the side.
Which characters pass through which is the contact filter's to say, by each
character's `contactTag` (`"character"` unless content names another):
```luau
Physics.setContactFilter("character", "character", "ignore") -- nobody blocks anybody
ghost.component.get("CharacterController").contactTag = "ghost"
Physics.setContactFilter("ghost", "character", "ignore") -- the ghost walks through people
Physics.setContactFilter("redTeam", "redTeam", "ignore") -- teammates pass, foes block
```
## Triggers, pickups and the bodies it walks into
The character holds no rigid body: it states its capsule (`Physics.setWaterVolume`),
`height` tall and `radius` round, standing on its feet. That capsule is how
the rest of the world meets it:
- **Triggers and pickups.** A trigger collider hears the character enter and
leave it as it hears a body (`Physics.onTrigger(zone, fn)`, with `other`
the character's entity), and a listener on the character
(`Physics.onTrigger(character, fn)`) hears every trigger it goes through.
Every engine the character exists in hears it, the remote players' bodies
included, so a zone counted on each peer counts every player. A trigger on
an entity beneath the character (a sensor it carries) rides with it and
does not hear it.
- **Water.** `Physics.onWater` hears it go in and out of the water and
`Physics.immersion` reads how deep it stands.
- **Pushing.** A dynamic body the walk runs into is pushed along the walk:
the walk stops at it as at a wall, and the body is given the impulse that
brings its speed along the walk up to the walk's, with at most `pushForce`
newtons (400 by default) behind it. On level ground a body moves once
`pushForce` passes its friction coefficient times its weight, so at the
default a 5 kg crate goes along at the walk with the character behind it and
a 500 kg one stands like a wall. `pushForce = 0` makes every body a wall.
- **Bodies moving into it.** A body that moves into the character puts it
back outside, as a wall that moved into it does.
```luau
local player = layers.active.players.localPlayer.avatar
Physics.onTrigger(coin, function(e)
if e.kind == "enter" and e.other == player.id then collect(coin) end
end)
player.component.get("CharacterController").pushForce = 150 -- a weaker shove
```
## Telemetry
These read back what the mover did on the frame just simulated:
- `grounded` — standing on ground no steeper than `maxSlopeAngle`.
- `falling` — in the air and descending.
- `sliding` — on ground too steep to stand on, being carried down it.
- `blocked` — the character asked to move horizontally and the wall pass left
it with none of that movement: pressed into a wall, or wedged where two
surfaces meet. This is what tells a character standing still apart from one
whose walk is being refused.
- `slopeAngle` — the angle, in degrees, of the ground under it.
- `velocityX` / `velocityY` / `velocityZ` / `horizontalSpeed` — its velocity.
- `jumpCount` — jumps used since it last landed.
# Locomotion
Blend-space-driven locomotion for entities running the
characterController package. Reads horizontal velocity from a sibling
`MovementState` (or, as a fallback, `CharacterController`) component
on the parent and feeds a single 2D blend space (strafe-angle on X,
speed on Y) with idle / walk-{F,L,R,B} / run-{F,L,R,B} / sprintF
clips. Each clip's point sits at the speed the clip carries this body
at: its retarget bake measures how fast the ground passes under the
stance foot on this body's legs, so the feet move with the ground at
whatever speed the body moves. A clip that plays without a measured
speed sits at its gait's `walkSpeed` / `runSpeed` / `sprintSpeed`.
Pair on the same entity (or a parent of) a `SkinnedModel`. The
component creates the AnimGraph, polls for the SkinnedModel child
once start() has run, registers the clips as blend-space points and
plays the graph. `update()` damps speed + angle and writes them to
the active blend space each frame.
This supersedes the older FSM-based Locomotion controllers
(crouch / jump / fall / land / turn-in-place state machine). Those
behaviours can be added back as separate layered graphs once the
blend-space driver has settled.
# MovementState
Component that exposes movement state for controller-driven animation and gameplay consumers.
# characterController
Physics-based character controller — capsule movement with
ground / wall / ceiling detection. A kinematic controller using
raycasts for collision; handles gravity, jumping, slope traversal,
step climbing, wall sliding, coyote time, and moving platforms. The
module owns a per-entity registry; attach once, call `move` / `jump`
each frame, then drive a per-frame `update(dt)`. The
`install` / `uninstall` / `preset` surface wires up the standard set
of components (CharacterController + Locomotion + MovementState +
optional WASDInput and third-person camera child) in one call.
Require it to use the surface:
```luau
local CharacterController = require("@builtin::systems.characterController.characterController")
```
## Exports
- `CC.attach(entityId: string, userConfig: Config?)` — register an entity, merge user overrides over `Defaults.standard`.
- `CC.detach(entityId: string)` — drop the registry entry.
- `CC.move(entityId: string, direction: Vec3)` — set per-frame world-space movement input (`y` is ignored).
- `CC.jump(entityId: string)` — request a jump; honours coyote time and jump buffer.
- `CC.getState(entityId: string) -> State` — snapshot copy of grounded / falling / velocity / etc.
- `CC.getVelocity(entityId: string) -> (number, number, number)` — current `vx, vy, vz`.
- `CC.setGravity(entityId: string, gravity: number)` — update gravity at runtime.
- `CC.setMaxSlope(entityId: string, degrees: number)` — update max walkable slope angle.
- `CC.setConfig(entityId: string, key: string, value: any)` — update a single config key.
- `CC.getConfig(entityId: string) -> Config` — config copy.
- `CC.update(entityId: string, dt: number)` — advance one frame (resolve movement, write position, tick state machine). `dt` is clamped to 0.1.
- `CC.isAttached(entityId: string) -> boolean` — whether the entity has a registration.
- `CC.install(entityId: string, opts: InstallOpts?) -> InstallResult` — high-level wire-up (components + optional camera / mesh / WASDInput).
- `CC.uninstall(entityId: string) -> UninstallResult` — remove everything `install` added.
- `CC.preset(entityId: string, presetName: string) -> PresetResult` — apply a preset to an already-installed character in place.
Types:
- `Vec3 = { x: number, y: number, z: number }`
- `Config = { height?, radius?, maxSlopeAngle?, stepHeight?, gravity?, jumpForce?, coyoteTime?, jumpBuffer?, maxJumps?, airControlFactor?, groundSnapDistance?, skinWidth?, moveSpeed? }`
- `State = { grounded, falling, sliding, wallContact, wallNormal, velocity, groundNormal, slopeAngle, jumpCount, timeSinceGrounded, timeSinceWallContact, onMovingPlatform, platformEntity? }`
- `BundleRef = { guid?, __ref?, identity?, path?, name? }`
- `InstallOpts = { preset?, camera?, input?, mesh?, overrides? }`
- `InstallResult = { entityId, cameraId?, meshHostId? }`
- `UninstallResult = { entityId, despawned }`
- `PresetResult = { entityId, preset, applied }`
## Usage
```luau
local CharacterController = require("@builtin::systems.characterController.characterController")
-- Low-level: manual attach + per-frame drive.
CharacterController.attach(entityId, { gravity = -15, jumpForce = 7 })
CharacterController.move(entityId, { x = 1, y = 0, z = 0 })
CharacterController.update(entityId, dt)
-- High-level: one-call wire-up.
CharacterController.install(entityId, {
preset = "humanoid_default",
camera = true,
overrides = { jumpForce = 8 },
})
```
## Notes
- `attach` merges user config over `Defaults.standard`; passing
unknown keys is allowed (they survive into the config table).
- `update` clamps `dt` to 0.1s to prevent capsule tunnelling on
lag spikes.
- `getState` and `getConfig` return shallow copies — mutating the
result does not affect the controller. The returned `velocity` /
`wallNormal` / `groundNormal` are also shallow copies.
- `install` is idempotent per component — re-running on an already
wired entity adds nothing new. `uninstall` removes the components
and any third-person-camera child that targets this entity.
- `preset` mutates fields in place and never adds or removes
components — call `install` first.