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

layers

Top-level scene-management global + Scene proxy. § 17 step 9 of `docs/plans/2026-05-01-player-camera-unification.md`. Renamed from the legacy `scene.*` global to match `/runtime/layers/` and to give scene-management state (active root, additives, callback registries) a single anc…

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

layers

Top-level scene-management global + Scene proxy. § 17 step 9 of docs/plans/2026-05-01-player-camera-unification.md. Renamed from the legacy scene.* global to match /runtime/layers/ and to give scene-management state (active root, additives, callback registries) a single anchor distinct from per-scene authoring.

Global surface

SymbolTypeNotes
layers.activeScene | nilCurrent root non-additive scene as a proxy. Live read; updates on every load/unload.
layers.list(){ Scene }Every loaded scene (root + additives) as proxies.
layers.find(ref)Scene | nilLookup by AssetRef<scene> or layer-id string.
layers.is_loaded(ref)boolean
layers.load(ref, opts?)—Loads ref. opts.additive = true layers on top; default = non-additive (replaces root).
layers.unload(ref?)—Unloads ref; nil = active root.
layers.reload(ref?)—Equivalent to unload + load with same ref.
layers.onLoad(cb) -> handlefunctionSubscribe to any scene-load event. Returns handle for offLoad.
layers.offLoad(handle)function
layers.onUnload(cb) -> handle / offUnload(h)functionSame shape for unload events.
layers.observe()SceneObservationWhat every load did and what each loaded scene costs, in one read.
layers.lastLoad()SceneLoadReport | nilThe last load's report; nil when nothing has loaded.
layers.lastUnload()SceneUnloadReport | nilThe last unload's, under the name the layer was loaded with.
layers.loadHistory(){ SceneLoadReport }The completed load reports still held, oldest first.
layers.problems(ref?){ SceneLoadFailure }What a layer failed to produce, and why.
layers.whyPartial(ref?)(reason?, detail?)The nearest cause a layer is not whole, from a closed set.
layers.inventory(){ SceneLayerInventory }What the engine attributes to each loaded layer.
layers.cost(){ SceneLayerCost }Each layer's per-frame entrypoint tick, summed across the window.
layers.resetCostWindow()—Open a new cost window.

Scene proxy surface

A Scene proxy is a sealed table with fields and :method callables.

Field / methodNotes
s.assetAssetRef<scene>
s.name, s.pathinformational (logging, debug)
s.guidthe scene asset's guid — the layer's identity
s.sceneIdentitythe identity of the scene asset the layer was loaded from (e.g. @builtin::scenes.test_arena), whichever VM loaded it
s.additiveboolean — additive overlay vs root scene
s.parent, s.childrenadditive ownership chain
s:root()walks .parent to the non-additive root; returns self for roots
s.players, s.camerapopulated by §17 step 10 (player + camera spawners)
s.entrypointAssetRef<script> | nil
s.visibleboolean — read via field, toggle via s:set_visible(b)
s.state"loading" / "loaded" / "ready" / "partial" / "unloading" — the layer's lifecycle state. Both "ready" and "partial" are terminal: the load has settled.
s.ready, s.loadedbooleans in lock-step with state. ready is true once the layer has settled, in either terminal state — it is the flag to wait on.
s.okboolean — whether everything the scene declared was produced and the layer has run clean since. False whenever state is "partial", including when the tick starts raising long after the load settled.
s.failures{ SceneLoadFailure } — every distinct failure the load and the layer's per-frame tick produced, each with the count of how often it repeated.
s:unload()unload this scene; additives use layers.unload(layerId), roots use layers.active:reload()
s:reload()unload + reload same ref
s:set_visible(b)show/hide without unloading
s:load_additive(ref)load a sibling additive overlay; returns the new proxy

Example

-- Switch root scene
layers.load(asset.ref("@builtin::scenes.baseline_visual"))

-- Subscribe to all loads
local h = layers.onLoad(function(scene)
    print("loaded:", scene.name)
end)

-- Layer an HUD overlay on top
layers.load(asset.ref("@builtin::scenes.hud"), { additive = true })

-- Iterate every loaded scene
for _, scn in ipairs(layers.list()) do
    print(scn.name, scn.additive and "(additive)" or "(root)")
end

layers.unload()       -- unload the active root
layers.offLoad(h)

What a load did, and what a scene costs

Every load writes one record at its own completion point; the readings below compose that record, so a caller that did not make the load can still ask what it did. A load that produced failures settles into "partial" rather than "ready", and names the nearest cause from a closed set: loaderRaised, entrypointCompileFailed, entrypointBodyRaised, entrypointRaised, buildRaised, entityFailed, parentMissing, parentRefused, parentAbandoned, componentUnresolved, componentRefused, subscriberRaised, updateRaised.

layers.load(asset.ref("scenes.arena", "scene"))

-- Did it come up whole?
if not layers.active.ok then
    local reason, detail = layers.whyPartial()
    print(reason, detail)
    for _, f in layers.problems() do
        -- `count` rises when the same failure happens again, so a per-frame
        -- tick that keeps raising stays one line.
        print(f.phase, f.reason, f.entity, f.component, f.hook, f.count)
    end
end

-- What did the swap do?
local r = layers.lastLoad()
print(r.name, r.outcome, r.durationMs)
print("replaced", r.replaced and r.replaced.name)      -- the root that went
print("cascaded", #r.cascaded)                         -- the overlays with it
print(r.entities.added, "arrived,", r.entities.removed, "left")
print(r.phases.teardown, r.phases.instantiate, r.phases.settle)

-- Which loaded scene is expensive? `totalMs` is a SUM across the window, so
-- reset it first and read `avgMs` for the per-tick figure.
layers.resetCostWindow()
task.wait(1)
for _, c in layers.cost() do
    print(c.name, c.avgMs, "ms/tick over", c.calls, "ticks")
end

-- What does each layer hold, and what does no layer claim?
for _, l in layers.inventory() do print(l.name, l.entities, l.ok) end
print(layers.observe().totals.unattributed)

The scene toolbox carries the same two readings as scene.observe and scene.whyPartial.

Authoring surface

layers.* is the sole public scene-management surface. It accepts AssetRefs (not paths), drives a callback registry, and constructs Scene proxies that carry players / camera / hooks. The previous scene.* global has been removed — its low-level FFI bindings now live behind layers.* and the Scene proxy methods.

Interface

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

conforms to

zero/source-extract/v2

global layers module layers Top-level scene-management namespace + Scene proxy. Owns the public layer-management API surface exposed on `_G.layers`. Pure Luau composition over internal `__layers.*` ECS-glue primitives; the LSP discovers the public shape via this `--!global layers` directive.

currentMode( ) → string

The engine mode a load is running in.

worldEntityIds( ) → void

Which entities the world holds right now, as a set of ids. Read at the two ends of a load so its entity delta is a set difference taken BOTH ways — what arrived and what left, rather than the one net number a pair of counts can express. A load costs two of these; nothing reads it per frame.

layerEntityCounts( ) → void

How many entities the engine attributes to each layer, keyed by layer guid, and how many entities the world holds, from one read of the world. Every entity carries the guid of the layer that owns it (`sceneLayer`), children and every deeper descendant included, and that attribution is the set an unload of the layer despawns. So each number is the engine's own count of what the layer holds, and the counts of every layer plus the entities no layer owns add up to the total.

layerEntityCount(guid: string?) → number

How many entities the engine attributes to one layer, by its guid.

argtypedescription
guidstring?

currentTaskHandle( ) → number

The scheduler handle of the task the calling code runs in, or nil outside any task. It is the half of a claim that stays answerable after the coroutine holding the claim stops being advanced: `task.status` reads a handle, and a coroutine reference on its own cannot tell a task parked at a wait from one the scheduler has cancelled.

ownerCanStillSettle(entry: any) → boolean

Whether the code that owes a slot can still run to the release it carries. A dead coroutine answers no on its own. A live one answers only with its task: a cancelled task's coroutine stays `suspended` forever, so the scheduler's reading of the owner is what separates a load still converging from one that stopped mid-flight. A slot taken outside any task has no owner to ask about, and the coroutine is the whole answer.

argtypedescription
entryany

holdSceneLoadGate(ns: any, sceneId: string?) → any

Raise the `__scene_load` gate and record the claim beside the code that owes the matching `finish`, so the readers' reap can lower a gate whose holder stopped being advanced. `sceneId` names the scene the gate is opened for where the caller has one. Returns the token `releaseSceneLoadGate` takes, or nil when there was no gate to raise.

argtypedescription
nsany
sceneIdstring?

releaseSceneLoadGate(token: any) → void

Lower a scene-load gate its holder still owes, once. The claim is dropped before the call, so a `finish` that raises still leaves the gate accounted for rather than lowered twice by the reap that comes after it.

argtypedescription
tokenany

invalidateActiveProxy( ) → void

getLoader( ) → void

Lazy getter avoids circular-require risk; falls back gracefully if scene_loader hasn't hot-reloaded yet during the transition.

canDrainMutations( ) → boolean

The engine's `SceneLayers` resource holds one slot per loaded layer, keyed by scene guid. `__layers.create` / `__layers.unload` reach it through the deferred-mutation pump, so the row appears (or leaves) a frame after the Luau call that queued the mutation. Every path that needs the registry to have caught up goes through these three helpers, which read `__layers.loaded()` — the engine's own answer. `M.find` / `M.is_loaded` fold in Luau-side bookkeeping on top of that row list, so they answer a different question and are the wrong instrument here. Whether the caller is on a coroutine that can yield to let the pump run.

layerSlotPresent(sceneGuid: string?) → boolean

True while the engine holds a layer slot for this guid.

argtypedescription
sceneGuidstring?

waitForLayerSlot(sceneGuid: string?, frames: number) → boolean

Yield until the engine holds the slot, up to `frames` frames. Every load path waits here before it fans `onLoad` out and before it returns, so a caller's next statement — and every subscriber — resolves the layer through `layers.find` / `layers.list` / `layers.active`. The frame ceiling turns a create the engine refused into the next assertion's failure instead of a hang.

argtypedescription
sceneGuidstring?
framesnumber

waitForLayerSlotGone(sceneGuid: string?, frames: number) → boolean

The mirror: yield until the engine has dropped the slot. An unload's despawn pass filters on the slot, so a same-guid load has to let that finish before it spawns into the layer again.

argtypedescription
sceneGuidstring?
framesnumber

noteHeldEntities(layerKey: string) → void

Take the entities live in the layer `layerKey` names as ones this session holds. The saver asks that of every overlay record whose entity is gone: an entity this session held and no longer holds is one it removed, and one it never held belongs to the session that authored it.

argtypedescription
layerKeystring

getPlayersModule( ) → void

Fields populated at construction: guid : string scene-asset GUID — CANONICAL identity. Matches `SceneLayers` HashMap key, every contained entity's `SceneOwner.scene`, and the multiplayer room-key component. Never empty for proxies returned by `layers.list` / `find` / `active`. asset : AssetRef<scene> ref envelope (same guid as above, plus identity / path / name / type mirrors) name : string human-readable display name (from asset). NOT unique — two scenes can share a name; only `guid` is the identity. Never used for comparison or lookup. path : string VFS path (informational) additive : boolean true for additive overlay scenes parent : Scene | nil owner (non-nil for additives) children : { Scene } additives loaded from this scene players : Players | nil non-nil on ROOT scenes (additive = nil) camera : Camera | nil non-nil on ROOT scenes (additive = nil) entrypoint : AssetRef<script> | nil visible : boolean Lives on root (non-additive) Scene proxies as `scene_proxy.players`. The registry surface itself is owned by the `players` module under `api/engine/`; this module just hands the Scene proxy a fresh registry per non-additive scene and exposes it as `.players`. Lazy require to avoid circular-load risk during prelude install (the players module is leaf-level and doesn't require layers, but the deferred resolution keeps the dependency direction unambiguous if that ever changes).

findPrimaryCameraEntityId( ) → void

Wraps the scene's primary camera entity (the engine-spawned "__primary_camera" when Step 10 lands). For now: scans for an entity named "__primary_camera" with a Camera component, returns a thin proxy that delegates field reads/writes to the Camera component instance and exposes `.behaviors` shortcuts.

hasCamera(e: any) → boolean

argtypedescription
eany

snakeToCamel(s: ?) → void

Camera-behavior catalog (tag-driven). The agent-facing surface `layers.active.camera.behaviors.<shortcut>` resolves to the AssetRef of a registered component carrying the `cameraBehavior` tag in its `.metadata` sidecar. No hardcoded mapping table — adding a new behavior is ONE step (tag its component), not "tag it AND edit this file". The shortcut key is the last `.`-separated segment of the asset identity, snake → camel: `@builtin::controller.orbital_follow` → `orbitalFollow`. `behaviors._list()` enumerates the catalog for discoverability (agents + editor UI).

argtypedescription
s?

shortcutForIdentity(identity: ?) → void

argtypedescription
identity?

listCameraBehaviorIdentities( ) → void

buildCameraBehaviors( ) → void

loadCatalog( ) → void

refFor(name: ?) → void

argtypedescription
name?

__index(_: ?, k: ?) → void

argtypedescription
_?
k?

__newindex(_: ?, k: ?, _: ?) → void

argtypedescription
_?
k?
_?

onWrite(value: ?) → void

argtypedescription
value?

onWrite(value: ?) → void

argtypedescription
value?

newConfigBlock(sceneProxy: ?, label: ?, schema: ?) → void

Build a metatable-wrapped config block. The wrapper table is empty; every read passes through __index to the backing `data` table, every write passes through __newindex (validates → writes data → fires mark). Storing data on the wrapper itself would defeat __newindex on subsequent overwrites of the same key, so the empty wrapper + separate backing pattern is mandatory for validation to keep working. Three backdoors via __index for serializers + LSP tooling: `_snapshot()` plain-table copy of the backing data (saver iteration) `_schema` the declared field-schema table `_label` the block name (`"player"` / `"camera"`)

argtypedescription
sceneProxy?
label?
schema?

schemaKeyList( ) → void

validate(key: ?, value: ?) → void

argtypedescription
key?
value?

markDirty( ) → void

snapshot( ) → void

callOnWrite(key: ?, value: ?) → void

Per-field `onWrite` hook: schema entries may declare `onWrite = function(value) ... end`. When the field is assigned, the hook fires AFTER validation + data update + manifest mark. This is the channel by which `settings.lighting.clear_color = {...}` routes into `__lighting.setClearColor(...)` — the scene_loader stays a pure data-pusher because the side effect lives on the schema.

argtypedescription
key?
value?

__index(_: ?, k: ?) → void

argtypedescription
_?
k?

__newindex(_: ?, k: ?, v: ?) → void

argtypedescription
_?
k?
v?

newSettingsBlock(sceneProxy: ?) → void

The `settings` proxy itself is sealed: top-level keys are the pre-built sub-blocks (built by `newConfigBlock`). Writes to `settings.player = ...` would replace the sub-block wrapper with a plain table and defeat validation — refuse them with a clear error that points the caller at the right shape (`settings.player.field = ref`).

argtypedescription
sceneProxy?

__index(_: ?, k: ?) → void

argtypedescription
_?
k?

__newindex(_: ?, k: ?, _v: ?) → void

argtypedescription
_?
k?
_v?

buildCameraProxy(sceneProxy: ?) → void

argtypedescription
sceneProxy?

__index(_: ?, k: ?) → void

argtypedescription
_?
k?

__newindex(_: ?, k: ?, v: ?) → void

argtypedescription
_?
k?
v?

new(fields: ?) → void

argtypedescription
fields?

root( ) → void

Walk up `parent` to the non-additive root. For a root scene, returns self. Cheap O(depth) traversal — additive nesting is shallow in practice (root → 1-2 overlays).

unload( ) → void

awaitLandingBuild(proxy: any) → void

Wait out a build of this layer's scene that is landing. A build carries its records into the layer and saves the scene over many frames, holding the ids of the entities it is landing on and composing the save from them. Tearing the layer down under it despawns those entities partway: the build goes on writing to ids that left, the overlay records the half-landed entities, and the save that closes the build is refused or composed across the teardown. So the layer comes down once the build has landed and saved. A caller that cannot yield tears it down at once.

argtypedescription
proxyany

awaitPartlyApplied(what: string) → void

Wait while a scene load has handed the frame back part way through its records (`loader.partlyApplied`). Its layer holds only the records applied so far: a load of the same scene would answer it as already loaded, a swap would tear it down under the records still to come, and an unload would take down a scene the load goes on applying. A load or an unload reaching that point waits here until the load in progress has applied the rest, so it finds every scene whole, as it would if each load applied its records within one frame. A caller that cannot yield goes on at once.

argtypedescription
whatstring

reload(opts: { rebuild: boolean?, fromFiles: boolean? }?) → void

Round-trip this layer: unload, then load the same ref again. The scene comes back as its sources describe it NOW, which is why the load below asks for the build: `build.luau` reads components and assets whose presence its own digest says nothing about, so answering a reload from that digest would hand the author back exactly the scene they asked to have rebuilt. `opts.rebuild = false` is the revert's form of the same round-trip: it leaves the load answering the build from the digest the saved scene records, the way a boot load answers it. An edit-mode reload first writes the live edits the overlay does not hold yet into it, so the scene comes back with them. `opts.fromFiles = true` is the respawn's form: the layer comes back as its files hold it, and a live edit no file holds goes with the unload. Returns what the build did, as `SceneBuildReport`.

argtypedescription
opts{ rebuild: boolean?, fromFiles: boolean? }?

resolveSaveTarget(self: ?, opts: ?) → void

Resolve the on-disk target for save/dirty operations on this layer. Prefers an explicit `opts.to`, otherwise falls back to the asset's VFS path / identity. Returns nil when nothing maps.

argtypedescription
self?
opts?

sceneAsset( ) → any

The durable scene ASSET this live layer maps to, as a dispatchable `AssetRef<scene>`. Persistence lives on the asset (not this runtime proxy); `save` / `clearDirty` below forward here. Resolved fresh from the scene identity so it always carries the assetType methods, even when the cached `self.asset` envelope came from an engine-internal seed.

save(opts: ?) → void

Publish the layer's current state to canonical `scene.json`. Forwards to the scene ASSET's `save` — this runtime proxy owns nothing on disk, so the asset is the one that persists. `opts.to` saves to a different scene ("save as"). Additive overlays are transient and not savable.

argtypedescription
opts?

writeDirty(opts: ?) → void

Ensure the dirty directory reflects every pending edit-mode mutation + the current scene-level config. The continuous writer keeps the dirty directory current per-frame; this is the "force the drain now" entry point (used by `wld.play()` before mode flip). Writes only deltas (changed-entity files + manifest when scene-level config differs). NEVER touches canonical. Returns the absolute VFS path of the manifest.

argtypedescription
opts?

hasDirty(opts: ?) → void

True iff any dirty state exists for this layer — the manifest OR at least one per-entity overlay file.

argtypedescription
opts?

clearDirty(opts: ?) → void

Discard this layer's unsaved edits and bring the LIVE scene back to its saved state. Deletes the dirty overlay (`scene_dirty/manifest.json` + every `entities/<id>.json`), then reloads the layer so the running ECS is respawned from canonical `scene.json`. The overlay is deleted first because `scene_loader` composes canonical + overlay on load — a reload with the overlay still present would respawn the very edits being discarded. Returns true if any overlay state was removed. The respawn re-establishes the saved baseline; it is not authoring, so it must not re-enter the dirty overlay. `M.load` releases its own scene-load gate before the deferred entity drain, so the respawned canonical entities would otherwise be marked dirty again. Holding the gate across the whole revert (delete + reload + respawn settle) makes `mark_entity_dirty` suppress them, so the end state is fully non-dirty. Spawner-managed entities (Player, primary camera, their temporary avatar children) created after the gate window are excluded by the saver's authored-entity filter, so they don't leak either. Runs the reload through the layer lifecycle, so it must execute in a coroutine (the same requirement as `:reload()` / `:save()`); callers from `execute`, the editor, and mode flips already provide one. Discard the layer's unsaved edits and bring the LIVE scene back to its saved state. Forwards to the scene ASSET's `discard` (the asset owns the dirty overlay); the asset deletes the overlay and drives this layer's `reload()` to respawn canonical under the scene-load gate. Additive overlays carry no dirty state.

argtypedescription
opts?

promoteDirty(opts: ?) → void

Promote the layer's dirty overlay to canonical: compose canonical + overlay (per-entity body overrides + tombstone removes + new entity appends + scene-level config overrides) → write canonical → clear dirty. Returns the canonical path on success, nil when there was no dirty state to promote, and raises when the canonical write is refused — that leaves the overlay standing with this session's edits still in it and nothing baked.

argtypedescription
opts?

set_visible(v: ?) → void

argtypedescription
v?

load_additive(ref: ?) → void

argtypedescription
ref?

on_load(cb: ?) → void

Per-proxy load/unload subscriptions (§ 4): fire only for THIS scene. These complement the global `layers.onLoad` / `onUnload` which fire for every scene load.

argtypedescription
cb?

off_load(handle: ?) → void

argtypedescription
handle?

on_unload(cb: ?) → void

argtypedescription
cb?

off_unload(handle: ?) → void

argtypedescription
handle?

on_load_play(cb: ?) → void

Mode-gated load subscriptions (Step 3k.1). `:on_load_play` fires only when the scene loads with `engine.mode == "play"`; `:on_edit_load` fires only when `engine.mode == "edit"`. Used by `scene_loader.runEntrypoint` to register the entrypoint's `function onLoad(...)` (play gameplay code) and `function onEditLoad(...)` (custom per-scene editor / authoring tools). Authors register against the proxy directly via the public surface above the SceneProxy methods on the layers module returned table.

argtypedescription
cb?

off_load_play(handle: ?) → void

argtypedescription
handle?

on_edit_load(cb: ?) → void

argtypedescription
cb?

off_edit_load(handle: ?) → void

argtypedescription
handle?

onReady(cb: ?) → void

Latched "scene is ready" subscription. Fires once the scene reaches `state == "ready"` (entrypoint onLoad/onEditLoad ran, or entities spawned when there is no such hook). LATCHED: a callback registered AFTER the scene is already ready fires immediately, so a late subscriber never misses the signal and never has to poll `.state`.

argtypedescription
cb?

offReady(handle: ?) → void

argtypedescription
handle?

registerSceneProxyDocs( ) → void

The proxy `layers.active` returns exposes its API as SceneProxy metatable methods, which the `--!`-directive doc scanner (module-global surface only) can't reach — so `layers.active:save()` and its siblings were reachable only from guide prose, absent from lsp.methods("layers") / lsp.describe. Register each explicitly under `globals/layers/active/*` so the whole proxy surface is discoverable alongside the layers globals.

push(reg: ?, fn: ?) → void

argtypedescription
reg?
fn?

remove(reg: ?, handle: ?) → void

argtypedescription
reg?
handle?

withTraceback(err: ?) → string

Carry the raise site with the message. `pcall` yields only the error value, which for a scene entrypoint names one line and none of the frames that reached it.

argtypedescription
err?

fire(reg: ?, ...: ?) → void

argtypedescription
reg?
...?

sceneContentSignature(refEnvelope: ?) → void

Canonical-content signature for the scene at `refEnvelope`. Returns nil when the saver / vfs is unavailable so the caller treats it as "unknown" and reloads (correctness over the no-op optimization).

argtypedescription
refEnvelope?

proxyCacheKey(sceneGuid: ?, isAdditive: ?) → void

argtypedescription
sceneGuid?
isAdditive?

buildProxyFromLayer(layer: ?) → void

Build a Scene proxy from raw fields returned by `__layers.loaded()`. Each row carries `{guid, name, additive, persistent, visible, origin, source}` — `guid` is the canonical identity, `name` is the display name from the underlying asset. The proxy is cached so repeated reads of `layers.active` / `layers.list()` return the SAME object — see `proxyCache` above for why.

argtypedescription
layer?

list( ) →

Every loaded scene layer as a proxy, root and additive alike, in the order the engine reports them. A proxy carries `name`, `sceneIdentity` (the scene asset it was loaded from, e.g. `scenes.main`), `guid`, `path`, `additive`, `persistent` and `visible`. The root one — the open scene — is also `layers.active`.

examples

for _, layer in ipairs(layers.list()) do print(layer.name, layer.sceneIdentity, layer.additive) end
print("open scene:", layers.active.sceneIdentity)

find(ref: AssetRef<scene> | string) → any

The loaded layer for a scene, matched on guid — the canonical identity, since display names can collide and paths drift when assets move. A layer torn down but not yet pumped out of the engine's loaded list reads as gone.

argtypedescription
refAssetRef<scene> | stringA scene `AssetRef`, or an identity string resolved through `asset.ref`.

examples

local layer = layers.find("scenes.arena")

is_loaded(ref: AssetRef<scene> | string) → boolean

Whether a scene currently has a loaded layer — the boolean form of `layers.find`. A scene counts as loaded from the frame the engine holds a layer slot for it — the same slot its entities are attributed to — until an unload is issued against that slot. So a gate like `if layers.is_loaded(ref) then layers.unload(ref) end` sees the layer on the frame its entities exist.

argtypedescription
refAssetRef<scene> | stringA scene `AssetRef`, or an identity string.

examples

if not layers.is_loaded("scenes.hud") then layers.load("scenes.hud", { additive = true }) end

currentRootLayerName( ) → string

The current root layer's NAME, read straight from engine state. The active root is the first non-additive loaded layer. `__layers.loaded()` is engine state — current in ANY VM — unlike the per-VM memo below, so it is the authority on which root is live right now.

activeProxy( ) → void

`active` is the current root non-additive scene. Listed layers carry an `additive=false` row for the root; we pick the first such entry. Returns nil when no root scene is loaded (engine boot state before any `layers.load`).

resolveSceneRef(ref: ?) → void

Coerce an AssetRef envelope or string into the string identity the underlying `__layers.load` / `__layers.loadAdditive` FFI expects. Prefers Resolve an input (AssetRef envelope OR identity string) to a full AssetRef envelope. Hard-errors when the result lacks a stable guid. Names alone are too brittle to drive scene identity: the same slot ("main") can carry different scenes serially, and the engine's `asset.ref` is the only thing that can answer "which scene is this, canonically" — so we always go through it and demand a guid back.

argtypedescription
ref?

incrLoadInFlight( ) → void

Load-in-flight counter, published through the public `M.loadInFlight()` accessor: it reads > 0 while any scene load is mid-flight (queued mutations not yet drained, or a non-additive load waiting on the default player identity to land). Callers that need a settled scene — an agent sequencing the next operation, a test waiting on a load — poll it down to 0. Module-local upvalue (one load per VM) — the counter lives for the VM lifetime.

decrLoadInFlight( ) → void

loadInFlight( ) → number

Returns the number of scene loads currently in flight (queued but not yet visible via `onLoad` dispatch). Returns 0 when the engine is in a stable load state. Used by `engine.mode = ...` to block flips while a load is mid-air; agents can read this to wait for a load to finish before driving the next operation.

rebuildInFlight( ) → boolean

Whether the engine is rebuilding the live scene right now: a scene load is carrying entities in, an edit↔play flip's transition is materialising the layer set, or a scene's `build.luau` build is landing what it produced. A flip unloads the root layer and loads it again for the new mode across many frames, and each mode materialises a different set of entities; a build lands its records and saves the scene over several frames. Either way the live entities are a stage of a scene being built while this reads true. A caller whose answer belongs to the settled scene, a test taking a root or a validator judging the live tree, polls it down to false first. converging.

examples

if not layers.rebuildInFlight() then print(#entity.findAll(), "entities settled") end

followScene(proxy: any, follow: boolean?) → void

Ask the user's client to open the root scene `proxy` this client just loaded, with the load's `follow` option. Only a load an agent's call made moves the user's client, so a load with no caller (the world's own startup, the person's own editor, game code) asks nothing. A follow the host could not be asked for is logged; the load itself stands.

argtypedescription
proxyany
followboolean?

load(ref: AssetRef<scene> | string, opts: LoadOpts?) → any

argtypedescription
refAssetRef<scene> | string
optsLoadOpts?

loadBody(ref: any, opts: any) → void

argtypedescription
refany
optsany

settleLoadSlot( ) → void

settleReport(raised: string?, unchanged: boolean?) → void

Settle the record on every way out of this function. A load that raises leaves a report saying so rather than an open record nothing closes.

argtypedescription
raisedstring?
unchangedboolean?

sceneLoadBegin( ) → void

sceneLoadFinish( ) → void

unload(refOrProxy: (AssetRef<scene> | string | any) → void

Unload a scene layer. Unloading the root cascades through its additive overlays first, most-recently-loaded first, so none is left as a layer the engine still lists after its entities are gone; persistent additive layers survive the cascade. A scene with no loaded layer is a no-op. An unload made while a load is part way through a scene's records waits for that load to apply the rest. Omit to unload the active root scene.

argtypedescription
refOrProxy(AssetRef<scene> | string | anyA scene `AssetRef`, an identity string, or a scene proxy.

examples

layers.unload("scenes.hud")
layers.unload() -- the active root, plus its non-persistent overlays

reload(ref: (AssetRef<scene> | string) →

Unload and re-load a scene layer in place, so an edited scene asset takes effect without rebuilding the surrounding layer stack. The scene's `build.luau` runs against what it resolves right now, so a build script whose inputs moved (a component that now exists, an asset that now resolves) produces the scene it describes today. The rebuild saves the scene, as a write to `build.luau` does, so `scene.json` holds what the reload built and the next play loads it; unsaved edits in the scene are saved with it. A library scene (under `/libs/`) is rebuilt in the live scene alone. A reload asked for while a build of the scene is landing (a write to `build.luau` rebuilds over several frames) waits for that build to land and save first. root scene. with the entity counts each half placed and whether `scene.json` now holds them (false for a library scene), carrying `refused` and a `message` reading them out when an operation the build ran was refused, or `{ built = false, reason, message }` naming what stood in the way. Nil when no layer matched, which is a no-op.

argtypedescription
ref(AssetRef<scene> | stringA scene `AssetRef`, or an identity string. Omit to reload the active

examples

layers.reload("scenes.arena")

onBeforeLoad(cb: (any) →

Run a callback just before a scene layer loads, while the previous layer's entities are still present.

argtypedescription
cb(anyReceives the scene proxy about to load.

examples

local h = layers.onBeforeLoad(function(scene) print("loading", scene.name) end)

offBeforeLoad(h: number) → boolean return remove

Cancel a `layers.onBeforeLoad` subscription.

argtypedescription
hnumberThe handle `layers.onBeforeLoad` returned.

examples

layers.offBeforeLoad(h)

onLoad(cb: (any) →

Run a callback once a scene layer has loaded — the point where its entities exist and player / camera spawners can attach to them.

argtypedescription
cb(anyReceives the loaded scene proxy.

examples

local h = layers.onLoad(function(scene) print("loaded", scene.name) end)

offLoad(h: number) → boolean return remove

Cancel a `layers.onLoad` subscription.

argtypedescription
hnumberThe handle `layers.onLoad` returned.

examples

layers.offLoad(h)

onUnload(cb: (any) →

Run a callback as a scene layer unloads, while its entities are still addressable — the place to release anything keyed to them.

argtypedescription
cb(anyReceives the scene proxy being unloaded.

examples

local h = layers.onUnload(function(scene) print("unloaded", scene.name) end)

offUnload(h: number) → boolean return remove

Cancel a `layers.onUnload` subscription.

argtypedescription
hnumberThe handle `layers.onUnload` returned.

examples

layers.offUnload(h)

onEntityChanged(cb: (any) →

Subscribe to authored entity changes. The callback runs once per frame with every entity edited since the previous frame, batched by layer as `{ { scene = string, entities = { string } } }` — a moved transform, an edited component field, a spawn, or a despawn (the id of a despawned entity arrives with `entity.exists` already false). Any number of subscribers can watch the same edits. Scope: authored edits in edit mode — what lands in the scene's dirty overlay. Mutations a component makes from its own `update` are runtime behavior and do not appear, so a subscriber that rebuilds derived data cannot re-trigger itself.

argtypedescription
cb(anyCalled with the change batch.

examples

layers.onEntityChanged(function(batch)
for _, row in ipairs(batch) do
for _, id in ipairs(row.entities) do print("changed", id) end
end
end)

offEntityChanged(h: number) → boolean

Remove a subscription made with `layers.onEntityChanged`.

argtypedescription
hnumberThe handle returned by `layers.onEntityChanged`.

examples

layers.offEntityChanged(handle)

withActiveLayer(sceneGuid: ?, fn: ?) → void

Internal: dispatchers exposed to other engine-side modules (the step-10 spawners + scene-load hooks) that need to fire the registries without going through `M.load` / `M.unload`. Both the global registry AND the proxy's per-scene `:on_load`/`:on_unload` subscribers fire. Each dispatcher sets `__layers.setActive(guid)` for the duration of the callback fan-out so any `entity.spawn` / `component.add` issued inside a subscriber attributes the new entity to THE LAYER THIS DISPATCH IS FOR. Without this, entities spawned by a scene entrypoint's `onLoad` land in whatever layer was active when the load started, making `proxy:unload()` unable to evict them. The string passed to `__layers.setActive` is the scene's guid — the same value `SceneOwner.scene` carries for entities in this layer.

argtypedescription
sceneGuid?
fn?

fireProxyList(proxy: ?, list: ?, listName: ?) → void

argtypedescription
proxy?
list?
listName?

fireProxyOnLoad(proxy: ?) → void

Fire the mode-agnostic `_onLoadCbs` always, then fire EITHER `_onLoadPlayCbs` (play mode) OR `_onEditLoadCbs` (edit mode) — never both. This is where the scene entrypoint's `onLoad` and `onEditLoad` get dispatched (registered to the gated lists by `scene_loader.runEntrypoint`). Entities created programmatically from a scene entrypoint (its top-level body, `onLoad` / `onEditLoad`, `update`, or any closure / deferred task it defines) are runtime scene setup, regenerated on every load / mode flip — not authored scene data. They are marked `temporary` (excluded from scene/world saves + the dirty overlay) at SPAWN TIME by the entity.spawn FFI, which inherits the `__spawn_temporary` flag stamped on the entrypoint env (see scene_loader.runEntrypoint + resolve_spawn_context in ffi_callbacks.rs). That call-stack mechanism is deterministic regardless of WHEN the spawn runs and covers indirect spawns (e.g. via a spawn helper tool) — it replaced an earlier snapshot-diff here that only caught spawns inside the synchronous onLoad window (deferred / async spawns escaped it). They still despawn on unload normally because LayerUnload reaps by `SceneOwner.scene` (the layer guid they were attributed to), NOT by the temporary flag.

argtypedescription
proxy?

captureNonPersistentLayerSet( ) → void

layerRefLabel(ref: ?) → string

The name a layer's asset ref goes by in a log line: its identity, else its display name, else its path — the same order `M.load` names a scene by.

argtypedescription
ref?

anyNonPersistentLoaded( ) → void

reapDeadLoadSlots( ) → void

True while a scene load still has work in front of it. A load outlives the call that started it — the entities drain, `awake()` settles, the load fan-out runs — and `loadInFlightCount`, the counter `M.loadInFlight()` publishes, is raised across that whole window. `__scene_load.inProgress` covers a loader pass a caller brackets on its own (the dirty hot-reload applies a body inside it), which raises no counter of this module's. Release every claim — the in-flight slot and the scene-load gate — whose owner can no longer settle it. A teardown cancels the tasks of the env it sweeps, and a cancelled task stops mid-flight without unwinding, so the settle a cancelled load or join carries never runs. Two readings say the owner is finished with the claim: the coroutine reads `dead`, or the scheduler reports a terminal status for the task that coroutine belongs to. The second is the one a cancelled task answers — its coroutine stays `suspended` for the rest of the session — and short of it the slot would hold `loadInFlightCount` raised for that whole session, with `M.rebuildInFlight` telling every later caller a scene is still converging. Run by the readers, so a wait on the counter never spends its budget on a load that no longer exists to finish.

sceneLoadInFlight( ) → boolean

waitForSceneLoadToSettle( ) → boolean

Let a load that is already running finish, and answer whether it did. A pass that unloads mid-load leaves the loader draining entities into a layer the transition has taken away, and two loads of the same scene interleave — the entities of one land under the other, and a native row an `awake()` inserted is dropped by the teardown of the load that started first. Bounded, so a load that never settles delays one pass rather than stalling every flip after it.

reportUnrestoredOverlayContent(target: ?) → void

argtypedescription
target?

heldAsTemplate(id: string) → any

argtypedescription
idstring

instanceLabel(typeName: string, instanceName: string?) → string

Each component INSTANCE the entity came back with: the type for its anonymous instance, and the type with the instance's name in brackets for one added under a name.

argtypedescription
typeNamestring
instanceNamestring?

transitionToLayerSet(target: ?) → void

argtypedescription
target?

avatarReady(root: ?) → void

argtypedescription
root?

claimFlipTeardowns( ) → void

releaseFlipTeardowns( ) → void

recordCarried(mode: string) → void

Put what the unloads of a pass kept into the record of the scene the pass loaded back. An entity a caller made after the write is work of the mode the flip entered, and in edit that work belongs in the scene's record. The mark its creation left may have reached the writer while the layer stood between its unload and its reload, with no scene folder to be recorded in, so it is marked again here, once the pass has loaded the layer and closed the swap. In play what a pass kept is the play session's, which the record never holds.

argtypedescription
modestring

runFlipConvergence( ) → void

Materialise the layer set the engine's CURRENT mode calls for, and keep materialising until it is the live one. The mode flag flips SYNCHRONOUSLY in the setter while a transition takes many frames (unload + reload + player/camera settle). So the mode can change again mid-run, leaving the layer set materialising the mode the engine has already left — in play the loader drops every PlayerPrototype subtree, so a run that stops there hands edit mode a scene with no prototypes and every PlayerSpawn pointing at a missing entity. Re-check after each pass and transition again until the layer set is the one the engine's current mode calls for.

ensureModeFlipWatcher( ) → void

fireProxyOnUnload(proxy: ?) → void

`_onUnloadCbs` fires unconditionally. Engine-managed teardown (entity despawn, resource cleanup) runs separately from the user's on_unload hook — the latter is purely additional cleanup the author wants to attach, not the load/unload pair's lifecycle teardown.

argtypedescription
proxy?

setProxyState(proxy: ?, state: ?) → void

Transition a scene proxy's observable lifecycle state (`proxy.state`) and keep the `loaded`/`ready` boolean conveniences in lock-step. When the proxy first reaches "ready", fire its latched `onReady` subscribers exactly once. Idempotent: a repeated set to the current state no-ops (so it never double-fires onReady).

argtypedescription
proxy?
state?

republishProxyOutcome(proxy: ?) → void

Republish a layer's load failures onto the proxy so the layer's own state carries them: `ok` false, `failures` the records, and `state` "partial" once the layer has settled. Called after every write into the load record, so a failure that lands after the settle (a per-frame `update` that raises) moves the layer off "ready" the same way one raised during the load does.

argtypedescription
proxy?

fireBeforeLoad(proxy: any) → nil

Announce that a scene layer is about to load: clears any pending unload for that layer slot, marks the proxy loading, and fans out to every `layers.onBeforeLoad` subscriber. The scene-load pipeline calls this.

argtypedescription
proxyanyThe scene proxy about to load.

examples

layers.fireBeforeLoad(sceneProxy)

fireLoad(proxy: any) → nil

Announce that a scene layer has loaded, fanning out to every `layers.onLoad` subscriber. The layer is pinned as the active one for the duration of the fan-out, so entities a subscriber spawns are attributed to it rather than landing orphaned. The scene-load pipeline calls this.

argtypedescription
proxyanyThe loaded scene proxy.

examples

layers.fireLoad(sceneProxy)

fireUnload(proxy: any) → nil

Announce that a scene layer is unloading: fans out to every `layers.onUnload` subscriber, then drops the layer's cached proxy and per-layer state so the next load of that scene rebuilds from disk. The unload path calls this.

argtypedescription
proxyanyThe scene proxy being unloaded.

examples

layers.fireUnload(sceneProxy)

install( ) → nil

Install the `layers` global. `layers.active` is exposed as a property whose every read resolves the current root scene, so it tracks scene changes without manual invalidation; other keys resolve against this module. The prelude calls this once at boot.

examples

layers.install()

__index(_: ?, k: ?) → void

argtypedescription
_?
k?

__newindex(_: ?, k: ?, _: ?) → void

argtypedescription
_?
k?
_?

observe( ) → SceneObservation

What every scene load did, and what each loaded scene costs. One read covering the last load's report (what it produced, what it replaced, what it failed to produce and why, and how long each phase took), the load and unload history, a per-layer inventory of what the engine attributes to each layer, and the per-frame cost of each layer's entrypoint tick. Answers in edit mode as well as play.

examples

local o = layers.observe(); print(o.lastLoad.outcome, o.lastLoad.durationMs)
for _, c in layers.observe().cost do print(c.name, c.avgMs) end

lastLoad( ) → SceneLoadReport

The most recent load's report: what it loaded, what root it replaced and which overlays went with it, the entity counts on each side, how long each phase took, and every failure it produced. Nil on an engine that has loaded nothing — which is how "nothing has loaded" reads differently from a load that changed nothing.

examples

local r = layers.lastLoad(); print(r.name, r.outcome, r.entities.added)

lastUnload( ) → SceneUnloadReport

The most recent unload's report: the layer it took down under the name it was loaded with, the overlays it cascaded, and the entities that went with them. A guid no longer resolves to a name once its layer is gone, so this is where that name survives.

examples

local u = layers.lastUnload(); print(u.name, u.entities.removed)

loadHistory( ) →

Every load report the engine still holds, oldest first. Bounded — old reports fall off the front, so a long session's memory does not grow with how many times a scene was swapped.

examples

for _, r in layers.loadHistory() do print(r.name, r.durationMs) end

problems(ref: (AssetRef<scene> | string | any) →

What a layer failed to produce, and why. Each entry names the phase it happened in, one reason from the closed set, and the engine's own words — plus the entity, component or lifecycle hook it is about when it is about one. the active root layer.

argtypedescription
ref(AssetRef<scene> | string | anyA scene `AssetRef`, an identity string, or a scene proxy. Omit for

examples

for _, f in layers.problems() do print(f.reason, f.entity, f.message) end

whyPartial(ref: (AssetRef<scene> | string | any) →

Why a layer is not whole. Returns nil when it IS — everything the scene declared was produced — and otherwise the nearest cause from the closed set `loaderRaised`, `entrypointCompileFailed`, `entrypointBodyRaised`, `entrypointRaised`, `buildRaised`, `entityFailed`, `parentMissing`, `parentRefused`, `parentAbandoned`, `componentUnresolved`, `componentRefused`, `subscriberRaised`, `updateRaised`. A second return carries the engine's own words for that cause. the active root layer.

argtypedescription
ref(AssetRef<scene> | string | anyA scene `AssetRef`, an identity string, or a scene proxy. Omit for

examples

local why, detail = layers.whyPartial(); if why then print(why, detail) end

inventory( ) →

What each loaded layer holds: the entities the engine attributes to it, whether it came up whole, and how many failures it carries. `unattributed` in `layers.observe().totals` counts what exists in the world that no layer claims.

examples

for _, l in layers.inventory() do print(l.name, l.entities, l.ok) end

cost( ) →

What each loaded scene's per-frame tick costs, attributed to the layer that owns it — the `update` / `editorUpdate` its entrypoint declares, timed where it runs. `totalMs` is a SUM across the window `layers.observe().window` reports, so divide by `calls` (or read `avgMs`) for the per-tick figure; a tick that runs every frame makes that the per-frame figure. Call `layers.resetCostWindow()` first to time a particular stretch. A layer whose entrypoint declares no tick is absent.

examples

layers.resetCostWindow(); task.wait(1); for _, c in layers.cost() do print(c.name, c.avgMs) end

resetCostWindow( ) → nil

Open a new cost window, discarding what the previous one measured. Call this before timing a stretch of frames; the load history is untouched.

examples

layers.resetCostWindow()
⌬ Types
LoadOpts = {PlayerConfig = {CameraConfig = {LightingConfig = {SceneSettings = {SceneLoadFailure = Observe.SceneLoadFailureSceneLoadReport = Observe.SceneLoadReportSceneUnloadReport = Observe.SceneUnloadReportSceneLayerCost = Observe.SceneLayerCostSceneLayerInventory = {SceneObservation = {

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

Showing up to 3 levels deep. Open a part to see what it holds further down.

90+items
·
assettype · born here
❒asset
# Module (asset type) A module is a reusable, stateless (or globally-stateful) Luau library that other code pulls in with `require()`. Modules are the unit of factored-out logic in a world: helpers, math libraries, format parsers, registries, shared algorithms. ## When to use one - You have logic you want to share across multiple components, services, scenes, or tools. - You have a registry, lookup table, or shared cache that callers all read from / write to. - You want a stable API surface (`M.fn`) other code can depend on. If the logic is bound to one entity, use a `.component`. If you want a named UI of fields rather than functions, use a `.preset`. ## Where it lives - Source: `/zero/source/.../<name>.module/` - Identity: the source path with `/` written as `.` and each segment's type suffix dropped — `/zero/source/demo/beats.module` is `demo.beats`, and `/zero/source/kit.package/beats.module` is `kit.beats`, the container's name kept and its `.package` suffix gone. `asset.create` returns this string, `asset.resolve(...).identity` reads it back, and the `require` forms below write it as `<identity>`. - Folder shape: - `init.luau` (or `init.lua`) — module body. **Required.** Returns a table (conventionally named `M`). - `README.md` — instance-level documentation. **Required.** - `.metadata` — agent-editable tags + free-form fields. **Required.** ## How to create one ```luau asset.create("module", "<name>") -- Creates: /zero/source/<name>.module/ -- init.luau (canonical `local M = {} … return M`) -- README.md (instance README template) -- `folder` places it in a subfolder of /source, and that subfolder -- leads the identity: `{ folder = "lib" }` produces `lib.<name>`. -- `into` authors it inside a resolved container (a package, a toolbox), -- whose own identity leads the same way: asset.create("module", "<name>", { folder = "lib" }) asset.create("module", "<name>", { into = asset.resolve("myPkg.package") }) ``` ## How it operates 1. **Registration.** Writing `init.luau` into a `.module/` folder indexes the asset and registers the module path with the resolver. 2. **Loading.** The first `require("<identity>")` runs the file's body and caches the returned table. Subsequent requires from anywhere return the **same table** — this is the shared-state lever for "module-local" registries. The body runs in an environment of the module's own: a name it declares without `local` is readable by the module's own functions and by no other script, so an export reaches its callers through the returned table and nothing else. Requiring a component's folder runs its chunk the same way, once, and its `update`, `start` and `public` stay in that environment; a component runs on an entity through `entity(id).component.add(name)`. 3. **Hot reload.** Editing the file re-runs the module body and folds what it returns into the table already loaded, so that table keeps its identity: a caller that captured it with `require` reads the new source's functions and values through the reference it already holds, and a later `require` returns that same table. A key the new source drops goes away; a key something set at runtime stays. The body's own `local`s start again from their initial values, so state that must outlive an edit lives in `modules.state()` (`guides { path: "core/scripting-and-tasks" }`). 4. **Identity resolution.** A module is reached by its `<identity>`, and where the caller lives decides which spelling of it resolves. For a module in a **world**, from a caller in that same world — another module, a component, a scene entrypoint, or an `execute` chunk: - `require("<identity>")` — the identity on its own, resolved against the caller's own root. It carries every folder segment, so a module created with `{ folder = "demo" }` is `require("demo.beats")`. - `require("@root::<identity>")` — the same root-relative resolution, written out. - `require(".sibling")` — a module in the same folder, by its bare name; `..name` steps up one folder, `...name` two. Logs, stack traces and hot-reload notices name that same module `@local.source.<identity>` — its key under the world source root. The `<identity>` tail of that key is the form above, so a trace reading `@local.source.demo.beats` is `require("demo.beats")`. For a module in a **library** — content under `/zero/source/libs/@<lib>/` — `@<lib>::` addresses that library's root from anywhere: `require("@builtin::modules.transform")`. Mounting a world as a library moves its files under such a root and flips the caller root to `@<lib>::`, which is what keeps the root-relative forms above resolving across the move. ## Discovery - `asset.list("module")` — every registered module. - `asset.inspect("<name>")` — public functions, source path, this type README. - `ls /zero/source/<name>.module` lists the files the folder holds. ## Authoring conventions - Return a single `M` table from `init.luau`. Top-level statements with side effects run on first require — useful for one-time initialization, dangerous if they touch the engine before it's ready. - Write exported functions as `typed function`, not `function`: the argument types are enforced at the call and the checker knows the signature, so a caller's mistake is reported where they made it. - Annotate exported functions with `--!desc` / `--!arg` / `--!return` / `--!example` so the LSP, `tools.list`, and `asset.inspect` surface them. A function with no `--!desc` is reachable only by someone already reading this file. - Declare a VALUE with `Field.<kind>(default, mode, description)`, and a table whose members are reached through a metatable with `--!members <TypeName>` — the latter gives the surface its accepted member set, its type, and its documentation from one table. See `guides { path: "core/authoring" }` for all four rules and `modules/api/engine/entity.module/members.module` for a worked member table. - Keep module state in module-local upvalues or in `modules.state()`. A name the body declares without `local` lives in the module's environment, which every run of the module shares: a function the previous run left in place reads what the reload assigned. Module-locals start again from their initial values with each hot reload; the table `modules.state()` returns is the same table on both sides of every reload. - Prefer focused modules over kitchen-sink modules. If two halves of a module have no shared state, split them. ## Common pitfalls - **Cyclic requires.** A `require` chain that loops will return the partial table (the half built before the cycle was detected). Design for one-way dependencies. - **Engine-time side effects.** Don't `entity.spawn` at module top-level — the engine may not be ready. Expose an `M.init` and call it from a scene entrypoint. - **Hot-reload + module-local cache.** A module that caches expensive computation in upvalues loses that cache on reload — fine for dev, but be aware in performance work. - **`init.lua` vs `init.luau`.** Either works, `.luau` is canonical. - **Writing one while play runs.** A `/source` write made while play is running lands on the play shadow, and a guarded play-exit discards it unless it is kept. One `.module` write shadows `init.luau`, the `README.md` and the `.metadata` together. `vfs.write(path, bytes, { durable = true })` skips the shadow, and `vfs.promotePlayShadow` keeps what is already on it — the `core/vfs` guide has the model and what each route costs. ## Related types - `.component` — for entity-bound state + lifecycle hooks. - `.service` — generates content you don't have yet (a mesh, sound, texture, …) via a metered provider. - `.tool` — for a single agent-callable function with a YAML schema. - `.package` — to group several modules + components + scenes into one shippable folder. ## In the Inspector Exports: what the module exports (name, kind, signature), parsed from its source without running it, with **Check** (the LSP's diagnostics for its entry file) and **Open**.
▲ 0↑ born
▣
module · born here
❒asset
# scene_observe The record of what a scene load did, and what each loaded scene costs. Backs `layers.observe`, `layers.lastLoad`, `layers.lastUnload`, `layers.loadHistory`, `layers.problems`, `layers.whyPartial`, `layers.inventory`, `layers.cost` and `layers.resetCostWindow`, and the `scene` toolbox's `observe`, `whyPartial` and `cost` above them. `layers` and `scene_loader` are its writers. ## One record per load A load opens a record; the loader, the lifecycle dispatchers and the scene's own build write their failures and phase timings into it; the load's own completion point closes it with the duration the engine already measured for its `DONE` line. Reading is lazy — nothing here walks the world, and the only writer that runs every frame is `noteUpdate`, which the entrypoint tick calls once per scene that declares one. ```lua local r = layers.lastLoad() print(r.name, r.outcome, r.durationMs) print(r.entities.added, "arrived,", r.entities.removed, "left") print(r.phases.teardown, r.phases.instantiate, r.phases.settle) ``` `outcome` is `"ok"` when everything the scene declared was produced, `"partial"` when the load finished with failures in it, `"failed"` when the load raised and left no layer, and `"unchanged"` when the scene asked for was already the active root — that load rebuilt nothing, so the layer keeps the record of the load that built it and still answers why it is not whole. `reason` names the nearest cause from the closed set — `loaderRaised`, `entrypointCompileFailed`, `entrypointBodyRaised`, `entrypointRaised`, `buildRaised`, `entityFailed`, `parentMissing`, `parentRefused`, `parentAbandoned`, `componentUnresolved`, `componentRefused`, `subscriberRaised`, `updateRaised` — ranked so it names the thing to fix rather than the last thing to break. ## Failures reach the layer they belong to Every write of a failure calls the subscriber `layers` registers through `M.onFailure`, which republishes the record onto that layer's proxy: `ok` false, `failures` the records, and `"partial"` in place of `"ready"` once the layer has settled. A tick that starts raising on frame 400 moves the layer the same way one raised during the load does. A failure identical to one already held raises that one's `count`, so a tick raising every frame keeps one record. `FAILURE_LIMIT` bounds the distinct records a report holds, and `failuresOmitted` states how many arrived past it. ## Cost `noteUpdate` accumulates each layer's entrypoint tick into a per-guid entry — calls, total, last, max, average and how many raised — summed across the window `M.window()` reports. `M.resetWindow()` opens a new one, leaving the load history alone. An unload drops the layer's entry.
▲ 0↑ born
▣
module · born here
❒asset
# modules.api.engine.dirty_hot_reload Picks up dirty-overlay changes from disk while a scene is loaded in edit mode, applies them to the live entities, and keeps the in-memory representation in lockstep with `scene_dirty/` files. Pairs with `scene_saver` (writes deltas) + `scene_loader` (composes canonical + overlay at load time). ## Parents A record's `parent` names the entity it stands under: the entity whose id is that text, else the entity whose display name is exactly that text. A `*` or `?` in it is a character of the name, never a pattern. A record whose parent no entity provides waits. An entity that does not stand yet is not built, one that already stands keeps its state, the layer logs the record once, and `debugState(guid).waiting` maps its id to the parent it names. While a record waits, the scene saver leaves it as it stands rather than writing a standing entity's older state over it, until an author edits that entity, which the saver then records as it stands. When a record builds an entity, the records waiting on that entity's id or display name are built under it, so a child record that arrives before its parent's record lands where a load of both places it. Each waiting record is built as its overlay file states it at that moment, so a record rewritten while it waited, including by this session's own saver, builds from its current bytes. A load gives the same account of a record whose parent stays missing: the loader abandons it with `parentMissing`.
▲ 0↑ born
▣
module · born here
❒asset
# renderer GPU-resource factory plus CPU codec/store wrappers — the GPU/CPU half of the asset↔resource split. Moves a resource Disk → CPU → GPU in explicit steps and returns inert handles describing each live resource. assetType behaviours, components, and every other module call `renderer.*`. A resource moves through three states, each an explicit call: - `ref:load()` → `renderer.<res>.loadCpu(ref)` decodes the asset's primary content into the guid-keyed CPU store and returns a CPU handle (holds only a guid plus dims/counts and the read/encode/unload ops). - `renderer.<res>.create(cpuHandle | rawData, guid?)` uploads CPU → GPU, keyed by guid, and returns a GPU handle. `create` never takes an `AssetRef` — load the CPU first. - `renderer.destroy(handle)` frees the GPU resource; a CPU handle's `:unload()` frees the CPU copy. A `MeshHandle` / `TextureHandle` / `MaterialHandle` is an inert data record (`{ kind, category, guid, name, ... }`) describing one live GPU resource. Every GPU op lives on `renderer.*` and takes the handle. Anywhere a call names a resource it takes any of the forms you already hold — the handle `create` returned, the CPU handle `loadCpu` returned, the guid, or the `AssetRef` `asset.resolve` returned. Handles compose: what one call hands back, the next call accepts. ## Types - `Aabb` — `{ min = {x,y,z}, max = {x,y,z} }`. - `MeshHandle` / `MeshCpuHandle` / `MeshGeometry` / `MeshBuffers`. - `TextureHandle` / `TextureCpuHandle` / `TexturePixels`. - `MaterialHandle` / `MaterialContent`. ## renderer.mesh - `encode(geom) -> string?` / `decode(zmsh) -> (geom?, errmsg?)` — the ZMSH CPU codec. - `loadCpu(ref) -> MeshCpuHandle` — Disk → CPU load (called by `meshRef:load()`). - `create(src, guid?) -> MeshHandle` — create or fetch a GPU mesh from a `MeshCpuHandle`, raw geometry `{positions, indices, normals?, uvs?, colors?}`, compute buffers `{vertexBuffer, indexBuffer, vertexCount, indexCount, aabbMin?, aabbMax?}`, or a `MeshHandle`. - `geometry(mesh) -> MeshGeometry` — the mesh's vertex data, the read that pairs with `create`. - `update(handle, src) -> MeshHandle` — overwrite the GPU resource in place under the same guid. - `readback(mesh, into?) -> MeshCpuHandle`: GPU → CPU recovery of a runtime mesh's geometry. `into` lands the copy under a CPU-store key of the caller's own, which stays resident until the caller unloads it, whatever re-registers or unloads the mesh itself. - `isResident(mesh) -> boolean` / `isCpuResident(mesh) -> boolean`. Geometry moves in four directions, two per axis — DATA the caller holds, and the geometry of a mesh the ENGINE holds: | From | → bytes | → geometry | |---|---|---| | geometry (data the caller holds) | `encode(geom)` | — | | ZMSH bytes (data the caller holds) | — | `decode(zmsh)` | | a mesh the engine holds | `encodeCpu(mesh)` | `geometry(mesh)` | `geometry(mesh)` reads the resident CPU copy when there is one and reads the geometry back off the GPU when there isn't (yielding a frame or two), so a mesh straight out of `create` answers it: ```luau local h = renderer.mesh.create({ positions = P, indices = I, tangents = T }) local geom = renderer.mesh.geometry(h) -- { positions, indices, tangents, ... } ``` An optional stream is present only when the mesh carries one. The GPU vertex layout has no "unset" — it holds a zeroed tangent, a zeroed skin binding, and a second UV set copied from the texture UVs for every mesh — so a stream saying only what its absence already says is reported absent. `geom.tangents == nil` is therefore the answer to whether a mesh has a tangent basis, and `geom.uvs1 == nil` to whether it has a second UV set. ## renderer.texture - `encode(rgba, width, height, opts) -> (string?, errmsg?)` / `encodeFromImage(bytes, opts) -> (string?, errmsg?)` / `decode(ztex) -> (rgba?, width?, height?)` — the ZTEX CPU codec. - `withSampler(ztex, { filter?, wrapU?, wrapV?, anisotropy? }) -> (string?, errmsg?)` — the same payload with only its recorded sampler state changed; every level is byte-identical. - `loadCpu(ref, encodeOpts?) -> TextureCpuHandle` — Disk → CPU load with per-pixel access. - `create(src, guid?) -> TextureHandle` — from a `TextureCpuHandle`, raw pixels `{rgba, width, height, srgb?}`, a `TextureHandle`, or render-target dimensions `{width, height, name?}` (an empty GPU texture a render pass writes into). - `update(handle, src) -> TextureHandle`, `destroy(handle)`, `capture(handle) -> string` (CPU readback result key), `readback(texture) -> TextureCpuHandle`, `isResident(texture) -> boolean`. ## renderer.material - `create(content, key) -> MaterialHandle` — register or update a material's GPU record (`content = { shader, properties, textures, aliases?, name? }`) under its canonical registry key. - `animatedTexture(texture, opts?) -> MaterialHandle` — a material that PLAYS a layered texture: its layers bound as the frames, its timing beside them, the built-in `animatedTexture` shader turning the clock into the layer showing now. One call from an imported GIF / APNG / animated WebP to a material an entity can wear. `guides { path: "topics/animated-images" }` is the whole surface. - `setProperty(key, name, value)` — push one changed uniform. - `setTexture(key, slot, ref)` — push one changed texture slot (the texture must already be GPU-resident). - `destroy(key) -> boolean` — drop the definition filed under `key`, so `describe` and `list` stop answering for it. A surface already wearing the handle goes on drawing it. A `MaterialHandle` and its `guid` are two different currencies. What a surface wears is the HANDLE — `Model:applySessionMaterial(handle)`, or a Model's `material` field. The handle's `guid` is the material's registry key, which is what `setProperty`, `setTexture`, `describe` and `destroy` take. A component field resolves an asset, so a bare registry key in one leaves the component waiting for an asset to register under that name. ## renderer.instanceData Four `vec4` lanes of generic shader data per entity — the channel that lets ONE material serve many entities that differ in a value, instead of one material per entity. A surface shader reads lane `i` back as `input.shader_data[i]`, and the engine attaches no meaning to what a lane holds. - `laneCount() -> number` — lanes per entity, so a lane index runs `0 .. laneCount() - 1`. - `set(target, lane, x, y?, z?, w?)` — write one lane of an entity's block. `target` is an entity proxy or an entity-id string naming a live entity; `y` / `z` / `w` default to 0. The lane reaches the block where the call is made, and the draw on the next frame. - `clear(target)` — drop the entity's whole block, so its draws read zero again. Takes an entity that has already gone, and does nothing for one holding no block. A lane index outside the block, or a target no live entity answers to, is an error at the call rather than a write that lands nowhere. A feature picks the lane indices it owns and names them where it writes them: `@builtin::systems.globalIllumination.lightmap` holds lane 0 for a receiver's atlas rect and lane 1 for its layer and enable flag, which is the shape to copy. The same lanes reach a GPU-driven population through `renderer.mesh.drawInstanced`'s `instanceDataBuffer`, on slots no entity owns. ## renderer.featureTexture The texture analogue: a shared `rgba16f` 2D array every surface shader can sample as `zero_feature_texture(uv, layer)`, and the array a `SpotLight` projects a layer of through its cone via `cookieLayer`. - `configure(width, height, layers)` — size the array. A call for the size it already has is left alone; one that changes the size reallocates, and the replacement is zeroed, so it empties every layer in the array — the layers other features and other cookies own along with your own. - `setLayer(layer, textureKey, x, y)` — copy a GPU-resident `rgba16f` texture into one layer at that offset, GPU to GPU with no readback. Several small images pack into one layer at different offsets. - `state() -> { width, height, layers, filled, fills }`: the extent the array carries and `filled`, the ascending 0-based indices of the layers a fill has landed in since it was last sized. One array is shared by every feature and every light cookie, and it has no allocator, so this is what a feature asks to tell whether the array it sized and filled is still the array it is writing into. A layer some other `configure` emptied leaves `filled` without it, which is what separates that from a fill that never landed. What it describes is the array a shader samples: the source texture a `setLayer` copied from is a GPU resource of its own and keeps the bytes it was written with, so `filled` is the reading that answers whether the layer behind a `cookieLayer` is live right now. `fills` counts the fills that have landed in each layer since the array was last sized, `fills[layer + 1]` for a 0-based layer: a fill of a layer already holding content leaves `filled` as it was and moves this count, so a feature re-filling its own layer reads its fill arriving here. Measured at the end of the last rendered frame, like every reader below. ```luau renderer.featureTexture.configure(256, 256, 4) renderer.featureTexture.setLayer(0, "my_gobo", 0, 0) -- ... elsewhere in the scene, another feature sizes the array ... local ft = renderer.featureTexture.state() if ft.width ~= 256 or table.find(ft.filled, 0) == nil then -- layer 0 was emptied under us: size it back and re-fill. end ``` ## Reading back what the renderer did Every call above states an intention. What the renderer made of it is a separate document, published once per frame and read through these: - `drawDiagnostics() -> { DrawDiagnostic }` — every renderable that is NOT drawing what its material says. A surface rendering as the magenta placeholder, one the renderer could bind nothing for, and one drawing a program whose most recent compile failed all land here, each naming the entity, the program asked for, the program bound, and the one cause. It covers every renderable the renderer holds, whether or not a camera reached it — a row with `observed = false` and `outcome = "notDrawn"` is the renderer's own resolution for one this frame drew nowhere, so a broken surface off-screen reads the same as one in frame. An empty result means every renderable the renderer holds is drawing the program its material named. **Start here when a surface looks wrong.** - `material.renderState(key) -> MaterialObservation?` — the blend / cull / topology / queue / depth key the renderer holds a material under, and whether a pipeline exists for it. `nil` means the renderer holds no material under that key, which is what writes reaching nothing on screen look like. `index` is the material index its row is filed under, and `textures` the texture key each slot of that row names, so a `setTexture` the renderer has taken up reads there. - `materialCost() -> { MaterialObservation }` — draws, instances, placeholder draws and material-owned bind groups (`binds` set, `bindsElided` skipped) per material, over the published frame. - `shaderCost() -> { ShaderCost }` — pipeline build time and permutation count per program, summed since engine start, beside the compile gate's word. - `observe() -> RenderObservation` — the whole document the four above read. `/zero/runtime/generated_materials` serves the same document as files. ## renderer.destroy - `destroy(handle) -> boolean` — free the GPU resource behind a `MeshHandle` / `TextureHandle`, routing by the handle's `category`. ## Parts The module is a folder of parts, each a module of its own that `init.luau` requires: - `renderer.refs`: guid minting and the coercion from whatever names a material, mesh or texture to the key the renderer indexes it by. - `renderer.sources`: the `src` shapes `renderer.mesh.create` / `update` and `renderer.texture.create` / `update` take, and the bounds and counts raw geometry implies. - `renderer.shading`: the readings `renderer.shadingOf` builds out of the document the renderer publishes. ## Usage ```luau local renderer = require("@builtin::modules.api.engine.renderer") local gpu = renderer.mesh.create({ positions = { ... }, indices = { ... } }) renderer.destroy(gpu) ```
▲ 0↑ born
▣
module · born here
❒asset
# `scene.shared.loader` Luau-side scene loader. Reads `scene.json` v6, dispatches to engine FFIs, runs the sibling `entrypoint.luau`. ## Public surface ```lua local loader = require("@builtin::assetTypes.scene.shared.loader") loader.load(ref, opts?) -- ref: AssetRef<scene> | identity string | VFS path -- opts.layer: layer name (default "main") -- Returns: the Scene proxy (with player_config + camera_config attached). loader.unload(layerName) -- Wrapper around layers.unload(name); symmetric to M.load. -- Cannot unload "main". ``` ## Behavior 1. Resolve `ref` to a VFS path; append `/scene.json` if needed. 2. `vfs.read` + `Json.decode` (from `modules.json`) → body table. 3. Version check — refuse anything but `version: 6`. 4. Attach `body.player` + `body.camera` to the Scene proxy as `player_config` / `camera_config` (consumed by player_spawner + camera_spawner). 5. Activate the target layer via `layers.find(layerName)` (the loader threads the layer through `entity.spawn` opts), spawn `body.entities` in two passes (shells + transforms first, parents + components second), then restore the previous active layer. 6. Apply `body.lighting` via `lights.setup` + `lights.addPointLight`. Field name mapping: `directional` → `sun`, `clear_color` → `clearColor` (both engine API names and v6 field names are accepted). 7. Auto-discover sibling `entrypoint.luau` via `vfs.exists`; if present, compile with `loadstring` + run. ## Performance ~5 ms for a 1000-entity scene (≈5k FFI calls × ~1 µs each). Acceptable for a load-time operation. If a particular call class becomes hot, batch primitives can be added in a narrow follow-up. ## Why pure Luau Per § 10 of the unification integration design, the scene format is data + dispatch — no Rust-only primitives needed. The existing ECS FFI (`entity.spawn`, `entity(id).component.add`, etc.) covers everything. Keeping the loader in Luau means iteration speed, auditability, and hot-reload. ## FFI corrections vs. the original plan The plan was drafted against assumed API names. The actual engine FFIs differ: | Plan assumed | Actual engine API | |---|---| | `json.parse(s)` | `require("..json").decode(s)` (`modules.json`) | | `json.encode(t)` | `require("..json").encode(t)` | | `entity.spawn(n, { layer }).id` | layer activation via `layers.find(layer)` + `entity.spawn(n, opts).id` | | `entity.setParent(id, pid)` | `entity(id).setParent(pid)` | | `unloadLayer(name)` | `layers.unload(name)` | | `lights.setup({ directional })` | `lights.setup({ sun })` | | `lights.setup({ clear_color })` | `lights.setup({ clearColor })` | | `lights.addPointLight(table)` | `lights.addPointLight(name, x, y, z, opts)` | The loader accepts both the v6 field names and the engine API names for the lighting fields so that round-tripping through the scene saver and back works without a conversion step.
▲ 0↑ born
▣
module · born here
❒asset
# entity_records Walks a live entity hierarchy into the flat record array the engine's entity templates use — `{ name, original_id, parent_id, position, rotation, scale, hidden, components }` per entity, root first, parents before children. `bundle` composes its `entity_template` through this module; scene builds compose their baked output through it. One record shape, one implementation. `compose(rootId)` walks one hierarchy. `composeMany(rootIds)` walks several, which is what a build needs — a builder may leave more than one unparented root. Temporary descendants are pruned; an explicitly-named temporary root is kept. `compose(rootId, nil, nil, true)` keeps the temporary descendants too, so the records hold every entity under the root.
▲ 0↑ born
▣
module · born here
❒asset
# modules.api.engine.players The curated player surface. Wraps the raw `UserIdentity` component proxy in a view that exposes only the safe authoring API: `.isLocal` / `.avatar` / `.ready` / `.userId` / `.identity` / `.displayName`. `.avatar` is the visible body's entity REF (a live proxy), or nil until a body is bound — act on it directly (`player.avatar.position = { x, y, z }`). Want the id? `player.avatar.id`. Assign a live entity ref to bind it as the body — `player.avatar = entityRef` (assign nil to clear) is the one path that binds a body to the player. `.entity` / `.entityId` / `.id` / `.component` are intentionally REFUSED. The identity entity is a internal anchor with no world presence — reach the visible body via `player.avatar`. Position writes always target the avatar. Used by every `layers.active.players.localPlayer` / `onLocalReady` / `playerJoined` / `playerLeft` call site so user scripts can't reach past the curated wrapper into the underlying component proxy.
▲ 0↑ born
▣
module · born here
❒asset
# client_follow Carries a world or branch switch, or a root scene opened, in an agent's own client over to the user's client. `zeromind.swap`, `world.checkout` and `zm checkout` call `ClientFollow.after(request, opts.follow)` once their switch has landed, and `layers.load` of a root scene calls `ClientFollow.afterScene(request, opts.follow)` once the scene has loaded. ```lua local ClientFollow = require("modules.client_follow") ClientFollow.after({ world = guid, branch = "feature" }, nil) ClientFollow.afterScene({ scene = sceneGuid, name = "scenes/level2.scene", world = guid, branch = "main" }, nil) ``` - `follow = false` asks nothing; nil asks, and the host follows from an agent's own default sub-client; true asks, and the host also follows from a sub-client the agent made with `client create`. - Only the world, the branch and the version are carried; the user's client keeps its own play/edit mode. - The host answers at once: `{ followed = true }` when it took the switch on and `{ followed = false, reason }` when the call is not one the user's client follows (the user's own client, another agent's sub-client, a call of no agent, a switch to where the user's client already is). It makes the switch on its own time; a switch it could not make is told to the calling agent as a notice, and the engine state's `split` lists the sub-client until the user's client has caught up. - A host that cannot be reached raises, and the error says the switch was made in this client. - An engine with no client control, and code with no caller, follow nothing and answer nil. - A scene follow carries the scene's guid and name and the world and branch it was opened on; the user's client opens it once it is on that world and branch, in its own play/edit mode. `follow = false` is told to the host, and a scene open the user's client does not follow (said not to, refused, or failing there) reaches the owning agent as a notice naming the scene the user's client stayed on. `state.split` lists a sub-client on another scene than the user's client.
▲ 0↑ born
▣
module · born here
❒asset
# player_prototype_spawn The deterministic spawn core for authored player prototypes. A PlayerSpawn entity names a PlayerPrototype subtree to instantiate; `spawnFor` clones that subtree from its captured authored template, prunes clone-subtree nodes whose networkScope excludes the caller's owner/authority role, marks the clone RuntimeOnly, and turns the clone root into the joining user's hidden UserIdentity, named `user` like every user identity (the prototype keeps its own name, so a lookup by that name reaches the prototype), plugging it into the players registry, join/leave, ownership, and sync. The body named by `PlayerPrototype.body` is adopted as the user's avatar and placed at the PlayerSpawn's world transform; the prototype's CameraRig follows it. `installJoinHook` wires `spawnFor` to a scene's user-join event so a joining user is placed automatically. Location: `src/lua/lib/modules/api/engine/player_prototype_spawn.module`
▲ 0↑ born
▣
module · born here
❒asset
# mode_flip_guard Two tiny cross-module transient signals about the edit↔play mode flip: - **owned** — "the `layers` module currently owns the mode-flip reset, so the `player_spawner` / `camera_spawner` `onModeChange` watchers should stand down." - **in flight** — "a mode-flip transition is materialising the scene right now, so the live entities are a partial rebuild of it." Formerly `_G.__zero_layers_owns_mode_flip`. Moved off `_G` ahead of the read-only `_G` seal — the flags are runtime writes (set when `layers` drives a mode flip), which would break under a sealed `_G`. `require()` is cached per VM, so the module-local upvalues are shared state across every requirer within a VM — exactly the cross-module reach the old `_G` key provided. - **Setter**: `layers.module` claims ownership before any flip, and raises the in-flight signal for the span of the transition it runs. - **Readers**: `player_spawner.module`, `camera_spawner.module` stand down while owned so the player/camera respawn happens exactly once via the `layers` transition's reload fan-out (not a second time from their own `onModeChange` watchers); `playerSetupValidation.module` judges the authored scene once the transition has settled. ## Surface | Symbol | Notes | |---|---| | `M.setOwned(v: boolean)` | Set whether the layers module owns the current mode-flip reset. | | `M.isOwned() -> boolean` | True while the layers transition owns the flip; spawners stand down. | | `M.setInFlight(v: boolean)` | Set whether a mode-flip transition is materialising the scene. | | `M.isInFlight() -> boolean` | True for the span of the transition; the live entities are a partial rebuild of the scene. |
▲ 0↑ born
◇
component · born here
❒asset
# Camera Manages viewport priority, render-to-texture, and capture. State is stored in the native `Camera` ECS component; the Rust camera system handles render scheduling and render targets. Public fields: `fov`, `near`, `far`, `priority`, `textureHandle` (the guid of the texture the camera renders into; empty = main viewport), `renderLayers` (which render layers this camera draws — a space-separated spec of names, e.g. `"all"`, `"all !ui"`, or `"default sky"`; `ui`/`sky`/`debug`/`EditorUI` are built-in layers), `postProcessing` (whether this camera runs the post-process chain), `debugChannel`, plus the behavior slot below. Methods: `:lookAt(target)` (entity id string OR `{x, y, z}` table), `:render()`, `:capture()`, `:setTargetTexture(tex?)` (a `renderer.texture.create` handle to render into, or nil for the viewport). ```luau entity(id).component.add("Camera", { fov = 90, priority = 10 }) entity(id).component.get("Camera"):capture() ``` The scene's play-mode camera is reached as `layers.active.camera`, a handle that reads and writes the fields above on whichever entity currently carries them. `layers.active.camera.entity` is the entity ref for that camera and `layers.active.camera.entityId` its id string, so a script that needs to attach something to the camera — an `AudioListener`, a child entity — goes through the ref: ```luau local cam = layers.active.camera cam.fov = 70 -- the camera's settings cam.entity.component.add("AudioListener") -- the entity carrying them ``` ## How the camera moves: `behavior` and `follow` A `Camera` does not move itself. `behavior` names a component that does, and setting it attaches that component to this entity. Clearing it detaches whatever was attached. ```luau local cam = entity(id).component.get("Camera") cam.behavior = asset.ref("@builtin::controller.orbital_follow", "component") cam.follow = playerBody ``` The attached behavior is an ordinary component on the camera's entity, so it is tuned the way any component is: read it with `component.get` and set its fields there. A `component.add` of the same type configures the instance the slot attached instead of adding a second one: the values it passes are written onto that instance and its proxy is returned. That add is the form a scene `build.luau` tunes the behavior with, because its values are saved with the scene and the loaded Camera's behavior takes them back. A key the component reads only as it is created (one of its `initKeys`, a private field) refuses the add and names the key. ```luau cam.behavior = asset.ref("@builtin::controller.third_person_follow", "component") local rig = entity(id).component.get("third_person_follow") rig.cameraDistance = 6 -- the same, as an add of the type the slot attached entity(id).component.add("third_person_follow", { cameraDistance = 6 }) ``` `follow` is the standard slot every shipped behavior reads. Set the follow target on the **Camera**, not on the behavior, so swapping behaviors keeps it. A behavior that finds its own `follow` field empty falls back to this one, which is what lets a rig keep tracking the player across a behavior swap. `followResolves` answers whether that slot names an entity that is live — `true` while it names a live one or names nothing at all, `false` once the target is despawned or the id names no entity. A rig whose target does not resolve holds its last pose, and this is the field that tells it from a rig posed correctly on a subject that has not moved. `camera.get` carries the same value beside `follow`, and a write naming an id with no entity behind it draws a warning where it lands. ```luau cam.followResolves -- false once the followed entity is gone tools.use("camera", "get", id).followResolves -- the same answer off the tool ``` The shipped behaviors live under `@builtin::controller.*`: `orbital_follow`, `third_person_follow`, `first_person`, `free`, `orbit`, `chase`, `isometric`, `rts`, `birds_eye`, `side_scroller`, `cinematic`, `menu`. ## Writing your own Any component can be a camera behavior. Write one that moves its own entity and attach it the same way: ```luau cam.behavior = asset.ref("MyChaseCam", "component") ``` `follow` lives on the Camera, so a behavior gets no property notification of its own when the target changes. Declare `onFollowChanged(newFollow, oldFollow)` to be told the moment it does — the Camera calls it on the component it attached, which is what lets a rig re-pose on the new subject at once. A behavior that reads `Camera.follow` on its own schedule declares nothing and is attached the same way. ```luau typed function public:onFollowChanged(newFollow: any, oldFollow: any) -- pose this entity against the new target end ``` To make it appear in the discovery catalog alongside the shipped ones, declare the `cameraBehavior` tag in the component's `.metadata`: ```json { "tags": ["cameraBehavior"] } ``` The tag governs **discovery**, not attachment. A tagged component is listed by `layers.active.camera.behaviors` and is what tooling offers when something asks "which camera behaviors exist"; an untagged component attaches just as well and simply stays out of that list. Tag the ones you want other people (and agents) to find. ```luau for name, ref in pairs(layers.active.camera.behaviors) do print(name, ref.identity) end ``` ## Texture colour space `textureColorSpace = "display"` applies the display transform when rendering into a texture. `"linear"` writes scene-linear values instead. `postProcessing` independently controls the effects chain in either mode. Floating-point targets retain values above one; normalized targets clamp to their representable range. The main viewport uses display encoding.
▲ 0↑ born
▣
module · born here
❒asset
# `scene.shared.saver` Luau-side scene saver. Writes `scene.json` v6 — **authored intent only**. No captured runtime state. ## Public surface ```lua local saver = require("@builtin::assetTypes.scene.shared.saver") saver.save(name, opts?) -- name: logical scene name ("main") OR full VFS path -- opts.layer: layer name to read from (default layers.active.name or "main") -- Returns: the absolute VFS path written. ``` ## What is captured | Field | Source | Notes | |---|---|---| | `format`, `version` | constants | Always `"scene"` + `6`. | | `entities` | `entity.findAll()` walk | Excludes `temporary` entities + the spawner-managed Player + primary Camera. | | `entities[].transform` | local position / rotation / scale | NOT world transform — local only. | | `entities[].components` | component.list + component.get | Strips `_`-prefixed runtime fields. | | `entities[].attributes` | `attribute.list` + `attribute.get` | The entity's key/value bag, written as a `{ [key] = value }` map; omitted for an entity that holds none. Holds the authored keys — a `_`-prefixed key is the engine's own session bookkeeping. | | `lighting` | `lights.snapshot()`, filtered | Scene-level `clear_color` + `sky` only. Directional / ambient / point lights persist as `Light` entities in `entities[]`. | | `player` | `sceneProxy.player_config` | Carried forward from load-time, authored only. | | `camera` | `sceneProxy.camera_config` | Carried forward from load-time, authored only. | ## What is NOT captured - Local player's position / rotation. Runtime drift; not authored intent. - Primary camera's transform. Runtime; behavior-driven. - Any entity flagged `temporary = true`. Debug helpers, runtime markers. - Internal component fields prefixed with `_` (e.g. `_velocity` on CharacterController). The spawner-managed entities (Player + primary Camera) are excluded because they're created on load by player_spawner / camera_spawner from the scene's declarative `player` + `camera` blocks. Saving them would double them on the next load. ## Parts The module is a folder of parts, each a module of its own that `init.luau` requires: - `scene_saver.serialize`: one live entity as the record a scene file carries. - `scene_saver.recordDiff`: the comparisons the record diffs are built from. ## When to use `layers.active:save(name)` (Phase 6) routes through this module. Callers that want a state snapshot (save-game systems, undo stacks) should use `world.debugSaveToDisk(...)` instead — that captures runtime state by design.
▲ 0↑ born
▣
module · born here
❒asset
# scene_build Turns builder code into scene records, and scene records into scene entities. `run(builder)` opens an entity capture scope, calls `builder`, and composes every entity it created into records — then despawns them. The builder writes ordinary spawn code; what comes back is data. A builder that raises leaves nothing behind. What a component the builder attached creates while running its own lifecycle belongs to that component: the record names the COMPONENT, and the same lifecycle runs again wherever the record is put back. That is what makes a nested build one build — a placement the builder makes runs its own module and owns what it lands, and the build around it describes the placement. `reconcile(records, target, owner)` applies records to the scene under `target`, writing `owner` and the record's place in the hierarchy onto each entity it places as the `buildOwner` / `buildKey` attributes. A rebuild reads that pair back off the entities under `target` and lands on the same ones, so nothing has to be remembered between two rebuilds — the pair is in the scene, and a reload brings it back with the entity. It returns the ids it landed on, keyed by record identity. A record is identified by its place in the hierarchy — the chain of names from the build root down to it, `base/coin_3` — so dropping a line from the middle of a builder, inserting one, or emitting two entities in the other order leaves every other entity's id where it was. Children of one parent that share a name carry their rank among those, `base/crate#2`, counted in the order the builder created them. Together these are the bake: code in, durable static-id scene content out. ## Who states an entity An entity names the build that placed it, so `ownerOf(id)` answers which build owns it — and answers nil for an entity an author spawned. `sourceOf(owner)` names the file that build is written in, from the `source` the reconcile running it passed. That pair is what makes ownership legible where an author meets it. `notePreview(id, values)` records what an entity carries after an author's change and `takePreview(id)` reads it back exactly once, in the run that states the entity again, which is where what the author set and what the build says can be named side by side. ## What a rebuild keeps Every entity a build places records what that build stated about it. A rebuild whose code states a value the way the last build did leaves that value as the scene holds it, so a hand edit to a built entity (a move, a rename, an attribute, a component field) survives every plain rebuild. The scene's build answers for all of it: ```lua local report = layers.active.asset:build({ save = false }) print(report.message) -- opens with one line counting all four lists ``` `kept` lists the hand edits to entities the build placed, `driven` the fields another component writes at runtime, `handAdded` the components and attributes added by hand to built entities, and `handPlaced` the entities no build placed. `layers.active.asset:build({ restate = true })` lands every value `build.luau` states over the kept ones. `reconcile(records, target, owner, { restate = true })` is the same at this level, and its third return value is the `kept` list. `kept` covers every value a build states about an entity it placed: its name, internal flag, transform, active flag, lifecycle mode, replication scope, synced flag, attributes and components. A restate writes exactly those: a number the scene holds within the precision a saved record keeps, and the bookkeeping a component writes about its own runtime, stay as they are. `drift()` reads the entity's own values alone; the build's report is the whole answer. `guides { path: "core/scenes-as-code" }`, "What a rebuild touches", gives the shape of every entry.
▲ 0↑ born
▣
module · born here
❒asset
# player_spawner Legacy v6 default-identity avatar setup. v7 scenes place players through the PlayerSpawn / PlayerPrototype flow; this module stands down (`M.ensure` returns early) for any scene carrying a string `playerIntent`. Hooks `layers.onLoad`: on every non-additive v6 scene load it locates the `ensure_default_player`-spawned identity entity and binds its avatar: - `world.avatar_default_<mode>` (per-mode world default). The avatar bundle combines visual + controller in one unit (mesh + skeleton + Locomotion + MovementState + CharacterController). - Per-scene `settings.player.avatar_<mode>` overrides the world default when set; `""` is the explicit opt-out (the scene builds its own body in `entrypoint.luau::onLocalReady`). It spawns a fresh body entity from the bundle, then binds it by assigning the identity's `avatar` field, which marks the body synced + PlayerOwned and attaches its `PlayerAvatar` link. Idempotent per layer: reload doesn't re-instantiate; `onUnload` clears the per-layer "already applied" flag. ## Surface | Symbol | Notes | |---|---| | `M.install()` | Idempotent. Registers `layers.onLoad` / `onUnload` hooks. Called once from the engine prelude. | | `M.ensure(sceneProxy) -> entity_id \| nil` | Apply the avatar bundle to the identity entity. Returns the identity id, or nil when none exists yet (or the scene is v7). |
▲ 0↑ born
▣
module · born here
❒asset
# camera_spawner Generic primary-camera spawner. § 17 step 10 of `docs/plans/2026-05-01-player-camera-unification.md`. Hooks `layers.onLoad`: on every non-additive scene load it spawns a `Camera`-bearing entity with `behavior` resolved through: 1. `sceneProxy.camera_default` — per-scene override (future field) 2. `world.camera_default` — world-level default 3. Neither set: `log.error` + skip the spawn (no hardcoded fallback). The spawned entity is `temporary` so `layers.active:save()` doesn't bake it. `follow` is set to the first `Player` entity in the scene at spawn time; later scripts can re-target by writing `entity(camId).component.get("Camera").follow = someId`. Additive overlays do NOT spawn their own camera — they ride on the parent non-additive scene's camera. ## Surface | Symbol | Notes | |---|---| | `M.install()` | Idempotent. Registers the `layers.onLoad` / `onUnload` hooks. Called once from the engine prelude. | | `M.ensure(sceneProxy) -> entity_id \| nil` | Manually spawn the primary camera for `sceneProxy`. Use from scene entrypoints that want to control spawn ordering. Returns nil when the camera was already in place. |
▲ 0↑ born
·
assettype · born here
❒asset
# assetType (asset type) An asset type says what a kind of asset is: the files an asset of the kind is made of, the code that gives it behaviour, the interface a person uses to work with it, and how it is found, pictured and checked. A `<typename>.assetType/` folder declares a type called `<typename>`, and every `<name>.<typename>/` folder is an asset of it. `assetType` is itself a type, so a type is an asset like any other: it is created, versioned, installed and contributed the same way. ## Making a type `asset.create("assetType", "<typename>")` scaffolds a type. The type registers the moment its folder is written, anywhere under `/zero/source/`, and from then on `<name>.<typename>/` folders are its assets. An asset of a type that is not registered yet is not an asset, so make the type first. A type folder is a root: `~.x` in any file inside it names the type's own `x`, wherever the type is installed. Keep the type's whole implementation inside its folder and reach it that way. What a type folder must hold is set by this type's own `type.yaml`, the same way every type's `type.yaml` sets what its assets hold. `asset.validate` on a type reports anything missing, and the scaffold produces a folder that passes. ## What sets your type's schema (`type.yaml`) `type.yaml` is the structural contract every asset of the type is checked against. The keys below are the ones the engine reads; a key not listed here is ignored. | Key | What it controls | |---|---| | `suffix` | The folder suffix of the type's assets. Defaults to `.<typename>`. | | `primary` | The file or files that are the asset's content: what the asset resolves to when it is used. | | `entry_files`, `primary_aliases` | Further files that load as the asset or share its identity. | | `is_container` | Whether the suffix stays in the identities of what the asset holds. | | `is_opaque_walker` | Whether a walk of the tree stops at the asset and registers only its primary. | | `plural_dir`, `classify_exts` | Loose files in a folder of this name, or with these extensions, are assets of the type. | | `is_text_default` | Whether the asset's files are text unless stated otherwise. | | `broadcasts_subassets` | Whether assets nested inside an asset of the type are found by their own short name. | | `root` | `true` makes every asset of the type a root, so `~.x` inside one names that asset's own `x`. | | `contract_ref: { field, category }` | A key of the primary file that names another asset the asset is built on. | | `files: { required, optional }` | The files an asset holds (below). | | `allow_unlisted` | `false` reports every file the type does not declare. | | `aliases_from: [{ file, key }]` | Further names an asset answers to, read from its own files. | | `settings:` | Typed per-asset settings (below). | | `inspector:` | The interface people use for the type and its assets (below). | | `preview:` | How an asset is pictured (below). | | `references:` | Names of other assets the type's files carry (below). | | `indexing:` | What search reads for each asset (below). | | `describe:` | How a missing description is generated (below). | ### The files an asset holds Each entry under `files.required` or `files.optional` is `{ path, kind: file | folder, one_of_group?, content? }`. `*` in a path matches within one segment. Entries that share a `one_of_group` are satisfied by any one of them. `content` lists checks on the file's bytes: | Check | Passes when | |---|---| | `non_empty` | the file has content | | `json_field { key, type?, non_empty?, accept? }` | the JSON holds the key (a dotted path) with that shape | | `yaml_field { key, type?, non_empty?, accept? }` | the same for YAML | | `described { keys?, headings?, message? }` | the file says what the asset is (see "Ask your assets to say what they are") | Each check takes a `message`, which is what the author is told when it fails. ### Settings `settings: { values, schema: { type | instance, export? } }` gives every asset typed settings. `values` names the file an asset's values live in; `schema.type` declares one schema for the whole type, and `schema.instance` names a file each asset declares its own in. `asset.create` writes the resolved values, and a write to the values file reaches `onChange` with what changed. ## The human side (`inspector.luau`) A type is used by people through its Inspector, and without one the type is usable only from code. The Inspector is the type's interface for a person: for a procedural graph it is the graph editor, for a kit it is the tracking view of what the kit holds and what is still missing. Writing it is part of writing the type. `inspector: { type, instance? }` in `type.yaml` names the files. `type` is the interface for the type itself and for its assets; `instance` names a file an asset may ship to add its own. Each returns: ```luau return { sections = { { id = "graph", title = "Graph", build = function(ctx) ... end } }, replace = { contents = { ... } }, -- replace a default section by id order = { "graph", "contents" }, -- section order } ``` `build(ctx)` receives the asset and builds the section. A section's `title`, and the text its rows carry, is a string or an `i18n.text` value read from a catalog (`i18n.text("inspectors.mesh.title")`), which follows the editor's language. `asset.create("assetType", ...)` scaffolds a working `inspector.luau` to start from. `asset.validate` on a type that names no inspector, or names one that does not load, reports it. ## Say what your type is for (`about.yaml`) Every type carries an `about.yaml` that says what the type is for, in three plain-language texts: ```yaml intent: "Sets the typeface of the text in your game: UI, labels, signs and 3D lettering." function: "A font, from a TTF, OTF or WOFF file, made available to all of Zero's text, including 3D text." usage: "You choose it by name for your UI or your text, and the text appears in that typeface." ``` - **`intent`** is what the type is for in someone's game, in the words a game maker uses. Up to 800 bytes. - **`function`** is how it works today: what an asset of it is made of and what the engine does with it. Up to 1500 bytes. - **`usage`** is what a person or an agent does with one. Up to 1200 bytes. Write about the type as a whole, not one asset of it, and say what it does now. Agents read these texts to learn when to reach for the type and how; people searching find the type by them. The scaffold starts each text with `[[describe]]` and a note on what to write; a text that still starts that way counts as not written. `services describe` can write them. They show up in `asset.inspect` as `detail.about`, in `assetTypeRef:getAbout()`, at the end of the type's `types/<typename>` guide, and at the top of the type's Inspector. ## Ask your assets to say what they are A type can require each asset to carry a description: a file, written by the author or generated, saying what the asset is and what it is for. Declare it with a `described` check: ```yaml files: required: - path: "README.md" kind: "file" content: - { check: "described", message: "Say what this widget is for and where it goes." } ``` A file that is missing, empty or still has a line starting with `[[describe]]` fails the check, and so does a YAML file whose named `keys` are missing or over their `max_bytes`, or a Markdown file missing a named heading. `asset.validate` names the asset, and a push that carries it is refused with `message`. `services describe` finds such assets and writes their descriptions. `describe:` steers what is generated: ```yaml describe: guidance: "Say what the widget shows, what input it reacts to, and where it fits in a UI." examples: - "<identity of an asset of this type whose description reads well>" ``` An example is an asset of your type whose description is a true, written one, never a placeholder and never the asset being described; with none, leave `examples` empty. A type whose assets the model cannot perceive (a sound, a motion) says so in `guidance`, and the description is drawn only from what the asset's own files state. Start the file unwritten in your `template/`: a heading and one line starting with `[[describe]]`, never example content, which every new asset would carry verbatim. A type whose assets say what they are through their own content (a mesh, a texture) declares no check. ## The type's code (`behavior.luau`) `behavior.luau` returns one table. These are the keys the engine reads from it; anything else on the table is the type's own. ### What the type's assets can do | Key | Shape | What the engine does with it | |---|---|---| | `ref` | `{ [name] = function(self, ...) }` | Every function becomes a method on every asset of the type: `ref:name(...)`. | | `modules` | `{ [name] = require(".x") }` | Code the type's assets reach with `asset.containing(__FILE__).modules.<name>`. | | `events` | an events schema | Events an asset fires. Readers subscribe through `ref.events.<name>:connect(...)`; the type fires them. | | `refShapes` | `{ [method] = function(self) -> (typeExpr, source?) }` | The result type of a `ref` method for one particular asset (below). | | `namePattern` | a Lua pattern | The names `asset.create` accepts for the type's assets. Default `^[A-Za-z][A-Za-z0-9_]*$`. | | `derive` | `{ output, module, compute, fingerprint, matches?, required?, timeout? }` | A file computed from the asset when it is committed; a `required` one holds the commit until it lands. | Some `ref` names mean the same for every type, and the engine calls them: - **`instantiate(self, target?, opts?) -> (root, idMap)`**: puts the asset in a scene. Defining it is what makes the type scene-instantiable. Its return is a contract (below). - **`inspect(self) -> detail`**: what `asset.inspect` reports for the asset beyond the common record (below). - **`preview(self, opts)`**: renders the asset's picture; it wins over the type's `preview:` recipe. - **`previewMaterial(self) -> { material }`**: the material a `surface` preview paints. - **`saveDefinition(self)`**: writes the asset's in-memory edits back to its files in edit mode. Some names are answered for every asset before the type is asked, so a `ref` entry of the same name is never reached: `getSource`, `getBytes`, `getText`, `exists`, `deps`, `canInstantiate`, `canPreview`, `preview` (which calls yours when you define one), `meta`, `runtime`, `events`, `typeRef`, `modules`, and the residency flags `has_backing_asset`, `has_runtime_changes`, `cpu_resident`, `gpu_resident`. ### When the engine calls the type | Hook | Signature | When it runs | |---|---|---| | `onCreate` | `(name, opts) -> { [path] = contents }` | On `asset.create`. Returns the files of the new asset, laid over the type's `template/`. Annotate `opts`: its type is the schema `asset.create` checks the caller's arguments against. A `""` key writes a single loose file. | | `onReplace` | `(dest, files) -> files` | On an `asset.create` over an asset already at `dest`, after `onCreate`, so what the author added can be carried into the replacement. | | `onRegister` | `(self)` | Once per asset, when it first registers: when the world loads, on a live `asset.create`, and when an asset arrives later (installed, pulled, synced). This is what makes an asset take effect the moment it is written. | | `onChange` | `(ref, change)` | On every write to a file inside an asset of the type. `change` is `{ path, asset, type, kind, origin }`, plus `settings` and `settingsChanged` for a write to the settings values file; `kind` is `edited` or `seeded`, `origin` is `local` or `remote`. Filter on `change.path`. Writes to one asset arrive in order, each after the hook for the one before has finished, and the hook may wait on what it reads. A write the hook makes inside its own asset arrives later like any other, so keep the hook convergent. | | `onDependencyChange` | `(ref, change)` | When a module the asset's code requires is re-run, or a name the asset carries starts resolving. `change.kind` is `dependency`. | | `onDelete` | `(ref)` | When an asset of the type leaves the world: deleted, or the world it is in is swapped away. | | `validate` | `(ref) -> { { code, message, severity?, path? } }` | On `asset.validate`, after the `type.yaml` checks, for the type's own rules. `severity` defaults to `error`. Runs on every push, so a type's rules hold at publish. A hook that fails reports `validate.hook_failed`. | ### Settings hooks | Hook | When it runs | |---|---| | `settingsDefaults(name, opts, asked) -> table` | Once per `asset.create`, for values the schema's defaults do not give. | | `settingsCorrections(values, name, opts) -> (corrections?, reasons?)` | On every settings write. A correction to a field the writer named refuses the write, giving the reason. | | `settingsDerivedDefaults(values, explicit, changed)` | On a settings write, for fields derived from others. | | `normalizeSettings(values, stored?)` | On every read and write, to map an earlier spelling of a field to the current one. | | `settingsHealed(values, stored)` | On a read, to repair stored values. | | `settingsSchemaProblem(schema, ref) -> string?` | When an asset's own schema is read; a returned string refuses the schema. | `creationInputs` (`{ [opt] = true | selectorOpt }`) names `asset.create` options that are inputs to the type rather than settings. ### Reloading An edit to `behavior.luau` reaches existing assets with no restart. ## How an asset is pictured (`preview:`) | `kind` | The picture is | The type provides | |---|---|---| | `instantiate` | the asset placed in the preview studio through its `instantiate` | `ref.instantiate` | | `image` | a file the asset holds, fitted to the frame | `source: { files }`, the candidate files in order | | `surface` | the asset painted on a mesh | `mesh`, and `ref.previewMaterial` | | `custom` | whatever `ref.preview` returns | `ref.preview` | ```yaml preview: kind: surface mesh: sphere ``` `angle: [yaw, pitch]` turns the camera. The studio owns the light, the backdrop and the framing, so an asset pictures the same in every world. A type with no `preview:` that defines `instantiate` still answers `ref:preview()`. A picture is rendered when something asks to view it (the editor showing the asset, `ref:preview()`), when previews are generated on request (`assets.generatePreviews`), and when the asset is staged. An edit alone renders nothing. The picture records what it was made from, so a stale one is told from a current one. ## The names your type's assets hold (`references:`) Where your type's own format or API carries the name of another asset, declare it here: ```yaml references: keys: # a top-level key of the type's files that holds a name, or a table of them - { key: "shader", type: "shader" } args: # an argument of a call, counting from 1 - { call: "g:node", position: 2, type: "procNode" } fields: # a field of the options table a call takes - { call: "fx.beam", field: "material", type: "material" } ``` `type` is the category the name resolves in. `asset.declareReferenceKey`, `asset.declareReferenceArg` and `asset.declareReferenceField` declare the same from a script. ## What search reads (`indexing:`) `indexing:` is how assets are found. Search reaches an asset only through what its type's `indexing:` names, and adds nothing of its own. That includes you: an asset indexed badly is one you cannot find later, when you are making something else and need it. A type whose assets are never looked for says `indexing: none`. ```yaml indexing: data: # text, read from the asset's files - role: identity extractor: verbatim source: { file: "README.md" } - role: interface extractor: symbols source: { files: ["init.luau"] } - role: implementation extractor: verbatim source: { files: ["init.luau"] } content: # the picture - role: identity modality: image source: { file: "preview.png" } facets: # what a query filters and re-ranks by file: ".metadata" rigged: { type: bool, from: { components: { contains: SkinnedModel } } } roughness: { type: number, filter: range, from: { file: "mat.yaml", field: "floats.roughness" } } ``` **Roles.** Each `data` and `content` entry has a `role`, and a query matches in two slots: - **`identity`**: what an asset is. For anything you look at, the picture; for anything else, the text that says what it is. - **`capability`**: what it does and how it is made. `interface` (the signatures or shape a caller uses) and `implementation` (the body) both count as capability, and a type with code usually declares both. Ask what a person would recognise an asset of the type by, and what it does, and point each role at the file that says it. For text, that is the asset's description: the file your template starts with a `[[describe]]` block, which the author writes or `services describe` fills in (see "Ask your assets to say what they are"). **`data`.** `extractor: verbatim` embeds a file's text as it is; `symbols` embeds the declared signatures of code. `source` is `{ file }` or `{ files: [...] }`. Never index a file name (`source: { field: name }`): one or two words carry nothing to match. **`content`.** `modality: image` embeds the picture itself, so a text query matches what the asset looks like. A type whose assets are looked at makes the picture its identity. **`facets`.** What a query narrows and re-ranks the matches by. `file` is embedded whole, so keys nobody declared in it are still found. Each further key is computed for every asset and states a value for every one, including `false`: a file can imply "not rigged" but never say it, and a query separates rigged from unrigged only because the unrigged ones say `rigged: false`. A key is `{ type: bool | number | enum, filter?: range, from }`, where `from` is `{ file, field }` (a field of one of the asset's files, dotted for nesting), `{ metadata: key }`, or `{ components: { contains | any_outside } }` (what the asset's entities carry). ## What blocks a push A push checks every asset it carries against its type. These refuse it: - a required file that is missing, a `content` check that fails, a `described` file not written yet; - an error from the type's `validate`. Unlisted files and warnings do not. A `described` file blocks only a push that changes the asset. When a push is refused, the message names each asset and what it lacks. `world.publishBlockers()` and `zm status` read the same list without pushing. ## Typing a result from the asset (`refShapes`) A `ref` method whose result depends on the asset (one entry per child folder, per row of a config, per control a map declares) can only be annotated as `{ [string]: Thing }`, which accepts any key. `refShapes` states the result for each asset instead: a function returning a Luau type expression for that asset, and the module whose types the expression uses. Read the asset; never run it. ```lua -- inputMap.assetType/behavior.luau M.refShapes = { activate = function(self): (string, string) local names = {} for _, control in ipairs(M.ref.controls(self)) do table.insert(names, control.name .. ": Handle") end if #names == 0 then return "", "" end return "{ " .. table.concat(names, ", ") .. " }", "@builtin::modules.zinput.scheme" end, } ``` With it, `map.jump:onPressed(fn)` is checked and `map.noexisting` is reported. A per-asset type applies where the call site names which asset: a component field whose default names it, or an annotation `AssetRef<"inputMap", "<identity>">`. `asset.resolve(name, category)` carries only the category, and a name computed at runtime carries nothing, so calls on those keep the declared return. The type belongs to the call's result: index it there, or bind what you need from it there, and the names stay checked. `require("@builtin::assetTypes.assetType.shared.refShapes").published()` shows what was published: `categories` (each type's method surface) and `returns` (per-asset results by identity, then method). An identity missing from `returns` was never published. Results are recomputed when an asset is written; at most 64 assets of one type are read. ## Putting an asset in a scene (`ref.instantiate`) A caller writes one piece of code against every instantiable type, so what `instantiate` returns is fixed: ```lua local Instantiable = require("@builtin::assetTypes.assetType.shared.instantiable") M.ref = { instantiate = function(self, target, opts) local root = Instantiable.root(self, target, opts) -- compose the asset under `root`, now return Instantiable.result(self, root, idMap) end, } ``` **In.** `target` is the entity the asset lands under, or onto for a hierarchy type; with none, the type spawns a new root. `position`, `rotation` (three numbers in degrees, or a quaternion), `scale`, `name` and `temporary` mean the same for every type: `Instantiable.root` applies them to a root you make, `Instantiable.place` to one you adopt. Document any options of your own in the hook's `--!arg` docs. **Out.** `(root, idMap)`. `root` is the composed root, live when you return: build synchronously, never defer to a component's `awake`. `idMap` maps each original id to the spawned one, so a component that composes the asset again on every load can pass it back in and keep references into the composition. Every call goes through `Instantiable.result`, which refuses a root that is not live and turns a missing `idMap` into `{}`. ## Inspecting an asset (`ref.inspect`) `asset.inspect(ref)` builds a record every asset shares (`identity`, `name`, `guid`, `source`, `typeName`, `typeDefinitionPath`, `scope`, `origin`, `description`, `tags`), then calls `ref.inspect(self)` for the type's own `detail`: ```lua M.ref = { inspect = function(self) -- read the asset's own files, never runtime state: inspect works on an asset -- that has not been compiled, uploaded or registered return { --[[ what makes this asset what it is ]] } end, } ``` Without it, the record is the shared part alone, and an agent inspecting the asset learns nothing of what it is. A hook that raises leaves `detail` empty and sets `record.warning`. ## Discovery - `asset.list("assetType")`: every registered type. - `asset.inspect("<typename>")`: the type, its README and its `about.yaml` texts. - `asset.resolve("<typename>", "assetType")`: the type itself.
▲ 0↑ born
▣
module · born here
❒asset
# scene runtime What a `.scene` folder does when it is loaded, saved, built, or swapped. A `<name>.scene/` carries `scene.json` (the entity arrangement), an optional `build.luau` (the code author's half), an optional `entrypoint.luau`, and a `scene_dirty/` overlay of unsaved edits. Reading, composing and writing all four is the scene type's own behaviour, so it lives in the type. ## Sub-modules | Module | Responsibility | |---|---| | `loader.module` | Reads scene.json v6 and v7, refuses versions it does not know, composes canonical + dirty overlay, spawns the entities, and runs the entrypoint. | | `saver.module` | Persists scene state as a delta overlay against the canonical file, promotes that overlay on save, and answers which edits are still pending. | | `build.module` | Runs a `build.luau` inside an entity capture scope and composes what it spawned into scene records. | | `observe.module` | The read side — the per-scene counts and costs `layers` and `loader` write. | | `swapOrchestrator.module` | Drives multiplayer room transitions and the scene-swap gate, so a local swap does not leak despawns to peers in the old room. | ## Reaching it ```luau local rt = require("@builtin::assetTypes.scene.shared") rt.saver.hasPendingSceneEdits(layers.active.name) ``` Fields resolve lazily. The prelude installs `swapOrchestrator` and starts `saver`'s dirty writer in a fixed order, which a table that required all five on load would take away from it.
▲ 0↑ born
▣
module · born here
❒asset
# renderer.holds The reads every renderer cell a hold pins answers the same way. A hold on a cell such as `renderer.temporal` (the per-frame clock) or `renderer.atmospherics` (the share of the air that reaches the image) names who took it and the key it was taken under, so a caller reads who holds the cell, an exclusive hold is refused for every other key, and a hold whose task ended is handed back. - `statedOwner(options)` answers the key `options.owner` states, or nil. - `actor()` answers the id and display name of the caller the call is attributed to. - `ownerLabel(owner, ownerName)` answers how a refusal names the holder. - `holderIsGone(holder)` answers whether the task that took a hold was cancelled or died; `holdingTask()` answers the task taking a hold now. ```luau local Holds = require("modules.api.engine.renderer.holds") assert(Holds.statedOwner({ owner = "shot" }) == "shot") assert(Holds.ownerLabel("abc", "Ada") == "Ada (abc)") assert(Holds.holderIsGone(nil) == false) ```
▲ 0↑ born
▣
module · born here
❒asset
# renderer.letGo The watch that releases a runtime texture, material, mesh or render feature mid-session once no script reaches a handle to it and nothing else holds it. It reads the renderer's handle sets every few dozen frames: a resource whose last handle the garbage collector took joins the watch and is judged against the runtime resource census, by the holders `renderer.collect` reads, and released once nothing holds it. A resource kept only by the component or scene load that created it stays while that owner does, and the log names an owner once it holds 64 of one kind that way, and again each time that count doubles. A render feature holds what it created through the handles it keeps and the passes it queues, which the census names as references, so a target whose handle the feature dropped and that none of its passes names any more is released while the feature stands. A texture or mesh the asset path uploaded under its asset's guid waits on the watch while that asset stands, and is judged from its holders once the asset index changes and the asset no longer answers. A texture a released material record named goes on the watch with it, the one the device holds for an asset included: that asset is the path the texture is read back by, so it is released once nothing else names it, the way a collection releases it. - `new(host)` makes the watch over the handle sets, census and release the renderer hands it in `host`, and answers `{ start, rejudge, letGo }`: `start()` starts the task that reads the sets unless it is running, `rejudge(kind, guid)` marks a watched resource due a judgement at the next reading, and `letGo(kind, guid)` puts a resource a holder other than a handle let go of on the watch.
▲ 0↑ born
▣
module · born here
❒asset
▲ 0↑ born
▣
module · born here
❒asset
# renderer.refs How `renderer.*` names a live resource. A runtime resource is filed under a v4 guid, minted from OS entropy or given by the caller; and each call that names a resource takes whatever the caller already holds (the key or guid, the handle `create` returned, the CPU handle `load` returned, or an `AssetRef`) and coerces it to the key the renderer's stores index it by. - `makeGuid()` mints a guid; `validateGuid(guid, what)` answers `guid` when it is a v4 guid and raises at the caller's line when it is not. - `materialKey(value, what)`, `meshKey(value, what)` and `textureKey(value, what)` answer the registry key or guid a value names, and raise a rejection that lists the accepted forms. - `refField(t, name)`, `declaredCategory(value)` and `shapeName(value)` read a ref-like table the way the coercions do. - `primaryBytes(ref)` answers an asset's primary content bytes, waiting for them under a coroutine when they are still on their way; `textureRefOf(value, what)` answers the ref a texture asset's content is read through. ```luau local Refs = require("modules.api.engine.renderer.refs") local guid = Refs.makeGuid() assert(Refs.validateGuid(guid, "example") == guid) assert(Refs.meshKey({ kind = "MeshHandle", category = "mesh", guid = guid }, "example") == guid) ```
▲ 0↑ born
▣
module · born here
❒asset
# renderer.shading The readings `renderer.shadingOf` builds out of the document the renderer publishes every frame. - `shadingSubject(value, what)` answers the id a shading question names: an entity proxy's id, an entity-id string, or the registry key of a material in any form a material answers to. - `publishedRenderable(doc, id)` answers the row that answers for a subject: the entity's own row, or a row drawing with the material, a fault wherever there is one. - `materialRow(doc, id)` answers the renderer's record for one material. - `shadingFault(state, means, row)` builds the fault reading a row carries. ```luau local Shading = require("modules.api.engine.renderer.shading") local doc = { renderables = { { entity = "e1", material = "m1", substituted = false } }, materials = {} } local row = Shading.publishedRenderable(doc, Shading.shadingSubject("e1", "example")) assert(row.material == "m1") ```
▲ 0↑ born
▣
module · born here
❒asset
# renderer.sources The `src` shapes `renderer.mesh.create` / `update` and `renderer.texture.create` / `update` take. - `classifyMesh(src)` answers which mesh src it is (`SRC_GPU`, `SRC_CPU`, `SRC_GEOMETRY` or `SRC_BUFFERS`), and raises for a src that is none of them or a geometry src whose indices address a vertex its positions do not carry. - `vertexRecordsToArrays(src)` turns geometry written as per-vertex records (`vertices = { { pos, normal?, uv?, uv1? }, ... }`) into the parallel flat arrays the upload takes. - `boundsFromPositions(positions)`, `vecToAabb(min, max)` and `ZERO_AABB` are the bounds a mesh is created with; `geometryCounts(src)` answers the vertex and index counts raw geometry implies. - `classifyTex(src)` answers which texture src it is (`TSRC_GPU`, `TSRC_CPU`, `TSRC_PIXELS` or `TSRC_TARGET`). ```luau local Sources = require("modules.api.engine.renderer.sources") local src = { positions = { 0, 0, 0, 1, 0, 0, 0, 1, 0 }, indices = { 0, 1, 2 } } assert(Sources.classifyMesh(src) == Sources.SRC_GEOMETRY) print(Sources.boundsFromPositions(src.positions).max.x) -- 1 ```
▲ 0↑ born
·
assettype · born here
❒asset
# Component (asset type) A component is a reusable behavior + data unit attached to an entity. The component file declares public fields, methods, and lifecycle callbacks; the engine instantiates one per attachment and drives its hooks every frame. Components are the primary unit of gameplay code — movement, AI, animations, UI panels, network sync, and per-entity state all live here. ## When to use one - You need per-entity state that survives across frames. - You need per-entity behavior driven by engine lifecycle hooks (`start`, `update`, `onDestroy`). - You want to expose configurable fields to designers / `entity.spawn` callers / scenes without code changes. If you need a stateless pure-function library, use a `.module`. If you need to generate content declaratively, use a `.service`; compute work belongs in a `.computeShader`. ## Where it lives - Source: `/zero/source/.../<Name>.component/` - Identity: `<Name>` (the `.component` suffix strips from the identity, but the folder retains the suffix on disk). - Folder shape: - `init.luau` (or `init.lua`) — declares the component. **Required.** - `README.md` — instance-level documentation. **Required.** - `.metadata` — agent-editable tags + free-form fields. **Required.** The structural contract is enforced by `asset.validate` against this type's `type.yaml`. ## How to create one Always start with the scaffold — it guarantees the folder shape matches `type.yaml` from the moment it's on disk: ```luau asset.create("component", "<Name>") -- Creates: /zero/source/<Name>.component/ -- init.luau (canonical declare + public block + hooks stubbed) -- README.md (instance README template) ``` After scaffolding, edit `init.luau` to fill in the actual fields and behaviour. The component registers as soon as the file is written — hot-reload is automatic; no engine restart required. ## How it operates 1. **Registration.** Writing `init.luau` into a `.component/` folder indexes the asset, mints a guid (in the `.meta` sidecar), and surfaces the type to the engine's component registry. Same-frame visible to `entity.component.add`. 2. **Attachment.** `entity(id).component.add(name, data)` (or the batch form `tools.use("entityOps", "addComponents", targets, { [name] = data })`) attaches an instance. The `data` table's fields override the component's declared defaults; omitted fields take the declared default. The `data` values are copied into `public.*` BEFORE `awake()` runs. 3. **Lifecycle.** The hooks run in this order: - `awake()` — same frame as attach, immediately after the data copy. Initialise state, set up native bridges, register with other systems. Other components on the same entity may not have awoken yet. - `start()` — the next frame. Every component on the entity has completed `awake()` by then, so cross-component setup is safe here. - `update(dt)` — same frame as `start()`, then every frame after, for as long as the gameplay clock is running. `fixedUpdate(dt)` runs once per physics step, straight after it, with the step's `dt`, so a frame can run it several times or not at all; `editorUpdate(dt)` runs while the clock is held. Which of them ticks is decided by `engine.mode` AND `engine.paused` together — see **Per-frame hooks and the two axes** below, and `man modes`. - `onDestroy()` — when the component is removed via `component.remove` or when the owning entity is despawned. Release resources, drop native ECS components. For the full list (`onEnable`, `onDisable`, `fixedUpdate`, `editorUpdate`, `onPropertyChanged`, `onAssetReload`, `onModuleReload`, `onBeforeSave`, …) and the timing details, **read `man components` — that is the canonical lifecycle reference. Generic component patterns (declare blocks, public fields, sync, ECS bindings, typed methods) all live there.** 4. **Public surface.** Fields declared in `public` are inspectable, editable in the inspector, and persist with the entity. Methods are declared on that same table with a colon — `typed function public:method(args)` — and every one of them takes the component ref as `self`, so a caller invokes it with a colon too: `entity(id).component.get(name):method(args)`. That is the one calling convention a component ref answers to: the reflection methods `ref:fields()` / `ref:getField(name)` / `ref:setField(name, value)` take the same spelling. A function the chunk declares at file scope (`function helper()`) is the component's own, reachable from its hooks under its bare name; `public` is what the ref carries. 5. **Settings and the Inspector card.** `type.yaml` names the component's settings schema as `settings: { schema: { instance: "init.luau", export: "public" } }`: the `public` table IS the schema, and its values live on each entity the component is on, so `asset.schema(componentRef)` answers the Field descriptors and no values file exists. On an entity the Inspector shows the component as a card whose generic `settings` section edits those fields as typed controls, each edit checked against the schema and written to the live component as one undoable operation. `type.yaml` also names `inspector: { instance: "inspector.luau" }`: a component that ships an `inspector.luau` beside its `init.luau` shapes its card — the file returns `{ sections, replace, order }` (see `assetTypes/README.md`, "`inspector:`"), each section's `build(ctx)` reading `ctx.component` (the live component) and `ctx.selection.id` (the entity). `SceneModule.component/inspector.luau` replaces `settings` with the bound module's declared inputs. 6. **Events.** An `events` block declares typed moments the component fires from inside — `events = { onHit = Event({ dmg = Field.number(0, NoSync) }) }`. The owner fires with `events.onHit:fire({ dmg = 10 })`; outside code subscribes through the proxy's subscribe-only facade, `entity(id).component.get(name).events.onHit:connect(fn)` (`:once` / `:wait` too). Pass `Sync` as the event's second argument to replicate a fire to other peers. Events let one component react to another's moments without polling. Full reference: **`man components`**, Events section. 7. **Hot reload.** Editing `init.luau` reloads the component definition; live instances are reconciled with the new declaration in-place, and each crosses one lifecycle boundary: `onDestroy()` ends the running life, then `awake()` and `start()` construct the one that replaces it, and `update()` resumes on the next frame. `public` and `private` values carry across; module-level `local`s belong to the chunk, so the new life starts with them at their initial values and its `awake`/`start` are what fill them in. Whatever the old life handed elsewhere — a subscription, a shared registration, a spawned entity — is released in `onDestroy`, the call that pairs with the construction about to run. An edit that leaves the source byte-identical crosses no boundary at all. A field carries its value across when something stated it: a key of the `data` table the instance was attached with (a scene record's data is that table), or a write made since. Every other field takes the edited source's declared default, so changing a default reaches every instance that left the field to it. An instance that states its own value for a field whose default the edit changed keeps that value, and the reload logs a `[HotReload]` warning naming the field, the entity, the value kept and both defaults. ## Discovery - `asset.list("component")` — every registered component (engine + world + libraries). - `asset.inspect("<name>")` — identity, scope, public fields, lifecycle methods, source path, and this type README. `detail` carries the component's declared `fields`, `methods`, and `events`, parsed from its source — `tools.use("assets","describe", "<name>")` renders it as markdown, so a component's events are visible without opening its source. - `ls /zero/source/<Name>.component` lists the files the folder holds. - `entity(id).component.list()` — components attached to an entity. ## Per-frame hooks and the two axes `engine.mode` (`"edit"` / `"play"`) and `engine.paused` (the gameplay clock) are independent, and the per-frame hooks read them separately: - `update(dt)` / `fixedUpdate(dt)` tick while **the gameplay clock is running** — whichever mode the engine is in. - `editorUpdate(dt)` ticks while **the clock is held** — because the mode is `edit`, or because play is paused — and also alongside `update` whenever edit is running. Which gives four states, and this table is the contract: | `engine.mode` | `engine.paused` | hooks that tick | |---|---|---| | `edit` | `true` | `editorUpdate` | | `edit` | `false` | `update`, `fixedUpdate`, `editorUpdate` | | `play` | `false` | `update`, `fixedUpdate` | | `play` | `true` | `editorUpdate` | Entering edit sets `paused = true` and entering play sets it back to `false`, so a session that never writes `engine.paused` only ever sees rows 1 and 3 — which is where the shorthand "`update` is the play tick, `editorUpdate` is the edit tick" comes from. It is the two default rows of a four-row table, not the rule. **Row 2 is the one that surprises.** With `engine.paused = false` in edit — set by hand, or by a tool that advances the gameplay clock to sample it, such as a `capture.collage` given a `duration` — `update` and `editorUpdate` both fire, once each, every frame. A component that declares both and routes them to one body therefore runs that body **twice per frame**: ```luau local function drive(dt) ... end function update(dt) drive(dt) end function editorUpdate(dt) drive(dt) end -- twice per frame in row 2 ``` Nothing reports the doubling; it reads as an animation running at twice its intended speed. To get exactly one tick per frame in every row, ask which axis you meant and answer it in the body: ```luau function update(dt) drive(dt) end function editorUpdate(dt) if engine.paused then drive(dt) end end ``` A scene `entrypoint.luau` declaring the same two hook names is dispatched by the scene loader, not by this table: there `update` needs play AND running, `editorUpdate` needs edit, and play-paused ticks neither. Read `man scenes` before carrying a component's rule to an entrypoint. ## Authoring conventions - Annotate public fields with `--!desc` so the inspector + LSP show documentation alongside the field name. - Declare lifecycle hooks (`start`, `update`, `onDestroy`) explicitly rather than relying on engine defaults — readers can see at a glance what runs when. - Keep `update(dt)` cheap — it runs every frame per instance. Move heavy work to `start`, to a `.computeShader`, or behind a job (`man jobs`). - For multi-entity batching, prefer `tools.use("entityOps", "addComponents", targets, components)` over a loop of `entity(id).component.add` — it takes many targets and many components in one call. ## Common pitfalls - **Naming.** The component identity is the folder stem with `.component` stripped (e.g. `<Spinner>.component/` → identity `Spinner`). Don't repeat the suffix in the identity passed to `component.add`. - **`init.lua` vs `init.luau`.** Either is accepted (it's a `one_of_group: "entrypoint"`), but `.luau` is canonical. Mixing both in one folder is invalid. - **`update` in edit mode.** It runs whenever the gameplay clock is running, and entering edit stops that clock — so `update` is idle in a freshly-entered edit session and ticks again the moment anything sets `engine.paused = false`. Use `tools.use("wld", "play")` to test update logic under the mode it ships in; `tools.use("wld", "edit")` to return. See **Per-frame hooks and the two axes** above. - **Renaming.** Renaming the folder changes the identity. References to the component are recorded against the component itself, so renaming or moving it does not break them. ## Related types - `.module` — pure-function library, no per-entity state. - `.service`: a declarative content generator, no per-entity state. - `.preset` — a captured component configuration, replayable into `component.add` without re-typing fields. - `.bundle` — entity hierarchies that may carry component attachments as part of the bundle. ## In the Inspector Fields: its execution order, hooks, and how many methods and events it declares, then the fields its `public` table declares as read-only typed controls holding their defaults, with **Check** and **Open** for its entry file. Instances: a link to every entity carrying it. What its card shows on an entity comes from the component's own `inspector.luau`.
▲ 0↑ born
▣
module · born here
❒asset
# scene_saver.recordDiff The comparisons the saver's record diffs (`transformDiffLines`, `recordDiffLines`, the pending scene edits) are built from. - `diffEqual(a, b)` and `valuesEqual(a, b)` compare two record values, numbers within a tolerance that absorbs the f32 round trip of a live read. - `componentMatchName(t)` answers the name a component type matches by, whichever spelling the record used; `componentList(rec)`, `componentMatchNameOf(c)`, `componentInstanceLabel(c, typeName)` and `componentData(c)` read a record's components the way the comparison needs them, answering empty for a malformed record. - `selfWrittenFieldSet(entityId, componentType, instanceName)` answers the fields a component instance wrote about its own runtime. - `pushAttributeDiffLines(oldRec, newRec, push)` hands `push` one line per attribute added, changed or removed. ```luau local RecordDiff = require("@builtin::assetTypes.scene.shared.saver.recordDiff") assert(RecordDiff.diffEqual({ 1, 2 }, { 1.00001, 2 })) RecordDiff.pushAttributeDiffLines({ attributes = { hp = 1 } }, { attributes = {} }, print) -- - attribute.hp ```
▲ 0↑ born
▣
module · born here
❒asset
# scene_saver.serialize One live entity as the record a scene file carries, and the reads the saver asks of a live entity while it decides what to record. - `serializeEntity(id, parentById)` answers the record for a live entity: its name, parent reference, transform, components (each field value serialized), participation, network scope, render layer and attributes. A field holding a runtime GPU handle is reported once, with the remedy, and left out of the record. - `serializeFieldValue(v)` answers one component field value as a record states it, with the reason when the value has no record form. - `entityDisplayName(id)` answers the name an entity is shown by, and `entityIsTemporary(id)` whether it is marked as never saved. ```luau local Serialize = require("@builtin::assetTypes.scene.shared.saver.serialize") for _, e in ipairs(entity.findAll()) do print(Serialize.serializeEntity(e.id).name) end ```
▲ 0↑ born
▣
module · born here
❒asset
# luau_introspect (module) Parses Luau/asset source TEXT into structured declarations. Pure string/pattern parsing (`string.find` / `string.match` / `string.gmatch`) over the literal source — no compiling, no VM spawn, no runtime state, no engine FFI. Given source text, it extracts what is written in the file. This is the shared parser every per-assetType `M.ref.inspect` hook uses to turn a component/module/tool's own source into the structured record `asset.inspect` returns. ## Exports - `docstrings(src) -> DocMap` — scans `--!desc` / `--!arg` / `--!return` / `--!example` comment runs and binds each run to the name of the declaration on the next non-comment line (the identifier after `function`, `public:`, `local function`, or `M.`). - `publicFields(src) -> { FieldEntry }` — parses `public = { name = Field.<kind>(default, mode), ... }` table-literal entries and module-scope `public.<name> = Field.<kind>(...)` assignments. - `events(src) -> { EventEntry }` — parses `events = { name = Event(payloadSchema?, syncMode?), ... }` table-literal entries. - `methods(src) -> { MethodEntry }` — parses `function public:<name>(...)` / `typed function public:<name>(...)` declarations (params + optional return type). - `lifecycleHooks(src, catalog) -> { string }` — top-level `function <name>(` declarations whose name is in the caller-supplied `catalog` array. - `moduleExports(src) -> { ExportEntry }` — parses `M.<name> = function` assignments, `function M.<name>(...)` declarations, and a trailing `return { foo = foo, ... }` export table. - `forSource(src, computeFn) -> any` — memoises `computeFn(src)` keyed on `src` itself in a module-local table. The same source text returns the cached result without re-running `computeFn`; different source text recomputes. Keyed on the source content (not an asset checksum) because composite/container assets (component folders, scene folders, etc.) all hash to the empty-string checksum — a checksum-keyed cache collapses every such asset's detail onto whichever one was inspected first. ## Usage ```luau local Introspect = require("modules.luau_introspect") local src = self:getInitScript() local detail = Introspect.forSource(src, function(s) return { fields = Introspect.publicFields(s), events = Introspect.events(s), methods = Introspect.methods(s), hooks = Introspect.lifecycleHooks(s, lifecycleCatalog), } end) ``` ## Notes - Every function is a pure string→table transform: same source text in, same structured table out, every time. No reads of live component state, no entity/world queries. - Structural scanning runs over a comment- and string-aware **mask** of the source (a same-length copy where comment bodies and string-literal contents are blanked to spaces, delimiters and newlines preserved). Pattern matches and brace/paren balancing run on the mask — so a brace, `Field.`, `Event(`, or a whole entry that appears inside a comment or a string literal never registers — while captured values are sliced from the original source at the same (aligned) indices. This makes the parser robust to apostrophes in comments, commented-out entries, string defaults containing `}` / `Field.` / `Event(`, and `[[ ]]` long strings. - `default` / `category` are raw trimmed source-text slices (with any trailing comment stripped), not evaluated values. - For a **ref constructor** (`Field.assetRef` / `dataRef` / `resource` / `componentRef`) the FIRST positional argument is the category / contract / componentType selector, captured under `category`; the SECOND argument is captured under `default`. - For every **other** Field kind the first argument is the `default` and `category` is nil. - A trailing `Sync` / `NoSync` identifier is captured as `sync`, tolerating a trailing comma or a trailing comment after the last argument. - Field/Event entries whose key is a computed or indirect expression (`[expr] = Field.number(...)`) are omitted — only literal identifier keys are recognised. - `methods` captures a `...` variadic parameter (as `name = "..."`), with its `: <type>` annotation when present. - A `--!desc` written above a field/event declaration (`<name> = Field.<kind>(...)` / `<name> = Event(...)`) or a `public.<name> =` assignment binds to that name in `docstrings`, and is folded into the corresponding `publicFields` / `events` entry's `desc`. - `lifecycleHooks` never hardcodes the lifecycle-callback catalog; the caller passes the list of names to match against. - `forSource`'s memo is bounded (oldest-key eviction) so a long session touching many distinct asset versions can't grow it without limit.
▲ 0↑ born
▣
module · born here
❒asset
# assetType.shared.ref Builds the metatable every `AssetRef` (the `{ __ref, type, name, guid, identity, path }` envelope returned by `asset.resolve` / `asset.ref`) carries. Replaces the per-call C metatable that used to live in `crates/zero_scripting/src/ffi/bindings/asset.rs::attach_asset_ref_metatable`. ## Public API ```lua local assetRef = require("@builtin::assetTypes.assetType.shared.ref") -- Called by the Rust factory (push_asset_ref_handle) via -- _G.__build_asset_ref_proxy after the envelope fields are set. assetRef.build(envelope) -- attaches AssetRefMT, returns the table ``` The module exposes no invalidation surface — discovery is registry-driven and hot-reload is transparent (see "Discovery and hot-reload" below). ## Method dispatch order `ref.foo` is resolved in this order: 1. **Default methods** — `getSource` / `getBytes` / `getText` / `exists` / `inspect` and the lazy `meta` property. Per-type definitions cannot override these (engine contract from gh#1889). 2. **Per-type `ref` table** — discovered through `asset.resolve(<typename>, "assetType")` + `require(<identity>.behavior)`. The lookup resolves to whichever `<typename>.assetType/` folder is currently registered for the typename (built-in, user, or library-vendored) and pulls its `ref` methods. 3. **Nil** — unknown key, same shape as the original C metatable. ## Adding methods for a new asset type Drop a `behavior.luau` into the type folder: ``` src/lua/lib/assetTypes/<typename>.assetType/ ├── type.yaml -- structural spec (existing) ├── behavior.luau -- ref + global behaviour (new) └── template/ -- placeholder body (existing) ``` `behavior.luau` returns: ```lua return { ref = { --!desc Per-instance method on every `<typename>` AssetRef. myMethod = function(self, ...) ... end, }, global = { -- Reserved for the asset.<typename>.* surface — not consumed -- yet; included so the contract from gh#1889 lands cleanly. }, } ``` Within `ref` methods, `self` is the AssetRef envelope: `self.path`, `self.identity`, `self.guid`, `self.type`, `self.name` are available. Engine-required fields (`guid`, `path`, `identity`, `type`) must not be redefined. ## Discovery and hot-reload Type discovery uses the asset registry, so it doesn't matter where a `<typename>.assetType/` folder lives — engine built-ins under `@builtin::assetTypes.<X>`, user types dropped under `/zero/source/<X>.assetType/`, or types vendored inside an imported library all resolve identically. The dispatcher walks `asset.resolve(<typename>, "assetType")` → canonical identity → `require <identity>.behavior` on every miss; the asset registry is the cache for the resolve half and Luau's `_LOADED` is the cache for the require half. Hot-reload is transparent. When a `<typename>.assetType/behavior.luau` is rewritten through VFS, the engine's `invalidate_require_cache_for_state` re-runs the module and mutates the cached `_LOADED[<identity>.behavior]` table in place. Dispatch reads `mod.ref` on every access (rather than caching a sub-pointer), so existing AssetRefs see the new methods on the very next access — no Rust-side hook into this module is needed, and no invalidation API is exposed for callers to call. The same registry-driven path also handles type **registration** correctness: dropping a new `<typename>.assetType/behavior.luau` updates the asset registry, the next `asset.resolve(<typename>, "assetType")` returns the new ref, and AssetRefs of that type immediately gain the new methods. ## Why Luau, not Rust The asset surface needed per-category behaviour (`material:getProperties()`, `bundle:instantiate(entityId)`, `tool:run(args)`) and the old shape couldn't grow without an FFI change per method. Owning the proxy in Luau means: - Type-specific methods ship as content (the `<typename>.assetType/` folder), not engine code. - Adding a new asset type drops in a new folder; no Rust rebuild. - Methods can call any other Luau global (`vfs`, `asset`, `Material`, `entity`, etc.) directly, instead of going through narrow FFI primitives. ## Consumers - `crates/zero_scripting/src/ffi/bindings/asset.rs::attach_asset_ref_metatable` — the Rust factory that pushes envelopes invokes `_G.__build_asset_ref_proxy` once per push. - Every Luau call site of `asset.resolve` / `asset.ref` / `entity(id).component.X.material` / any binding declared `AssetRef<...>` — they all receive envelopes built through this module.
▲ 0↑ born
▣
module · born here
❒asset
# yaml.module YAML decode + encode for authored engine content. Pure Luau, no engine dependencies — a general parsing library, not data-system plumbing. ```luau local Yaml = require("@builtin::modules.yaml") local doc = Yaml.decode(vfs.read(path)) vfs.write(path, Yaml.encode(doc)) ``` ## Supported subset - Block mappings (`key: value`) and block sequences (`- item`), nested to any depth. - Compact sequence-of-mapping entries (`- path: x` / ` kind: y`). - Flow collections — `{ a: 1, b: 2 }` and `[1, 2, 3]` — single line. - Plain scalars with type inference: `~` / `null` → nil, `true` / `false` → boolean, numeric literals → number, everything else → string. - Single- and double-quoted strings (`''` escapes a literal quote inside a single-quoted string; `\n` `\t` `\r` `\\` `\"` inside a double-quoted one). A quote opens a quoted scalar where a scalar begins — after `key:`, after a `- ` entry marker, or inside a flow collection — so a plain scalar carries an apostrophe as data (`note: the world's rules`). Quoted keys are read in flow mappings. - `#` comments — honored outside quotes, so a `#` inside a quoted string is kept as data. - Literal (`|`) and folded (`>`) block scalars, with a chomping indicator (`-` strips the final newline, `+` keeps every trailing blank line, none keeps one newline) and an indentation indicator (`1`-`9`: the content's indent past the parent's), in either order (`|-`, `>+`, `|2`, `>1-`). A block scalar's content is literal text: quotes (balanced or not), `#`, `key: value` and `---` inside it are data. - An optional leading `---` document marker. ## Loud-error contract Constructs outside the subset above raise instead of misparsing: anchors/aliases (`&`, `*`), tags (`!`), directives (`%`), multi-document streams (a second `---`), a block-scalar header it cannot read (`|x`, `|-+`, `|0`), tab indentation, and inconsistent indentation (both block structure and block-scalar bodies). Every error carries the offending line number (`yaml: line N: ...`), so a bad config points straight at the line to fix. Tab indentation is rejected everywhere — including block-scalar body lines whose leading whitespace contains a tab. A tab after the first non-space character of a line is content and passes through. ## API - `Yaml.decode(text: string): any` — decode a YAML document into a Luau value (table, scalar, or nil for an empty document). Raises on malformed input or an unsupported construct. - `Yaml.decodeWithComments(text: string): (any, boolean)` — decode as `decode` does, and report whether the text carries a comment by the decoder's own rule: a `#` at a line's start or after whitespace, outside a quoted scalar and outside a block scalar. Re-encoding the value drops such comments, so an editor that writes a document back reads this first. - `Yaml.encode(value: table): string` — encode a Luau table as YAML (block style, two-space indent, alphabetically sorted keys). Raises on values YAML can't represent (functions, userdata, non-string mapping keys). A top-level empty table encodes to an empty document, which decodes back to `nil` (the YAML empty-document ambiguity).
▲ 0↑ born
▣
module · born here
❒asset
# json JSON encode/decode library for Luau. Encodes Lua values to JSON strings and decodes JSON strings back to Lua values. Used for communication with the Rust side of the engine, the VFS read/write bridge, and any wire-format that needs JSON. Pure Luau, no engine dependencies. Compact and pretty-printed encoders, plus a hand-rolled decoder that streams the input by position so it works under WASM as well as native. ## Exports - `Json.encode(value: any, indent?: string, currentIndent?: string) -> string` — compact encode. Functions / unknown types and NaN/Inf encode as `null`. - `Json.encodePretty(value: any, indentStr?: string) -> string` — pretty-printed encode with sorted object keys (diff-friendly). - `Json.encodeArgs(...: any) -> string` — encode varargs as a JSON array. - `Json.decode(str: string) -> any` — decode a JSON string. Returns the decoded value, or `nil` + error message on failure. ## Usage ```luau local Json = require("@builtin::modules.json") local widget = { type = "button", text = "Click Me" } local compact = Json.encode(widget) -- '{"text":"Click Me","type":"button"}' local pretty = Json.encodePretty(widget, " ") local decoded = Json.decode(compact) local v, err = Json.decode("oops") -- v = nil, err = error message ``` ## Notes - Object keys are sorted alphabetically in both encoders for consistent output across runs. - Numeric keys on objects are stringified at encode time (JSON has no numeric keys). Pure-integer key sets get detected as arrays via `isArray` and encoded with brackets. - NaN, +Inf, -Inf encode as `null` — JSON has no representation. Round trips through `decode` recover `null` (Lua `nil`), so they don't preserve. - Unicode `\uXXXX` escapes decode to UTF-8 by hand to stay WASM-safe. Only the BMP is covered; supplementary planes via surrogate pairs are not. - Functions encode as `null`. - Decode is character-streamed — no regex, no `string.match` patterns on the whole input — so the line-and-column information needs to be reconstructed from the position offset.
▲ 0↑ born
▣
module · born here
❒asset
# assetType runtime The machinery that reads a `<typename>.assetType/behavior.luau` and turns its declarations into live behaviour. A `behavior.luau` is a table of declarations — `ref` methods, `modules` shared code, an `events` schema, a `namePattern`, `refShapes`, and the `onCreate` / `onRegister` / `onChange` / `onDelete` / `validate` / `settingsDefaults` / `settingsCorrections` hooks. None of it runs itself. This is the code that runs it, and it lives here because reading a type's declarations is the **assetType type's own behaviour** — the same way `material.assetType` owns what a `.material` does. ## Sub-modules | Module | Reads | Responsibility | |---|---|---| | `ref.module` | `ref`, `modules` | Builds every `AssetRef` envelope, attaches the shared metatable, and dispatches per-type methods and shared modules onto it. Also owns edit-mode write-behind persistence. | | `create.module` | `onCreate`, `namePattern`, `validate` | Backs `asset.create`: resolves the type, checks the name against its pattern, runs `onCreate` (or clones `template/`), and writes the instance. `validate.module` beside it checks a creation `opts` table against the type's `createSchema`. Before running `onCreate`, resolves the type's settings chain (below) and hands the result to the hook as `opts.settings`. | | `settings.module` | `settings`, `settingsDefaults`, `settingsCorrections` | A type's declared settings schema and where its values live (`type.yaml`'s `settings:` block). `Settings.resolveForCreate` layers the schema's own defaults, the type's own `settingsDefaults(name, opts, asked)` hook (a DEFAULT the schema can't express — a name-derived convention, a fact read off a payload the caller handed it, a value following a field `asked` shows a higher layer naming; any later layer overrides it), the Preset Manager, an importer's settings, the caller's `settings` table, then the type's own `settingsCorrections(values, name, opts)` hook (a CROSS-FIELD CONSTRAINT the schema can't express, applied last over the fully merged values). A correction over a default/preset/importer value lands silently; a correction that would override what the caller's own `settings` table explicitly asked for refuses the creation instead, naming the field and why. Neither hook is ever handed a table to mutate; each returns what it wants changed (`settingsCorrections` may also return a `{ [field]: reason }` table for that refusal message). `Settings.cloneValues` deep-copies a values table — `create.module` hands `onCreate` a copy, never the table it stamps. `Settings.valuesOf` / `writeValues` read and write an asset's own values file. | | `typeYaml.module` | `type.yaml` | The folder a type lives in and its parsed `type.yaml`, decoded once per content version of the file. `settings.module` and `inspector.module` read their blocks through it. `about` / `aboutAt` read a type's `about.yaml` (`intent`, `function`, `usage`), leaving out any key that is empty or still starts with `[[describe]]`; `aboutRows` and `aboutMarkdown` lay the texts out for the Inspector and the `types/<name>` guide. | | `inspector.module` | `type.yaml`'s `inspector:` block | Which inspector a type declares for its assets (`inspector: { type: ... }` or `{ instance: ... }`), and the declaration that file returns — the sections it adds, the generic ones it replaces, and their order — or the problem that kept it from loading. | | `onRegister.module` | `onRegister` | Fires an instance's once-only registration hook — on arrival, on world load, and for `@builtin` library instances. | | `changeDispatch.module` | `onChange`, `onDelete`, `refShapes` | Routes a VFS source write or a folder delete to the enclosing typed asset's type hooks. | | `refShapes.module` | `refShapes`, `ref` | Publishes what every `AssetRef<category>` answers to, so a member read on an asset-typed value is checked against that category's real surface. | | `events.module` | `events` | The per-asset event runtime behind `ref.events`. | | `instantiable.module` | `ref.instantiate` | The instantiation contract an asset type opts into: `root` stands the root entity, `place` applies the base placement opts to one the type adopted, and `result` shapes the `(root, idMap)` every `instantiate` returns. Also registers the `sceneInstantiable` field-constraint validator. | | `declaration.module` | `type.yaml` | The type's decoded declaration, read once and held until a write inside an `.assetType` folder; what every question about a type as a whole reads. | | `previewRecipe.module` | `type.yaml` `preview:` | How an instance's `preview.png` is produced: which of the four recipes (`instantiate`, `image`, `surface`, `custom`) the type declares, and what that recipe needs. | ## Reaching it ```luau local rt = require("@builtin::assetTypes.assetType.shared") rt.ref.loadTypeBehavior("material") ``` Fields resolve lazily. The prelude requires the sub-modules directly, in dependency order (`ref`, then `changeDispatch`, `onRegister.install()`, `refShapes.install()`) — a table that required all six on load would take that ordering away from it.
▲ 0↑ born
backing path · modules/api/engine/layers.module

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported on this asset or on the parts this page shows. Parts it leaves out are not counted here.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.