modules

The modules namespace: 3711 functions.

modules/AgentSkillAssetTypeRef/README

require("@builtin::assetTypes.agentSkill.behavior") -- AgentSkillAssetTypeRef

Per-instance methods exposed on every AssetRef<agentSkill>. Loaded lazily by assetType.shared.ref.

Usage: local AgentSkillAssetTypeRef = require("@builtin::assetTypes.agentSkill.behavior")

modules/AgentSkillAssetTypeRef/getInstructions

getInstructions(self): string?

Read the skill's instructions.md body — the prose an agent receives when it invokes the skill.

Parameters

• self any (optional)

local body = skillRef:getInstructions()

modules/AgentSkillAssetTypeRef/getManifest

getManifest(self): { [string]: any }

Read and parse the skill's skill.yaml manifest — its description, declared dependencies, and subskill ordering.

Parameters

• self any (optional)

local m = skillRef:getManifest()

modules/AgentSkillAssetTypeRef/getReadme

getReadme(self): string?

Read the skill's README.md body.

Parameters

• self any (optional)

print(skillRef:getReadme())

modules/AgentSkillAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail — the skill's whole structured surface: { description, kind, when, checks, stages, verdicts, instructions, dependencies, subskills, manifestError }. checks carries each acceptance criterion as { check, observe } — what must hold, and where it is seen. stages carries the ordered passes as { name, detail, checks }, each holding the criteria that only mean anything once that pass has run. verdicts carries the outcomes a reader reports as { verdict, means } — the word, and what reporting it asserts. dependencies carries each declared identity with what it resolved to and whether it resolves here; a toolbox additionally carries the tools it holds, a module the exports it carries, and a tool its own signature, all read live rather than restated. subskills carries each nested skill's parent/sub invoke address. This is the dump skills.invoke renders — a skill with no readable instructions.md still describes, reporting the gap rather than erroring.

Parameters

• self any (optional)

local subskills = asset.inspect(skillRef).detail.subskills

modules/AgentSkillAssetTypeRef/onChange

onChange(self, change)

Lifecycle hook: re-publish this skill when anything inside its folder is written, so a skill just authored is listed and an edited description is the one agents see. Reads the manifest and writes nothing back.

Parameters

• self any (optional) — The changed skill's AssetRef.
• change any (optional) — The write record the dispatcher passes through.

modules/AgentSkillAssetTypeRef/onDelete

onDelete(self)

Lifecycle hook: take this skill's row out of the roster when the skill leaves the runtime — deleted, or moved to a new identity, which registers it again there. The roster lists each skill that exists once.

Parameters

• self any (optional) — The departing skill's AssetRef.

modules/AgentSkillAssetTypeRef/onRegister

onRegister(self)

Lifecycle hook: publish this skill to the roster agents read when the skill first registers. The scope it is listed under is derived from the asset's own identity.

Parameters

• self any (optional) — The registering skill's AssetRef.

modules/AnimationAssetTypeBehavior/README

require("@builtin::assetTypes.animation.behavior") -- AnimationAssetTypeBehavior

Behaviour for the animation asset type — a clip's disk shape. The payload is data.zanim (the engine-native binary AnimAsset, parallel to .mesh's data.zmsh). onCreate writes that payload, and — when the clip's source rig guid is supplied — records it as source_rig.json (a .rig asset reference) so the clip knows the skeleton it was authored on and retargets onto any humanoid. Converters call asset.create("animation", name, { bytes, rig }) to mint a clip.

Usage: local AnimationAssetTypeBehavior = require("@builtin::assetTypes.animation.behavior")

modules/AnimationAssetTypeBehavior/onChange

onChange(ref: any, change: { [string]: any })

React to a write inside a .animation/ instance: when the clip's source rig link (source_rig.json) changes, record the rig's humanoid classification into .metadata for search — the clip inherits it from the rig it targets. Originator-only; .metadata syncs as ordinary content.

Parameters

• ref any (optional) — The AssetRef for the changed clip.
• change { [string]: any } — { path, asset, type, kind, origin }.

modules/AnimationAssetTypeBehavior/reindexSearchMeta

reindexSearchMeta(self): ()

Re-derive this clip's search .metadata (its humanoid classification, resolved from the source rig). onChange calls it when source_rig.json changes; the search-metadata backfill calls it per clip to populate clips minted before the deriver existed.

Parameters

• self any (optional)

animationRef:reindexSearchMeta()

modules/AssetChangeDispatch/README

require("@builtin::assetTypes.assetType.shared.changeDispatch") -- AssetChangeDispatch

Routes a VFS source write to the enclosing typed-asset's onChange(ref, change) hook. Installs _G.__zero_dispatch_asset_change, which the engine calls (via ffi_callbacks::fire_asset_change_dispatch) once per source write.

This is the type-level analogue of the component-centric onAssetReload(field) fan-out. Components react to assets they reference; an asset type reacts to writes INSIDE its own instances. When any file under a <name>.<type>/ folder changes on the VFS, the engine hands the written path here; this module finds the enclosing typed-asset folder, loads its <type>.assetType/behavior.luau, and — if that module exports an onChange function — invokes onChange(ref, change). The engine half is deliberately thin (a generic "this path was written" signal); all the resolution + behaviour lives here in Luau, mirroring the __build_asset_ref_proxy split.

Usage: local AssetChangeDispatch = require("@builtin::assetTypes.assetType.shared.changeDispatch")

modules/AssetChangeDispatch/dispatch

dispatch(path: string, kind: string?, origin: string?)

Dispatch the asset-type change hook for a VFS path. Called by the engine for two orthogonal axes:

• kind: a per-file EDIT ("edited", path is the written file) vs an asset COMPLETION ("seeded", path is the typed-asset folder, now fully present from a world seed). The type inspects kind to decide whether to filter by which file changed or act on the whole asset. "dependency" says a module the asset's code at path required has re-run, or that a reference path names has bound to a target that did not exist before, and goes to the type's onDependencyChange(ref, change) alone.
• origin: "local" for a write made on this client, "remote" for a peer-synced write — forwarded so hooks can gate on it (importers run on the originator only). Resolves the typed asset, loads its behavior.luau, and invokes onChange(ref, change) (change = { path, asset, type, kind, origin }, plus settings and settingsChanged for a write to the settings values file). The written file's content version moves first; the enclosing asset folder's moves last, after the type has reacted. An edit schedules no preview. When the path has no enclosing typed asset, forwards to the loose-file seam (dispatch_loose) so the importer system can claim orphan writes. A hook may wait on what it reads: vfs.read of bytes only the blob store holds fetches them. The writes routed to one asset react in the order they were routed, each once the hook before it has finished.

Parameters

• path string — The VFS path: the written file (edited) or the asset folder (seeded).
• kind string? (optional) — "edited" (default) or "seeded".
• origin string? (optional) — "local" (default) or "remote".

__zero_dispatch_asset_change("/zero/source/Goblin.dynamicAsset/prompt.json", "edited", "local")

modules/AssetChangeDispatch/dispatchDelete

dispatchDelete(path: string, guid: string?)

Dispatch the asset-type DELETE hook for a removed typed-asset FOLDER — the teardown counterpart of dispatch. path is the folder that was removed; this resolves its <name>.<type> identity, loads the type's behavior.luau, and invokes onDelete(ref) if defined (a .component unregisters its type). No-op when the path isn't a registered typed asset or the type defines no onDelete. The engine calls this via ffi_callbacks::fire_asset_delete_dispatch once per typed-asset folder removal. A removal routed while the asset's onChange is waiting tears the asset down once that hook, and every write queued behind it, has finished.

Parameters

• path string — The removed asset folder's VFS path.
• guid string? (optional) — The removed asset's guid, as its manifest row carried it, when the removal knew it.

__zero_dispatch_asset_delete("/zero/source/Spinner.component", guid)

modules/AssetRef/README

require("@builtin::assetTypes.assetType.shared.ref") -- AssetRef

AssetRef proxy builder. Attaches the default method metatable to every { __ref, type, name, guid, identity, path } envelope produced by asset.resolve / asset.ref, and dispatches type-specific methods from <typename>.assetType/behavior.luau so a .material ref carries material-only methods (and so on).

The Rust side (crates/zero_scripting/src/ffi/bindings/asset.rs) used to ship a C metatable with a fixed __index that knew about getSource / getBytes / getText / exists / inspect / meta. That shape couldn't grow without an FFI change, which meant the per-asset-type behaviour required to make refs useful (read a material's properties, instantiate a bundle, run a tool) had no hook. This module owns that responsibility now. It exposes one entry point — M.build(envelope) — that the Rust factory invokes via the _G.__build_asset_ref_proxy global the prelude installs. The build call attaches a shared metatable whose __index first serves the default method table, then falls through to the type's own ref table (loaded lazily from @builtin::assetTypes.<type>.behavior). The default method surface is fixed and engine-required — per-type ref tables CANNOT shadow getSource / getBytes / getText / exists / deps / canInstantiate / canPreview / preview (which calls the type's own ref.preview when it has one), or the lazy meta, runtime, events, typeRef, modules and residency properties. inspect is NOT a fixed default — it falls through to the type's own ref.inspect(self) (returning the type-specific detail for asset.inspect's dispatch), and is nil when the type defines none.

Usage: local AssetRef = require("@builtin::assetTypes.assetType.shared.ref")

modules/AssetRef/build

build(envelope: any): any

Attach the AssetRef method metatable to an envelope table. Invoked by the Rust factory (push_asset_ref_handle → _G.__build_asset_ref_proxy) immediately after the six envelope fields (__ref, type, name, guid, identity, path) have been set, so the metatable's __index only ever fires for method / property lookups, never for the literal envelope fields.

Parameters

• envelope any (optional) — The freshly-built envelope table.

local r = require("@builtin::assetTypes.assetType.shared.ref").build({ type = "material", path = "/zero/source/Gold.material", ... })

modules/AssetRef/canInstantiate

canInstantiate(self): boolean

Whether this asset can be instantiated into a scene — true iff its asset type defines an instantiate method. Generic capability query (no type allowlist); consumers gate on it before offering a scene path (an Asset.source field, a viewport drop, a tool argument).

Parameters

• self any (optional)

if asset.resolve("Golem","dynamicAsset"):canInstantiate() then ... end

modules/AssetRef/canPreview

canPreview(self): boolean

Whether this asset can render a preview — true when its type declares a preview: recipe in its type.yaml, defines its own preview, or defines instantiate (a scene-instantiable asset previews as itself).

Parameters

• self any (optional)

if ref:canPreview() then local p = ref:preview() end

modules/AssetRef/deps

deps(self): { deps: { any }, unresolved_deps: { any }, problems: { any } }

Return this asset's outbound reference table, aggregated across every file inside it (for composite asset folders) — same data asset.deps(ref) returns. deps holds the references that resolved ({ asset_guid, origin, literal, via, line?, checksum?, ... }), unresolved_deps the literals nothing answered ({ literal, via, reason, line? }), and problems the findings attached to the asset. An asset that references nothing returns all three empty.

Parameters

• self any (optional)

modules/AssetRef/flushPendingPersists

flushPendingPersists()

Write out every asset whose edit-mode persistence is still coalesced, spending no allowance and waiting on no refill. The runtime-state wipe on a mode flip calls this first, so a change made in the last window before the flip reaches the asset instead of being cleared with the overlay it lives in. Call it before reading an asset's file for a value a runtime write may have just changed.

require("@builtin::assetTypes.assetType.shared.ref").flushPendingPersists()

modules/AssetRef/forgetRuntime

forgetRuntime(guid: string): boolean

Forget everything a type derived from ONE asset's content — the values it cached in ref.runtime off the bytes that asset used to hold. Called when an asset's content is REPLACED under a guid live consumers already hold: a type memoizes its parse, its GPU handle, its settings against the content it read, and each of those describes the previous bytes the moment the new ones land. Emptying the table in place rather than replacing it is what makes the clear reach every holder — the runtime table is shared by every resolver of the copy the world holds under the guid, and a type may be holding it directly. A recorded version's copy, held in that version's folder, keeps a runtime table of its own and is left as it is.

Parameters

• guid string — The asset's stable guid; the copy the world holds under it is the one forgotten.

require("@builtin::assetTypes.assetType.shared.ref").forgetRuntime(ref.guid)

modules/AssetRef/loadTypeBehavior

loadTypeBehavior(asset_type: string): ({ [string]: any }?, string?)

Load an asset type's behavior.luau module table, reporting a behavior that raised while loading. The first return is the module (nil when the type ships no behavior.luau); the second is set when the type HAS a behavior.luau that raised, and carries the require key plus the error it raised. A caller that runs the type's hooks — asset.create runs onCreate — reads the second return to tell "this type declares no behavior" from "this type's behavior is broken", which are opposite situations for the asset it is about to write.

Parameters

• asset_type string — The type name (e.g. "dynamicAsset", "material").

local mod, err = require("@builtin::assetTypes.assetType.shared.ref").loadTypeBehavior("dialogue")

modules/AssetRef/loadTypeBehaviorOf

loadTypeBehaviorOf(type_ref: any): ({ [string]: any }?, string?)

Load the behavior.luau module table of the asset type type_ref names, from the folder the type asset lies in, the way loadTypeBehavior loads it once the name has resolved. For a caller that already holds the type asset, such as a row of asset.list("assetType").

Parameters

• type_ref any (optional) — The type asset: a ref or a listing row holding its identity and path.

for _, t in ipairs(asset.list("assetType")) do local mod = require("@builtin::assetTypes.assetType.shared.ref").loadTypeBehaviorOf(t) end

modules/AssetRef/loadTypeModule

loadTypeModule(asset_type: string): { [string]: any }?

Load the full behavior.luau module table for an asset type (every key the type declares), or nil when the type ships no behavior.luau. Registry-driven resolution — same path the per-type ref dispatch uses. Exposed so the asset-change dispatcher (@builtin::assetTypes.assetType.shared.changeDispatch) can reach a type's onChange hook without duplicating the resolution logic.

Parameters

• asset_type string — The type name (e.g. "dynamicAsset", "material").

local m = require("@builtin::assetTypes.assetType.shared.ref").loadTypeModule("dynamicAsset")

modules/AssetRef/persistInEditMode

persistInEditMode(self: any)

Generic edit-mode persistence hook an assetType calls when a change of its own is meant to reach the file. In EDIT mode, flush a ref's transient runtime overlay (ref.runtime) to its backing asset file by invoking the type's own saveDefinition(self), so the change syncs to peers and is saved. Works for any assetType that defines a saveDefinition; whether a given type's runtime writes route through here is that type's own contract. The write-through is rate-limited per asset: an asset carries an allowance of 8 writes that refills at one per 250ms. Changes made in one frame are coalesced onto a single re-emit, and a caller that changes a value and moves on has it on disk a frame or two later. A caller that keeps changing the same asset runs the allowance down to its refill rate, so over any span the asset costs at most that allowance plus one write per 250ms, whatever cadence the changes arrive at. In PLAY mode this is a deliberate no-op: runtime overlays stay transient (frame-fast) and are persisted back to the source asset on demand. An assetType opts in simply by exposing ref.saveDefinition; no per-type branching lives here.

Parameters

• self any (optional) — Any AssetRef.

require("@builtin::assetTypes.assetType.shared.ref").persistInEditMode(matRef)

modules/AssetRef/preview

preview(self, opts: { [string]: any }?): { [string]: any }

Render this asset's preview in the preview studio, by the recipe its type declares under preview: in its type.yaml — or through the type's own preview when it defines one (kind: custom). A scene-instantiable type that declares nothing previews by instantiating the asset.

Parameters

• self any (optional)
• opts { [string]: any }? (optional) — { size? = { width, height }, angle? = { yaw, pitch }, live? }.

local p = asset.resolve("gold", "material"):preview({ size = { width = 256, height = 256 } })

modules/AssetRef/requireKeyOf

requireKeyOf(ref: any): string?

The key an asset's own code is required by from a type's behavior: its path, which the module loader answers with the module the asset's identity names, for a world asset and a library one alike. A ref that holds no path is required by the path its guid resolves to, and only a ref with neither by its identity.

Parameters

• ref any (optional) — The asset ref.

local ok, mod = pcall(require, AssetRef.requireKeyOf(moduleRef))

modules/AssetRef/requireTypeModule

requireTypeModule(identity: string?, path: string?, stem: string?, accept: ((any) -> boolean)?): (any?, string?)

Require a module inside an asset folder — a type's <stem>.luau ("behavior", a settings schema file's own stem, or any other module a type.yaml names), or, with no stem, the asset's own entry module (its init.luau, as an importer or a component ships) — from wherever the asset lives (the builtin library, a world-authored folder, a vendored library), through the ONE resolution that works for all of them: see the comment above for the routes it tries in order.

Parameters

• identity string? (optional) — The asset's own resolved identity (ref.identity), or nil.
• path string? (optional) — The asset's own resolved folder path (ref.path), or nil.
• stem string? (optional) — The module's file stem (its filename with .luau stripped), or nil for the asset's entry module.
• accept ((any) -> boolean)? (optional) — Optional acceptance check a loaded module must satisfy to count as a hit — distinguishing "declares none" from "failed to load" for a module whose shape this caller knows. Omit to accept any table.

local schema, err = require("@builtin::assetTypes.assetType.shared.ref").requireTypeModule(identity, path, "settings")

modules/AssetRef/typeModuleKeys

typeModuleKeys(identity: string?, path: string?, stem: string?): { string }

The require keys requireTypeModule tries, in order, for a module inside an asset folder: the asset's identity with the stem appended, then the folder path under @local/. A key reads true from library.has once the module source is registered under it.

Parameters

• identity string? (optional) — The asset's own resolved identity (ref.identity), or nil.
• path string? (optional) — The asset's own resolved folder path (ref.path), or nil.
• stem string? (optional) — The module's file stem, or nil for the asset's entry module.

for _, key in ipairs(AssetRef.typeModuleKeys(ref.identity, ref.path, "schema")) do print(library.has(key)) end

modules/AssetRefShapes/README

require("@builtin::assetTypes.assetType.shared.refShapes") -- AssetRefShapes

Publishes what every AssetRef<category> answers to, so a member read on an asset-typed value is checked against the category's own surface.

An asset category's per-instance surface is authored: a <name>.assetType/behavior.luau declares M.ref = { ... }, and each category declares its own. So the members an AssetRef<inputMap> carries are knowable only to inputMap itself — no fixed set of types covers the ones a world defines, and the checker has no way to guess them. This module reads each registered category's M.ref table from its source (never executing it) and renders it as a Luau table type, then hands the whole set to the engine. From there a ref:method(...) on an asset-typed value resolves against the category's real surface: a name it does not carry is reported with the list of the ones it does. The sweep is complete and replaces what was published before, so a category whose type is removed stops being published. It runs at world load, and again whenever a behavior.luau is written — the assetType type's own onChange hook re-publishes, which is what makes an edited surface take effect without a restart.

Usage: local AssetRefShapes = require("@builtin::assetTypes.assetType.shared.refShapes")

modules/AssetRefShapes/ensure

ensure()

Publish the surfaces if they are not known to be current, and do nothing when they are. This is what a checker calls before it reads them: it makes the published set complete at the moment of use rather than at some earlier moment that may not have arrived yet. A set a sweep left stale while it waited on bytes is swept again once the engine is past the frame that sweep ran in, so a run of checks in one frame pays for one sweep.

AssetRefShapes.ensure()

modules/AssetRefShapes/install

install()

Arm the world-load sweep. Idempotent.

AssetRefShapes.install()

modules/AssetRefShapes/instanceReturnsOf

instanceReturnsOf(typeRef: any, out: { { category: string, identity: string, method: string, definition: string, source: string } })

The instance-derived returns one category contributes: for each of its instances, the type each refShapes entry states for THAT asset. A category whose behavior declares no refShapes contributes none.

This is how a method whose result is shaped by the asset gets typed at all. inputMapRef:activate() answers one handle per binding the map declares — a set that is authored, differs per map, and changes when a control is added — so no fixed signature can state it and only the type itself can compute it.

Each entry is function(self) -> (typeExpression, source?): the type that call answers for THIS asset, and the module whose type vocabulary the expression is written in — the handles an inputMap:activate() answers are Handle, a name its own module declares. Omit the source when the expression names only types visible from anywhere.

Parameters

• typeRef any (optional) — The AssetRef<assetType> for the category.
• out { { category: string, identity: string, method: string, definition: string, source: string } } — Array the { category, identity, method, definition, source } records append to.

AssetRefShapes.instanceReturnsOf(asset.resolve("inputMap", "assetType"), {})

modules/AssetRefShapes/invalidate

invalidate(path: string?)

Mark the published set stale, so the next ensure publishes it again, in the same frame as well. With a path, a write landed at that path: the answers of the instances holding it are computed again and every other one is read from what was kept. Without one, every answer is computed again — what a changed type definition or a world load asks for.

Parameters

• path string? (optional) — The written path, or nil to recompute everything.

AssetRefShapes.invalidate("/zero/source/controls.inputMap/bindings.yaml")

modules/AssetRefShapes/publish

publish(): number

Sweep every registered asset type and publish its ref: surface, plus every instance-derived return its types compute. Complete each time: a category the sweep does not reach stops being published, so a removed type's surface never lingers. The sweep never yields: a source whose bytes are not resident yet is fetched, left unstated, and stated by an ensure in a later frame, which sweeps again while one is outstanding.

AssetRefShapes.publish()

modules/AssetRefShapes/published

published(): { categories: { [string]: string }, returns: { [string]: { [string]: string } } }

What the checker currently believes, as { categories = { [category] = definition }, returns = { [identity] = { [method] = definition } } }. Publishes first, so it answers about the set a check would use rather than a stale one.

This is the answer to "is my type not published, or published and correct?" — from a call site the two look the same, because both are simply no diagnostic. Read it when a member access you expected to be reported was not.

AssetRefShapes.published().returns["@builtin::inputMaps.default"]

modules/AssetRefShapes/shapeOf

shapeOf(typeRef: any): string?

The Luau table type describing one category's ref: surface — the methods its behavior.luau declares, plus everything every AssetRef carries regardless of category. Returns nil when the type ships no behavior or declares no M.ref methods: a category that states nothing of its own is left opaque rather than described by the common members alone, so an access on it stays unchecked instead of being judged against a surface its author never wrote.

Parameters

• typeRef any (optional) — The AssetRef<assetType> for the category.

local t = AssetRefShapes.shapeOf(asset.resolve("inputMap", "assetType"))

modules/AssetTypeAssetTypeRef/README

require("@builtin::assetTypes.assetType.behavior") -- AssetTypeAssetTypeRef

Per-instance methods exposed on every AssetRef<assetType>. Loaded lazily by assetType.shared.ref.

An AssetRef<assetType> points at a <typename>.assetType/ definition folder. SHARED CODE that a type exposes to every instance is declared in that type's own behavior.luau as a modules map of tracked requires, e.g.: -- inside <typename>.assetType/behavior.luau M.modules = { shared = require(".shared") } and reached from any instance through the pinned instance->type link: -- inside any foo.<thatType>/init.luau local api = asset.containing(FILE).modules.shared Resolution follows the instance's pinned typeRef guid (its .refs via = "asset_type" dep), so identically-named modules in different types never collide and an imported instance reaches the exact type version it was authored against. This is the mechanism that makes a type fully self-contained: the behaviour every instance relies on lives in the type, not duplicated as a require("modules.x") in 100 instance files. See @builtin::assetTypes.assetType.shared.ref.module for the dispatch.

Usage: local AssetTypeAssetTypeRef = require("@builtin::assetTypes.assetType.behavior")

modules/AssetTypeAssetTypeRef/getAbout

getAbout(self): { [string]: string }?

Read the three texts the type states about itself in its about.yaml: intent (what the type is for in someone's game), function (how it works) and usage (what a person or agent does with one). Only keys that hold written text are returned.

Parameters

• self any (optional)

local about = assetTypeRef:getAbout(); if about then print(about.intent) end

modules/AssetTypeAssetTypeRef/getReadme

getReadme(self): string?

Read the asset type's own README.md body (type-level docs — what THE TYPE is, surfaced by asset.inspect).

Parameters

• self any (optional)

print(assetTypeRef:getReadme())

modules/AssetTypeAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail for a type definition: { about }, the intent / function / usage texts of its about.yaml, when the type has written them.

Parameters

• self any (optional)

local about = asset.inspect("font", "assetType").detail.about

modules/AssetTypeAssetTypeRef/onChange

onChange(ref, change)

Re-publish every asset category's ref: surface after a write inside a type definition.

Parameters

• ref any (optional) — The AssetRef<assetType> for the edited type.
• change any (optional) — { path, asset, type, kind, origin } for the write.

-- the engine calls this; a behavior.luau edit is picked up live

modules/AssetTypeAssetTypeRef/onCreate

onCreate(name: string): { [string]: string }

Generic-creation hook for asset.create("assetType", name). Scaffolds a new asset type by cloning this type definition's own template/ skeleton with the [name] placeholder rewritten to your type's name, so the new <name>.assetType/ is ready to edit (type.yaml, behavior.luau, and its own template/ instance body). Pure: returns the substituted file map.

Parameters

• name string — The new type's name. Becomes its .<name> instance suffix.

asset.create("assetType", "Waypoint")

modules/AssetTypeAssetTypeRef/validate

validate(ref): { any }

asset.validate's semantic check of a type definition, read from the folder's own type.yaml. Every type names the file its Inspector sections come from with inspector: { type }; a type that names none is assetType.inspector_required, an error for a @builtin type the engine's library authors and a warning for a world's own or for one the library carries by reference (vfs.installedFrom), which the world that published it answers for (a push refuses only errors, so a world holding one still publishes, and its assets show the generic sections). A block that is not a map naming .luau files is assetType.inspector_block, a named file missing from the folder assetType.inspector_file_missing, and one that does not load or returns the wrong shape assetType.inspector_invalid, an error.

Parameters

• ref any (optional) — The AssetRef<assetType> being validated.

local v = asset.validate("@builtin::assetTypes.material")

modules/AssetTypeDeclaration/README

require("@builtin::assetTypes.assetType.shared.declaration") -- AssetTypeDeclaration

A type's type.yaml, decoded: the declaration every question about the type as a whole reads from — which files it holds, whether it broadcasts its subassets, how its instances are pictured. Read once per type and held; the change dispatcher calls forget for every write inside an .assetType folder and for every removed type, so an edited type.yaml is read again.

Usage: local AssetTypeDeclaration = require("@builtin::assetTypes.assetType.shared.declaration")

modules/AssetTypeDeclaration/forget

forget()

Drop every held declaration, so each is read again the next time it is asked for.

declaration.forget()

modules/AssetTypeDeclaration/of

of(typeName: string): { [string]: any }?

The decoded type.yaml of typeName, or nil when no type answers to the name, it has no type.yaml, or the file does not decode — the last with a warning naming the type. The table is shared: read it, do not write to it.

Parameters

• typeName string — The asset type's name ("bundle").

local broadcasts = declaration.of("package").broadcasts_subassets == true

modules/AssetTypePreviewRecipe/README

require("@builtin::assetTypes.assetType.shared.previewRecipe") -- AssetTypePreviewRecipe

How a type makes its instances' pictures, as its type.yaml declares it under preview:. The declaration names one of the four recipes the preview runtime implements, and whatever that recipe needs: | kind | The picture is | Needs | |---|---|---| | instantiate | the asset stood in the studio through its own instantiate | — | | image | a file the instance already holds, fitted to the frame | source.files | | surface | the asset painted on a builtin mesh | mesh | | custom | whatever the type's behavior.luau preview returns | — | It says how an instance's preview.png is PRODUCED. What is embedded for search is a separate declaration, indexing.content, and neither implies the other.

Usage: local AssetTypePreviewRecipe = require("@builtin::assetTypes.assetType.shared.previewRecipe")

modules/AssetTypePreviewRecipe/forget

forget()

Drop every held recipe, so each is read again from its type.yaml the next time it is asked for. The change dispatcher calls this for every write inside an .assetType folder and for every type removed.

previewRecipe.forget()

modules/AssetTypePreviewRecipe/of

of(typeName: string): PreviewRecipe?

The preview recipe typeName declares, or nil when it declares none — in which case its instances persist no picture. Read from the type's type.yaml once, and again after any of the type's files change.

Parameters

• typeName string — The asset type's name ("material").

local r = previewRecipe.of("texture")   -- { kind = "image", files = { ... } }

modules/AssetTypeRuntime/README

require("@builtin::assetTypes.assetType.shared") -- AssetTypeRuntime

The assetType runtime — the machinery that reads a type's behavior.luau and turns its declarations into live behaviour.

A <typename>.assetType/behavior.luau is a table of DECLARATIONS: ref methods, modules shared code, events schema, namePattern, refShapes, and the onCreate / onRegister / onChange / onDelete / validate hooks. Nothing in that table runs itself. This module is what runs it, and it lives inside assetType.assetType/ because reading a type's declarations IS the assetType type's own behaviour — the same way material.assetType owns what a .material does. The sub-modules, one per stage of a type's life:

Field	Reads from behavior.luau	What it does
ref	ref, modules	Builds every AssetRef and dispatches per-type methods onto it.
create	onCreate, onReplace, namePattern, creationInputs	Backs asset.create — scaffolds a new instance of a type.
onRegister	onRegister	Fires an instance's once-only registration hook.
changeDispatch	onChange, onDelete, refShapes	Routes a VFS write or delete to the enclosing asset's type.
refShapes	refShapes, ref	Publishes each category's ref: surface to the checker.
events	events	The per-asset event runtime ref.events reads.
instantiable	ref.instantiate	The instantiation contract a type opts into — stands the root, applies the base placement opts, and shapes the return.
declaration	type.yaml	The type's decoded declaration, read once and held.
previewRecipe	type.yaml preview:	How an instance's preview.png is produced.
settings	type.yaml's settings: block	Resolves an asset's schema, values file and defaults.
typeYaml	type.yaml	The type's folder and its parsed type.yaml, read once per content version.
inspector	type.yaml's inspector: block	The inspector declaration a type names for its assets.
Fields resolve LAZILY. The prelude requires the sub-modules in
dependency order (ref, then changeDispatch, onRegister.install(),
refShapes.install()); a table that required all of them on load would
take that ordering away from it.

Usage: local AssetTypeRuntime = require("@builtin::assetTypes.assetType.shared")

modules/AssetTypeSharedInspector/README

require("@builtin::assetTypes.assetType.shared.inspector") -- AssetTypeSharedInspector

Which inspectors a type declares, and the declaration each file returns. A type names them in type.yaml under inspector:, with either key or both: type: "inspector.luau" is the Inspector for every asset of the type (a file in the type folder); instance: "inspector.luau" is a file each asset may ship in its own folder, whose sections apply to what that asset declares — a component's instances on entities — and never to the asset's own view.

Usage: local AssetTypeSharedInspector = require("@builtin::assetTypes.assetType.shared.inspector")

modules/AssetTypeSharedInspector/blockFor

blockFor(typeName: string): any?

The inspector: value a type declares, or nil. Well-formed, it is a map naming type and/or instance; blockProblem says what is wrong with any other value.

Parameters

• typeName string — The asset type's name.

local InspectorDecl = require("@builtin::assetTypes.assetType.shared.inspector")
local block = InspectorDecl.blockFor("material")

modules/AssetTypeSharedInspector/blockProblem

blockProblem(block: any): string?

Why an inspector: value is malformed, or nil. A block is a map naming type, instance or both, each a .luau file in the folder it applies to.

Parameters

• block any (optional) — The decoded inspector: value.

local InspectorDecl = require("@builtin::assetTypes.assetType.shared.inspector")
local problem = InspectorDecl.blockProblem({ type = "inspector.luau" })

modules/AssetTypeSharedInspector/declarationFor

declarationFor(ref: any): (any?, string?, string?)

The declaration for ref in the asset view: its type's type: inspector.

Parameters

• ref any (optional) — The asset ref.

local InspectorDecl = require("@builtin::assetTypes.assetType.shared.inspector")
local decl, problem, file = InspectorDecl.declarationFor(matRef)

modules/AssetTypeSharedInspector/declarationStamp

declarationStamp(typeName: string): string

Text that moves when what typeName's inspector declaration is made from changes: its type folder and inspector file, and each module the file requires, a module it required before that module was known included. Read after typeDeclaration, which reloads the declaration on such a change; empty for a type whose declaration was never read.

Parameters

• typeName string — The asset type's name.

local InspectorDecl = require("@builtin::assetTypes.assetType.shared.inspector")
local s = InspectorDecl.declarationStamp("material")

modules/AssetTypeSharedInspector/declaresTypeInspector

declaresTypeInspector(typeName: string): boolean

Whether typeName's assets show a declared Inspector in their own view: an inspector: block naming type, or one malformed enough that its problem is what that view shows.

Parameters

• typeName string — The asset type's name.

local InspectorDecl = require("@builtin::assetTypes.assetType.shared.inspector")
if InspectorDecl.declaresTypeInspector("material") then print("declared") end

modules/AssetTypeSharedInspector/instanceDeclarationFor

instanceDeclarationFor(declarerRef: any): (any?, string?, string?)

The declaration declarerRef ships for the things it declares — a component's inspector.luau, applied to that component on an entity. (nil, nil, file) when the type names an instance: file this asset does not ship; (nil, nil, nil) when the type names none.

Parameters

• declarerRef any (optional) — The declaring asset (a component).

local InspectorDecl = require("@builtin::assetTypes.assetType.shared.inspector")
local decl, problem, file = InspectorDecl.instanceDeclarationFor(compRef)

modules/AssetTypeSharedInspector/loadIn

loadIn(typeRef: any, file: string): (any?, string?, string)

Load the inspector file file of the type definition typeRef — the type folder that ref names, whatever other type shares its name — and check its shape.

Parameters

• typeRef any (optional) — The AssetRef<assetType> whose folder holds the file.
• file string — The inspector file its type.yaml names.

local InspectorDecl = require("@builtin::assetTypes.assetType.shared.inspector")
local _, problem = InspectorDecl.loadIn(typeRef, "inspector.luau")

modules/AssetTypeSharedInspector/requiredSeverity

requiredSeverity(typeRef: any): string

How severe a missing inspector: block is on the type definition typeRef: "error" for a @builtin type the engine's library authors, "warning" for a world's own type and for one the library carries by reference (vfs.installedFrom), which the world that published it answers for. A push refuses only errors.

Parameters

• typeRef any (optional) — The AssetRef<assetType>, or any table carrying its identity and path.

local InspectorDecl = require("@builtin::assetTypes.assetType.shared.inspector")
local severity = InspectorDecl.requiredSeverity(typeRef)

modules/AssetTypeSharedInspector/shapeProblem

shapeProblem(decl: any): string?

Check a declaration's shape: sections an array of sections, replace a map of id to section, order an array of ids; any other member a function.

Parameters

• decl any (optional) — What the inspector file returned.

local InspectorDecl = require("@builtin::assetTypes.assetType.shared.inspector")
local problem = InspectorDecl.shapeProblem(decl)

modules/AssetTypeSharedInspector/typeDeclaration

typeDeclaration(typeName: string): (any?, string?, string?)

The declaration a type's own inspector file returns — the sections every asset of typeName shows. (nil, nil, nil) when the type names no type: inspector; (nil, problem, file?) when the block is malformed or the file is missing, fails to load or returns the wrong shape. The answer, a failure included, is held until a file of the type folder or a module the inspector file requires changes.

Parameters

• typeName string — The asset type's name.

local InspectorDecl = require("@builtin::assetTypes.assetType.shared.inspector")
local decl, problem = InspectorDecl.typeDeclaration("material")

modules/AssetTypeSharedSettings/README

require("@builtin::assetTypes.assetType.shared.settings") -- AssetTypeSharedSettings

Typed per-asset settings: which schema governs an asset, what its values are, and where both are declared. A type's type.yaml names its schema file and its values file; nothing here is found by convention.

Usage: local AssetTypeSharedSettings = require("@builtin::assetTypes.assetType.shared.settings")

modules/AssetTypeSharedSettings/acceptedFieldNames

acceptedFieldNames(typeName: string): { string }

Every field name a write to typeName may carry: the fields its schema declares plus the older names its normalizeSettings maps (behavior.luau's normalizedSettingNames), sorted.

Parameters

• typeName string — The asset type's name.

local names = Settings.acceptedFieldNames("texture")

modules/AssetTypeSharedSettings/applyCorrections

applyCorrections(

Apply typeName's cross-field corrections to a complete values table — the one path every settings write takes: resolveForCreate for a new asset, M.writeValues for every later write (asset.setSettings, a type's first-encode seed, the legacy heal). The type's settingsCorrections hook (M.settingsCorrectionsHookOf) is asked once, over a copy of values, for the fields a constraint the schema cannot express forces to another value.

explicit names the fields the writer asked for by name — the settings table passed to asset.create, the patch passed to asset.setSettings. Corrections merge into the values the way every settings layer does (M.mergeValues): a correction to one field of a group leaves the group's other fields. A correction over a field the writer did NOT name applies silently: nobody asked for that value, so overriding it states a fact. A correction that changes a leaf field the writer DID name refuses the whole write, naming the field's path (group.field inside a group), the value asked for, the value it is corrected to, and why it cannot hold (the hook's second return, keyed by the path or the top-level field, or a generic reason) — an explicit request is never silently rewritten into something else.

local fixed = Settings.applyCorrections("texture", values, patch, { label = "asset.setSettings" })

modules/AssetTypeSharedSettings/applyDerivedDefaults

applyDerivedDefaults(

Apply typeName's derived defaults to a complete values table: the type's settingsDerivedDefaults hook (M.derivedHookOf) is asked once, over a copy of values, and every field it answers that explicit does not name takes the answered value. A create passes every schema field as changed; a write passes the fields whose value it moved.

local values = Settings.applyDerivedDefaults("texture", values, { textureType = true }, { textureType = true })

modules/AssetTypeSharedSettings/blockFor

blockFor(typeName: string): any?

The settings: block a type declares, or nil when it declares none.

Parameters

• typeName string — The asset type's name, e.g. "texture".

local block = Settings.blockFor("texture")

modules/AssetTypeSharedSettings/cloneValues

cloneValues(values: { [string]: any }): { [string]: any }

A deep copy of a settings values table — every table-valued field, and every table nested inside one (a Field.settingsOf group, a list of structs), copied at whatever depth it goes. Settings values are YAML-shaped data (tables, strings, numbers, booleans, never a cycle), so a plain recursive table copy is the whole guarantee this makes: nothing a hook or onCreate does to what it's handed, at ANY depth, can reach the table asset.create goes on to stamp into the values file.

Parameters

• values { [string]: any } — The values table to copy.

local copy = Settings.cloneValues(resolved)

modules/AssetTypeSharedSettings/creationInputsOf

creationInputsOf(typeName: string): { [string]: string | boolean }

The creation inputs typeName declares, and the shape each one belongs to — its behavior.luau's exported creationInputs map, when it ships one, or an empty map. A key is a top-level asset.create opt the type's onCreate reads as what the asset is MADE FROM; its value is the name of the opt that selects the shape the input belongs to, or true for an input that belongs to every shape. soundClip declares { sampleRate = "pcm", channels = "pcm", ext = "bytes", writeSource = "bytes" }: sampleRate and channels describe raw PCM as it arrives and mean something only alongside pcm; ext names the container encoded source bytes are in, and writeSource keeps a copy of them, and both mean something only alongside bytes.

asset.create reads it before anything else touches the caller's opts. A declared input given alongside the opt that selects its shape is a creation input and reaches onCreate unchanged. A declared input given on any other shape has no meaning there and never reaches onCreate; one that names no declared setting refuses the create, naming the input and the opt it belongs with.

Parameters

• typeName string — The asset type's name.

Settings.creationInputsOf("soundClip").sampleRate --> "pcm"

modules/AssetTypeSharedSettings/defaultsOf

defaultsOf(schema: any): { [string]: any }

Every declared default of schema, one value per field. A field declared without a default is absent rather than nil-valued.

Parameters

• schema any (optional) — The Field schema table.

local values = Settings.defaultsOf(schema)

modules/AssetTypeSharedSettings/derivedHookOf

derivedHookOf(typeName: string): (({ [string]: any }, { [string]: true }, { [string]: true }) -> { [string]: any }?)?

typeName's own derived-defaults hook — its behavior.luau's exported settingsDerivedDefaults(values, explicit, changed), when it ships one — or nil. It answers the values of fields whose default follows another field (a texture's colour space follows its texture type), given the complete values, the fields the writer named (explicit) and the fields this write changed (changed). The framework applies a returned field only when the writer did not name it (M.applyDerivedDefaults).

Parameters

• typeName string — The asset type's name.

Returns { [string]: any }?)? — The hook function, or nil when the type declares none.

local hook = Settings.derivedHookOf("texture")

modules/AssetTypeSharedSettings/diffFor

diffFor(ref: any, writtenPath: string): ({ [string]: any }?, { [string]: any }?)

The settings a write to writtenPath produced, and which fields it changed, when that path IS the asset's declared values file. A write to anything else answers (nil, nil). A values file that fails its schema answers (nil, nil) too, after reporting the violations — the asset keeps the settings it last had rather than taking an invalid set. changed is computed against an in-process baseline (last_values, forgotten on delete via forgetChangeBaseline) — a fresh process, or an asset diffed for the first time this session, reports every field as old = nil.

Parameters

• ref any (optional) — The asset ref.
• writtenPath string — The path that was written.

local values, changed = Settings.diffFor(ref, change.path)

modules/AssetTypeSharedSettings/fieldNames

fieldNames(typeName: string): { string }

Every field name typeName's settings schema declares, sorted.

Parameters

• typeName string — The asset type's name.

local names = Settings.fieldNames("texture")

modules/AssetTypeSharedSettings/forgetChangeBaseline

forgetChangeBaseline(assetPath: string)

Forget the diff baseline diffFor holds for assetPath — the settings it last saw for that asset's own folder path. Called when the asset is deleted, so a later create that reuses the same path (a delete-then-recreate) diffs its first write against nothing rather than against what the deleted asset last held, and the baseline map does not grow for assets no longer alive.

Parameters

• assetPath string — The asset's own folder path, as diffFor keys its baseline.

Settings.forgetChangeBaseline("/zero/source/Rock.texture")

modules/AssetTypeSharedSettings/healLegacyIfNeeded

healLegacyIfNeeded(ref: any, origin: string?)

Migrate ref's settings out of legacy storage, when a LOCAL edit just landed on an asset that still carries them there: settings in the legacy .metadata block move into its values file, and a values file holding an older spelling (one the type's normalizeSettings rewrites) is rewritten in the declared spelling — every existing asset self-heals this way as it is touched, rather than only on an explicit settings write. Called once per dispatched edit, generically, for every registered type (a type that declares no settings block, an asset whose values file its type ships no normalizeSettings for or holds only the declared spelling, or one with no values file whose .metadata carries no settings key, returns without writing — this is a no-op the overwhelming majority of the time, by construction, and convergent: a second call after healing finds the values file in the declared spelling and does nothing).

Never runs for a REMOTE-origin dispatch — the peer whose own edit this was heals it there, and the migration reaches every other session as an ordinary synced write once it does. Never runs for installed / foreign-origin content (isForeignOrigin, the same check M.writeValues already applies to the .metadata removal) — a library's own content is not this world's to rewrite.

The healed values are what M.valuesOf already reports for this asset — the stored settings read through the type's normalizeSettings (M.normalizeFor), filtered to declared fields, schema-checked — with the fields the type's settingsHealed hook changes for settings stored before its schema decided them (a texture whose settings predate compression heals to the compression it should have). The diff baseline is seeded with the values read before the heal, so that write's own follow-up dispatch reports only what the hook changed: nothing, when healing only relocates storage — the edit that triggered the heal already got its own reaction from the dispatch that called this — and the changed fields otherwise, which the type reacts to as to any settings change.

Parameters

• ref any (optional) — The asset ref the just-applied edit landed on.
• origin string? (optional) — The dispatch's origin ("local"/nil, or "remote") — see AssetChangeDispatch.dispatch.

Settings.healLegacyIfNeeded(ref, change.origin)

modules/AssetTypeSharedSettings/isForeignOrigin

isForeignOrigin(ref: any): boolean

True when ref's origin is outside this world — installed from a library, or carried by the engine's library by reference, rather than authored here or shipped with the engine. Read through the same envelope asset.inspect reports, origin.kind: "installed" for either, and "authored" for a world-authored or builtin asset. An origin asset.inspect cannot answer (it raises, or reports a shape these reads don't recognise) resolves foreign: what this guards is that a foreign asset's legacy settings are never dropped or rewritten, so an undetermined origin takes the side that leaves the asset's content as it is.

Parameters

• ref any (optional) — The asset ref.

if not Settings.isForeignOrigin(ref) then Settings.healLegacyIfNeeded(ref, "local") end

modules/AssetTypeSharedSettings/mergeValues

mergeValues(schema: any, base: { [string]: any }?, overlay: { [string]: any }?): { [string]: any }

Lay overlay over base under schema, the one way settings layers combine: a field overlay names replaces the field in base, except a struct field (a Field.struct, or a Field.settingsOf group) that both hold as tables, which merges field by field at whatever depth it nests — so a layer naming one field of a group leaves the group's other fields where the layers below put them. Neither input is modified; the result is a deep copy.

Parameters

• schema any (optional) — The Field schema the values follow (the fields of a struct at depth), or nil to replace every named field.
• base { [string]: any }? (optional) — The values below.
• overlay { [string]: any }? (optional) — The values laid over them.

Settings.mergeValues(schema, { group = { a = 1, b = 2 } }, { group = { b = 3 } }) --> { group = { a = 1, b = 3 } }

modules/AssetTypeSharedSettings/normalizeFor

normalizeFor(typeName: string?, values: { [string]: any }, stored: { [string]: any }?): { [string]: any }

values in the spelling typeName's schema declares: the type's normalizeSettings applied, or values itself when it ships none. Every settings source passes through here — a values file, a legacy .metadata block, a create's preset / importer / caller layers, a asset.setSettings patch — so an older spelling reads, creates and writes as the field it names today. The hook is handed copies; neither table passed here is modified.

Parameters

• typeName string? (optional) — The asset type's name (nil answers values unchanged).
• values { [string]: any } — A settings table in any spelling the type accepts.
• stored { [string]: any }? (optional) — The asset's current values, when values is a patch over them.

local values = Settings.normalizeFor("texture", { format = "bc7" })

modules/AssetTypeSharedSettings/normalizeHookOf

normalizeHookOf(typeName: string): (({ [string]: any }, { [string]: any }?) -> { [string]: any })?

typeName's own normalisation hook — its behavior.luau's exported normalizeSettings(values, stored?), when it ships one — or nil. The hook maps every older spelling a stored file or a write may carry (a renamed field, an older enum member) to the field and member the schema declares now, and returns a new table. stored, when given, is the asset's current values, which an older spelling in a patch may need to keep the meaning it had against them.

Parameters

• typeName string — The asset type's name.

Returns { [string]: any })? — The hook function, or nil when the type declares none.

local hook = Settings.normalizeHookOf("texture")

modules/AssetTypeSharedSettings/orderedNames

orderedNames(schema: any): { string }

The field names of schema in the order they are declared: by each descriptor's declaredOrder, a name breaking a tie and a descriptor without one sorting after those that carry one.

Parameters

• schema any (optional) — The Field schema table.

for _, name in ipairs(Settings.orderedNames(schema)) do print(name) end

modules/AssetTypeSharedSettings/presetLayerFor

presetLayerFor(typeName: string, destPath: string): ({ [string]: any }?, any?)

The Preset Manager's layer for a new asset of typeName at destPath: the valid values of the world's first [[presets]] row naming the type's assetType whose filter matches the new asset's path (under /source for a durable asset, under /runtime/assets for a runtime one), and the match. Nil for any other destination, a type with no type-level schema, or no matching row.

Parameters

• typeName string — The asset type being created.
• destPath string — Where the new asset lands.

local layer = Settings.presetLayerFor("texture", "/zero/source/sprites/hero.texture")

modules/AssetTypeSharedSettings/recordedWrite

recordedWrite(path: string, text: string)

Write text to path, recording the write into the open undo operation when one is open so undoing it restores the file's previous contents. Raises when the write fails.

Parameters

• path string — VFS path.
• text string — The whole new contents.

local Yaml = require("@builtin::modules.yaml")
Settings.recordedWrite(ref.path .. "/values.yaml", Yaml.encode(doc))

modules/AssetTypeSharedSettings/requiredModulesCurrent

requiredModulesCurrent(record: any, ref: any): boolean

Whether a value read alongside record still stands: every module it listed holds the version it was listed at, and — when some required module was not yet known — none of those has become known since. That last question is asked again at most every quarter second, so a read held while a module was unknown is not read again on every call.

Parameters

• record any (optional) — What requiredModulesRecord answered.
• ref any (optional) — The asset the record was taken for.

if held and Settings.requiredModulesCurrent(held.modules, ref) then return held.value end

modules/AssetTypeSharedSettings/requiredModulesRecord

requiredModulesRecord(ref: any): { deps: { { path: string, version: number } }, depsPending: boolean, depsCheckedAt: number }

What a read derived from ref's code depends on beyond ref's own files: the entry file of each module its sources require (as its reference table has bound them), with the content versions they have now, and whether some module it requires is not yet known. Hold it beside the value read, and ask requiredModulesCurrent before serving the value again.

Parameters

• ref any (optional) — The asset.

held.modules = Settings.requiredModulesRecord(ref)

modules/AssetTypeSharedSettings/requiredModulesStamp

requiredModulesStamp(record: any, ref: any): string

Text that moves when a module a record listed changes, or when a module it required before that module was known becomes known (asked at most every quarter second, as requiredModulesCurrent asks it): the content versions of its listed modules now, and whether the read beside it has gone stale. Fold it into a build signature to rebuild what was read from code that requires them.

Parameters

• record any (optional) — What requiredModulesRecord answered.
• ref any (optional) — The asset the record was taken for.

parts[#parts + 1] = Settings.requiredModulesStamp(held.modules, ref)

modules/AssetTypeSharedSettings/resolveForCreate

resolveForCreate(

Resolve the settings a created asset is stamped with. For a new asset the layers, lowest priority first, are: the schema's declared defaults, the type's own settingsDefaults hook, the Preset Manager's first matching row, the creating importer's settings for this type, and the settings table the caller passed. When destPath already holds an asset of typeName that records settings of its own, it is being re-authored — overwrite = true, or an importer re-creating what it made inside its container — and those settings take the place of every layer below the caller's, so what it was stamped with and edited to stays. An asset that records none (a hand-written container being seeded) takes the layers a new asset takes. Each layer overrides the ones before it, field by field, and a struct field merges field by field inside (M.mergeValues). Each layer is read through the type's normalizeSettings (M.normalizeFor), so a layer naming a field in an older spelling sets the field it names today. Once every layer has merged, the type's derived defaults (M.applyDerivedDefaults) set each field whose default follows another and that no layer above the schema named; for a re-authored asset its own settings name nothing, and a derived field follows only a field the caller's settings changed. Then M.applyCorrections applies the type's cross-field corrections with the caller's settings table as the explicit fields: a correction over a field that came from any layer below the caller applies silently, and one that contradicts a field the caller's own settings table set refuses the creation, naming the field, the value asked for, and why it cannot hold.

The (possibly corrected) result is checked against the schema, so a bad value nothing corrects refuses the creation rather than landing in a new asset.

local values = Settings.resolveForCreate("texture", name, dest, opts, opts.settings, nil)

modules/AssetTypeSharedSettings/resolvePatch

resolvePatch(ref: any, patch: { [string]: any }): ({ [string]: any }, { [string]: any })

The complete values a partial settings patch writes — the values asset.setSettings hands M.writeValues. The patch is read through the type's normalizeSettings against the asset's current values, so an older field name lands as the field it names today with the meaning it had for this asset, and is merged over those values, a struct group field by field (M.mergeValues); the type's derived defaults (M.applyDerivedDefaults) then move each field that follows a field this patch changed, unless the patch names it too. M.writeValues applies the corrections with the normalised patch as the explicit fields.

Parameters

• ref any (optional) — The asset ref.
• patch { [string]: any } — Any subset of the schema's fields, in the current or an older spelling.

local values, named = Settings.resolvePatch(texRef, { compression = "uastc" })

modules/AssetTypeSharedSettings/schemaFor

schemaFor(ref: any): any?

The schema governing ref's own settings values — the type-level schema when its type declares one, else the schema the asset declares for itself. ref naming an assetType asset itself (rather than an instance of one) reports that TYPE's own declared schema — the same schema every instance of it reports.

Parameters

• ref any (optional) — The asset ref.

local schema = Settings.schemaFor(texRef)

modules/AssetTypeSharedSettings/schemaForType

schemaForType(typeName: string): any?

The schema governing the settings of assets of typeName, when the type declares one at type level (schema: { type = ... }).

Parameters

• typeName string — The asset type's name.

local schema = Settings.schemaForType("texture")

modules/AssetTypeSharedSettings/schemaOfDeclarer

schemaOfDeclarer(identity: string): any?

The schema a declarer declares, named by its identity. This is what Field.settingsOf(identity) resolves to: an assetType's instance-settings schema, or an importer's / component's own declared schema.

Parameters

• identity string — The declarer's asset identity.

local schema = Settings.schemaOfDeclarer("@builtin::assetTypes.texture")

modules/AssetTypeSharedSettings/schemaOfInstance

schemaOfInstance(ref: any): any?

The schema an individual asset declares for itself, when its type says the schema is per instance (schema: { instance = ... }). Whether an instance may lack the file is what the type's files: block says of it: a schema file listed under files.optional may be absent, and an instance without one declares no settings; one listed under files.required, or not listed at all, must load, and a missing one is the instance's declaration broken, and is logged.

Parameters

• ref any (optional) — The asset ref.

local schema = Settings.schemaOfInstance(importerRef)

modules/AssetTypeSharedSettings/schemaProblemOf

schemaProblemOf(ref: any): string?

Why ref's settings schema resolved to nothing: the declaring file could not be read, compiled, run, or did not declare its table; or the type refused what it declared — the sentence its behavior.luau's exported settingsSchemaProblem(schema, ref) returned. Nil when the schema resolved or ref's type declares none.

Parameters

• ref any (optional) — The asset ref.

local why = Settings.schemaProblemOf(compRef)

modules/AssetTypeSharedSettings/seedChangeBaseline

seedChangeBaseline(assetPath: string, values: { [string]: any })

Record values as the settings diffFor last saw for assetPath, so the dispatch of a values file written with exactly these values reports nothing changed. Every writer that has ALREADY done what those values ask for calls it with what it writes: asset.create after stamping a new asset (its onCreate encoded against them), a type's first-encode seed of a hand-written container, and the legacy heal (which moves values without changing one). A later write that changes a field still diffs against these and reports that field.

Parameters

• assetPath string — The asset's own folder path, as diffFor keys its baseline.
• values { [string]: any } — The complete values table the values file holds.

Settings.seedChangeBaseline(rawget(texRef, "path"), values)

modules/AssetTypeSharedSettings/settingsCorrectionsHookOf

settingsCorrectionsHookOf(typeName: string): (({ [string]: any }, string, { [string]: any }?) -> ({ [string]: any }?, { [string]: string }?))?

typeName's own settings-corrections hook — its behavior.luau's exported settingsCorrections(values, name, opts), when it ships one — or nil. Where settingsDefaults supplies an opinion a layer below the caller can still override, this hook enforces a cross-field constraint the schema itself has no way to express (a field whose valid range depends on another field's resolved value). M.applyCorrections calls it on every settings write — once a create's layers have merged, and on every later write of the values file. Called with the complete values; it READS them and RETURNS a table of the corrections to apply (or nil for none), rather than mutating what it was given. A SECOND return, { [field]: reason }, names why a corrected field cannot hold the value it is being corrected away from — used only when the writer named that field explicitly, to explain the refusal; omitted or missing a field falls back to a generic reason.

Parameters

• typeName string — The asset type's name.

Returns ({ [string]: any }?, { [string]: string }?))? — The hook function, or nil when the type declares none.

local hook = Settings.settingsCorrectionsHookOf("texture")

modules/AssetTypeSharedSettings/settingsDefaultsHookOf

settingsDefaultsHookOf(typeName: string): ((string, { [string]: any }?, { [string]: any }) -> { [string]: any }?)?

typeName's own create-time settings-defaults hook — its behavior.luau's exported settingsDefaults(name, opts, asked), when it ships one — or nil. A type contributes a layer here for whatever it can only compute at creation (a name-derived convention, a fact read off a pre-encoded payload the caller handed it, a default that follows a field another layer sets); resolveForCreate calls it once per create, above the schema's own defaults and below every other layer, with asked holding what the layers above it (the Preset Manager, an importer, the caller) name, field by field, the higher layer's value where two name one. The hook returns a fresh table of its own opinions; it is never handed anything to mutate, and a field it returns that a layer above it names takes that layer's value.

Parameters

• typeName string — The asset type's name.

Returns { [string]: any }?)? — The hook function, or nil when the type declares none.

local hook = Settings.settingsDefaultsHookOf("texture")

modules/AssetTypeSharedSettings/settingsHealedHookOf

settingsHealedHookOf(typeName: string): (({ [string]: any }, { [string]: any }) -> { [string]: any }?)?

typeName's own settings-heal hook — its behavior.luau's exported settingsHealed(values, stored), when it ships one — or nil. Healing moves an asset's settings out of older storage on a local edit; this hook answers the fields whose value that move changes, for content whose stored settings predate what the type's schema now decides. values is what a read of the stored settings reports, stored the settings exactly as stored (before an older spelling is read as today's). It returns the fields to change, or nil for none.

Parameters

• typeName string — The asset type's name.

Returns { [string]: any }?)? — The hook function, or nil when the type declares none.

local hook = Settings.settingsHealedHookOf("texture")

modules/AssetTypeSharedSettings/valuesEqual

valuesEqual(a: any, b: any): boolean

Structural equality for a settings value at any depth: two tables are equal when they hold the same keys and every value is itself equal (recursively), and two scalars (string, number, boolean, nil) are equal by ==. Table VALUES in a settings table are always freshly built — defaultsOf clones a default, read_values_file decodes a fresh table from YAML — so comparing them by reference would report a table-valued field as changed on every read even when its contents are identical. The one comparison every settings-value equality check in this module shares — diffFor's own diff and resolveForCreate's caller-conflict check both call this rather than each carrying its own. Takes acyclic settings values — YAML-shaped data, the same invariant clone_value relies on — so the recursive walk always terminates.

Parameters

• a any (optional) — A settings value (a scalar or a table, at any nesting depth).
• b any (optional) — A settings value to compare it against.

Settings.valuesEqual({ a = 1, b = { 2, 3 } }, { a = 1, b = { 2, 3 } }) --> true

modules/AssetTypeSharedSettings/valuesOf

valuesOf(ref: any): { [string]: any }?

This asset's settings values: every declared default, overlaid with what its values file holds — or, for content that predates the values file, with its legacy .metadata settings. A field neither sets reads as its declared default, so content written before a field existed still answers for it. A stored field the schema no longer declares is filtered out, so a schema revision that drops a field leaves old content reading as clean rather than carrying a value nothing recognises. A stored value that fails its own field's constraint is dropped the same way — the field falls back to its declared default and a warning names the path, the field and the violation — so a read never answers with a value the schema (and therefore the type's own encode) refused. The values are resolved in memory from what is already on disk. An asset whose type declares no values file holds no settings values of its own — a component's live on each entity it is on — and reads as nil, while its schema still answers through schemaFor.

Parameters

• ref any (optional) — The asset ref.

local s = Settings.valuesOf(texRef)

modules/AssetTypeSharedSettings/valuesPathOf

valuesPathOf(ref: any): string?

The path of ref's settings values file, per its type's declared settings.values, or nil when its type declares no values file. A ref that carries its guid or identity without its path reaches the same file through what that name resolves to.

Parameters

• ref any (optional) — The asset ref.

local p = Settings.valuesPathOf(texRef)

modules/AssetTypeSharedSettings/whyNoSettings

whyNoSettings(ref: any): string

Why ref carries no settings, as a sentence naming where they would be declared: the type declares no settings block; or the type declares a schema per instance and this instance ships none, naming the file it would be; or the type's declared schema did not load.

Parameters

• ref any (optional) — The asset ref, one for which M.schemaFor answered nil.

error("asset.setSettings: " .. Settings.whyNoSettings(ref))

modules/AssetTypeSharedSettings/writeActedValues

writeActedValues(ref: any, values: { [string]: any })

Write ref's whole values file (M.writeValues) with values, the settings the caller has already acted on, and seed the change baseline with what was written (M.seedChangeBaseline) before that write's dispatch runs, so the dispatch reports nothing changed and no reaction runs a second time.

Parameters

• ref any (optional) — The asset ref.
• values { [string]: any } — The complete values table.

Settings.writeActedValues(texRef, values)

modules/AssetTypeSharedSettings/writeValues

writeValues(ref: any, values: { [string]: any }, explicit: { [string]: any }?): { [string]: any }

Write this asset's whole settings values file. The values (and explicit) are read through the type's normalizeSettings first, so an older spelling is stored as the field it names today. They then take the type's cross-field corrections (M.applyCorrections, with explicit as the fields the writer named — a correction contradicting one of them refuses the write), then are checked against the schema. Every violation is reported in one error naming the field, what it takes, and where the schema is declared. When the asset also carries legacy .metadata settings and its origin is authored — this world's own content, or the engine's builtin library — the legacy key is dropped as part of this same write, so the values file above is what a read prefers from here on. A library-installed asset keeps its .metadata settings key alongside the values file this call writes. Inside an undo operation, the write is recorded so undoing the operation restores the previous file contents; authored legacy content is first healed into its values file, so undo returns it to the healed file, which reads the same values as the legacy one. When that heal does not complete, the legacy settings stay in .metadata and the step records the values file alone, so undo falls back to the legacy values.

Parameters

• ref any (optional) — The asset ref.
• values { [string]: any } — The complete values table.
• explicit { [string]: any }? (optional) — The fields the writer asked for by name (a patch), or nil.

Settings.writeValues(texRef, { filter = "nearest", colorSpace = "srgb" })

modules/AssetTypeSharedTypeYaml/README

require("@builtin::assetTypes.assetType.shared.typeYaml") -- AssetTypeSharedTypeYaml

A type's type.yaml, parsed: the folder a type lives in and the document its type.yaml holds, read once per content version of that file. Every block a type declares — settings:, inspector: — is read from here, and so are the texts of its about.yaml (about, aboutAt).

Usage: local AssetTypeSharedTypeYaml = require("@builtin::assetTypes.assetType.shared.typeYaml")

modules/AssetTypeSharedTypeYaml/about

about(typeName: string): { [string]: string }?

The written about.yaml texts of the type typeName; see aboutAt.

Parameters

• typeName string — The asset type's name.

local about = TypeYaml.about("font")

modules/AssetTypeSharedTypeYaml/aboutAt

aboutAt(folder: string): { [string]: string }?

The texts the type folder at folder states in its about.yaml: intent (what the type is for in someone's game), function (how it works) and usage (what a person or agent does with one). Only the keys that hold written text are returned; a key that is missing, empty or still starts with the [[describe]] marker is left out.

Parameters

• folder string — The type's folder, e.g. /zero/source/libs/@builtin/assetTypes/font.assetType.

local about = TypeYaml.aboutAt("/zero/source/libs/@builtin/assetTypes/font.assetType")

modules/AssetTypeSharedTypeYaml/aboutMarkdown

aboutMarkdown(about: { [string]: string }?): string

The about.yaml texts as a Markdown section titled "About this type", each text under its label. Empty text when no key holds written text.

Parameters

• about { [string]: string }? (optional) — What about / aboutAt returned, or nil.

print(TypeYaml.aboutMarkdown(TypeYaml.about("font")))

modules/AssetTypeSharedTypeYaml/aboutRows

aboutRows(about: { [string]: string }?): { { key: string, label: string, text: string } }

The labelled about.yaml texts as { { key, label, text } } in reading order: Intent, Function, Usage. Empty when no key holds written text.

Parameters

• about { [string]: string }? (optional) — What about / aboutAt returned, or nil.

for _, row in ipairs(TypeYaml.aboutRows(TypeYaml.about("font"))) do print(row.label, row.text) end

modules/AssetTypeSharedTypeYaml/describeBlock

describeBlock(typeName: string): { guidance: string?, examples: { string } }

What services describe hands the model when it writes a description for an asset of this type: the type's own guidance on what to cover, and the identities of the examples whose descriptions show the shape.

Parameters

• typeName string — The asset type's name.

local block = TypeYaml.describeBlock("module"); print(block.guidance)

modules/AssetTypeSharedTypeYaml/described

described(typeName: string): { DescribedFile }

The files a type's assets must describe: every file its type.yaml declares with a described content check, with the keys and headings the check names and the limit on each key. Empty when the type asks its assets for no description.

Parameters

• typeName string — The asset type's name.

for _, f in ipairs(TypeYaml.described("module")) do print(f.file, f.required) end

modules/AssetTypeSharedTypeYaml/folder

folder(typeName: string): (string?, string?)

The folder the assetType typeName lives in, and its identity.

Parameters

• typeName string — The asset type's name, e.g. "texture".

local folder, identity = TypeYaml.folder("material")

modules/AssetTypeSharedTypeYaml/of

of(typeName: string): { [string]: any }?

The document typeName's type.yaml holds, decoded. Read again when the file's content changes.

Parameters

• typeName string — The asset type's name.

local doc = TypeYaml.of("material"); print(doc.suffix)

modules/AssetValidator/README

require("@builtin::systems.worldValidation.assetValidator") -- AssetValidator

Structure validator for asset folders. Delegates each asset to asset.validate — the engine primitive that checks the folder against its type's type.yaml (required files, one_of_groups, unexpected entries, content constraints), waives the describe-this-asset requirements for private subassets (assets nested inside a non-broadcasting container like a .bundle), and runs the type's own semantic validate hook — and maps the result into the report's Problem records.

asset.validate is the same primitive the world.push gate runs, so a world that validates clean here also passes the structural half of the publish gate. Each problem is attributed to the asset path (missing files anchor at the asset root; existing files — unexpected entries, content violations — anchor at the file). An asset whose type has no registered type.yaml gets a schema.unknown_type warning; an asset the registry cannot resolve (e.g. written this frame, registration still draining) gets a schema.unresolved_asset warning.

Usage: local AssetValidator = require("@builtin::systems.worldValidation.assetValidator")

modules/AssetValidator/dependencyProblemsFrom

dependencyProblemsFrom(path: string, deps: any, guidCache: { [string]: boolean })

Map an asset's reference table into publish-blocking Problem records. Split from the lookup so the mapping can be exercised on a reference table directly. A guid already present in guidCache is not looked up again.

Parameters

• path string — Asset path the problems are attributed to.
• deps any (optional) — Reference table in the shape asset.deps returns.
• guidCache { [string]: boolean } — Memo of guid → whether the live asset index carries it.

local problems = AssetValidator.dependencyProblemsFrom(path, asset.deps(path), {})

modules/AssetValidator/validate

validate(entry, guidCache: { [string]: boolean }?)

Validate one asset folder via asset.validate and map the result into Problem records.

Parameters

• entry any (optional) — Asset entry from vfsScanner — { path, name, type }.
• guidCache { [string]: boolean }? (optional)

local problems = AssetValidator.validate({ path = "/source/Foo.component", name = "Foo.component", type = "component" })

modules/AssetValidator/validateBatch

validateBatch(assets)

Validate a batch of asset entries and flatten the per-asset problem lists into one array. Convenience wrapper over M.validate.

Parameters

• assets any (optional) — Array of asset entries from the scanner.

local all = AssetValidator.validateBatch(bucket.assets)

modules/AvatarAssetTypeBehavior/README

require("@builtin::assetTypes.avatar.behavior") -- AvatarAssetTypeBehavior

Behaviour for the avatar asset type — a playable character composed from three INDEPENDENT parts so each swaps on its own axis: - body — a .bundle: skinned mesh + bone entities (the look). - controller — the movement system (default: CharacterController + MovementState + Humanoid, the standard kinematic humanoid mover). - animation — the system that animates the body (default: the shared Locomotion blend space, which reads the controller's velocity and plays retargeted clips; or ClipPlayer; or your own component). Movement and animation are NOT tied together: attaching the controller never pulls in Locomotion, and choosing your own animation keeps the standard controller — so authoring your own locomotion is a one-field swap. The clip set retargets onto any humanoid rig, so the default locomotion drives any humanoid body with no per-body setup. :instantiate() composes the parts; :setCharacter(root, body) swaps the body. Point a scene's PlayerPrototype.body at a body carrying this avatar to make it the body every connecting player spawns with.

Usage: local AvatarAssetTypeBehavior = require("@builtin::assetTypes.avatar.behavior")

modules/AvatarAssetTypeBehavior/instantiate

instantiate(self, target: EntityRef?, opts: any): (EntityRef, { [string]: string })

Instantiate this avatar: spawn an avatar root, spawn the body bundle under it, then attach the movement controller and the animation system — independently. With the defaults the root gets the standard humanoid controller and the shared Locomotion that drives the body with retargeted clips. Pass a target entity REF to make that entity the avatar root (the player-avatar path passes the freshly-spawned avatar entity here).

Parameters

• self any (optional)
• target EntityRef? (optional) — Optional avatar root as an EntityRef. Omit to spawn one.
• opts any (optional) — Optional { position, rotation, scale, name, temporary, idMap, diff, sourceTag } — the base placement opts land on the root; idMap pins the composed body root, label, and every body-bundle child to stable ids across re-instantiations; diff replays the user's sparse edits to the composed body. sourceTag marks the call as owned — the Asset component sets it when it drives the composition itself.

local av = avatarRef:instantiate()

modules/AvatarAssetTypeBehavior/onCreate

onCreate(name: string, opts: CreateOpts?): { [string]: string }

Generic-creation hook for asset.create("avatar", name, opts). Composes the avatar from a body plus an independent movement controller and animation system, written as avatar.json. The body is a .bundle (skinned mesh + bones), a plain .mesh (a simple visual), or omitted (a body-less avatar — a controller / first-person camera with no mesh). Defaults: the standard humanoid controller and, for a humanoid body, the shared Locomotion (clips from the locomotion preset, default "synty"). Override animation to author your own locomotion without touching movement; pass controller = false for a body the engine doesn't move; pass clip for a single-clip ClipPlayer. Humanoid-ness drives the default animation only and is auto-derived from a rigged body; pass humanoid to set it explicitly (e.g. a body-less first-person avatar that still carries Humanoid).

Parameters

• name string
• opts CreateOpts? (optional)

asset.create("avatar", "my_hero", { body = heroBundle })  -- standard controller + locomotion
asset.create("avatar", "fp_player", { humanoid = true })  -- body-less first-person player

modules/AvatarAssetTypeBehavior/setCharacter

setCharacter(self, root: any, body: any): EntityRef

Swap the body on a live avatar. Despawns the current body and spawns body (a .bundle ref) in its place. The controller + animation systems live on the avatar root and re-resolve the new body's rig, so the look swaps while movement and animation are kept. A single-clip ClipPlayer rides the skinned body, so it is re-attached to the new body. Every item seated with Humanoid:attach is kept and re-seated on the new body's socket for the same point, with the same transform, as soon as the new body's skeleton stands (within the call when the body wakes inside it); an item whose point the new body does not have stays on the avatar root. The new body takes the old body's id and is composed with the options the avatar was instantiated with, and the avatar's Asset id map is updated to name it.

Parameters

• self any (optional)
• root any (optional) — The live avatar root (an EntityRef from :instantiate()).
• body any (optional) — The new body — a .bundle ref (guid / identity / AssetRef).

avatarRef:setCharacter(avatarRoot, asset.resolve("knight", "bundle"))

modules/AvatarTypeAssetTypeBehavior/README

require("@builtin::assetTypes.avatarType.behavior") -- AvatarTypeAssetTypeBehavior

Behaviour for the avatarType asset type. An avatar type describes a kind of body (a humanoid, a quadruped, a vehicle): the roles and chains a rig of that kind maps onto, and how to find them in a skeleton. An avatar points at its type by guid, and a rig stores its author's overrides per type. The type's init.luau is the module; ref:module() loads it.

Usage: local AvatarTypeAssetTypeBehavior = require("@builtin::assetTypes.avatarType.behavior")

modules/AvatarTypeAssetTypeBehavior/onChange

onChange(self, _change)

Drop the cached module and advance the generation when the type's content changes, so the next :module() loads the edited init.luau and every rig qualified under the old one is qualified again.

Parameters

• self any (optional) — The avatarType AssetRef that changed.
• _change any (optional) — What happened to it; the cache is dropped whatever it was.

modules/BlankAppLayout/README

require("@builtin::_templates.blank_app.blank_app_layout") -- BlankAppLayout

Minimum-viable app — one screen built from the raw CSS-parity widget tree. Clone-and-edit starting point; replace build with your own tree.

Usage: local BlankAppLayout = require("@builtin::_templates.blank_app.blank_app_layout")

modules/BundleAssetTypeRef/README

require("@builtin::assetTypes.bundle.behavior") -- BundleAssetTypeRef

Per-instance methods exposed on every AssetRef<bundle>. Loaded lazily by assetType.shared.ref.

Usage: local BundleAssetTypeRef = require("@builtin::assetTypes.bundle.behavior")

modules/BundleAssetTypeRef/getTemplate

getTemplate(self): any

Parse the bundle's entity_template into a Lua value. The engine format is a flat array of entity records ({ name, original_id, parent_id, components, ... }), so the result is an array-table; the return type is any because the payload is decoded JSON. Returns nil when parsing fails or the bundle has no template. Parsed results are cached per-guid — repeat :instantiate on the same bundle reuses the parsed table instead of re-decoding the JSON. Cleared when the template is written — by :setTemplate or straight to the bundle's entity_template — so authoring-time edits land on the next instantiate.

Parameters

• self any (optional)

local t = bundleRef:getTemplate()

modules/BundleAssetTypeRef/getTemplateRaw

getTemplateRaw(self): string?

Read the raw entity_template file (JSON) as a string. Use :getTemplate() for a parsed table.

Parameters

• self any (optional)

local raw = bundleRef:getTemplateRaw()

modules/BundleAssetTypeRef/inspectDetail

inspectDetail(self): any

asset.inspect type-specific detail: { nodeCount, attachedComponents, rootName }, parsed from the bundle's own entity_template JSON — never instantiates the hierarchy. A bundle with no readable template returns an empty detail rather than erroring.

Parameters

• self any (optional)

local attached = asset.inspect(bundleRef).detail.attachedComponents

modules/BundleAssetTypeRef/instantiate

instantiate(self, target: EntityRef?, opts: { [string]: any }?): (EntityRef, { [string]: string })

Instantiate this bundle. The DEFAULT — bundle:instantiate() with no target entity — spawns ONE root entity carrying an Asset component that references this bundle: the component spawns the bundle's hierarchy as TEMPORARY runtime children (never written to the saved scene) and owns save / reload / diff, so the scene stays clean (one entity per instance, not the whole exploded permanent tree). This is the one-call path to put a bundle in the world.

Passing a target entityId (instantiate ONTO that entity, which becomes the bundle root) OR opts.raw = true (build a permanent fresh hierarchy) selects the RAW explode: it spawns every child in the entity_template, remaps cross-entity references, applies any saved sparse diff, and writes the bundleProvenance live-link attribute, returning the root entity id and the originalId → runtimeId map. The Asset component, Player avatars, and template tooling use this raw path.

Spawn mode is selected by opts.deferred. Default (deferred = false) uses the legacy batch() flush — every component is visible on the SAME tick so spawn-then-query patterns (tests, scene-load critical path, spawn-then-read flow) keep working. Pass opts.deferred = true for hundreds-to-thousands-of-entities bundles (large levels, density spawners, gibbed-prop debris bundles): the spawn+component work wraps in queue() and the engine drainer spreads it across multiple frames at the QUEUE_DRAIN_BUDGET_PER_FRAME cap. The root entity id is minted same-tick either way (entity.spawn always returns immediately), but in deferred mode children + components arrive in the ECS over the next few frames — don't read them back synchronously.

Parameters

• self any (optional)
• target EntityRef? (optional) — Optional target entity — an entity REF (proxy) to explode ONTO (that entity becomes the bundle root; this selects the RAW path). Omit for the default (fresh root + Asset component).
• opts { [string]: any }? (optional) — Optional { position, rotation, scale, name, temporary, raw, idMap, diff, sourceTag, deferred }. The base placement opts land on the returned root; raw = true forces the raw explode into a fresh permanent hierarchy (no Asset component); idMap reuses saved child ids (stable ids across reload); diff reapplies sparse child overrides keyed by template original_id; sourceTag labels the provenance record (defaults to "bundle"); deferred=true switches the spawn pump from same-tick batch() to cross-frame queue() — required for thousand-entity bundles to avoid one huge frame stall; temporary=true spawns every child born temporary (the Asset component's re-created scaffolding — kept out of the saved scene so a reload doesn't respawn them alongside a re-instantiate). idMap / diff / deferred / temporary apply to the raw path only.

local root = bundleRef:instantiate()                          -- scene-clean instance (Asset component); root is an EntityRef
local root, map = bundleRef:instantiate(entity.spawn("mount"))     -- raw, ONTO an entity ref
local root, map = bundleRef:instantiate(nil, { raw = true })  -- raw permanent fresh hierarchy

modules/BundleAssetTypeRef/listChildren

listChildren(self, rootsOnly: boolean?): { string }

List the names of every entity captured in THIS bundle instance's entity_template. Pass rootsOnly = true to restrict to entities with no parent_id. Best-effort: empty list when the template can't parse.

Parameters

• self any (optional)
• rootsOnly boolean? (optional) — When true, only entities with no parent_id are returned.

for _, name in ipairs(bundleRef:listChildren()) do print(name) end

modules/BundleAssetTypeRef/listContents

listContents(self): { { name: string, isDirectory: boolean } }

List the entries directly under the bundle root folder (meshes, textures, materials, sub-bundles) for tooling (inspectors, dependency graphs).

Parameters

• self any (optional)

for _, e in ipairs(bundleRef:listContents()) do print(e.name) end

modules/BundleAssetTypeRef/meshBindings

meshBindings(self): { any }

List each renderable node's mesh→material binding from THIS bundle's entity_template — the static data a spawned Model / SkinnedModel resolves — WITHOUT instantiating anything. Answers "which material does this mesh bind" as a direct read, with no spawn / settle / tree-walk / despawn cycle. Each entry is { node, nodeId, component, mesh, material }, where mesh and material are ref descriptors { guid, identity, name, path } (nil when the component omits that field). One entry per renderable component, in template order. Best-effort: empty list when the template can't parse.

Parameters

• self any (optional)

for _, b in ipairs(bundleRef:meshBindings()) do print(b.node, b.material and b.material.name) end

modules/BundleAssetTypeRef/onChange

onChange(ref: any, change: { [string]: any })

React to a write inside a .bundle/ instance: an entity_template change means the assembled model changed — regenerate the bundle's preview.png, its persisted visual description (syncs, publishes, feeds search and browser thumbnails), and record the component set + humanoid classification into .metadata for search facets. Originator-only; both artifacts sync to peers as ordinary content.

Parameters

• ref any (optional) — The AssetRef for the changed container.
• change { [string]: any } — { path, asset, type, kind, origin }.

modules/BundleAssetTypeRef/onCreate

onCreate(name: string, opts: CreateOpts?): { [string]: string }

Generic-creation hook for asset.create("bundle", name, opts). With opts.entity, composes that LIVE entity's hierarchy into the new bundle's entity_template in the same call — one step, capturing live component state (serialized component snapshots) + transforms of the root and every non-temporary descendant. With no opts, the bundle starts from the template skeleton's entity_template.

Parameters

• name string
• opts CreateOpts? (optional)

asset.create("bundle", "tree_prefab", { entity = rootRef })

modules/BundleAssetTypeRef/reindexSearchMeta

reindexSearchMeta(self): ()

Re-derive this bundle's search .metadata (component set + humanoid classification) from its current entity_template, without touching the preview. onChange calls it on every template edit; the search-metadata backfill calls it per bundle to populate assets minted before the deriver existed. Reads the template fresh — the parsed cache is only invalidated by setTemplate.

Parameters

• self any (optional)

bundleRef:reindexSearchMeta()

modules/BundleAssetTypeRef/setTemplate

setTemplate(self, template: { any }): boolean

Overwrite the bundle's entity_template with a Lua table, JSON-encoded. The VFS write triggers the engine's asset hot-reload pipeline, so every component subscribed to this bundle's guid (via a declared asset field) reconciles automatically. Returns true on success.

Parameters

• self any (optional)
• template { any } — The full entity-template table (array of records) to write.

bundleRef:setTemplate(bundleRef:getTemplate())

modules/BundleAssetTypeRef/update

update(self, entityId: string): boolean

Re-compose THIS bundle from entityId's current hierarchy and write the new template back to the bundle's on-disk path. Walks the whole hierarchy under entityId (recursive), capturing live component state + transforms of every non-temporary descendant. The VFS write fires the engine's asset hot-reload pipeline, so every component subscribed to this bundle's guid reconciles automatically.

Parameters

• self any (optional)
• entityId string — The entity whose live hierarchy is captured into the bundle.

bundleRef:update(playerId)   -- "save" the live edits back into the bundle

modules/BundleUpdate/README

require("@builtin::modules.bundle_update") -- BundleUpdate (also available as global 'bundle')

Adds bundle.update to the existing bundle namespace. Pure Luau — thin ergonomic wrapper around bundle.compose. The prelude grafts this onto the engine's bundle table at boot.

bundle.update(entityId, bundleRef?) re-composes the bundle from the entity's current hierarchy state, writing the new template into the bundle's existing on-disk path. The reconcile is fully engine-driven: the VFS write fires the generic asset hot-reload pipeline, which dispatches onAssetReload(field) on every component instance whose declared asset field references the bundle's guid. Components decide what reload means for them (Asset.component → despawn + re-instantiate template; user components → whatever they implement in onAssetReload). With one arg, the bundle ref is inferred from entity(entityId).component.get("Asset").source. With two args the explicit ref wins. There is no opt-in subscription surface — declaring an asset field IS the subscription.

Usage: local BundleUpdate = require("@builtin::modules.bundle_update") Also available as global: bundle

modules/BundleUpdate/installInto

installInto(bundle: BundleNamespace)

Install update onto the supplied bundle-shaped namespace. The prelude calls this once at boot with the engine's bundle global; users reach the result as bundle.update.

Parameters

• bundle BundleNamespace — The target namespace table. No-op when given a non-table value.

require("@builtin::modules.bundle_update").installInto(bundle)

modules/BundleUpdate/update

update(entityId: string, bundleRef: BundleRef?): any

Re-compose a bundle from an entity's current hierarchy and write it back to the bundle's on-disk path. The VFS write triggers the engine's generic asset hot-reload pipeline, which fires onAssetReload(field) on every component subscribed to this bundle's guid via a declared asset field — those components reconcile per their own policy.

Parameters

• entityId string — The entity whose hierarchy is captured into the bundle.
• bundleRef BundleRef? (optional) — Optional. When omitted, the ref is inferred from the entity's Asset.source field. When given, the explicit ref wins.

bundle.update(entityId)                     -- infer from Asset
bundle.update(entityId, { guid = "..." })   -- explicit ref

modules/CanvasAppLayout/README

require("@builtin::_templates.canvas_app.canvas_app_layout") -- CanvasAppLayout

Node-graph canvas built from the raw CSS-parity widget tree — absolutely positioned node cards over an SVG bezier connector; click a node to select it.

Usage: local CanvasAppLayout = require("@builtin::_templates.canvas_app.canvas_app_layout")

modules/CarriedReferences/README

require("@builtin::modules.api.engine.carried.references") -- CarriedReferences

Usage: local CarriedReferences = require("@builtin::modules.api.engine.carried.references")

modules/CarriedReferences/close

close(value: any, site: string, prefix: string): any

value (decoded component data) with every asset-reference envelope in it, at any depth, naming what the closure at site means by it: the guid the reference resolves to there (the session guid of the carried copy, or the engine library asset), or, while the mount answers nothing for it, the reference spelled in the mount (@carried.<key>::<reference>). A field holding that spelling waits on the mount and applies once the mount holds the asset. A component reference (componentType beside __ref) stays as written.

Parameters

• value any (optional) — The data to read.
• site string — The site M.site answers for the asset holding value.
• prefix string — The prefix M.site answers for that asset.

local data = references.close(comp.data, site, prefix)

modules/CarriedReferences/records

records(template: { any }, path: string?, identity: string?): { any }

The records of an entity template as the asset holding them composes them. For an asset of a carried mount, a copy whose records' component data names every asset reference within the closure (close); for an asset of the open world, template itself.

Parameters

• template { any } — The template's records ({ { components = { { type, data } } } }).
• path string? (optional) — The VFS path of the asset holding the template.
• identity string? (optional) — Optional identity of the same asset.

local records = references.records(bundleRef:getTemplate(), bundleRef.path, bundleRef.identity)

modules/CarriedReferences/site

site(path: string?, identity: string?): (string?, string?)

Where an asset of a carried mount stands: the site a reference it holds is read at, and the prefix its mount spells content with.

Parameters

• path string? (optional) — The asset's VFS path.
• identity string? (optional) — Optional identity of the same asset, read when path names no mount (@carried.<key>::<name>).

local site, prefix = references.site(ref.path, ref.identity)

modules/ComponentAssetTypeRef/README

require("@builtin::assetTypes.component.behavior") -- ComponentAssetTypeRef

Per-instance methods exposed on every AssetRef<component>. Loaded lazily by assetType.shared.ref.

Usage: local ComponentAssetTypeRef = require("@builtin::assetTypes.component.behavior")

modules/ComponentAssetTypeRef/attachTo

attachTo(self, entityId: string, fields: { [string]: any }?): any

Attach this component to an entity, equivalent to entity(entityId).component.add(compRef, fields). The ref names the component by its identity, so a component whose leaf name another package's component shares attaches as itself.

Parameters

• self any (optional)
• entityId string — Target entity ID.
• fields { [string]: any }? (optional) — Optional public field overrides.

compRef:attachTo(playerId, { speed = 5 })

modules/ComponentAssetTypeRef/getAssetFields

getAssetFields(self): any

The component type's asset-field declarations — a map of field name to asset category (e.g. { material = "material" }), or nil when the component declares no Field.assetRef fields.

Parameters

• self any (optional)

for field, cat in pairs(compRef:getAssetFields() or {}) do end

modules/ComponentAssetTypeRef/getInfo

getInfo(self): any

Metadata for the component type: { name, builtin, executionOrder, hooks }, where hooks is a { <hookName> = true } map scanned from the source.

Parameters

• self any (optional)

local info = compRef:getInfo() print(info.executionOrder)

modules/ComponentAssetTypeRef/getInitScript

getInitScript(self): string?

Read the component's entry script (init.luau / init.lua) as raw text.

Parameters

• self any (optional)

local src = compRef:getInitScript()

modules/ComponentAssetTypeRef/getReadme

getReadme(self): string?

Read the component's README.md body.

Parameters

• self any (optional)

print(compRef:getReadme())

modules/ComponentAssetTypeRef/getSource

getSource(self): string?

The component type's registered source text — the live definition in the runtime registry. getInitScript reads the on-disk entry file; this reads what the engine actually registered (and resolves builtin components by identity).

Parameters

• self any (optional)

local src = compRef:getSource()

modules/ComponentAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { fields, privateFields, methods, events, hooks, assetFields, executionOrder }, parsed from the component's own entry script (getInitScript) via luau_introspect. Cached on the asset's content checksum, so re-inspecting unchanged source is free. A component with no readable entry script returns an empty detail rather than erroring.

Parameters

• self any (optional)

local events = asset.inspect(compRef).detail.events

modules/ComponentAssetTypeRef/isRegistered

isRegistered(self): boolean

Whether the component type is registered with the ECS, so that component.add(name) takes it. The source is stored the moment the asset is written; the type registers when that registration drains, on a later frame, and this reads the registration rather than the source.

Parameters

• self any (optional)

while not compRef:isRegistered() do task.wait() end

modules/ComponentAssetTypeRef/listInstances

listInstances(self): { string }

List every entity in the live scene that currently has a component of this type. Useful for inspector tooling.

Parameters

• self any (optional)

for _, id in ipairs(compRef:listInstances()) do print(id) end

modules/ComponentAssetTypeRef/listPublicFields

listPublicFields(self): { string }

Best-effort list of the component's public field names by parsing the entry script. Recognises public.<name> = ... assignments at module scope; doesn't expand metatable declarations. Comments and string literals are not read. Use as a discovery hint, not a strict schema.

Parameters

• self any (optional)

for _, f in ipairs(compRef:listPublicFields()) do print(f) end

modules/ComponentAssetTypeRef/onChange

onChange(ref, change)

Asset-type change callback: (re)register + hot-reload this component type whenever its .component is seeded (a world seed) or its entry script (init.luau / init.lua) is edited. This is what registers and live-reloads USER components — library components register through the VFS write hook (author-immutable content does not dispatch onChange). Mirrors the .material / .shader assetTypes owning their own registration. Convergent

• idempotent: registration never writes back into the asset folder, and the underlying registry upsert is a no-op when the source is unchanged.

Parameters

• ref any (optional)
• change any (optional)

modules/ComponentAssetTypeRef/onDelete

onDelete(ref)

Asset-type delete callback: unregister this component type when its .component folder is removed. The teardown counterpart of onChange's registration — the type owns both halves of its runtime lifecycle, the way the .material / .shader types do. __components.unregister drops every type the folder registered, under each name it answers to (a nested component's full identity and its bare leaf), from the runtime registry, the FFI type-info / schema mirrors, and the /registered/components/ projection; instances already attached to live entities keep running (their closures are already bound).

Parameters

• ref any (optional)

modules/ComponentAssetTypeRef/onRegister

onRegister(self)

Initial-registration callback: register this component's type from its entry script the moment the instance first registers. Fired by the world-ready onRegister sweep BEFORE the world entrypoint (and its scene load) runs, so component.add-by-name resolves for entities the same load materialized. Idempotent: the registry upsert is a no-op when the source is unchanged, and a later onChange re-registration converges on the same definition.

Parameters

• self any (optional)

modules/ComponentAssetTypeRef/settingsSchemaProblem

settingsSchemaProblem(schema: { [string]: any }, ref: any): string?

The component type's verdict on a component's settings schema: a field named for one of the names the engine reserves on every component (__components.reservedFields) is refused, because the engine refuses to add a component whose public table declares one to an entity. Called by the settings module on every schema it reads for a component.

Parameters

• schema { [string]: any } — The Field schema the component's public table declares.
• ref any (optional) — The component's asset ref.

modules/ComputeShaderAssetTypeRef/README

require("@builtin::assetTypes.computeShader.behavior") -- ComputeShaderAssetTypeRef

Per-instance methods exposed on every AssetRef<computeShader>. Loaded lazily by assetType.shared.ref.

Usage: local ComputeShaderAssetTypeRef = require("@builtin::assetTypes.computeShader.behavior")

modules/ComputeShaderAssetTypeRef/buffer

buffer(self, name: string): any?

The buffer this shader last made under name. Two systems driving one shader over the same data reach for this rather than each creating their own; a system that wants its own calls createBuffer again.

Parameters

• self any (optional)
• name string — The name the buffer was created under.

local params = shaderRef:buffer("params") or shaderRef:createBuffer("params", { type = "vec4", len = 3 })

modules/ComputeShaderAssetTypeRef/compile

compile(self)

Compile this shader now, rather than on its first dispatch. Idempotent. NORMALLY UNNECESSARY — a dispatch compiles on first use. Reach for this only to avoid the one-frame first-dispatch warm-up in a latency-critical spot.

Parameters

• self any (optional)

shaderRef:compile()

modules/ComputeShaderAssetTypeRef/compileByName

compileByName(ref: string): boolean

Compile a compute shader by reference from its .computeShader VFS source — the lazy compile-on-first-use entry. A system that must guarantee the shader is registered before its first dispatch calls this (via compute.compileByName) to bring it online through the same generic compileCompute path an edit runs. Resolution goes through the universal asset system — a reference that doesn't resolve is a bad reference in the content that owns it, not something to special-case here.

Parameters

• ref string — A compute-shader asset reference (identity / guid) resolvable by asset.resolve.

require("@builtin::assetTypes.assetType.shared.ref").loadTypeModule("computeShader").compileByName("@builtin::shaders.compute_double")

modules/ComputeShaderAssetTypeRef/copyBufferToTexture

copyBufferToTexture(self, source: any, name: string, width: number, height: number, format: string?): TextureHandle

Copy one of this shader's buffers into a cached GPU texture, staying on the GPU — the path for an image a compute pass produced.

Parameters

• self any (optional)
• source any (optional) — The buffer holding tightly-packed rows in the format's texel layout.
• name string — Texture name, unique within this shader.
• width number — Texture width in texels.
• height number — Texture height in texels.
• format string? (optional) — Texel format: "rgba16f" (default), "rgba32f", "rgba8".

local tex = shaderRef:copyBufferToTexture(packed, "foam", 256, 256, "rgba16f")

modules/ComputeShaderAssetTypeRef/createBuffer

createBuffer(self, name: string, opts: { [string]: any }): any

Create a GPU buffer this compute shader owns. It is a substrate buffer — the same one every other part of the engine deals in — filed under this shader's guid, name, and a serial, so two callers asking this shader for a params each get their own. Pass the handle to any shader's dispatch, including another shader's, to bind it there. The shader remembers what it made: shaderRef:buffer(name) returns the last buffer created under that name, which is how two callers share one instead.

Parameters

• self any (optional)
• name string — What this buffer is for, e.g. "params" or "verts".
• opts { [string]: any } — { type, len, usage? } — type is the element ("f32", "vec3", "vec4", "quat", "mat4"), len is how many of them, and usage adds what the buffer is used for beyond the storage it always has: "readback" to read it on the CPU, "vertex" to draw it as geometry, "index" to draw it as an index run, "indirect" for a draw to read its arguments out of. A buffer can carry several.

There is no integer element: a buffer is a block of 32-bit words, so a binding the shader declares as u32 or atomic<u32> in bindings.yaml is created as "f32" here and written with buf:writeU32. The element type sets the STRIDE; what the words mean is the shader's to say.

local verts = shaderRef:createBuffer("verts", { type = "vec3", len = 1024, usage = { "readback" } })
verts:write(packed)  -- an array of numbers, or a `buffer` already holding the words
local values = verts:read():result()
local counts = shaderRef:createBuffer("counts", { type = "f32", len = 64 })  -- bindings.yaml: element: u32
counts:writeU32({ 0, 0, 0, 0 })
local geo = shaderRef:createBuffer("geo", { type = "vec3", len = 4096, usage = { "vertex", "readback" } })
local args = shaderRef:createBuffer("args", { type = "f32", len = 5, usage = { "indirect" } })  -- DrawIndexedIndirectArgs

modules/ComputeShaderAssetTypeRef/createSampler

createSampler(self, name: string, opts: { [string]: any }?): TextureHandle

Create a sampler owned by this compute shader, for its texture bindings.

Parameters

• self any (optional)
• name string — Sampler name, unique within this shader.
• opts { [string]: any }? (optional) — Sampler options — filtering and addressing.

local smp = shaderRef:createSampler("linear", { filter = true, clamp = true })

modules/ComputeShaderAssetTypeRef/createStorageTexture2D

createStorageTexture2D(self, name: string, opts: { [string]: any }): TextureHandle

Create a write-only 2D storage texture owned by this compute shader — the target a raymarch or image pass writes.

Parameters

• self any (optional)
• name string — Texture name, unique within this shader.
• opts { [string]: any } — { width, height, format? }.

local out = shaderRef:createStorageTexture2D("out", { width = 1920, height = 1080, format = "rgba16f" })

modules/ComputeShaderAssetTypeRef/createTexture3D

createTexture3D(self, name: string, opts: { [string]: any }): TextureHandle

Create a 3D texture owned by this compute shader — a density volume, an occupancy grid, a signed-distance field. Keyed by the shader's guid plus name, so it cannot collide with another asset's.

Parameters

• self any (optional)
• name string — Texture name, unique within this shader.
• opts { [string]: any } — { width, height, depth, format?, storage? }.

local density = shaderRef:createTexture3D("density", { width = 64, height = 64, depth = 64, format = "r16f", storage = true })

modules/ComputeShaderAssetTypeRef/createTextureHistory

createTextureHistory(self, name: string, opts: { [string]: any }): TextureHandle

Create a temporal history pair owned by this compute shader — the previous frame's result to read while writing this frame's.

Parameters

• self any (optional)
• name string — History name, unique within this shader.
• opts { [string]: any } — { width, height, format? }.

local history = shaderRef:createTextureHistory("taa", { width = 1920, height = 1080, format = "rgba16f" })

modules/ComputeShaderAssetTypeRef/destroy

destroy(self): boolean

Destroy this texture or sampler and free its GPU memory.

Parameters

• self any (optional)

modules/ComputeShaderAssetTypeRef/dispatch

dispatch(self, opts: { [string]: any }): boolean

Dispatch this compute shader with named buffers bound to its declared storage bindings, in order. Compiles on first use. A zero in any workgroup dimension is refused and recorded as a dispatch failure, so a count derived from how much data there is passes through math.max(1, ...) first.

Parameters

• self any (optional)
• opts { [string]: any } — { buffers, workgroups } — buffers names one compute buffer per declared storage binding; workgroups is { x, y, z }, { x }, or x.

shaderRef:dispatch({ buffers = { "positions" }, workgroups = { 64 } })

modules/ComputeShaderAssetTypeRef/dispatchEx

dispatchEx(self, opts: { [string]: any }): boolean

Dispatch this compute shader with explicit texture / storage-texture / sampler resources, one per declared binding in order. A params: block's uniform is engine-owned and takes no entry here. A zero in any workgroup dimension is refused and recorded as a dispatch failure, so a count derived from how much data there is passes through math.max(1, ...) first.

A resource's kind says what it is, in the words bindings.yaml uses: buffer (name is a buffer handle), texture3d / storage3d (a 3D texture handle), storage2d (a 2D storage texture handle), texture2d (a copyBufferToTexture handle or a texture asset's guid), sampler (a sampler handle), history_prev / history_curr (one side of a history pair) and scene_depth (the frame's scene depth, no name). A slot takes the kind it is declared with; a texture2d slot also reads a storage2d, a history side or scene_depth, and a storage2d slot also writes history_curr. The engine spellings texture_3d, texture_2d and storage_2d name the same resources. Any other kind is refused, naming the accepted ones.

Parameters

• self any (optional)
• opts { [string]: any } — { resources, workgroups }: each resource is { kind, name }.

shaderRef:dispatchEx({ resources = { { kind = "storage2d", name = target } }, workgroups = { 8, 8 } })
shaderRef:dispatchEx({ resources = { { kind = "storage3d", name = density }, { kind = "buffer", name = params } }, workgroups = { 8, 8, 8 } })

modules/ComputeShaderAssetTypeRef/dispatchOnVertices

dispatchOnVertices(self, opts: { [string]: any }): boolean

Dispatch this compute shader with a model's vertex buffer bound at the first storage binding, and opts.buffers filling the rest. Use to mutate vertex positions directly. A zero in any workgroup dimension is refused and recorded as a dispatch failure, so a count derived from how many vertices there are passes through math.max(1, ...) first.

Parameters

• self any (optional)
• opts { [string]: any } — { model, buffers?, workgroups } — model is the mesh guid whose vertices the shader writes.

shaderRef:dispatchOnVertices({ model = meshHandle.guid, workgroups = { 64 } })

modules/ComputeShaderAssetTypeRef/getBindings

getBindings(self): { [string]: any }

List this compute shader's declared bindings + params (parsed from bindings.yaml). Returns { bindings = { {name, kind, access?, element?, format?}, ... }, params = { {name, type, default}, ... } }. This is the editor-discovery surface, and the SAME parse the compile uses. Raises, naming the file, when bindings.yaml is text the YAML decoder refuses (with the line) or bindings: / params: holds anything but a list of mappings (with the key).

Parameters

• self any (optional)

for _, b in ipairs(computeRef:getBindings().bindings) do print(b.name, b.kind) end

modules/ComputeShaderAssetTypeRef/getSource

getSource(self): string?

Read the compute WGSL body (shader.wgsl) as raw text.

Parameters

• self any (optional)

local src = computeRef:getSource()

modules/ComputeShaderAssetTypeRef/onChange

onChange(ref, change)

Asset-type change callback: (re)compile the compute shader whenever its WGSL body or bindings.yaml is written. This is the ONLY thing that compiles a .computeShader — so it fires on the initial create (the template write) AND on every later edit, with no world reload. Convergent: see compileCompute.

Parameters

• ref any (optional)
• change any (optional)

modules/ComputeShaderAssetTypeRef/onDelete

onDelete(ref)

Asset-type delete callback: release the program a removed .computeShader folder registered. The teardown counterpart of onChange's compile, so the type owns both halves of its runtime lifecycle the way .material does: the program, the params uniform it carried and the dispatch history under its key go with the asset, and a shader authored afresh at the same path registers a new program rather than inheriting the one the removed asset left.

Parameters

• ref any (optional)

modules/ComputeShaderAssetTypeRef/program

program(self): any

This shader's kernel ABI as a program: program:variant(spec) lowers and compiles one specialization, and variant:run(env) allocates the outputs bindings.yaml declares (count, capacity, append with a live counter), binds and dispatches. See modules.compute_abi.

Parameters

• self any (optional)

local variant = shaderRef:program():variant({ specialize = { T = "vec3<f32>" } })
local run = variant:run({ n = 64, inputs = { src = srcBuffer } })

modules/ComputeShaderAssetTypeRef/read

read(self): Readback

Start a GPU→CPU read-back of this 3D texture's voxels. The read takes frames to arrive — ask the returned Readback whether it is :ready(), then drain it.

Parameters

• self any (optional)

local pending = density:read()
if pending:ready() then local voxels = pending:result() end

modules/ComputeShaderAssetTypeRef/setParam

setParam(self, prop: string, value: number): boolean

Set one scalar parameter declared in this shader's bindings.yaml params: block. The next dispatch sees the new value; a value set before the shader's first compile is the value it starts with.

Parameters

• self any (optional)
• prop string — Parameter name as declared in bindings.yaml.
• value number — New scalar value.

shaderRef:setParam("scale", 4.0)

modules/ComputeShaderAssetTypeRef/setSource

setSource(self, src: string): boolean

Overwrite the compute WGSL body on disk. Hot-reload recompiles the shader on the next frame. Returns true on success.

Parameters

• self any (optional)
• src string — New WGSL source (only @compute fn main + helpers).

computeRef:setSource(myWgsl)

modules/ComputeShaderAssetTypeRef/status

status(self): { { [string]: any } }

What the engine did with this shader's dispatches, one record per target. A dispatch is recorded into a command encoder frames after the call that asked for it returned, so this is where its outcome lands: ok is the most recent outcome, dispatches counts what reached the encoder, failures how many of those could not be recorded, and lastError says why the last failure failed (kept after a recovery). target is the mesh guid for a dispatchOnVertices, empty for a dispatch that writes only its bound buffers. This answers "is this pass running?" — an empty result means nothing has dispatched this shader.

Parameters

• self any (optional)

for _, d in ipairs(shaderRef:status()) do print(d.target, d.ok, d.lastError) end

modules/ComputeShaderAssetTypeRef/write

write(self, data: buffer | string | { number }): boolean

Upload voxels into this 3D texture: a buffer or a binary string carrying the texture's byte layout verbatim, or one number per channel in the texture's format.

Parameters

• self any (optional)
• data buffer | string | { number } — Voxel bytes, or voxel values in texel order.

modules/ComputeShaderAssetTypeRef/writeFloats

writeFloats(self, floats: { number }, formatOrOpts: (string | { [string]: any })?): boolean

Upload float voxels into this 3D texture, converting to the texture's format.

Parameters

• self any (optional)
• floats { number } — Voxel values in texel order.
• formatOrOpts (string | { [string]: any })? (optional) — Source format name, or an options table.

modules/ContentVersion/README

require("@builtin::modules.content_version") -- ContentVersion

Per-path content-version counters — a cheap, synchronous "has this file changed?" token that lets an assetType behavior memoize a parse in its ref's runtime and serve repeated reads as a pure table lookup instead of re-reading + re-parsing the file every call.

A source write bumps the written path's counter. A memoized reader keyed by the value get(path) returned when it parsed can then check, on every later call, whether the counter still matches — an integer compare, no vfs.read, no parse. It rebuilds only when the counter moved. Two write surfaces feed it, so the token reflects a change no matter where it came from:

• vfs.write / vfs.move bump SYNCHRONOUSLY, in the same call, so a script that writes a file and reads it back in the SAME tick sees the new content immediately (the asset-change onChange dispatch fires a frame LATER, too late for a same-tick read).
• the generic asset-change dispatcher bumps on every source write it routes, including peer-synced and engine-originated writes that never pass through the Luau vfs.* surface — with the engine's normalized path, which is the canonical form a reader keys on. A typed asset's FOLDER path carries a counter too: the dispatcher bumps it after it has routed a write inside the asset and the asset's type has reacted to it, so a reader of "anything in this asset" keys on one number. Counters are per PATH (not one global epoch): the per-frame dirty-entity writer churns scene-dirty paths every frame during play, and a global epoch would let that churn invalidate every unrelated cache. Per-path isolation means only a change to THE file a reader depends on rebuilds it. The counters are held once for the process (__contentVersion): a write made in a worker VM, the engine thread's dispatch of it, and a write made on the engine thread advance the same number, and every VM reads it. A counter lives as long as its path, or as long as a reader has read it. Removing a path (vfs.remove, a move off it, a folder removal reaching it, a peer's removal, the shell's rm) moves the counter of a path some reader has read, so that reader rebuilds: inside the removing call for vfs.remove and vfs.move, and on the frame the engine delivers the removal for a peer's or the shell's. The counter of a path no reader read goes with the path, and a write back starts it from 0. The store therefore holds one small integer per path that exists or that a reader read, which keeps it the size of the content rather than of every path a session ever wrote.

Usage: local ContentVersion = require("@builtin::modules.content_version")

modules/ContentVersion/bump

bump(path: string)

Bump path's version counter, invalidating every reader memoized against its previous value. Called by the vfs.* write surface and the asset-change dispatcher; content code rarely calls it directly.

Parameters

• path string — VFS path whose content changed.

require("@builtin::modules.content_version").bump(p)

modules/ContentVersion/get

get(path: string): number

The current version counter for path (0 if no VM ever wrote it). A memoized reader stores the value it saw when it parsed, and treats a later call as a cache hit exactly while get(path) still returns it.

Parameters

• path string — Normalized VFS path.

local v = require("@builtin::modules.content_version").get(p)

modules/DataAssetTypeRef/README

require("@builtin::assetTypes.data.behavior") -- DataAssetTypeRef

Per-instance methods on every AssetRef<data> — a configured value instance of a dataType contract. Instances carry values only; structure and behavior live on the contract.

Usage: local DataAssetTypeRef = require("@builtin::assetTypes.data.behavior")

modules/DataAssetTypeRef/contract

contract(self)

The dataType contract this instance is bound to.

Parameters

• self any (optional)

local weaponType = smg:contract()

modules/DataAssetTypeRef/data

data(self, wanted: string?)

Resolve this instance into a read-only typed value object: this instance's values.yaml with the contract's schema defaults applied, ref fields materialized (assetRef -> AssetRef, dataRef -> nested value object), and the bound contract chain's behavior methods reachable on it — the bound contract's own methods win over an ancestor's when both define the same name, and any explicit instance value wins over both. Errors loudly when the instance violates its contract, when wanted is given and the bound contract's chain doesn't include it, and when dataRef fields form a circular chain.

Parameters

• self any (optional)
• wanted string? (optional) — Optional contract the caller requires — an assertion, not a filter: the returned object still carries the FULL bound schema and method chain.

local w = smg:data("tdWeapon"); print(w.damage, w:effectiveRating())

modules/DataAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { contract, valueKeys }, parsed from this instance's own values.yaml — the bound contract identity plus the sorted top-level keys of its values map. Never resolves the contract or materializes ref fields (that's :data()).

Parameters

• self any (optional)

local valueKeys = asset.inspect(dataRef).detail.valueKeys

modules/DataAssetTypeRef/onCreate

onCreate(name: string, opts: { contract: string })

Create a data instance bound to a contract. Seeds values.yaml with the contract's declared defaults so a fresh instance is immediately valid wherever every required field has a default.

Parameters

• name string
• opts { contract: string }

modules/DataAssetTypeRef/satisfies

satisfies(self, wanted: string): (boolean, string?)

Whether this instance's contract chain includes wanted — true for the bound contract itself and for any contract it extends.

Parameters

• self any (optional)
• wanted string — Contract identity (bare leaf or full identity).

if smg:satisfies("weapon") then ... end

modules/DataAssetTypeRef/satisfiesDetail

satisfiesDetail(self, wanted: string): { ok: boolean, code: string, reason: string? }

Chain-membership check that also reports WHY, as a stable code a caller can branch on without matching reason text.

Parameters

• self any (optional)
• wanted string — Contract identity (bare leaf or full identity).

local d = smg:satisfiesDetail("weapon")
if not d.ok and d.code ~= "contract-mismatch" then warn(d.reason) end

modules/DataAssetTypeRef/setValues

setValues(self, patch: { [string]: any })

Change this instance's values: patch replaces the named top-level fields. The result is checked against the bound contract, and it is refused — one error naming each violation, nothing written — when it introduces a violation, or leaves one standing at or under a value the change set. A list item is known by what it holds rather than where it sits, so removing or reordering items sets none of the rest. A violation the file already held anywhere else stays listed without stopping the change, so an instance that does not yet satisfy its contract is filled in one field at a time and a value beside an undeclared key stays editable. A written result goes to values.yaml (re-encoded, so comments in the file are not kept), recorded into the open undo operation when there is one.

Parameters

• self any (optional)
• patch { [string]: any } — Top-level field -> new value, in the forms values.yaml holds.

ref:setValues({ clipmap = { baseTile = 100, levels = 5 } })

modules/DataAssetTypeRef/validateInstance

validateInstance(self): (boolean, { DS.Violation })

Validate this instance's values against its contract's merged schema (missing required fields, constraint breaches, unknown fields, ref-field existence + contract compatibility).

Parameters

• self any (optional)

local ok, v = smg:validate()

modules/DataSchema/README

require("@builtin::modules.data_schema") -- DataSchema

Schema engine for the typed-data system. A contract's schema.yaml declares fields + constraints; this module parses the decoded declaration, merges extends chains, applies defaults, validates value tables, and maps a contract onto Field descriptors so a data instance's values edit through typed controls: values convert between the file's forms and the controls', and an edit lands on the stored values leaf by leaf. No VFS reads — callers decode the YAML themselves and inject asset/contract resolvers; converting a reference resolves it.

Usage: local DataSchema = require("@builtin::modules.data_schema")

modules/DataSchema/applyDefaults

applyDefaults(merged: { [string]: FieldSpec }, values: { [string]: any }): { [string]: any }

Produce a NEW value table with every schema default filled in where values has no explicit entry — recursively: struct values gain their subfield defaults and array elements gain their item defaults, at every depth. Neither input is mutated.

Parameters

• merged { [string]: FieldSpec } — Merged field map from mergeChain.
• values { [string]: any } — The instance's raw value table.

local filled = DataSchema.applyDefaults(merged, rawValues)

modules/DataSchema/editedValues

editedValues(merged: { [string]: FieldSpec }, stored: { [string]: any }, edited: { [string]: any }, base: string?): { [string]: any }

The top-level values a control edit writes: for each field edited names, the value stored holds with only the leaves the edit changed replaced, each in the form the file held it in. Every value the edit leaves alone keeps its stored value and form — a colour held as numbers (above 1 included), a map-form vector, and keys the contract does not declare.

Parameters

• merged { [string]: FieldSpec } — The merged field map.
• stored { [string]: any } — The values as the data file holds them.
• edited { [string]: any } — Control-form values for the fields the edit names.
• base string? (optional) — The data file's VFS path, which a ~ reference expands against.

local patch = DataSchema.editedValues(schema, stored, controlPatch, ref.path)

modules/DataSchema/fromFieldValues

fromFieldValues(merged: { [string]: FieldSpec }, values: { [string]: any }): { [string]: any }

Values from the Field controls in the forms the data file holds: the inverse of toFieldValues.

Parameters

• merged { [string]: FieldSpec } — The merged field map.
• values { [string]: any } — The control-form values (any subset of fields).

local stored = DataSchema.fromFieldValues(schema, patch)

modules/DataSchema/mergeChain

mergeChain(chain: { Schema? }): ({ [string]: FieldSpec }?, { string })

Merge an extends chain of parsed schemas into one field map. The chain is ordered ROOT PARENT FIRST, derived contract LAST. A child redeclaring a parent field is a problem — shared shape comes from the parent, per-child shape from new fields.

Parameters

• chain { Schema? } — Array of Schema, root parent first. A nil hole (e.g. a failed parseSchema result passed straight in) is a problem entry.

local merged, problems = DataSchema.mergeChain({ itemSchema, weaponSchema })

modules/DataSchema/parseSchema

parseSchema(raw: any): (Schema?, { string })

Parse a decoded schema.yaml table into a Schema. Returns (schema, problems) — schema is nil when any problem was found. fields may be written as a map (name -> spec) or as a sequence of specs each carrying its own name:; both key the resulting fields by name.

Parameters

• raw any (optional) — The decoded document ({ extends?, fields }).

local Yaml = require("@builtin::modules.yaml")
local schema, problems = DataSchema.parseSchema(Yaml.decode(bytes))

modules/DataSchema/toFieldValues

toFieldValues(merged: { [string]: FieldSpec }, values: { [string]: any }, base: string?): { [string]: any }

A data instance's values in the forms the Field controls read: colours as { r, g, b, a }, vectors as { x, y, z }, references as { __ref = guid }, number enum members as strings.

Parameters

• merged { [string]: FieldSpec } — The merged field map.
• values { [string]: any } — The values as the data file holds them.
• base string? (optional) — The data file's VFS path, which a ~ reference expands against.

local shown = DataSchema.toFieldValues(schema, values, ref.path)

modules/DataSchema/toFields

toFields(merged: { [string]: FieldSpec }): { [string]: any }

One Field descriptor per contract field, so a data instance's values edit through the same typed controls as asset settings: a number with both bounds is a range, a string or number with enum an enum (a number enum's members shown as strings), and every other type its Field kind.

Parameters

• merged { [string]: FieldSpec } — The merged field map (dataTypeRef:schema()).

local fields = DataSchema.toFields(contract:schema())

modules/DataSchema/validateValues

validateValues(

Validate a raw value table against a merged field map. Checks missing required fields (a field with a default is never missing), per-field constraints, unknown top-level fields, and ref fields via the injected resolvers.

local violations = DataSchema.validateValues(merged, rawValues, resolvers)

modules/DataTypeAssetTypeRef/README

require("@builtin::assetTypes.dataType.behavior") -- DataTypeAssetTypeRef

Per-instance methods exposed on every AssetRef<dataType> — the contract surface of the typed-data system: schema (extends chain merged), validation, defaults, chain navigation, instance listing.

Usage: local DataTypeAssetTypeRef = require("@builtin::assetTypes.dataType.behavior")

modules/DataTypeAssetTypeRef/chain

chain(self)

The full extends chain as refs, root parent first, this contract last.

Parameters

• self any (optional)

for _, link in ipairs(t:chain()) do print(link.identity) end

modules/DataTypeAssetTypeRef/defaults

defaults(self)

The default value table the merged schema declares.

Parameters

• self any (optional)

local d = weaponType:defaults()

modules/DataTypeAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { fields, extends }, the contract's OWN declared field schema (not the merged extends chain) — fields is { {name, type, required}, ... } sorted by name, parsed from this contract's own schema.yaml. extends is the parent contract identity, or nil for a root contract.

Parameters

• self any (optional)

local fields = asset.inspect(dataTypeRef).detail.fields

modules/DataTypeAssetTypeRef/instances

instances(self)

Every data instance bound to this contract (or to a contract that extends it). Scans the whole data-asset registry — a discovery surface for authoring and tooling, not a per-frame call. A broken instance (unreadable values.yaml, dangling contract binding) warns and is skipped, so one bad instance never aborts enumeration of the rest.

Parameters

• self any (optional)

for _, ref in ipairs(weaponType:instances()) do print(ref.identity) end

modules/DataTypeAssetTypeRef/parent

parent(self)

The parent contract ref (extends), or nil for a root contract.

Parameters

• self any (optional)

local base = rangedType:parent()

modules/DataTypeAssetTypeRef/schema

schema(self)

The contract's merged field schema — its own fields plus every field inherited through the extends chain.

Parameters

• self any (optional)

local schema = weaponType:schema()

modules/DataTypeAssetTypeRef/validateValues

validateValues(self, values: { [string]: any })

Validate a value table against this contract's merged schema.

Parameters

• self any (optional)
• values { [string]: any }

local ok, v = weaponType:validate({ damage = 12 })

modules/Debris/README

require("@builtin::modules.debris") -- Debris

Timed entity despawn — Roblox Debris:AddItem(instance, lifetime) analog. Wraps the internal __debris.* FFI with a typed Luau surface. Installed as the global debris via the prelude.

Collapses the common task.delay + entity.despawn pattern into one call. Use for transient entities — bullet tracers, hit FX, dropped pickups, tween-completion cleanups, ragdoll cleanup. Semantics (match Roblox):

• debris.add(id, lifetime) queues a despawn after lifetime seconds. Default lifetime is 10 seconds.
• Calling add twice on the same entity REPLACES the prior deadline.
• If the entity is despawned through any other path the pending record is dropped silently — no error.
• Pending entries survive world.save / world.load (saved lifetime is seconds-remaining, so timers resume from where they paused).

Usage: local Debris = require("@builtin::modules.debris")

modules/Debris/add

add(id: any, lifetime: number?): DebrisHandle

Schedule the entity for despawn after lifetime seconds (default 10). Calling again on the same entity replaces the prior deadline. Negative or zero lifetime despawns immediately. Returns a handle for cancel(), or 0 if the entity id couldn't be resolved.

Parameters

• id any (optional) — Entity id, name, or proxy table.
• lifetime number? (optional) — Seconds before despawn — defaults to 10 when nil.

local bullet = entity.spawn("Bullet"); debris.add(bullet.id, 2.0)
local h = debris.add(target.id, 5); debris.cancel(h)

modules/Debris/cancel

cancel(handleOrId: any): boolean

Cancel a pending despawn. Accepts either a handle from debris.add or an entity id / proxy. Returns true if a pending record was actually removed.

Parameters

• handleOrId any (optional) — Cancel handle, or entity id / name / proxy.

debris.cancel(handle); debris.cancel(target.id)

modules/Debris/clear

clear(): boolean

Drop every pending entry. Used by the test suite to isolate cases — not part of the user-facing surface.

modules/Debris/count

count(): number

Number of currently pending debris entries — handy for diagnostics overlays.

print(debris.count(), "pending despawns")

modules/Debris/list

list(): { DebrisEntry }

Snapshot every pending entry as a flat array of {id, remainingSecs, handle} records. Order is not stable — don't rely on it.

for _, e in debris.list() do print(e.id, e.remainingSecs) end

modules/Debris/pending

pending(id: any): number?

Return the number of seconds remaining before the entity is despawned, or nil if it isn't scheduled.

Parameters

• id any (optional) — Entity id, name, or proxy.

local s = debris.pending(bullet.id); if s then print("dies in", s) end

modules/DepthProbe/README

require("@builtin::tests.fixtures.depth_probe") -- DepthProbe

The reader half of the depth probe — the two depth grids depth_probe_feature.renderFeature writes each frame, one at afterDepthPrepass and one at afterOpaque. A suite requires this module and enables the feature; the feature records the targets it writes here, so both halves address the same targets.

Usage: local DepthProbe = require("@builtin::tests.fixtures.depth_probe")

modules/DepthProbe/read

read(): ({ number }?, { number }?)

Read both grids: the nearest depth of each tile at afterDepthPrepass and at afterOpaque, row by row.

local seam, final = probe.read()

modules/DisplayCurve/README

require("@builtin::tests.fixtures.display_curve") -- DisplayCurve

The chain's display transform in Luau, for the suites that predict what a light value arrives at the frame as: the Khronos PBR Neutral tone curve __display__ applies at its default (curve = 3), the sRGB encode over it, and the two composed. The port is of zero_display_neutral in post_process_renderer.rs — the same formula read on a light triple rather than on a fragment, since the curve mixes channels by their shared peak and a single channel cannot be converted on its own.

Usage: local DisplayCurve = require("@builtin::tests.fixtures.display_curve")

modules/DisplayCurve/neutralCurve

neutralCurve(rgb: { number }): { number }

The Khronos PBR Neutral tone curve on a light triple, as __display__ applies it at curve = 3.

Parameters

• rgb { number } — Linear light, one entry per channel.

local curved = DisplayCurve.neutralCurve({ 1.0, 0.5, 0.25 })

modules/DisplayCurve/shownRGB

shownRGB(rgb: { number }): { number }

The code values the delivered frame shows for a light triple: the Neutral curve, then the sRGB encode, on each channel. The curve mixes channels by their shared peak, so one channel's code value depends on the other two — which is why this takes the whole triple. The engine applies the display exposure before the curve, so this answers for exposure = 1; a case running at another exposure scales the triple by it first.

Parameters

• rgb { number } — Linear light, one entry per channel. A negative channel reads 0.

local shown = DisplayCurve.shownRGB({ 0.8, 0.8, 0.8 })

modules/DisplayCurve/srgbDecode

srgbDecode(code: number): number

The inverse of srgbEncode: a 0-255 code value back to the channel's share of peak light before the transfer function encoded it. Exact for a frame held at curve = 0, where __display__ only clamps to [0, 1] and encodes — a case reading such a frame at an exposure other than 1 divides that back out afterward to recover the light the scene carried.

Parameters

• code number — The code value, on a 0-255 scale.

local peak = DisplayCurve.srgbDecode(128)

modules/DisplayCurve/srgbEncode

srgbEncode(v: number): number

One channel of a display's peak light as the 0-255 code value that shows it, IEC 61966-2-1.

Parameters

• v number — The channel's share of peak light; clamped to [0, 1].

local code = DisplayCurve.srgbEncode(0.5)

modules/DockedAppLayout/README

require("@builtin::_templates.docked_app.docked_app_layout") -- DockedAppLayout

Docked-shell UI template — a top toolbar, a scrolling body, and a bottom status bar built as a raw CSS-parity widget tree. Clone-and-edit starting point for editor-style tool apps.

Usage: local DockedAppLayout = require("@builtin::_templates.docked_app.docked_app_layout")

modules/DotBot/README

require("@builtin::plugins.dotbot.surface") -- DotBot

DotBot's Luau surface: the agents a person has connected, the conversations they hold, and the turns they run.

Usage: local DotBot = require("@builtin::plugins.dotbot.surface")

modules/DotBotRun/README

require("@builtin::modules.api.editor.dotbotRun") -- DotBotRun

A DotBot run driven from outside the panel: a boot that names a prompt (--agent dotbot --agent-prompt <text>, or start_instance { prompt }) hands it to DotBot as the first message of a fresh conversation, or a boot that names --agent-resume sends its message into the conversation this world's run already holds. The run is recorded the way an agent CLI records its own: the conversation in this machine's agent-session store under (world, dock slot), and every prompt and turn event in its transcript (agentSessions.record), which agent_run_report reads.

Usage: local DotBotRun = require("@builtin::modules.api.editor.dotbotRun")

modules/DotBotRun/start

start(opts: { [string]: any }): { [string]: any }

Start a DotBot run over this engine's DotBot plugin, in the background: the prompt as the first message of a fresh conversation, or a resume message into the conversation this machine recorded for the world and slot. The outcome and every turn are recorded in the run's transcript and reported as the agent's state in the engine status. One run per engine; a second call starts nothing and answers whether the first was started.

Parameters

• opts { [string]: any } — { agent, worldGuid, slot?, prompt?, resume?, model?, effort?, account?, seeded?, asPanel? }: agent is dotbot (DotBot on its Claude account) or dotbot-<provider>; account names the connected account of that provider the run is put on (its agent such as dotbot-claude~2, its account key, its panel name or its email; an account the host provides also by the host's id for it); seeded waits for the Claude accounts the host hands this engine to reach DotBot before the account is chosen; asPanel, in place of agent and account, runs on the agent a person's own message in the DotBot panel starts a conversation on.

modules/DotBotRun/startArmed

startArmed(): boolean

Start the DotBot run this engine's boot armed, from the boot's own settings (--agent, --agent-prompt or --agent-resume, --agent-model, --agent-effort, --agent-account, the bound world). Does nothing on a boot that armed no DotBot run, or once this engine has started one.

modules/DotBotRun/watchHanded

watchHanded(): boolean

Serve the prompts the page hosting this engine hands the editor's agent (origozero.ai's /create idea, posted as agent_prompt on the worker channel): each is sent as the first message of the world's DotBot conversation, once the DotBot plugin has loaded, and the page is told whether it was sent or why not. Started once per engine; a later call starts nothing.

modules/DotBotTranscript/README

require("@builtin::plugins.dotbot.transcript") -- DotBotTranscript

The DotBot panel's transcript: a conversation's rows as the widget tree one tab draws, rebuilt row by row. A row whose content has not changed since the last draw is the same subtree it was, its callbacks carried over, so a delta streaming into the last answer rebuilds that answer and nothing above it. The newest rows are drawn and the rest wait behind a "Show earlier messages" row, so what a redraw costs is set by how much is on screen rather than by how long the conversation is.

Usage: local DotBotTranscript = require("@builtin::plugins.dotbot.transcript")

modules/DotBotTranscript/folded

folded(key: string, runs: { any }, conversation: string?): boolean

Whether key's section is folded to its heading for runs, the agents of conversation: as the person set it for that conversation since its agents last started or all ended, else open while an agent works and folded once every agent has ended.

Parameters

• key string
• runs { any }
• conversation string? (optional)

modules/DotBotTranscript/new

new(deps: { [string]: any })

Build a transcript.

Parameters

• deps { [string]: any } — { source, icons, expanded, onToggle, pageSize? }: source reads a tool answer (traceOf, toolsRunIn); icons holds the down, right, alert and bot paths; expanded is the open/closed table, keyed by row key, that the panel keeps; onToggle() runs after a row is opened or closed; pageSize overrides M.PAGE.

modules/DotBotTranscript/newAgents

newAgents(deps: { [string]: any })

Build the agent cards one tab draws above its composer.

Parameters

• deps { [string]: any } — The same { source, icons, expanded, onToggle } a transcript takes (icons.term marks a tool call, icons.stop the Stop button), plus onOpen(run, key) (a card's chevron or name) and onStop(run, key) (its Stop), each handed the run and the key of the section it was pressed in; pageSize overrides M.AGENT_PAGE.

modules/DotBotTranscript/render

render(tabId: string, messages: { any }, opts: { [string]: any }?): any

messages as the scroll area tabId draws.

Parameters

• tabId string
• messages { any }
• opts { [string]: any }? (optional) — { conversation?, now? }: the conversation the rows belong to (a new one starts again at one page), and the clock a thinking row's seconds are read against (os.clock() when absent).

modules/DotBotTranscript/setFolded

setFolded(key: string, runs: { any }, conversation: string?, folded: boolean)

Fold (true) or open key's section for conversation's agents runs, as a press on its heading does: it holds until the conversation's agents next start or all end.

Parameters

• key string
• runs { any }
• conversation string? (optional)
• folded boolean

modules/DotBotTranscript/showEarlier

showEarlier(tabId: string)

Draw one page more of the earlier rows on tabId's next render.

Parameters

• tabId string

modules/DotBotTranscript/stats

stats(tabId: string): any

What tabId's last render did: { rows, drawn, built, kept, hidden }. rows is every row the conversation has, drawn the rows on screen, built the rows whose nodes were made by that render, kept the rows that carried the nodes they already had, and hidden the rows behind "Show earlier messages".

Parameters

• tabId string

modules/DotBotWorkflows/README

require("@builtin::plugins.dotbot.workflows") -- DotBotWorkflows

The DotBot panel's Workflows view: every workflow run in the engine as a card (its name, state, who started it, how long it has run, its phase and how many of its requests are answered), and one run opened: its phases with each request (its state, the agent that holds it and for how long, the claims that ran out, its error, and its answer once opened), its log, and Cancel while it runs. A card or a request row whose content has not changed since the last draw is the same subtree it was, its callbacks carried over, so a change to one request builds that row and nothing else.

Usage: local DotBotWorkflows = require("@builtin::plugins.dotbot.workflows")

modules/DotBotWorkflows/detail

detail(key: string, run: any, opts: { [string]: any }?): { any }

One run opened: its header (name, state, who started it, how long it has run, its progress, why it ended, and Cancel while it runs), each phase with its requests, and its log. opts.nowSec is the wall clock times are read against.

Parameters

• key string
• run any (optional)
• opts { [string]: any }? (optional)

modules/DotBotWorkflows/list

list(key: string, opts: { [string]: any }?): any

Every workflow run in the engine, newest first, one card each; a press on a card opens the run. opts.nowSec is the wall clock times are read against.

Parameters

• key string
• opts { [string]: any }? (optional)

modules/DotBotWorkflows/new

new(deps: { [string]: any })

Build a Workflows view.

Parameters

• deps { [string]: any } — { source, icons, onToggle?, onOpenAgent?, onConversation? }: source is the panel's source (workflows, workflow, workflowPhases, workflowRevision, workflowAgent, workflowConversation, cancelWorkflow, conversations, subagents, splitAddress); icons holds the right, down, stop and term paths; onToggle() runs after something in the view opened, closed or was asked of a run; onOpenAgent(agentRun, key) opens an agent a turn started; and onConversation(address, key) opens a conversation, each from view key.

modules/DotBotWorkflows/open

open(key: string): string?

The run opened in view key, by id, or nil while the list shows.

Parameters

• key string

modules/DotBotWorkflows/setOpen

setOpen(key: string, runId: string?)

Open run runId in view key, or go back to the list with nil.

Parameters

• key string
• runId string? (optional)

modules/DotBotWorkflows/stats

stats(key: string): any

What the last draw of key did: { runs | requests, built, kept }.

Parameters

• key string

modules/DynamicAssetTypeRef/README

require("@builtin::assetTypes.dynamicAsset.behavior") -- DynamicAssetTypeRef

Behaviour for the dynamicAsset asset type — a prompt-driven, self-regenerating 3D asset. Reference example for the asset-type onChange change-callback. Loaded lazily by @builtin::assetTypes.assetType.shared.ref.

Usage: local DynamicAssetTypeRef = require("@builtin::assetTypes.dynamicAsset.behavior")

modules/DynamicAssetTypeRef/onChange

onChange(ref, change)

Regenerate this dynamic asset when its own prompt.json is written with a prompt other than the one already generated. A write anywhere else in the instance is ignored, and a prompt arriving while a generation is in flight is held for the poll loop to pick up when that one settles.

Parameters

• ref any (optional) — The changed .dynamicAsset's reference.
• change any (optional) — The change record the asset dispatcher raised for the write.

modules/EcsAudioListenerSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsAudioListener") -- EcsAudioListenerSpec

Usage: local EcsAudioListenerSpec = require("@builtin::modules.api.engine.ecs.components.EcsAudioListener")

modules/EcsAudioSourceSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsAudioSource") -- EcsAudioSourceSpec

Usage: local EcsAudioSourceSpec = require("@builtin::modules.api.engine.ecs.components.EcsAudioSource")

modules/EcsCameraSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsCamera") -- EcsCameraSpec

Usage: local EcsCameraSpec = require("@builtin::modules.api.engine.ecs.components.EcsCamera")

modules/EcsColliderSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsCollider") -- EcsColliderSpec

Usage: local EcsColliderSpec = require("@builtin::modules.api.engine.ecs.components.EcsCollider")

modules/EcsCollisionGroupsSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsCollisionGroups") -- EcsCollisionGroupsSpec

Usage: local EcsCollisionGroupsSpec = require("@builtin::modules.api.engine.ecs.components.EcsCollisionGroups")

modules/EcsComponentSpecs/README

require("@builtin::modules.api.engine.ecs.components") -- EcsComponentSpecs

Usage: local EcsComponentSpecs = require("@builtin::modules.api.engine.ecs.components")

modules/EcsFluidForcesSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsFluidForces") -- EcsFluidForcesSpec

Usage: local EcsFluidForcesSpec = require("@builtin::modules.api.engine.ecs.components.EcsFluidForces")

modules/EcsForceSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsForce") -- EcsForceSpec

Usage: local EcsForceSpec = require("@builtin::modules.api.engine.ecs.components.EcsForce")

modules/EcsGravityFieldSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsGravityField") -- EcsGravityFieldSpec

Usage: local EcsGravityFieldSpec = require("@builtin::modules.api.engine.ecs.components.EcsGravityField")

modules/EcsHandle/README

require("@builtin::modules.api.engine.ecs.handle") -- EcsHandle

Usage: local EcsHandle = require("@builtin::modules.api.engine.ecs.handle")

modules/EcsHandles/README

require("@builtin::modules.api.engine.ecs.handles") -- EcsHandles

Usage: local EcsHandles = require("@builtin::modules.api.engine.ecs.handles")

modules/EcsHandles/handleFields

handleFields(typeName: string): { { rust: string, category: string } }?

The fields of a native component that hold a GPU handle.

Parameters

• typeName string — The component's public name under ecs.

local fields = handles.handleFields("Mesh")

modules/EcsHandles/insertAll

insertAll(specs: { { id: string, type: string, data: any } }, site: string?): { { type: string, ids: { string }, message: string } }

Insert saved native components, one insertMany per distinct entry.

Parameters

• specs { { id: string, type: string, data: any } } — A list of { id, type, data }: the entity, the public component name and the saved row. Entities stating the same type and data share one insert.
• site string? (optional) — Optional path or identity of the asset the rows were read from. A site inside a carried mount resolves each guid within that mount's closure.

local failed = handles.insertAll({ { id = id, type = "Mesh", data = { mesh = guid } } })

modules/EcsHandles/value

value(entry: any, site: string?): any

The component value a saved ecs entry states: its handle fields resolved from asset guids to the handles the component holds.

Parameters

• entry any (optional) — { type, data }, type the public name under ecs and data the saved row.
• site string? (optional) — Optional path or identity of the asset the entry was read from. A site inside a carried mount resolves each guid within that mount's closure (asset.tryResolve(guid, category, site)).

ecs.insert(id, handles.value({ type = "Mesh", data = { mesh = guid } }))

modules/EcsLiftSurfaceSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsLiftSurface") -- EcsLiftSurfaceSpec

Usage: local EcsLiftSurfaceSpec = require("@builtin::modules.api.engine.ecs.components.EcsLiftSurface")

modules/EcsLightSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsLight") -- EcsLightSpec

Usage: local EcsLightSpec = require("@builtin::modules.api.engine.ecs.components.EcsLight")

modules/EcsMaterialSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsMaterial") -- EcsMaterialSpec

Usage: local EcsMaterialSpec = require("@builtin::modules.api.engine.ecs.components.EcsMaterial")

modules/EcsMeshSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsMesh") -- EcsMeshSpec

Usage: local EcsMeshSpec = require("@builtin::modules.api.engine.ecs.components.EcsMesh")

modules/EcsMorphWeightsSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsMorphWeights") -- EcsMorphWeightsSpec

Usage: local EcsMorphWeightsSpec = require("@builtin::modules.api.engine.ecs.components.EcsMorphWeights")

modules/EcsPhysicsJointSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsPhysicsJoint") -- EcsPhysicsJointSpec

Usage: local EcsPhysicsJointSpec = require("@builtin::modules.api.engine.ecs.components.EcsPhysicsJoint")

modules/EcsPhysicsSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsPhysics") -- EcsPhysicsSpec

Usage: local EcsPhysicsSpec = require("@builtin::modules.api.engine.ecs.components.EcsPhysics")

modules/EcsPlan/README

require("@builtin::modules.api.engine.ecs.plan") -- EcsPlan

Usage: local EcsPlan = require("@builtin::modules.api.engine.ecs.plan")

modules/EcsPlaneHoldSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsPlaneHold") -- EcsPlaneHoldSpec

Usage: local EcsPlaneHoldSpec = require("@builtin::modules.api.engine.ecs.components.EcsPlaneHold")

modules/EcsPlayerOwnedSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsPlayerOwned") -- EcsPlayerOwnedSpec

Usage: local EcsPlayerOwnedSpec = require("@builtin::modules.api.engine.ecs.components.EcsPlayerOwned")

modules/EcsRetargetProfileSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsRetargetProfile") -- EcsRetargetProfileSpec

Usage: local EcsRetargetProfileSpec = require("@builtin::modules.api.engine.ecs.components.EcsRetargetProfile")

modules/EcsShaderDataSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsShaderData") -- EcsShaderDataSpec

Usage: local EcsShaderDataSpec = require("@builtin::modules.api.engine.ecs.components.EcsShaderData")

modules/EcsShaftNetworkSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsShaftNetwork") -- EcsShaftNetworkSpec

Usage: local EcsShaftNetworkSpec = require("@builtin::modules.api.engine.ecs.components.EcsShaftNetwork")

modules/EcsSkeletonSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsSkeleton") -- EcsSkeletonSpec

Usage: local EcsSkeletonSpec = require("@builtin::modules.api.engine.ecs.components.EcsSkeleton")

modules/EcsSkySpec/README

require("@builtin::modules.api.engine.ecs.components.EcsSky") -- EcsSkySpec

Usage: local EcsSkySpec = require("@builtin::modules.api.engine.ecs.components.EcsSky")

modules/EcsSoftBodySpec/README

require("@builtin::modules.api.engine.ecs.components.EcsSoftBody") -- EcsSoftBodySpec

Usage: local EcsSoftBodySpec = require("@builtin::modules.api.engine.ecs.components.EcsSoftBody")

modules/EcsTessellationSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsTessellation") -- EcsTessellationSpec

Usage: local EcsTessellationSpec = require("@builtin::modules.api.engine.ecs.components.EcsTessellation")

modules/EcsTransformConstraintsSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsTransformConstraints") -- EcsTransformConstraintsSpec

Usage: local EcsTransformConstraintsSpec = require("@builtin::modules.api.engine.ecs.components.EcsTransformConstraints")

modules/EcsTransformSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsTransform") -- EcsTransformSpec

Usage: local EcsTransformSpec = require("@builtin::modules.api.engine.ecs.components.EcsTransform")

modules/EcsVisibilityRangeSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsVisibilityRange") -- EcsVisibilityRangeSpec

Usage: local EcsVisibilityRangeSpec = require("@builtin::modules.api.engine.ecs.components.EcsVisibilityRange")

modules/EcsWatch/README

require("@builtin::modules.api.engine.ecs.watch") -- EcsWatch

Usage: local EcsWatch = require("@builtin::modules.api.engine.ecs.watch")

modules/EcsWatch/entities

entities(ids: { string }, ...: any): Watch

A watch over the named entities, whatever they hold, and over the entities holding any of the given component terms. changed() also reports a named entity that moved.

Parameters

• ids { string } — The ids of the entities watched for movement.
• args any (optional)

modules/EcsWatch/new

new(...: any): Watch

A watch over the entities holding any of the given component terms.

Parameters

• args any (optional)

modules/EcsWheelColliderSpec/README

require("@builtin::modules.api.engine.ecs.components.EcsWheelCollider") -- EcsWheelColliderSpec

Usage: local EcsWheelColliderSpec = require("@builtin::modules.api.engine.ecs.components.EcsWheelCollider")

modules/EditorLayoutAssetTypeRef/README

require("@builtin::editor.edui.editorLayout.behavior") -- EditorLayoutAssetTypeRef

Per-instance methods + the onRegister / onChange lifecycle hooks for every AssetRef<editorLayout>. Loaded lazily by asset_ref.module.

Usage: local EditorLayoutAssetTypeRef = require("@builtin::editor.edui.editorLayout.behavior")

modules/EditorLayoutAssetTypeRef/loadRecordMethod

loadRecordMethod(self): any?

Read this instance's layout record: its name, title, description, slot, mode, panels with regions, fractions, origin, and the captured arrangement when it holds one.

Parameters

• self any (optional)

local rec = layoutRef:loadRecord()

modules/EditorPanelAssetTypeRef/README

require("@builtin::editor.edui.editorPanel.behavior") -- EditorPanelAssetTypeRef

Per-instance methods + the onRegister lifecycle hooks for every AssetRef<editorPanel>. Loaded lazily by asset_ref.module.

Usage: local EditorPanelAssetTypeRef = require("@builtin::editor.edui.editorPanel.behavior")

modules/EditorPanelAssetTypeRef/getInitScript

getInitScript(self): string?

Read the instance's init.luau source as raw text (inspectors).

Parameters

• self any (optional)

modules/EditorPanelAssetTypeRef/loadSpecMethod

loadSpecMethod(self): any

Read this instance's panel spec (the table its init.luau returns).

Parameters

• self any (optional)

local spec = panelRef:loadSpec()

modules/EditorPanelAssetTypeRef/onChange

onChange(self, change)

Parameters

• self any (optional)
• change any (optional)

modules/EditorPanelAssetTypeRef/onDelete

onDelete(self)

Parameters

• self any (optional)

modules/EditorPanelAssetTypeRef/onRegister

onRegister(self)

Parameters

• self any (optional)

modules/EditorPanelAssetTypeRef/panelIds

panelIds(self): { string }

The panel ids this file registers, one per spec it returns, in order: a spec's own id, else the instance name, suffixed by position for the later specs of a multi-tab file. Answered from the instance's last registration, which every write to it repeats, so reading it runs nothing; an instance never registered (a runtime profile) loads its spec to answer. Raises the load error when init.luau does not return a spec.

Parameters

• self any (optional)

for _, id in ipairs(panelRef:panelIds()) do print(id) end

modules/EffectAssetTypeBehavior/README

require("@builtin::systems.effects.effect.behavior") -- EffectAssetTypeBehavior

Per-instance methods and lifecycle hooks of the effect asset type. An effect's effect.yaml names what it plays: each entry under plays is one graph or a stack of graphs played together, called by its name. play plays an entry where the caller asks, with its inputs, and answers a handle that drives it; entries lists what can be played and the inputs each takes.

Usage: local EffectAssetTypeBehavior = require("@builtin::systems.effects.effect.behavior")

modules/EffectAssetTypeBehavior/entries

entries(self): (any, string?)

What this effect plays: each entry's name, the graphs it plays together and the inputs it takes, and the entry played when none is named.

Parameters

• self any (optional)

for name, e in effectRef:entries().entries do print(name, #e.graphs) end

modules/EffectAssetTypeBehavior/entry

entry(self, name: string?, cooperative: boolean?): (any, string?)

One of this effect's entries: the graphs it plays together, each with the inputs it declares.

Parameters

• self any (optional)
• name string? (optional) — The entry's name, as effect.yaml lists it under plays; nil for the default.
• cooperative boolean? (optional) — True from a task: describing the effect hands the frame back between its graphs.

local burst = effectRef:entry("burst")

modules/EffectAssetTypeBehavior/instantiate

instantiate(self, target: any?, opts: { [string]: any }?): (any, { [string]: string })

Place this effect in the scene: an entity with an Effect component that plays one of its entries there, the way a drop into the viewport or an Asset field places it.

Parameters

• self any (optional)
• target any? (optional) — Optional owning entity ref; the effect's entity spawns under it.
• opts { [string]: any }? (optional) — The base placement opts (position, rotation, scale, name, temporary), plus entry (the entry it plays; the effect's default when omitted) and inputs (values for the entry's inputs by name).

local root = effectRef:instantiate(nil, { position = { 0, 1, 0 }, entry = "flare" })

modules/EffectAssetTypeBehavior/isDescribed

isDescribed(self): boolean

Whether the effect's entries are described already, so that entry answers without reading its graphs.

Parameters

• self any (optional)

if effectRef:isDescribed() then bind() end

modules/EffectAssetTypeBehavior/newGraph

newGraph(self, name: string, opts: { part: boolean? }?): any

Make a new graph inside this effect: under graphs/ for one it plays, under parts/ for one its graphs use as a node.

Parameters

• self any (optional)
• name string — The graph's name.
• opts { part: boolean? }? (optional) — { part? }: true makes it under parts/.

local core = beacons:newGraph("flareCore")
local crack = beacons:newGraph("crack", { part = true })

modules/EffectAssetTypeBehavior/onCreate

onCreate(name: string, opts: CreateOpts?): { [string]: string }

Scaffold a new effect playing one entry: effect.yaml with that entry as its default, the graph it plays under graphs/ by the same name, and a README to describe each. The entry is opts.entry, or the effect's own name when none is given.

Parameters

• name string — The effect's name.
• opts CreateOpts? (optional) — { entry? }: the name of the entry it starts with and of its graph.

asset.create("effect", "beacons", { entry = "flare" })

modules/EffectAssetTypeBehavior/onRegister

onRegister(self)

Initial-registration callback: describe the effect in a task of its own, a slice of each frame at a time, so the Effect that plays it finds its entries described when it binds them.

Parameters

• self any (optional)

modules/EffectAssetTypeBehavior/play

play(self, entryName: string?, opts: PlayOpts?): any

Play one of this effect's entries. Every graph the entry holds plays together from the same moment, each given the inputs it declares, under the entity root names, so the effect moves with it (a sword, a torch, a character's hand); with no root it stands in the world. A finished play is kept and played again by the next call for the same entry.

Parameters

• self any (optional)
• entryName string? (optional)
• opts PlayOpts? (optional) — { root?, offset?, rotation?, inputs?, ending?, speed?, keep? }. root: the entity it plays on (proxy or id). offset: where it stands, from root or, with no root, in the world. rotation: its rotation there (pitch/yaw/roll degrees, or a quaternion). inputs: values for the entry's inputs by name; each goes to every graph of the entry that declares it. ending: "graph" (what the timeline declares), "loop" or "hold". speed: 1 its own rate. keep: stay once finished instead of going.

local beacons = asset.resolve("beacons", "effect")
local shown = beacons:play("flare", { root = mast, offset = { 0, 0.9, 0 }, inputs = { size = 0.4 } })
shown:onFinished(function() print("done") end)

modules/EffectAssetTypeBehavior/playing:playback

playing:playback(): any

Where the play stands and what it has cost: the Effect's playback(), its combined cost and one entry per graph. Once the play has finished and gone back to the kept plays, the answer is what it stood at when it went.

modules/EffectAssetTypeBehavior/playing:set

playing:set(input: string, value: any)

Set one of the entry's inputs while it plays, on every graph that declares it.

Parameters

• input string
• value any (optional)

modules/EffectAssetTypeBehavior/preview

preview(self, opts: { [string]: any }?): { [string]: any }

Render this effect to a still: its default entry played on the preview stage (effects.stage) from its first frame, over the dark backdrop and framed on the effect's body, and the picture taken at the effect's still moment: the latest of the moments its graphs name with g:still (halfway through its range, or two seconds into a timeline with no end, for a graph that names none). A timeline with an end is moved to that moment; one with no end is played to it.

Parameters

• self any (optional)
• opts { [string]: any }? (optional) — { size? = { width, height }, angle? = { yaw, pitch }, backdrop?, fit? }, as preview.fromEntities takes them.

local shot = effectRef:preview({ size = { width = 256, height = 256 } })

modules/EffectAssetTypeBehavior/removeEntry

removeEntry(self, name: string)

Remove an entry and the comment lines directly above it. The default moves to the first entry left; the last entry cannot be removed.

Parameters

• self any (optional)
• name string — The entry's name.

beacons:removeEntry("flare")

modules/EffectAssetTypeBehavior/renameEntry

renameEntry(self, old: string, new: string)

Rename an entry; the default follows it.

Parameters

• self any (optional)
• old string — The entry's name now.
• new string — Its new name: letters, digits and _, starting with a letter.

beacons:renameEntry("glow", "flare")

modules/EffectAssetTypeBehavior/setDefault

setDefault(self, name: string)

Make an entry the one played when none is named.

Parameters

• self any (optional)
• name string — The entry's name.

beacons:setDefault("flare")

modules/EffectAssetTypeBehavior/setEntry

setEntry(self, name: string, graphs: { any })

Set what one entry plays: replaces the entry's graphs, or adds the entry after the others when the effect has none by that name. Other lines of effect.yaml, comments included, are kept.

Parameters

• self any (optional)
• name string — The entry's name: letters, digits and _, starting with a letter.
• graphs { any } — The graphs it plays together: procGraph refs, or names as effect.yaml states them (~.graphs.flash).

beacons:setEntry("flare", { asset.resolve("~.graphs.flareCore", "procGraph"), "~.graphs.flareTrail" })

modules/EffectAssetTypeBehavior/validate

validate(ref): { { code: string, message: string, severity: string? } }

The effect's own rules: effect.yaml plays graphs that resolve, its default is one of its entries, every graph under graphs/ is played by some entry, and each folder holds only the assets it is for.

Parameters

• ref any (optional)

modules/EffectAssetTypeBehavior/warm

warm(self, entryName: string?, count: number?, inputs: { [string]: any }?)

Keep plays of this effect's entries ready, built ahead of time, so a play takes one and shows its first frame at once. Plays are made one after another on the frames after the call, and one counts as ready once every graph of it is planned, cooked and has its first frame presented (entries() reports ready). A play made for inputs is ready for a play given the same inputs; one given others cooks for them as it starts. A finished play goes back on its first frame, prepared again for the inputs it last played with, while its entry has fewer than this count. An entry nothing sized keeps the effect's pool setting ready, made the first time that entry plays; call this at a level's load, or before a burst, with the number of plays of an entry that run at once.

Parameters

• self any (optional)
• entryName string? (optional)
• count number? (optional) — How many to keep ready; nil keeps the effect's pool setting. 0 keeps none.
• inputs { [string]: any }? (optional) — The values of the entry's inputs the plays are made for, as play takes them; nil makes them with the defaults.

beacons:warm()
beacons:warm("flare", 6)
beacons:warm("flare", 2, { size = 0.4 })

modules/EffectShared/README

require("@builtin::systems.effects.effect.shared") -- EffectShared

What the effect type and its Effect component share: which of an entry's graphs takes each input, and the plays the type handed out and keeps to play again. An entry is what effectRef:entry(name) answers.

Usage: local EffectShared = require("@builtin::systems.effects.effect.shared")

modules/EffectShared/add

add(path: string, entry: string, e: any, stillPreparing: boolean?)

Put a play made ahead of time among the kept plays of its entry: it waits disabled and out of the scene's hierarchy. A play still preparing counts as ready once prepared is called for it.

Parameters

• path string — The effect's VFS path.
• entry string — The entry's name.
• e any (optional) — The play's entity, carrying a bound Effect component.
• stillPreparing boolean? (optional) — Whether its graphs are still doing the work its first play needs.

modules/EffectShared/current

current(record: any): boolean

Whether record is still the play its entity is playing.

Parameters

• record any (optional)

modules/EffectShared/defaultSize

defaultSize(path: string): number

The pool size every entry of the effect at path keeps until warm() sizes it.

Parameters

• path string

modules/EffectShared/dropKept

dropKept(path: string)

Let go of every kept play of the effect at path: what it plays changed.

Parameters

• path string — The effect's VFS path.

modules/EffectShared/finished

finished(entityId: string)

Called by an Effect component when every graph of its entry has finished. A play the effect type handed out tells its listeners, and goes back to the kept plays unless it stays.

Parameters

• entityId string — The Effect component's entity.

modules/EffectShared/handOut

handOut(e: any, path: string, entry: string, stays: boolean): any

Hand a play out: who to tell when it finishes, and whether it stays where it is once finished instead of going back to the kept plays.

Parameters

• e any (optional) — The play's entity.
• path string — The effect's VFS path.
• entry string — The entry's name.
• stays boolean — Whether the play stays once finished.

modules/EffectShared/inputs

inputs(entry: any): { [string]: any }

The inputs an entry takes: every input any of its graphs declares.

Parameters

• entry any (optional) — An entry, as effectRef:entry(name) answers it.

modules/EffectShared/isPreparing

isPreparing(entityId: string): boolean

Whether the kept play entityId is still doing the work its first play needs.

Parameters

• entityId string — The play's entity.

modules/EffectShared/keep

keep(record: any)

Take a handed-out play back: pause it, take it out of the scene and keep it ready for the next play of its entry, or let it go when the entry already has as many plays, ready and playing, as its pool size.

Parameters

• record any (optional) — The play's record.

modules/EffectShared/onKept

onKept(fn: (any) -> ())

Name what is done with each play that goes back among the kept plays: it counts as preparing until prepared is called for it.

Parameters

• fn (any) -> () — Called with the play's entity.

modules/EffectShared/prepared

prepared(entityId: string)

A kept play's graphs are done with the work its first play needs.

Parameters

• entityId string — The play's entity.

modules/EffectShared/ready

ready(path: string, entry: string): number

How many kept plays of entry are ready now: built, and their graphs done with the work their first play needs.

Parameters

• path string
• entry string

modules/EffectShared/route

route(entry: any, inputs: { [string]: any }?): ({ { [string]: any } }?, string?)

Each graph's share of inputs: the values of the inputs it declares.

Parameters

• entry any (optional) — An entry, as effectRef:entry(name) answers it.
• inputs { [string]: any }? (optional) — Values by input name.

modules/EffectShared/setDefaultSize

setDefaultSize(path: string, count: number)

Set the pool size every entry of the effect at path keeps until warm() sizes it.

Parameters

• path string
• count number

modules/EffectShared/setSize

setSize(path: string, entry: string, count: number)

Set how many plays of entry of the effect at path are kept ready; ready plays past the count are let go.

Parameters

• path string — The effect's VFS path.
• entry string — The entry's name.
• count number — Whole number >= 0.

modules/EffectShared/size

size(path: string, entry: string): number

How many plays of entry are kept ready.

Parameters

• path string
• entry string

modules/EffectShared/sortedKeys

sortedKeys(t: { [string]: any }): { string }

The keys of t, sorted.

Parameters

• t { [string]: any }

modules/EffectShared/stopped

stopped(entityId: string): boolean

Called by an Effect component told to stop. A play the effect type handed out goes back to the kept plays.

Parameters

• entityId string — The Effect component's entity.

modules/EffectShared/take

take(path: string, entry: string): any?

A kept play of entry of the effect at path, or nil when none is kept.

Parameters

• path string — The effect's VFS path.
• entry string — The entry's name.

modules/EffectShared/total

total(path: string, entry: string): number

How many plays of entry there are: kept ones, ready or preparing, and ones playing now. The pool size counts both, so plays are built while fewer exist and a finished one always goes back while the pool is not over its size.

Parameters

• path string
• entry string

modules/Engine/README

require("@builtin::modules.api.engine.engine") -- Engine (also available as global 'engine')

Process-level engine state surface. Read-only boot profile and read-write engine mode. Both exposed as computed properties via metatable __index / __newindex — never call them as methods. Usage: if engine.profile == "editor" then ... end engine.mode = "play" engine.setMode("play", { strict = false }) Implemented as a thin Luau wrapper over internal FFI: engine.profile → __engineSettings.get("profile") engine.mode → __mode.get() / __mode.set(value) engine.setMode → __mode.set(value, strict) engine.paused → __pause.get() / __pause.set(value) engine.timeScale → __timescale.get() / __timescale.set(value) engine.timeScaleOwner → who the rate answers to (hold, or last writer) engine.gameplayReady → __gameplay.ready() engine.mode = X is load-bearing — the setter owns the mode-flip side effects so any path that changes mode behaves identically: edit → play: drain pending edit-mode marks into the dirty overlay (so wld.edit() can reassemble the user's authored state) BEFORE flipping __mode. Never writes canonical scene.json. play → edit: flip __mode first, then reload the active non-additive layer so the dirty overlay reapplies + play-mode runtime mutations are discarded. Toolbox wrappers (wld.play() / wld.edit()) are thin pass-throughs — they MUST NOT carry side-effect logic. If a future caller writes engine.mode = "play" directly (or via a different toolbox tool), the same side effects fire. Putting drain/reload on the toolbox alone would let a direct assignment leave the scene in a half-applied state. See man engine for the full surface and side effects.

Usage: local Engine = require("@builtin::modules.api.engine.engine") Also available as global: engine

modules/Engine/_fireWorldLoaded

_fireWorldLoaded(detail: string?)

INTERNAL. Mark the world fully loaded and fan out to every onWorldLoaded subscriber. Called by the builtin world-entrypoint loader once onWorldLoad has returned. Idempotent per load — re-fires on a genuine reload (mirrors a scene's onReady), so the flag is set true and subscribers run on each call.

Parameters

• detail string? (optional) — Optional JSON text the boot timeline's world_loaded mark carries as its detail: the loader's account of the frames the load ran across.

modules/Engine/_resetWorldLoaded

_resetWorldLoaded()

INTERNAL. Clear the world-loaded latch on unbind/unload so a subsequent bind re-fires onWorldLoaded for the new world.

modules/Engine/editWaiters

editWaiters(): { EditWaiter }

Everyone waiting for this engine to leave play so their edit-mode work can run, oldest first. Each entry is { key, id, name, reason, heldSeconds }: id is the waiting caller, the same value vfs.currentAuthor().id reads, and heldSeconds is how long it has been waiting. A session holding play reads this to see whose work it is holding. Empty in edit mode and whenever nobody has said they are waiting.

for _, who in ipairs(engine.editWaiters()) do
log.warn(("%s has waited %.0fs for edit mode"):format(who.name or who.key, who.heldSeconds))
end

modules/Engine/engineRecord

engineRecord(record: { [any]: any })

Declare record an engine record: a table a subsystem keeps as its own account of what the engine holds — the renderer's registry of live features, its capture views — and puts back through its own reset. engine.snapshotModuleState neither copies nor walks it, and engine.restoreModuleState leaves it as that reset left it, so a module restore never seats a record back around what the reset did: a feature a suite destroyed stays destroyed, and one it made again under its identity stays the one the renderer ticks.

Parameters

• record { [any]: any } — The table.

engine.engineRecord(activeFeatures)

modules/Engine/holdTimeScale

holdTimeScale(scale: number, options: TimeScaleHoldOptions?): () -> ()

Run the simulation at scale for as long as the hold stands, and return the release. engine.timeScale is one number for the whole process, so a rate one agent sets is the rate every other agent's entities and measurements run at; a hold records who set it and refuses a plain engine.timeScale write from anywhere else while it stands, so the rate cannot move under a measurement without the measurement hearing about it. Holds nest: the innermost names the rate, and the rate that stood before the outermost is back once the last release is called. Each release takes its own hold off the stack whatever order the releases come in. exclusive takes the rate for the owner key the call states: while that hold stands, a hold is admitted only when it states the same key, and every other one is refused with an error naming the key and the rate. That is what lets one caller pin the rate its run is measured at while another agent drives the same engine.

Parameters

• scale number — The rate to run at: 1 is real time, 0.5 half speed, 0 frozen, 2 double. Finite and >= 0.
• options TimeScaleHoldOptions? (optional) — owner is the key this hold is taken under, a non-empty string, and an exclusive hold states one. A hold that states no key takes the key of the agent the call is attributed to, or a minted hold#n when the call carries no agent identity, so every hold answers to a key engine.releaseTimeScale accepts and engine.timeScaleOwner reports as id. exclusive takes the rate for the stated key until the hold is released.

Returns () — A function that releases this hold. Calling it twice releases once.

local release = engine.holdTimeScale(0.08) ; task.wait(0.12) ; release()
local release = engine.holdTimeScale(1, { exclusive = true, owner = "duel-measurement" })

modules/Engine/markBaseline

markBaseline(): number

Read this module's own memory — the time-scale holds standing, who wrote the rate last, the rate that stood before any hold, the onTimeScaleChange subscribers and the highest watcher id each registry has handed out — and answer with a generation engine.resetToBaseline puts exactly that back from. Take it once, before the work whose changes are to be undone.

local mark = engine.markBaseline() -- then run, then engine.resetToBaseline(mark)

modules/Engine/markScriptingBaseline

markScriptingBaseline(): number

Record the scripting registries — world-event subscriptions, the four lifecycle-watcher lists, and the require cache — as they stand right now, as a mark engine.resetScriptingState() restores to. Marks stack: a reset names the generation it restores to, and the marks taken after that one go with it. Returns the new mark's generation, counting from 1. Mark once the engine is serving rather than while it boots: the registries keep growing as the prelude subscribes, the world entrypoint runs and the startup scene loads, so a mark taken partway through sits below the rest of that work and the first reset would remove it.

engine.markScriptingBaseline()
world.on("player_join", function() end)
engine.resetScriptingState() -- the subscription above is gone

modules/Engine/offDeviceRebuilt

offDeviceRebuilt(id: number): boolean

Remove an engine.onDeviceRebuilt subscriber by its watcher id. Returns true when a live watcher carried that id, false when it named none — already removed, or never registered.

Parameters

• id number — Watcher id returned by engine.onDeviceRebuilt.

local id = engine.onDeviceRebuilt(function() end)
engine.offDeviceRebuilt(id)

modules/Engine/offMemoryPressure

offMemoryPressure(id: number): boolean

Remove an engine.onMemoryPressure subscriber by its watcher id. Returns true when a live watcher carried that id, false when it named none: already removed, or never registered.

Parameters

• id number — Watcher id returned by engine.onMemoryPressure.

local id = engine.onMemoryPressure(function() end)
engine.offMemoryPressure(id)

modules/Engine/offModeChange

offModeChange(id: number): boolean

Remove an engine.onModeChange subscriber by its watcher id. Returns true when a live watcher carried that id, false when it named none — already removed, or never registered.

Parameters

• id number — Watcher id returned by engine.onModeChange.

local id = engine.onModeChange(function() end)
engine.offModeChange(id)

modules/Engine/offPauseChange

offPauseChange(id: number): boolean

Remove an engine.onPauseChange subscriber by its watcher id. Returns true when a live watcher carried that id, false when it named none.

Parameters

• id number — Watcher id returned by engine.onPauseChange.

modules/Engine/offTimeScaleChange

offTimeScaleChange(id: number): boolean

Remove an engine.onTimeScaleChange subscriber by its watcher id. Returns true when a live watcher carried that id, false when it named none.

Parameters

• id number — Watcher id returned by engine.onTimeScaleChange.

local id = engine.onTimeScaleChange(function() end)
engine.offTimeScaleChange(id)

modules/Engine/offWorldLoaded

offWorldLoaded(id: number): boolean

Remove an onWorldLoaded subscriber by its watcher id.

Parameters

• id number

modules/Engine/offWorldReady

offWorldReady(id: number): boolean

Remove an engine.onWorldReady subscriber by its watcher id. Returns true when a live watcher carried that id, false when it named none.

Parameters

• id number — Watcher id returned by engine.onWorldReady.

modules/Engine/offWorldUnloading

offWorldUnloading(id: number): boolean

Remove an engine.onWorldUnloading subscriber by its watcher id. Returns true when a live watcher carried that id, false when it named none.

Parameters

• id number — Watcher id returned by engine.onWorldUnloading.

modules/Engine/onDeviceRebuilt

onDeviceRebuilt(callback: (number) -> ()): number

Register a callback that fires after the engine has answered a lost render device by building another one. The callback receives the new device generation — a number that counts the devices this session has run on, and moves exactly once per rebuild. Returns a watcher id.

A device is lost when the driver resets, when the GPU is taken away, or when a browser reclaims a WebGPU context. Everything the engine can re-derive by itself it does: meshes, materials, shaders, render passes and the UI are all back on the new device before this fires. What it cannot re-derive is what YOUR content made and only the GPU held — a texture uploaded from pixels a script computed, a compute buffer it filled, a render target it created. Make those again here.

Content that owns no GPU resource of its own needs no subscriber: asset handles re-materialise on their next use.

Parameters

• callback (number) -> () — Function invoked as (generation: number).

engine.onDeviceRebuilt(function(generation)
-- the noise field lived only on the GPU, so it is computed again
print("upload the noise field again for device generation", generation)
end)

modules/Engine/onMemoryPressure

onMemoryPressure(callback: (string, string) -> ()): number

Register a callback that fires when the system says it is short of memory, after the engine has released what that level of pressure releases. The callback receives the level ("normal", "moderate", "low" or "critical") and who reported it: onTrimMemory(<level>) for Android's report, script for renderer.signalMemoryPressure. Returns a watcher id.

The engine frees what it can rebuild by itself: mip levels the frame does not sample, render-target storage nothing is drawing into, and from "critical" half the texture budget. What it cannot free is what YOUR content keeps: a cache of generated meshes, a table of decoded audio, pixels kept for a later upload. Drop those here and build them again when they are next needed. A level stands for a minute after the last report, and renderer.memoryPressure() reads the level in force and what the engine released.

Parameters

• callback (string, string) -> () — Function invoked as (level: string, source: string).

engine.onMemoryPressure(function(level, source)
if level ~= "normal" then
decodedClips = {} -- decoded again on next play
end
end)

modules/Engine/onModeChange

onModeChange(callback: (string, string) -> ()): number

Parameters

• callback (string, string) -> ()

modules/Engine/onPauseChange

onPauseChange(callback: (boolean, boolean) -> ()): number

Register a callback that fires synchronously whenever the gameplay pause flag flips via an explicit engine.paused write. Callback receives (newPaused, oldPaused) as booleans. Returns a watcher id. Pause is independent of engine.mode: pausing play mode returns the editor authoring surface (free camera + EditorOnly entities) over the frozen play world, and resuming hides it again. Mode-driven pause resets (the edit=paused / play=running defaults applied on a mode flip) are delivered through onModeChange, not this hook.

Parameters

• callback (boolean, boolean) -> () — Function invoked as (newPaused: boolean, oldPaused: boolean).

local id = engine.onPauseChange(function(paused)
print(paused and "frozen" or "running")
end)

modules/Engine/onTimeScaleChange

onTimeScaleChange(

Register a callback that fires on every move of the simulation rate, whoever moved it: an engine.timeScale write, a hold taken at a rate other than the one in force, a release that hands a different rate back. The callback receives (newScale, oldScale, owner), where owner is the record engine.timeScaleOwner answers with. It counts transitions, so a write or a hold landing on the rate already in force moves nothing and announces nothing; engine.timeScaleOwner is what answers who holds a rate that has stayed where it is. Several agents drive one engine at once, so this is how a run whose numbers depend on the rate learns that somebody else moved it instead of reading the number and finding out afterwards. Returns a watcher id.

local id = engine.onTimeScaleChange(function(new, old, who)
log.warn(("rate %g -> %g by %s"):format(old, new, who and who.id or "nobody"))
end)

modules/Engine/onWorldLoaded

onWorldLoaded(callback: () -> ()): number

Register a callback fired (no args) when the world is fully LOADED — its .world_entrypoint.luau ran AND its onWorldLoad returned (the startup scene loaded, defaults seeded, editor UI mounted). This is strictly AFTER onWorldReady (content synced): ready = "bytes are in the VFS"; loaded = "the entrypoint has run". LATCHED — a callback registered after the world is already loaded fires immediately, so a late consumer never misses it and never has to poll. Read the same state synchronously via engine.worldLoaded.

Parameters

• callback () -> () — Function invoked with no arguments.

modules/Engine/onWorldReady

onWorldReady(callback: () -> ()): number

Register a callback fired (no args) when the bound world's content has been synced into the VFS and the world is ready to load. This is the race-free, user-space hook that drives the whole world-VM lifecycle: the builtin world-entrypoint loader subscribes to it and, when it fires, loadstring(vfs.read(...))s /source/.world_entrypoint.luau and runs its onWorldLoad — exactly the way a scene entrypoint loads. The trusted VM fires this (via world.markReady()) ONLY once the bytes are in the VFS, so a subscriber never sees a half-synced world. Returns a watcher id.

Parameters

• callback () -> () — Function invoked with no arguments.

modules/Engine/onWorldUnloading

onWorldUnloading(callback: () -> ()): number

Symmetric teardown of engine.onWorldReady: register a callback fired (no args) when the bound world is unbinding/swapping out. The builtin loader runs the world entrypoint's onWorldUnload here, so the world entrypoint has the same load/unload parity a scene entrypoint has. Returns a watcher id.

Parameters

• callback () -> () — Function invoked with no arguments.

modules/Engine/releaseBaseline

releaseBaseline(generation: number): boolean

Drop the mark generation names, and every mark taken after it, once the caller that took it is done resetting to it. It touches the marks alone.

Parameters

• generation number — The mark to drop, as engine.markBaseline returned it.

engine.releaseBaseline(mark) -- the run is over

modules/Engine/releaseScriptingBaseline

releaseScriptingBaseline(generation: number): boolean

Drop the scripting mark generation names, and every mark taken after it, once the caller that took it is done resetting to it. The registries stay as they stand. A mark holds the require cache's keys as they stood, so a caller that marks once per run drops each mark when its run is over.

Parameters

• generation number — The mark to drop, as engine.markScriptingBaseline returned it.

engine.releaseScriptingBaseline(mark) -- the run is over

modules/Engine/releaseTimeScale

releaseTimeScale(owner: string): number

Parameters

• owner string

modules/Engine/resetScriptingState

resetScriptingState(generation: number?): { [string]: number }

Drop every world-event subscription, lifecycle watcher and cached module registered since the mark generation names — the newest engine.markScriptingBaseline() when omitted — leaving everything registered before it in place, including the builtin world-entrypoint loader, which subscribes at VM boot and so always sits below any mark. The marks taken after that one go with the reset. A module with a frame on the stack keeps its cache entry and its registrations. Raises when no such mark is in force. Returns per-registry counts of what was removed: worldEvents, modeWatchers, worldReadyWatchers, worldUnloadingWatchers, pauseWatchers, deviceRebuiltWatchers, memoryPressureWatchers, modules, and total.

Parameters

• generation number? (optional) — The generation to restore to, as markScriptingBaseline returned it; the newest mark when omitted.

modules/Engine/resetToBaseline

resetToBaseline(generation: number?): number

Put this module's own memory back as engine.markBaseline read it: every time-scale hold taken since comes off, every onTimeScaleChange subscriber added since is removed, the last writer and the base rate read as they did, the rate in force follows, and the record of who registered each watcher forgets the ids handed out since. The marks taken after generation go with the reset.

Parameters

• generation number? (optional) — The mark to restore to; the newest when omitted.

engine.resetToBaseline(mark)

modules/Engine/restoreModuleState

restoreModuleState(snapshot: { [string]: any }, options: { remint: { [string]: string }?, gone: ((any) -> boolean)?, successor: ((any) -> any?)?, only: { [string]: boolean }? }?): { [string]: any }

Put every module's state back to what engine.snapshotModuleState read. A table is refilled in place, so a closure holding it sees the restored contents, and the upvalue is pointed back at it, so a module that assigned its local a new table is reading the restored one again.

The same snapshot restores to the same state however many times it is used, so one reading taken before a run puts every later point in that run back to it.

A value whose reading names an object the engine no longer holds — a buffer whose storage was destroyed since, answering alive false — is left as it stands: what it remembered cannot be given back to it, and what it holds now is what it went on to make. The module holding it is left whole, because what it remembers beside that object — the count it sized the object for, the flag that says it made one — is the state of the object it now holds instead; it is counted under stale. A data table naming a gone object in one of its fields is a registry, and is refilled around that field. Called from a coroutine that can yield, the restore gives the frame back every few milliseconds. the engine re-minted since replaced by the id it now uses.

Parameters

• snapshot { [string]: any }
• options { remint: { [string]: string }?, gone: ((any) -> boolean)? — remint maps an id the reading holds to the id the engine now uses for the same thing — a render feature's guid after the feature was made again under its identity. gone answers whether a value the reading holds names something the engine no longer holds — a record carrying a render feature's guid when no feature carries it now; a handle answering alive false is known without it. successor answers, for an object that has gone, the live object standing in for it — the handle under a buffer's name after the buffer was made again under it — and the reading is put back holding that one, its own fields left as they are. A handle that already answered alive false when the reading was taken is the module's own record of something gone before it, and is put back as it is. same answers whether a value a module holds now already stands in for the gone object a successor was found for — the module's own live handle to the buffer made again under the name — and such a value is kept, the successor released. only names the modules to put back, by module name, and every other module's reading is left untouched — a second pass over the modules an earlier one left as they stood, once what stands in for the objects they named exists.
• successor ((any) -> any?)? (optional)
• only { [string]: boolean }? }? (optional)

engine.restoreModuleState(snap)
engine.restoreModuleState(snap, { remint = { [oldGuid] = newGuid } })

modules/Engine/scriptingRegistryCounts

scriptingRegistryCounts(): { [string]: number }

How many subscriptions each scripting registry holds right now, plus the size of the require cache and the generation of the mark in force. Keys: worldEvents, modeWatchers, worldReadyWatchers, worldUnloadingWatchers, pauseWatchers, deviceRebuiltWatchers, memoryPressureWatchers, modules, and baselineGeneration (nil when no mark has been taken).

modules/Engine/setMode

setMode(mode: string, options: { strict: boolean?, endSession: boolean? }?): { mode: string, bypassed: { any }, leftPlaySession: boolean }

Change the engine mode with per-call control over the play gate, and read back what the change went past. engine.mode = value is the same flip with the defaults.

options.strict = false lets THIS call enter play while your own content carries error-severity diagnostics. It settles with the call: the world's lsp.strict_mode is untouched, so no other session and no later session of the world sees a different gate. The returned bypassed array holds the diagnostics the call went past — each { path, line, col, code, message, severity } — and the engine log carries the same list. An error in content another session wrote never gates the flip, so it never appears here; a push still refuses to publish while any of them stands.

Parameters

• mode string — "edit" or "play".
• options { strict: boolean?, endSession: boolean? }? (optional) — { strict: boolean?, endSession: boolean? }. strict = false waives the play gate for this call; true or omitted honours the world's lsp.strict_mode. endSession = true with "edit" ends the running play session for every caller in it, whether or not you take part, and answers for everything the session holds (engine.discardPlayChanges() arms its discard); without it, an "edit" from one of several callers in play takes only that caller out, and one from a caller outside the session is refused.

local report = engine.setMode("play", { strict = false })
for _, d in ipairs(report.bypassed) do
print(("entered play past %s:%d — %s"):format(d.path, d.line, d.message))
end

modules/Engine/snapshotModuleState

snapshotModuleState(): { [string]: any }

Read the state every cached module holds — the upvalues of the closures it hands back — and answer with it, so engine.restoreModuleState can put exactly that back later.

Take it once, before the work whose changes are to be undone. Data is copied, so a table a module goes on mutating does not change what was read; an object — a table carrying a metatable or methods of its own — is kept by reference and its fields copied, so restoring returns the object every other holder is still attached to rather than a lookalike that answers none of its methods.

A module with a frame on the stack while the reading is taken — the caller, and whatever called it — is mid-operation, and what it holds is left out: neither copied here nor written back by the restore, however another module reaches it. Called from a coroutine that can yield, the walk gives the frame back every few milliseconds, so the engine keeps stepping through a reading that takes seconds.

local snap = engine.snapshotModuleState()

modules/Engine/timeScaleHolds

timeScaleHolds(): { string }

modules/Engine/waitForEdit

waitForEdit(reason: string?): () -> ()

Say that this caller's edit-mode work is waiting on the play session, and get back the call that takes the wait off.

One process runs one simulation, so a play session holds the engine in play for every caller outside it, and an agent whose edit-mode work cannot proceed has no way to say so. While this wait stands it rides the run-state block of every response any session gets from this engine, so the callers in the play session learn somebody is waiting for it. Read engine.playSession for who they are, and engine.modeOwner for who entered play and how long ago.

A wait is keyed by the caller the call was attributed to, so a named caller that registers twice moves its own entry forward rather than queueing behind itself: one caller waits once. A call carrying no agent identity is named by nothing to key on, so each such ask stands as its own waiter and the release it handed back takes that one off. Reaching edit mode takes every wait off, so a caller whose release is lost with the task that held it leaves nothing standing.

Parameters

• reason string? (optional) — What this caller is waiting to do, shown beside its name.

Returns () — A function that takes this caller's wait off.

local done = engine.waitForEdit("promote my scene edits")
-- ... once the engine reaches edit and the work is taken ...
done()

modules/Engine/watcherSources

watcherSources(): { [string]: { [number]: string } }

Who registered each watcher still standing, by registry: modeWatchers, pauseWatchers, deviceRebuiltWatchers, memoryPressureWatchers, worldReadyWatchers and worldUnloadingWatchers, each a map from watcher id to the source and line that registered it. A watcher registered before this module loaded is absent. What a reading of the registry counts names when it finds a watcher more than it began with.

for id, at in pairs(engine.watcherSources().modeWatchers) do print(id, at) end

modules/EntityRecords/README

require("@builtin::modules.entity_records") -- EntityRecords

Walks a live entity hierarchy into the flat record array the engine's entity templates use. Shared by bundle (its entity_template) and by scene builds (their baked output), so both speak one record shape.

Usage: local EntityRecords = require("@builtin::modules.entity_records")

modules/EntityRecords/addData

addData(data: any, instanceName: string?): any

The data table component.add puts a record's instance back with: data itself for the anonymous instance, and a copy carrying name for a named one, which is the key component.add reads the instance name from.

Parameters

• data any (optional) — The entry's field values.
• instanceName string? (optional) — The entry's instance name, or nil for the anonymous instance.

entity(id).component.add("Pool", EntityRecords.addData({ amount = 120 }, "mana"))

modules/EntityRecords/authoredComponentData

authoredComponentData(

A component instance's snapshot with the fields the instance wrote about its own runtime removed, leaving what states how it was CONFIGURED. A capture reads it to build the record, and whoever diffs a live entity against that record reads it too, so both sides speak the same fields.

local d = EntityRecords.authoredComponentData(id, ty, nil, snapshot)

modules/EntityRecords/captureRecord

captureRecord(rid: string, parentOriginalId: string?): any

Capture ONE entity into a template record. Reads LIVE component public state (serialized component snapshots), not init data, so the record matches what is on screen, and states the fields each instance's configuration states (configuredFields): a field left to its declared default stays out, so a later change to that default reaches whatever the record rebuilds. Each component INSTANCE gets its own entry, carrying instance_name when the instance has one, so a type the entity carries several of comes back as the same several. The record also carries the entity's own active flag, every attribute it holds, and its lifecycle mode and replication scope when either is other than the default. The entity's runtime id IS its record original_id, so cross-entity component references — which already point at runtime ids — round-trip and get remapped on the next instantiate. Each component entry names where it holds such a reference in entity_fields, taken from the component's declared field kinds: a top-level field by its name, and a reference held as a list element or struct subfield by its path from the field (an array such as { "attachments", 1, "target" }), so a rebuild resolves exactly those.

Parameters

• rid string — Runtime entity id to capture.
• parentOriginalId string? (optional) — Parent's original_id, or nil for a root record.

local rec = EntityRecords.captureRecord(id, nil)

modules/EntityRecords/carriesInstance

carriesInstance(rid: string, typeName: string, instanceName: string?): boolean

Whether the entity carries the component instance a record entry names: the instance of typeName under instanceName, or the type's anonymous instance when instanceName is nil. A loader asks this before it puts an instance back, so a named instance is never read as already present because the anonymous one is, and the reverse.

Parameters

• rid string — Runtime entity id.
• typeName string — Component type the entry names.
• instanceName string? (optional) — The entry's instance name, or nil for the anonymous instance.

if not EntityRecords.carriesInstance(id, "Pool", "mana") then entity(id).component.add("Pool", { name = "mana" }) end

modules/EntityRecords/componentIsCodeAttached

componentIsCodeAttached(rid: string, componentType: string): boolean

Whether another component's lifecycle attached this component instance, rather than an author putting it there. A composed asset brings its own machinery with it — a humanoid avatar attaches a character controller to the body it expands into — and that machinery comes back on its own wherever the composition does. A record that named it would put a second one beside the one the expansion just produced, and a rebuild that removed every component its records leave unnamed would tear the expansion off the entity it belongs to. Both sides of a rebuild ask this.

Reached through the _G singleton the origin module publishes, which is the same answer the scene serializer takes for the same question; a load order that has not published it yet reads every component as authored.

Parameters

• rid string — Runtime entity id carrying the instance.
• componentType string — Component type name as the entity reports it.

if EntityRecords.componentIsCodeAttached(id, "Humanoid") then continue end

modules/EntityRecords/compose

compose(

Build the flat record array by walking rootId's hierarchy. Skips temporary entities and their descendants — scaffolding and editor-only tooling stay out of a baked result. The explicit root is always captured: the caller named THAT entity as the thing to serialize, so temporary pruning applies to descendants.

local records = EntityRecords.compose(rootId)

modules/EntityRecords/composeMany

composeMany(

Compose several roots into one flat record array. A build captures a SET of roots (a builder may spawn several unparented entities), not the single root a bundle composes from. The roots are ordered the same way siblings are — by rank, then name, then id.

local records = EntityRecords.composeMany({ idA, idB })

modules/EntityRecords/configuredComponentData

configuredComponentData(ref: any, data: any): any

A live component instance's snapshot limited to the fields its configuration states (configuredFields). A field the instance leaves to its declared default is left out, so whatever is rebuilt from the result takes the component's default as it stands then, rather than the value it had when this was read.

Parameters

• ref any (optional) — The live component instance (a component proxy).
• data any (optional) — Snapshot of the instance's data.

local ComponentSnapshot = require("@builtin::modules.component_snapshot")
local d = EntityRecords.configuredComponentData(ref, ComponentSnapshot.snapshot(ref))

modules/EntityRecords/configuredFields

configuredFields(ref: any): { [string]: boolean }?

The fields one live component instance's configuration states: the keys of the table it was attached with, and every field written since (through its proxies, or by a replicated or undo write). That is the set a hot reload carries across a source edit; every other field holds the component's declared default, so a record that leaves it out lets a changed default reach the instance. Nil when the engine does not answer, which a caller reads as "every field".

Parameters

• ref any (optional) — The live component instance (a component proxy).

local set = EntityRecords.configuredFields(entity(id).component("Light"))

modules/EntityRecords/instanceNameOf

instanceNameOf(entry: any): string?

The instance name a component entry of a record states, or nil for the type's anonymous instance. Every record shape names a component instance the same way: a scene entity record, a captured entity record and a build record each carry instance_name beside type on the entry of a named instance, so an entity carrying several instances of one type comes back carrying the same several.

Parameters

• entry any (optional) — One entry of a record's components list.

local name = EntityRecords.instanceNameOf({ type = "Pool", instance_name = "mana" }) -- "mana"

modules/EntityRecords/instancesOf

instancesOf(rid: string, typeName: string?): { ComponentInstance }

The { type, instance?, data } records component.getAll answers for the entity, normalised: instance is nil for the anonymous instance and the instance's name otherwise. Narrowed to one type when typeName is given.

Parameters

• rid string — Runtime entity id.
• typeName string? (optional) — Component type to narrow to, or nil for every instance.

for _, inst in ipairs(EntityRecords.instancesOf(id, "Pool")) do print(inst.type, inst.instance) end

modules/FontAssetTypeRef/README

require("@builtin::assetTypes.font.behavior") -- FontAssetTypeRef

Hooks for .font assets. onCreate is the type's contribution to the generic asset.create("font", name, opts) flow (mirroring texture.assetType): it parses the font file ONCE into the baked, vectorized glyph format (data.zfnt) — the asset payload. onRegister loads that baked format via the engine font.register(name, zfnt) primitive — a font is a general CPU resource, so one registration makes fontFamily = "<name>" resolve on the egui UI text surface AND on text.* 2D/3D rendering, and feeds font.glyph / font.textMesh for true 3D text.

Usage: local FontAssetTypeRef = require("@builtin::assetTypes.font.behavior")

modules/FontAssetTypeRef/onChange

onChange(self, change)

Install the instance again when a file its registration reads is written: face.json, data.zfnt, a raw font file, or the font or coverage file an on-demand entry names. The font is then selected by the names the descriptor now gives it and no longer by a name it dropped, on every text surface, and text drawn in it is drawn again. A folder that arrives whole installs once, unless onRegister already installed it.

Parameters

• self any (optional) — The .font instance's AssetRef.
• change any (optional) — { path, asset, kind, ... }: the written file and how it arrived.

modules/FontAssetTypeRef/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

The .font type's contribution to asset.create("font", name, opts). Parses the font file ONCE into the baked vectorized glyph format and stores it as data.zfnt. The original font bytes are embedded inside the baked payload, so no separate font file is kept. The heavy parse happens here, at author time — onRegister then loads the result cheaply.

Parameters

• name string — The font asset name (also the registered fontFamily).
• opts CreateOpts

asset.create("font", "Inter", { bytes = fontBytes, ext = "ttf" })

modules/FontAssetTypeRef/onRegister

onRegister(self)

Install this .font instance into the engine's text systems. Reads the instance's baked data.zfnt and calls font.register(name, zfnt), which loads the vectorized glyph data into the runtime store (for font.glyph / font.textMesh) and feeds the embedded font bytes to the 2D text and egui UI systems. Falls back to a raw font file for instances authored before the baked layout. An instance whose face.json lists onDemand entries is declared by their coverage instead (font.declare), and each entry's file is read the first time text needs a character it covers. Fired once per instance by the asset system (live on asset.create, and in the world-load sweep). Guarded so a single bad font never errors the sweep.

Parameters

• self any (optional)

modules/FontAssetTypeRef/payloadReady

payloadReady(path: string): boolean

Whether a .font instance's payload is present to register from: its baked data.zfnt, or, for an on-demand face, the face.json that lists its chunks. The builtin boot registration asks this before firing onRegister; on WASM a builtin leaf arrives asynchronously, so a read that returns nil answers false and has started the fetch a later call finds landed.

Parameters

• path string — VFS path of the .font folder.

modules/FrameBudget/README

require("@builtin::modules.frame_budget") -- FrameBudget

The share of a frame that cooperative engine work spends before it hands the frame back. Work that runs as a sequence of units on a task (a scene load applying its records, the world-load onRegister sweep) asks due() before each unit and yields once the frame's slice is spent, so a long piece of work runs across frames at the engine's frame rate rather than holding one frame for its whole length. One slice per frame is shared by every caller in the VM: what each caller runs between its readings of the slice in a frame (task.runTime, so none of what the rest of the frame runs) is charged to it. A unit is never split, so the first unit of a frame always runs, and a frame holds the slice plus the one unit that crossed it.

Usage: local FrameBudget = require("@builtin::modules.frame_budget")

modules/FrameBudget/due

due(ms: number?): boolean

Whether the caller hands the frame back before its next unit: it runs on a coroutine that can yield, and this frame's slice has spent ms. Code that cannot yield is answered false and runs its units in the frame it was called in.

Parameters

• ms number? (optional) — Milliseconds the slice may spend (default FrameBudget.DEFAULT_MS).

if FrameBudget.due() then FrameBudget.wait() end

modules/FrameBudget/mark

mark(into: { [string]: any }?): { [string]: any }

A reading of how long the calling coroutine has run (task.runTime), for ranMs to measure the work it runs from here: a budget of a caller's own, counted apart from the frame's shared slice. Written into into when given, a table several pieces of work share by reference. The reading names its coroutine by a token of its own.

Parameters

• into { [string]: any }? (optional) — The table to write the reading into, or nil for a new one.

local mark = FrameBudget.mark() ... if FrameBudget.ranMs(mark) > 5 then FrameBudget.wait() FrameBudget.mark(mark) end

modules/FrameBudget/ranMs

ranMs(mark: { [string]: any }): number

Milliseconds the calling coroutine has run since mark was read on it: none of the time it spent suspended (waiting on a frame, a read-back, or another coroutine it resumed). 0 when the mark was read on another coroutine.

Parameters

• mark { [string]: any } — A reading from mark.

if FrameBudget.ranMs(mark) > 5 then FrameBudget.wait() FrameBudget.mark(mark) end

modules/FrameBudget/remainingMs

remainingMs(ms: number?): number?

Milliseconds this frame's slice has left before due(ms) answers true, never below zero, for work that bounds a unit by time itself (a native call told how long it may run). Nil when the caller runs on a coroutine that cannot yield: it runs its work in the frame it was called in, with no slice to keep to.

Parameters

• ms number? (optional) — Milliseconds the slice may spend (default FrameBudget.DEFAULT_MS).

local left = FrameBudget.remainingMs()

modules/FrameBudget/spent

spent(): number

Milliseconds the budgeted work of the current frame has spent: the time each caller ran between its readings of the slice in this frame, summed over every caller. A caller's first reading in a frame charges nothing.

local ms = FrameBudget.spent()

modules/FrameBudget/sync

sync(fn: () -> ...any): ...any

Run fn without handing the frame back: due() answers false to every caller until it returns, so the work its callees do between their checkpoints completes inside the call. For a caller whose result must stand when the call returns. Answers what fn answers.

Parameters

• fn () -> ...any — The function to run.

local entry = FrameBudget.sync(function() return effect:entry("burst") end)

modules/FrameBudget/wait

wait()

Hand the frame back: yield to the next frame and open that frame's slice as the caller resumes, so the unit it runs next is charged to the slice. A caller that does work of its own around the yield asks due() and calls this; yield() is the two together.

if FrameBudget.due() then FrameBudget.wait() end

modules/FrameBudget/yield

yield(ms: number?): boolean

Yield to the next frame when due(ms) answers true. Called before each unit of a long piece of work, so the work spends at most a slice of each frame it runs across.

Parameters

• ms number? (optional) — Milliseconds the slice may spend (default FrameBudget.DEFAULT_MS).

for _, path in ipairs(paths) do FrameBudget.yield() print(vfs.read(path)) end

modules/FrameDriver/README

require("@builtin::modules.frameDriver") -- FrameDriver

A loop a library module runs on its own behalf once per frame, for as long as it has work: the driver behind a system that advances itself without an owner calling update(dt), such as an autoUpdate particle emitter or an effects.play.

The loop is a system task (task.spawnSystem), so it belongs to the module rather than to whoever happened to be running when the first piece of work arrived. A one-shot execute, a task scope, a component hook and a scene entrypoint can each start it, and none of them ending stops it. It runs while there is work and ends once there is none; the next ensure starts it again. A loop that ended any other way (cancelled by handle, halted by the watchdog, or torn down with its VM), whether at its frame wait or in the middle of a step, is recognised by its task status, and ensure starts a fresh one in its place. With gameplayClock = true the loop steps on the gameplay clock: in play, a frame that arrives while engine.paused is set calls nothing, and the next frame after the pause lifts carries on from there. In edit the loop keeps stepping, because there it is the editor's authoring preview, the same standing editorUpdate(dt) has. engine.timeScale reaches the step through the scheduler, which scales the delta task.wait() reports.

Usage: local FrameDriver = require("@builtin::modules.frameDriver")

modules/FrameDriver/gameplayClockRunning

gameplayClockRunning(): boolean

Whether the gameplay clock is running: false only in a play session that is paused. Edit mode reads as paused and still answers true, since a self-driven system there is the editor's preview.

if FrameDriver.gameplayClockRunning() then sys:update(dt) end

modules/FrameDriver/new

new(opts: Options): Driver

Make a driver. It starts on the first ensure and runs while hasWork answers true.

Parameters

• opts Options — { name, hasWork, step, gameplayClock?, maxStep? }, see Options.

local driver = FrameDriver.new({ name = "ripples", hasWork = function() return #live > 0 end, step = advanceAll, gameplayClock = true })

modules/FrameShape/README

require("@builtin::tests.fixtures.frame_shape") -- FrameShape

The shape of the frame the viewport draws, for a suite whose fixture or whose reading depends on it: the width over the height of the scene rect, the extent the frame covers at a distance, whether the frame was drawn at the scene rect's shape yet, and a scene rect drawn at a chosen shape for as long as a case needs it. The frame is the rect the engine draws the scene into: the headless framebuffer a native engine was started at, the browser window on the web, and whatever the editor's panels leave of either. A case written for one of those shapes and read on another reads a different part of the scene.

Usage: local FrameShape = require("@builtin::tests.fixtures.frame_shape")

modules/FrameShape/aspectOf

aspectOf(w: number, h: number): number

The width over the height of a rect of pixels.

Parameters

• w number — The rect's width.
• h number — The rect's height.

local aspect = FrameShape.aspectOf(1920, 1080)

modules/FrameShape/frameHalfExtent

frameHalfExtent(distance: number): (number, number)

The half width and half height of the rectangle the viewport's frame covers distance in front of the camera drawing it. Read off the frame as it was drawn, so a fixture sized from it fills the frame whatever shape an editor layout gives the scene rect.

Parameters

• distance number — How far in front of the camera, in metres.

local halfW, halfH = FrameShape.frameHalfExtent(5)

modules/FrameShape/frameMatchesSceneRect

frameMatchesSceneRect(cameraId: string?): boolean

Whether the viewport's frame was drawn at the shape of the scene rect the engine reports now. A resize reaches the camera's frame a frame after the surface, and a fixture sized or a tile worked out off the frame before it would be for a shape that is gone.

Parameters

• cameraId string? (optional) — The camera whose frame to read; the viewport camera when nil.

while not FrameShape.frameMatchesSceneRect() do task.wait() end

modules/FrameShape/widenTheSceneRect

widenTheSceneRect(aspect: number?): () -> ()

Draw the scene rect aspect times wider than it is tall, by changing the surface's height and keeping its width. The panels an editor layout puts under or over the scene take a share of that height, so the height that gives the shape is found by measuring: each step resizes the surface, reads the scene rect the layout drew at that size, and aims the next step along the line through the two latest readings. The shape is asserted, to within a tenth of aspect either way, rather than assumed, so a host that keeps the size it has, or cannot draw the scene rect at that shape, fails the case instead of running it at another shape. Call it from inside a test: it registers a cleanup that puts the surface back, without waiting, for a case that ends early.

Parameters

• aspect number? (optional) — The width over the height to reach; WIDE_ASPECT when nil.

Returns () — What puts the surface back and waits for the host to realize it, for the case to call at its end so the frames that do it are drawn under that case rather than under whatever runs next.

local putBack = FrameShape.widenTheSceneRect(); --[[ … ]] putBack()

modules/FxFrameProbe/README

require("@builtin::tests.fixtures.fx_probe") -- FxFrameProbe

The reader half of the frame probe — the grid fx_frame_probe.renderFeature writes each frame, and the measurements taken off it. A suite requires this module and enables the feature; the feature records the target it writes here, so both halves address one target. They are separate assets because renderer.feature.create compiles a feature's init.luau as its own chunk rather than requiring it, so a feature cannot publish state to a caller through its own module table. What it is for: a returned screenshot is not evidence. A fully transparent emitter reports live particles, reports that it drew, and changes the image hash. A reader needs a magnitude, taken from the frame a viewer actually sees, that a known control is shown to move.

Usage: local FxFrameProbe = require("@builtin::tests.fixtures.fx_probe")

modules/FxFrameProbe/channelSums

channelSums(grid: { [string]: any }?): { [string]: number }

Sum each colour channel over the grid — how much red, green and blue the frame carries. What a colour parameter has to move.

Parameters

• grid { [string]: any }? (optional) — A grid from read().

local c = probe.channelSums(probe.read())

modules/FxFrameProbe/faceTiles

faceTiles(

The tiles the middle fifth of a flat face is drawn in: a six by six grid of points over that fifth, each turned into the tile it lands in. The middle rather than the whole, because a tile is a downsample of many pixels and one straddling the face's silhouette carries the background with it.

local tiles, off = probe.faceTiles(view, { -4, 40.25, -4 }, { 8, 0, 0 }, { 0, 0, 8 })

modules/FxFrameProbe/litRegion

litRegion(grid: { [string]: any }?, baseline: { [string]: any }?, threshold: number): { [string]: number }

The size of the lit region: how many tiles rise threshold luminance above baseline's same tile, and the radius of a disc with that area, in tiles. This is the spatial reading — how WIDE something drew, which no whole-frame number can answer.

Parameters

• grid { [string]: any }? (optional) — The grid to measure.
• baseline { [string]: any }? (optional) — The grid of the same view with the subject absent.
• threshold number — How far above the baseline tile a tile must rise to count.

local r = probe.litRegion(after, before, 6).radius

modules/FxFrameProbe/movedTiles

movedTiles(grid: { [string]: any }?, other: { [string]: any }?, threshold: number): number

How many tiles differ between two grids by at least threshold luminance, in either direction. Zero says the two readings are the same picture — which is what a reading that has not caught up with a change yet also answers, so this is how a caller tells a still frame from one that has not arrived.

Parameters

• grid { [string]: any }? (optional) — The grid to measure.
• other { [string]: any }? (optional) — The grid to measure it against.
• threshold number — How far a tile must differ to count.

if probe.movedTiles(now, before, 4) > 0 then --[[ the change landed ]] end

modules/FxFrameProbe/read

read(): { [string]: any }?

Read the last grid the probe wrote. Returns { width, height, tiles }, where tiles[y * width + x + 1] is that tile's mean colour as { r, g, b } in 0..255, plus lum — the tile's luminance on the same scale.

local grid = probe.read(); print(grid.tiles[1].lum)

modules/FxFrameProbe/rowOf

rowOf(tile: number): number

The row of the grid a tile from tileAt sits in, counted from 0 at the top of the frame.

Parameters

• tile number — A 1-based tile index.

local row = probe.rowOf(tile)

modules/FxFrameProbe/skyTiles

skyTiles(view: { [string]: any }, toward: { number }): ({ number }, number)

The tiles of the rows above the horizon, which is where sky is drawn whatever shape the frame is. The horizon is the row a point level with the camera is drawn in, as far along the ground direction toward toward as the lens resolves; the row is read off the view's projection whether or not that point falls inside the frame's columns. The row just above it and the frame's top row are left out, so no tile read reaches the ground or the frame's edge.

Parameters

• view { [string]: any } — A view from camera.viewData(id): its position is the eye.
• toward { number } — A world point { x, y, z } the camera looks toward; only its x and z are read.

local sky, horizonRow = probe.skyTiles(view, { 0, 40, 0 })

modules/FxFrameProbe/sphereTiles

sphereTiles(

The tiles the inner part of a sphere is drawn in: every tile whose whole rect lies inside the sphere's outline drawn inner of the way out from its middle. The outline is the circle along which a line from the eye grazes the sphere, projected through the view the frame was drawn under, so the tiles follow the sphere at whatever shape the frame is. Whole tiles, and inside a margin, because a tile is a downsample of many pixels and one straddling the silhouette carries the background with it.

local tiles, off = probe.sphereTiles(camera.viewData(cam.id), { -3.5, 0, 0 }, 1.5)

modules/FxFrameProbe/tileAt

tileAt(view: { [string]: any }, x: number, y: number, z: number): number?

The tile a world point is drawn in, worked out from the view the frame was drawn under. The grid covers the whole frame whatever shape the frame is, so a tile written down as a constant lands on a different part of the scene at every other shape; a tile worked out from the view lands on the point at every shape.

Parameters

• view { [string]: any } — A view from camera.viewData(id): its viewProj is the matrix the frame was drawn with.
• x number — World x of the point.
• y number — World y of the point.
• z number — World z of the point.

local tile = probe.tileAt(camera.viewData(cam.id), 0, 1, 0)

modules/FxFrameProbe/tilesColour

tilesColour(grid: { [string]: any }, tiles: { number }): { r: number, g: number, b: number, lum: number }

The mean colour of a set of tiles in a grid.

Parameters

• grid { [string]: any } — A grid from read().
• tiles { number } — 1-based tile indices, as tileAt, faceTiles, sphereTiles and skyTiles hand them back.

local c = probe.tilesColour(probe.read(), tiles)

modules/FxFrameProbe/tilesLuminance

tilesLuminance(grid: { [string]: any }, tiles: { number }): number

The mean luminance of a set of tiles in a grid.

Parameters

• grid { [string]: any } — A grid from read().
• tiles { number } — 1-based tile indices, as tileAt, faceTiles, sphereTiles and skyTiles hand them back.

local lum = probe.tilesLuminance(probe.read(), tiles)

modules/FxFrameProbe/totalLuminance

totalLuminance(grid: { [string]: any }?): number

Sum the grid's luminance — the whole frame's brightness as one number.

Parameters

• grid { [string]: any }? (optional) — A grid from read().

local before = probe.totalLuminance(probe.read())

modules/GI.Scenarios/README

require("@builtin::systems.globalIllumination.scenarios") -- GI.Scenarios

Several baked lighting states per probe volume, blended at runtime.

A volume holds one bake, so a scene lit for noon cannot become a scene lit for dusk without baking again — which takes far longer than a transition is allowed to. Capturing each bake under a name and blending the captures turns that into an interpolation the frame can afford. Irradiance adds, so blending the spherical-harmonic coefficients is the same as blending the light that produced them. Each coefficient's fourth lane is not light, though: it carries the probe's per-axis visibility reach and the markers the sampler reads. Those describe the geometry the volume sits in, which every scenario shares, so they are carried from the heaviest-weighted scenario rather than averaged — the mean of two distances describes no wall that exists. Carrying them from the heaviest contributor also makes the ends of a transition exact: a blend that names one scenario at full weight reproduces that scenario's field lane for lane.

Usage: local GI.Scenarios = require("@builtin::systems.globalIllumination.scenarios")

modules/GI.Scenarios/blend

blend(volumeEntityId: string, weights: { [string]: number }) -> boolean

Publish the weighted mix of named scenarios to the renderer.

Parameters

• volumeEntityId string
• weights { [string]: number }

Returns boolean

modules/GI.Scenarios/capture

capture(volumeEntityId: string, name: string) -> number

Store the volume's currently published field under a name. Returns how many probes it holds.

Parameters

• volumeEntityId string
• name string

Returns number

modules/GI.Scenarios/clear

clear(volumeEntityId: string)

Parameters

• volumeEntityId string

modules/GI.Scenarios/field

field(volumeEntityId: string, name: string) -> { number }?

Parameters

• volumeEntityId string
• name string

Returns { number }?

modules/GI.Scenarios/forget

forget(volumeEntityId: string, name: string)

Parameters

• volumeEntityId string
• name string

modules/GI.Scenarios/list

list(volumeEntityId: string) -> { string }

Parameters

• volumeEntityId string

Returns { string }

modules/GI.Scenarios/mix

mix(fields: { { number } }, weights: { number }) -> { number }

Blend baked SH fields by weight. Pure — no volume, no GPU.

Parameters

• fields { { number } }
• weights { number }

Returns { number }

modules/GI.Scenarios/stats

stats() -> table

Returns table

modules/GI.SkyResponse/README

require("@builtin::systems.globalIllumination.skyResponse") -- GI.SkyResponse

A probe volume's sky term, evaluated at publish time instead of baked in.

A probe bake follows each path until it escapes, and what escapes carries the sky's colour. Baking that in means the sky is fixed the moment the bake finishes: a scene cannot dim its sky for dusk, or clear an overcast, without paying for the bake again. The sky enters the path integral as throughput * sky at the point a ray escapes, and throughput — the product of the albedos the path already passed through — does not depend on the sky at all. So the baked field splits exactly into a term that has nothing to do with the sky and a term that is linear in it, per channel: field(sky) = lights + sky * aperture lights is a bake under no sky. aperture is what a unit sky adds: how much of it each probe can see, tinted by whatever the light passed through on the way, so sky arriving through a red wall stays red. Both come from real bakes at the same settings, and the bake seeds its paths from the probe and sample index alone — so the two runs trace the same paths and the subtraction that isolates the aperture carries no sampling residual.

Usage: local GI.SkyResponse = require("@builtin::systems.globalIllumination.skyResponse")

modules/GI.SkyResponse/apply

apply(volumeEntityId: string, sky: { number }) -> boolean

Publish the volume's field for a sky colour. No bake.

Parameters

• volumeEntityId string
• sky { number }

Returns boolean

modules/GI.SkyResponse/calibrate

calibrate(volumeEntityId: string) -> table

Bake the volume twice — once with no sky, once with a unit sky — and keep the two terms the split needs.

Parameters

• volumeEntityId string

Returns table

modules/GI.SkyResponse/calibrated

calibrated(volumeEntityId: string) -> boolean

Parameters

• volumeEntityId string

Returns boolean

modules/GI.SkyResponse/clear

clear(volumeEntityId: string)

Parameters

• volumeEntityId string

modules/GI.SkyResponse/combine

combine(lights: { number }, aperture: { number }, sky: { number }) -> { number }

The field for a sky colour, from the two calibrated terms. Pure.

Parameters

• lights { number }
• aperture { number }
• sky { number }

Returns { number }

modules/GI.SkyResponse/terms

terms(volumeEntityId: string) -> table?

Parameters

• volumeEntityId string

Returns table?

modules/GaussianSplatAssetTypeBehavior/README

require("@builtin::assetTypes.gaussianSplat.behavior") -- GaussianSplatAssetTypeBehavior

Behaviour for the gaussianSplat asset type — how a capture becomes something standing in a scene. A cloud draws through a GaussianSplat component pointed at the container, so :instantiate() — the uniform contract every consumer reaches — spawns exactly that, in the axis convention the container recorded.

Usage: local GaussianSplatAssetTypeBehavior = require("@builtin::assetTypes.gaussianSplat.behavior")

modules/GaussianSplatAssetTypeBehavior/instantiate

instantiate(self, target: EntityRef?, opts: { [string]: any }?): (EntityRef, { [string]: string })

Instantiate this capture — spawn an entity drawing the cloud, in the axis convention the container recorded. The same name a bundle and an avatar answer to, so an asset goes into a scene the same way whatever kind it is.

Passing a target entityRef spawns the cloud as that entity's CHILD, so an owner that tears down its children takes the cloud with it. With no target the cloud is a fresh root.

Parameters

• self any (optional)
• target EntityRef? (optional) — Optional owning EntityRef — the cloud spawns as its child.
• opts { [string]: any }? (optional) — { position?, rotation?, scale?, name?, temporary? } — the base placement opts; temporary keeps the spawn out of the saved scene.

local root = asset.resolve("room", "gaussianSplat"):instantiate()
local root = captureRef:instantiate(entity.spawn("mount"))

modules/GeneratorInspector/README

require("@builtin::systems.procgen.generator_inspector") -- GeneratorInspector

The Generator component's card on an entity. It replaces the card's generic settings section with one built from the bound graph: the graph it runs, as an asset picker, and which of its outputs it realizes; then groups — INPUTS, one row per input the graph declares in the control its declared type takes, each able to take an expression over the graph's own time in its place; TIMELINE, the transport, a scrubber across the range, the range itself, the frame rate, looping and wall time; COOK, what is cooking, what cooking has cost and the frame budget — and the Flatten action.

Usage: local GeneratorInspector = require("@builtin::systems.procgen.generator_inspector")

modules/GeneratorInspector/buildFieldSpecs

buildFieldSpecs(graph: any, params: { [string]: any }?): { FieldSpec }

Build the editable field descriptors for a graph: one spec per declared graph input, sorted by name, carrying the input's kind, its current value (the param override when set, else the declared default), the declared min/max range, the asset kind a reference input picks from, and whether the value changes over the graph's time. Pure — no UI, no entity access — so the field mapping is testable headless.

Parameters

• graph any (optional) — A loaded proc graph (proc.load).
• params { [string]: any }? (optional) — The component's current param-override table (may be nil).

modules/GuideAssetTypeRef/README

require("@builtin::assetTypes.guide.behavior") -- GuideAssetTypeRef

Per-instance methods exposed on every AssetRef<guide>. Loaded lazily by assetType.shared.ref.

Usage: local GuideAssetTypeRef = require("@builtin::assetTypes.guide.behavior")

modules/GuideAssetTypeRef/getGuide

getGuide(self): string?

Read the guide's guide.md body.

Parameters

• self any (optional)

local md = guideRef:getGuide()

modules/GuideAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { headings, wordCount }, parsed from this guide's own guide.md. A guide with no readable guide.md returns an empty headings list and zero wordCount rather than erroring.

Parameters

• self any (optional)

local headings = asset.inspect(guideRef).detail.headings

modules/ImporterAssetTypeRef/README

require("@builtin::assetTypes.importer.behavior") -- ImporterAssetTypeRef

Per-instance methods exposed on every AssetRef<importer>. Loaded lazily by assetType.shared.ref.

Usage: local ImporterAssetTypeRef = require("@builtin::assetTypes.importer.behavior")

modules/ImporterAssetTypeRef/getInitScript

getInitScript(self): string?

Read the importer's entry script as raw text.

Parameters

• self any (optional)

local src = importerRef:getInitScript()

modules/ImporterAssetTypeRef/getReadme

getReadme(self): string?

Read the importer's README.

Parameters

• self any (optional)

print(importerRef:getReadme())

modules/ImporterAssetTypeRef/run

run(self, payload: any): any

Invoke the importer with a payload (e.g. a path to the file to import). Loads the importer module on demand and calls its primary exported function. Raises a Luau error tagged with the importer's identity on load failure / missing entry.

Parameters

• self any (optional)
• payload any (optional) — Argument forwarded verbatim to the importer entry.

importerRef:run("/zero/source/foo.glb")

modules/ImporterShared/README

require("@builtin::assetTypes.importer.shared") -- ImporterShared

The importer SYSTEM — shared by every .importer/ instance. Owns dispatch, origin-gating, content-gating, the asset.containing bundle skip, re-entrancy, output marking, and bundle relocation. The engine emits one generic "a source path was written" signal per write (onLooseWrite); this module decides whether any registered importer should claim it and runs the winner. Individual importers implement ONLY canImport(path, bytes) + import(ctx) — never trigger logic.

Usage: local ImporterShared = require("@builtin::assetTypes.importer.shared")

modules/ImporterShared/awaitJob

awaitJob(path: string, timeoutSecs: number?): ImportJob?

Wait until the latest job for path settles: a terminal state (imported / failed / unclaimed / skipped / cancelled), or "owed", which holds until play ends or the live session re-establishes (reason says which) and so is returned at once rather than waited out. The in-flight "queued" and "running" are waited through, until the timeout elapses. Returns the job (nil when no job exists for the path at all).

Parameters

• path string — The source VFS path.
• timeoutSecs number? (optional) — Max seconds to wait (default 30).

modules/ImporterShared/cancelAllQueued

cancelAllQueued(): number

Cancel EVERY queued source that hasn't started importing yet, and every owed import, held until play ends or until the live session re-establishes (in-flight imports are left to finish). Use it to abandon a large accidental drop.

modules/ImporterShared/cancelQueued

cancelQueued(path: string): boolean

Cancel a source before it imports: a QUEUED one is dropped from the pump's queue, an OWED one (waiting for play to end or for the live session to re-establish) is dropped from the owed set, and its job settles as "cancelled". A source already importing is mid-parse and can't be unwound cleanly, so it is left to finish: returns false for a path that is already running, terminal, or was never queued or owed.

Parameters

• path string — The queued or owed source VFS path.

modules/ImporterShared/explain

explain(path: string): { [string]: any }

Dry-run the dispatch gates for a path WITHOUT importing: does the file exist, which importers claim it, and which gate (if any) would stop an import right now. The answer to "I wrote this file and nothing happened".

Parameters

• path string — The source VFS path.

modules/ImporterShared/extensionsOf

extensionsOf(ref: any): { string }?

The file extensions ref's importer declares it claims (M.extensions in its init.luau), lower-case without the dot; nil when it declares none.

Parameters

• ref any (optional) — The importer asset.

local exts = ImporterShared.extensionsOf(asset.resolve("@builtin::importers.texture"))

modules/ImporterShared/importedAssets

importedAssets(): { { [string]: any } }

Every asset in the world carrying import provenance, newest at first. Each row: { asset (path), importer (guid), source ({guid,path}), iteration, at }. Backed by the asset.list presence filter — one cross-type query.

modules/ImporterShared/job

job(path: string): ImportJob?

The latest import job recorded for an exact source path, or nil when no dispatch has reached a claimant for it.

Parameters

• path string — The source VFS path.

modules/ImporterShared/jobs

jobs(filter: { state: string?, path: string?, limit: number? }?): { ImportJob }

Recent import jobs, newest first. Pass a filter to narrow: state keeps one state, path substring-matches the source path, limit caps the count (default 25).

Parameters

• filter { state: string?, path: string?, limit: number? }? (optional) — Optional { state?: string, path?: string, limit?: number }.

modules/ImporterShared/jobsVersion

jobsVersion(): number

A number that moves each time an import job is recorded or its state changes: fold it into a signature to rebuild what lists the jobs.

parts[#parts + 1] = tostring(ImporterShared.jobsVersion())

modules/ImporterShared/listImporters

listImporters(): { { name: string, identity: string } }

Every registered importer: { name, identity } per .importer asset.

modules/ImporterShared/onAssetWrite

onAssetWrite(assetPath: string, path: string, origin: string?): string?

Engine-driven (through the asset-type change dispatcher): a file inside a typed asset was written. When that asset's import record names the file as the source the asset was imported from, the importers run again on it, regenerating the asset in place. The record is the whole link: it follows the source through a rename (by guid), and nothing else is watched. A write of the same bytes under the same importer settings is skipped, and a write made on a peer is left to that peer.

Parameters

• assetPath string — The typed asset the written file is inside.
• path string — The written file.
• origin string? (optional) — "local" for a write made on this client, "remote" for a peer's.

modules/ImporterShared/onLooseWrite

onLooseWrite(path: string, origin: string?)

Engine-driven: a source path with no enclosing typed-asset folder was written. Gate on origin + re-entrancy, then ENQUEUE it on the bounded import queue (default concurrency 1) — the pump reads the bytes, decides whether a registered importer claims it, applies the content + containment gates, and runs the winner, one import at a time.

Parameters

• path string — The written VFS path.
• origin string? (optional) — "local" for a write made on this client, "remote" for a peer-synced write. Only "local" writes trigger — peers receive the originator's derived bundle as ordinary synced content.

modules/ImporterShared/queue

queue(): { ImportJob }

The live import backlog: queued sources (still waiting behind the concurrency cap, in FIFO order), then the ones importing right now, then the owed ones, held until play ends or the live session re-establishes (sorted by path). The focused "what is the importer doing this instant" view, distinct from jobs (the full recent-dispatch log including terminal states).

modules/ImporterShared/reimportAsset

reimportAsset(assetPath: string): string?

Reimport a produced asset in place: resolve its source and re-run the importers on it (the containment gate regenerates the container's derived assets from the retained source). Returns the produced path, or nil when no source could be resolved.

Parameters

• assetPath string — The produced asset's path.

modules/ImporterShared/resolveImportSource

resolveImportSource(assetPath: string): string?

Resolve the source file a produced asset was imported from. Prefers the provenance source guid (survives rename/move), falls back to the recorded path, then to scanning the container for an importer-claimed file.

Parameters

• assetPath string — The produced asset's path (e.g. a .bundle).

modules/ImporterShared/runImporter

runImporter(importer: any, path: string): string?

Run ONE importer on path now and return the produced asset path, or nil when that importer does not claim the file. runImporters hands a source to the first claimant that takes it; this names the importer, for a source two importers both claim or an importer being tried out. The import runs exactly as a dispatched one does — synchronously, in the calling task, with the importer's own settings as ctx.settings — and is recorded as a job.

Parameters

• importer any (optional) — The importer: an AssetRef, or its name or identity.
• path string — The raw source VFS path to import.

local out = Importers.runImporter("texture", "/zero/source/hero.png")

modules/ImporterShared/runImporters

runImporters(

Run the importers on path NOW and return the produced asset path (a .bundle / .texture / .audio / …), or nil if no importer claims it. The manual, deterministic counterpart to the engine's loose-write dispatch: forced (no origin, content, or containment gate) and synchronous — it runs in the calling task and returns only when the import is complete, so a caller can write a raw source quietly (vfs.write(path, bytes, { quiet = true })) and then import it deterministically instead of racing the watcher. A source that already lives inside its own output container re-imports in place, regenerating the container's derived assets from the retained source. While play runs and holds a source that predates it where it stands (vfs.playHoldsInPlace), a fresh import of it is owed: this returns nil, the job (M.job(path)) reads "owed" with reason "play-lock", and the import runs when play ends or pauses. While the live session is lost (vfs.sessionLost), and when a drop refuses a write the import makes, the import is owed with reason "session-lost" the same way, and runs when the session re-establishes.

modules/ImporterShared/runTargets

runTargets(target: any, opts: { recursive: boolean?, mode: string? }?): { [string]: any }

Import/reimport one target, an array of targets, or a folder. A produced asset (with provenance) reimports in place; a loose source imports; a folder is scanned (recursive by default) and its imported assets reimported + loose sources imported, filtered by opts.mode ("all" | "new" | "existing").

Parameters

• target any (optional) — A VFS path string or an array of path strings.
• opts { recursive: boolean?, mode: string? }? (optional) — { recursive?: boolean (default true), mode?: "all"|"new"|"existing" }.

modules/ImporterShared/stats

stats(): { queued: number, running: number, owed: number, states: { [string]: number } }

Live queue counters: queued (sources waiting on the pump — the authoritative backlog depth), running (imports in flight), owed (imports held back until play ends, because the running play session holds their source where it stands, or until the lost live session re-establishes), and states (every recorded job tallied by state). queued, running and owed are exact; states tallies the job registry, which keeps every in-flight job plus the most recent settled records.

modules/ImporterShared/writeOutcome

writeOutcome(path: string, sinceFrame: number?, timeoutSecs: number?): WriteOutcome?

Where the bytes a write put at path end up. A write outside every typed asset folder is offered to the importers, and one that claims the bytes may move them into the asset it makes. This waits, up to timeoutSecs, for the dispatch that write set off to settle, and answers with its outcome: nil when no importer claims the bytes (they stay at path), else the import's state, the importer, the asset it made (output), the file the bytes are in now (source, nil when the import kept no copy) and a note stating all of it in a sentence. An import still running when the wait runs out answers queued or running; an import held back answers owed at once, the bytes staying at path until it runs: reason "play-lock" when the running play session holds them, until play ends or pauses, and "session-lost" while the live session is lost, until it re-establishes; bytes an importer claims that no dispatch reached (a quiet write fires none) answer not-started, the bytes staying at path.

Parameters

• path string — The written VFS path, as the engine spells it (/zero/source/...).
• sinceFrame number? (optional) — The engine frame (time.frameCount()) read before the write: a settled job recorded for path before it answers for an earlier write.
• timeoutSecs number? (optional) — Max seconds to wait for the import to settle (default 10).

local outcome = ImporterShared.writeOutcome("/zero/source/art/hero.png", time.frameCount() - 1)

modules/ImporterShared/writeOutcomes

writeOutcomes(paths: { string }, sinceFrame: number?, timeoutSecs: number?): { [string]: WriteOutcome }

writeOutcome for several paths written together, such as the files of one folder transfer, asked once every one of them has landed. One wait bounds them all: each path is answered as writeOutcome answers it, with whatever share of timeoutSecs is left when its turn comes, so a path whose import is still running when the wait runs out answers queued or running.

Parameters

• paths { string } — The written VFS paths, as the engine spells them (/zero/source/...).
• sinceFrame number? (optional) — The engine frame (time.frameCount()) read before the first of the writes.
• timeoutSecs number? (optional) — Max seconds to wait for all of the imports to settle (default 10).

local outcomes = ImporterShared.writeOutcomes({ "/zero/source/art/a.png", "/zero/source/art/b.png" }, since)

modules/InputBindingAssetTypeRef/README

require("@builtin::assetTypes.inputBinding.behavior") -- InputBindingAssetTypeRef

Usage: local InputBindingAssetTypeRef = require("@builtin::assetTypes.inputBinding.behavior")

modules/InputBindingAssetTypeRef/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

Generic-creation hook for asset.create("inputBinding", name, opts). Writes a record carrying every device class, so a binding is complete the moment it exists.

Parameters

• name string
• opts CreateOpts

asset.create("inputBinding", "boost", { label = "Boost", kind = "button", kbm = '{ B.key("ShiftLeft") }', gamepad = '{ B.padButton("left_shoulder") }', touch = '{ B.touchButton({ zone = "right-lower" }) }' })

modules/InputBindingAssetTypeRef/problemsWith

problemsWith(record: any, name: string): { string }

Check a binding record for the things that make it unusable, and return the problems rather than raising, so a tool can report every fault in a map at once instead of stopping at the first.

Parameters

• record any (optional) — The binding record to check.
• name string — The binding's name, for the messages.

modules/InputMacroAssetTypeRef/README

require("@builtin::assetTypes.inputMacro.behavior") -- InputMacroAssetTypeRef

Per-instance methods exposed on every AssetRef<inputMacro>. Loaded lazily by assetType.shared.ref.

Usage: local InputMacroAssetTypeRef = require("@builtin::assetTypes.inputMacro.behavior")

modules/InputMacroAssetTypeRef/getEvents

getEvents(self): { any }?

Parse events.json into a Lua table.

Parameters

• self any (optional)

local events = macroRef:getEvents()

modules/InputMacroAssetTypeRef/getEventsRaw

getEventsRaw(self): string?

Read the macro's events.json body as raw JSON text.

Parameters

• self any (optional)

local raw = macroRef:getEventsRaw()

modules/InputMacroAssetTypeRef/length

length(self): number

Number of recorded events.

Parameters

• self any (optional)

print(macroRef:length())

modules/InputMacroAssetTypeRef/replay

replay(self): number

Replay the macro by handing its recorded events to the sim toolbox's macro tool, which dispatches each timed input event through the engine input surface. Returns the number of events queued for replay.

Parameters

• self any (optional)

local n = macroRef:replay()

modules/InputMapAssetTypeRef/README

require("@builtin::assetTypes.inputMap.behavior") -- InputMapAssetTypeRef

Usage: local InputMapAssetTypeRef = require("@builtin::assetTypes.inputMap.behavior")

modules/InputMapAssetTypeRef/activateShape

activateShape(self): (string, string)

The type activate() answers for one map — a field per control it declares, each a Handle.

Parameters

• self any (optional) — The map.

local text = M.refShapes.activate(mapRef)

modules/InputMapAssetTypeRef/onChange

onChange(self, change)

Re-activate this map after a write inside the instance, so an edit to its bindings takes hold in the running session. Only the map that is currently active is re-activated; a removal is ignored.

Parameters

• self any (optional) — The changed .inputMap asset's reference.
• change any (optional) — The change record the asset dispatcher raised for the write.

modules/InputMapAssetTypeRef/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

Generic-creation hook for asset.create("inputMap", name, opts). With opts.record, bakes it into both shapes a map is read in — the "play it, bake it, tweak it" on-ramp Zin.map.bake drives.

init.luau returns the record's flat actions / axes tables, which is what Zin.map.materialize reads. Beside it, one <name>.inputBinding/ child per entry, which is what a controller subscribes to through activate(). Each child carries all three device classes, a class the baked map had nothing for written as false with the reason beside it.

A binding that fails to serialize (an unknown kind, or an axis/vector composite whose nested arm fails — the whole composite drops) is dropped from init.luau with an -- UNSERIALIZED kind: <kind> (<name>) comment line; a function-valued axis gate / curve is dropped with a -- <name>.gate omitted / -- <name>.curve omitted comment line. An entry whose name no asset folder can take, or that lost every device class, stays in init.luau alone and is named in the header comment as a control the bake could not make.

With no opts.record, contributes nothing on top of the type's template/ skeleton.

Parameters

• name string
• opts CreateOpts

Zin.map.bake("my_scheme")

modules/InspectorAppLayout/README

require("@builtin::_templates.inspector_app.inspector_app_layout") -- InspectorAppLayout

Property-inspector shell on the raw widget tree — a section header and labelled field rows (text input, slider, checkbox) whose edits update the displayed state.

Usage: local InspectorAppLayout = require("@builtin::_templates.inspector_app.inspector_app_layout")

modules/InspectorProbe/README

require("@builtin::tests.fixtures.inspector_probe") -- InspectorProbe

Helpers the Inspector suites share: walk a published edui tree for its callback ids and label texts, mount an app over a render function, render an asset's Inspector, and build one section of an asset by id.

Usage: local InspectorProbe = require("@builtin::tests.fixtures.inspector_probe")

modules/InspectorProbe/callbackIds

callbackIds(node: any): { string }

Every string-valued callback prop in a published tree, depth first.

Parameters

• node any (optional) — The tree.

local app, tree = Probe.mount(Test, function() return node end)
local ids = Probe.callbackIds(tree())

modules/InspectorProbe/dropUndoHistoryAtCleanup

dropUndoHistoryAtCleanup(Test: any)

Drop the undo history at the test's cleanup, after every cleanup registered later has run. An edit dispatched through an Inspector app is an undo step on the scratch asset the test removes, so the test ends with nothing to undo or redo. Raises naming the wait when the history is still held once the frame budget runs out.

Parameters

• Test any (optional) — The Test API.

Probe.dropUndoHistoryAtCleanup(Test)

modules/InspectorProbe/fact

fact(rows: { any }, label: string): string?

The value a fact row shows beside label: the last text of the first row whose first text is exactly label.

Parameters

• rows { any } — A section's rows.
• label string — The fact's label.

assert(Probe.fact(rows, "Splats") == "3")

modules/InspectorProbe/hasText

hasText(tree: any, needle: string): boolean

Whether any label text in tree contains needle.

Parameters

• tree any (optional) — The tree.
• needle string — Plain text to find.

local app, tree = Probe.mount(Test, function() return node end)
assert(Probe.hasText(tree(), "4 × 4"))

modules/InspectorProbe/idEndingWith

idEndingWith(tree: any, suffix: string): string

The callback id in tree ending with suffix; raises naming the ids the tree holds.

Parameters

• tree any (optional) — The tree.
• suffix string — The id's tail.

app:dispatch(Probe.idEndingWith(tree(), ":act:play"), nil)

modules/InspectorProbe/ids

ids(sections: { any }): string

The ids of sections, space-joined.

Parameters

• sections { any } — Sections.

assert(string.find(Probe.ids(sections), "texture"))

modules/InspectorProbe/mount

mount(Test: any, render: () -> any): (any, () -> any)

Mount an app whose tree is render(). At the test's cleanup the app is unmounted and then the undo history is dropped (dropUndoHistoryAtCleanup).

Parameters

• Test any (optional) — The Test API.
• render () -> any — Returns the node to publish.

Returns any) — (app, lastTree).

local app, tree = Probe.mount(Test, function() return node end)

modules/InspectorProbe/pngOf

pngOf(size: number, hex: string): string

A solid PNG of size×size pixels.

Parameters

• size number — Edge length in pixels.
• hex string — Fill colour, e.g. "#336699".

local png = Probe.pngOf(4, "#ff00ff")

modules/InspectorProbe/renderAsset

renderAsset(Test: any, ref: any): (any, () -> any)

Mount the full Inspector for ref (generic plus declared sections).

Parameters

• Test any (optional) — The Test API.
• ref any (optional) — The asset.

Returns any) — (app, lastTree).

local app, tree = Probe.renderAsset(Test, texRef)

modules/InspectorProbe/rowsHave

rowsHave(rows: { any }, needle: string): boolean

Whether any row in a section's rows contains needle in a label.

Parameters

• rows { any } — A section's rows.
• needle string — Plain text to find.

assert(Probe.rowsHave(rows, "vertices"))

modules/InspectorProbe/rowsHaveExactly

rowsHaveExactly(rows: { any }, text: string): boolean

Whether any label text in a section's rows is exactly text.

Parameters

• rows { any } — A section's rows.
• text string — The whole text.

assert(Probe.rowsHaveExactly(rows, "3"))

modules/InspectorProbe/section

section(ref: any, id: string): ({ any }, any)

Build the section id of ref's Inspector. Raises naming the ids present when id is absent, and the build problem when it fails.

Parameters

• ref any (optional) — The asset.
• id string — The section id.

local rows = Probe.section(texRef, "texture")

modules/InspectorProbe/texts

texts(node: any): { string }

Every label text in a tree, depth first.

Parameters

• node any (optional) — The tree.

local app, tree = Probe.mount(Test, function() return node end)
local all = Probe.texts(tree())

modules/InspectorProbe/texture

texture(Test: any, stem: string, size: number?, hex: string?, settings: { [string]: any }?): any

A scratch texture of size (default 4) pixels, removed at cleanup.

Parameters

• Test any (optional) — The Test API.
• stem string — Name stem.
• size number? (optional) — Edge length (default 4).
• hex string? (optional) — Fill (default "#336699").
• settings { [string]: any }? (optional) — The texture's settings, where a case needs ones other than the defaults.

local tex = Probe.texture(Test, "sectTex", nil, nil, { compression = "rgba8" })

modules/LightmapDataAssetTypeRef/README

require("@builtin::assetTypes.lightmapData.behavior") -- LightmapDataAssetTypeRef

Per-instance methods on every AssetRef<lightmapData> — the baked-lighting container the bake flow writes and component awakes read. Entries are keyed (lightmaps by entity id, probe fields by field id); each entry pairs a manifest record with a raw f32 payload file inside the container.

Usage: local LightmapDataAssetTypeRef = require("@builtin::assetTypes.lightmapData.behavior")

modules/LightmapDataAssetTypeRef/beginBatch

beginBatch(self)

Hold the manifest open across a run of writes. Each setLightmap / setProbeField still writes its payload file as it goes, but the manifest is read once here and written once by commitBatch, instead of being decoded and re-encoded per entry. A bake storing many entries into one container is the case this exists for. Re-entrant calls are ignored, and a batch left open by an error is closed by the next commitBatch.

Parameters

• self any (optional)

container:beginBatch()
for _, s in surfaces do container:setLightmap(s.id, s.meta, s.texels) end
container:commitBatch()

modules/LightmapDataAssetTypeRef/clearEntries

clearEntries(self)

Remove every entry and payload, leaving an empty manifest — the container-wide teardown baking.clear uses for a full-scene clear.

Parameters

• self any (optional)

container:clearEntries()

modules/LightmapDataAssetTypeRef/commitBatch

commitBatch(self)

Write the manifest a beginBatch has been holding and close the batch. No-op when no batch is open.

Parameters

• self any (optional)

container:commitBatch()

modules/LightmapDataAssetTypeRef/lightmap

lightmap(self, key: string): (LightmapEntry?, { number }?)

Read one entity's baked lightmap.

Parameters

• self any (optional)
• key string — The receiver entity id.

local entry, texels = container:lightmap(entityId)

modules/LightmapDataAssetTypeRef/manifest

manifest(self)

The decoded manifest: { version, lightmaps = { [entityId] = entry }, probeFields = { [fieldId] = entry } }.

Parameters

• self any (optional)

local m = container:manifest()

modules/LightmapDataAssetTypeRef/onCreate

onCreate(name: string, opts: { scene: string? }?)

Create an empty baked-lighting container. The bake flow (baking.all / Lightmap.bake / VolumeProbe.bake) fills it.

Parameters

• name string
• opts { scene: string? }? (optional)

modules/LightmapDataAssetTypeRef/probeField

probeField(self, key: string): (ProbeFieldEntry?, { number }?)

Read one probe volume's baked field.

Parameters

• self any (optional)
• key string — The volume's stable field id.

local entry, sh = container:probeField(fieldId)

modules/LightmapDataAssetTypeRef/removeLightmap

removeLightmap(self, key: string)

Remove one entity's lightmap entry and its payload file. No-op when the entry is absent.

Parameters

• self any (optional)
• key string — The receiver entity id.

container:removeLightmap(entityId)

modules/LightmapDataAssetTypeRef/removeProbeField

removeProbeField(self, key: string)

Remove one probe volume's field entry and its payload file. No-op when the entry is absent.

Parameters

• self any (optional)
• key string — The volume's stable field id.

container:removeProbeField(fieldId)

modules/LightmapDataAssetTypeRef/setLightmap

setLightmap(self, key: string, meta: { [string]: any }, texels: { number })

Store one entity's baked lightmap: writes the texel payload file and its manifest entry, replacing any prior entry under the same key.

Parameters

• self any (optional)
• key string — The receiver entity id.
• meta { [string]: any } — { resolution, intensity } — the parameters the runtime needs to rebuild the lightmap and place it in the atlas.
• texels { number } — Flat f32 RGBA texel array (resolution² × 4 floats, dilated, alpha = coverage).

container:setLightmap(entityId, { resolution = 256, intensity = 1 }, data)

modules/LightmapDataAssetTypeRef/setProbeField

setProbeField(self, key: string, meta: { [string]: any }, sh: { number })

Store one probe volume's baked field: writes the SH payload file and its manifest entry, replacing any prior entry under the same key.

Parameters

• self any (optional)
• key string — The volume's stable field id.
• meta { [string]: any } — { boundsMin = {x,y,z}, boundsMax = {x,y,z}, res = {x,y,z}, count }.
• sh { number } — Flat f32 SH L2 array — 36 floats per probe, X-fastest.

container:setProbeField(fieldId, { boundsMin = mn, boundsMax = mx, res = r, count = n }, sh)

modules/LoadingScreenAssetTypeRef/README

require("@builtin::assetTypes.loadingScreen.behavior") -- LoadingScreenAssetTypeRef

Per-instance methods for every AssetRef<loadingScreen>. Loaded lazily by asset_ref.module.

Usage: local LoadingScreenAssetTypeRef = require("@builtin::assetTypes.loadingScreen.behavior")

modules/LoadingScreenAssetTypeRef/isShown

isShown(self): boolean

Whether the world shows this screen while it loads: its settings name this asset under [world] loading_screen.

Parameters

• self any (optional)

if not screenRef:isShown() then world.loading_screen = screenRef end

modules/LoadingScreenAssetTypeRef/preview

preview(self, seconds: number?): any

Show this loading screen over the whole window exactly as a boot of the world draws it, for seconds (default 15): its pictures, colours, title, text and tips, with the progress filling and the tips changing on the screen's own clock. Capture it while it is up with capture { source = "window" }. Pass 0 to take a preview down.

Parameters

• self any (optional)
• seconds number? (optional) — How long the preview stays up (default 15; 0 takes it down).

local p = screenRef:preview(20) -- then capture { source = "window" }

modules/LoadingScreenAssetTypeRef/spec

spec(self): any

The screen this asset states, every key it leaves out at the engine's own look, and the problems that kept a key out. Pictures are paths relative to /zero/source.

Parameters

• self any (optional)

local read = screenRef:spec(); print(read.spec.title, #read.problems)

modules/LoadingScreenShared/README

require("@builtin::assetTypes.loadingScreen.shared") -- LoadingScreenShared

The rules of a loadingScreen asset: the keys screen.yaml takes, the look a screen states nothing for, how the world's settings name its loading screen, and where each picture a screen names lives in the world. The engine's boot draws from what read answers here, and the type's Inspector and ref:spec() answer from the same rules.

Usage: local LoadingScreenShared = require("@builtin::assetTypes.loadingScreen.shared")

modules/LoadingScreenShared/folderFor

folderFor(identity: any): string?

The source-relative folder of the loadingScreen asset identity names: a world asset's dotted identity (branding.title is branding/title.loadingScreen) or a built-in one (@builtin::x.y).

Parameters

• identity any (optional) — The identity [world] loading_screen holds.

modules/LoadingScreenShared/identityIn

identityIn(settingsText: any): (string?, string?)

The loading screen a .world_settings text names under [world] loading_screen.

Parameters

• settingsText any (optional) — The text of .world_settings.

modules/LoadingScreenShared/parse

parse(text: any, folder: string): (Spec, { string })

Read a screen.yaml text into the screen it states, with every key it leaves out at the default, and the problems that left a key out.

Parameters

• text any (optional) — The text of screen.yaml.
• folder string — The screen's folder relative to /zero/source, which a picture named inside it is relative to.

modules/LoadingScreenShared/read

read(read: (string) -> string?): any

The loading screen a world states, read through read: the settings name a screen, and its screen.yaml states it.

Parameters

• read (string) -> string? — A function taking a path relative to /zero/source and answering the file's text, or nil when the world holds none there.

modules/LoadingScreenShared/tipAt

tipAt(spec: Spec, elapsed: number): string?

The text one tip slot shows elapsed seconds into the load.

Parameters

• spec Spec — A screen from parse.
• elapsed number — Seconds since the screen went up.

modules/MaterialAssetTypeRef/README

require("@builtin::assetTypes.material.behavior") -- MaterialAssetTypeRef

Per-instance methods exposed on every AssetRef<material>. Loaded lazily by assetType.shared.ref via require("@builtin::assetTypes.material.behavior") the first time a material ref is touched in a VM.

Usage: local MaterialAssetTypeRef = require("@builtin::assetTypes.material.behavior")

modules/MaterialAssetTypeRef/applyToEntity

applyToEntity(self, entityId: string): boolean

Apply this material to an entity by setting the material field on its Model / SkinnedModel component (where the renderer reads it). A material only renders where there is a mesh.

Parameters

• self any (optional)
• entityId string — Target entity ID.

matRef:applyToEntity(playerId)

modules/MaterialAssetTypeRef/getDefinition

getDefinition(self): string?

Read the on-disk mat.yaml body as raw text. Use vfs.write(self.path .. "/mat.yaml", ...) to write the file directly, :setProperty / :setTexture followed by :saveDefinition to write the current values into it, or :setShader to rewrite it for a new shader.

Parameters

• self any (optional)

local yaml = matRef:getDefinition()

modules/MaterialAssetTypeRef/getShader

getShader(self): string?

Read the shader identity currently bound to this material — parses mat.yaml and returns the shader: field as a string. The result is whatever the YAML names (a built-in like "pbr", a guid, or a full identity like "@builtin::shaders.pbr"); pass it to asset.resolve(..., "shader") to get a ref.

Parameters

• self any (optional)

local s = matRef:getShader()

modules/MaterialAssetTypeRef/getShaderRef

getShaderRef(self): any?

The shader this material draws with, resolved from its shader: field read at the material's own path, so a ~ names the nearest root enclosing the material.

Parameters

• self any (optional)

local props = matRef:getShaderRef():getProperties()

modules/MaterialAssetTypeRef/getTextures

getTextures(self): { [string]: { ref: string, name: string } }

The textures bound to this material's slots: slot name -> { ref, name }, the bound texture's guid and the id the material names it by.

Parameters

• self any (optional)

for slot, t in pairs(matRef:getTextures()) do print(slot, t.name) end

modules/MaterialAssetTypeRef/isRegistered

isRegistered(self): boolean

Whether this material exists as an asset — its mat.yaml is present. Writing the asset is what registers the material, so file presence IS the registration check.

Parameters

• self any (optional)

if matRef:isRegistered() then ... end

modules/MaterialAssetTypeRef/onChange

onChange(ref, change)

Asset-type change callback: (re)register this material into the renderer's MaterialRegistry whenever its .material is seeded (a baked builtin at boot, or a world seed) or its mat.yaml is edited. This is the ONLY thing that populates the registry for a material — the legacy boot-time library loader (which registered every material by name) is gone; materials register through their own assetType exactly as shaders do (__shader.compile). Keyed by guid@checksum, the key a MaterialRef.id wears; an edit files under the new version's key and moves every wearer onto it. Convergent + idempotent: see registerToGpu.

Parameters

• ref any (optional)
• change any (optional)

modules/MaterialAssetTypeRef/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

Generic-creation hook for asset.create("material", name, opts). Pure: returns the mat.yaml content for the caller to persist to the authored destination; the write registers the material definition (CPU-side) — GPU resources are built later, only on actual use. Properties resolve from the shader's properties.yaml overlaid by these overrides; no shader compile happens at create. Flat non-reserved top-level keys on opts are shader-property overrides (e.g. base_color = {1,0,0,1}, roughness = 0.3), admitted by the open schema and resolved against the shader's properties.yaml inside the hook.

Parameters

• name string — Material identity (the instance name).
• opts CreateOpts

asset.create("material", "Gold", { shader = "pbr", base_color = {1, 0.84, 0, 1}, metallic = 1, roughness = 0.2 })
asset.create("material", "Glass", { shader = "pbr", base_color = {0.2, 0.9, 0.4, 0.45}, render = { blend = "alphaBlend", depth_write = false } })

modules/MaterialAssetTypeRef/onDelete

onDelete(ref)

Asset-type delete callback: release the renderer record a removed .material folder filed. The teardown counterpart of onChange's registration, so the type owns both halves of its runtime lifecycle the way .component does. renderer.material.destroy drops the registry entry and the bind group the renderer prepared under that key; the module's own caches for the folder go with it. A material authored afresh at the same path therefore files a new record instead of inheriting the one the removed material left, and a surface still wearing the key draws the renderer's fallback until it does.

Parameters

• ref any (optional)

modules/MaterialAssetTypeRef/previewMaterial

previewMaterial(self): { [string]: any }?

The material a surface preview paints this asset with: the material itself. ref:preview() paints it on the mesh type.yaml names under preview:.

Parameters

• self any (optional)

local surface = matRef:previewMaterial()

modules/MaterialAssetTypeRef/saveDefinition

saveDefinition(self): boolean

Persist the material's live runtime overrides into its mat.yaml (the lazy/explicit flush). Property/texture sets are frame-fast and transient by default (they live on the ref's runtime, wiped on mode change); call this to bake the current values into the asset so they survive a restart. Routes through the mat.yaml write → RegisterMaterial path. The changed values are written where they already stand in the authored file, so its comments, the order of its keys and blocks, and the spelling of the literals it was written with all survive the save.

Parameters

• self any (optional)

matRef:saveDefinition()

modules/MaterialAssetTypeRef/setProperties

setProperties(self, patch: { [string]: any }): number

Set many properties at once, resolving each key against the shader's vocabulary the way setProperty does. Entries the material's shader doesn't expose are skipped (a generic patch table won't error on shader differences). Each entry is judged and recorded the way setProperty judges and records it, so a refused entry raises and leaves its property as it was.

Parameters

• self any (optional)
• patch { [string]: any } — Table of { [propertyName] = value } pairs.

matRef:setProperties({ roughness = 0.2, metallic = 0.9 })

modules/MaterialAssetTypeRef/setShader

setShader(self, shaderRef: any): (boolean, any)

Switch this material to a different shader by rewriting the material asset itself (mat.yaml), then letting the asset-reload pipeline mark every instance dirty so the renderer repacks. The full mat.yaml is regenerated for the new shader's property vocabulary: current property values and texture links are carried across by canonical ROLE (via modules.material_remap), so MAIN_TEX→albedo→base_color_texture and friends survive the swap to our best ability. Properties the new shader does not expose are dropped; the name, builtin, parent, description, and render: block are preserved verbatim. This modifies the on-disk asset (or, in play mode, its runtime copy) — not a throwaway registry entry — so the change persists and propagates to all instances.

Parameters

• self any (optional)
• shaderRef any (optional) — An AssetRef<shader> (preferred) or a shader-identity string ("pbr", "@builtin::shaders.unlit").

matRef:setShader(asset.resolve("@builtin::shaders.unlit", "shader"))
matRef:setShader("pbr")

modules/MaterialAssetTypeRef/writeProperty

writeProperty(self, propertyName: string, value: any): (boolean, string?)

Write one property into the material's mat.yaml — the authored value, where setProperty is a runtime one. The session's own value for the property is dropped, so the material reads what the file now holds. Inside an undo operation the file write is recorded, so undoing the operation puts the previous file back. A texture-typed name routes to writeTexture, the way setProperty routes to setTexture.

Parameters

• self any (optional)
• propertyName string — Property name from the material's shader.
• value any (optional) — New value (number, bool, or a numeric array for a color/vector).

local ok, why = matRef:writeProperty("roughness", 0.2)

modules/MaterialRemap/README

require("@builtin::modules.material_remap") -- MaterialRemap

Canonical property/texture-role dictionary for cross-shader value preservation. When a material swaps shaders the new shader exposes a DIFFERENT vocabulary (one shader's MAIN_TEX is another's albedo is a third's base_color_texture). This module maps any known alias onto a canonical role so values carry across the swap "to our best ability".

Usage: local MaterialRemap = require("@builtin::modules.material_remap")

modules/MaterialRemap/canonicalizeTextures

canonicalizeTextures(

Canonicalize texture-slot names so links survive a shader swap. Each known slot is rewritten to its canonical on-disk slot name; unknown slots pass through unchanged. (The engine does not yet expose a target shader's reflected texture-slot list, so canonicalizing to the builtin convention is the best-effort path — see material_remap module header.)

modules/MaterialRemap/propertyRole

propertyRole(name: string): string?

Canonical role for a scalar/color property name, or nil when unknown.

Parameters

• name string — Property name as it appears in a shader / mat.yaml.

material_remap.propertyRole("MAIN_COLOR") -- "base_color"

modules/MaterialRemap/remapProperties

remapProperties(

Remap a table of old property values onto a target shader's accepted property names. Direct name matches win; otherwise the old key's canonical role is matched against the role of each target name. Values whose role the target shader does not expose are dropped (best-effort preservation).

modules/MaterialRemap/roleShapePair

roleShapePair(role: string): ({ colour: string, scalar: string })?

The colour+scalar role pair a role belongs to, as { colour, scalar }, or nil when the role stands alone. Both halves answer with the same pair, so a caller holding either one can ask which value shape belongs where.

Parameters

• role string — A canonical role from propertyRole.

material_remap.roleShapePair("emissive") -- { colour = "emissive", scalar = "emissive_intensity" }

modules/MaterialRemap/textureRole

textureRole(slot: string): string?

Canonical texture-slot role (and on-disk slot name) for a texture slot name, or nil when unknown.

Parameters

• slot string — Texture slot name as it appears in a shader / mat.yaml.

material_remap.textureRole("MAIN_TEX") -- "base_color_texture"

modules/MaterialSchema/README

require("@builtin::modules.material_schema") -- MaterialSchema

A shader's declared property vocabulary, and the routing of an authored key onto it. Every path that accepts material properties — the .material assetType and renderer.material.create — resolves the backing shader's properties.yaml through here, so the two agree on which keys are real, which are texture slots, and what to say about a key that is neither.

Usage: local MaterialSchema = require("@builtin::modules.material_schema")

modules/MaterialSchema/acceptsSlot

acceptsSlot(schema: Schema, slot: string): boolean

Whether a texture bound under slot reaches the bind group a schema describes: true for a slot the shader declares, and true for every slot while the schema holds no names at all (a shader whose vocabulary has not been read yet, which every write stays permissive about).

Parameters

• schema Schema — A Schema from forShader.
• slot string — The texture slot name.

if not MaterialSchema.acceptsSlot(schema, "base_color") then print("not a slot") end

modules/MaterialSchema/declaredNames

declaredNames(schema: Schema): { string }

Every name a schema declares, sorted — properties and texture slots.

Parameters

• schema Schema — A Schema from forShader.

local names = MaterialSchema.declaredNames(schema)

modules/MaterialSchema/declaredNamesList

declaredNamesList(schema: Schema): string

Comma-joined declared names, for the "not declared" diagnostic so the author sees exactly which keys the shader accepts.

Parameters

• schema Schema — A Schema from forShader.

warn("declared: " .. MaterialSchema.declaredNamesList(schema))

modules/MaterialSchema/declaredSlotsList

declaredSlotsList(schema: Schema): string

Comma-joined texture slot names a schema declares, sorted, for the diagnostic on a binding to a slot the shader does not declare.

Parameters

• schema Schema — A Schema from forShader.

warn("texture slots: " .. MaterialSchema.declaredSlotsList(schema))

modules/MaterialSchema/displacedMessage

displacedMessage(name: string, key: string, declared: string): string

The diagnostic for an authored key whose value another spelling of the same declared property took precedence over.

Parameters

• name string — The material's name or registry key.
• key string — The authored key whose value did not apply.
• declared string — The declared property that took its value from another spelling.

warn(MaterialSchema.displacedMessage(name, "emissive_color", "emissive"))

modules/MaterialSchema/forShader

forShader(shader: string): Schema?

The declared vocabulary of the shader backing a material, split into uniform properties and texture slots. Read from the shader assetType's getProperties() (its properties.yaml).

Parameters

• shader string — Shader identity, path, or short name ("pbr").

local s = MaterialSchema.forShader("pbr")

modules/MaterialSchema/isTextureSlotType

isTextureSlotType(kind: any): boolean

Whether a declared property type is a texture slot: texture (a 2D texture) and texture_array (a 2D texture array, one binding holding every layer) both bind through the material's textures.

Parameters

• kind any (optional) — The type a properties.yaml entry declares.

MaterialSchema.isTextureSlotType("texture_array") -- true

modules/MaterialSchema/isTextureValue

isTextureValue(value: any): boolean

Whether a value is a texture binding rather than a scalar/vector. A renderer.texture handle (kind == "TextureHandle") or any AssetRef<texture> envelope. Scalar/vector values are bare numbers or numeric arrays, so this never misfires on a colour like {1, 0, 0, 1}.

Parameters

• value any (optional) — The authored value.

MaterialSchema.isTextureValue(tex) -- true

modules/MaterialSchema/roleIndex

roleIndex(props: { [string]: boolean }): { [string]: string }

The role index for a set of declared property names: canonical role -> the single declared name claiming it. A role two declared names both claim is left out, so an authored spelling never resolves to an arbitrary one of them. This is what turns emissive_color into the emissive a shader declares, and ao_strength into its occlusion_strength.

Parameters

• props { [string]: boolean } — Declared property names, as a { [name]: true } set.

local byRole = MaterialSchema.roleIndex({ emissive = true })

modules/MaterialSchema/route

route(schema: Schema, key: string, value: any): (Route, string)

Resolve an authored key against a schema: which surface it belongs to and under what name. Routes by the schema's texture slots and by the value's own shape (a texture value is a texture binding whatever the key is called), then by canonical role — so a spelling from another engine's convention reaches the property this shader declares for that role, under the name the shader declares it by.

Parameters

• schema Schema — A Schema from forShader.
• key string — The authored key.
• value any (optional) — The authored value.

local route, name = MaterialSchema.route(schema, "color", {1,0,0,1})

modules/MaterialSchema/routeAll

routeAll(schema: Schema, authored: { [string]: any }): (

Route a whole authored property table at once, so two spellings that resolve to one declared property are settled the same way everywhere.

Parameters

• schema Schema — A Schema from forShader.
• authored { [string]: any } — { [key] = value } as written by the author.

local props, tex, unknown = MaterialSchema.routeAll(schema, parsed)

modules/MaterialSchema/settle

settle(schema: Schema, claimed: { Claim }): (

Settle the authored values that resolved onto declared properties, so every path that accepts material properties answers the same way. One declared name takes one value — the spelling the shader declares verbatim, else the first in key order, so the outcome is the authored table's rather than the order pairs walked it in. Two spellings meeting on one half of a colour+scalar pair the shader declares both halves of are not competing: a number is the scalar and a vector is the colour, the reading the uniform buffer already makes of them, so a material naming its glow colour under one convention and its brightness under another keeps both values.

Parameters

• schema Schema — A Schema from forShader.
• claimed { Claim } — Every Claim that routed to a property.

local props, displaced = MaterialSchema.settle(schema, claims)

modules/MaterialSchema/undeclaredMessage

undeclaredMessage(name: string, key: string, shader: string, schema: Schema): string

The diagnostic for a key the shader declares under neither surface, naming the material, the key, the shader, and the accepted vocabulary. One wording for every path that accepts material properties.

Parameters

• name string — The material's name or registry key.
• key string — The key that is not declared.
• shader string — The backing shader's name.
• schema Schema — A Schema from forShader.

warn(MaterialSchema.undeclaredMessage(name, key, shader, schema))

modules/MaterialSchema/undeclaredSlotMessage

undeclaredSlotMessage(name: string, slot: string, shader: string, schema: Schema): string

The diagnostic for a texture bound to a slot the shader does not declare, naming the material, the slot, the shader and the texture slots it declares; a slot name the shader declares as a property says so. One wording for every path that binds a material texture.

Parameters

• name string — The material's name or registry key.
• slot string — The slot that is not declared.
• shader string — The backing shader's name.
• schema Schema — A Schema from forShader.

warn(MaterialSchema.undeclaredSlotMessage(name, slot, shader, schema))

modules/MaterialSchema/valueShape

valueShape(value: any): "scalar" | "vector" | "either"

What shape an authored value has, for the one question a colour+scalar pair asks of it. A number is the scalar; a numeric array or an {r, g, b} colour is the vector. Anything else answers "either" and stays with the half its key claimed.

Parameters

• value any (optional) — The authored value.

MaterialSchema.valueShape(5) -- "scalar"

modules/MeshAssetTypeBehavior/README

require("@builtin::assetTypes.mesh.behavior") -- MeshAssetTypeBehavior

Behaviour for the mesh asset type — the disk + CPU side of the disk-asset ↔ GPU-mesh split. onCreate writes the engine-native ZMSH geometry payload as the container's data.zmsh primary; :load() decodes it into the CPU store and returns a CPU handle. Both go through the public renderer.mesh.* API — this behaviour calls no __ FFI directly.

Usage: local MeshAssetTypeBehavior = require("@builtin::assetTypes.mesh.behavior")

modules/MeshAssetTypeBehavior/getVertices

getVertices(self)

Read this mesh's vertices — one entry per vertex, { pos = {x,y,z}, normal = {x,y,z}, uv = {u,v} }. Requires the CPU copy to be resident: turn on keepCpu (meshRef:setSettings({ keepCpu = true })) for an in-use mesh. Errors loudly — naming the exact reason — rather than silently loading a transient copy.

Parameters

• self any (optional)

local verts = meshRef:getVertices()

modules/MeshAssetTypeBehavior/handle

handle(self)

Materialize this mesh asset's live GPU resource (Disk→CPU→GPU) and return its MeshHandle. The handle is cached on the interned ref's shared runtime table — its presence IS "loaded to the GPU", so once materialised every later call (and every consumer of the same asset) gets the SAME handle back directly → ONE GPU entry, no re-work. (The mode-flip runtime wipe clears the cache so a mode change re-materialises.) A component that renders a mesh holds the mesh resource and calls this internally — you rarely call it by hand.

CPU lifecycle: the keepCpu setting (:settings/:setSettings) governs whether the CPU copy survives the upload. DEFAULT (keepCpu = false): the CPU copy is dropped right after the GPU upload (the GPU handle holds no data → no double memory). keepCpu = true retains the CPU store for geometry reads/edits.

Clusters: the mesh draws through clusters from this call, on its lod0 set until its bake lands. The clusterLod setting governs how deep the bake builds. DEFAULT (clusterLod = true): the LOD hierarchy. clusterLod = false: one level of clusters, drawn at full detail.

Parameters

• self any (optional)

local h = meshRef:handle()

modules/MeshAssetTypeBehavior/instantiate

instantiate(self, target: EntityRef?, opts: { [string]: any }?): (EntityRef, { [string]: string })

Instantiate this mesh — the uniform instantiate(target?, opts?) contract every scene-instantiable asset answers to. A mesh becomes an entity carrying a Model that renders it. With target the entity spawns as a child of that owner (so an owning Asset component tears it down with its other children); with no target it is a fresh root. The base opts — position, rotation, scale, name, temporary — place the root.

Parameters

• self any (optional)
• target EntityRef? (optional) — Optional owning entity ref.
• opts { [string]: any }? (optional) — { position?, rotation?, scale?, name?, temporary? }.

meshRef:instantiate(owner)

modules/MeshAssetTypeBehavior/load

load(self)

Load this .mesh asset's geometry into the guid-keyed CPU store and return a CPU handle (the Disk→CPU step). The handle carries the guid, vertex / index counts, and per-handle geometry ops (getTriangles / getVertices / getBounds / encode / unload) that read the Rust-side store — it holds no geometry itself. Upload to the GPU with renderer.mesh.create(handle); the DEFAULT is to handle:unload() right after. Delegates to renderer.mesh.loadCpu (the sole __ caller).

Parameters

• self any (optional)

local cpu = meshRef:load(); local gpu = renderer.mesh.create(cpu); cpu:unload()

modules/MeshAssetTypeBehavior/morphTargets

morphTargets(self): { string }

The names of the shapes this mesh blends towards, in the order an entity's ecs.MorphWeights addresses them — weight i drives the target named at i. An imported model keeps the names its source file gave its blend shapes, so a face is driven by the shape it means rather than by the ordinal that shape imported at. A target the source never named reads as an empty string, and a mesh with no morph targets returns an empty array. Requires the mesh to be materialised (meshRef:handle(), or anything rendering it) — it errors loudly naming that, rather than answering as though the mesh carried no shapes.

Parameters

• self any (optional)

for i, name in meshRef:morphTargets() do print(i, name) end

modules/MeshAssetTypeBehavior/onChange

onChange(ref: any, change: { [string]: any })

React to a write inside this mesh asset. A write to the stored geometry re-uploads it into the GPU mesh registered under this asset's guid, so everything already rendering it draws the new shape. A settings write — to the declared settings.yaml values file, or a legacy .metadata block for content published before it existed — acts on whichever fields it named: keepCpu and clusterLod are lifecycle settings governing PER-ENGINE state (a CPU copy in this process's store, a cluster set on this process's GPU), so they act on an already-materialised mesh right away for EVERY origin — a synced peer's engine holds its own CPU/GPU state that the write says just as much about as the one that made it; lightmapUvs reconciles the second (lightmap) UV set — "generate" (re)creates a non-overlapping unwrap into the second UV set, "none" strips it, "keep" leaves the stored geometry untouched. The re-cook round-trips the geometry through the codec, so tangents, skinning, and the skeleton are preserved; it is the one part of this hook that WRITES persisted content, so it alone stays local-origin-only (a peer's own re-cook of the same settings would just be a second, redundant write of the same bytes the sync already delivered) and play-mode-gated (the play-lock): a setting flip never rewrites the persisted geometry while the world is running; a resident mesh re-materialises on its next fetch.

Parameters

• ref any (optional) — The AssetRef for the changed container.
• change { [string]: any } — { path, asset, kind, origin, settings, settingsChanged } — path the written file, asset the container folder, kind "edited"/"seeded", origin "local"/"remote", settings the validated values and settingsChanged what changed when path is the settings values file.

modules/MeshAssetTypeBehavior/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

Generic-creation hook for asset.create("mesh", name, opts). Pure: returns the content-file map; asset.create writes it to the authored destination, registering the .mesh asset under its minted guid. Disk-only — nothing is uploaded to the GPU here (the GPU mesh is a separate, explicit renderer.mesh.create step keyed by this asset's guid).

opts is raw geometry { positions, indices, normals?, uvs?, colors? } (flat float / u32 arrays, encoded to data.zmsh via renderer.mesh.encode), or a pre-encoded { bytes } payload (stored verbatim).

Parameters

• name string — Mesh identity (the instance name).
• opts CreateOpts

asset.create("mesh", "tree", { positions = {...}, indices = {...} })

modules/MeshAssetTypeBehavior/setSettings

setSettings(self, patch: { [string]: any })

Write a partial settings patch. The patch is checked against this type's declared schema; a violation refuses the write naming every problem. A valid write reaches onChange: keepCpu loads or drops the CPU copy, clusterLod rebakes a mesh in use at the cluster depth it now asks for — neither touches the stored geometry — and lightmapUvs re-cooks the stored geometry's second UV set (edit mode only).

Parameters

• self any (optional)
• patch { [string]: any } — Any subset of the schema's fields.

meshRef:setSettings({ keepCpu = true })

modules/MeshAssetTypeBehavior/setVertices

setVertices(self, positions)

Replace this mesh's vertex positions IN PLACE — indices, normals/uvs, and skinning are preserved, the AABB recomputes, and the edit shows on screen (the GPU re-fetches the changed CPU copy). Requires the CPU copy resident: turn on keepCpu (meshRef:setSettings({ keepCpu = true })) for an in-use mesh. Errors loudly — naming the reason — when the CPU copy isn't resident or the vertex count doesn't match.

Parameters

• self any (optional)
• positions any (optional) — One position per vertex: an array of {x,y,z} (or [x,y,z]), or a flat {x,y,z, ...} array. The count must match the mesh's vertex count.

local v = meshRef:getVertices()
local p = {}; for i, vert in ipairs(v) do p[i] = { vert.pos.x*0.01, vert.pos.y*0.01, vert.pos.z*0.01 } end
meshRef:setVertices(p)   -- scale the mesh to 1/100

modules/MeshAssetTypeBehavior/settings

settings(self): { [string]: any }

Read this mesh asset's settings, with every declared default filled in.

Parameters

• self any (optional)

if meshRef:settings().keepCpu then ... end

modules/MeshAssetTypeBehavior/settingsPending

settingsPending(self): boolean

Whether a settings change to this mesh is still reading its stored geometry. A clusterLod or keepCpu change on a mesh in use reads the geometry before it rebakes the mesh or loads its CPU copy, and where the geometry is fetched on first read that read spans frames. While it is in flight this answers true; once it answers false every settings change made so far has reached the mesh, a rebake it asked for is in renderer.mesh.clusterBakes().inFlight or has landed, and the CPU copy is as the latest keepCpu says.

Parameters

• self any (optional)

meshRef:setSettings({ clusterLod = false })
while meshRef:settingsPending() do task.wait() end

modules/ModuleAssetTypeRef/README

require("@builtin::assetTypes.module.behavior") -- ModuleAssetTypeRef

Per-instance methods exposed on every AssetRef<module>. Loaded lazily by assetType.shared.ref.

Usage: local ModuleAssetTypeRef = require("@builtin::assetTypes.module.behavior")

modules/ModuleAssetTypeRef/getExports

getExports(self): { { name: string, type: string } }?

The module's exported names and their value types — requires the module and reflects over the table it returns. Available for every module (world-authored or library), since a module is just an asset.

Parameters

• self any (optional)

for _, e in ipairs(modRef:getExports() or {}) do print(e.name, e.type) end

modules/ModuleAssetTypeRef/getInitScript

getInitScript(self): string?

Read the module's entry script as raw text.

Parameters

• self any (optional)

local src = modRef:getInitScript()

modules/ModuleAssetTypeRef/getReadme

getReadme(self): string?

Read the module's README body.

Parameters

• self any (optional)

print(modRef:getReadme())

modules/ModuleAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { exports }, where exports is parsed from the module's own entry script (getInitScript) via luau_introspect.moduleExports — name/kind/signature/desc of every top-level export, read from the source text rather than a require() reflection. Cached on the asset's content checksum, so re-inspecting unchanged source is free. A module with no readable entry script returns an empty exports list rather than erroring.

Parameters

• self any (optional)

local exports = asset.inspect(modRef).detail.exports

modules/ModuleAssetTypeRef/loadModule

loadModule(self): any

Require the module: the same module require(self.identity) answers from the world's own code, for a world module and a library one alike. A load failure raises a Luau error tagged with the module identity rather than propagating the raw error.

Parameters

• self any (optional)

local mod = modRef:loadModule()

modules/ModuleAssetTypeRef/onChange

onChange(ref, change)

Asset-type change callback: hot-reload this module whenever a .luau / .lua file inside it is edited (or the module is seeded). A user module reloads here; a library module has already reloaded through the VFS write hook by the time this runs, and the reload here finds its source unchanged. Mirrors the .material / .shader assetTypes owning their own reload. Convergent: the reload only invalidates the require() cache + fires watchers and never writes back into the asset folder.

Parameters

• ref any (optional)
• change any (optional)

modules/ModuleAssetTypeRef/onRegister

onRegister(self)

Initial-registration callback: register every .luau / .lua file this module owns — its entry AND its plain-file submodules — into the require() layer, so require("<mod>.<sub>") resolves the instant it first registers (fired before the world entrypoint runs). A .luau inside a NESTED typed-asset folder (a nested .module / .component / …) belongs to that asset and registers through its own onRegister, so it is skipped here.

Parameters

• self any (optional) — The per-instance AssetRef<module>.

-- driven by the assetType lifecycle; not called directly

modules/NodeboxAssetTypeRef/README

require("@builtin::systems.procgen.nodebox.behavior") -- NodeboxAssetTypeRef

Per-instance methods exposed on every AssetRef<nodebox>.

Usage: local NodeboxAssetTypeRef = require("@builtin::systems.procgen.nodebox.behavior")

modules/NodeboxAssetTypeRef/getReadme

getReadme(self): string?

Read the nodebox's README.md body.

Parameters

• self any (optional)

print(boxRef:getReadme())

modules/NodeboxAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { nodes }, each { name, call, desc } where call is the name a graph calls the node by (<box>.<node>).

Parameters

• self any (optional)

local nodes = asset.inspect(boxRef).detail.nodes

modules/NodeboxAssetTypeRef/listNodes

listNodes(self): { any }

List the node refs the box holds, each an AssetRef<procNode>.

Parameters

• self any (optional)

for _, n in ipairs(boxRef:listNodes()) do print(n.identity) end

modules/OpenVDB/README

require("@builtin::plugins.openvdb.surface") -- OpenVDB

OpenVDB, as a dense voxel grid: the .vdb importer's parser.

Usage: local OpenVDB = require("@builtin::plugins.openvdb.surface")

modules/OpenVDB/parse

parse(vdb: string | buffer)

Parse a .vdb file's bytes into a dense RGBA8 voxel grid.

Parameters

• vdb string | buffer — The file's bytes, as a string or a buffer.

modules/PackageAssetTypeRef/README

require("@builtin::assetTypes.package.behavior") -- PackageAssetTypeRef

Per-instance methods exposed on every AssetRef<package>. Loaded lazily by assetType.shared.ref.

Usage: local PackageAssetTypeRef = require("@builtin::assetTypes.package.behavior")

modules/PackageAssetTypeRef/getDefinition

getDefinition(self): string?

Read the package's package.yaml body as raw text.

Parameters

• self any (optional)

local raw = packageRef:getDefinition()

modules/PackageAssetTypeRef/getReadme

getReadme(self): string?

Read the package's README body.

Parameters

• self any (optional)

print(packageRef:getReadme())

modules/PackageAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { contents }, where contents is { {name, type}, ... } sorted by name — the package's own direct children (components, modules, tools, docs), enumerated via vfs.list against the package's own path. Never reads/executes any child's content.

Parameters

• self any (optional)

local contents = asset.inspect(packageRef).detail.contents

modules/PackageAssetTypeRef/listContents

listContents(self): { { name: string, isDirectory: boolean } }

List the package's child entries — every VFS entry one level below the package root. Use this to enumerate components, modules, tools, etc. shipped by the package.

Parameters

• self any (optional)

for _, e in ipairs(packageRef:listContents()) do print(e.name) end

modules/Particles.Curves/ColorSequence.new

ColorSequence.new(a, b?) -> ColorSequence

Three shapes: constant ({r,g,b}), two-point lerp (startColor, endColor), or keypoint table ({ {time=, value={r,g,b,a?}, envelope={r,g,b}?}, ... }).

Parameters

• a any (optional)
• b any (optional)

Returns ColorSequence

modules/Particles.Curves/ColorSequence:evaluate

ColorSequence:evaluate(t: number) -> (r, g, b, a)

Deterministic per-channel sample.

Parameters

• t number

Returns (r, g, b, a)

modules/Particles.Curves/ColorSequence:getKeypoints

ColorSequence:getKeypoints() -> {table}

Returns a fresh array of { time, value = {r,g,b,a}, envelope = {r,g,b} }.

Returns {table}

modules/Particles.Curves/ColorSequence:pack

ColorSequence:pack(buffer: {number}, offset: number) -> number

Pack the color curve into a flat float array; returns the next-write offset.

Parameters

• buffer {number}
• offset number

Returns number

modules/Particles.Curves/ColorSequence:sample

ColorSequence:sample(t: number, rng?: number) -> (r, g, b, a)

Sample with per-channel RGB envelope randomness (alpha is deterministic).

Parameters

• t number
• rng number (optional)

Returns (r, g, b, a)

modules/Particles.Curves/NumberSequence.new

NumberSequence.new(a, b?) -> NumberSequence

Three shapes: constant (value), two-point lerp (start, end), or keypoint list ({ {time=, value=, envelope=}, ... }), whose entries also read positionally as ({ {time, value[, envelope]}, ... }). A field that is not a number is refused at the call.

Parameters

• a any (optional)
• b any (optional)

Returns NumberSequence

modules/Particles.Curves/NumberSequence:evaluate

NumberSequence:evaluate(t: number) -> number

Deterministic interpolation at life-fraction t in [0, 1].

Parameters

• t number

Returns number

modules/Particles.Curves/NumberSequence:getKeypoints

NumberSequence:getKeypoints() -> {table}

Returns a fresh array of { time, value, envelope } entries.

Returns {table}

modules/Particles.Curves/NumberSequence:pack

NumberSequence:pack(buffer: {number}, offset: number) -> number

Pack the curve into a flat float array; returns the next-write offset.

Parameters

• buffer {number}
• offset number

Returns number

modules/Particles.Curves/NumberSequence:sample

NumberSequence:sample(t: number, rng?: number) -> number

Envelope-randomized sample; rng (in [0, 1]) seeds the jitter.

Parameters

• t number
• rng number (optional)

Returns number

modules/Particles.Curves/README

require("@builtin::deprecated.deprecatedParticles.curves") -- Particles.Curves

NumberSequence and ColorSequence — keyframe curves for VFX properties.

Animatable keyframe curves used by the particle system. Modelled on Roblox's NumberSequence / ColorSequence so the muscle memory carries over, with two differences:

1. Up to 16 keypoints (Roblox caps at 20; we cap a bit lower so the GPU pack fits in a fixed-size param block).
2. ColorSequence supports per-channel envelope (RGB) — Roblox does not. Curves are immutable plain tables with a metatable. Build once, sample many times. The shader-side pack format is a flat float array — see NumberSequence.pack / ColorSequence.pack for the contract. Usage: local size = NumberSequence.new({ { time = 0.0, value = 0.1 }, { time = 0.3, value = 1.0, envelope = 0.2 }, { time = 1.0, value = 0.0 }, }) print(size:evaluate(0.5)) -- deterministic interpolation print(size:sample(0.5)) -- envelope randomness applied local color = ColorSequence.new( { 1, 0.8, 0.2 }, -- yellow { 1, 0.1, 0.0 } -- red )

Usage: local Particles.Curves = require("@builtin::deprecated.deprecatedParticles.curves")

modules/Particles.Curves/isColorSequence

isColorSequence(x: any) -> boolean

True if x is a ColorSequence answering the calls one takes. A sequence that crossed a boundary preserving only its fields has its methods put back, so the value a caller tests is one it can go on to sample.

Parameters

• x any (optional)

Returns boolean

modules/Particles.Curves/isNumberSequence

isNumberSequence(x: any) -> boolean

True if x is a NumberSequence answering the calls one takes. A sequence that crossed a boundary preserving only its fields has its methods put back, so the value a caller tests is one it can go on to sample.

Parameters

• x any (optional)

Returns boolean

modules/Particles.Curves/new

new(a: any, b: any?): any

Parameters

• a any (optional)
• b any? (optional)

NumberSequence.new(1.0)
NumberSequence.new(0.0, 1.0)
NumberSequence.new({ {time=0,value=0}, {time=1,value=1,envelope=0.1} })
NumberSequence.new({ {0, 0}, {1, 1, 0.1} })

modules/Particles.Meshes/README

require("@builtin::deprecated.deprecatedParticles.meshes") -- Particles.Meshes

Built-in source-mesh templates for mesh particles.

Source-mesh geometries for the mesh-particle path of the particle system. Each built-in returns a table with positions (flat xyz array), normals (flat xyz array), uvs (flat uv array), and indices (flat u32 array) — the shape particles.create expects under its mesh field. Built-in kinds: "cube" — 24 verts × 36 indices (face-normalled box) "octahedron" — 24 verts × 24 indices (face-normalled octahedron) "tetrahedron" — 12 verts × 12 indices (face-normalled tetrahedron) "plane" — 4 verts × 6 indices (axis-aligned XY quad) Custom geometry: Pass mesh = { positions = {...}, normals = {...}, uvs = {...}, indices = {...} } directly to particles.create. The module also accepts an asset ref (assetRef("identity", "mesh")) but resolution happens through the engine's asset system — the fast path is built-in kinds.

Usage: local Particles.Meshes = require("@builtin::deprecated.deprecatedParticles.meshes")

modules/Particles.Meshes/list

list() -> {string}

Returns the built-in mesh kind names.

Returns {string}

modules/Particles.Meshes/resolve

resolve(spec: string | table) -> table

Resolve a mesh spec to { positions, normals, uvs, indices }. Spec is one of "cube" | "octahedron" | "tetrahedron" | "plane", or a custom { positions, normals, uvs?, indices } table.

Parameters

• spec string | table

Returns table

modules/Particles.Shapes/README

require("@builtin::deprecated.deprecatedParticles.shapes") -- Particles.Shapes

Emission-shape samplers — CPU-side, called at spawn time.

Spawn positions and initial velocity directions for the standard emission shapes. CPU sampling is fine here because it runs at most N times per frame where N = emission rate, not N = active particle count — and the math is trivial. Shapes (matching Roblox naming): point — emit from origin box — Volume / Surface sphere — Volume / Surface, partial = hemisphere cap cylinder — Volume / Surface, axis = Y disc — Surface (XZ plane), partial = annulus inner radius cone — Surface, partial = half-angle Styles: "volume" — uniform inside the shape "surface" — uniform on the shape's boundary inOut (determines initial velocity direction): "outward" — surface-normal outward "inward" — surface-normal inward "inandout" — random sign per particle

Usage: local Particles.Shapes = require("@builtin::deprecated.deprecatedParticles.shapes")

modules/Particles.Shapes/frame

frame(ax: number, ay: number, az: number): (number, number, number, number, number, number, number, number, number)

Build an orthonormal frame whose middle axis is the given direction. Shape samplers emit around a local +Y axis; this frame maps those local samples into world space so emission can be aimed along any vector. Returns 9 numbers — right, axis, forward — for allocation-free use in per-particle loops: world = local.x * right + local.y * axis + local.z * forward. The frame is the shortest rotation that turns +Y onto the direction, so the local X and Z axes keep as close to world X and Z as the turn allows: a direction along +X or -X turns about Z and keeps Z, one along +Z or -Z turns about X and keeps X, and -Y is the half turn about X. A zero-length or +Y direction returns the exact identity frame.

Parameters

• ax number — Direction X (any length; normalized internally).
• ay number — Direction Y.
• az number — Direction Z.

local rx, ry, rz, ax2, ay2, az2, fx, fy, fz = Shapes.frame(0, 0, -1)

modules/Particles.Shapes/inOuts

inOuts() -> {string}

Returns the directions a sample aims in — outward, inward, inandout.

Returns {string}

modules/Particles.Shapes/sample

sample(shape: string, opts: table) -> (px, py, pz, dx, dy, dz)

Sample one spawn position + unit direction from the named shape. opts: { size = {x,y,z}, style = "volume"|"surface", inOut = "outward"|"inward"|"inandout", partial = number, spreadAngle = degrees }.

Parameters

• shape string
• opts table

Returns (px, py, pz, dx, dy, dz)

modules/Particles.Shapes/shapes

shapes() -> {string}

Returns the supported shape names — point, box, sphere, cylinder, disc, cone.

Returns {string}

modules/Particles.Shapes/styles

styles() -> {string}

Returns the fill styles a shape is sampled with — volume, surface.

Returns {string}

modules/Particles.spawnBatches/README

require("@builtin::deprecated.deprecatedParticles.engine.spawnBatches") -- Particles.spawnBatches

The spawn batches an emitter keeps, as a min-heap on the clock each batch leaves the live bound at, and the count of particles they can still hold alive.

Usage: local Particles.spawnBatches = require("@builtin::deprecated.deprecatedParticles.engine.spawnBatches")

modules/Particles.spec/README

require("@builtin::deprecated.deprecatedParticles.engine.spec") -- Particles.spec

How the particle system reads an emitter spec: each field's value checked against the shapes it takes (a range, a size, a curve, a colour sequence, bursts, a direction, a number, a boolean, an enum, a vector, a table), with the refusal reported at the call that wrote it.

Usage: local Particles.spec = require("@builtin::deprecated.deprecatedParticles.engine.spec")

modules/Particles/M.list

M.list() -> {ParticleSystem}

Every live particle system this VM has created, newest last.

Returns {ParticleSystem}

modules/Particles/M.observe

M.observe(system: ParticleSystem?) -> table

One emitter's document, or — with no argument — the whole world's: { emitters, count, alive, capacity, spawned, silent, bytes, frame }.

Parameters

• system ParticleSystem? (optional)

Returns table

modules/Particles/M.silenceReasons

M.silenceReasons() -> table

The closed set of reasons an emitter can be producing nothing, in the order they are resolved, each with what it means.

Returns table

modules/Particles/M.whySilent

M.whySilent(system: ParticleSystem) -> (string?, string?)

The reason one emitter is producing nothing and the detail line naming what it is about, or nil when it is producing.

Parameters

• system ParticleSystem

Returns (string?, string?)

modules/Particles/ParticleSystem:billboard

ParticleSystem:billboard(): { [string]: any }

The camera frame this emitter's geometry was last built against: which camera supplied it, the world point it was read at, the right/up pair, and the direction that pair faces.

A sprite is a flat card placed in the compute pass against ONE camera frame, so a view looking along normal sees it face-on and a view looking across normal sees its edge. A mesh emitter spins each copy about the axis running from it to position. When a frame drawn from somewhere else shows an emitter that every count reports as producing, this is the reading that says where its geometry is turned, and means names which part of the frame this emitter's kind builds from.

local b = sys:billboard(); print(b.source, b.normal[1], b.normal[2], b.normal[3])

modules/Particles/ParticleSystem:clear

ParticleSystem:clear()

Kill every live particle by re-zeroing the state buffer, and take them out of the frame on the same call.

modules/Particles/ParticleSystem:destroy

ParticleSystem:destroy()

Release every GPU buffer and the render entity. Idempotent.

modules/Particles/ParticleSystem:emit

ParticleSystem:emit(count: number)

One-shot burst of N particles, independent of rate / enabled.

Parameters

• count number

modules/Particles/ParticleSystem:getActiveCount

ParticleSystem:getActiveCount() -> number

How many particles are alive right now: the slots whose lifetime has not elapsed under the simulated time this emitter's dispatches have advanced. Falls to 0 when the last particle ages out.

Returns number

modules/Particles/ParticleSystem:getCastsShadows

ParticleSystem:getCastsShadows(): boolean

Whether this emitter's particles block light.

print(debris:getCastsShadows())

modules/Particles/ParticleSystem:getColliders

ParticleSystem:getColliders(): { any }

The colliders currently in force, in the shape setColliders takes — so what comes out of one goes back into the other.

local n = #sys:getColliders()

modules/Particles/ParticleSystem:getCreator

ParticleSystem:getCreator(): { [string]: any }

Whose this emitter is. owner and name are the keys its creator stated on the spec, and source and line are the code that made the call, read off the stack — so an emitter nobody tagged still names the module it came from. actor is the caller the creating call was attributed to and actorName the ZeroMind account it authenticated as, and createdAt is when the emitter was made, which orders two emitters one creator built across separate loads.

local who = sys:getCreator(); print(who.owner, who.source, who.line)

modules/Particles/ParticleSystem:getDepthFade

ParticleSystem:getDepthFade() -> number

That distance.

Returns number

modules/Particles/ParticleSystem:getGpuBytes

ParticleSystem:getGpuBytes() -> table

Every GPU buffer this emitter holds, by name, plus their total.

Returns table

modules/Particles/ParticleSystem:getLightEmission

ParticleSystem:getLightEmission() -> number

That share.

Returns number

modules/Particles/ParticleSystem:getLightInfluence

ParticleSystem:getLightInfluence() -> number

That share.

Returns number

modules/Particles/ParticleSystem:getMaxCount

ParticleSystem:getMaxCount() -> number

Buffer cap.

Returns number

modules/Particles/ParticleSystem:getRenderEntity

ParticleSystem:getRenderEntity() -> string?

Entity id of the renderable a sprite emitter spawns at world origin; nil for a mesh emitter, which draws as a GPU population instead.

Returns string?

modules/Particles/ParticleSystem:getRenderLayer

ParticleSystem:getRenderLayer(): string

The render layers this emitter's particles draw on, as the space-separated name string every render-layer surface speaks.

print(smoke:getRenderLayer())

modules/Particles/ParticleSystem:getSimulatedTime

ParticleSystem:getSimulatedTime() -> number

Seconds of simulation this emitter's dispatches have advanced. Every particle's age is measured against this clock.

Returns number

modules/Particles/ParticleSystem:getSpawnedCount

ParticleSystem:getSpawnedCount() -> number

How many slots the emitter has filled since the last clear(), saturating at maxCount. The emission schedule's own total, and the span the draw covers.

Returns number

modules/Particles/ParticleSystem:isPlaying

ParticleSystem:isPlaying() -> boolean

True while the timeline emits: enabled, past delay, and inside duration (or looping / untimed).

Returns boolean

modules/Particles/ParticleSystem:isSorted

ParticleSystem:isSorted() -> boolean

Whether this emitter reorders its own particles back to front every frame.

Returns boolean

modules/Particles/ParticleSystem:isVisible

ParticleSystem:isVisible() -> boolean

Whether the emitter's population reaches the frame.

Returns boolean

modules/Particles/ParticleSystem:observe

ParticleSystem:observe() -> table

Everything the engine holds for this emitter in one document: population, capacity, timeline, GPU bytes, render-side liveness, the GPU's own confirmation of the population, and — when it is producing nothing — the reason from a closed set.

Returns table

modules/Particles/ParticleSystem:play

ParticleSystem:play(restart?: boolean)

Start (or re-arm) the emission timeline: resets the clock to -delay, re-arms scheduled bursts, and enables emission. restart = true also clears live particles.

Parameters

• restart boolean (optional)

modules/Particles/ParticleSystem:requestCensus

ParticleSystem:requestCensus()

Ask the GPU to count its own live slots on the next dispatch. The answer arrives on a later frame and reads back through observe().confirmation.

modules/Particles/ParticleSystem:setAcceleration

ParticleSystem:setAcceleration(x, y, z: number)

Set the constant acceleration vector (combined with gravity + wind).

Parameters

• x any (optional)
• y any (optional)
• z number

modules/Particles/ParticleSystem:setBlendMode

ParticleSystem:setBlendMode(mode: string)

"alpha" (default) or "additive".

Parameters

• mode string

modules/Particles/ParticleSystem:setBursts

ParticleSystem:setBursts(bursts: table)

Replace the scheduled-burst list ({ {time, count}, ... }); nil/empty removes the schedule.

Parameters

• bursts table

modules/Particles/ParticleSystem:setCastsShadows

ParticleSystem:setCastsShadows(on: boolean?)

State whether this emitter's particles block light. A caster is drawn into the shadow map as the geometry it is — a sprite emitter's quads as quads, a mesh emitter's copies as copies — and the surfaces behind it are shaded in shadow. The declaration reaches both emitter kinds, so it means the same thing whichever one carries it.

Parameters

• on boolean? (optional) — true to block light, false to let it through. Omitted, the emitter goes back to the default, which is letting it through.

debris:setCastsShadows(true)

modules/Particles/ParticleSystem:setColliders

ParticleSystem:setColliders(colliders: { any }?): number

Replace the shapes this emitter's particles collide against. Each entry is { kind = "plane" | "sphere" | "box" | "world", position = {x,y,z}, ... } — a plane also takes normal, a sphere radius, a box halfExtents. A world entry is the scene's own geometry, read from the distance field sceneProxy builds: it takes only radius, how far from a surface a particle counts as touching it. At most 8 are carried; the rest are dropped and reported.

Parameters

• colliders { any }? (optional) — Array of collider descriptions.

sys:setColliders({ { kind = "world" } })

modules/Particles/ParticleSystem:setCollision

ParticleSystem:setCollision(mode: string?, opts: { [string]: any }?)

Choose what a particle does when it meets a collider.

Parameters

• mode string? (optional) — "off", "bounce", "stop" or "kill".
• opts { [string]: any }? (optional) — Optional { restitution, friction }. restitution is how much normal speed survives a bounce, friction how much tangential speed is lost on contact — both in [0, 1].

sys:setCollision("bounce", { restitution = 0.5, friction = 0.3 })

modules/Particles/ParticleSystem:setColor

ParticleSystem:setColor(value: ColorSequence | {number})

Per-particle color curve. A {number} array {r, g, b} is read as a constant color, and a list of such arrays as a ramp through them.

Parameters

• value ColorSequence | {number}

modules/Particles/ParticleSystem:setDepthFade

ParticleSystem:setDepthFade(distance: number)

Set the distance, in world units, over which this emitter's particles dissolve into the surface drawn behind them. 0 turns the fade off.

Parameters

• distance number

modules/Particles/ParticleSystem:setDirection

ParticleSystem:setDirection(x, y, z: number)

Aim emission: the shape's local +Y axis maps onto this world-space vector (positions and initial velocities both rotate). Pass nil to reset to the native +Y frame.

Parameters

• x any (optional)
• y any (optional)
• z number

modules/Particles/ParticleSystem:setDrag

ParticleSystem:setDrag(d: number)

Set the velocity damping factor (per-second exponential decay).

Parameters

• d number

modules/Particles/ParticleSystem:setEnabled

ParticleSystem:setEnabled(b: boolean)

Pause / resume continuous emission. Does not kill live particles.

Parameters

• b boolean

modules/Particles/ParticleSystem:setGravity

ParticleSystem:setGravity(x, y, z: number)

Set the gravity vector (m/s^2). Default {0, -9.81, 0}.

Parameters

• x any (optional)
• y any (optional)
• z number

modules/Particles/ParticleSystem:setLifetime

ParticleSystem:setLifetime(min: number, max?: number)

Per-particle lifetime range in seconds.

Parameters

• min number
• max number (optional)

modules/Particles/ParticleSystem:setLightEmission

ParticleSystem:setLightEmission(share: number)

How much of itself each particle emits whatever the scene's light is, from 0 to 1. At 1 a particle is self-illuminated.

Parameters

• share number

modules/Particles/ParticleSystem:setLightInfluence

ParticleSystem:setLightInfluence(share: number)

How much of the scene's light these particles take, from 0 to 1.

Parameters

• share number

modules/Particles/ParticleSystem:setLook

ParticleSystem:setLook(look: string)

Parameters

• look string — One of the eight look names.

sys:setLook("glow")

modules/Particles/ParticleSystem:setMaterial

ParticleSystem:setMaterial(materialName: string)

Replace the material applied to the render entity entirely.

Parameters

• materialName string

modules/Particles/ParticleSystem:setOrientation

ParticleSystem:setOrientation(mode: string)

"FacingCamera" | "FacingCameraWorldUp" | "VelocityParallel" | "VelocityPerpendicular".

Parameters

• mode string

modules/Particles/ParticleSystem:setOrigin

ParticleSystem:setOrigin(x, y, z: number)

Move the emitter to a new world-space origin.

Parameters

• x any (optional)
• y any (optional)
• z number

modules/Particles/ParticleSystem:setParam

ParticleSystem:setParam(name: string, value: number)

Generic setter — matches PARAM_LAYOUT keys or "user" for the user block.

Parameters

• name string
• value number

modules/Particles/ParticleSystem:setRate

ParticleSystem:setRate(r: number)

Set continuous emission rate (particles/sec).

Parameters

• r number

modules/Particles/ParticleSystem:setRenderLayer

ParticleSystem:setRenderLayer(layers: any)

Put this emitter's particles on named render layers. A camera or a capture including the layer draws them and one excluding it does not, so a reflection probe, a portal camera, a minimap or a clean screenshot can take the scene with the emitter's effect in it or without. The layers reach both emitter kinds.

Parameters

• layers any (optional) — A layer name, an array of names, or a space-separated string. Omitted, the emitter goes back to the default layer.

smoke:setRenderLayer("vfx")

modules/Particles/ParticleSystem:setRotSpeed

ParticleSystem:setRotSpeed(min: number, max?: number)

Per-particle rotation-speed range (degrees/sec).

Parameters

• min number
• max number (optional)

modules/Particles/ParticleSystem:setRotSpeedCurve

ParticleSystem:setRotSpeedCurve(value: NumberSequence | number | {start, finish} | {table})

Rotation-speed curve — multiplies each particle's own rotSpeed across its life. Written the same four ways as the transparency curve.

Parameters

• value NumberSequence | number | {start, finish} | {table}

modules/Particles/ParticleSystem:setRotation

ParticleSystem:setRotation(min: number, max?: number)

Per-particle initial rotation range (degrees).

Parameters

• min number
• max number (optional)

modules/Particles/ParticleSystem:setShape

ParticleSystem:setShape(opts: table)

Replace the emission shape — { kind, size, style, inOut, partial, spreadAngle } (any subset). Existing values are kept for omitted fields.

Parameters

• opts table

modules/Particles/ParticleSystem:setSize

ParticleSystem:setSize(value: NumberSequence | number | {min, max} | {table})

Size, read the way create reads its size: a curve — a NumberSequence or the keypoint list {{time, value, envelope?}, ...} one is built from — is sampled per particle every frame on the GPU over base 1, and a number or {min, max} pair is the base each spawn samples under a constant curve of 1. Either way a particle draws at the size that was written.

Parameters

• value NumberSequence | number | {min, max} | {table}

modules/Particles/ParticleSystem:setSorted

ParticleSystem:setSorted(on: boolean?)

State whether this emitter reorders its own particles back to front every frame. nil hands the choice back to the blend mode.

Parameters

• on boolean? (optional)

modules/Particles/ParticleSystem:setSpeed

ParticleSystem:setSpeed(min: number, max?: number)

Per-particle initial-speed range.

Parameters

• min number
• max number (optional)

modules/Particles/ParticleSystem:setSquash

ParticleSystem:setSquash(value: NumberSequence | number | {start, finish} | {table})

X-dimension scale curve (>1 stretches, <1 squashes). Written the same four ways as the transparency curve.

Parameters

• value NumberSequence | number | {start, finish} | {table}

modules/Particles/ParticleSystem:setTexture

ParticleSystem:setTexture(texture: string)

Set the sprite texture (asset id or VFS path).

Parameters

• texture string

modules/Particles/ParticleSystem:setTransparency

ParticleSystem:setTransparency(value: NumberSequence | number | {start, finish} | {table})

Transparency curve (0 = opaque, 1 = invisible). A {start, finish} pair of numbers is read as a two-stop ramp — a table holding one number as that value across the whole life — and a keypoint list as the curve through its stops.

Parameters

• value NumberSequence | number | {start, finish} | {table}

modules/Particles/ParticleSystem:setUserParam

ParticleSystem:setUserParam(index: number, value: number)

Write one slot (1..32) of the 32-float user param block. Custom WGSL update shaders read these at params[31 + index].

Parameters

• index number
• value number

modules/Particles/ParticleSystem:setVisible

ParticleSystem:setVisible(on: boolean)

Whether the population the emitter holds reaches the frame. Emission is setEnabled; the draw is this, and a hidden emitter keeps its particles.

Parameters

• on boolean

modules/Particles/ParticleSystem:setWind

ParticleSystem:setWind(x, y, z: number)

Set the wind vector (m/s).

Parameters

• x any (optional)
• y any (optional)
• z number

modules/Particles/ParticleSystem:simulate

ParticleSystem:simulate(t: number, stepDt?: number)

Deterministically advance the system by t seconds in fixed steps (default 1/60). Drives the full update — timeline, bursts, compute passes — so a system can be prewarmed or scrubbed to a known state.

Parameters

• t number
• stepDt number (optional)

modules/Particles/ParticleSystem:stop

ParticleSystem:stop(clearParticles?: boolean)

Stop emitting. Live particles finish their lifetime unless clearParticles = true.

Parameters

• clearParticles boolean (optional)

modules/Particles/ParticleSystem:update

ParticleSystem:update(dt: number)

Step the simulation. Drives continuous emission, dispatches the compute update pass, and re-packs per-frame uniforms. Call once per frame.

Parameters

• dt number

modules/Particles/README

require("@builtin::deprecated.deprecatedParticles.engine") -- Particles

Generic GPU-driven particle system — compute-shader simulation, zero-copy rendering.

A generic GPU particle substrate for VFX. Every active particle lives in a GPU storage buffer; the simulation runs entirely as compute dispatches; the per-frame vertex output is consumed directly by the renderer via renderer.mesh.create (no readback, no CPU re-upload). Spawning happens on the CPU (the bookkeeping cost is bounded by emission rate, not particle count) and writes new particle slots straight into the GPU state buffer. The module is one-stop: the high-level ParticleEmitter component declared elsewhere in src/lua/lib/components/ is a thin wrapper around this API. Usage: local particles = require("@builtin::deprecated.deprecatedParticles.engine") local fire = particles.create({ maxCount = 2000, rate = 100, -- particles/sec lifetime = { 0.8, 1.6 }, speed = { 2.5, 4.0 }, shape = { kind = "cone", size = {1, 1, 1}, partial = 0.3 }, gravity = { 0, 1.5, 0 }, -- buoyant drag = 0.6, size = NumberSequence.new({ { time = 0, value = 0.4 }, { time = 0.3, value = 1.0, envelope = 0.2 }, { time = 1, value = 0.0 }, }), color = ColorSequence.new({ 1, 0.9, 0.3 }, { 0.8, 0.1, 0 }), transparency = NumberSequence.new(0, 1), texture = "@builtin::textures.fire_sprite", blendMode = "additive", }) -- Each frame: fire:setOrigin(torch.position.x, torch.position.y, torch.position.z) fire:update(dt) See references/luau-cookbook.md#particles (zero-engine skill) for more recipes — explosion bursts, magic swirls, custom WGSL update injection.

Usage: local Particles = require("@builtin::deprecated.deprecatedParticles.engine")

modules/Particles/create

create(spec: table) -> ParticleSystem

Allocate a new particle system: GPU buffers, registered compute shader, renderer.mesh.create-wrapped renderable. See the about block for the full spec field list. Returns a handle whose methods are summarised below.

Parameters

• spec table

Returns ParticleSystem

modules/Particles/list

list(filter: any?): { any }

Every particle system this VM has created and not destroyed, in creation order — or, given a filter, the ones whose creator matches it. An emitter is something this module made, so the list is answered from its own registry rather than by walking entities.

Called with nothing it answers with every emitter in the VM, which is what makes it the way to reach one whose creator has lost its handle, and :getCreator() on an entry says whose that one is. A filter narrows it to one creator's own, so a module sweeps what it left behind on a previous load without touching anybody else's.

Parameters

• filter any? (optional) — Optional. A string matches the owner key a creator stated; a table matches every one of owner, name and source that it names.

for _, sys in ipairs(Particles.list()) do print(sys:getActiveCount()) end
for _, sys in ipairs(Particles.list("starfield")) do sys:destroy() end

modules/Particles/observe

observe(system: any?): { [string]: any }

One emitter's reading, or — called with no argument — the whole world's: every live emitter's document plus the totals they sum to. An engine with no emitters answers count = 0 with an empty list, which reads differently from an engine whose emitters are all silent.

Parameters

• system any? (optional) — Optional ParticleSystem to read; omitted, every live one.

local world = Particles.observe(); print(world.alive, world.silent)

modules/Particles/silenceReasons

silenceReasons(): { { reason: string, means: string } }

The closed set of reasons an emitter can be producing nothing, in the order a reading resolves them — nearest cause first — each with what it means. Every observe().reason is one of these.

for _, r in ipairs(Particles.silenceReasons()) do print(r.reason, r.means) end

modules/Particles/whySilent

whySilent(system: any): (string?, string?)

Why one emitter is producing nothing, from the closed set silenceReasons() enumerates — or nil when it is producing. The second return is the detail line naming what the reason is about.

Parameters

• system any (optional) — The particle system to ask about.

local why, detail = Particles.whySilent(fire)

modules/PluginAssetTypeRef/README

require("@builtin::assetTypes.plugin.behavior") -- PluginAssetTypeRef

The lifecycle of every AssetRef<plugin>: onCreate makes one, registering loads it, and a change to its component or manifest loads it again in place.

Usage: local PluginAssetTypeRef = require("@builtin::assetTypes.plugin.behavior")

modules/PluginAssetTypeRef/doSomething

doSomething(input: string): any

What doSomething does.

Parameters

• input string — What the caller passes.

local answer = await({name}.doSomething("x"))

modules/PluginAssetTypeRef/onChange

onChange(self, change)

Load the plugin again when its component or its manifest changes.

Parameters

• self any (optional) — The AssetRef<plugin> whose files changed.
• change any (optional) — { path, kind, origin } describing the write.

modules/PluginAssetTypeRef/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

Make a new plugin asset: its manifest, README, surface module and search metadata, and its component when one is given.

Given bytes, the asset is made WITH its component in one write, so it registers as a plugin that can load rather than as an empty folder that is filled in afterwards. Without them it is a scaffold, and it loads when a plugin.wasm is written into it.

Parameters

• name string — The plugin's name, which is also its identity in this world.
• opts CreateOpts

asset.create("plugin", "motion", { bytes = componentBytes })

modules/PluginAssetTypeRef/onDelete

onDelete(self)

Stop the plugin this asset loaded, because the asset is gone.

Parameters

• self any (optional) — The AssetRef<plugin> that was removed.

modules/PluginAssetTypeRef/onRegister

onRegister(self)

Load the plugin this asset carries.

Parameters

• self any (optional) — The AssetRef<plugin> registering.

modules/PluginShared/README

require("@builtin::assetTypes.plugin.shared") -- PluginShared

What every plugin's Luau surface is built on: calling the plugin it belongs to, listening to it, and asking the person to open one of its pages. Shipped by the TYPE, so no plugin implements any of it.

Usage: local PluginShared = require("@builtin::assetTypes.plugin.shared")

modules/PluginShared/awaitingPerson

awaitingPerson(): boolean

Whether a call to this plugin is waiting on a person.

modules/PluginShared/call

call(method: string, ...): any

Call one of the methods this plugin's plugin.yaml exposes.

Parameters

• method string

modules/PluginShared/identity

identity(): string

This plugin's engine identity, for a caller that needs to name it.

modules/PluginShared/on

on(listener: (string, any) -> ())

Listen to this plugin's events, waiting for it to load first.

Parameters

• listener (string, any) -> () — function(eventType, payload).

modules/PluginShared/openUrl

openUrl(url: string): any

Ask the person to open one of this plugin's own declared pages.

Parameters

• url string

modules/PopulationAssetTypeBehavior/README

require("@builtin::assetTypes.population.behavior") -- PopulationAssetTypeBehavior

Behaviour for the population asset type — a hardware-instanced population at rest. onCreate writes the recipe (population.json) plus the instance matrices as bytes (transforms.bin); :draw() turns that recipe back into live GPU buffers and draw registrations, and instantiate puts one entity in the scene that owns them for as long as it lives.

Usage: local PopulationAssetTypeBehavior = require("@builtin::assetTypes.population.behavior")

modules/PopulationAssetTypeBehavior/bounds

bounds(self): any

The box the drawn instances occupy — each variant's mesh AABB carried through every one of its matrices, in the space the matrices are taken in: the parent's own frame for a population drawn with a parent, world space otherwise.

Parameters

• self any (optional)

local box = drawn:bounds()

modules/PopulationAssetTypeBehavior/count

count(self): number

Instances the engine reports drawing across every registration this holds. Read back from the renderer rather than from the recipe, so a registration that went away, or that the renderer turned away, counts as gone.

Parameters

• self any (optional)

print(drawn:count())

modules/PopulationAssetTypeBehavior/destroy

destroy(self)

Release every registration and its transform buffer. The draw is dropped BEFORE its buffer is destroyed: a registration reserves slots against the buffer it was given, so a buffer that goes away takes its registration with it. The meshes belong to their .mesh assets and stay. A second call finds an empty list and returns.

Parameters

• self any (optional)

drawn:destroy()

modules/PopulationAssetTypeBehavior/draw

draw(self, opts: { [string]: any }?): any

Rebuild this population's live draws: allocate a GPU transform buffer per variant, upload that variant's run of transforms.bin into it, resolve the mesh and material, and register one instanced draw. The returned value OWNS those resources — hold it and call :destroy() to release them; a registration nobody holds can be neither enumerated nor dropped afterwards. With a parent the matrices are taken in that entity's space and the draws move with it; without one they stand where the recipe placed them in the world.

Parameters

• self any (optional)
• opts { [string]: any }? (optional) — { castsShadows? = true, renderLayer?, parent? } — parent is the entity (or its id) the copies stand in.

local drawn = populationRef:draw(); … ; drawn:destroy()

modules/PopulationAssetTypeBehavior/drawCalls

drawCalls(self): number

Draw calls this population costs — one per variant the renderer is drawing, at any instance count. A variant the renderer turned away costs nothing and is counted nowhere; :errors() says why.

Parameters

• self any (optional)

print(drawn:drawCalls())

modules/PopulationAssetTypeBehavior/errors

errors(self): { any }

Why this population is drawing less than its recipe asks for: one entry per registration the renderer turned away, carrying the variant it belongs to, the mesh it names and the renderer's own reason. A population drawing everything it holds answers with an empty list, so this and :drawCalls() agree with the frame.

Parameters

• self any (optional)

for _, e in ipairs(drawn:errors()) do warn(e.variant, e.error) end

modules/PopulationAssetTypeBehavior/inspectDetail

inspectDetail(self): any

asset.inspect type-specific detail: { total, variantCount, variants }, read straight from population.json — never allocates a buffer or registers a draw. A population whose recipe can't be read returns an empty detail rather than erroring.

Parameters

• self any (optional)

local n = asset.inspect(populationRef).detail.total

modules/PopulationAssetTypeBehavior/instantiate

instantiate(self, target: EntityRef?, opts: { [string]: any }?): (EntityRef, { [string]: string })

Instantiate this population — the uniform instantiate(target?, opts?) contract every scene-instantiable asset answers to. A population becomes ONE entity carrying a Population component that references this asset: the component rebuilds the live draws on awake and releases them on destroy, so the scene records one entity for a population of any size and a reload replaces the draws rather than stacking a second set. With target the entity spawns as a child of that owner (so an owning Asset component tears it down with its other children); with no target it is a fresh root. The base opts — position, rotation, scale, name, temporary — place the root.

Parameters

• self any (optional)
• target EntityRef? (optional) — Optional owning entity ref.
• opts { [string]: any }? (optional) — { position?, rotation?, scale?, name?, temporary? }.

populationRef:instantiate(owner)

modules/PopulationAssetTypeBehavior/onCreate

onCreate(name: string, opts: CreateOpts?): { [string]: string }

Generic-creation hook for asset.create("population", name, opts). Pure: returns the content-file map; asset.create writes it to the mode-aware destination. Each variant contributes its mesh + material to population.json and its matrices to transforms.bin, in variant order.

Parameters

• name string — Population identity (the instance name).
• opts CreateOpts? (optional)

asset.create("population", "forest", { variants = { { mesh = meshGuid, material = matGuid, transforms = flat } } })

modules/PopulationAssetTypeBehavior/setRenderLayer

setRenderLayer(self, renderLayer: number)

Put every registration this holds on the render layers renderLayer names. Constant time per registration — the transforms are not re-uploaded and nothing is re-registered — so a population can follow a membership that moves, and the next frame drawn tests its copies against the new one.

Parameters

• self any (optional)
• renderLayer number — The membership bitmask, the same value :draw({ renderLayer }) takes. At least one bit must be set.

drawn:setRenderLayer(mask)

modules/PopulationAssetTypeBehavior/settled

settled(self): boolean

Whether the renderer has answered for every registration this holds. A registration is made a stage before the renderer sees it, so the frame it is made in is one where nothing yet says whether the copies are drawn; :errors() is complete from the frame this turns true.

Parameters

• self any (optional)

if drawn:settled() then print(#drawn:errors(), "variants failed") end

modules/PopulationAssetTypeBehavior/spec

spec(self): any

The recipe this population draws from: { version, total, variants }, where each variant carries { mesh, material?, materialKey?, count, offset } — the .mesh it draws, the material it draws with, how many instances it holds, and where its matrices start in transforms.bin (counted in instances).

Parameters

• self any (optional)

local total = populationRef:spec().total

modules/PopulationAssetTypeBehavior/transforms

transforms(self): string

The instance matrices as raw bytes — total * 64, little-endian f32, column-major mat4 per instance, in variant order.

Parameters

• self any (optional)

local blob = populationRef:transforms()

modules/PostMetrics/README

require("@builtin::modules.postMetrics") -- PostMetrics

Instruments for judging a picture by numbers: FLIP against a golden, pixel metrics (banding, halo overshoot, temporal variance, ring energy, hue drift), CPU twins of the display curves and of the synthetic HDR chart, and scope pictures (histogram, waveform, vectorscope, false colour, banding zebra, tone curve). Every function takes a picture in any form one arrives in: a TextureCpuHandle, a frame renderer.presentedFrames returns, a capture result carrying base64 data, or PNG / ZTEX bytes. Pixel values are code values on the 0-255 scale the picture is delivered at unless a function says it reads light.

Usage: local PostMetrics = require("@builtin::modules.postMetrics")

modules/PostMetrics/banding

banding(frame: any, rect: Rect?, opts: { channel: string?, tolerance: number? }?): Banding

Banding along a ramp. The rectangle's columns are averaged over its rows (so dither, which varies from row to row, averages into a smooth profile and a quantised ramp does not), and the profile is read for how long it stays flat. longestRun is the most consecutive columns holding one value, distinctCodes how many distinct whole code values the profile passes through, and steps how many times it changes value. A ramp that climbs fewer code values than it has columns, undithered, holds each one for several columns: a long longestRun is a visible band. Give the rectangle several rows; one row of a dithered ramp has runs of its own.

Parameters

• frame any (optional) — The picture.
• rect Rect? (optional) — The ramp's rectangle, its gradient running along x; the whole picture when nil.
• opts { channel: string?, tolerance: number? }? (optional) — { channel?, tolerance? }: tolerance is how far apart two values may be and count as one (default 0.001).

local b = postMetrics.banding(frame, { x = 0, y = 8, w = 256, h = 16 }); print(b.longestRun)

modules/PostMetrics/canvas

canvas(width: number, height: number, fill: { number }?): Canvas

A blank RGBA8 picture to draw into on the CPU, filled with one colour (code values, default black, opaque).

Parameters

• width number — Pixels across.
• height number — Pixels down.
• fill { number }? (optional) — { r, g, b } in code values.

local c = postMetrics.canvas(64, 64)

modules/PostMetrics/chart.hide

chart.hide(name: string?)

Take the chart down again.

Parameters

• name string? (optional) — The name chart.show returned (default "postMetrics_chart").

modules/PostMetrics/chart.light

chart.light(props: any, u: number, v: number): (number, number, number)

The light the chart holds at a point of the picture (u, v from the top-left, 0..1), the CPU twin of the chart shader: what a reference picture for the chart is built from. It returns the light before dither.

Parameters

• props any (optional) — The chart's properties (pattern by number or name).
• u number — Across, 0 at the left edge.
• v number — Down, 0 at the top edge.

local r, g, b = postMetrics.chart.light({ pattern = "greyWedge" }, 0.5, 0.5)

modules/PostMetrics/chart.patch

chart.patch(props: any, width: number, height: number, stop: number, half: string?, inset: number?): Rect

The pixel rectangle one column of a wedge pattern covers in a width x height picture, inset by inset pixels on each side so a reading stays clear of the edges between columns. half picks the top ("top") or bottom ("bottom") half of a colour wedge; nil covers the whole height.

Parameters

• props any (optional) — The chart's properties.
• width number — The picture's width.
• height number — The picture's height.
• stop number — The column's exposure in whole stops.
• half string? (optional) — "top", "bottom" or nil.
• inset number? (optional) — Pixels kept clear of each edge (default 1).

local rect = postMetrics.chart.patch({ pattern = "colorWedge" }, 168, 64, 4, "top")

modules/PostMetrics/chart.reference

chart.reference(props: any, width: number, height: number, curve: any, exposure: number?): any

The picture the display should present for the chart: every pixel's chart light taken through curves.display with curve and exposure and rounded to a code value. Held against the presented chart with flip, it measures the display path against its reference; built with a different curve, it measures how far the display path stands from that.

Parameters

• props any (optional) — The chart's properties.
• width number — Pixels across, the presented chart's.
• height number — Pixels down.
• curve any (optional) — The curve, as curves.display takes it.
• exposure number? (optional) — The exposure (default 1).

local ref = postMetrics.chart.reference({ pattern = "colorWedge" }, 128, 64, postMetrics.curves.acesHuePreserving)

modules/PostMetrics/chart.show

chart.show(props: any?, name: string?): string

Draw the chart in place of the scene: register @builtin::shaders.post.hdrChart first in the chain (on the scene layer, in light) with props. Everything after it in the chain (the effects registered after, and the display transform) draws over it.

Parameters

• props any? (optional) — The chart's properties (pattern by number or name).
• name string? (optional) — The effect's name (default "postMetrics_chart").

local name = postMetrics.chart.show({ pattern = "ramp", low = 0, high = 0.1 })

modules/PostMetrics/curves.aces

curves.aces(x: number): number

The ACES filmic fit of Narkowicz 2015 (__display__ curve 2), applied to one channel.

Parameters

• x number

modules/PostMetrics/curves.acesHuePreserving

curves.acesHuePreserving(r: number, g: number, b: number): (number, number, number)

ACES (Narkowicz) applied to a colour's largest channel, the colour scaled with it: the channels keep their ratios, so the hue a per-channel curve skews is kept. On grey it is the per-channel curve exactly.

Parameters

• r number
• g number
• b number

modules/PostMetrics/curves.clamp

curves.clamp(x: number): number

The clamp curve (__display__ curve 0): light clipped to 0..1.

Parameters

• x number

modules/PostMetrics/curves.display

curves.display(r: number, g: number, b: number, curve: any, exposure: number?): (number, number, number)

What the display transform __display__ presents for a colour in light: exposure, then curve (0 clamp, 1 Reinhard, 2 ACES, 3 PBR Neutral, or a function (r, g, b) -> (r, g, b)), then the sRGB encode, in code values (0..255, unrounded).

Parameters

• r number — Red, in light.
• g number — Green, in light.
• b number — Blue, in light.
• curve any (optional) — The curve's number, or a function.
• exposure number? (optional) — The multiplier on the light before the curve (default 1).

local r, g, b = postMetrics.curves.display(0.18, 0.18, 0.18, 3)

modules/PostMetrics/curves.pbrNeutral

curves.pbrNeutral(r: number, g: number, b: number): (number, number, number)

Khronos PBR Neutral (__display__ curve 3), over a colour in light. The reference is the Khronos sample implementation (https://github.com/KhronosGroup/ToneMapping).

Parameters

• r number
• g number
• b number

modules/PostMetrics/curves.reinhard

curves.reinhard(x: number): number

Reinhard (__display__ curve 1): x / (1 + x).

Parameters

• x number

modules/PostMetrics/expectGolden

expectGolden(frame: any, path: string, opts: any?): Golden

golden, raising its reason when the picture does not pass.

Parameters

• frame any (optional) — The picture.
• path string — The golden's VFS path.
• opts any? (optional) — The options golden takes.

postMetrics.expectGolden(frame, here .. "/goldens/halo.png", { maxMean = 0.02 })

modules/PostMetrics/flip

flip(test: any, reference: any, opts: any?): any

NVIDIA FLIP of test against reference: how different the two look to a viewer flipping between them, per pixel in 0..1, summarised. mean is the number the reference evaluator reports for a pair; around 0.01 is invisible flipping between them, around 0.1 a difference anybody sees.

Parameters

• test any (optional) — The picture being judged.
• reference any (optional) — The picture it is held against, of the same size.
• opts any? (optional) — { rect?, pixelsPerDegree?, errorMap? }: rect summarises one rectangle of the error map; errorMap = true hands back the per-pixel error as a grey picture.

local f = postMetrics.flip(frame, golden); print(f.mean)

modules/PostMetrics/golden

golden(frame: any, path: string, opts: any?): Golden

Compare a picture with the golden stored at path (a PNG), by FLIP. It passes when the FLIP mean is at most maxMean (default GOLDEN_MAX_MEAN) and, when maxP99 is given, its 99th percentile at most that: tolerant of the noise one GPU, driver or platform puts on a picture another drew, and failing at a change a viewer sees. status is "matched", "differs", "size" (the two are not one size), "missing" (no golden at path) or "recorded". record = true writes the picture as the golden instead of comparing, which is how a golden is made or remade after a change that is meant to change the picture.

Parameters

• frame any (optional) — The picture.
• path string — The golden's VFS path, a .png.
• opts any? (optional) — { maxMean?, maxP99?, rect?, pixelsPerDegree?, record?, errorMap? }

local g = postMetrics.golden(frame, asset.containing(__FILE__).path .. "/goldens/halo.png")

modules/PostMetrics/halfWidth

halfWidth(profile: { number }): number

The distance, in profile entries, at which a profile has fallen to half of its first entry, interpolated between the two entries either side.

Parameters

• profile { number } — A profile, from its source outward.

postMetrics.halfWidth(postMetrics.profile(frame, row))

modules/PostMetrics/haloOvershoot

haloOvershoot(frame: any, rect: Rect?, opts: { plateau: number?, channel: string?, linear: boolean? }?): Overshoot

Halo overshoot at an edge: how far a profile across a step between two flat regions rises above the brighter plateau and falls below the darker one. A sharpening or a ringing filter overshoots; a clean edge stays between its plateaus. The plateaus are the means of the profile's first and last plateau entries.

Parameters

• frame any (optional) — The picture.
• rect Rect? (optional) — A rectangle across the edge, its gradient running along x.
• opts { plateau: number?, channel: string?, linear: boolean? }? (optional) — { plateau?, channel?, linear? }: plateau defaults to 4.

local e = postMetrics.haloOvershoot(frame, { x = 100, y = 60, w = 40, h = 8 })

modules/PostMetrics/hueDrift

hueDrift(colours: { any }): HueDrift

Hue drift of one colour across a series of readings (a saturated patch over exposure, say): each reading's CIELAB hue angle, drift the largest angle any reading stands from the first, and span the angle between the two readings furthest apart. A tone curve that keeps a colour's hue as it brightens drifts by nothing. Readings are colours in light ({ r, g, b }) or results of meanColour.

Parameters

• colours { any } — The readings, in order.

local d = postMetrics.hueDrift({ postMetrics.meanColour(a, rect), postMetrics.meanColour(b, rect) }).drift

modules/PostMetrics/image

image(source: any): (any, boolean)

Load a picture (PNG / ZTEX bytes, a capture result, a presented frame) into a TextureCpuHandle. A handle passes through unchanged.

Parameters

• source any (optional) — The picture.

local cpu, loaded = postMetrics.image(vfs.read(path)); ...; if loaded then cpu:unload() end

modules/PostMetrics/lab

lab(r: number, g: number, b: number): { L: number, a: number, b_: number, chroma: number, hue: number }

CIELAB of a colour in linear light (sRGB primaries, D65 white): lightness L, the opponent axes a and b_, chroma and hue (the hue angle in degrees, 0..360).

Parameters

• r number — Red, in light.
• g number — Green, in light.
• b number — Blue, in light.

postMetrics.lab(0.05, 0.1, 1.0).hue

modules/PostMetrics/meanColour

meanColour(frame: any, rect: Rect?): Colour

The mean colour of a rectangle: its code values, the light they decode to (averaged as light), and that light's CIELAB lightness, chroma and hue.

Parameters

• frame any (optional) — The picture.
• rect Rect? (optional) — { x, y, w, h }; the whole picture when nil.

local patch = postMetrics.meanColour(frame, { x = 10, y = 10, w = 8, h = 8 })

modules/PostMetrics/picture

picture(source: any): any

A picture as an image value: returned from execute, a tool or a probe, it reaches the caller as a picture (mcp.image).

Parameters

• source any (optional) — The picture.

return postMetrics.picture(postMetrics.scopes.waveform(frame))

modules/PostMetrics/profile

profile(frame: any, rect: Rect?, opts: { axis: string?, channel: string?, linear: boolean? }?): { number }

The values along a rectangle of a picture: one per column (axis = "x", the default), each the mean over the rectangle's rows, or one per row (axis = "y"). channel is "luma" (Rec. 709, the default), "r", "g" or "b"; linear = true reads light (0..1) in place of code values.

Parameters

• frame any (optional) — The picture.
• rect Rect? (optional) — { x, y, w, h }; the whole picture when nil.
• opts { axis: string?, channel: string?, linear: boolean? }? (optional) — { axis?, channel?, linear? }

local row = postMetrics.profile(frame, { x = 0, y = 40, w = 256, h = 1 })

modules/PostMetrics/ringEnergy

ringEnergy(frame: any, cx: number, cy: number, inner: number, outer: number): RingEnergy

The light in a ring around a point: the summed Rec. 709 luminance, in light (0..1 per pixel, decoded from sRGB), of every pixel whose centre lies at least inner and less than outer pixels from (cx, cy). The energy a bloom spreads out of a source is the ring's energy with the bloom less the same ring's without it.

Parameters

• frame any (optional) — The picture.
• cx number — The ring's centre, in pixels from the left (a pixel's centre is +0.5).
• cy number — The ring's centre, in pixels from the top.
• inner number — The inner radius in pixels.
• outer number — The outer radius in pixels.

local e = postMetrics.ringEnergy(frame, 64, 64, 4, 24).energy

modules/PostMetrics/scopes.falseColor

scopes.falseColor(frame: any, opts: { middleGrey: number? }?): any

False-colour exposure: each pixel painted by the band of stops its light stands at relative to middleGrey (light, default 0.18): deep purple below -6, blue to -4, cyan-blue to -2, grey to -0.5, green within half a stop of middle grey, light grey to +2, yellow to +2.4, orange above; pixels at code 255 in any channel are red (clipped) and at 0 in every channel dark purple-black (crushed).

Parameters

• frame any (optional) — The picture.
• opts { middleGrey: number? }? (optional) — { middleGrey? }

return postMetrics.picture(postMetrics.scopes.falseColor(frame))

modules/PostMetrics/scopes.histogram

scopes.histogram(frame: any, opts: { rect: Rect?, height: number? }?): any

A histogram picture: luma (grey) and the red, green and blue channels (each drawn as its own line) over the 256 code values, left to right, each column's height its share of the tallest bucket. rect is the metering window: only the pixels inside it are counted.

Parameters

• frame any (optional) — The picture.
• opts { rect: Rect?, height: number? }? (optional) — { rect?, height? }: height defaults to 128.

return postMetrics.picture(postMetrics.scopes.histogram(frame, { rect = { x = 0, y = 0, w = 64, h = 64 } }))

modules/PostMetrics/scopes.toneCurve

scopes.toneCurve(curves: { any }, opts: { evMin: number?, evMax: number?, size: number? }?): any

A tone curve plot: each curve's output code value (up) against its input light from evMin to evMax stops around middle grey (across, on a log scale), with middle grey and the output's 0 and 255 marked. A curve is a __display__ curve number or a function (r, g, b) -> (r, g, b) over light.

Parameters

• curves { any } — The curves, each drawn in its own colour (white, orange, cyan, magenta, then repeating).
• opts { evMin: number?, evMax: number?, size: number? }? (optional) — { evMin?, evMax?, size? }: defaults -10, 10, 256.

return postMetrics.picture(postMetrics.scopes.toneCurve({ 2, 3 }))

modules/PostMetrics/scopes.vectorscope

scopes.vectorscope(frame: any, opts: { size: number? }?): any

A vectorscope: every pixel's chroma (Rec. 709 Cb across, Cr up) on a disc, brighter where more pixels share it. Grey sits at the centre; a saturated colour sits out toward the rim along its hue. Graticule: the rim and the directions of the six primaries and secondaries.

Parameters

• frame any (optional) — The picture.
• opts { size: number? }? (optional) — { size? }: the scope's side in pixels (default 256).

return postMetrics.picture(postMetrics.scopes.vectorscope(frame))

modules/PostMetrics/scopes.waveform

scopes.waveform(frame: any, opts: { width: number? }?): any

A luma waveform: one column per column of the picture (resampled to at most width), its pixels plotted by code value from the bottom (0) to the top (255), brighter where more pixels share a value. A flat region is a thin line, a gradient a slope, a clipped highlight a line along the top.

Parameters

• frame any (optional) — The picture.
• opts { width: number? }? (optional) — { width? }: the most columns the scope has (default 512).

return postMetrics.picture(postMetrics.scopes.waveform(frame))

modules/PostMetrics/scopes.zebra

scopes.zebra(frame: any, opts: { minRun: number?, maxRun: number? }?): (any, number)

A banding zebra: the picture in grey, with diagonal magenta stripes over every run of minRun or more pixels along a row that holds one code value and ends in a step of one or two code values to its neighbour: a contour a smooth gradient was quantised into. Flat regions with no step at their end, and runs longer than maxRun, are left unmarked.

Parameters

• frame any (optional) — The picture.
• opts { minRun: number?, maxRun: number? }? (optional) — { minRun?, maxRun? }: defaults 4 and 128.

local z, marked = postMetrics.scopes.zebra(frame)

modules/PostMetrics/temporalVariance

temporalVariance(frames: { any }, rect: Rect?, opts: { channel: string?, linear: boolean? }?): TemporalVariance

Temporal variance: how much each pixel changes across a run of frames of the same view. Each pixel's variance over the frames is taken, in code values squared (or light squared, linear = true), and the rectangle summarised. A converged temporal resolve on a still view holds every pixel; flicker, shimmer and crawl are variance.

Parameters

• frames { any } — Two or more pictures of one size, in order.
• rect Rect? (optional) — { x, y, w, h }; the whole picture when nil.
• opts { channel: string?, linear: boolean? }? (optional) — { channel?, linear? }

local f = renderer.presentedFrames({ frames = 16 }); local v = postMetrics.temporalVariance(f)

modules/PostMetrics/toImage

toImage(c: Canvas): any

A canvas as a TextureCpuHandle, for the metrics, flip and picture. The caller unloads it.

Parameters

• c Canvas — The canvas.

local cpu = postMetrics.toImage(c)

modules/PostMetrics/upturns

upturns(profile: { number }, tol: number): number

How many times a profile turns back UP by more than tol: a local minimum followed by a rise of at least tol. A halo falls away from its source and turns back up nowhere; a kernel taking taps on a grid re-brightens at every tap.

Parameters

• profile { number } — A profile, from its source outward.
• tol number — The rise, in the profile's units, that counts as a turn.

postMetrics.upturns(postMetrics.profile(frame, row), 2)

modules/Prelude/README

require("@builtin::modules.prelude") -- Prelude

Auto-require globals available in every script without require(). Injects Entity, Physics, Transform, and Material as global Luau wrappers.

This script runs once after FFI registration. It requires builtin library modules and exposes them as globals. Users never need to write: local Entity = require(".entity_reflect") Instead they just use Entity directly. Only high-frequency, universally-useful APIs belong here. Specialized modules (e.g. agent tools, editor UI) still use require(). Convention: __name = raw FFI binding (Rust native call, never used directly by scripts) Name = Luau wrapper (user-facing, auto-injected via this prelude)

Usage: local Prelude = require("@builtin::modules.prelude")

modules/PresetAssetTypeRef/README

require("@builtin::assetTypes.preset.behavior") -- PresetAssetTypeRef

Per-instance methods on every AssetRef<preset>, the onCreate hook that writes a checked preset.yaml, and the validation asset.validate and every edit run.

Usage: local PresetAssetTypeRef = require("@builtin::assetTypes.preset.behavior")

modules/PresetAssetTypeRef/applyTo

applyTo(self, entityId: string, componentType: string, overrides: { [string]: any }?): boolean

Write this preset's values, overrides laid on top, onto the componentType component of entityId, field by field. Forwards to preset.load, which warns once that preset.values replaces it.

Parameters

• self any (optional)
• entityId string — Target entity ID.
• componentType string — Component type name (e.g. "Locomotion").
• overrides { [string]: any }? (optional) — Optional shallow overrides applied on top of the preset.

modules/PresetAssetTypeRef/getDefinition

getDefinition(self): string?

Read the preset's preset.yaml body as raw text.

Parameters

• self any (optional)

local raw = presetRef:getDefinition()

modules/PresetAssetTypeRef/inspect

inspect(self): any

asset.inspect detail: the target, the format, the checked values, every rejected field, and whether the target changed since it was pinned. componentType names the component a component preset configures (nil for any other target), and fieldValues is the same table as values.

Parameters

• self any (optional)

local detail = asset.inspect(presetRef).detail
local componentType = asset.inspect(presetRef).detail.componentType

modules/PresetAssetTypeRef/load_preset

load_preset(self, overrides: { [string]: any }?): { [string]: any }?

This preset as a plain table, overrides laid on top. Forwards to preset.load, which warns once that preset.values replaces it.

Parameters

• self any (optional)
• overrides { [string]: any }? (optional) — Optional table merged shallowly over the values.

modules/PresetAssetTypeRef/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

Write a preset for opts.target's schema holding opts.values, checked against that schema before anything is written.

Parameters

• name string — The preset's name.
• opts CreateOpts

modules/PresetDefaults/README

require("@builtin::modules.preset.defaults") -- PresetDefaults

The Preset Manager: the world's ordered [[presets]] rows in /zero/source/.world_settings. A row names one declarer (target), one preset for that declarer (preset) and a path glob (filter). When something a declarer governs is created — an asset of an assetType, an import an importer runs, a component added to an entity — the first row naming that declarer whose filter matches the new thing's path gives a layer of its settings. Rows are read only at creation.

Usage: local PresetDefaults = require("@builtin::modules.preset.defaults")

modules/PresetDefaults/batchLayers

batchLayers(targets: { any }, typeName: string, data: { [string]: any }?): { { targets: { any }, data: { [string]: any }? } }

The targets of a batch component add split into runs by the data each takes: consecutive targets the same row reaches (or no row reaches) share one run, each with the data forComponent gives its members. Adding the runs in order adds the targets in the order given. A world whose rows name nothing for typeName gives one run of every target.

Parameters

• targets { any } — Entity ids or proxies.
• typeName string — The component type.
• data { [string]: any }? (optional) — The values the caller passed, or nil.

for _, g in ipairs(Defaults.batchLayers(ids, "Model", {})) do print(#g.targets) end

modules/PresetDefaults/check

check(value: any, _constraint: any): (boolean, string?)

The presetDefaultRow constraint's validator: a row passes when rowProblems finds nothing.

Parameters

• value any (optional) — The row.
• _constraint any (optional) — The constraint descriptor.

local ok, why = Defaults.check(row, { kind = "presetDefaultRow" })

modules/PresetDefaults/consultedAt

consultedAt(declarer: any): string?

Where a declarer's settings are consulted when something it governs is created: "import" for an importer, "component.add" for a component, "asset.create" for an assetType that declares one schema for every instance. Nil for any other asset.

Parameters

• declarer any (optional) — The declarer's AssetRef.

Defaults.consultedAt(asset.resolve("@builtin::importers.texture")) --> "import"

modules/PresetDefaults/entityPath

entityPath(id: string): string

An entity's hierarchy path: its ancestors' names from the root down and its own, joined by /. A nameless entity contributes its id.

Parameters

• id string — The entity id.

Defaults.entityPath(id) --> "level/props/crate"

modules/PresetDefaults/forComponent

forComponent(entityId: string, typeName: string, data: { [string]: any }?): { [string]: any }?

The data a component add of typeName to entityId takes: data as given, or a new table holding the first matching row's values with data's own values laid over them, field by field. The row is read when the component is added; a row edited later changes no component already added. A row applies to what a scene build's capture scope adds (entity.capturing()), in any mode and whoever runs the build, and outside a build in edit mode. A component put back from existing content takes none: one added inside materializing, and one a component's own code adds outside a build, on any coroutine it runs. The component's own public defaults fill whatever neither states.

Parameters

• entityId string — The entity the component is added to.
• typeName string — The component type.
• data { [string]: any }? (optional) — The values the caller passed, or nil.

local data = Defaults.forComponent(id, "Model", { model = "cube" })

modules/PresetDefaults/importerSettings

importerSettings(importerRef: any, sourcePath: string): ({ [string]: any }, Match?)

An importer's settings for importing sourcePath: its own values with its first matching [[presets]] row (the filter read against the source path under /source) laid over them, a struct group field by field.

Parameters

• importerRef any (optional) — The importer.
• sourcePath string — The source file being imported.

local s = Defaults.importerSettings(asset.resolve("@builtin::importers.texture"), "/source/sprites/hero.png")

modules/PresetDefaults/layerFor

layerFor(declarerGuid: string, relPath: string): ({ [string]: any }?, Match?)

The layer the Preset Manager gives a new thing declarerGuid governs at relPath, and the row that gives it. A matching row whose preset does not resolve, or is for another declarer, gives no layer and says why.

Parameters

• declarerGuid string — The declarer's guid.
• relPath string — The new thing's path, as relativePathOf gives it.

local values, match = Defaults.layerFor(asset.guid(importer), "sprites/hero.png")

modules/PresetDefaults/match

match(declarerGuid: string, relPath: string): (Row?, number?)

The first row naming declarerGuid whose filter matches relPath.

Parameters

• declarerGuid string — The declarer's guid.
• relPath string — The new thing's path, as relativePathOf gives it.

local row, index = Defaults.match(asset.guid(importer), "sprites/hero.png")

modules/PresetDefaults/materializing

materializing(fn: (...any) -> ...any, ...: any): ...any

Run fn with no Preset Manager row reaching a component add on this thread — for code that puts back a component that already existed (a peer's record, a saved scene's record, a template's clone).

Parameters

• fn (...any) -> ...any — The function to run.
• args any (optional)

Defaults.materializing(function() entity(id).component.add("Model", saved) end)

modules/PresetDefaults/normalize

normalize(input: RowInput): StoredRow

A row input as the row a world stores: its target and preset as guid envelopes, its filter as a string. An absent target is the preset's own. A target that does not resolve is kept as written so rowProblems names it; a preset that does not resolve raises.

Parameters

• input RowInput — { preset, target?, filter? }; preset and target take an AssetRef, envelope, guid or identity.

local row = Defaults.normalize({ preset = "pixel_art", filter = "sprites/**" })

modules/PresetDefaults/recordingStamps

recordingStamps(fn: (...any) -> ...any, ...: any): ...any

Run fn and return, before its own results, what the Preset Manager rows gave the components added on this thread while it ran inside a capture scope: per stampKey, the fields the row gave that the add's caller did not state, sorted — a field of a group the caller stated only partly as group.field.

Parameters

• fn (...any) -> ...any — The function to run.
• args any (optional)

local stamps, ids = Defaults.recordingStamps(entity.capture, builder)

modules/PresetDefaults/relativePathOf

relativePathOf(path: string): string?

The path a row's filter reads for path, without a leading slash: the path under /source for a durable path, the path under /zero/runtime/assets/ for a runtime asset. Nil for any other path.

Parameters

• path string — A VFS path.

Defaults.relativePathOf("/zero/source/sprites/hero.png") --> "sprites/hero.png"

modules/PresetDefaults/removeAt

removeAt(index: number)

Remove the row at index and write every other row back exactly as the file holds it — neither re-normalised nor checked, so a row can be removed while another is broken.

Parameters

• index number — The row's index, as rows() reports it.

Defaults.removeAt(2)

modules/PresetDefaults/resolveValue

resolveValue(v: any): any?

A row value as the asset it names: an envelope by its guid, a string by the guid .world_settings's .refs pinned for it, else by the string itself as an identity or guid.

Parameters

• v any (optional) — An envelope, a guid or identity string, or an AssetRef-shaped { path, type }.

local ref = Defaults.resolveValue(row.target)

modules/PresetDefaults/rowProblems

rowProblems(row: any): ({ string }, any?, any?)

Every problem that keeps a row from applying, and the declarer and preset it resolves to.

Parameters

• row any (optional) — A stored row or a row input.

local problems = Defaults.rowProblems({ target = "@builtin::importers.texture", preset = "pixel_art" })

modules/PresetDefaults/rows

rows(): { Row }

The world's rows, in order, each resolved and with every problem that keeps it from applying.

for _, row in ipairs(Defaults.rows()) do print(row.index, row.targetName) end

modules/PresetDefaults/stampKey

stampKey(entityId: string, componentGuid: string, instanceName: string?): string

The key recordingStamps files a component instance under: its entity, its component's guid and its instance name (empty for an anonymous one).

Parameters

• entityId string — The entity.
• componentGuid string — The component's guid.
• instanceName string? (optional) — The instance name, or nil.

local key = Defaults.stampKey(id, asset.guid(asset.resolve("Model", "component")), nil)

modules/PresetDefaults/version

version(): number

The content version of the rows file: the engine's own count for .world_settings, which moves the moment any change of the file lands, whatever made it, and at no other time.

local v = Defaults.version()

modules/PresetDefaults/write

write(inputs: { RowInput })

Replace the world's rows. Every input is normalised and the whole set checked first; any problem refuses the write, naming every one. The [[presets]] block is replaced and the rest of the file kept.

Parameters

• inputs { RowInput } — The complete ordered rows.

Defaults.write({ { preset = "pixel_art", filter = "sprites/**" } })

modules/PresetDefaultsSection/README

require("@builtin::editor.edui.inspector.presetDefaultsSection") -- PresetDefaultsSection

The Preset Manager as an inspector section: the world's ordered [[presets]] rows, each a declarer chip, a preset chip that offers only presets for that declarer, and a filter glob, edited as typed fields through the Settings section, with move up / down, remove and add. An edit that leaves every row whole is one checked, undoable write of .world_settings. A row being filled in — just added, or given its declarer before its preset — stays in the section until it is whole, and shows what it still needs. Removing a row always writes, whatever the other rows hold. A row that cannot apply shows why.

Usage: local PresetDefaultsSection = require("@builtin::editor.edui.inspector.presetDefaultsSection")

modules/PresetDefaultsSection/context

context(): any

The section's context: the rows as values of the block's schema, a writer that checks and writes them, the chip predicate, and each row's problems as its rejection.

local ctx = PresetDefaultsSection.context()

modules/PresetDefaultsSection/render

render(): { any }

The section rendered with a fresh context.

local nodes = PresetDefaultsSection.render()

modules/PresetDefaultsSection/signature

signature(): string

A value that moves whenever what the section shows moves — the rows file's content version and the draft — for a panel's build signature.

sig ..= PresetDefaultsSection.signature()

modules/PresetDocument/README

require("@builtin::modules.preset.document") -- PresetDocument

A preset's preset.yaml. The typed form names the declarer the values are for (target) and the values themselves (values). target is written as a guid envelope, { __ref: <guid>, type: <type>, name: <name> }, which .refs pins by that guid; an identity string is accepted on read. The component-only form names a component by its registered name (component) and lists properties.

Usage: local PresetDocument = require("@builtin::modules.preset.document")

modules/PresetDocument/decode

decode(body: string): Doc

Decode a preset.yaml body. A body with a target is typed; a body with component or properties is component-only. A component-only body Yaml.decode refuses is read by the line parser presets have always been read with. A typed body that does not decode, or whose target is neither an envelope nor an identity string, raises.

Parameters

• body string — The file's text.

local doc = Document.decode(vfs.read(path))

modules/PresetDocument/encode

encode(envelope: Envelope, values: { [string]: any }): string

The typed preset.yaml body for a target envelope and values.

Parameters

• envelope Envelope — The target, { __ref = <guid>, type = <type>, name = <name> }.
• values { [string]: any } — The values.

local Target = require("@builtin::modules.preset.target")
local body = Document.encode(Target.envelopeFor(texType), { filter = "nearest" })

modules/PresetDocument/pathOf

pathOf(ref: any): string

The preset.yaml path of a preset asset.

Parameters

• ref any (optional) — The preset.

local path = Document.pathOf(presetRef)

modules/PresetDocument/read

read(ref: any): Doc

Read and decode a preset's preset.yaml.

Parameters

• ref any (optional) — The preset.

local doc = Document.read(presetRef)

modules/PresetDocument/write

write(ref: any, envelope: Envelope, values: { [string]: any })

Write the typed preset.yaml for a target envelope and values, raising when the write does not land. Inside an open undo operation the write is recorded into it, so undoing the operation puts back what the file held.

Parameters

• ref any (optional) — The preset.
• envelope Envelope — The target envelope.
• values { [string]: any } — The values.

Document.write(presetRef, envelope, { filter = "nearest" })

modules/PresetGlob/README

require("@builtin::modules.preset.glob") -- PresetGlob

Path globs for Preset Manager rows. * matches any run of characters inside one path segment, ** any run across segments, **/ zero or more whole segments, ? one character other than /; every other character matches itself. A glob matches a whole path. The empty glob matches every path.

Usage: local PresetGlob = require("@builtin::modules.preset.glob")

modules/PresetGlob/match

match(glob: string, path: string): boolean

Whether path matches glob as a whole.

Parameters

• glob string — The glob; "" matches everything.
• path string — A /-separated path.

Glob.match("sprites/**", "sprites/ui/button.png") --> true

modules/PresetHeal/README

require("@builtin::modules.preset.heal") -- PresetHeal

Rewrite a preset's preset.yaml into the form presets are written in, on a local edit of this world's own content. A typed document whose target is an identity string that resolves is rewritten with that target as a guid envelope; every value is kept as decoded, including any its target rejects. A component-only document whose component accepts every property it holds is rewritten in the typed form, its target the component, its values exactly as authored, and its legacy name moved to the .metadata title.

Usage: local PresetHeal = require("@builtin::modules.preset.heal")

modules/PresetHeal/forget

forget(ref: any)

Drop what this module remembers about ref, when the preset is removed.

Parameters

• ref any (optional) — The preset.

Heal.forget(presetRef)

modules/PresetHeal/ifNeeded

ifNeeded(ref: any, origin: string?): boolean

Heal ref on a local edit of this world's own preset: a typed document naming its target by an identity string that resolves gets the guid envelope; a component-only document whose component accepts every property gets the typed form. A component-only document that cannot heal stays as it is, and the reason is warned once. Convergent: a healed document is left as it is.

Parameters

• ref any (optional) — The preset.
• origin string? (optional) — The edit's origin: "local" (or nil) heals; anything else does not.

Heal.ifNeeded(presetRef, change.origin)

modules/PresetHeal/writeTyped

writeTyped(ref: any, doc: any, declarer: any, values: { [string]: any })

Write values into ref's preset.yaml in the typed form, its target declarer as a guid envelope. A component-only document's legacy name moves to the .metadata title first, so every conversion from that form keeps the name the same way. Inside an open undo operation both writes are recorded into it.

Parameters

• ref any (optional) — The preset.
• doc any (optional) — The document ref holds now, as Document.read decoded it.
• declarer any (optional) — The declarer the values are for.
• values { [string]: any } — The values to write.

local Document = require("@builtin::modules.preset.document")
Heal.writeTyped(presetRef, Document.read(presetRef), comp, values)

modules/PresetTarget/README

require("@builtin::modules.preset.target") -- PresetTarget

The declarer a preset's values are for: found by the guid its target envelope names (pinned in the preset's .refs) or by the identity string a hand-written target names, checked against that declarer's current schema, and compared with the checksum the pin recorded.

Usage: local PresetTarget = require("@builtin::modules.preset.target")

modules/PresetTarget/check

check(schema: any, values: { [string]: any }): ({ [string]: any }, { Violation })

Check values against schema field by field: the fields that pass, and every violation by path, sorted.

Parameters

• schema any (optional) — The declarer's Field schema.
• values { [string]: any } — The values.

local valid, rejected = Target.check(schema, { filter = "nearest" })

modules/PresetTarget/declarerOfAsset

declarerOfAsset(ref: any): (any, any)

The declarer governing an asset's settings and its schema: the asset's assetType when the type declares one schema for every instance, else the asset itself when it declares its own.

Parameters

• ref any (optional) — The asset.

local declarer, schema = Target.declarerOfAsset(texRef)

modules/PresetTarget/declarerOfComponent

declarerOfComponent(t: ComponentTarget): (any, any, any)

The component asset governing a component on an entity, its schema, and the live component proxy.

Parameters

• t ComponentTarget — { entity = <id>, component = <name> }.

local comp, schema, proxy = Target.declarerOfComponent({ entity = id, component = "Model" })

modules/PresetTarget/describe

describe(ref: any): string

ref as a person reads it: its identity, else its name.

Parameters

• ref any (optional) — The declarer.

local name = Target.describe(texTypeRef) --> "@builtin::assetTypes.texture"

modules/PresetTarget/envelopeFor

envelopeFor(ref: any): Envelope

The envelope a preset writes as its target for ref: the guid it resolves by, and the type and name a person reads it by. name is the asset's plain name, never an identity, so the envelope's guid is the one dependency .refs records for it.

Parameters

• ref any (optional) — The declarer.

local envelope = Target.envelopeFor(texTypeRef) --> { __ref = "8cc2…", type = "assetType", name = "texture" }

modules/PresetTarget/isComponentTarget

isComponentTarget(v: any): boolean

True when v names a component on an entity: { entity = <id>, component = <name> }.

Parameters

• v any (optional) — The value.

if Target.isComponentTarget(into) then ... end

modules/PresetTarget/literalFor

literalFor(ref: any): string

The literal a preset's .refs pins for ref: its guid.

Parameters

• ref any (optional) — The declarer.

local guid = Target.literalFor(texTypeRef)

modules/PresetTarget/merge

merge(schema: any, current: { [string]: any }?, patch: { [string]: any }): { [string]: any }

patch laid over current, by the settings module's one merge rule (Settings.mergeValues): a struct-kind field (including a resolved Field.settingsOf group) merges field by field, anything else replaces.

Parameters

• schema any (optional) — The declarer's Field schema.
• current { [string]: any }? (optional) — The values the asset has now.
• patch { [string]: any } — The values laid over them.

local merged = Target.merge(schema, asset.settings(tex), values)

modules/PresetTarget/refuse

refuse(prefix: string, violations: { Violation })

Raise one error listing every violation under prefix.

Parameters

• prefix string — The error's first line.
• violations { Violation } — The violations.

Target.refuse("preset.setValues refused:", violations)

modules/PresetTarget/resolve

resolve(presetRef: any, doc: any): Resolved

Resolve a typed document's target. An envelope resolves by its guid; pinned is true once the preset's .refs pins that guid, and changed is true while the pinned checksum differs from the target's current one. An identity string resolves by identity and reads as unpinned.

Parameters

• presetRef any (optional) — The preset whose .refs holds the pin, or nil for a document read on its own.
• doc any (optional) — The decoded typed document.

local Document = require("@builtin::modules.preset.document")
local target = Target.resolve(presetRef, Document.read(presetRef))

modules/PresetTarget/resolveLiteral

resolveLiteral(literal: string): Resolved

Resolve an identity string or a guid, unpinned.

Parameters

• literal string — The declarer's identity or guid.

local target = Target.resolveLiteral("@builtin::assetTypes.texture")

modules/PresetTarget/valuesOf

valuesOf(presetRef: any, doc: any): ({ [string]: any }, Report, Resolved?)

A preset document's values and the report preset.values answers: a typed document's values checked against its target's current schema (the valid ones returned, every refused one listed by path), or a component-only document's values as authored with what its component would refuse. Raises naming the target when a typed document's target does not resolve or declares no schema.

Parameters

• presetRef any (optional) — The preset the document is read from.
• doc any (optional) — The decoded document (Document.read).

local Document = require("@builtin::modules.preset.document")
local values, report, target = Target.valuesOf(p, Document.read(p))

modules/Preview/README

require("@builtin::modules.preview") -- Preview

Render an asset's preview in the preview studio. ref:preview() renders any asset by the recipe its type declares under preview: in its type.yaml, through these primitives: they spawn temporary entities, frame an offscreen camera over them, render one frame, read it back as a PNG, and tear down. Scheduled previews drain through one serial work queue whose drainer renders in shared batches — subjects settle together and capture concurrently — so a world-scale backfill completes in seconds per hundred assets while the engine stays responsive.

Usage: local Preview = require("@builtin::modules.preview")

modules/Preview/__deviceState

__deviceState(): string

The render device state the preview work queue renders by, read each time the queue decides whether a queued render can draw: renderer.deviceState(). A test that has to meet the queue on a device in another state assigns a function returning that state here and puts this one back when it ends.

modules/Preview/backdrop

backdrop(): { number }

The studio backdrop's colour in a finished preview, as 0-255 { r, g, b } — what every pixel of a preview reads where no subject stands. Measured from a frame of the empty studio the first time it is asked for.

local bg = preview.backdrop()

modules/Preview/fitToSilhouette

fitToSilhouette(cam: { [string]: any }, shoot: (number, number) -> string?, passes: number?,

Move a camera until what it photographs of its subject stands centred in the frame and spans TARGET_SPAN (82%) of it, measured from the pixels. The box's centre is not the silhouette's — a posed model leans, a lamp's head sits above its post, an effect's faint outer sparks reach past its bright core — so each pass takes a small shot, finds the subject as every pixel standing off the backdrop (the shot's own corner), re-aims the camera at the silhouette's centre and moves it in or out by how far the silhouette reaches. A subject's share of the frame does not scale evenly with distance, so each correction is measured again at the framing it produced. It is how an asset preview is framed; a shot over any flat backdrop frames the same way.

local settled = preview.fitToSilhouette(cam, shoot)

modules/Preview/fromEntities

fromEntities(makeFn: () -> any, opts: { [string]: any }?): PreviewResult

Instantiate entities via makeFn, auto-frame an offscreen camera to their bounds, render one frame, and return the still PNG (base64) + stats. Spawned entities are marked temporary and despawned after the render. Renders are serialised on the shared preview rig; renders requested while the preview queue is draining a batch join its shared pass, so each still shows only its own subject at single-render wall-clock.

Parameters

• makeFn () -> any — Function returning an entity id/proxy or array of them to preview.
• opts { [string]: any }? (optional) — { size? = { width, height }, angle? = { yaw, pitch }, entityBudget?, backdrop?, fit? } — entityBudget is the most entities the subject may compose, roots and everything under them (default 2000); past it the result is unavailable and says how many it composed. backdrop names one of preview.backdrops (default "studio"). fit is { minShare?, keep? }, how the camera is fitted to what it sees (preview.fitToSilhouette): a subject that is mostly empty space, such as a spray of sparks, frames on its body with a small minShare and a keep below 1.

preview.fromEntities(function() local e = entity.spawn("x"); e.component.add("Model", { model = meshRef:handle() }); return e end)

modules/Preview/fromRecipe

fromRecipe(ref: any, recipe: { [string]: any }, opts: { [string]: any }?): PreviewResult

Render ref by the preview recipe its type declares (see @builtin::assetTypes.assetType.shared.previewRecipe). instantiate stands the asset in the studio through its own instantiate. surface paints the material the type's ref.previewMaterial returns on recipe.mesh. image fits the first of recipe.files the asset holds to the frame, on the studio backdrop, rendering nothing — its result carries rendered = false. ref:preview() is what calls this; a caller holding a ref calls that.

Parameters

• ref any (optional) — The AssetRef to render.
• recipe { [string]: any } — The type's recipe, { kind, mesh?, files?, angle? }.
• opts { [string]: any }? (optional) — { size? = { width, height }, angle? = { yaw, pitch }, live? }.

preview.fromRecipe(ref, { kind = "surface", mesh = "sphere" })

modules/Preview/inputsFingerprint

inputsFingerprint(ref: any): string?

A fingerprint of the content an asset's preview pictures: every file of the asset that can change the picture, and the version of every asset those files reference. Its README.md and .metadata, its preview.png and where the asset sits are not part of it, so describing, renaming or moving an asset leaves it unchanged. A render records it in the preview it writes; isCurrent compares the two.

Parameters

• ref any (optional) — The asset's AssetRef.

print(preview.inputsFingerprint(matRef))

modules/Preview/isCurrent

isCurrent(ref: any): boolean

Whether an asset's preview.png pictures the asset as it is now: it exists and the fingerprint it recorded matches inputsFingerprint. A preview rendered before the asset's content last changed, or one that records no fingerprint, is not current.

Parameters

• ref any (optional) — The asset's AssetRef.

if not preview.isCurrent(matRef) then preview.schedulePreview(matRef) end

modules/Preview/liveFromEntities

liveFromEntities(makeFn: () -> any, opts: { [string]: any }?): PreviewResult

Instantiate entities via makeFn and hold them under a live orbiting camera instead of capturing a still: the returned session's rtHandle names a render target that camera writes EVERY frame (a UI image node with src = rtHandle shows it live), setOrbit(yaw, pitch, dist?) moves the camera around the subject's measured centre, and dispose() despawns the subject, light and camera and destroys the target. The session holds a key light over the subject the way a still render does. fromEntities routes here when opts.live is true, so every type's ref:preview({ live = true }) returns one of these with no wiring.

Parameters

• makeFn () -> any — Function returning an entity id/proxy or array of them to preview.
• opts { [string]: any }? (optional) — { live = true, size? = { width, height }, angle? = { yaw, pitch }, entityBudget?, deferFraming? } — entityBudget bounds the subject exactly as fromEntities does. deferFraming returns the session as soon as the subject stands, without waiting for it to report bounds: the camera and light stand for a unit box until the subject measures, and are placed again whenever its bounds change by more than a quarter of its extent (getBounds answers the bounds the session stands for).

local p = matRef:preview({ live = true })

modules/Preview/onWritten

onWritten(fn: (path: string) -> ()): () -> ()

Call fn(assetPath) whenever an asset's preview file is written with new bytes — a consumer showing the picture, which asked for it with schedulePreview(ref, { requested = true }), redraws when it lands.

Parameters

• fn (path: string) -> () — Called with the asset's folder path.

Returns () — A function that stops fn being called.

local stop = preview.onWritten(function(path) print("new picture for", path) end)

modules/Preview/queueStateOf

queueStateOf(path: string): { [string]: any }?

Where the preview work queue stands on one asset.

Parameters

• path string — The asset's VFS path, with or without the /zero prefix.

local s = preview.queueStateOf("/source/gold.material")

modules/Preview/queueStatus

queueStatus(): { [string]: any }

Report the preview work queue: how many renders are pending, the batch currently rendering, what holds the queue when it is waiting, session totals, and the most recent failures. Reading it starts a drain when work is queued and none is running, so a queue whose drain stopped resumes on the next read.

local s = preview.queueStatus(); print(s.pending, s.active, s.held)

modules/Preview/recordedFingerprint

recordedFingerprint(ref: any): string?

The fingerprint an asset's preview.png recorded when it was rendered, or nil when there is no preview or it records none.

Parameters

• ref any (optional) — The asset's AssetRef.

print(preview.recordedFingerprint(matRef))

modules/Preview/registerDerivedHooks

registerDerivedHooks(): { string }

Register the <type>.preview derive hook of every asset type that declares a preview recipe, so staging such an asset reserves its preview.png. The hook is required when the type's type.yaml lists preview.png under files.required. A type already registered is left as it is.

modules/Preview/renderForReservation

renderForReservation(snapshot: any, reservation: any): (boolean, string?, string?)

Render the preview a derive reservation asks for: the staged content snapshot holds, pictured through its type's ref:preview() at 256x256 and returned as PNG bytes recording the fingerprint of that content. The render waits while the engine is in play mode. When the live asset is still the staged content it renders from the live asset; when it was edited or removed after it was staged, the staged files are mounted under /zero/source/tmp/derive-snapshots/<fingerprint>/ and rendered from that copy, which is removed again however the render ends. The copy lands whole, every staged file at once, and a reference it makes to the asset or to an asset within it (a material's own texture) names that asset's copy, so the picture is of the staged files alone. An asset the stage holds no file of is refused with the reason. A subject that draws nothing has no picture: the answer is true, nil, "empty", which the derive runner settles as an empty reservation.

Parameters

• snapshot any (optional) — The derive snapshot of the asset: path, files, deps, read.
• reservation any (optional) — The reservation row; its expected_fingerprint, when set, is the fingerprint the picture records.

local ok, bytes, kind = preview.renderForReservation(snapshot, row)

modules/Preview/renderStaleFor

renderStaleFor(paths: { string }): { string }

Queue a render for every asset holding one of paths whose type declares a preview recipe and whose preview is missing or not current (isCurrent), given the paths of staged files or asset folders: each asset on the way down to a path is asked, since a bundle's picture holds its interior material's. Staging does not call it. The renders run on the preview queue, so the caller waits for none of them, and each new picture is a change to the asset's preview.png. The queue's own rules still apply: library, dependency and scratch content keep the picture they carry, and a private subasset with no preview renders only when something asks for its picture.

Parameters

• paths { string } — VFS paths of staged files or asset folders.

preview.renderStaleFor({ "/zero/source/gold.material/mat.yaml" })

modules/Preview/rendering

rendering(): boolean

Whether a preview render is under way: a batch of the work queue, or a render holding the preview rig. A render under way stands the scratch it draws through (its subjects, its capture targets, the clock its deterministic captures pin), and all of it goes when the render ends. A queued entry is under way once the batch that takes it begins.

Each is known by the engine frame it began on and bounded by the frames it can last: a batch by preview.RENDER_FRAMES, a hold of the rig by the frames past which the next waiter takes the rig. One older than its bound was left by a pass that stopped existing, and reads as ended. The answer reads the same from any caller.

while preview.rendering() do task.wait() end

modules/Preview/schedulePreview

schedulePreview(ref: any, opts: { [string]: any }?)

Queue a writePreview for ref on the preview work queue. Something that needs the picture calls this: a view that shows the asset (requested), a backfill over a world, renderStaleFor. An edit of the asset queues nothing; its preview goes stale until one of those asks. Schedules that land while the asset is queued render once, reading the asset as it is when its turn comes. Renders drain in shared batches in schedule order; poll queueStatus for progress. Only world source content under /zero/source/ is queued: scratch (/source/tmp/) carries no preview, and library content (/source/libs/) and pulled dependencies (/source/deps/) keep the picture they were committed or published with, which a direct writePreview call redraws. The queue renders in edit mode: what is scheduled while the engine plays stays pending and renders once the engine is back in edit.

Parameters

• ref any (optional) — The asset's AssetRef.
• opts { [string]: any }? (optional) — { debounce?: number, requested?: boolean } — debounce is the seconds the entry waits before its render becomes eligible (default 1; a backfill pass over settled content passes 0). requested says something wants this asset's picture: a private subasset (asset.isPrivateSubasset) is previewed only when requested or when it already holds a preview.

preview.schedulePreview(matRef)

modules/Preview/staleAssets

staleAssets(root: string?): { string }

The world's own assets whose preview.png pictures content they no longer hold: every instance of a type that declares a preview recipe, under root when one is given, that has a preview which is not current (isCurrent). Library, dependency and scratch content keep the picture they carry and are not listed. Reads only; staging the asset renders its current picture.

Parameters

• root string? (optional) — A path prefix to narrow the walk to; the whole world when absent.

for _, p in ipairs(preview.staleAssets()) do print(p) end

modules/Preview/writePreview

writePreview(ref: any, opts: { [string]: any }?): (boolean, string?)

Render an asset's preview via its type's ref:preview() and persist it as preview.png inside the asset folder. The preview is the asset's visual description — it syncs and publishes like any other file, feeds image-based search, and gives browsers a thumbnail. Skips scratch content (/source/tmp/). Writes only when the rendered bytes differ from the existing file, so re-rendering an unchanged asset produces no sync traffic. This call is how a library or dependency asset's picture is redrawn: the preview queue leaves that content with the picture it carries, and in a --dev engine the file written here for a @builtin asset lands in the source checkout, to be committed with the asset.

Parameters

• ref any (optional) — The asset's AssetRef — its type must expose preview (material, texture, bundle).
• opts { [string]: any }? (optional) — Forwarded to ref:preview(); defaults to a 256×256 render.

preview.writePreview(matRef)

modules/ProcGraphAssetTypeBehavior/README

require("@builtin::systems.procgen.procGraph.behavior") -- ProcGraphAssetTypeBehavior

Per-instance methods exposed on every AssetRef<procGraph> — a .procGraph asset is a serialized procedural graph (proc.graph.v1). The methods below let callers use the graph THROUGH its ref (ref:eval("output:mesh"), ref:inputs(), ref:asOp()) instead of round-tripping through the proc module + a path string. asOp is also how the op registry resolves a .procGraph referenced as a graph node: the type owns "how a graph becomes an op", the evaluator's registry delegates to it. Loaded lazily by assetType.shared.ref via require("@builtin::systems.procgen.procGraph.behavior") the first time a procGraph ref is touched in a VM.

Usage: local ProcGraphAssetTypeBehavior = require("@builtin::systems.procgen.procGraph.behavior")

modules/ProcGraphAssetTypeBehavior/asOp

asOp(self): any

Wrap this graph as an op def so it can be used as a NODE in another graph: its params mirror this graph's declared inputs, its outputs mirror this graph's declared outputs, and its version folds this graph's structure with every content op it references (so an edit anywhere beneath re-keys the wrapping node). The op registry resolves a graph node whose op is a .procGraph ref through this method — the type owns the graph-as-op mapping; the evaluator's wrapGraphAsOp is the library that does the heavy folding.

Parameters

• self any (optional)

local opDef = procRef:asOp()

modules/ProcGraphAssetTypeBehavior/compile

compile(self): { [string]: any }

Compile this asset's init.luau into its graph.json — the serialized form the evaluator loads when another graph composites this one, and the file whose write makes every live Generator bound to this asset re-cook. This is the SOURCE step, not the evaluation step: it produces the graph, it does not run it (that is a cook, which the Generator drives). The type compiles on its own whenever the source is written, so calling this is only for forcing it — a rebuild after restoring a file, or a script that wants the node count back.

Parameters

• self any (optional)

local r = procRef:compile()

modules/ProcGraphAssetTypeBehavior/eval

eval(self, target: string, opts: any?): any

Evaluate one output of this graph and return the produced value (Geometry / Population / Texture / Material / Bundle / …). target is an output name ("mesh"), or an explicit "output:<name>" / "node:<id>[:<out>]" selector. opts forwards to proc.eval ({ inputs = { … }, seed = N }) so the graph's exposed inputs can be overridden per call.

Parameters

• self any (optional)
• target string — Output name or selector.
• opts any? (optional) — Optional { inputs, seed, … } (see proc.eval).

local mesh = procRef:eval("mesh", { inputs = { radius = 3 } })

modules/ProcGraphAssetTypeBehavior/graph

graph(self): any

This asset's procedural graph, built from its init.luau source. The source is the graph's definition, so this answers with what the asset currently describes rather than with whatever was last compiled.

Parameters

• self any (optional)

local g = procRef:graph()

modules/ProcGraphAssetTypeBehavior/inputs

inputs(self): { [string]: any }

The graph's declared inputs — the parameters that drive it, each with its procgen type and default. This is the vocabulary a Generator exposes as editable overrides.

Parameters

• self any (optional)

for name, decl in pairs(procRef:inputs()) do print(name, decl.type) end

modules/ProcGraphAssetTypeBehavior/instantiate

instantiate(self, target: EntityRef?, opts: { [string]: any }?): (EntityRef, { [string]: string })

Put this graph in the scene — the uniform instantiate(target?, opts?) contract every scene-instantiable asset answers to. An entity carrying a Generator bound to this asset: the Generator cooks the graph and keeps the result as that entity's managed children, re-cooking whenever the graph or its params change — so the scene holds a live instance of the description, not a frozen copy of one evaluation. With target the generator spawns as a child of that owner (so an owning Asset component tears it down with its other children); with no target it is a fresh root. The base opts — position, rotation, scale, name, temporary — place the root.

Parameters

• self any (optional)
• target EntityRef? (optional) — Optional owning entity ref.
• opts { [string]: any }? (optional) — { position?, rotation?, scale?, name?, temporary?, output?, params? } — output names which declared output to realize, params seeds the graph's exposed inputs.

local gen = procRef:instantiate()
local gen = procRef:instantiate(nil, { params = { rockCount = 800 } })

modules/ProcGraphAssetTypeBehavior/onChange

onChange(ref, change)

Change callback: recompile whenever the entry source is written. The graph.json this produces lands inside the same folder, which is what a live Generator bound to this asset watches — so editing the source is the whole update path, with no build step between writing and seeing it. Writes to any other file in the folder (that graph.json, the README, the sidecars) are not the definition and do not recompile — by the path filter here, and by the compiled-source guard for a change that names no path.

Parameters

• ref any (optional)
• change any (optional)

modules/ProcGraphAssetTypeBehavior/onRegister

onRegister(self)

Initial-registration callback: compile the graph the moment the instance registers, so an asset restored without a graph.json — or one whose source changed while the engine was down — has its compiled form before anything composites or cooks it.

Parameters

• self any (optional)

modules/ProcGraphAssetTypeBehavior/outputs

outputs(self): { string }

The graph's declared output names (sorted). Each is a value the graph produces and a valid eval target.

Parameters

• self any (optional)

local outs = procRef:outputs()

modules/ProcGraphAssetTypeBehavior/preview

preview(self, opts: { [string]: any }?): { [string]: any }

Render this graph to a still through the shared preview rig — the image preview.writePreview persists as the asset's preview.png, the picture search shows the graph by. The graph stands in the preview studio on a Generator of its own; an effect is brought to a representative moment (the one it names with g:still, else halfway through the range it plays, or two seconds into a timeline with no end) before the frame is taken, so the picture is the effect in motion rather than its first frame. A timeline with an end is moved to that moment; one with no end is played to it, since what it shows then is everything its solvers simulated before.

Parameters

• self any (optional)
• opts { [string]: any }? (optional) — { size? = { width, height }, angle? = { yaw, pitch } }.

local shot = graphRef:preview({ size = { width = 256, height = 256 } })

modules/ProcGraphAssetTypeBehavior/promote

promote(self, opts: { [string]: any }?): { [string]: any }

Make this graph a node: a .procNode that declares this graph's inputs as its own, calls this graph with them and gives its outputs. This graph keeps its code and every graph calling it by its path; the node puts it among the nodes procgen.searchNodes finds and a graph calls by name, and it stays this graph's: editing this graph changes what the node makes. procgen.promote is the tool form.

Parameters

• self any (optional)
• opts { [string]: any }? (optional) — Optional { name, into, description, tags }: the node's name (default: this graph's), the folder it goes in (default: the one holding this graph), what it does and the tags search finds it by (default: this graph's own .metadata).

local made = procRef:promote({ description = "A rim of rocks around a disc." })

modules/ProcGraphAssetTypeBehavior/stillTime

stillTime(self): number

The moment a still of this graph shows: the one it names with g:still, else halfway through the range it plays, or two seconds into a timeline with no end.

Parameters

• self any (optional)

gen:seek(graphRef:stillTime())

modules/ProcGraphAssetTypeBehavior/validate

validate(self): { any }

Type-check this graph's connections. Returns proc.validate's diagnostic list (empty when the graph is well-typed) — each entry is { level, code, node, input, expected, actual, suggestions }.

Parameters

• self any (optional)

for _, d in ipairs(procRef:validate()) do warn(d.code, d.node, d.input) end

modules/ProcNodeAssetTypeBehavior/README

require("@builtin::systems.procgen.procNode.behavior") -- ProcNodeAssetTypeBehavior

Registration lifecycle for .procNode assets — custom procedural operations authored as content. An instance's init.luau returns either a GRAPH (return proc.define(...) — the node carrying its own pipeline, the self-contained form) or a def table (op-style { inputs, params, outputs, eval } for a hand-written eval). What a node takes and gives is read from that source without running it (asset.interface), the interface: block of the type's type.yaml saying how; this behaviour loads the node's op into the proc op registry, keyed by the asset's stable GUID, when a build first runs it, and again on every edit after that.

Usage: local ProcNodeAssetTypeBehavior = require("@builtin::systems.procgen.procNode.behavior")

modules/ProcNodeAssetTypeBehavior/load

load(ref)

Load this node's op from its entry source into the proc op registry: the registry calls it the first time a build runs the node.

Parameters

• ref any (optional)

modules/ProcNodeAssetTypeBehavior/onChange

onChange(ref, _change)

Change callback: a node a build has loaded loads again from its current entry source whenever its .procNode is written, and the version bump propagates the edit to every graph that reaches the node. A node no build has run has nothing loaded: its interface is read from the source as it now stands.

Parameters

• ref any (optional)
• _change any (optional)

modules/ProcNodeAssetTypeBehavior/onDelete

onDelete(ref)

Delete callback: unregister this node's op when its .procNode folder is removed. The delete ref carries no guid (the folder is already gone), so the guid is resolved from the removed folder path via the registry's path->guid index. A graph referencing it afterward errors loudly at eval — resolution is push-model, never a silent fallback. A node moved to another folder keeps its guid and stays registered at the folder it moved to.

Parameters

• ref any (optional)

modules/ProcNodeAssetTypeBehavior/onRegister

onRegister(self)

Initial-registration callback. The node's interface is read from its source wherever the asset index lists it, so nothing runs here unless a build already loaded the node, which then loads again.

Parameters

• self any (optional)

modules/ProcNodeAssetTypeBehavior/validate

validate(ref): { { code: string, message: string, severity: string? } }

The node's own rules: its source declares its interface as literals, so what it takes and gives reads without running it; its entry source loads and returns a def or a graph; and it registers as an op.

Parameters

• ref any (optional)

modules/ProcPackAssetTypeBehavior/README

require("@builtin::systems.procgen.procPack.behavior") -- ProcPackAssetTypeBehavior

Registration lifecycle for .procPack assets — a FAMILY of procedural operations authored as content. The instance's init.luau returns a pack table whose ops map op id to def, and this behaviour registers the whole map through registry.registerPack, so every op is validated exactly as a builtin is and tagged with the pack it came from. Ops registered this way carry the STABLE STRING IDS the pack names them with, which is what separates a pack from a .procNode — a single op keyed by its asset guid.

Usage: local ProcPackAssetTypeBehavior = require("@builtin::systems.procgen.procPack.behavior")

modules/ProcPackAssetTypeBehavior/onChange

onChange(ref, _change)

Change callback: re-register the family whenever the .procPack is seeded or its entry script is edited. Every op is re-registered from the current source and the version bump propagates the edit to every graph that reaches any of them; an op the edit removed is unregistered.

Parameters

• ref any (optional)
• _change any (optional)

modules/ProcPackAssetTypeBehavior/onDelete

onDelete(ref)

Delete callback: unregister every op this pack registered, and the pack itself, when its .procPack folder is removed. A graph naming one of its ops afterwards errors loudly at eval rather than cooking against a definition that no longer exists, and registry.pack answers nil.

Parameters

• ref any (optional)

modules/ProcPackAssetTypeBehavior/onDependencyChange

onDependencyChange(ref, _change)

Dependency callback: a module the pack's entry requires re-ran, so the op definitions the pack built from it are built again from the module as it now stands, and every graph reaching one of them recooks.

Parameters

• ref any (optional)
• _change any (optional)

modules/ProcPackAssetTypeBehavior/onRegister

onRegister(self)

Initial-registration callback: register this pack's whole family the moment the instance first registers, so a graph loaded in the same world-ready sweep can resolve every op in it. Idempotent with onChange.

Parameters

• self any (optional)

modules/ProcPackAssetTypeBehavior/ops

ops(self): { string }

The op ids this pack registers, sorted: the ids its ops table declares, as its last completed registration read them. The former ids its aliases maps onto them answer only as aliases. A pack whose last registration did not complete, or that was never registered here, reads its entry script to answer.

Parameters

• self any (optional)

for _, id in ipairs(packRef:ops()) do print(id) end

modules/ProcPackAssetTypeBehavior/registered

registered(path: string): boolean

Whether the pack at path has a registration that completed in this VM: every op its last registration declared stands in the registry. A registration still under way, or one that did not complete, answers false.

Parameters

• path string — The pack's folder path.

if not behavior.registered(path) then behavior.onRegister(ref) end

modules/ProcRecordAssetTypeRef/README

require("@builtin::systems.procgen.procRecord.behavior") -- ProcRecordAssetTypeRef

Per-instance methods exposed on every AssetRef<procRecord>.

Usage: local ProcRecordAssetTypeRef = require("@builtin::systems.procgen.procRecord.behavior")

modules/ProcRecordAssetTypeRef/definition

definition(self): any

The record kind this asset defines: what its init.luau returns through proc.record.

Parameters

• self any (optional)

local def = asset.resolve("@builtin::systems.procgen.records.material", "procRecord"):definition()

modules/PunctualLight/README

require("@builtin::tests.fixtures.punctual_light") -- PunctualLight

The engine's punctual-light response in Luau, for the suites that predict what light a point light puts on a surface: the windowed inverse-square falloff a light's radius defines, the radiance that falloff delivers, and the shading model's own answer at the one geometry that has a closed form — the surface normal, the direction to the camera and the direction to the light all the same vector. The falloff is a port of zero_punctual_falloff in engine_bindings.shaderModule, which is the one curve every reader of a light's reach answers from. The response is a port of zpbr_direct_full in pbr_shading.shaderModule, evaluated at that geometry, where every angular term is 1 and the microfacet lobes collapse to constants.

Usage: local PunctualLight = require("@builtin::tests.fixtures.punctual_light")

modules/PunctualLight/dielectricF0

dielectricF0(ior: number, reflectance: number): number

A dielectric's reflectance at normal incidence, from its index of refraction and the artist reflectance knob — zpbr_dielectric_f0. The PBR shader's defaults (ior 1.5, reflectance 0.5) give 0.04.

Parameters

• ior number — The surface's index of refraction.
• reflectance number — The [0, 1] reflectance knob, neutral at 0.5.

local f0 = PunctualLight.dielectricF0(1.5, 0.5)

modules/PunctualLight/falloff

falloff(dist: number, radius: number): number

How much of a punctual light's emitted power arrives at dist: the inverse-square law, windowed to zero at the light's radius. The engine's own curve, zero_punctual_falloff.

Parameters

• dist number — Distance from the light to the shaded point, in world units.
• radius number — The light's reach — a Light component's range.

local a = PunctualLight.falloff(2.0, 8.0)

modules/PunctualLight/normalIncidenceResponse

normalIncidenceResponse(

The light a surface answers for one radiance arriving along its own normal, while the camera also looks along that normal.

zpbr_direct_full evaluated where the normal, the view direction and the light direction coincide: the half-vector is the normal, so every one of n·h, n·v, v·h and n·l is 1, the Fresnel term is F0 itself, the GGX distribution is α²/(π·α⁴) and the Smith visibility is 1 at any roughness. What is left is a diffuse lobe and a specular lobe that are both constants of the surface, which is what lets a case state the light it expects as a number.

This models the diffuse and specular lobes alone — the ones a bare metal or dielectric surface shades with. Clearcoat, sheen, fibre, anisotropy and iridescence are lobes the PBR shader adds on top where a material's own properties ask for them.

local L = PunctualLight.normalIncidenceResponse(

modules/PunctualLight/radiance

radiance(color: { number }, intensity: number, dist: number, radius: number): { number }

The radiance one punctual light delivers at dist: its colour times its intensity times the falloff at that distance. The quantity the shading loop hands the BRDF, for a light with no cone, no cookie and no shadow.

Parameters

• color { number } — The light's colour, one entry per channel.
• intensity number — The light's intensity.
• dist number — Distance from the light to the shaded point, in world units.
• radius number — The light's reach — a Light component's range.

local r = PunctualLight.radiance({ 1, 0.6, 0.3 }, 4, 2.0, 8.0)

modules/Queue/README

require("@builtin::modules.api.engine.ecs.queue") -- Queue (also available as global 'queue')

Defer FFI mutations across frames — queue(fn) -> (ok, err, drainPromise).

Inside the body, write FFI calls (entity.spawn, component.add, position.set, etc.) enqueue rather than execute synchronously. The engine's per-frame drainer applies them in FIFO order with a per-frame budget. Returns (true, nil, drainPromise) on success, (false, err, nil) if the body throws — in which case the mutations the body queued are dropped so they do not later apply; what other code queued stays. drainPromise is a promise handle that resolves once every mutation queued inside fn has been applied by the engine drainer. await(drainPromise) blocks the calling coroutine until full drain — use this to gate post-queue work (scene/layer load fires onLoad after the drain promise resolves). If nothing was queued (e.g. an empty fn), the promise resolves before queue() returns. Nested queue() runs in the already-active queue mode: the depth counter is re-entrant, and an inner body that throws drops only what it queued. See docs/plans/2026-05-06-luau-queue-deferred-mutations.md for the full design (drain budget, error semantics, future per-key fences for reads).

Usage: local Queue = require("@builtin::modules.api.engine.ecs.queue") Also available as global: queue

modules/Random/README

require("@builtin::modules.random") -- Random (also available as global 'Random')

Seeded random-number generators. Each generator holds its own stream, so any number of independent, reproducible sequences run side by side, and none of them draws from or reseeds math.random.

A generator made from a seed produces the same sequence on every platform and every build: the same seed gives the same numbers on a native engine and in the browser, run after run. local rng = Random.new(1234) -- the same seed, the same stream local roll = rng:nextInteger(1, 6) -- integer in [1, 6], both ends included local t = rng:nextNumber() -- float in [0, 1) local x = rng:nextNumber(-5, 5) -- float in [-5, 5) Members every generator answers: rng:nextNumber() float in [0, 1), 53 random bits rng:nextNumber(min, max) float in [min, max) rng:nextInteger(min, max) integer in [min, max], both ends included, every value equally likely rng:clone() an independent generator at the same position: it draws what this one would draw next rng:state() the position as a 32-character hex string a save, a record or a network message can hold Random.fromState(rng:state()) makes a generator that continues the sequence from where rng stood, so a saved level, a replayed AI decision or a regenerated design picks up exactly where it left off. Random.new() with no seed takes its seed from the clock. math.random is a different thing: one stream per Luau VM, shared by every script in that VM and reseeded for all of them by math.randomseed. A generator here is a value of its own; drawing from one moves no other. The algorithm is xoshiro128** (Blackman and Vigna) over 32-bit words. A seed is read as the bits of its IEEE-754 double: the low word and the high word each go through the MurmurHash3 32-bit finalizer to give the first two state words, and the last two are mixed from those, so every distinct number is a distinct stream. nextNumber() joins the top 27 bits of one output and the top 26 of the next into a 53-bit fraction; nextInteger rejects the draws that would bias the range.

Usage: local Random = require("@builtin::modules.random") Also available as global: Random

modules/Random/fromState

fromState(state: string): RandomGenerator

Make a generator that continues a sequence from a position rng:state() recorded. It draws exactly what the recorded generator drew next, so a save holds the string and a load picks the stream up.

Parameters

• state string — The 32-character hex string rng:state() returned.

local resumed = Random.fromState(Random.new(7):state())

modules/Random/new

new(seed: number?): RandomGenerator

Make a generator with its own stream. The same seed gives the same sequence on every platform and build; any number of generators run side by side without moving one another or math.random. With no seed it takes one from the clock, and rng:state() records where it stands.

Parameters

• seed number? (optional) — Any finite number; every distinct number is a distinct stream. Omitted, the clock seeds it.

local roll = Random.new(42):nextInteger(1, 6)
local jitter = Random.new(42):nextNumber(-0.5, 0.5)
local clockSeeded = Random.new()

modules/RenderError/README

require("@builtin::modules.renderError") -- RenderError

Shared "this render is broken" marker. visibleError(entityId) swaps an entity to the builtin ERROR text model + error material, so a failed render reads as an unmistakable 3D "ERROR" sign on screen instead of empty pixels — empty silently reads as "fine" and a broken object gets mistaken for working. Every render component (built-in Model / SkinnedModel, or a user-authored one) calls this, so the error model is defined in ONE place: change it here and every render component updates.

Usage: local RenderError = require("@builtin::modules.renderError")

modules/RenderError/visibleError

visibleError(entityId: string, reason: string?): boolean

Swap entityId to the builtin ERROR marker so a broken render is unmistakable on screen. Un-skins the entity first (a bad skeleton can't collapse the marker), binds the ERROR mesh + error material via the public ecs.* API, and logs the reason at error level. Returns true if the marker was applied.

Parameters

• entityId string — The entity whose renderable becomes the ERROR marker.
• reason string? (optional) — Short human string describing what failed (logged).

renderError.visibleError(self.entityId, "mesh never became GPU-resident")

modules/RenderFeatureAssetTypeRef/README

require("@builtin::assetTypes.renderFeature.behavior") -- RenderFeatureAssetTypeRef

Per-instance methods exposed on every AssetRef<renderFeature>. Loaded lazily by assetType.shared.ref the first time a renderFeature ref is touched in a VM. A render feature is an init.luau exporting { setup?(ctx), render(ctx), teardown?(ctx) }; :enable() instantiates it (the engine begins calling its render(ctx) hook every frame) and returns a live handle, also visible under /zero/runtime/renderFeatures/.

Usage: local RenderFeatureAssetTypeRef = require("@builtin::assetTypes.renderFeature.behavior")

modules/RenderFeatureShared/README

require("@builtin::assetTypes.renderFeature.shared") -- RenderFeatureShared

Shared helpers + the authoring contract for renderFeature modules.

Usage: local RenderFeatureShared = require("@builtin::assetTypes.renderFeature.shared")

modules/ReportFormatter/README

require("@builtin::systems.worldValidation.reportFormatter") -- ReportFormatter

Filtering + formatting helpers for the world validation report. Pure functions: every call returns a new value, never mutates the input report.

Three exports: filter (re-filter an existing Report without re-scanning the VFS), format (render to a string in one of four shapes), and summary (one-line health line). All three are pure — they never mutate the input report.

Usage: local ReportFormatter = require("@builtin::systems.worldValidation.reportFormatter")

modules/ReportFormatter/filter

filter(report, opts)

Return a new Report containing only problems that match the filter options. Counts are recomputed from the filtered set so the caller can trust counts against the visible problems list. Pure — the input report is not mutated.

Parameters

• report any (optional) — Report produced by the main validator.
• opts any (optional) — Filter options — { severity, category, source, code, path (Lua pattern), includePlaceholders (default true), limit }.

local errs = ReportFormatter.filter(r, { severity = "error" })
local libsOnly = ReportFormatter.filter(r, { source = "library:@builtin" })

modules/ReportFormatter/format

format(report, format)

Render a Report into a string in the chosen format.

Parameters

• report any (optional) — Report produced by the main validator.
• format any (optional) — One of "human" (default), "markdown", "json", "summary". Unknown values fall back to "human".

print(ReportFormatter.format(r, "human"))
local md = ReportFormatter.format(r, "markdown")

modules/ReportFormatter/summary

summary(report)

Compact one-line health summary string — world: NE/NW libraries: NE/NW total: OK|FAIL.

Parameters

• report any (optional) — Report produced by the main validator.

print(ReportFormatter.summary(r))

modules/ResourceHandle/README

require("@builtin::modules.resource_handle") -- ResourceHandle

Recognises a live GPU resource handle — the { kind = "<Category>Handle", category, guid, name } table renderer.mesh.create, renderer.material.create and renderer.texture.create return. Every boundary that carries a component field value out of the session that produced it consults this to tell a handle from an AssetRef.

Usage: local ResourceHandle = require("@builtin::modules.resource_handle")

modules/ResourceHandle/forget

forget(owner: string)

Let go of every handle parked for owner. A parked handle is put back by a load that builds the entity from its record inside this session, so once no record names the entity, nothing reads it again.

Parameters

• owner string — The entity id the handles were parked under.

ResourceHandle.forget(id)

modules/ResourceHandle/isLive

isLive(v: any): boolean

Whether a value is a live GPU resource handle.

Parameters

• v any (optional) — Any component field value.

ResourceHandle.isLive(renderer.mesh.create(geometry)) -- true

modules/ResourceHandle/label

label(v: any): string

A short phrase naming a handle, for a message about the value.

Parameters

• v any (optional) — A handle table.

ResourceHandle.label(meshHandle) -- "mesh handle 'msh_grass_1'"

modules/ResourceHandle/park

park(owner: string, componentType: string, dropped: { [string]: any }?, instanceName: string?)

Hold the live handles one component instance's durable record left out, keyed by the entity and component instance they came from, until forget lets go of the entity. Each call replaces what that instance had parked before.

Parameters

• owner string — The entity id the component sits on.
• componentType string — The component's type name.
• dropped { [string]: any }? (optional) — The { field = handle } map left out of the record, or nil when the component's record carries every field it holds.
• instanceName string? (optional) — The instance's name, or nil for the type's anonymous instance.

ResourceHandle.park(id, "@builtin::components.Model", { model = mesh })

modules/ResourceHandle/withParked

withParked(data: any, owner: string, componentType: string, instanceName: string?): (any, number)

The component field map to apply, with every field this session parked for owner's instance of componentType and the record does not carry put back.

Parameters

• data any (optional) — A component's { field = value } map from a record.
• owner string — The entity id the component is being applied to.
• componentType string — The component's type name.
• instanceName string? (optional) — The instance's name, or nil for the type's anonymous instance.

ResourceHandle.withParked(record.data, id, "@builtin::components.Model")

modules/ResourceHandle/withoutLive

withoutLive(data: any): (any, { [string]: string }?)

The component field map to apply, with any live-handle value left out — the form a value read from durable content takes in a session other than the one that minted it. The field falls back to the component's declared default, and the caller reports what it stood for.

Parameters

• data any (optional) — A component's { field = value } map.

ResourceHandle.withoutLive(record.data) -- data, nil

modules/RigAssetTypeBehavior/README

require("@builtin::assetTypes.rig.behavior") -- RigAssetTypeBehavior

Behaviour for the rig asset type — a skeleton's disk shape. The payload is rig.json: ordered bones with names, parent hierarchy, the node index each maps to, rest local transform and inverse-bind matrix, where its bind pose comes from (bind), plus the author's overrides — per avatar type, the roles an author set by hand. How the rig maps onto an avatar type (which bone is the hips, the left hand, ...) is derived from the bones whenever it is asked for, and the overrides are laid over it. A rig is its own primitive: a skinned mesh references a rig, an animation references its source rig, and retargeting maps one rig onto another. The format is text, so an agent can open it and read or correct it with an edit.

Usage: local RigAssetTypeBehavior = require("@builtin::assetTypes.rig.behavior")

modules/RigAssetTypeBehavior/onChange

onChange(self, _change)

Drop the cached decode and every qualification made from it when the rig's content changes — a hot-reload, a re-import or an override edit — so the next read re-derives from the new rig.json.

Parameters

• self any (optional) — The rig AssetRef that changed.
• _change any (optional) — What happened to it; the caches are dropped whatever it was.

modules/RigAssetTypeBehavior/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

Generic-creation hook for asset.create("rig", name, opts). Returns the content-file map; asset.create writes it to the authored destination, registering the .rig asset under its minted guid. A profile or humanoid section in the incoming document is dropped: how a rig maps onto an avatar type is derived from its bones.

Parameters

• name string — Rig identity (the instance name).
• opts CreateOpts

asset.create("rig", "PolygonSyntyCharacter", { json = rigJson })

modules/RigAssetTypeBehavior/onReplace

onReplace(dest: string, files: { [string]: string }): { [string]: string }

Replacement hook: when asset.create writes a rig over one already at dest (a re-import re-deriving the rig from its source file), the replaced rig's overrides are carried into the new document, so what an author set by hand survives. Overrides the new document states itself win for their type.

Parameters

• dest string — The folder of the rig being replaced.
• files { [string]: string } — The files onCreate produced for the new rig.

modules/SceneAssetTypeRef/README

require("@builtin::assetTypes.scene.behavior") -- SceneAssetTypeRef

Per-instance methods exposed on every AssetRef<scene>. Loaded lazily by assetType.shared.ref.

Usage: local SceneAssetTypeRef = require("@builtin::assetTypes.scene.behavior")

modules/SceneAssetTypeRef/build_scene

build_scene(self, opts: { save: boolean?, record: boolean?, layer: any?, trigger: string? }?): any

Run this scene's build.luau against what it resolves right now and land what it declares in the scene — for the case where something the builder reads changed and the file did not. Writing build.luau already runs the build, so a call after a write is unnecessary. content() writes the scene's entities and editorOnly() writes the ones that are present while authoring and absent in play; each is reconciled against the entities the last build placed, so an entity keeps its id across every rebuild and anything else in the scene is left alone. Runs in edit mode on a LOADED scene — the entities it lands on are the live ones. opts.save = false leaves the result unsaved; by default the scene is saved, which is what puts the build in scene.json. opts.record = false lands the result in the live scene alone: nothing it creates, changes or takes away reaches the scene's unsaved edits or scene.json. A call made while a build for this scene is running returns that build right away instead of starting a second one — a build the scheduler is still advancing. One whose task was cancelled, or that stopped for any other reason without returning, hands the scene back to this call, which runs the build. A build that a newer write to build.luau replaces stops where it stands and leaves the scene to the rebuild that write asked for.

Parameters

• self any (optional)
• opts { save: boolean?, record: boolean?, layer: any?, trigger: string? }? (optional) — Optional { save = false } or { record = false }.

layers.active.asset:build()

modules/SceneAssetTypeRef/discard_scene

discard_scene(self, opts: any): boolean

Discard this scene's UNSAVED (dirty) edits and restore its saved scene.json. When the scene is LOADED, the overlay is deleted and the live layer is respawned from canonical (with the scene-load gate held so the respawn is not re-marked dirty); when it is NOT loaded, the on-disk overlay is simply deleted. Edit-mode overlay only — not the play-mode baseline.

Parameters

• self any (optional)
• opts any (optional) — Optional { to = <name|path> }, or a bare name/path string, to target a scene other than this asset's own path.

sceneRef:discard()

modules/SceneAssetTypeRef/getBuildScript

getBuildScript(self): string?

Read the scene's build.luau body as raw text.

Parameters

• self any (optional)

local src = sceneRef:getBuildScript()

modules/SceneAssetTypeRef/getEntrypoint

getEntrypoint(self): string?

Read the scene's entrypoint.luau body as raw text.

Parameters

• self any (optional)

local code = sceneRef:getEntrypoint()

modules/SceneAssetTypeRef/getSceneJson

getSceneJson(self): { [string]: any }?

Parse the scene's scene.json into a Lua table.

Parameters

• self any (optional)

local s = sceneRef:getSceneJson()

modules/SceneAssetTypeRef/getSceneJsonRaw

getSceneJsonRaw(self): string?

Read the scene's scene.json body as raw JSON text.

Parameters

• self any (optional)

local raw = sceneRef:getSceneJsonRaw()

modules/SceneAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { entityCount, entityNames, player }, parsed from the scene's own scene.json — never executes entrypoint.luau. A scene whose scene.json can't be read/parsed returns an empty detail rather than erroring.

Parameters

• self any (optional)

local entityNames = asset.inspect(sceneRef).detail.entityNames

modules/SceneAssetTypeRef/listEntities

listEntities(self): { string }

List the entity names declared at the top level of the scene's JSON body. Best-effort; nested children are not flattened.

Parameters

• self any (optional)

for _, n in ipairs(sceneRef:listEntities()) do print(n) end

modules/SceneAssetTypeRef/load_scene

load_scene(self, opts: { [string]: any }?): any

Load this scene into the root ("main") slot. Equivalent to layers.load(self) — the AssetRef envelope is passed straight through, so the loader threads scene identity by guid. Pass opts for additive overlays / persistence / origin offset (same shape as layers.load's second argument).

Parameters

• self any (optional)
• opts { [string]: any }? (optional) — Optional load options forwarded to layers.load.

sceneRef:load()
sceneRef:load({ additive = true, name = "hud_overlay" })

modules/SceneAssetTypeRef/onChange

onChange(ref, change)

A write inside a .scene folder. A write to build.luau re-runs the build on the loaded scene, which is what makes an edit to the code show up in the scene without reloading it. The rebuild finishes after the write has returned, and posts a notice naming the scene and how many entities each surface placed — the write's own answer is that the file was written. A write that arrives while a rebuild is running gets a rebuild of its own once that one finishes, and several such writes get the single run that reads them all. A rebuild lands and saves over several frames; until it is through, layers.rebuildInFlight() reads true and a flip to play is refused. A write to entrypoint.luau reloads the layer holding the scene without rebuilding it: the previous load's onUnload runs and the tasks, callbacks and entities that load started end, then the new code runs and its onEditLoad fires. That reload also finishes after the write has returned and posts a notice saying whether the layer came back whole, and writes landing while it runs get one more reload once it finishes. A write holding the code the layer already runs (only comments and whitespace count as none) reloads nothing. Both apply in edit mode; an edit made in play runs at the scene's next load. A write to build.luau builds in every session sharing the world that has the scene loaded, whichever session made it. The session that made it records and saves what its build lands; every other one lands the build in its live scene alone, and the records and the save of the session that made the write land on the same entities, since each entity a build creates takes the id every session derives for it. When the session that made the write does not have the scene loaded, the scene's next save, or its next load, puts the build in scene.json.

Parameters

• ref any (optional) — The scene whose folder was written.
• change any (optional) — { path, asset, type, kind, origin }.

__zero_dispatch_asset_change("/zero/source/scenes/main.scene/build.luau")

modules/SceneAssetTypeRef/onCreate

onCreate(_name: string): { [string]: string }

Generic-creation hook for asset.create("scene", name). A new scene is the type's template shape verbatim.

Parameters

• _name string

asset.create("scene", "my_level")

modules/SceneAssetTypeRef/save_scene

save_scene(self, opts: any): any

Publish this scene's current state to its canonical scene.json. When the scene is LOADED, its live scenegraph is captured into canonical; when it is NOT loaded, its pending dirty overlay is promoted into canonical. Either way the durable scene.json ends up reflecting the authored state. opts.to (a scene name or path) saves to a different scene ("save as"). opts.layer is the layer holding this scene, for a caller that already has it: a scene is findable through layers.list only once its load has registered it, so a save made DURING that load names its layer itself and captures the live scenegraph rather than reading it as unloaded.

Parameters

• self any (optional)
• opts any (optional) — Optional { to = <name|path>, layer = <SceneProxy> }, or a bare name/path string.

sceneRef:save()
layers.active.asset:save({ to = "level_2" })

modules/SceneAssetTypeRef/validate

validate(self): { { code: string, severity: string, message: string } }

Semantic content validation for a scene: the player-setup rule set run over this scene's scene.json, surfaced through asset.validate, plus a warning when the scene has no explicit sky entity.

Parameters

• self any (optional)

modules/SceneBuild/README

require("@builtin::assetTypes.scene.shared.build") -- SceneBuild

Runs a builder function in an entity capture scope and composes what it created into records, then reconciles records into the scene with ids held stable across rebuilds. Also holds the build surface a build script reads, whose build.asset authors the assets a build produces and hands back the same one on every run the code has not changed.

Usage: local SceneBuild = require("@builtin::assetTypes.scene.shared.build")

modules/SceneBuild/attribute

attribute(refusals: { Refusal }): { Refusal }

Read a refusal's traceback for the one frame that belongs to the code being built. A build composed from several contributors reports this so an author reads which contributor was refused rather than which build ran.

Parameters

• refusals { Refusal } — The refusal array entity.capture hands back.

local named = SceneBuild.attribute(select(4, entity.capture(fn)))

modules/SceneBuild/buildSurface

buildSurface(folder: string, sourceDigest: string): BuildSurface

The build surface a build script reads: the operations that belong to the build itself rather than to the scene it states. build.asset(kind, name, produce) is the asset a build makes — produce runs when the build script changed and its result is authored at <folder>/<name>.<kind>, and every other run hands back that same asset, guid and all, without running produce at all. The returned AssetRef is what a component field names, so the reference survives the save and the reload.

Parameters

• folder string — The build's own folder, which the assets it produces are authored inside.
• sourceDigest string — The digest of the build script running now, as M.digest reports it — what decides whether an asset it produced is still the asset the code states.

local surface = SceneBuild.buildSurface(dir, SceneBuild.digest(src))

modules/SceneBuild/digest

digest(source: string): string

A short, stable digest of a script's source. Two different scripts give different digests, and the same script gives the same one on every machine and every run — which is what makes it the answer to "did the code that produced this change?".

Parameters

• source string — The script body to digest.

local key = SceneBuild.digest(vfs.read(path))

modules/SceneBuild/drift

drift(owner: string?): { Drift }

Where the live scene disagrees with the build that states it. Every entity a build placed records what that build last said about each of its properties, so anything an author has changed since reads back differently — and this is that list: the entity, the property, what the build said, and what the scene holds now.

These are the values a rebuild KEEPS. A build repeating itself leaves them alone, and only a build that states something DIFFERENT about that property takes it back. So this is what to read to know that a scene and its build.luau disagree, and where, before deciding which should win.

Property names are the ones the build records: n name, i internal, p position, r rotation, s scale, and a:<name> for an attribute.

Parameters

• owner string? (optional) — Optional build name, as M.ownerOf reports it, to read just that build. Omitted, every build-owned entity in the scene is read.

for _, d in ipairs(SceneBuild.drift()) do print(d.name, d.property) end

modules/SceneBuild/isStatedNothingRefusal

isStatedNothingRefusal(err: any): boolean

Whether err is the refusal reconcile raises for a build that stated no records while its scene loads over entities an earlier build placed. The refusal is about the module's text, which a later request for the same text states again, so a caller keeps the text it built as the one that stands.

Parameters

• err any (optional) — The value a build raised.

local refused = SceneBuild.isStatedNothingRefusal(err)

modules/SceneBuild/landed

landed(key: string, landing: Landing)

Record that the build landing stands for is through. An entry a later build of the same scene put in its place stands.

Parameters

• key string — The key the scene is known by.
• landing Landing — The entry noteLanding recorded for this build.

SceneBuild.landed(guid, entry)

modules/SceneBuild/landing

landing(): { { scene: string, startedBy: string } }

The builds landing in the live scene right now, one row per scene, ordered by scene. A build lands over many frames, and while one is landing the live scene holds part of what it produces and part of what the build before it produced. An entry whose build stopped without saying so is dropped here.

if #SceneBuild.landing() == 0 then engine.mode = "play" end

modules/SceneBuild/landingFor

landingFor(scene: { guid: string?, path: string? }): { scene: string, startedBy: string }?

The build landing in the live scene for one scene, named by its guid or by the folder it is stored in, or nil while none is. A build of that scene is carrying its records into the scene's layer and saving it, over many frames, while this answers a row; an entry whose build stopped without saying so is dropped here. A caller running on the build's own coroutine is that build, and is answered nil.

Parameters

• scene { guid: string?, path: string? } — { guid, path } of the scene, either one or both.

while SceneBuild.landingFor({ guid = ref.guid, path = ref.path }) do task.wait() end

modules/SceneBuild/noteLanding

noteLanding(key: string, landing: Landing)

Record that a build of the scene known as key is landing, from the moment it is started until it is through. The entry replaces any standing one for the same scene.

Parameters

• key string — The key the scene is known by: its guid, else its path.
• landing Landing — { scene, startedBy, advancing }: the scene's name, what started the build, and a function answering whether the build is still being carried out.

SceneBuild.noteLanding(guid, { scene = "main", startedBy = "a write to build.luau", advancing = function() return true end })

modules/SceneBuild/notePreview

notePreview(entityId: string, values: { [string]: any }, componentType: string?): nil

Record the values an author left on entityId, an entity a build owns. The build states that entity from its own source, so the values hold until it runs again — and M.takePreview is what the next run reads to say which of them it replaced and with what. Each record REPLACES the one before it: what it states is everything the entity carries now, so a name dropped between two records is dropped here too.

Parameters

• entityId string — Runtime entity id of the owned entity.
• values { [string]: any } — The values the entity carries now, by name.
• componentType string? (optional) — The component that states them, so a rebuild knows to state that type again instead of leaving it to the scene.

SceneBuild.notePreview(id, { count = 9 }, "SceneModule")

modules/SceneBuild/noteSourceWrite

noteSourceWrite(guid: string, origin: string?): nil

Record that a file of the asset guid, which a build is stated from (a .sceneModule a placement builds), was written, and by which session. Every session holding a build stated from it rebuilds; the session that made the write records what its rebuild lands, and every other session lands it in its live scene alone.

Parameters

• guid string — The asset's guid.
• origin string? (optional) — "local" for a write this session made (the default), "remote" for one another session sharing the world made.

SceneBuild.noteSourceWrite(ref.guid, change.origin)

modules/SceneBuild/ownerOf

ownerOf(entityId: string): string?

The build that placed entityId, or nil when no build placed it. A reconcile writes the name of the build onto every entity it places, as an attribute the scene records beside the entity's name and transform, so the answer holds across a reload — and an entity an author spawned carries no owner at all.

Parameters

• entityId string — Runtime entity id.

if SceneBuild.ownerOf(id) ~= nil then print("a build states this") end

modules/SceneBuild/previewedComponentType

previewedComponentType(entityId: string): string?

The component type that recorded a preview for entityId, or nil when none is waiting. A component that records one is SAYING that a build states its fields and that it announces the replacement itself — so a rebuild states that type again rather than leaving it to the scene, which is what lets the announcement happen. Every other component is merged.

Parameters

• entityId string — Runtime entity id of the owned entity.

if SceneBuild.previewedComponentType(id) == "SceneModule" then end

modules/SceneBuild/reconcile

reconcile(

Apply records to the scene under target, reusing the entities a previous reconcile left behind. A record that maps to a live entity updates THAT entity — same runtime id, so every reference to it survives the rebuild — and only a record with no live entity spawns one. The entity it spawns takes an id derived from owner, target and the record's identity, so every session sharing the world that runs the same build creates it under the same id, and the records one session's build writes land on the entity another session's build created. Entities the previous build held that this one no longer emits are despawned. A SceneModule placement the previous build stated on an entity and this one does not goes together with the entities it built beneath it. Name, transform, hidden, active, attributes, lifecycle mode, network scope, whether the entity's live state replicates, and components are all made to match the record, so a rebuild that drops a component or an attribute drops it from the scene. Each of them is a diff: what already matches the record is left exactly as it is, so a rebuild that changed nothing changes nothing — a running component keeps running and the scene stays clean. Only entities the build owns are touched: anything else under target is left exactly as it was. A component field holding an entity reference is resolved as the records are applied: a reference to an entity of the SAME build points at the entity this reconcile landed it on, and a reference to any other entity keeps pointing where it did. owner names the build. Every entity it places carries that name and the record's identity as attributes of its own, which is what lets a rebuild find the entities the last one placed without anything being remembered between them — the pair is in the scene, and a reload brings it back with the entity. Two builds sharing a target stay out of each other's way by using different owners. A record's identity is its place in the hierarchy — the chain of names from the build root down to it — so dropping, inserting or reordering a sibling leaves every other entity where it was. Several children of one parent sharing a name are told apart by their rank among those, counted in the order the builder created them.

local ids = SceneBuild.reconcile(records, root, "chairs")
local ids, created = SceneBuild.reconcile(records, layer, "build")
SceneBuild.reconcile(SceneBuild.run(build), layers.active, "build")

modules/SceneBuild/recordDrift

recordDrift(rec: any): { string }

Where an entity RECORD disagrees with what the build that placed it last stated: the question M.drift asks of the live scene, asked of a record the way scene.json and a scene's unsaved edits hold it. A record carries the build's statement in its own attributes, so a property that reads differently from that statement is one changed since the build ran, and an attribute the record holds that the build never stated is one added since. The record's name, transform and attributes are compared, numbers within the precision a saved record keeps.

Parameters

• rec any (optional) — An entity record: name, transform = { position, rotation, scale } and attributes.

local drifted = SceneBuild.recordDrift(record)

modules/SceneBuild/run

run(builder: () -> ()): ({ any }, { Refusal })

Run builder inside an entity capture scope and return the records for every entity it created. The builder writes ordinary spawn code — real entity.spawn, real component.add, real loops — and the entities it creates are real for the duration of the call. They are composed into records and then despawned, so run leaves the scene untouched and hands back data. Reconciling that data into a scene is M.reconcile. The builder's entities are despawned even when it raises, so a failed build never leaks a half-built hierarchy into the scene. What a component the builder attached created 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, so the entities come from there rather than from records of their own. That covers a nested build — a placement the builder makes runs its own module and owns what it lands — and every other component that expands into entities. An operation the scope refused is refused BEFORE it lands, so the records describe the live world exactly as the builder left it, and a builder that ran to its end around a refusal somebody caught for it composes what it did make. Every such refusal comes back as the second return, naming the contributor it stopped, for the caller to report alongside what it baked.

Parameters

• builder () -> () — Function taking no arguments; spawns whatever it wants.

local records, refused = SceneBuild.run(function() entity.spawn("chair") end)

modules/SceneBuild/sourceOf

sourceOf(owner: string): string?

The file that states the build named owner — what the reconcile running that build passed as opts.source. Nil for a build that has not run in this session and for one that named no source.

Parameters

• owner string — Build name, as M.ownerOf reports it.

local file = SceneBuild.sourceOf(SceneBuild.ownerOf(id))

modules/SceneBuild/sourceWrittenHere

sourceWrittenHere(guid: string): boolean

Whether the latest write to the asset guid this session saw was its own, so a rebuild stated from it records what it lands. True for a write this session made and for an asset it has seen no write to; false when another session wrote it last, whose own rebuild records the change, and whose records reach this session.

Parameters

• guid string — The asset's guid.

local record = SceneBuild.sourceWrittenHere(ref.guid)

modules/SceneBuild/states

states(owner: string, key: string): boolean?

Whether the build named owner placed an entity for the record identity key the last time it ran in this session. An entity carrying that pair that is gone from the scene was taken away by the build when the build no longer states it, and by an author when the build still does: the build's next run would put it back.

Parameters

• owner string — Build name, as M.ownerOf reports it.
• key string — The record identity, as the entity's buildKey attribute holds it.

local stillStated = SceneBuild.states(owner, key)

modules/SceneBuild/takePreview

takePreview(entityId: string): { [string]: any }?

Take the values M.notePreview recorded for entityId and clear them. Each set of values is read once — by whichever run of the build states that entity next.

Parameters

• entityId string — Runtime entity id of the owned entity.

local set = SceneBuild.takePreview(id)

modules/SceneModuleAssetTypeRef/README

require("@builtin::assetTypes.sceneModule.behavior") -- SceneModuleAssetTypeRef

Per-instance methods exposed on every AssetRef<sceneModule>. Loaded lazily by assetType.shared.ref.

Usage: local SceneModuleAssetTypeRef = require("@builtin::assetTypes.sceneModule.behavior")

modules/SceneModuleAssetTypeRef/build

build(self, params: { [string]: any }?): ({ any }, { SceneBuild.Refusal })

Run this module's builder with params and return the entity records it built. The builder runs inside the entity capture scope, so it writes ordinary spawn code and what it created comes back as data — the scene is untouched by the call. SceneBuild.reconcile is what lands the records.

Parameters

• self any (optional)
• params { [string]: any }? (optional) — Per-placement input overrides, keyed by declared input name. An input the table omits resolves to its declared default. A builder that ran to its end around an operation the scope refused — one it caught itself, or one something between it and the refused call caught — hands back the records for what it did make, and every such refusal beside them: the operation was refused before it landed, so the records describe the scene as the builder left it.

local records, refused = moduleRef:build({ seed = 3 })

modules/SceneModuleAssetTypeRef/getInitScript

getInitScript(self): string?

Read the module's entry script (init.luau / init.lua) as raw text.

Parameters

• self any (optional)

local src = moduleRef:getInitScript()

modules/SceneModuleAssetTypeRef/inputs

inputs(self): { InputSpec }

The inputs this module declares, sorted by name — each one's name, its Field kind, its declared default, and, for a closed-set input, the members it accepts. This is what an inspector renders as widgets and what a caller reads to learn which params a placement can set.

The script runs once per change to a file of the module or to a module it requires; later calls answer from that run. A script whose declarations depend on anything else it reads at its top level (world state, the clock, another asset's content) is answered from the run that last read it until one of those files changes. A script that fails to load runs again on the next call.

Parameters

• self any (optional)

for _, i in ipairs(moduleRef:inputs()) do print(i.name, i.kind) end

modules/SceneModuleAssetTypeRef/inputsSignature

inputsSignature(ref: any): string

Text that moves when what inputs() answers for this module can have moved beyond the module's own files: the versions of the modules its script requires, as its last run found them. Empty before a run.

Parameters

• ref any (optional) — The sceneModule.

parts[#parts + 1] = require(behavior).inputsSignature(moduleRef)

modules/SceneModuleAssetTypeRef/inspectDetail

inspectDetail(self): any

asset.inspect type-specific detail: { inputs } — the declared inputs, as :inputs() reports them. A module whose entry script cannot be loaded reports an empty input list rather than erroring.

Parameters

• self any (optional)

local declared = asset.inspect(moduleRef).detail.inputs

modules/SceneModuleAssetTypeRef/instantiate

instantiate(self, target: EntityRef?, opts: { [string]: any }?): (EntityRef, { [string]: string })

Instantiate this module — the uniform instantiate(target?, opts?) contract every scene-instantiable asset answers to, and what makes a sceneModule placeable wherever a scene-instantiable asset is accepted.

With target it builds with opts.params and reconciles the records under that entity, owned by that entity: the entities a previous build placed there name it as their owner and are UPDATED in place, so ids hold across every rebuild and across a reload.

With no target it places the module the way an author places any asset: one entity carrying a SceneModule component bound to this module. That component is what runs the build. The base opts — position, rotation, scale, name, temporary — place the root either way.

Parameters

• self any (optional)
• target EntityRef? (optional) — Optional owning entity ref.
• opts { [string]: any }? (optional) — { position?, rotation?, scale?, name?, temporary?, params?, handBack?, record? } — params seeds the module's declared inputs; handBack spreads the build's reconcile across frames, and record = false lands it in the live scene alone, as SceneBuild.reconcile takes them.

moduleRef:instantiate(owner, { params = { seed = 3 } })

modules/SceneModuleAssetTypeRef/onChange

onChange(ref: any, change: { [string]: any })

A write inside a .sceneModule folder. Records which session wrote the module: the reload of every placement it reaches rebuilds in each session holding the placement, the session that made the write records what its rebuild lands, and every other one lands it in its live scene alone.

Parameters

• ref any (optional) — The module whose folder was written.
• change { [string]: any } — { path, asset, type, kind, origin }.

__zero_dispatch_asset_change("/zero/source/fort.sceneModule/init.luau")

modules/SceneModuleAssetTypeRef/onDelete

onDelete(ref: any)

Asset-type delete callback: the inputs a removed module declared are forgotten.

Parameters

• ref any (optional) — The removed module.

modules/SceneModuleInspector/README

require("@builtin::modules.editor.scene_module_inspector") -- SceneModuleInspector

The SceneModule component's card on an entity: the bound module's identity, the file that states the placement, the module's DECLARED inputs as editable rows, and a Rebuild action. It replaces the card's generic settings section.

Usage: local SceneModuleInspector = require("@builtin::modules.editor.scene_module_inspector")

modules/SceneModuleInspector/buildFieldSpecs

buildFieldSpecs(declared: { any }, params: { [string]: any }?): { FieldSpec }

Build the editable field descriptors for a module's declared inputs: one spec per input, sorted by name, carrying the input's kind, its current value (the param override when the placement set one, else the declared default), and the members a closed-set input accepts. Pure — no UI, no entity access — so the field mapping is testable headless.

Parameters

• declared { any } — The module's declared inputs, as moduleRef:inputs() reports.
• params { [string]: any }? (optional) — The placement's current param-override table (may be nil).

modules/SceneModuleInspector/statedIn

statedIn(entityId: string): string?

The file the build that placed entityId is written in, for a placement a build made. That build states the placement's params every time it runs, so the rows below read as a preview of what it would state rather than as the placement's own settings. Nil for a placement an author made, whose params are the author's.

Parameters

• entityId string — The inspected entity's id.

local file = SceneModuleInspector.statedIn(id)

modules/SceneRuntime/README

require("@builtin::assetTypes.scene.shared") -- SceneRuntime

The scene runtime — what a .scene folder does when it is loaded, saved, built, or swapped.

A <name>.scene/ folder carries scene.json (the entity arrangement), an optional build.luau (the code author's half — see scene.assetType's README), an optional entrypoint.luau, and a scene_dirty/ overlay of unsaved edits. Reading, composing, and writing all four is what this runtime does, and it lives here because that is the scene type's own behaviour.

Field	Responsibility
loader	Reads scene.json v6/v7, composes canonical + dirty overlay, spawns the entities, runs the entrypoint.
saver	Persists scene state as a delta overlay, promotes it to canonical, and answers what is still unsaved.
build	Runs a build.luau in an entity capture scope and composes what it spawned into records.
observe	The read side — per-scene counts and costs layers and loader write.
swapOrchestrator	Drives multiplayer room transitions across a scene swap.
Fields resolve LAZILY. The prelude installs swapOrchestrator and starts
saver's dirty writer in a fixed order; a table that required all five on
load would take that ordering away from it.

Usage: local SceneRuntime = require("@builtin::assetTypes.scene.shared")

modules/ScriptValidator/README

require("@builtin::systems.worldValidation.scriptValidator") -- ScriptValidator

Per-file Luau / Lua script validator. Wraps lsp.check to return real parser + type-check diagnostics for a single script, on top of cheap textual sanity checks (read failure, empty file).

Each script gets the full LSP pass — lsp.check(path, opts) from the engine's embedded Luau LSP. Severity, line, column, code, and message are taken straight from the LSP and re-wrapped in the validator's Problem shape. The LSP diagnostics carry stable codes (unknown-global, type-error, parse-error, …) — we forward them verbatim so callers can severity = "error" or code = "parse-error" and get exactly the rows they expect. Two cheap textual checks run BEFORE the LSP is invoked:

1. script.read_failed (error) — vfs.read returned nil (file deleted between scan and read, or unreadable).
2. script.empty (warning) — zero non-whitespace content. These don't duplicate anything the LSP produces — the LSP is skipped when read fails (no source to feed it) and the empty check is informational about the file rather than the code.

Usage: local ScriptValidator = require("@builtin::systems.worldValidation.scriptValidator")

modules/ScriptValidator/validate

validate(script, opts)

Validate a single script. Combines two cheap textual checks (script.read_failed, script.empty) with the embedded Luau LSP's full diagnostic pass via lsp.check(path).

Parameters

• script any (optional) — { path, name } script entry from vfsScanner.
• opts any (optional) — Reserved for future use; currently ignored.

local problems = ScriptValidator.validate({ path = "/source/foo.luau", name = "foo.luau" })

modules/ScriptValidator/validateBatch

validateBatch(scripts, opts)

Validate a batch of scripts and flatten the per-script problem lists into one array.

Parameters

• scripts any (optional) — Array of script entries from vfsScanner.
• opts any (optional) — Reserved for future use.

local all = ScriptValidator.validateBatch(bucket.scripts)

modules/ServiceAssetTypeRef/README

require("@builtin::assetTypes.service.behavior") -- ServiceAssetTypeRef

Per-instance methods exposed on every AssetRef<service>. Loaded lazily by assetType.shared.ref. These act on the SPECIFIC service the reference points to — asset.resolve("mesh_gen","service"):invoke{...} runs THAT service.

Usage: local ServiceAssetTypeRef = require("@builtin::assetTypes.service.behavior")

modules/ServiceAssetTypeRef/balance

balance(self): (number?, string?)

Read the caller's current credit balance — the balance every service draws from. Returns (nil, errMsg) when not signed in.

Parameters

• self any (optional)

local credits = serviceRef:balance()

modules/ServiceAssetTypeRef/cost

cost(self, operation: string?, input: { [string]: any }?): (number?, string?)

The declared credit cost of an operation (the provider's up-front estimate; the exact charge is returned on each generation). Defaults to the primary / only operation.

Parameters

• self any (optional)
• operation string? (optional) — Optional operation name.
• input { [string]: any }? (optional)

local c = serviceRef:cost()

modules/ServiceAssetTypeRef/frameworkInputs

frameworkInputs(self, operation: string?): { { [string]: any } }

The inputs a call on this service takes on top of what the operation declares — operation, naming which of the service's operations to run, and asset_path, naming where the run writes what it generates. Each row reads as a declared input does: { name, type, required, desc, framework = true }.

Parameters

• self any (optional)
• operation string? (optional) — The operation these apply to. Omit for the service's default.

local extra = serviceRef:frameworkInputs("sfx")

modules/ServiceAssetTypeRef/getDefinition

getDefinition(self): string?

Read this service's declaration source (init.luau).

Parameters

• self any (optional)

local src = serviceRef:getDefinition()

modules/ServiceAssetTypeRef/getReadme

getReadme(self): string?

Read this service's README.md body.

Parameters

• self any (optional)

print(serviceRef:getReadme())

modules/ServiceAssetTypeRef/info

info(self): { [string]: any }

A one-line summary of this service: its offering, what it produces, the operations it offers, and which of them a call runs when it names none.

Parameters

• self any (optional)

local i = serviceRef:info()

modules/ServiceAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { methods, description }, where methods is this service's declared operations — the top-level keys of its operations = { ... } table, parsed from the declaration's own source text — and description is the declaration's top-level summary, also parsed from source. A service with no readable declaration returns an empty methods list rather than erroring.

Parameters

• self any (optional)

local methods = asset.inspect(serviceRef).detail.methods

modules/ServiceAssetTypeRef/invoke

invoke(self, input: { [string]: any }?): { [string]: any }

Run a generation for this service. Picks the operation from input.operation (or the service's only / primary operation), runs its declared pipeline as a background task, and returns immediately with a generation handle. An input the operation does not declare is refused here, before anything is charged. Watch the run with the services toolbox status tool (or the watch tool) until it reads completed; that row's asset is the finished, spawnable asset. Consumes credits — check :cost() and :balance() first.

Parameters

• self any (optional)
• input { [string]: any }? (optional) — { prompt, ..., operation?, asset_path? } — the operation's inputs.

local g = asset.resolve("mesh_gen","service"):invoke({ prompt = "a treasure chest" })

modules/ServiceAssetTypeRef/onCreate

onCreate(name: string, opts: { [string]: any }): { [string]: string }

Generic-creation hook for asset.create("service", name, opts). Returns the scaffold content files for a new service declaration.

Parameters

• name string — Service identity (the instance name).
• opts { [string]: any }

asset.create("service", "mesh_gen", { offering = "origozero/mesh_gen" })

modules/ServiceAssetTypeRef/operations

operations(self): { { [string]: any } }

List this service's callable operations and their declared inputs, output, and credit cost — the per-service surface to read before invoking. framework carries the inputs the CALL takes on top of what the operation declares (:frameworkInputs()).

Parameters

• self any (optional)

for _, op in ipairs(serviceRef:operations()) do print(op.name, op.cost) end

modules/ServiceAssetTypeRef/resume

resume(self, record: { [string]: any }): { [string]: any }

Pick a recorded run of this service up where an earlier engine left it. Runs on world load for every run that did not finish; the record names the operation, the step in flight and the job it submitted, and the run continues from there without paying for the same work again.

Parameters

• self any (optional)
• record { [string]: any } — A run record as the framework's ServiceTask.durable returns it.

asset.resolve("mesh_gen","service"):resume(record)

modules/ServiceFramework/README

require("@builtin::assetTypes.service.shared") -- ServiceFramework

The runtime every .service instance declares against — reached via asset.containing(__FILE__).modules.shared. The TYPE owns all the machinery (metered invoke, the submit→poll→download→write pipeline, the async generation handle, error classification); an instance only declares its surface with Service.define{...}. A normal generation service is pure data — no per-instance logic.

Usage: local ServiceFramework = require("@builtin::assetTypes.service.shared")

modules/ServiceFramework/balance

balance(_self: any): ({ [string]: any }?, string?)

Read what the caller can spend on this service: spendable (the number an operation's cost must fit inside), with pool (the account balance) and agentRemaining (what is left of the caller's own allocation, when it works under one) behind it. Returns (nil, errMsg) when not signed in.

Parameters

• _self any (optional)

local credits = asset.resolve("mesh_gen","service"):balance().spendable

modules/ServiceFramework/cost

cost(self: any, operation: string?, input: { [string]: any }?): (number?, string?)

The declared credit cost of an operation: what a run of it spends when the call names none of the options that cost extra. This is the up-front figure to budget against — an operation that makes several metered calls declares what the RUN costs, not what one of its steps does. An option documented as costing more adds to it, so a call naming one spends above this figure. Defaults to the primary/only operation.

Parameters

• self any (optional)
• operation string? (optional) — Optional operation name.
• input { [string]: any }? (optional)

local c = asset.resolve("mesh_gen","service"):cost()

modules/ServiceFramework/define

define(spec: { [string]: any }): any

Declare a metered service. An instance's init.luau calls this with its surface — the offering identity and one or more operations — and returns the result. The TYPE runs the pipeline; the instance writes no machinery.

Parameters

• spec { [string]: any } — { name, description, offering, output?, primary?, retry?, operations }. An operation's result is either a single file (bytes / url) or a SET (files), and a set assembles one asset: files = { { as, url } } fetches each map into the asset's own folder (an entry states bytes instead of url when a step already bound its content), pack = { { as, channels = { r, g, b, a } } } gathers named maps' channels into one raster where a slot samples several properties from one image (a channel is a constant 0-255, a file name for its red, or "file.g" for a stated channel), and bind = { slot = name } binds fetched and packed maps to the asset's slots. A map that reaches no slot is named on the job row and in the log. retry is { attempts?, delay? } — how many times a call refused for a reason that describes the moment (a rate limit, a busy gateway, a write conflict) is sent again, and the first wait in seconds between attempts, which doubles each time. Defaults to 4 attempts starting at 1 second. An operation may declare its own retry to override the service's.

return Service.define({ offering = "origozero/mesh_gen", operations = { generate = { ... } } })

modules/ServiceFramework/frameworkInputs

frameworkInputs(self: any, operation: string?): { { [string]: any } }

The inputs a call on this service takes on top of what the operation declares — operation, naming which of the service's operations to run, asset_path, naming where the run writes what it generates, and durable, stating whether that is filed on canonical /source while play runs. Each row is { name, type, required, desc, framework = true }, the same shape a declared input reads as. operation is required of a service that declares no default; asset_path is offered by an operation that writes a single file, and left out by one that authors a folder of them under a name of its own. The operation row's text names the operation THIS service runs when a call omits it, or the ones a call chooses between.

Parameters

• self any (optional)
• operation string? (optional) — The operation these apply to. Omit for the service's default.

local extra = asset.resolve("audio_gen","service"):frameworkInputs("sfx")

modules/ServiceFramework/info

info(self: any): { [string]: any }

A one-line summary of this service for discovery: its offering, what it produces, and the operations it offers.

Parameters

• self any (optional)

local i = asset.resolve("mesh_gen","service"):info()

modules/ServiceFramework/invoke

invoke(self: any, input: { [string]: any }?): { [string]: any }

Run a generation for this service. Picks the operation from input.operation (or the service's primary / only operation), checks the operation's declared cost against the caller's balance/budget up front — raising with a legible reason if it can't be afforded — then runs the pipeline as a background task. An input the operation does not declare is refused here, before anything is charged. Returns immediately with a generation handle. Watch the task — the services toolbox status tool (or the watch tool) — until status == "completed", then the finished asset is that row's asset. The engine auto-imports the raw output into a spawnable asset (a mesh becomes a .bundle, an image a .texture, a sound a .soundClip); that imported asset, not the raw file, is what the completed result points to, ready to spawn. Consumes credits; check :cost() and :balance() first. A run files its asset where the caller's writes landed when it was requested: started outside the caller's play session, it files the asset on canonical /source even when it completes during play; started inside it, on the play shadow. input.durable states it outright (true: source, false: wherever the writes of that moment land). The finished status record carries durability, where what the run filed stands.

Parameters

• self any (optional)
• input { [string]: any }? (optional) — { prompt, ..., operation?, asset_path?, durable? }: the operation's inputs.

local g = asset.resolve("mesh_gen","service"):invoke({ prompt = "a treasure chest" })

modules/ServiceFramework/operations

operations(self: any): { { [string]: any } }

List this service's callable operations and their declared inputs, output, and credit cost — the per-service surface an agent reads before invoking. framework carries the inputs the call takes on top of what the operation declares (:frameworkInputs()). requireOneOf lists the groups of inputs a call must name at least one of.

Parameters

• self any (optional)

for _, op in ipairs(asset.resolve("mesh_gen","service"):operations()) do print(op.name, op.cost) end

modules/ServiceFramework/resume

resume(self: any, record: { [string]: any }): { [string]: any }

Pick a run of this service up where an earlier engine left it. The record names the operation, its inputs, the step in flight, the bindings the steps before it produced, and the provider or gateway job that step already submitted; the run continues from there, waiting on that job rather than paying for the same work again, and lands its asset the way an uninterrupted run does. Runs on world load for every recorded run that did not finish.

Parameters

• self any (optional)
• record { [string]: any } — A run record as ServiceTask.durable returns it.

asset.resolve("mesh_gen", "service"):resume(record)

modules/ServiceFramework/resumeAll

resumeAll(): number

Pick up every recorded run that did not finish: the ones an earlier engine submitted and did not live to collect. Runs when the world has loaded. A run's service is waited for rather than assumed present, because a service can be authored in the world and register a moment after the library's own; each run resumes on its own task, so one that has to wait holds up none of the others.

require("@builtin::assetTypes.service.shared").resumeAll()

modules/ServiceRunAssetTypeRef/README

require("@builtin::assetTypes.serviceRun.behavior") -- ServiceRunAssetTypeRef

Per-instance methods on every AssetRef<serviceRun> — one generation's durable record: what it was asked to make, the gateway job doing the work, and the state that job reached.

Usage: local ServiceRunAssetTypeRef = require("@builtin::assetTypes.serviceRun.behavior")

modules/ServiceRunAssetTypeRef/finished

finished(self): boolean

Whether this run reached a terminal state. A run that is neither completed nor failed was still working when it was last heard from.

Parameters

• self any (optional)

if not run:finished() then print("still out there") end

modules/ServiceRunAssetTypeRef/jobId

jobId(self): string?

The gateway job this run's work is running under. The job outlives the engine that submitted it, so this is what reaches an already-paid result when the run did not finish here.

Parameters

• self any (optional)

local id = asset.resolve("gen_4f2a_0", "serviceRun"):jobId()

modules/ServiceRunAssetTypeRef/record

record(self): { [string]: any }

This run's record: { id, service, operation, prompt, jobId, status, progress, assetPath, error }.

Parameters

• self any (optional)

local rec = asset.resolve("gen_4f2a_0", "serviceRun"):record()

modules/ServicesDescribe/README

require("@builtin::tools.services.shared.describe") -- ServicesDescribe

Fill in the descriptions a world's assets are still missing, many at a call. The assets are the ones a type asks to say what they are (a README, or about.yaml for a type) whose description is missing or still starts with the [[describe]] placeholder. A call of the describe service carries many assets, packed whole into as few calls as fit; the model answers each asset on a line of its own, and the text it returns for each is written into the description file the type declares, so the result is an ordinary file the author can edit.

Usage: local ServicesDescribe = require("@builtin::tools.services.shared.describe")

modules/ServicesDescribe/__configure

__configure(changes: { [string]: number })

Change how the tool waits, for a case that runs it against a stand-in.

Parameters

• changes { [string]: number } — Any of parallel, pollSeconds, waitSeconds, settleSeconds, budget (bytes a call carries), maxAssets (assets a call carries).

Describe.__configure({ pollSeconds = 0.05 })

modules/ServicesDescribe/describe

describe(options: Options?): Report

Find, or fill in, the descriptions the assets of a world still need. find (the default mode) lists the assets that lack the description their type asks for, the file and keys each needs, and how many calls filling them makes (a call costs 1 credit, so that is also the price), and writes nothing. all fills every asset find lists, and assets fills the ones it names. The default scope is what blocks the current push; scope = "world" takes every asset the world holds that a type asks to describe. A call of the describe service carries many assets, packed whole into as few calls as fit, several calls at once; each asset is answered written, failed (with the reason) or skipped (with the reason), and a reply that is missing or malformed for one asset fails that asset only. What is written is an ordinary file the author can edit; only the description file or keys a type declares are written, text an author wrote is never replaced, and library, installed and machine-local content is never touched.

Parameters

• options Options? (optional) — { mode?: "find" | "all" | "assets", scope?: "push" | "world", assets?: { string }, instructions?: string, examples?: { string } }. instructions is added to what the model is told, and examples names assets whose descriptions show the shape wanted.

local report = Describe.describe({ mode = "find" })

modules/ShaderAssetTypeRef/README

require("@builtin::assetTypes.shader.behavior") -- ShaderAssetTypeRef

Per-instance methods exposed on every AssetRef<shader>. Loaded lazily by assetType.shared.ref.

Usage: local ShaderAssetTypeRef = require("@builtin::assetTypes.shader.behavior")

modules/ShaderAssetTypeRef/compileKey

compileKey(key: string): string

Compile the shader key key (guid@checksum) for the materials waiting on it: the asset holding exactly that guid at that checksum (the guid's home when its bytes are that version, else a copy of that version held beside it) is compiled through the same path an edit runs. The engine calls this when a material first waits on a key, again when an asset under the key's guid arrives or changes, and again for a key answered "absent" once the asset index holds that version. While a world's content is being replaced, the index can state a version whose files are not all there to read; such a folder has nothing to compile yet, and the key is answered "absent" so it is asked for again.

Parameters

• key string — The shader key, guid@checksum.

require("@builtin::assetTypes.assetType.shared.ref").loadTypeModule("shader").compileKey(key)

modules/ShaderAssetTypeRef/compileStatus

compileStatus(self): { status: string, error: string?, key: string?, pending: string? }

This shader's latest compile outcome, read without the engine log. Returns { status, error?, key?, pending? } for the key the shader compiles under (guid@checksum of the version at its path): status is "compiled", "failed" (with error, the compiler's message) or "pending" (not compiled yet, or compiled with part of its verdict still being reached, which pending names: the material resolve's gate runs off the frame thread). A properties.yaml that getProperties refuses reads "failed", with error the same refusal, because the shader is not compiled against it. Compilation is async (a write queues it), so a "pending" right after editing means check again next frame. A write succeeding and getProperties returning a schema do not mean the WGSL compiled; this does.

Parameters

• self any (optional)

local s = shaderRef:compileStatus(); if s.status == "failed" then print(s.error) end

modules/ShaderAssetTypeRef/compiledWgsl

compiledWgsl(self): string?

The WGSL the shader compiler received for this shader, exactly as it received it. What getWgsl returns is the body as written; this is what that body became — the generated group(1) material interface above it, the domain's framework and entry points around it, every #include expanded and every #ifdef resolved. A compile error's line numbers, and the handle index naga prints where it has no name, are positions in THIS text, so a compileStatus() of "failed" is read against it. It answers for a failed compile as well as a clean one, and needs no material, entity or draw.

Parameters

• self any (optional)

local s = shaderRef:compileStatus()
if s.status == "failed" then print(s.error, shaderRef:compiledWgsl()) end

modules/ShaderAssetTypeRef/domain

domain(self): string

The render domain this shader's body declares with its first // @domain: <name> line — what entry points and framework the engine builds around it: "surface" (the default), "post-process", "screen", "sky", "compute". A further spelling (postprocess, screenspace, ui) answers as the domain it names; a name the compiler refuses answers as written.

Parameters

• self any (optional)

if shaderRef:domain() == "post-process" then print(shaderRef:getSpace()) end

modules/ShaderAssetTypeRef/getGlsl

getGlsl(self): string?

Read the GLSL body, when present. Returns nil for WGSL-only shaders.

Parameters

• self any (optional)

local glsl = shaderRef:getGlsl()

modules/ShaderAssetTypeRef/getPasses

getPasses(self): { { name: string, entry: string, scale: number, inputs: { string } } }

The passes this post-process shader declares, from passes: in its properties.yaml, in the order they are drawn. Each entry is { name, entry, scale, inputs }; scale is 0 on the last pass, which draws at the view's size. A shader that declares none is one pass.

Parameters

• self any (optional)

for _, p in ipairs(shaderRef:getPasses()) do print(p.name, p.entry, p.scale) end

modules/ShaderAssetTypeRef/getProperties

getProperties(self): { { [string]: any } }

List this shader's declared material properties (parsed from properties.yaml). Each entry is { name, type, default, min?, max? }. This is the editor-discovery surface, and the SAME parse the compile uses. Raises, naming the file, when properties.yaml is text the YAML decoder refuses (with the line) or one of its lists holds anything but a list of mappings (with the key).

Parameters

• self any (optional)

for _, p in ipairs(shaderRef:getProperties()) do print(p.name, p.type) end

modules/ShaderAssetTypeRef/getSourceCode

getSourceCode(self): string?

Read the primary shader body (shader.wgsl) as raw text.

Parameters

• self any (optional)

local src = shaderRef:getSourceCode()

modules/ShaderAssetTypeRef/getSpace

getSpace(self): string

The space this post-process shader's fragment() reads and returns, from space: in its properties.yaml: "light" (the default) or "display". The word the file declares, verbatim — an effect registered from a shader whose space: names something else renders in "light" and the engine log carries the spelling it was handed.

Parameters

• self any (optional)

print(asset.resolve("@builtin::shaders.post.lut", "shader"):getSpace())

modules/ShaderAssetTypeRef/getWgsl

getWgsl(self): string?

Read the WGSL body directly, ignoring the GLSL fallback. Use when you need to detect "is this shader WGSL-native?" vs the generic getSourceCode lookup that auto-falls-back.

Parameters

• self any (optional)

local wgsl = shaderRef:getWgsl()

modules/ShaderAssetTypeRef/listBindings

listBindings(self): { string }

List which top-level uniform / storage-buffer block names appear in the shader source — best-effort regex parse. Useful to cross-check against material:getPropertyNames() when debugging a "property doesn't exist" gap. Not a full WGSL parser; complex shaders with macros may report incomplete results.

Parameters

• self any (optional)

for _, name in ipairs(shaderRef:listBindings()) do print(name) end

modules/ShaderAssetTypeRef/listMaterialsUsing

listMaterialsUsing(self): { string }

List the material identities currently bound to this shader, by scanning the registered material catalogue. O(n) over the material list; cache the result if you call it on a hot path.

Parameters

• self any (optional)

for _, m in ipairs(shaderRef:listMaterialsUsing()) do print(m) end

modules/ShaderAssetTypeRef/onChange

onChange(ref, change)

Asset-type change callback: (re)compile the shader whenever its WGSL body or properties.yaml is written, and bring materials already bound to it onto the declared property list when that list changed shape. This is the ONLY thing that compiles a .shader — the implicit "WGSL written → recompile" path is gone — so it fires on the initial create (the template write) AND on every later edit, with no world reload. Convergent: see compileShader.

Parameters

• ref any (optional)
• change any (optional)

modules/ShaderAssetTypeRef/onDelete

onDelete(ref)

Asset-type delete callback: release what a removed .shader folder registered. The teardown counterpart of onChange's compile: under the key the shader compiled under, its programs and their variants, its composed WGSL, its compile status and its diagnostic go with the asset, and so do the per-path records this module kept for it. A shader authored afresh at the same path compiles as a new one.

Parameters

• ref any (optional)

modules/ShaderAssetTypeRef/onDependencyChange

onDependencyChange(ref, _change)

Dependency callback: a reference the shader names bound to its target — an #include of a module that did not exist when the shader last compiled. The shader compiles again against the module now there.

Parameters

• ref any (optional)
• _change any (optional)

modules/ShaderAssetTypeRef/previewMaterial

previewMaterial(self): ({ [string]: any }?, string?)

The material a surface preview paints this shader with: a transient one built from the shader at its properties.yaml defaults, which is the shader as it looks before anyone tunes it. Only a surface shader has a surface to paint; a post-process, sky or compute shader answers nil and the reason. ref:preview() paints the result on the mesh type.yaml names under preview: and releases the material after the render.

Parameters

• self any (optional)

local surface, why = shaderRef:previewMaterial()

modules/ShaderAssetTypeRef/schemaParseCount

schemaParseCount(): number

How many times a shader's properties.yaml has been parsed in this session, across every shader and every surface that reads one — the editor-discovery method, the compile, the alias registration and the alias lookup. A read whose bytes match the parse already held answers from it and leaves this unchanged, so the count rises once per distinct revision of a file rather than once per read.

local m = require("@builtin::assetTypes.assetType.shared.ref").loadTypeModule("shader"); local before = m.schemaParseCount(); ref:getProperties(); print(m.schemaParseCount() - before)

modules/ShaderAssetTypeRef/setWgsl

setWgsl(self, source: string): boolean

Overwrite the WGSL body on disk. Hot-reload picks the new body up on the next frame so any material using this shader recompiles. Returns true on success.

Parameters

• self any (optional)
• source string — New WGSL source.

shaderRef:setWgsl(myWgsl)

modules/ShaderAssetTypeRef/shadingModel

shadingModel(self): string

Which shading model this shader's body uses, and with it what the engine can take the shader apart into.

"engine-lit" — the body exposes fn surface(...) -> PbrSurface. It hands the engine a surface (albedo, roughness, metallic, emissive, normal, occlusion) and the engine lights it, so the capture tool's PBR debug passes read real material channels.

"self-shading" — the body exposes fn fragment(...) -> vec4<f32> and returns the finished pixel. There is no separate albedo to read, so those same passes render what the body returns.

"unknown" — no readable body, or one that exposes neither entry point.

The test is the literal one the compiler applies to the same source, so this reports the model the shader was actually built as.

Parameters

• self any (optional)

if shaderRef:shadingModel() == "self-shading" then print("albedo pass shows final colour") end

modules/ShaderModuleAssetTypeRef/README

require("@builtin::assetTypes.shaderModule.behavior") -- ShaderModuleAssetTypeRef

Per-instance methods exposed on every AssetRef<shaderModule>. Loaded lazily by assetType.shared.ref.

Usage: local ShaderModuleAssetTypeRef = require("@builtin::assetTypes.shaderModule.behavior")

modules/ShaderModuleAssetTypeRef/getSource

getSource(self): string?

Read this module's WGSL (module.wgsl) as raw text.

Parameters

• self any (optional)

local src = moduleRef:getSource()

modules/ShaderModuleAssetTypeRef/onRegister

onRegister(self)

Initial-registration callback: file this module's WGSL under every name it answers to the moment the instance first registers, so a shader that #includes it resolves on its first compile rather than only after the module has been written once this session. Idempotent — the guard below skips a re-register of identical source.

Parameters

• self any (optional)

modules/ShaderModuleAssetTypeRef/register

register(self): string?

Read this module's WGSL through the VFS and file what it holds now under every name it answers to, so a shader compiled next expands this text. Files unconditionally: the registry answers whether the text moved, and keeps the catalog generation still when the same bytes arrive again.

Parameters

• self any (optional)

local wgsl = moduleRef:register()

modules/ShaderModuleAssetTypeRef/setSource

setSource(self, src: string): boolean

Overwrite this module's WGSL. Every shader that includes it recompiles on the next frame.

Parameters

• self any (optional)
• src string — New WGSL source.

moduleRef:setSource(myWgsl)

modules/Slots/README

require("@builtin::modules.slots") -- Slots

The rules of the slot family: which entities are slots, the path each slot answers to, which part fills it, whether a part fits it and why not, and building or emptying the part that fills it. The Slot, Assembly and Part components call into it; content reads it through them. A slot is a place on an entity that another part fills: an entity carrying a Slot component (its transform is where the part attaches), or a role socket of a Humanoid (righthand, head, ...), which a part fills the way Humanoid:attach seats an item. The nearest Assembly on or above a slot holds what fills it, by the slot's path: the slot's name, under the path of the slot whose part it stands in (engine/turbo). An Assembly on the root of a part built into a slot passes its slots to the Assembly holding that part; any other Assembly below holds its own, so an assembled object parented under another keeps its own configuration.

Usage: local Slots = require("@builtin::modules.slots")

modules/Slots/afterOperation

afterOperation(fn: () -> ())

Run fn now, or once the undoable operation open on this peer closes. A part is built from the configuration that names it, so the building stays out of the step that changed the configuration: undoing the step puts the configuration back and the parts follow it.

Parameters

• fn () -> () — The work to run.

modules/Slots/apply

apply(entry: any, guid: string?): any?

Make a slot hold guid: leave the fill standing when it already holds that part, otherwise remove the fill and build the part in its place. Only this slot's branch changes.

Parameters

• entry any (optional) — A slot entry.
• guid string? (optional) — The guid of the part to hold, or nil to hold nothing.

modules/Slots/currentFill

currentFill(entry: any): (any?, any?)

The entity filling a slot right now, and the record it carries.

Parameters

• entry any (optional) — A slot entry.

modules/Slots/decide

decide(config: any, entry: any): (string?, string)

What fills a slot under a configuration: the configured part, an explicit empty, or the slot's default.

Parameters

• config any (optional) — The holder's configuration ({ [path] = guid | false }), or nil.
• entry any (optional) — A slot entry.

modules/Slots/declaredFits

declaredFits(ref: any): ({ string }, string?)

The slot kinds a part declares it fits: the fits of the Part component at the root of a bundle, or the fits list of the asset's .metadata for any other asset.

Parameters

• ref any (optional) — The part's AssetRef.

modules/Slots/discover

discover(rootId: string): { any }

Every slot at and under rootId, in breadth-first order: each Slot component, and each role socket of a Humanoid, with its path. A descendant whose own Assembly holds its slots (holdsOwnSlots) is left out with everything under it.

Parameters

• rootId string — The entity to walk from (an Assembly's entity).

modules/Slots/fits

fits(entry: any, part: any): (boolean, string, any?)

Whether a part fits a slot, and why not. A part fits when it is an asset a scene can hold, the slot's kind is empty or among the kinds the part declares it fits, and the part carries every tag the slot names.

Parameters

• entry any (optional) — A slot entry (discover), or any table with path, kind, tags.
• part any (optional) — The part: an AssetRef, identity, guid or path.

modules/Slots/holderOf

holderOf(entityId: string): any?

The Assembly that holds what fills the slots at and under entityId: the nearest one on the entity or its ancestors, and when that one stands on the root of a part built into a slot, the one holding that part, climbing on the same way.

Parameters

• entityId string — The entity to look from.

modules/Slots/holdsOwnSlots

holdsOwnSlots(e: any): boolean

Whether e carries an Assembly that holds its own slots: one on an entity that is no part built into a slot.

Parameters

• e any (optional) — The entity.

modules/Slots/nameOf

nameOf(slot: any): string

The name a Slot component answers to: its name, or the name of the entity it is on when that is empty.

Parameters

• slot any (optional) — The Slot component proxy.

modules/Slots/partRef

partRef(part: any): (any?, string?)

Resolve whatever names a part to its asset: an AssetRef, an identity, a guid or a path.

Parameters

• part any (optional) — The part to resolve.

modules/Slots/pathOf

pathOf(slot: any): string

The path a Slot answers to under the Assembly that holds it.

Parameters

• slot any (optional) — The Slot component proxy.

modules/SoundClipAssetTypeRef/README

require("@builtin::assetTypes.soundClip.behavior") -- SoundClipAssetTypeRef

Hooks for .soundClip assets. onCreate is the type's contribution to the generic asset.create("soundClip", name, opts) flow (mirroring texture.assetType). onChange keeps a managed container's data.zaud encoded payload in sync when its settings.yaml (or, for content published before it existed, its legacy .metadata settings) are edited, or its retained source audio is rewritten — the asset type reacting to writes inside its own instances (the type-level analogue of a component's onAssetReload). This hook owns every re-encode after the container exists. The settings themselves are declared in settings.luau and read/written through asset.settings / asset.setSettings.

Usage: local SoundClipAssetTypeRef = require("@builtin::assetTypes.soundClip.behavior")

modules/SoundClipAssetTypeRef/audition

audition(self): string?

Play this clip once through the mixer, unpositioned, replacing any clip auditioning. The voice plays on a temporary host entity the scene never saves and the entity listings leave out; the host is removed when the mixer reports the voice ended, and on the frame after stopAudition or a later audition.

Parameters

• self any (optional)

clipRef:audition()

modules/SoundClipAssetTypeRef/auditionVoice

auditionVoice(self): any?

This clip's audition in progress: its host entity and the mixer's view of the voice (nil until the mixer has it).

Parameters

• self any (optional)

local a = clipRef:auditionVoice(); if a and a.voice then print(a.voice.mixerState) end

modules/SoundClipAssetTypeRef/info

info(self): (any?, string?)

Read the header of this soundClip asset's data.zaud payload: how long the clip runs, the rate it plays at, how many channels it interleaves, which codec holds it, how many packets it is in, and where its loop points sit. Read off the header, so a script timing a caption to a line of narration pays a header read per clip where :pcm() would decode every sample. The sampleRate here is the rate the payload holds; :settings().sampleRate is the resample target the encode was ASKED for, where 0 means the source's own rate was kept.

Parameters

• self any (optional)

local info = clipRef:info(); task.wait(info.durationMs / 1000)

modules/SoundClipAssetTypeRef/lastAuditionEnd

lastAuditionEnd(self): { host: string, reason: string }?

How this clip's most recent audition ended, once its host is gone: "ended" (the mixer reported it played through), "stopped", "replaced" (a later audition), "unvoiced" (no output, a mixer rendering nothing, or the mixer turned it away), "timeout" (the mixer rendered past the clip's length with no end reported), "neverArrived" (the voice never reached the mixer) or "hostGone".

Parameters

• self any (optional)

local last = clipRef:lastAuditionEnd(); if last then print(last.reason) end

modules/SoundClipAssetTypeRef/loopSeam

loopSeam(self): (any?, string?)

Measure what this clip's samples do where a whole-clip loop wraps — the reading that says whether the clip can be looped without a click. The wrap's own step is reported against the step the signal ordinarily makes between neighbouring samples, so the figure is in the units the signal moves in and a quiet ambience reads the same way as a loud drone. A clip whose partials wrap reads near 1; one carrying a strike at its head and silence at its tail reads in the tens, and seamless is ratio <= threshold. Taken on the decoded payload, so it answers for what the codec left behind — including for a clip that arrived already encoded.

Parameters

• self any (optional)

local seam = clipRef:loopSeam(); if not seam.seamless then print(seam.ratio) end

modules/SoundClipAssetTypeRef/onChange

onChange(ref: any, change: { [string]: any })

React to a write inside a .soundClip/ instance, keeping the encoded data.zaud payload in sync. Rewriting the container's retained source audio — source.<ext>, or an imported file kept under its own name beside data.zaud — re-encodes from the new bytes; a rewrite carrying the bytes the payload was already encoded from, under the same encode settings, does nothing. A settings write — to the declared settings.yaml values file, or a legacy .metadata block for content published before it existed — re-encodes from the container's source when the encode-relevant fields (codec, bitrateKbps, vbr, sampleRate, forceMono, loopStart, loopEnd) actually changed: the retained source, or — for a PCM-baked container — the decoded data.zaud itself. loadType decides how the clip reaches the mixer, not what the payload holds, so it never drives a re-encode on its own — the generic per-asset reload dispatch already reaches every Audio component referencing this clip on any write here, and it asks clipRef:streams afresh on each rebuild, so the next source built from this clip picks up the new mode. data.zaud / README.md writes are ignored. The dispatcher's same-asset guard suppresses the re-dispatch of our own synchronous data.zaud write, so no loop forms.

Parameters

• ref any (optional) — The AssetRef for the changed container.
• change { [string]: any } — { path, asset, type, kind, origin, settings, settingsChanged } — path is the written file, asset the container folder, kind "edited"/"seeded", origin "local"/"remote", settings the validated values and settingsChanged what changed when path is the settings values file.

modules/SoundClipAssetTypeRef/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

Generic-creation hook for asset.create("soundClip", name, opts). Pure: returns the content-file map; the caller (asset.create) writes it to the authored destination (/source/<name>.soundClip/) and that write registers the soundClip asset.

Two input shapes, mirroring how clips originate:

• PCM — { pcm, sampleRate, channels }: generated / decoded interleaved f32 samples, in any container audio.encodePcm reads — a buffer, a binary string of little-endian f32, or a flat number array (no source file). Encoded to the canonical data.zaud payload (the engine's ZAUD format) via audio.encodePcm. data.zaud is the primary the runtime decodes — so a generated clip becomes a persistent, reload-stable asset addressed by guid.
• ENCODED AUDIO — { bytes, ext }: OGG / MP3 / WAV / FLAC source bytes, kept verbatim as source.<ext>, with data.zaud encoded from them against the instance's settings.

Parameters

• name string — SoundClip identity (the instance name).
• opts CreateOpts

asset.create("soundClip", "beep", { pcm = buffer.create(960 * 4), sampleRate = 48000, channels = 1 })
asset.create("soundClip", "music", { bytes = oggBytes, ext = "ogg" })

modules/SoundClipAssetTypeRef/onDelete

onDelete(ref: any)

Asset-type delete callback: a removed clip's audition ends, and how its last audition ended is forgotten.

Parameters

• ref any (optional) — The removed clip (its guid when the removal knew it, and its path).

modules/SoundClipAssetTypeRef/pcm

pcm(self): (string?, number?, number?)

Decode this soundClip asset's data.zaud payload into its samples, the rate they play at, and the number of channels they interleave.

Parameters

• self any (optional)

local pcm, sr, ch = clipRef:pcm()

modules/SoundClipAssetTypeRef/setSettings

setSettings(self, patch: { [string]: any })

Write a partial settings patch. The patch is checked against this type's declared schema; a violation refuses the write naming every problem. A valid write reaches onChange: an encode-relevant field (codec, bitrateKbps, vbr, sampleRate, forceMono, loopStart, loopEnd) re-encodes data.zaud; loadType never re-encodes — it decides how the next Audio source built from this clip reaches the mixer.

Parameters

• self any (optional)
• patch { [string]: any } — Any subset of the schema's fields.

clipRef:setSettings({ bitrateKbps = 64, forceMono = true })

modules/SoundClipAssetTypeRef/settings

settings(self): { [string]: any }

Read this soundClip asset's settings, with every declared default filled in. The settings say how the clip is encoded and where its loop points sit; what its samples do where a whole-clip loop wraps is clipRef:loopSeam().

Parameters

• self any (optional)

if clipRef:settings().forceMono then ... end

modules/SoundClipAssetTypeRef/stopAudition

stopAudition(self): boolean

Stop this clip's audition: it stops being the audition in progress at once, and its host is removed on the next frame.

Parameters

• self any (optional)

clipRef:stopAudition()

modules/SoundClipAssetTypeRef/streams

streams(self, bytes: string?): boolean

Whether a source playing this clip holds it streaming: loadType "streaming" does, "decompressOnLoad" does not, and "auto" streams a clip that runs longer than 5 seconds.

Parameters

• self any (optional)
• bytes string? (optional) — The clip's data.zaud payload when the caller already holds it.

local s = ecs.AudioSource{ clip = c, streaming = c:streams(bytes) }

modules/StyleAssetTypeRef/README

require("@builtin::assetTypes.style.behavior") -- StyleAssetTypeRef

Per-instance methods exposed on every AssetRef<style>. Loaded lazily by assetType.shared.ref.

Usage: local StyleAssetTypeRef = require("@builtin::assetTypes.style.behavior")

modules/StyleAssetTypeRef/getInitScript

getInitScript(self): string?

Read the style's entry script as raw text.

Parameters

• self any (optional)

local src = styleRef:getInitScript()

modules/StyleAssetTypeRef/getReadme

getReadme(self): string?

Read the style's README.

Parameters

• self any (optional)

print(styleRef:getReadme())

modules/StyleAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { tokenCategories }, the top-level keys of the style's own M.tokens = { ... } table literal, parsed from the entry script's source text via luau_introspect.tableLiteralKeys — never requires the style. Cached on the asset's content checksum, so re-inspecting unchanged source is free. A style with no readable entry script returns an empty detail rather than erroring.

Parameters

• self any (optional)

local tokenCategories = asset.inspect(styleRef).detail.tokenCategories

modules/StyleAssetTypeRef/loadTheme

loadTheme(self): any

Load the style module and return its exported theme table. Raises a Luau error tagged with the style identity if the require fails.

Parameters

• self any (optional)

local theme = styleRef:loadTheme()

modules/Test.valueText/README

require("@builtin::assetTypes.testSuite.shared.valueText") -- Test.valueText

How the test framework renders a value nested inside a table for test output: structurally, with bounded breadth, depth and string length, in a deterministic order.

Usage: local Test.valueText = require("@builtin::assetTypes.testSuite.shared.valueText")

modules/Test.worldReadings/README

require("@builtin::assetTypes.testSuite.shared.worldReadings") -- Test.worldReadings

Readings the test framework takes of engine-wide state around a test: each facet a queued teardown moves (entities, layers, render features, render targets, loads in flight), and which editor chrome screens the window shows.

Usage: local Test.worldReadings = require("@builtin::assetTypes.testSuite.shared.worldReadings")

modules/Test.worldReadings/residentRenderTargets

residentRenderTargets(): number

Readings the test framework takes of engine-wide state around a test: each facet a queued teardown moves (entities, layers, render features, render targets, loads in flight), and which editor chrome screens the window shows.

modules/TestSuiteAssetTypeRef/README

require("@builtin::assetTypes.testSuite.behavior") -- TestSuiteAssetTypeRef

Per-instance methods exposed on every AssetRef<testSuite>. Loaded lazily by assetType.shared.ref. These methods act on the SPECIFIC asset instance the reference points to — asset.resolve(id, "testSuite"):run() runs only THAT suite. Running every suite is the tests toolbox's job (it iterates asset.list("testSuite") and calls :run() on each); it is deliberately not offered here.

Usage: local TestSuiteAssetTypeRef = require("@builtin::assetTypes.testSuite.behavior")

modules/TestSuiteAssetTypeRef/getReadme

getReadme(self): string?

Read this suite's README.md body.

Parameters

• self any (optional)

print(suiteRef:getReadme())

modules/TestSuiteAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { testCount, testNames }, parsed from Test.it("<name>", ...) calls in this suite's own init.luau text. A string scan, not a suite run — inspecting a suite never registers or executes its tests. A suite with no readable init.luau returns an empty testNames list rather than erroring.

Parameters

• self any (optional)

local testNames = asset.inspect(suiteRef).detail.testNames

modules/TestSuiteAssetTypeRef/run

run(self, opts: { quiet: boolean? }?): any

Run THIS test suite (only this one) and return its results. Refuses in play mode — tests are an edit-mode / authoring concern, not gameplay. The run is cooperative (the framework yields a frame between tests) so it never blocks the engine or trips the execute watchdog.

Parameters

• self any (optional)
• opts { quiet: boolean? }? (optional) — Optional { quiet }.

local r = asset.resolve("vfs", "testSuite"):run()

modules/TestSuiteAssetTypeRef/tests

tests(self): { { name: string, skip: boolean } }

List the tests this suite declares (loads THIS asset's init.luau to read its registered Test.it / Test.skip names; does not run them).

Parameters

• self any (optional)

for _, t in ipairs(suiteRef:tests()) do print(t.name) end

modules/TextureAssetTypeRef/README

require("@builtin::assetTypes.texture.behavior") -- TextureAssetTypeRef

Hooks for .texture assets. onCreate is the type's contribution to the generic asset.create("texture", name, opts) flow (mirroring material.assetType). onChange keeps a MANAGED container's data.ztex encoded payload in sync when its settings.yaml (or, for content published before it existed, its legacy .metadata settings) are edited, or its retained source image is rewritten — the asset type reacting to writes inside its own instances (the type-level analogue of a component's onAssetReload). The loose-image → container PROMOTE step is the separate texture.importer (loose-write seam); this hook owns every re-encode AFTER the container exists. The settings themselves are declared in settings.luau and read/written through asset.settings / asset.setSettings.

Usage: local TextureAssetTypeRef = require("@builtin::assetTypes.texture.behavior")

modules/TextureAssetTypeRef/compressionFor

compressionFor(settings: { [string]: any }, isLegacy: boolean): { compression: string, textureType: string }

What a texture is compressed as, and as what type, given its settings. isLegacy says the settings predate compression (stored before it was a setting, whatever older format they name): such a texture is compressed as it should have been — a nearest-filtered one is pixel art, a sprite held exactly as rgba8; a high-precision one (rgba16, rgba32f) keeps its format; every other one is uastc. Settings that name compression keep it, so a texture whose settings say rgba8 is never compressed. The one decision the local-edit heal (settingsHealed) and an on-device compressor of legacy content both make.

Parameters

• settings { [string]: any } — The texture's settings, as a read reports them.
• isLegacy boolean — Whether the stored settings predate compression.

M.compressionFor({ compression = "rgba8", filter = "nearest", textureType = "color" }, true) -- { compression = "rgba8", textureType = "sprite" }

modules/TextureAssetTypeRef/handle

handle(self)

Put this texture asset on the GPU under its own guid and return its TextureHandle at once. The asset's bytes are decoded off the frame and the texture lands on the device when the decode finishes, a frame or more later: a material naming the guid draws the shader's default for that slot until then and rebinds when it arrives, and renderer.texture.isResident(guid) reports the arrival. The handle is cached on the interned ref's shared runtime table for as long as something holds the one it handed out, so every consumer and material slot naming the asset over that time gets the SAME handle back → ONE GPU entry. Once the last of them lets go, the next call asks for the asset again and is answered with a handle on the texture the device already holds under that guid — which is also what a mode flip's runtime wipe leads to. The material binds this handle's guid; it never creates the GPU texture itself.

CPU lifecycle: governed by the asset's declared keepCpu setting (texRef:setSettings({ keepCpu = true })). By DEFAULT (false) the decoded pixels are dropped right after the GPU upload (the GPU handle holds no data → no double-memory cost); with keepCpu = true the CPU store keeps them for later pixel reads / edits. A keepCpu change reaches an already-materialised texture too — onChange's applyKeepCpu loads or drops the CPU copy the moment the setting changes, not only here.

Parameters

• self any (optional)

local h = texRef:handle() -- bind h.guid on a material; it draws once resident

modules/TextureAssetTypeRef/info

info(self): (any?, string?)

Read the header of this texture asset's compiled data.ztex payload: the pixel format it was compiled to, as its compression and colorSpace too, how many texels it is across and down, how many mip levels and array layers it carries, the sampler recorded in it (filter, wrapU, wrapV, anisotropy), and, for a sequence, each layer's display time and the length of one pass. Read off that payload's own header, so a compiled texture answers how big it is for a header read where :load() decodes its pixels and :handle() uploads them. A container whose primary is a source image answers (nil, err), and :load() reads its size. The compression and colorSpace here are what the payload holds; :settings() holds what the encode was ASKED for.

Parameters

• self any (optional)

local i = texRef:info(); print(i.width .. "x" .. i.height)

modules/TextureAssetTypeRef/load

load(self)

Load this .texture asset's pixels into the guid-keyed CPU store and return a CPU handle for per-pixel access (no GPU readback). The handle holds no pixels — only the guid, dims, texel format, and the read/write/encode/ unload ops. The pixels stay at the precision they were authored with: handle.format is "rgba8", "rgba16" or "rgba32f", and :readPixel reports channels in that format's own units. Upload to the GPU with renderer.texture.create(handle); the DEFAULT is to handle:unload() after. The handle's :encode() re-encodes the (possibly edited) pixels into a fresh ZTEX blob for asset.create("texture", …), at the same format.

Parameters

• self any (optional)

local cpu = texRef:load(); local r,g,b,a = cpu:readPixel(3, 4); cpu:unload()

modules/TextureAssetTypeRef/normalizeSettings

normalizeSettings(values: { [string]: any }, stored: { [string]: any }?): { [string]: any }

Map every older spelling a stored file or a write may carry to the fields and members the schema declares: an older filter keyword to linear / nearest, an anisotropy given as a number to its string (8 → "8"), compression = "bc7" to "uastc", maxDimension = 0 (no cap) to 8192, and format + srgb to colorSpace + compression (an explicit srgb sets the colour space of an rgba8, uastc or bc7 format; the high-precision formats stay linear). An srgb given without a format applies to the compression the same table names, else to the asset's stored one, so { srgb = true } leaves an rgba16 texture linear. A table that names both an older field and its replacement keeps the replacement's value. A format no schema declared stays under its own name, so the schema check refuses it naming the field. Returns a new table.

Parameters

• values { [string]: any } — A settings table in any spelling.
• stored { [string]: any }? (optional) — The asset's current values, when values is a patch over them.

M.normalizeSettings({ format = "bc7_srgb", maxDimension = 0 }) -- { colorSpace = "srgb", compression = "uastc", maxDimension = 8192 }

modules/TextureAssetTypeRef/onChange

onChange(ref: any, change: { [string]: any })

React to a write inside a .texture/ instance, keeping the encoded data.ztex payload in sync. Rewriting the container's retained source image — source.<ext>, or an imported image kept under its own name beside data.ztex — re-encodes from the new bytes; a rewrite carrying the bytes the payload was already encoded from does nothing. A settings change that touches only the sampler fields (filter, wrapU, wrapV, anisotropy) on a container holding data.ztex rewrites the payload's header with them (renderer.texture.withSampler): every level keeps its bytes and no preview is rendered, because no pixel changed. A settings change that touches an encode-affecting field (textureType, colorSpace, compression, generateMipmaps, maxDimension, alpha, alphaIsTransparency) re-encodes from the container's source: the managed source.<ext>, a plain container's image primary, or — for a raw-pixel container — the data.ztex payload itself, re-encoded whole (every layer and its display time kept) and read back with straight alpha. A raw-pixel container's payload is its only source, so what an earlier encode discarded stays discarded: after alpha = "none" its alpha is opaque, and after alphaIsTransparency its transparent texels keep the colour dilation gave them. Whatever rewrote the payload — a re-encode here, or a data.ztex written directly or arriving from a peer — the texture this engine has on the GPU under the asset's guid is uploaded again from it, so every material, UI image and effect sampling the guid draws the new pixels, size, format, colour space, mip chain, filter, wrapU, wrapV and anisotropy, and a resident CPU copy is decoded again. A keepCpu change acts on the texture's CPU residency instead (applyKeepCpu) and never re-encodes on its own — and, because CPU residency is PER-ENGINE state, it acts for EVERY origin: a synced peer's write says exactly as much about its own process as a local one does about this one. Everything that WRITES persisted content — the source re-encode and the settings-driven re-encode — stays local-origin-only; a peer receives that content through the ordinary sync instead of reproducing the write itself. It fires on a write to the declared settings.yaml values file only when change.settingsChanged is non-empty — an identical rewrite carries an empty diff and does nothing — or on a legacy .metadata settings block for content published before the values file existed, which carries no diff and so re-encodes unconditionally. README.md writes are ignored. The dispatcher's same-asset guard suppresses the re-dispatch of our own synchronous data.ztex write, so no loop forms.

Parameters

• ref any (optional) — The AssetRef for the changed container.
• change { [string]: any } — { path, asset, type, kind, origin, settings, settingsChanged } — path is the written file, asset the container folder, kind "edited"/"seeded", origin "local"/"remote", settings the validated values and settingsChanged what changed when path is the settings values file.

modules/TextureAssetTypeRef/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

Generic-creation hook for asset.create("texture", name, opts). Pure: returns the content-file map; the caller (asset.create) writes it to the authored destination (/source/<name>.texture/) and that write registers the texture asset. Disk-only — nothing is uploaded to the GPU here.

Two input shapes, mirroring how textures originate:

• RAW PIXELS — { rgba, width, height }: a generated / decoded pixel buffer (no source image). Encoded to the canonical data.ztex payload (the engine's ZTEX format; zero_texture::blob) via __texture.encode, at the resolved opts.settings.compression and opts.settings.colorSpace. data.ztex is the primary the renderer uploads — so a generated texture becomes a persistent, reload-stable asset addressed by guid, never an ephemeral GPU handle. compression picks the on-disk storage: "uastc" blocks (a new texture's default), 8 bits per channel with "rgba8" (a sprite's), or "rgba16" / "rgba32f" for a data raster (height / displacement field, baked lightmap, imported elevation) whose values 8 bits would quantize. A cook that drops texels (maxDimension, the power-of-two resample) keeps every one as source.ztex, so a later settings change re-encodes from them.
• ENCODED IMAGE — { bytes, ext }: PNG / JPEG / WebP / … source bytes, stored verbatim as the <name>.<ext> primary (the renderer image-decodes on upload; the same shape asset.create produced before).

Parameters

• name string — Texture identity (the instance name).
• opts CreateOpts

asset.create("texture", "skyGradient", { rgba = pixels, width = 256, height = 256 })
asset.create("texture", "terrain_height", { rgba = heights, width = 512, height = 512, settings = { compression = "rgba16" } })
asset.create("texture", "pixel_icon", { rgba = pixels, width = 16, height = 16, settings = { compression = "rgba8", filter = "nearest" } })
asset.create("texture", "bricks", { bytes = imageBytes, ext = "jpg" })

modules/TextureAssetTypeRef/setSettings

setSettings(self, patch: { [string]: any })

Write a partial settings patch. The patch is checked against this type's declared schema; a violation refuses the write naming every problem. A valid write reaches onChange: an encode-affecting field (textureType, colorSpace, compression, generateMipmaps, maxDimension, effort, uastcRdo, alpha, alphaIsTransparency) re-encodes data.ztex; a write naming only sampler fields (filter, wrapU, wrapV, anisotropy) rewrites the payload's header and keeps every level's bytes; keepCpu loads or drops the CPU copy instead, without touching the encoded bytes.

Parameters

• self any (optional)
• patch { [string]: any } — Any subset of the schema's fields.

texRef:setSettings({ filter = "nearest" })

modules/TextureAssetTypeRef/settings

settings(self): { [string]: any }

Read this texture asset's settings, with every declared default filled in. The table also answers the older format and srgb names, read from colorSpace + compression: format is "srgb", "linear", "uastc_srgb", "uastc", "rgba16" or "rgba32f", and srgb is true for the srgb colour space. Both are read-only: a write names colorSpace / compression.

Parameters

• self any (optional)

if texRef:settings().filter == "nearest" then ... end

modules/TextureAssetTypeRef/settingsCorrections

settingsCorrections(values: { [string]: any }, _name: string, _opts: { [string]: any }?): ({ [string]: any }?, { [string]: string }?)

Cross-field settings correction Settings.applyCorrections applies on every settings write — once a create's layers (schema defaults, this type's own settingsDefaults, the Preset Manager, an importer, the caller) have merged, and on every later asset.setSettings: a high-precision compression stores the raster verbatim and linear, so it carries no mip chain, no max-dimension downsample and no sRGB colour space — the encoder refuses all three structurally. Overrides generateMipmaps / maxDimension / colorSpace to the only values a high-precision compression allows. Whether that lands SILENTLY or REFUSES the write is applyCorrections' call, based on whether the writer named the field being overridden — the second return here supplies the "why" for that refusal message, naming the compression that made it necessary. Reads values; returns the correction rather than writing to it.

Parameters

• values { [string]: any } — The fully resolved settings, after every layer has merged.
• _name string
• _opts { [string]: any }? (optional)

local fix, why = M.settingsCorrections({ compression = "rgba16", generateMipmaps = true }, "height", {})

modules/TextureAssetTypeRef/settingsDefaults

settingsDefaults(name: string, opts: { [string]: any }?, asked: { [string]: any }?): { [string]: any }

The create-time settings this type contributes to a new asset's values, layered above the schema's own declared defaults and below every other layer (Preset Manager, importer, caller) — resolveForCreate calls this once per create, so an explicit override from any later layer replaces what it returns here. textureType follows the created name's own data-map convention: "normalMap" for a _normal/_nrm/_n/... suffixed name, "mask" for a _rough/_metal/_ao/_height/_disp/ _mask/... one, "color" otherwise; the colour space then follows the type (settingsDerivedDefaults). A new texture is uastc with a maxDimension of 4096; a sprite (a textureType a layer above names) is rgba8, drawn exactly as given; a high-precision source (a 16-bit PNG, a Radiance .hdr) leaves compression to the layers above. When opts.ztex is a pre-encoded payload whose header reads, its colorSpace, compression, filter, wrapU, wrapV, anisotropy, textureType, alpha and alphaIsTransparency are what was actually written, and the settings describe what is stored.

Parameters

• name string — The instance name being created.
• opts { [string]: any }? (optional) — The creation opts passed to asset.create.
• asked { [string]: any }? (optional) — What the layers above this one (Preset Manager, importer, caller) name.

local layer = M.settingsDefaults("brick_normal", {}, {})  -- { textureType = "normalMap", compression = "uastc", maxDimension = 4096 }

modules/TextureAssetTypeRef/settingsDerivedDefaults

settingsDerivedDefaults(

The fields whose default follows textureType, for a write that set or changed it: colorSpace (srgb for color and sprite, linear for normalMap and mask), alphaIsTransparency (true for sprite) and wrapU / wrapV (clamp for sprite — drawn whole — and repeat otherwise). The settings framework applies a returned field only where the same write did not name it, so a create or patch that names its own colour space keeps it.

M.settingsDerivedDefaults({ textureType = "sprite" }, {}, { textureType = true }) -- { colorSpace = "srgb", alphaIsTransparency = true, wrapU = "clamp", wrapV = "clamp" }

modules/TextureAssetTypeRef/settingsHealed

settingsHealed(values: { [string]: any }, stored: { [string]: any }): { [string]: any }?

The settings a local edit heals for a texture whose stored settings predate compression (they name no compression): the compression and texture type compressionFor answers for it. maxDimension heals as an older "no cap" reads (normalizeSettings), so a healed 8K texture stays 8K. Nothing else changes. Settings that name compression heal nothing.

Parameters

• values { [string]: any } — The texture's settings, as a read reports them.
• stored { [string]: any } — The settings exactly as stored.

M.settingsHealed({ compression = "rgba8", textureType = "color", filter = "linear" }, { format = "srgb" }) -- { compression = "uastc", textureType = "color" }

modules/TextureRef/README

require("@builtin::modules.texture_ref") -- TextureRef

The GPU key a material's texture slot binds by, resolved from whatever form the author wrote it in. Every path that accepts a texture reference — the .material assetType, renderer.material.create, renderer.material.setTexture — resolves through here, so the same string binds the same texture wherever it is written.

Usage: local TextureRef = require("@builtin::modules.texture_ref")

modules/TextureRef/isProcedural

isProcedural(ref: string): boolean

Whether a reference is one the GPU texture cache resolves on its own (color: / default: / runtime:), so it must be passed through untouched rather than looked up as an asset.

Parameters

• ref string — The reference string.

TextureRef.isProcedural("color:1,0,0,1") -- true

modules/TextureRef/resolve

resolve(ref: any, altIdentity: string?, site: string?): (string, string)

Resolve a texture reference to the resident GPU key the renderer binds a slot by, materialising the texture on the way. Accepts a guid, an asset identity, a bare name, a .texture path, or the image path a texture was imported from. color: / default: / runtime: forms and live GPU handles (a video frame, a render target) pass through untouched. An array:a|b|c reference resolves each layer the same way, materialising every layer texture the array is assembled from, and answers the array keyed by the layers' resolved keys.

Parameters

• ref any (optional) — The authored reference.
• altIdentity string? (optional) — Optional second candidate, tried when ref resolves to nothing — a slot's stable identity, so a binding whose guid was orphaned by a delete + recreate still finds the texture the author named.
• site string? (optional) — Optional VFS path of the asset whose file holds the reference — a material resolving its own mat.yaml slots. A package-relative ~.textures.x then expands against the package enclosing that asset, and a reference that asset's .refs recorded resolves to the texture recorded there. A site inside a carried mount resolves the reference within that mount.

TextureRef.resolve("wall.texture") -- "9f2c…", "asset"
TextureRef.resolve("array:grass.texture|rock.texture") -- "array:9f2c…|41ab…", "array"

modules/TextureRef/unresolvedMessage

unresolvedMessage(ref: string, what: string): string

The message describing a reference that names no texture. Bound anyway, the slot renders the shader's declared fallback, so the caller says this rather than letting the material render as though nothing was asked for.

Parameters

• ref string — The unresolved reference.
• what string — The call being made, for the message's subject.

TextureRef.unresolvedMessage("sky.jpg", "renderer.material.setTexture")

modules/ToolAssetTypeRef/README

require("@builtin::assetTypes.tool.behavior") -- ToolAssetTypeRef

Per-instance methods exposed on every AssetRef<tool>. Loaded lazily by assetType.shared.ref.

Usage: local ToolAssetTypeRef = require("@builtin::assetTypes.tool.behavior")

modules/ToolAssetTypeRef/getDefinition

getDefinition(self): string?

Read the tool's definition — its init.luau source, which carries the typed signature and the --!desc/--!arg/--!return/--!example docstring that together form the tool's schema.

Parameters

• self any (optional)

local raw = toolRef:getDefinition()

modules/ToolAssetTypeRef/getInitScript

getInitScript(self): string?

Read the tool's entry script as raw text.

Parameters

• self any (optional)

local src = toolRef:getInitScript()

modules/ToolAssetTypeRef/getReadme

getReadme(self): string?

Read the tool's README body.

Parameters

• self any (optional)

print(toolRef:getReadme())

modules/ToolAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { desc, args, returns, examples, signature }, parsed from the tool's own entry script (getInitScript) via luau_introspect.docstrings — the same --!desc/--!arg/--!return/--!example docstring that documents the tool's schema. Cached on the asset's content checksum, so re-inspecting unchanged source is free. A tool with no readable entry script returns an empty detail rather than erroring.

Parameters

• self any (optional)

local args = asset.inspect(toolRef).detail.args

modules/ToolAssetTypeRef/run

run(self, args: any): any

Invoke the tool's entry script. Requires the tool's identity and calls the first function it exports — the canonical function M.<name>(args) shape every tool ships. args is forwarded verbatim. Raises a Luau error (tagged with the tool's identity) on load or invocation failure rather than returning a swallowed nil — failing loudly matches the rest of the engine's tool dispatch surface.

Parameters

• self any (optional)
• args any (optional) — Optional table of arguments to pass to the tool's entry.

toolRef:run({ subject = "world" })

modules/ToolAssetTypeRef/wrap

wrap(fn: (...any) -> ...any, regionName: string): (...any) -> ...any

Standardize a single tool function into a ZmToolResult-returning call. THIS is where the tool-result contract lives — the engine's tool-bind paths (boot + runtime) apply wrap to every tool function so the result type is a system guarantee, never the individual tool's choice. The tool body returns its raw value, returns the Lua failure convention (nil, reason), or raises with error(msg); wrap produces the canonical envelope { ok, value | error, durationMs, tool } from all three — a (nil, reason) return becomes { ok = false, error = reason } instead of silently dropping the reason and reporting a bare success with no value. Timing is measured with the engine profiler: a region named for the tool is opened when the call is invoked and closed when it returns, so each invocation is both timed (region elapsed -> durationMs) and visible as a profiler region. Each envelope is also reported into the running task's tool-result buffer, which execute() auto-surfaces as the response's toolResults.

A tool that states MORE than one value on success — a path AND what that path holds — keeps them: the envelope carries the first as value, and every value past it follows the envelope out, so local a, b, c = tools.use(...) reads the tool the way the tool's own signature declares it. Keeping only the first turns every such declaration into a promise nobody can read.

Parameters

• fn (...any) -> ...any
• regionName string

Returns ...any

modules/ToolAssetTypeRef/wrapToolbox

wrapToolbox(box: { [string]: any }, namespace: string): { [string]: any }

Wrap every function on a toolbox table so each tool call returns a ZmToolResult (see wrap). Non-function fields pass through untouched.

Parameters

• box { [string]: any }
• namespace string

modules/ToolboxAssetTypeRef/README

require("@builtin::assetTypes.toolbox.behavior") -- ToolboxAssetTypeRef

Per-instance methods exposed on every AssetRef<toolbox>. Loaded lazily by assetType.shared.ref.

Usage: local ToolboxAssetTypeRef = require("@builtin::assetTypes.toolbox.behavior")

modules/ToolboxAssetTypeRef/getReadme

getReadme(self): string?

Read the toolbox's README.md body.

Parameters

• self any (optional)

print(toolboxRef:getReadme())

modules/ToolboxAssetTypeRef/hasShared

hasShared(self): boolean

Check whether the toolbox ships a shared.module/.

Parameters

• self any (optional)

if toolboxRef:hasShared() then ... end

modules/ToolboxAssetTypeRef/inspect

inspect(self): any

asset.inspect type-specific detail: { tools }, where tools is { name, desc } for every *.tool/ child the toolbox owns, walked directly from the toolbox's own folder — desc is the child tool's own --!desc docstring line, read from its entry script without requiring the tool module. A toolbox with no readable folder returns an empty tools list rather than erroring.

Parameters

• self any (optional)

local boxTools = asset.inspect(toolboxRef).detail.tools

modules/ToolboxAssetTypeRef/listTools

listTools(self): { any }

List the tool refs the toolbox carries. Walks the toolbox folder, finds every *.tool/ child, and resolves each to an AssetRef<tool>.

Parameters

• self any (optional)

for _, t in ipairs(toolboxRef:listTools()) do print(t.identity) end

modules/Trails/README

require("@builtin::systems.trails.trails") -- Trails

Continuous ribbon geometry that follows a moving point.

A trail is a strip of quads threaded along the positions something occupied over the last few seconds. Each recorded point contributes two vertices, offset either side of the direction of travel, and consecutive points are joined into a continuous surface — so a spark, a wingtip vapour trail or a sword arc is one mesh rather than a queue of sprites that betrays its spacing when the subject moves fast. Width, colour and opacity run from the head (the newest point) to the tail (the oldest), indexed by each point's age rather than its position in the list, so the fade reads the same whether the subject is crawling or sprinting. ribbon is pure: the same points, camera and settings produce the same arrays, so a trail's geometry can be checked without a scene.

Usage: local Trails = require("@builtin::systems.trails.trails")

modules/Trails/expire

expire(path: table, now: number) -> number

Drop points older than lifetime. Returns how many went.

Parameters

• path table
• now number

Returns number

modules/Trails/newPath

newPath(opts: table?) -> table

A fresh path. lifetime seconds a point survives, minDistance metres before a new one is recorded, maxPoints the ring's bound.

Parameters

• opts table? (optional)

Returns table

modules/Trails/pathOf

pathOf(id: string) -> table?

Parameters

• id string

Returns table?

modules/Trails/push

push(path: table, x: number, y: number, z: number, now: number) -> boolean

Record the head position when it has travelled minDistance from the last point. Returns whether a point was recorded.

Parameters

• path table
• x number
• y number
• z number
• now number

Returns boolean

modules/Trails/register

register(id: string, path: table)

Parameters

• id string
• path table

modules/Trails/ribbon

ribbon(path: table, opts: table) -> table?

Build the ribbon over a path's points — flat positions / normals / uvs / colors / indices, the shape renderer.mesh.create takes. nil under two points, which is no surface.

Parameters

• path table
• opts table

Returns table?

modules/Trails/stats

stats() -> table

Returns table

modules/Trails/unregister

unregister(id: string)

Parameters

• id string

modules/Transform/README

require("@builtin::modules.transform") -- Transform (also available as global 'Transform')

Math helpers for positions, rotations, and directions on transforms. Exposed as the global Transform table; entity-aware helpers accept an id string or an entity proxy.

Usage: local Transform = require("@builtin::modules.transform") Also available as global: Transform

modules/Transform/direction

direction(fromX: number, fromY: number, fromZ: number, toX: number, toY: number, toZ: number): (number, number, number)

Normalized direction vector from point A to point B. Returns zeros when the two points coincide (within ~0.001 units).

Parameters

• fromX number — From x.
• fromY number — From y.
• fromZ number — From z.
• toX number — To x.
• toY number — To y.
• toZ number — To z.

local dx, dy, dz = Transform.direction(0, 0, 0, 1, 0, 0)

modules/Transform/directionBetween

directionBetween(entityA: string | EntityRef, entityB: string | EntityRef): (number, number, number)

Normalized world-space direction from one entity to another, read from their world positions. Returns zeros if either entity can't be resolved.

Parameters

• entityA string | EntityRef — Source entity (id string or proxy).
• entityB string | EntityRef — Target entity (id string or proxy).

local dx, dy, dz = Transform.directionBetween("cam", "target")

modules/Transform/distance

distance(x1: number, y1: number, z1: number, x2: number, y2: number, z2: number): number

Euclidean distance between two world-space positions.

Parameters

• x1 number — First point x.
• y1 number — First point y.
• z1 number — First point z.
• x2 number — Second point x.
• y2 number — Second point y.
• z2 number — Second point z.

local d = Transform.distance(0, 0, 0, 1, 1, 1)

modules/Transform/distanceBetween

distanceBetween(entityA: string | EntityRef, entityB: string | EntityRef): number?

Distance between two entities in world space. Each entity's world position is what is measured, so a parent's offset counts toward the distance the way the scene shows it.

Parameters

• entityA string | EntityRef — First entity (id string or proxy).
• entityB string | EntityRef — Second entity (id string or proxy).

local d = Transform.distanceBetween("cam", "box")

modules/Transform/euler

euler(qx: number, qy: number, qz: number, qw: number): (number, number, number)

Convert quaternion to euler angles (yaw, pitch, roll) in radians.

Parameters

• qx number — Quaternion x.
• qy number — Quaternion y.
• qz number — Quaternion z.
• qw number — Quaternion w.

local yaw, pitch, roll = Transform.euler(0, 0, 0, 1)

modules/Transform/eulerToQuat

eulerToQuat(yaw: number, pitch: number?, roll: number?): (number, number, number, number)

Identity-aware overload of euler-to-quaternion. Uses the negative-yaw convention shared with quatFromYaw, quatFromYawPitch, lookAtQuat, and T.euler extraction — so T.euler(T.eulerToQuat(y, p, r)) returns (y, p, r). Order is yaw (Y) then pitch (X) then roll (Z).

Parameters

• yaw number — Y-axis rotation in radians.
• pitch number? (optional) — X-axis rotation in radians. Defaults to 0.
• roll number? (optional) — Z-axis rotation in radians. Defaults to 0.

local qx, qy, qz, qw = Transform.eulerToQuat(math.pi / 2)

modules/Transform/lerp

lerp(ax: number, ay: number, az: number, bx: number, by: number, bz: number, t: number): (number, number, number)

Linearly interpolate between two positions.

Parameters

• ax number — Start x.
• ay number — Start y.
• az number — Start z.
• bx number — End x.
• by number — End y.
• bz number — End z.
• t number — Interpolation factor [0, 1].

local x, y, z = Transform.lerp(0, 0, 0, 1, 1, 1, 0.5)

modules/Transform/lerp1

lerp1(a: number, b: number, t: number): number

Linearly interpolate two scalars.

Parameters

• a number — Start value.
• b number — End value.
• t number — Interpolation factor [0, 1].

local v = Transform.lerp1(0, 10, 0.5)

modules/Transform/lerpAngle

lerpAngle(a: number, b: number, t: number): number

Lerp between two angles via the shortest arc; returns a value in [-pi, pi].

Parameters

• a number — Start angle in radians.
• b number — End angle in radians.
• t number — Interpolation factor [0, 1].

local a = Transform.lerpAngle(0, math.pi, 0.5)

modules/Transform/localToWorld

localToWorld(px: number, py: number, pz: number, pqx: number, pqy: number, pqz: number, pqw: number, lx: number, ly: number, lz: number): (number, number, number)

Transform a local-space position into world space using a parent pose.

Parameters

• px number — Parent position x.
• py number — Parent position y.
• pz number — Parent position z.
• pqx number — Parent rotation x.
• pqy number — Parent rotation y.
• pqz number — Parent rotation z.
• pqw number — Parent rotation w.
• lx number — Local x.
• ly number — Local y.
• lz number — Local z.

local wx, wy, wz = Transform.localToWorld(px, py, pz, pqx, pqy, pqz, pqw, lx, ly, lz)

modules/Transform/lookAt

lookAt(entityOrId: string | EntityRef, txOrTarget: any, ty: any?, tz: number?, up: any?): (boolean, string?)

Make an entity face a world position. The target slot accepts three explicit coordinates, one point as { x, y, z } / { x =, y =, z = } / a vector, or an entity — an id string, an entity NAME, or a proxy — whose WORLD position is resolved. A table carrying an entity id reads as that entity; any other table reads as the point it spells. The subject slot takes the three entity spellings. Everything here is world space: the subject and the target are read as entity(id).position and the aim is written as entity(id).rotation, so a parent under either one moves the entity and the aim still lands on the point named. Returns whether the rotation was written, so a caller that named an entity the scene does not carry learns the aim did not happen instead of reading a stale orientation back as the answer.

Parameters

• entityOrId string | EntityRef — Entity id, name, or proxy for the entity to rotate.
• txOrTarget any (optional) — A number (world x), a point table, or an entity id / name / proxy whose world position is resolved as the look-at target.
• ty any? (optional) — World y of the target. Omitted when txOrTarget is a point or an entity.
• tz number? (optional) — World z of the target. Omitted when txOrTarget is a point or an entity.
• up any? (optional) — Optional world up hint deciding the roll — { x, y, z }, { x =, y =, z = } or a vector. World +Y when omitted. It never bends the aim; it only says which way is up around it. When the target slot is an entity or a point this is the third argument, and when it is coordinates the fifth.

Transform.lookAt("cam", 0, 1, 0)
Transform.lookAt("cam", "box")  -- resolve target entity position
Transform.lookAt(cam, box)      -- entity proxies for both
Transform.lookAt("cam", { 0, 1, 0 })         -- one point table
Transform.lookAt("cam", "box", { 0, 0, 1 })  -- rolled to a +Z up

modules/Transform/lookAtQuat

lookAtQuat(fx: number, fy: number, fz: number, tx: number, ty: number, tz: number): (number?, number?, number?, number?)

Compute quaternion to look from origin position toward a target. Returns four components (qx, qy, qz, qw), or nil when the from and to points are too close to derive a meaningful direction.

Parameters

• fx number — Origin x.
• fy number — Origin y.
• fz number — Origin z.
• tx number — Target x.
• ty number — Target y.
• tz number — Target z.

local qx, qy, qz, qw = Transform.lookAtQuat(0, 0, 0, 1, 0, 1)

modules/Transform/lookRotation

lookRotation(fx: number, fy: number, fz: number, tx: number, ty: number, tz: number, ux: number?, uy: number?, uz: number?): (number?, number?, number?, number?)

The rotation that aims an entity standing at one world point at another, with a world up hint deciding the roll. Where lookAtQuat derives the aim from yaw and pitch alone — clamping the pitch just short of vertical, so a point directly overhead comes back a twentieth of a degree off — this builds all three axes, so the aim lands on the point at any elevation and straight up and straight down are ordinary cases. The aimed axis is the entity's local -Z, the same forward quatFromBasis, Transform.lookAt and entity(id):lookAt state and the direction entity(id).transform.forward reads back. The up hint is a world direction the entity's own +Y is turned toward as far as the aim allows; it never bends the forward axis. A hint parallel to the aim leaves the roll undetermined, and a hint of no length names no direction — both fall back to a stable roll rather than a NaN.

Parameters

• fx number — Eye x — where the entity stands.
• fy number — Eye y.
• fz number — Eye z.
• tx number — Target x — the world point it faces.
• ty number — Target y.
• tz number — Target z.
• ux number? (optional) — Up hint x. World +Y when the hint is omitted.
• uy number? (optional) — Up hint y.
• uz number? (optional) — Up hint z.

local qx, qy, qz, qw = Transform.lookRotation(0, 2, 10, 0, 1, 0)
entity("cam").rotation = { Transform.lookRotation(0, 2, 10, 0, 1, 0) }
-- a dutch tilt: the same aim, rolled by leaning the up hint
local q = { Transform.lookRotation(0, 2, 10, 0, 1, 0, 0.2, 1, 0) }

modules/Transform/normalizeAngle

normalizeAngle(a: number): number

Normalize an angle into [-pi, pi].

Parameters

• a number — The angle in radians.

local a = Transform.normalizeAngle(3 * math.pi)

modules/Transform/orbit

orbit(centerX: number, centerY: number, centerZ: number, radius: number, height: number, angle: number): (number, number, number, number, number, number, number)

Position + rotation for orbiting around a center point. Returns the world position followed by the orientation that faces the center.

Parameters

• centerX number — Center x.
• centerY number — Center y.
• centerZ number — Center z.
• radius number — Horizontal distance from the center.
• height number — Vertical offset from centerY.
• angle number — Orbital angle in radians.

local x, y, z, qx, qy, qz, qw = Transform.orbit(0, 1, 0, 5, 2, t)

modules/Transform/quatFromAxisAngle

quatFromAxisAngle(ax: number, ay: number, az: number, angle: number): (number, number, number, number)

Create quaternion from axis and angle (radians). Returns the identity quaternion when the axis is degenerate (length < 0.001).

Parameters

• ax number — Axis x.
• ay number — Axis y.
• az number — Axis z.
• angle number — Rotation angle in radians.

local qx, qy, qz, qw = Transform.quatFromAxisAngle(0, 1, 0, math.pi)

modules/Transform/quatFromBasis

quatFromBasis(rx: number, ry: number, rz: number, ux: number, uy: number, uz: number, fx: number, fy: number, fz: number): (number, number, number, number)

Build the rotation whose right, up and forward ARE the given axes. Where lookAtQuat derives a rotation from a direction alone — yaw and pitch, with pitch clamped just short of straight up or down and no say in the roll — this states all three axes, so a view straight down has a defined image-up instead of whatever the yaw implied. The axes are expected orthonormal and are used as given: right and up are the entity's local +X and +Y, forward its local -Z (the direction it faces).

Parameters

• rx number — Right axis x.
• ry number — Right axis y.
• rz number — Right axis z.
• ux number — Up axis x.
• uy number — Up axis y.
• uz number — Up axis z.
• fx number — Forward axis x.
• fy number — Forward axis y.
• fz number — Forward axis z.

local qx, qy, qz, qw = Transform.quatFromBasis(1,0,0, 0,1,0, 0,0,-1) -- identity
-- looking straight down with the subject's front toward the top of frame
local qx, qy, qz, qw = Transform.quatFromBasis(1,0,0, 0,0,-1, 0,-1,0)

modules/Transform/quatFromYaw

quatFromYaw(yaw: number): (number, number, number, number)

Create quaternion from yaw (Y-axis rotation) in radians. Uses the negative-yaw convention shared with quatFromYawPitch, lookAtQuat, and T.euler extraction — so T.euler(T.quatFromYaw(y)) round-trips to y.

Parameters

• yaw number — Rotation in radians around the Y axis.

local qx, qy, qz, qw = Transform.quatFromYaw(math.pi / 2)

modules/Transform/quatFromYawPitch

quatFromYawPitch(yaw: number, pitch: number): (number, number, number, number)

Create quaternion from yaw and pitch in radians.

Parameters

• yaw number — Y-axis rotation in radians.
• pitch number — X-axis rotation in radians.

local qx, qy, qz, qw = Transform.quatFromYawPitch(0, math.pi / 4)

modules/Transform/quatIdentity

quatIdentity(): (number, number, number, number)

Identity quaternion (0, 0, 0, 1).

local qx, qy, qz, qw = Transform.quatIdentity()

modules/Transform/quatInverse

quatInverse(qx: number, qy: number, qz: number, qw: number): (number, number, number, number)

Quaternion inverse. Equal to the conjugate for unit quaternions.

Parameters

• qx number — Quaternion x.
• qy number — Quaternion y.
• qz number — Quaternion z.
• qw number — Quaternion w.

local ix, iy, iz, iw = Transform.quatInverse(qx, qy, qz, qw)

modules/Transform/quatMul

quatMul(ax: number, ay: number, az: number, aw: number, bx: number, by: number, bz: number, bw: number): (number, number, number, number)

Quaternion multiplication: returns qa * qb (composition: rotate by qb then qa).

Parameters

• ax number — Left quat x.
• ay number — Left quat y.
• az number — Left quat z.
• aw number — Left quat w.
• bx number — Right quat x.
• by number — Right quat y.
• bz number — Right quat z.
• bw number — Right quat w.

local qx, qy, qz, qw = Transform.quatMul(ax, ay, az, aw, bx, by, bz, bw)

modules/Transform/quatRotateVec

quatRotateVec(qx: number, qy: number, qz: number, qw: number, vx: number, vy: number, vz: number): (number, number, number)

Rotate a 3-vector by a quaternion.

Parameters

• qx number — Quaternion x.
• qy number — Quaternion y.
• qz number — Quaternion z.
• qw number — Quaternion w.
• vx number — Vector x.
• vy number — Vector y.
• vz number — Vector z.

local rx, ry, rz = Transform.quatRotateVec(qx, qy, qz, qw, 1, 0, 0)

modules/Transform/quatToEuler

quatToEuler(qx: number, qy: number, qz: number, qw: number): (number, number, number)

Convert quaternion to (yaw, pitch, roll). Alias of euler with the explicit name so callers don't have to remember the order.

Parameters

• qx number — Quaternion x.
• qy number — Quaternion y.
• qz number — Quaternion z.
• qw number — Quaternion w.

local yaw, pitch, roll = Transform.quatToEuler(qx, qy, qz, qw)

modules/Transform/readVec3

readVec3(value: Vec3Input, label: string?): { number }

Normalize a vector a caller wrote to a plain { x, y, z } array. Accepts a positional array {1, 2, 3}, a keyed table {x =, y =, z =}, or a live vec handle. Missing components read as 0. Raises when the value is not a vector; label names the caller in that error.

Parameters

• value Vec3Input — The vector to normalize.
• label string? (optional) — Name reported in the error when the value is not a vector. Defaults to "Transform".

local v = Transform.readVec3({ x = 1, y = 2, z = 3 })

modules/Transform/slerp

slerp(ax: number, ay: number, az: number, aw: number, bx: number, by: number, bz: number, bw: number, t: number): (number, number, number, number)

Spherical linear interpolation between two quaternions. Picks the shortest path (flips sign if dot < 0). Falls back to lerp+normalize when the two quats are very close (avoids div-by-zero on near-parallel inputs).

Parameters

• ax number — Start quaternion x.
• ay number — Start quaternion y.
• az number — Start quaternion z.
• aw number — Start quaternion w.
• bx number — End quaternion x.
• by number — End quaternion y.
• bz number — End quaternion z.
• bw number — End quaternion w.
• t number — Interpolation factor [0, 1].

local qx, qy, qz, qw = Transform.slerp(0, 0, 0, 1, 1, 0, 0, 0, 0.5)

modules/Transform/snapVec3

snapVec3(v: { number }, step: number | Vec3Input): { number }

Quantize each component of a vector to the nearest multiple of step — a number for uniform steps, or a vector for per-axis steps. A step of 0 on an axis leaves that axis at its exact value.

Parameters

• v { number } — The vector to quantize, as { x, y, z }.
• step number | Vec3Input — Uniform step size, or a per-axis vector of step sizes.

local v = Transform.snapVec3({ 1.4, 2.6, -0.4 }, 1)

modules/Transform/toQuaternion

toQuaternion(rotation: any, label: string?): { number }

Normalize a rotation a caller wrote to a { qx, qy, qz, qw } quaternion. Accepts a quaternion ({x,y,z,w} or {x=,y=,z=,w=}) or euler DEGREES ({pitch,yaw,roll} or {pitch=,yaw=,roll=}), so one call site takes whichever form the caller finds natural. This is the reading every rotation-taking surface in the engine shares, so a quaternion and euler degrees mean the same thing at all of them. Raises when the value matches no form; label names the caller in that error, and a value that is one of the shapes a quaternion helper returns is named as such along with the packing it goes in as.

Parameters

• rotation any (optional) — The rotation to normalize, in any form of the RotationInput union.
• label string? (optional) — Name reported in the error when the value is not a rotation. Defaults to "Transform".

local q = Transform.toQuaternion({ pitch = 0, yaw = 90, roll = 0 })

modules/Transform/tryQuaternion

tryQuaternion(rotation: any, label: string?): ({ number }?, string?)

Read a rotation a caller wrote WITHOUT raising: returns the canonical { qx, qy, qz, qw }, or nil and the message describing what arrived. The forms are the RotationInput union — a quaternion ({x,y,z,w} or {x=,y=,z=,w=}) or euler DEGREES ({pitch,yaw,roll} or {pitch=,yaw=,roll=}). Takes any value because reporting on a value that is none of those forms is the whole job; a setter built on this raises the returned message itself, so the error points at the line that wrote the value rather than at the reading.

Parameters

• rotation any (optional) — The value to read as a rotation.
• label string? (optional) — Name reported in the message. Defaults to "Transform".

local q, why = Transform.tryQuaternion(value, "myTool")

modules/Transform/vec.add

vec.add(ax: number, ay: number, az: number, bx: number, by: number, bz: number): (number, number, number)

Component-wise vec3 addition.

Parameters

• ax number — First vector x.
• ay number — First vector y.
• az number — First vector z.
• bx number — Second vector x.
• by number — Second vector y.
• bz number — Second vector z.

local x, y, z = Transform.vec.add(1, 2, 3, 4, 5, 6)

modules/Transform/vec.cross

vec.cross(ax: number, ay: number, az: number, bx: number, by: number, bz: number): (number, number, number)

Cross product a x b.

Parameters

• ax number — First vector x.
• ay number — First vector y.
• az number — First vector z.
• bx number — Second vector x.
• by number — Second vector y.
• bz number — Second vector z.

local cx, cy, cz = Transform.vec.cross(1, 0, 0, 0, 1, 0)

modules/Transform/vec.dot

vec.dot(ax: number, ay: number, az: number, bx: number, by: number, bz: number): number

Dot product of two vec3s.

Parameters

• ax number — First vector x.
• ay number — First vector y.
• az number — First vector z.
• bx number — Second vector x.
• by number — Second vector y.
• bz number — Second vector z.

local d = Transform.vec.dot(1, 0, 0, 0, 1, 0)

modules/Transform/vec.length

vec.length(x: number, y: number, z: number): number

Euclidean length of a vec3.

Parameters

• x number — Vector x.
• y number — Vector y.
• z number — Vector z.

local len = Transform.vec.length(1, 2, 3)

modules/Transform/vec.normalize

vec.normalize(x: number, y: number, z: number): (number, number, number)

Normalize a vec3. Returns zeros when the input is degenerate (length < 1e-8).

Parameters

• x number — Vector x.
• y number — Vector y.
• z number — Vector z.

local nx, ny, nz = Transform.vec.normalize(0, 5, 0)

modules/Transform/vec.scale

vec.scale(x: number, y: number, z: number, s: number): (number, number, number)

Component-wise scalar multiplication of a vec3.

Parameters

• x number — Vector x.
• y number — Vector y.
• z number — Vector z.
• s number — Scalar factor.

local x, y, z = Transform.vec.scale(1, 2, 3, 2)

modules/Transform/vec.sub

vec.sub(ax: number, ay: number, az: number, bx: number, by: number, bz: number): (number, number, number)

Component-wise vec3 subtraction (a - b).

Parameters

• ax number — First vector x.
• ay number — First vector y.
• az number — First vector z.
• bx number — Second vector x.
• by number — Second vector y.
• bz number — Second vector z.

local x, y, z = Transform.vec.sub(4, 5, 6, 1, 2, 3)

modules/Transform/worldToLocal

worldToLocal(px: number, py: number, pz: number, pqx: number, pqy: number, pqz: number, pqw: number, wx: number, wy: number, wz: number): (number, number, number)

Transform a world-space position into a parent's local space.

Parameters

• px number — Parent position x.
• py number — Parent position y.
• pz number — Parent position z.
• pqx number — Parent rotation x.
• pqy number — Parent rotation y.
• pqz number — Parent rotation z.
• pqw number — Parent rotation w.
• wx number — World x.
• wy number — World y.
• wz number — World z.

local lx, ly, lz = Transform.worldToLocal(px, py, pz, pqx, pqy, pqz, pqw, wx, wy, wz)

modules/UiMotionCapture/README

require("@builtin::modules.ui_motion_capture") -- UiMotionCapture

Publishes the UI-animation capture views — the UI analogues of the motion_vectors pass. capture pass=ui_motion shows WHERE the UI is animating (change-magnitude heatmap); capture pass=ui_motion_flow shows WHICH WAY it is moving (directional optical flow). Each view's drawing feature is created on demand the first time it is captured, so a session that never selects one pays nothing.

Usage: local UiMotionCapture = require("@builtin::modules.ui_motion_capture")

modules/UiMotionCapture/register

register()

Register the ui_motion (change magnitude) and ui_motion_flow (directional flow) capture views. Idempotent — safe to call at boot and again later; re-registering keeps each view's channel.

require("@builtin::modules.ui_motion_capture").register()

modules/Validator/README

require("@builtin::systems.worldValidation.validator") -- Validator

Orchestrator for the world validator. Composes vfsScanner + scriptValidator + assetValidator + reportFormatter into one call that produces a Report with world and library buckets cleanly separated.

The validator does ONE pass over the VFS to discover every script and asset, then dispatches each entry to the appropriate per-type validator (scripts → scriptValidator → lsp.check; asset folders → assetValidator → asset.validate). It does not spawn entities or allocate GPU resources. Repeated calls are independent — there is no shared mutable state across runs. The four helper modules (vfsScanner, scriptValidator, assetValidator, reportFormatter) sit alongside this module at the package root and are pulled in via the ~.X package-relative form so the whole package is position-independent — moving it to any identity continues to resolve correctly without code edits.

Usage: local Validator = require("@builtin::systems.worldValidation.validator")

modules/Validator/check

check(opts)

Validate authored content. By DEFAULT scopes to YOUR world — everything under /source/ EXCEPT /source/libs/ — because imported libraries and engine builtins are not yours to validate (and scanning the whole builtin tree is slow and noisy). Pass opts.scope to widen: "libraries" for every imported library, "library:<name>" for one, "all" for world + libraries together. The cargo check equivalent for a Zero world.

Parameters

• opts any (optional) — Optional table — scope?: "world"|"libraries"|"library:<name>"|"all" (default "world") plus filter fields forwarded to the formatter: { severity, category, code, source, path, includePlaceholders, limit }.

local r = Validator.check()                         -- your world only
local r = Validator.check({ severity = "error" })   -- your world, errors only
local r = Validator.check({ scope = "all" })        -- world + imported libraries

modules/Validator/filter

filter(report, opts)

Re-filter an existing Report without re-scanning the VFS. Forwards to reportFormatter.filter; the resulting Report's counts are recomputed from the visible problems.

Parameters

• report any (optional) — Report produced by any of the validate* functions.
• opts any (optional) — FilterOpts — { severity, category, code, source, path, includePlaceholders, limit }.

local errs = Validator.filter(report, { severity = "error" })

modules/Validator/format

format(report, format)

Render a Report into a string. format selects the renderer.

Parameters

• report any (optional) — Report produced by any of the validate* functions.
• format any (optional) — "human" (default) / "markdown" / "json" / "summary".

print(Validator.format(report, "human"))
local md = Validator.format(report, "markdown")

modules/Validator/placeholders

placeholders()

Enumerate the registered placeholder checks. Each placeholder is a check the validator runs today but with a stub implementation — listing them tells callers which validations still need real primitives wired up.

for _, ph in ipairs(Validator.placeholders()) do print(ph.code) end

modules/Validator/saveReport

saveReport(report, path, opts)

Render a Report and write it to path. Format is taken from opts.format if present, otherwise inferred from the destination extension (.md → markdown, .json → json, anything else → human). Returns (ok, message?).

Parameters

• report any (optional) — Report produced by any of the validate* functions.
• path any (optional) — Destination VFS path (e.g. /source/.validation/run.md).
• opts any (optional) — Optional { format } override.

Validator.saveReport(report, "/source/.validation/run.md")
Validator.saveReport(report, "/source/audit.json", { format = "json" })

modules/Validator/summary

summary(report)

Compact one-line health summary — world: NE/NW libraries: NE/NW total: OK|FAIL.

Parameters

• report any (optional) — Report produced by any of the validate* functions.

print(Validator.summary(Validator.check()))

modules/Validator/validateLibraries

validateLibraries(opts)

Validate every imported library under /source/libs/. The returned Report has world = nil and libraries populated for every library that exists on disk.

Parameters

• opts any (optional) — Optional filter table — same shape as M.check.

local r = Validator.validateLibraries()
local r = Validator.validateLibraries({ source = "library:@builtin" })

modules/Validator/validateLibrary

validateLibrary(name, opts)

Validate ONE named library under /source/libs/<name>/. When the library does not exist, the Report carries a single library.missing error against that name so callers can tell a clean run from a missing-dependency run.

Parameters

• name any (optional) — Library directory name (e.g. "@builtin", "@mylib").
• opts any (optional) — Optional filter table — same shape as M.check.

local r = Validator.validateLibrary("@builtin")
local r = Validator.validateLibrary("@mylib", { severity = "error" })

modules/Validator/validateWorld

validateWorld(opts)

Validate ONLY the world's authored content (/source/ excluding /source/libs/). The returned Report has world populated and libraries = {}.

Parameters

• opts any (optional) — Optional filter table — same shape as M.check.

local r = Validator.validateWorld()
local r = Validator.validateWorld({ severity = "error" })

modules/ValueType/README

require("@builtin::modules.value_type") -- ValueType

Converts a handle-backed value type — ColorSequence, NumberSequence — between the live object a session holds and the durable payload its serialize() produces. Every boundary that writes a component field to a record, or applies a record back onto a component, converts here.

Usage: local ValueType = require("@builtin::modules.value_type")

modules/ValueType/bind

bind(v: any, kind: string): any

Put a value type's methods back on a value read out of a component field. Field.table keeps the table it is handed without its metatable and gives that stored table back on every read, so binding once makes the field answer :evaluate / :keypoints for the rest of the session.

Parameters

• v any (optional) — A live value carrying a handle.
• kind string — The kind to bind as when v names none itself.

ValueType.bind(component.color, "ColorSequence"):evaluate(0)

modules/ValueType/isLive

isLive(v: any): boolean

Whether a value is a live handle-backed value type — the form that holds a session-local curve handle.

Parameters

• v any (optional) — Any component field value.

ValueType.isLive(NumberSequence.new(0, 1)) -- true

modules/ValueType/isPayload

isPayload(v: any): boolean

Whether a value is the durable payload of a handle-backed value type — the form a record carries.

Parameters

• v any (optional) — Any component field value.

ValueType.isPayload(NumberSequence.new(0, 1):serialize()) -- true

modules/ValueType/keypoints

keypoints(v: any, kind: string): { any }?

The keypoint list a value holds, whichever of the two forms it is in. A caller that knows the field's type passes it as kind so a bare { __h = n } — a handle written by a session that named no kind — is still read as that type.

Parameters

• v any (optional) — A live value, a durable payload, or a bare handle table.
• kind string — The kind to read v as when v names none itself.

ValueType.keypoints(field, "ColorSequence")

modules/ValueType/kindOf

kindOf(v: any): string?

The kind name a value declares, when it is one this module converts.

Parameters

• v any (optional) — Any component field value.

ValueType.kindOf(ColorSequence.new({1, 0, 0})) -- "ColorSequence"

modules/ValueType/revive

revive(v: any): any?

The live value a durable payload names, rebuilt in this session.

Parameters

• v any (optional) — Any component field value.

ValueType.revive(record.color)

modules/ValueType/serialize

serialize(v: any): any?

The durable payload for a live value — what a record stores in place of the session-local handle.

Parameters

• v any (optional) — Any component field value.

ValueType.serialize(field) -- { kind = "ColorSequence", keypoints = {...} }

modules/ValueType/withRevived

withRevived(data: any): (any, number)

The component field map to apply, with every durable payload rebuilt as the live value it names — the counterpart of the saver writing payloads in place of handles.

Parameters

• data any (optional) — A component's { field = value } map from a record.

ValueType.withRevived(record.data)

modules/VfsScanner/README

require("@builtin::systems.worldValidation.vfsScanner") -- VfsScanner

Recursive /source/ walker for the world validator. Separates world content from imported libraries so downstream validators can attribute every problem to the right bucket.

An asset root is any folder whose name has a registered asset type suffix (Foo.component, bar.module, Baz.toolbox, …). When the scanner crosses one it records the root and does NOT recurse into it as raw files — the asset validator handles the interior. Scripts (.luau, .lua) discovered outside any asset root are also recorded (e.g. _shared.luau siblings inside a toolbox, or stray top-level scripts).

Usage: local VfsScanner = require("@builtin::systems.worldValidation.vfsScanner")

modules/VfsScanner/assetSuffixes

assetSuffixes(): { string }

Expose the registered asset-suffix list (read-only). External callers that want to recognise asset folders the same way the scanner does can iterate this list.

for _, s in ipairs(VfsScanner.assetSuffixes()) do print(s) end

modules/VfsScanner/listLibraryNames

listLibraryNames(): { string }

Enumerate the immediate children of /source/libs/. Each child is a library identity (e.g. @builtin, @mylib). Returns an empty array if /source/libs/ does not exist.

for _, name in ipairs(VfsScanner.listLibraryNames()) do print(name) end

modules/VfsScanner/scanAll

scanAll()

Convenience: scan world + every imported library in one call.

local scan = VfsScanner.scanAll(); print(#scan.world.assets)

modules/VfsScanner/scanLibraries

scanLibraries(): { [string]: any }

Walk every imported library and return a map keyed by name.

local libs = VfsScanner.scanLibraries(); for n, b in pairs(libs) do print(n, #b.assets) end

modules/VfsScanner/scanLibrary

scanLibrary(name: string)

Walk one named library under /source/libs/<name>/. The returned Bucket's rootPath is the library root so callers can derive relative paths cheaply.

Parameters

• name string — Library directory name (e.g. "@builtin").

local bucket = VfsScanner.scanLibrary("@builtin")

modules/VfsScanner/scanWorld

scanWorld()

Walk only the world bucket — everything under /source/ except /source/libs/. The scanner stops recursing whenever it reaches an asset-suffixed folder; asset interiors are handled by the assetValidator.

local bucket = VfsScanner.scanWorld()

modules/WorkflowAssetTypeRef/README

require("@builtin::assetTypes.workflow.behavior") -- WorkflowAssetTypeRef

Per-instance methods exposed on every AssetRef<workflow>. Loaded lazily by asset_ref.module.

Usage: local WorkflowAssetTypeRef = require("@builtin::assetTypes.workflow.behavior")

modules/WorkflowAssetTypeRef/getManifest

getManifest(self): { [string]: any }

Read and parse workflow.yaml: what this workflow is, when it is reached for, and the phases it moves through.

Parameters

• self any (optional)

local m = wf:getManifest()

modules/WorkflowAssetTypeRef/getSource

getSource(self): string?

Read the program itself — the JavaScript body that runs when the workflow is started.

Parameters

• self any (optional)

local src = wf:getSource()

modules/WorkflowAssetTypeRef/inspect

inspect(self): { [string]: any }

What this workflow is, without running it: its description, when to reach for it, the phases it moves through, and what it expects in args.

Parameters

• self any (optional)

local info = wf:inspect()

modules/WorkflowAssetTypeRef/start

start(self, args: { [string]: any }?): { [string]: any }

Start a run of this workflow. Returns immediately: the run is already executing, and it parks the moment it asks its first question. Answer what it asks through the workflow toolbox — the run decides what comes next.

Parameters

• self any (optional)
• args { [string]: any }? (optional) — Optional table handed to the program as its args.

local run = wf:start({ concept = "outrun a tornado" })

modules/World/README

require("@builtin::modules.world") -- World (also available as global 'world')

Public Luau API for the bound world. Composes internal __world FFI primitives with per-mode slot defaults (world_defaults), source-control toolbox (world_vcs), and the connected-users registry (connected_users) into a single namespace. Usage: world.guid() -- current world GUID, nil if none world.swap(guid) -- bind to another world (promise) world.avatar_default_edit = ref -- per-mode avatar default world.on("player_join", cb) -- world-level event hooks Implemented as a thin Luau wrapper. The world global is a plain table whose __index metatable falls through to the internal __world namespace for unknown reads. Other library modules (world_defaults, world_vcs, connected_users) attach their surfaces via installInto(world) from prelude.luau; their metatable wrappers chain through this base layer correctly.

Usage: local World = require("@builtin::modules.world") Also available as global: world

modules/Yaml/README

require("@builtin::modules.yaml") -- Yaml

YAML decode + encode for authored engine content. Supports the YAML subset engine configs use: block mappings + sequences (a sequence may sit at its key's own column), flow collections (on one line or continued over several), typed plain scalars, quoted strings, comments, literal and folded block scalars, an optional leading ---. Unsupported constructs (anchors, aliases, tags, directives, multi-document streams, tab indentation) raise with the offending line number.

Usage: local Yaml = require("@builtin::modules.yaml")

modules/Yaml/decode

decode(text: string): any

Decode a YAML document into a Luau value. Raises (with the line number) on malformed input or constructs outside the supported subset — never misparses silently.

Parameters

• text string — The YAML document text.

local doc = Yaml.decode(vfs.read(path))

modules/Yaml/decodeWithComments

decodeWithComments(text: string): (any, boolean)

Decode a YAML document and report whether it carries a comment — by the decoder's own rule: a # at a line's start or after whitespace, outside a quoted scalar (a quote opens one only where a scalar can begin, so a plain scalar may carry an apostrophe) and outside a block scalar. What re-encoding the value would drop.

Parameters

• text string — The YAML document text.

local doc, commented = Yaml.decodeWithComments(vfs.read(path))

modules/Yaml/encode

encode(value: { [any]: any }): string

Encode a Luau table as a YAML document (block style, two-space indent, sorted keys). Raises on values YAML can't represent (functions, userdata, non-string mapping keys).

Parameters

• value { [any]: any } — The table to encode.

vfs.write(path, Yaml.encode({ contract = "weapon", values = v }))

modules/Yaml/flowEntries

flowEntries(text: string): ({ FlowEntry }, string)

Split a flow collection written on one line, { a: 1, b: [2, 3] } or [x, { y: 2 }], into its top-level entries as written: each entry's key (unquoted; nil for a sequence item) and its value text, trimmed, with nested collections, quoted scalars and the literal spelling of every value kept. Raises with the decoder's own message on text that is not one well-formed flow collection, so it accepts exactly what decode reads as a flow value.

Parameters

• text string — The flow collection's text.

for _, e in Yaml.flowEntries("{ exposure: 1.5, tint: [1, 0, 0] }") do print(e.key, e.value) end
local entries, trailing = Yaml.flowEntries("{ exposure: 1.5 } # brighter")

modules/ZJsAssetTypeRef/README

require("@builtin::packages.zerojs.zJs.behavior") -- ZJsAssetTypeRef

Per-instance methods exposed on every AssetRef<zJs>. Loaded lazily by asset_ref.module the first time a zJs ref is touched in a VM. A zJs asset is a <name>.zJs/ folder whose main.js holds a JavaScript ES module. The methods here surface the static write-time diagnostics the type computes for that module and execute it: run / runAsync for a script or module, and exports to read a module's export namespace as a Luau table.

Usage: local ZJsAssetTypeRef = require("@builtin::packages.zerojs.zJs.behavior")

modules/ZJsAssetTypeRef/check

check(self): { ok: boolean, diagnostics: { Diagnostic } }

Static diagnostics for THIS module's main.js: parse errors plus imports that do not resolve to a zJs module. Reads the cache onChange maintains, running the parse+resolve pipeline once on a cold reference.

Parameters

• self any (optional)

local r = asset.resolve("greeter", "zJs"):check(); if not r.ok then ... end

modules/ZJsAssetTypeRef/exports

exports(self, opts: { env: { [string]: any }? }?): any

Evaluate THIS module as an ES module on a fresh VM and return its export namespace marshaled to a Luau table: each named export plus default. Cross-asset imports resolve through the live asset index, so a JS library built from several .zJs assets is consumed as one table. Refuses when the module carries diagnostics, naming the first; a cycle, an unresolved import, or a thrown module body surfaces as a Luau error.

Parameters

• self any (optional)
• opts { env: { [string]: any }? }? (optional)

local lib = asset.resolve("mathlib", "zJs"):exports(); print(lib.add(1, 2))

modules/ZJsAssetTypeRef/onChange

onChange(ref, change)

Asset-type change callback: recompute this module's static diagnostics whenever its main.js is edited or the whole instance is seeded. Convergent: it reads the source and asset index and replaces the ref's cached pipeline result; it never writes to the VFS. Edits to sidecars (README.md, .metadata) leave the cache untouched.

Parameters

• ref any (optional)
• change any (optional)

modules/ZJsAssetTypeRef/onCreate

onCreate(name: string, opts: CreateOpts): { [string]: string }

Generic-creation hook for asset.create("zJs", name, opts). Pure: returns the instance's content file map for the caller to persist. opts.source, when given, becomes main.js verbatim; otherwise a hello-world module naming the instance is scaffolded from the template.

Parameters

• name string — zJs module identity (the instance name).
• opts CreateOpts

asset.create("zJs", "greeter", { source = "export const x = 1" })

modules/ZJsAssetTypeRef/run

run(self, opts: { env: { [string]: any }? }?): any

Execute THIS module on a fresh JavaScript VM and marshal the result to Luau. A plain script (no imports or exports) runs as a script and returns its completion value; a module evaluates through the module graph and returns nil, since module evaluation has no completion value. opts.env seeds host values as JavaScript globals. Refuses when the module carries diagnostics, naming the first, and directs a script that leaves asynchronous work pending to runAsync.

Parameters

• self any (optional)
• opts { env: { [string]: any }? }? (optional)

local sum = asset.resolve("calc", "zJs"):run({ env = { base = 10 } })

modules/ZJsAssetTypeRef/runAsync

runAsync(self, opts: { env: { [string]: any }?, timeoutMs: number? }?): any

Execute THIS module's program on a fresh VM under the asynchronous runner, driving armed timers and pending promises to completion. Returns the engine run handle: poll handle.done, then read handle.ok / handle.value / handle.error, or call handle:await() from a yieldable context. opts.timeoutMs bounds a never-settling run. Refuses when the module carries diagnostics, naming the first.

Parameters

• self any (optional)
• opts { env: { [string]: any }?, timeoutMs: number? }? (optional)

local h = asset.resolve("job", "zJs"):runAsync({ timeoutMs = 1000 }); h:await()

modules/ZinputActions/README

require("@builtin::modules.zinput.actions") -- ZinputActions

DEPRECATED: A control asset carries what an action carried, plus the gamepad and touch an action never had. Author an .inputMap with .inputBinding children, activate it, and subscribe: local map = public.inputMap:activate() then map.jump:onPressed(fn). See man topics/input.

Usage: local ZinputActions = require("@builtin::modules.zinput.actions")

modules/ZinputActions/_clearHandlers

_clearHandlers()

Test-only: clear every handler (does NOT touch action definitions).

Zin.actions._clearHandlers()

modules/ZinputActions/_dispatchHandlers

_dispatchHandlers(firstTickThisFrame: boolean?)

Internal: dispatch action handlers. Called by Zin.tick after axes/chords advance. Fires Begin/End/Change/Held handlers based on each action's polling state this tick. firstTickThisFrame is false on a same-engine-frame re-tick (e.g. the autoTick worker and an explicit Zin.tick both land in one frame): edge fires (Begin/End/Change) are per-frame events and must not fire twice, so they are gated to the first tick of the frame. Held is a per-tick redeliver and still fires every call. A nil argument is treated as the first tick (edges fire).

Parameters

• firstTickThisFrame boolean? (optional) — Whether this is the frame's first dispatch pass.

Zin.actions._dispatchHandlers()

modules/ZinputActions/_owns

_owns(handle: number): boolean

Internal: cross-API ownership probe. Used by Zin.disconnect to route handles to the right disconnect implementation, since Zin.input.on* and Zin.actions.bind share a handle namespace.

Parameters

• handle number — The numeric handle to probe.

if Zin.actions._owns(h) then Zin.actions.disconnect(h) end

modules/ZinputActions/_resetUnknownWarnings

_resetUnknownWarnings()

Test-only: forget which names have already been reported as unregistered, so a fresh suite sees the warning again.

Zin.actions._resetUnknownWarnings()

modules/ZinputActions/_setAllocator

_setAllocator(fn: () -> number)

Internal: wire a shared id allocator, so handles from this module and from Zin.input.on* never collide. Called once at module-load time from zinput/init.luau.

Parameters

• fn () -> number — The allocator function that returns the next handle id.

M._setAllocator(allocateZinHandle)

modules/ZinputActions/_setEnsureBindingsFn

_setEnsureBindingsFn(fn: () -> ())

Internal: wire the lazy-default-map hook. Called once at module- load time from zinput/init.luau.

Parameters

• fn () -> () — The hook invoked on a cold read (name not in the registry).

M._setEnsureBindingsFn(ensureDefaultBindings)

modules/ZinputActions/_setEnsureLiveFn

_setEnsureLiveFn(fn: () -> ())

Internal: wire the liveness hook. Called once at module-load time from zinput/init.luau.

Parameters

• fn () -> () — The hook invoked on every cold-checked read below.

M._setEnsureLiveFn(ensureInputLive)

modules/ZinputActions/_settled

_settled(): boolean

Internal: whether the most recent dispatch pass delivered nothing and saw nothing held. The tick's quiescence gate reads it.

if Zin.actions._settled() then ... end

modules/ZinputActions/active

active(name: string): boolean

True if an action is currently active in the input context stack. An action is "active" iff its declared context matches the top of the context stack (so push("ui") suppresses every non-"ui" action).

Parameters

• name string — The action name.

if Zin.actions.active("jump") then ... end

modules/ZinputActions/bind

bind(name: string, fn, opts: BindOpts?): ActionHandle?

Register a handler. Returns a numeric handle (also accepted by Zin.input.disconnect). Returns nil if name is not a defined action. The handler ends with the context that bound it as well: a component's with that component instance, a module body's with the module's next run.

Parameters

• name string — The action name.
• fn any (optional) — Handler fn(name, state, io, gpe) -> "sink" | any.
• opts BindOpts? (optional) — Optional { priority, fire, once }.

local h = Zin.actions.bind("jump", function() print("jump") end)

modules/ZinputActions/clear

clear()

Wipe every defined action. Primarily for tests.

Zin.actions.clear()

modules/ZinputActions/define

define(spec: ActionSpec)

Define one or more actions. Each entry replaces any existing action under the same name; other actions are preserved.

Parameters

• spec ActionSpec — Map of name -> binding | { binding... } | { context, binding(s) }.

Zin.actions.define({ jump = Zin.bindings.key("Space") })

modules/ZinputActions/disconnect

disconnect(handle: ActionHandle): boolean

Tear down a handler returned by bind. Idempotent.

Parameters

• handle ActionHandle — The handle from bind (or onPressed/onReleased/etc).

Zin.actions.disconnect(h)

modules/ZinputActions/get

get(name: string): ActionEntry?

Internal: the registry record behind a name, for profile capture and conflict indexing. Returns nil if the action is not defined.

Parameters

• name string — The action name.

local entry = Zin.actions.get("jump")

modules/ZinputActions/handlerCount

handlerCount(name: string): number

Number of registered handlers for an action (0 if none / unknown).

Parameters

• name string — The action name.

assert(Zin.actions.handlerCount("jump") == 1)

modules/ZinputActions/has

has(name: string): boolean

True if an action with this name is defined.

Parameters

• name string — The action name to test.

if Zin.actions.has("jump") then ... end

modules/ZinputActions/held

held(name: string): boolean

True if any binding on the action is currently delivering input. For boolean bindings: any held. For axis/vector bindings: non-zero magnitude. Suppressed by context gating.

Parameters

• name string — The action name.

if Zin.actions.held("attack") then print("swing") end

modules/ZinputActions/heldTime

heldTime(name: string): number?

Seconds the action has been held, taken as the MAX held-time across the action's boolean bindings. Returns nil if no binding is held or if the action is gated off by the current input context. Vector / axis bindings are skipped — use a held-time threshold against Zin.axes.value for held-direction analogs.

Parameters

• name string — The action name.

local t = Zin.actions.heldTime("interact")

modules/ZinputActions/names

names(): { string }

All defined action names, in arbitrary order.

for _, n in ipairs(Zin.actions.names()) do print(n) end

modules/ZinputActions/onChanged

onChanged(name: string, fn, opts: BindOpts?): ActionHandle?

Fire on axis/vector value delta (state = "Change"). For boolean actions Change fires on every press AND release transition — use onPressed / onReleased instead if you only want edges.

Parameters

• name string — The action name.
• fn any (optional) — Handler fn(name, state, io, gpe).
• opts BindOpts? (optional) — Optional { priority, once }.

Zin.actions.onChanged("move", function(_, _, io) print(io.value) end)

modules/ZinputActions/onHeld

onHeld(name: string, fn, opts: BindOpts?): ActionHandle?

Fire every tick while held (state = "Held"). Fires whenever held() is true at dispatch time, regardless of value change. Inherits the action's context constraint (no per-handler context filter).

Parameters

• name string — The action name.
• fn any (optional) — Handler fn(name, state, io, gpe).
• opts BindOpts? (optional) — Optional { priority, once }.

Zin.actions.onHeld("interact", function(_, _, io) print("charge", io.value) end)

modules/ZinputActions/onPressed

onPressed(name: string, fn, opts: BindOpts?): ActionHandle?

Fire on rising edge (state = "Begin"). Sugar for bind with fire = {"Begin"}.

Parameters

• name string — The action name.
• fn any (optional) — Handler fn(name, state, io, gpe).
• opts BindOpts? (optional) — Optional { priority, once }.

Zin.actions.onPressed("jump", function() ... end)

modules/ZinputActions/onReleased

onReleased(name: string, fn, opts: BindOpts?): ActionHandle?

Fire on falling edge (state = "End"). Sugar for bind with fire = {"End"}.

Parameters

• name string — The action name.
• fn any (optional) — Handler fn(name, state, io, gpe).
• opts BindOpts? (optional) — Optional { priority, once }.

Zin.actions.onReleased("attack", function() ... end)

modules/ZinputActions/pressed

pressed(name: string): boolean

True if any boolean binding on the action was just pressed this frame — the press EDGE, so it fires once per press no matter how long the input is held. Use it for one-shot input: fire, jump, pause, undo. For continuous input that should repeat every frame the input is down, read the level instead with Zin.state.keyDown(key). Axis/vector bindings do not contribute to press edges. Suppressed by context gating.

Parameters

• name string — The action name.

if Zin.actions.pressed("jump") then ... end

modules/ZinputActions/reason

reason(name: string): string

Why a named action is not delivering, from the closed set this registry can distinguish: unknownControl (no action is registered under the name — the value readers answer their neutral value, which is not a reading), contextInactive (registered, but its context is not on top of the stack), atRest (live, and the devices it binds are not being driven), or delivering.

Parameters

• name string — The action name.

if Zin.actions.reason("jump") == "unknownControl" then ... end

modules/ZinputActions/released

released(name: string): boolean

True if any boolean binding on the action was just released this frame. Suppressed by context gating.

Parameters

• name string — The action name.

if Zin.actions.released("attack") then ... end

modules/ZinputActions/remove

remove(name: string)

Remove an action by name. No-op if not defined.

Parameters

• name string — The action name to remove.

Zin.actions.remove("jump")

modules/ZinputActions/repeated

repeated(name: string, opts: { delay: number?, period: number? }?): boolean

Should a synthetic repeat fire this frame for the action? Returns true if any of the action's boolean key bindings reports State.keyRepeatFired. Mouse bindings are skipped (use a hold- time threshold for press-and-hold UX). Suppressed by context gating.

Parameters

• name string — The action name.
• opts { delay: number?, period: number? }? (optional) — Optional { delay, period } override of the global repeat defaults.

if Zin.actions.repeated("scrollLeft") then ... end

modules/ZinputActions/value

value(name: string): any

Read the action's current value.

• Axis binding → number in [-1, 1]
• Vector binding → { x, y } numbers in [-1, 1]
• Boolean binding → 1 when held, 0 when not (consumers usually use held() instead; this exists so a single API works for any kind) When multiple bindings exist, the first one whose kind matches the caller's expectation wins (axis > vector > boolean in declaration order). When suppressed by context, returns the identity value for the first binding's kind: 0 for axis/boolean, { x = 0, y = 0 } for vector.

Parameters

• name string — The action name.

local mv = Zin.actions.value("move")  -- { x, y }

modules/ZinputAxes/README

require("@builtin::modules.zinput.axes") -- ZinputAxes

DEPRECATED: An axis1 / axis2 control carries the same deadzone, smoothing, curve and invert, and reads a stick and a dragging thumb as well as a key. Author an .inputMap with .inputBinding children, activate it, and subscribe: local map = public.inputMap:activate() then map.move:onInput(fn). See man topics/input.

Usage: local ZinputAxes = require("@builtin::modules.zinput.axes")

modules/ZinputAxes/_resetGateWarnings

_resetGateWarnings()

Test-only: reset the once-per-axis gate-error warning state so a fresh suite can verify warning behavior again.

Zin.axes._resetGateWarnings()

modules/ZinputAxes/_resetUnknownWarnings

_resetUnknownWarnings()

Test-only: forget which names have already been reported as unregistered, so a fresh suite sees the warning again.

Zin.axes._resetUnknownWarnings()

modules/ZinputAxes/_setEnsureBindingsFn

_setEnsureBindingsFn(fn: () -> ())

Internal: wire the lazy-default-map hook. Called once at module- load time from zinput/init.luau.

Parameters

• fn () -> () — The hook invoked on a cold read (name not in the registry).

M._setEnsureBindingsFn(ensureDefaultBindings)

modules/ZinputAxes/_setEnsureLiveFn

_setEnsureLiveFn(fn: () -> ())

Internal: wire the liveness hook. Called once at module-load time from zinput/init.luau.

Parameters

• fn () -> () — The hook invoked on every cold-checked read below.

M._setEnsureLiveFn(ensureInputLive)

modules/ZinputAxes/_settled

_settled(): boolean

Internal: whether every axis sits at zero, current and target alike. The tick's quiescence gate reads it: the axes are read again after an evaluation or a change to the registry, and every call between those answers from the last read.

if Zin.axes._settled() then ... end

modules/ZinputAxes/advance

advance(dt: number)

Parameters

• dt number

modules/ZinputAxes/clear

clear()

Wipe every axis and its state. Primarily for tests.

Zin.axes.clear()

modules/ZinputAxes/define

define(spec: AxisSpec)

Define one or more axes. Each entry replaces any existing axis of the same name; other axes are preserved.

Parameters

• spec AxisSpec — Map of name -> { binding, deadzone?, smoothing?, curve?, invert?, context?, gate? }.

Zin.axes.define({ aim_x = { binding = ..., deadzone = 0.05 } })

modules/ZinputAxes/get

get(name: string): AxisDef?

Internal introspection: definition record (or nil).

Parameters

• name string — The axis name.

local def = Zin.axes.get("aim_x")

modules/ZinputAxes/has

has(name: string): boolean

True if an axis with this name is defined.

Parameters

• name string — The axis name.

if Zin.axes.has("aim_x") then ... end

modules/ZinputAxes/names

names(): { string }

All defined axis names, in arbitrary order.

for _, n in ipairs(Zin.axes.names()) do print(n) end

modules/ZinputAxes/raw

raw(name: string): any

Read the raw, unsmoothed, unshaped value of the underlying binding. For vector bindings returns {x,y}; for everything else returns a number in [-1, 1]. Useful for debugging or comparing pre/post processing.

Parameters

• name string — The axis name.

print(Zin.axes.raw("aim_x"))

modules/ZinputAxes/reason

reason(name: string): string

Why a named axis is not delivering, from the closed set this registry can distinguish: unknownControl (no axis is registered under the name — the value readers answer zero, which is not a reading), contextInactive (registered, but its context is not on top of the stack), gateRefused (its own gate answered no), atRest (live, and the binding it reads is not being driven), or delivering.

Parameters

• name string — The axis name.

if Zin.axes.reason("look") == "gateRefused" then ... end

modules/ZinputAxes/remove

remove(name: string)

Remove an axis. No-op if not defined.

Parameters

• name string — The axis name.

Zin.axes.remove("aim_x")

modules/ZinputAxes/value

value(name: string): any

Read the smoothed, shaped, context-gated value. Scalar axes return a number in [-1, 1]. Vector axes return {x, y} numbers in [-1, 1]. Returns 0 / {x=0,y=0} if the axis isn't defined.

Parameters

• name string — The axis name.

local mv = Zin.axes.value("move")  -- { x, y }

modules/ZinputMap/README

require("@builtin::modules.zinput.map") -- ZinputMap

DEPRECATED: An .inputMap asset with .inputBinding children is the map, and Zin.scheme is the live set: several can be live at once, each declaring the groups it suppresses. Zin.map.bake(name) writes the active map out as one, which is the migration. See man topics/input.

Usage: local ZinputMap = require("@builtin::modules.zinput.map")

modules/ZinputMap/_reactivate

_reactivate(record: any): any

Re-apply the active map from a changed record — the edit-in-place path an .inputMap asset takes when its source is written while it is live. Who asked for the map is carried across: a write to its source is the same map with new bindings, not a caller taking it up.

Parameters

• record any (optional) — The map record, freshly read from its source.

Zin.map._reactivate(record)

modules/ZinputMap/_reset

_reset()

Test-only: clear active-map state (the profile registry keeps whatever was applied).

Zin.map._reset()

modules/ZinputMap/activate

activate(record: any): any

Activate a map record: materialize it and apply the flattened result as the live binding set (through the profile registry, so persistence and conflict surfaces keep working). Per-class axis bindings beyond the primary register as <axis>@<class> sibling axes; consumers that combine device values read both (e.g. look + look@touch).

Parameters

• record any (optional) — The map (or profile) record, or an inputMap asset ref.

Zin.map.activate(require("@builtin::inputMaps.default"))

modules/ZinputMap/activeName

activeName(): string?

The active map's name, or nil.

if Zin.map.activeName() == "default" then ... end

modules/ZinputMap/addTouchButton

addTouchButton(actionName: string, buttonOpts: Bindings.TouchButtonOpts, emitKey: string?): any

Add a touchButton binding to an action's touch class on the active effective map, then re-flatten and re-activate so it takes effect immediately. Creates the action entry if actionName doesn't exist yet (the overlay's synthetic emit:<code> buttons).

Parameters

• actionName string — The action to attach the button to.
• buttonOpts Bindings.TouchButtonOpts — The options Zin.bindings.touchButton takes - the button's zone, label, icon glyph, layout and appearance.
• emitKey string? (optional) — Optional key code — when set and the action has no kbm class yet, seeds it with B.key(emitKey) so a synthetic action is self-contained from the moment it's created.

Zin.map.addTouchButton("emit:KeyF", { label = "Cast" }, "KeyF")

modules/ZinputMap/bake

bake(name: string): any

Write the active effective map as a new inputMap asset — synthesis made explicit and editable. The snapshot includes every live entry, overlay-registered emit:<code> actions included. Returns the created ref.

Parameters

• name string — The new asset's name.

Zin.map.bake("my_scheme")

modules/ZinputMap/bindingsFor

bindingsFor(eff: any, name: string, class: string): any

The effective bindings for one action or axis and device class.

Parameters

• eff any (optional) — An effective map (from materialize/effective).
• name string — The action or axis name.
• class string — "kbm" | "gamepad" | "touch".

local touch = Zin.map.bindingsFor(eff, "jump", "touch")

modules/ZinputMap/effective

effective(): any

The active map's effective form, or nil before any activation.

local eff = Zin.map.effective()

modules/ZinputMap/ensureActive

ensureActive(): any

Ensure a map is active: keeps the current one, else activates the builtin default map. The bootstrap the on-screen controls and controllers call.

Zin.map.ensureActive()

modules/ZinputMap/isFallback

isFallback(): boolean

Whether the active map is the fallback ensureActive armed on its own, rather than one a caller activated. A reader that presents the map to a player — the on-screen controls — asks this to tell a scheme a world offered from the keyboard floor under a name that was read.

if not Zin.map.isFallback() then print(Zin.map.effective()) end

modules/ZinputMap/materialize

materialize(record: any): any

Materialize a map record into its effective form: extends chain resolved (child wins per action/axis/class), then the touch class synthesized from the kbm shape wherever absent. Returns { name, description, actions = { [name] = { context, classes, synthesized = { touch = true? } } }, axes = { ... } }.

Parameters

• record any (optional) — The map (or profile) record.

local eff = Zin.map.materialize(require("@builtin::inputMaps.default"))

modules/ZinputMap/removeTouchButton

removeTouchButton(actionName: string, binding: any): boolean

Remove a touchButton binding previously added via addTouchButton, then re-flatten and re-activate. Drops the action entry entirely once every class is empty — cleanup for synthetic emit:<code> actions the overlay created.

Parameters

• actionName string — The action the binding was added to.
• binding any (optional) — The binding table returned by addTouchButton.

Zin.map.removeTouchButton("emit:KeyF", binding)

modules/ZinputObserve/README

require("@builtin::modules.zinput.observe") -- ZinputObserve

Usage: local ZinputObserve = require("@builtin::modules.zinput.observe")

modules/ZinputObserve/_publish

_publish()

Internal: publish this layer's half of the engine's input observation for the current frame. Called once per frame from Zin.tick while Zin.observe.wanted() holds.

Zin.observe._publish()

modules/ZinputObserve/arm

arm(on: boolean?)

Hold the engine's input observation open, so /runtime/input and input.observe() carry this layer's half of the document every frame. A read of either arms it for a window of frames on its own; this is for a test or a tool that wants it building continuously.

Parameters

• on boolean? (optional) — Arm (the default) or disarm.

Zin.observe.arm(true)

modules/ZinputObserve/armedFrames

armedFrames(): number

How many more frames the arming window has left. A read of Zin.observe.frame(), input.observe() or /runtime/input sets it back to the full window; every frame that passes takes one off it, and 0 means nothing is observing.

print(Zin.observe.armedFrames())

modules/ZinputObserve/control

control(name: string): any

Everything known about one named control in a single call: which maps contribute it, its bindings per device class, its subscriber count, the value it reported on the most recent tick, whether that reached a subscriber, and — when it is live and silent — why.

Parameters

• name string — The control name.

local c = Zin.observe.control("move")

modules/ZinputObserve/frame

frame(): any

The mapping layer's account of the most recent tick: every live map, every live control with what it did and why, and what the tick cost.

The window is ONE tick — the most recent one. Reading consumes nothing, so any number of observers in the same frame all get the same answers.

local f = Zin.observe.frame()

modules/ZinputObserve/means

means(reason: string): string?

What one reason name means, or nil for a name outside the set.

Parameters

• reason string — The reason name.

print(Zin.observe.means("gateRefused"))

modules/ZinputObserve/reasons

reasons(): { any }

The closed set of reasons a control resolves to, each with what it means and what to do about it. The resolver answers with exactly one of these names.

for _, r in ipairs(Zin.observe.reasons()) do print(r.name, r.means) end

modules/ZinputObserve/wanted

wanted(): boolean

Whether the engine wants this layer's half of the input observation built this frame — true while something has read input.observe() or /runtime/input recently enough.

if Zin.observe.wanted() then ... end

modules/ZinputObserve/whySilent

whySilent(name: string): any

Why a named control is not reaching the game right now, as one reason from the closed set Zin.observe.reasons() lists, with the particulars behind it.

Resolves against the devices as they are at the moment of the call, so it answers for a control the tick has never reached and for one that does not exist. The layer field says which of the three naming layers answered — the live maps' controls, the action registry, or the axis registry — since a name can be live in one and unknown in the others.

Parameters

• name string — The control name.

local why = Zin.observe.whySilent("look")

modules/animGraph/README

require("@builtin::modules.api.engine.animGraph") -- animGraph (also available as global 'animGraph')

Per-entity engine animation graph over the __animGraph FFI: clips, mixers, 2D blend spaces, crossfade, weights, and graph state. Each call routes onto the entity's AnimGraphComponent (auto-resolved from script context or passed explicitly).

Usage: local animGraph = require("@builtin::modules.api.engine.animGraph") Also available as global: animGraph

modules/animation/README

require("@builtin::modules.api.engine.animation") -- animation (also available as global 'animation')

Observe what the engine is animating: every body it is posing, the clips driving each one and where their playheads are, how many of a body's bones a clip's retarget reached, and — for a body that is not moving — the one reason why, from a closed set. Ragdoll a skinned character or creature (animation.ragdoll): its skeleton carried by physics bodies for a death, a knockout, a hit reaction or a limp limb, every bone body a body the Physics calls take.

Usage: local animation = require("@builtin::modules.api.engine.animation") Also available as global: animation

modules/animation/animating

animating(): { AnimationBody }

The bodies the engine measured a changing pose on — what is animating right now.

for _, b in animation.animating() do print(b.entity, b.clips[1] and b.clips[1].name) end

modules/animation/bodies

bodies(): { AnimationBody }

Every body the engine holds animation state for.

for _, b in animation.bodies() do print(b.entity, b.matched .. "/" .. b.total) end

modules/animation/body

body(entityId: string | EntityRef): AnimationBody?

The report for one body, or nil when the engine holds no animation state for it. Accepts the body itself or any ancestor of it, so a character root answers for the skinned body underneath it.

Parameters

• entityId string | EntityRef — The entity's stable id, or an EntityRef.

local b = animation.body(hero.id); print(b and b.reason)

modules/animation/clips

clips(entityId: string | EntityRef): { AnimationClip }

The clips contributing to a body's pose right now, with their playheads and their retarget coverage.

Parameters

• entityId string | EntityRef — The entity's stable id, or an EntityRef.

for _, c in animation.clips(hero.id) do print(c.name, c.time, c.matched) end

modules/animation/coverage

coverage(entityId: string | EntityRef): (number, number)

How many of a body's bones the clips driving it actually reach. Returns (matched, total). A clip that retargets onto nothing reads (0, 50) while its playhead advances; a partial retarget reads its own count, so 3 of 50 is as visible as none.

Parameters

• entityId string | EntityRef — The entity's stable id, or an EntityRef.

local m, t = animation.coverage(hero.id); print(m .. "/" .. t)

modules/animation/declare

declare(entityId: string, facts: { [string]: any })

Publish what an animator is running on a body, so the observation names its clips, playheads and retarget coverage beside the pose the engine measures. The shipped animators declare through AnimGraph:publish; a custom animator calls this itself, once per frame it runs.

Parameters

• entityId string — The body the animator drives.
• facts { [string]: any } — { driver, bound, playing, outputKind, failure, clips }, where each clip is { name, nodeKind, time, duration, playing, finished, looping, weight, matched, total, unmatched }.

animation.declare(body.id, { driver = "MyAnimator", playing = true, clips = {} })

modules/animation/forget

forget(entityId: string)

Drop the declaration and the pose evidence the engine holds for one body. An animator calls this when it releases a body, so the observation reports the body as undriven from the next frame.

Parameters

• entityId string — The body to drop.

animation.forget(body.id)

modules/animation/observe

observe(): AnimationObservation

Report what the engine is posing right now and why a body is not moving. One read covering every body the engine holds animation state for, each with the pose evidence the engine measured on its armature beside the clips the animator driving it declared. Answers in edit mode as well as play mode.

local a = animation.observe(); print(a.animatingCount, a.riggedBodyCount)
for _, b in animation.observe().bodies do print(b.entity, b.animating, b.reason) end

modules/animation/ragdoll

ragdoll(entityId: string | EntityRef, opts: (boolean | RagdollOptions)?): string

Ragdoll a skinned body: its skeleton is carried by physics bodies that fall, tumble and pose the mesh, for a death, a knockout, a hit reaction, a stunt fall or a limp limb. Works on any rigged skeleton: a humanoid (the built-in avatar and any imported humanoid rig) gets bodies sized for each body part and anatomical joints (hinged knees and elbows, cones at the shoulders, hips and neck); any other rig (a quadruped, a bird, a tail, a robot arm) gets a capsule along every bone and ball joints. The first call builds the ragdoll on the next frame, false included (its bodies follow the animation until it is switched on, so its bones can be read and jointed first); animation.ragdollState reads it back. false hands the body back to its animation, and true ragdolls it again.

The options table takes active (default true), limp (bone names: only those bones and the bones below them go limp while the rest keep animating), mass (the whole body's mass in kilograms; by default bodies weigh 1000 kg per cubic metre of collider, about 120 kg for the built-in avatar, so pass a person's 60 to 90 kg for a lifelike one) and bones (bone name -> { shape = "capsule" | "box" | "sphere" | "none", radius, length, size = {x, y, z}, mass, joint = "ball" | "hinge" | "fixed", swing, twist, hinge = {min, max}, strength, damping }, sizes in metres and angles in degrees). A description different from the last one rebuilds the ragdoll. On a humanoid a bone is also named by its humanoid role (hips, spine, chest, neck, head, leftshoulder, leftarm, leftforearm, lefthand, leftupleg, leftleg, leftfoot and the right ones), so one description fits every humanoid rig.

Each bone body is the body of that bone's armature entity (its id in ragdollState), so every Physics call takes it: Physics.addJoint to hold a hand to a ledge (breakable with breakForce), Physics.applyImpulseAtPoint for a hit, Physics.getVelocity, Physics.bodyState and Physics.contacts to measure a fall.

Parameters

• entityId string | EntityRef — The skinned entity, or any entity above it (a character root).
• opts (boolean | RagdollOptions)? (optional) — true / false, or a RagdollOptions table.

animation.ragdoll(enemy.id)                       -- collapse it
animation.ragdoll(enemy.id, false)                -- back to its animation
animation.ragdoll(hero.id, { limp = { "leftarm" } })  -- one limp arm
animation.ragdoll(dummy.id, { mass = 75, bones = { head = { mass = 5, swing = 30 }, leftleg = { hinge = { -140, 0 } } } })
local hand = animation.ragdollBone(hero.id, "righthand"); Physics.addJoint(hand, ledge, { kind = "ball", breakForce = 3000 })

modules/animation/ragdollBone

ragdollBone(entityId: string | EntityRef, bone: string): string?

The entity a ragdoll's bone body answers to, by bone name or, on a humanoid, by humanoid role (head, righthand, ...): the id to pass Physics.addJoint, Physics.applyImpulseAtPoint, Physics.getVelocity, Physics.bodyState, Physics.contacts and every other Physics call. nil until the ragdoll is built, or when that bone has no body of its own.

Parameters

• entityId string | EntityRef — The skinned entity, or any entity above it.
• bone string — The bone's name in the skeleton.

local head = animation.ragdollBone(dummy.id, "head"); print(Physics.getVelocity(head))

modules/animation/ragdollState

ragdollState(entityId: string | EntityRef): RagdollState?

The ragdoll built on a skinned body: whether the simulation drives it, its total mass, and every bone body with the entity it answers to (the bone's armature entity), its shape and size in metres, its mass read off the solver, whether it is simulated, and its joint. built reads false until the engine has built it (the frame after animation.ragdoll), and problems names anything the description asked for that the skeleton could not give. Under multiplayer replication reads which peer simulates the ragdoll (the owner of the synced entity at or above the body; every other peer shows it from that peer's bone poses) and what it costs on the wire.

Parameters

• entityId string | EntityRef — The skinned entity, or any entity above it.

local r = animation.ragdollState(hero.id); for _, b in r.bones do print(b.bone, b.mass, b.joint and b.joint.kind) end

modules/animation/whyStill

whyStill(entityId: string | EntityRef): (string?, string?)

Why the body on an entity is not animating. Returns nil when it IS animating, and otherwise one of deactivated, noRiggedSkeleton, noGraph, clipUnreadable, noOutputNode, retargetPending, retargetMatchedNoRoles, stopped, finished, paused, poseNotApplied, poseUnchanged — the nearest cause, so the answer names the thing to change. A second return carries the animator's own words when it could not build a graph.

An entity the engine holds no animation state for is answered from the entity itself, in the same order the engine resolves a body it does hold: one carrying no rigged Skeleton is noRiggedSkeleton, and a rigged one nothing drives is noGraph. An id no entity carries is neither — the reason is nil and the detail says so.

Parameters

• entityId string | EntityRef — The entity's stable id, or an EntityRef.

local why, detail = animation.whyStill(hero.id); if why then print(why, detail) end

modules/antiAliasing/README

require("@builtin::systems.antiAliasing.antiAliasing") -- antiAliasing

Edge antialiasing from the finished frame — the stair-stepping along a high-contrast silhouette is replaced by a gradient, without softening the regions on either side of it.

Usage: local antiAliasing = require("@builtin::systems.antiAliasing.antiAliasing")

modules/antiAliasing/active

active(): boolean

Whether the antialiasing pass is running this frame.

if antiAliasing.active() then ... end

modules/antiAliasing/disable

disable()

Turn edge antialiasing off and release the pass. The settings are kept, so a later enable() brings back the same tuning.

antiAliasing.disable()

modules/antiAliasing/enable

enable(opts: AntiAliasingOpts?): AntiAliasingState

Turn edge antialiasing on and set it. Any omitted field keeps its current value.

Parameters

• opts AntiAliasingOpts? (optional) — Antialiasing settings — see AntiAliasingOpts.

antiAliasing.enable({ edgeThreshold = 0.125 })

modules/antiAliasing/get

get(): AntiAliasingState

The antialiasing settings currently in force.

local t = antiAliasing.get().edgeThreshold

modules/antiAliasing/paramsBuffer

paramsBuffer(): any?

The buffer this system's passes read. The render feature binds what this hands it, so the pass has the values this module packed.

local p = antiAliasing.paramsBuffer()

modules/ao.shared/README

require("@builtin::systems.ambientOcclusion.aoShared") -- ao.shared

The parts every ambient-occlusion technique has in common: the WGSL prelude its kernel is written against, and the render targets, filter and passes that turn a per-pixel visibility term into shading.

A technique differs from its siblings in one thing only: how it estimates, for one pixel, what fraction of the hemisphere above the surface is visible. Everything either side of that estimate — reconstructing the surface from depth and normal, sizing the screen-space reach of a world-space radius, filtering the result across the noise the estimate carries, and multiplying it into the frame — is the same work whichever estimate produced it. So it lives here once. A technique file is its kernel and nothing else, which is what makes the three readable against each other.

Usage: local ao.shared = require("@builtin::systems.ambientOcclusion.aoShared")

modules/ao.shared/feature

feature(name: string, kernel: AssetRef<computeShader>) -> table

Build the render feature for one technique from its kernel shader.

Parameters

• name string
• kernel AssetRef<computeShader>

Returns table

modules/ao.shared/scale

scale() -> number

The fraction of the frame's resolution the occlusion is computed at.

Returns number

modules/ao.shared/setScale

setScale(scale: number)

Parameters

• scale number

modules/ao/README

require("@builtin::systems.ambientOcclusion.ao") -- ao

Screen-space ambient occlusion — the contact darkening in corners, creases and where objects meet. Without it every concave region is lit exactly like a flat one.

Usage: local ao = require("@builtin::systems.ambientOcclusion.ao")

modules/ao/active

active(): boolean

Whether the occlusion pass is running this frame.

if ao.active() then ... end

modules/ao/clear

clear()

Turn occlusion off and release the pass. The other settings are kept, so a later set({ intensity = ... }) brings back the same look.

ao.clear()

modules/ao/get

get(): AoState

The occlusion settings currently in force.

local r = ao.get().radius

modules/ao/paramsBuffer

paramsBuffer(): any?

The buffer the AO kernel reads. It belongs to whichever technique is running, and is remade when the technique swaps, so the pass binds what this hands it rather than looking it up.

local p = ao.paramsBuffer()

modules/ao/qualityLevels

qualityLevels(): { [string]: { slices: number, steps: number, scale: number } }

What each quality level costs: slices × steps taps per pixel (total slices * steps * 2, the same for every technique), computed on a grid scale of the frame's resolution.

local cost = ao.qualityLevels().ultra

modules/ao/set

set(opts: AoOpts?): AoState

Set the scene's ambient occlusion. Any omitted field keeps its current value, so a call can adjust one knob without restating the rest. An intensity of 0 turns occlusion off and releases the pass.

Parameters

• opts AoOpts? (optional) — Occlusion settings — see AoOpts.

ao.set({ technique = "hbao", intensity = 0.9, radius = 1.5 })

modules/ao/techniques

techniques(): { [string]: string }

The techniques that can be selected, each with what it does.

for name in pairs(ao.techniques()) do print(name) end

modules/asset/README

require("@builtin::modules.api.engine.asset") -- asset (also available as global 'asset')

Asset resolver, ref envelope builder, sidecar metadata. Public Luau surface over the __asset Internal FFI namespace.

Usage: local asset = require("@builtin::modules.api.engine.asset") Also available as global: asset

modules/asset/add_tag

add_tag(ref: RefArg, tag: string)

Add a tag to the asset's .metadata.tags. Idempotent. Creates the sidecar and the tags array if missing.

Parameters

• ref RefArg — Any name the asset has.
• tag string — Tag to add.

asset.add_tag("brick", "wip")

modules/asset/alias

alias(ref: RefArg, alias: string): boolean

Add a name the asset answers to. asset.resolve, leaf shorthand, and the typed-argument coercion that content refs travel through all reach the asset by the alias from here on, exactly as they do by its identity — so a material naming a shader by its alias resolves, and content written against an older name keeps working after a rename. The name survives writes to the asset's own files. Raises when the name already resolves to a DIFFERENT asset — an alias extends the identity namespace and never takes a name out of another asset's hands — and when it is shaped like a guid or a VFS path, forms that resolve before identity lookup, so an alias in that shape could never answer.

Parameters

• ref RefArg — The asset gaining the name.
• alias string — The additional name. Any identity form: a bare leaf (standard) or a scope-qualified path (@builtin::shaders.legacy).

asset.alias("@builtin::shaders.pbr", "standard")

modules/asset/aliases

aliases(ref: RefArg): { string }

The additional names this asset answers to, beyond its own identity — what asset.alias registered, plus the package-relative ~pkg.tail form when the asset lives inside a package.

Parameters

• ref RefArg — Any name the asset has.

for _, n in asset.aliases("pbr") do print(n) end

modules/asset/canCreate

canCreate(typeName: string): boolean

Whether asset.create can instance typeName: the type declares creation logic (a behavior.luau onCreate hook) or ships a template/ skeleton the hookless fallback clones. A type with neither — one whose instances only arrive by import — answers false. The query a creation UI derives its offering from, so what it offers is what asset.create accepts.

Parameters

• typeName string — Registered asset type (e.g. "material", "scene").

if asset.canCreate(kind) then asset.create(kind, name) end

modules/asset/categories

categories(): { string }

List every asset category the engine currently recognises. Use to discover valid type argument values for the rest of asset.*.

for _, c in asset.categories() do print(c) end

modules/asset/containing

containing(path: string): AssetRef?

Walk path and its ancestors and return an AssetRef handle for the INNERMOST registered category-folder containing it — the typed asset that directly owns the path (e.g. main.scene for "/source/scenes/main.scene/scene.json"; for a folder that is itself a registered asset, that asset). Returns nil for paths outside any registered asset.

Parameters

• path string — VFS path to inspect.

local a = asset.containing("/source/scenes/main.scene/scene.json")

modules/asset/cpuResident

cpuResident(ref: RefArg, typeName: string?): boolean

True when the asset is CPU-resident — a live script-component context holds it (a component's assetRef field, or an imperative asset.resolve/ref made while a component is the caller), which is what warms its bytes into memory. The CPU pool is a different pool from the device's: asset.observe().cpu lists it, asset.observe().textures / .meshes list what the device holds, and an asset can be in one and not the other.

Parameters

• ref RefArg — Any name the asset has — handle, identity, guid, name or path.
• typeName string? (optional) — Category to restrict the match to. Omit to search every category.

if asset.cpuResident(ref) then print("bytes are warm") end

modules/asset/create

create(typeName: string, name: string, opts: { [string]: any }?): (AssetRef, { durable: boolean, survivesRestart: boolean?, warning: string?, playShadow: string?, shadowed: { string }?, scratch: { string }? })

Instance a new asset of an existing type. Runs the type's behavior.luau onCreate(name, opts) hook to produce the asset's files, then writes them under /source/<folder>/<name>.<type>/ (/source/<name>.<type>/ when no folder is given). This is the single generic asset-creation API. Refuses to clobber an existing edit-mode asset unless opts.overwrite = true, which re-authors it in place and keeps the existing guid (only the checksum changes). Pairs with asset.exists for content generators that re-run over the same names.

A create made from a script component's callback or a scene entrypoint is output the world reproduces on every load, so it is filed in the ephemeral /runtime/assets/ store instead, where the saved manifest never carries a second copy of it. name and folder spell the same IDENTITY in either store, so a reference written against that identity resolves the asset wherever the call filed it, and one generator run from an execute and from a component names one asset.

Parameters

• typeName string — The asset category to instance — one of asset.categories().
• name string — The new asset's name.
• opts { [string]: any }? (optional) — Optional table forwarded to the type's onCreate hook, minus five framework keys consumed here and never seen by the hook: folder (a relative subfolder path under /source to author the asset in, with / between its folders as in game/materials, so generated content groups instead of accumulating at the source root; those folders joined by dots prefix the asset's identity, game.materials.<name>), into (author INSIDE a resolved container ref), dest (an absolute destination path), overwrite (re-author in place, keeping the guid), and durable (file every content file this create writes on canonical /source with play still running, in place of the play shadow, and raise with the reason when they cannot become source, the same key, meaning the same thing, that vfs.write takes). Every type accepts all five whatever its own contract declares; asset.describe(typeName).frameworkParams names them, and a rejection prints them under the type's own parameters.

local m = asset.create("material", "brick", { shader = "pbr" })
local s = asset.create("shader", "glow", { folder = "fx" }) -- s.path: /zero/source/fx/glow.shader, s.primary: /zero/source/fx/glow.shader/shader.wgsl
local wgsl = vfs.read(s.primary) -- the created asset's content file, read by the path the ref names
local mesh = asset.create("mesh", "tree", { positions = {...}, indices = {...} })
local mesh = asset.create("mesh", "rock", { positions = {...}, indices = {...}, folder = "terrain/props" })
local mesh = asset.create("mesh", name, { positions = p, indices = i, overwrite = true }) -- idempotent rebuild
local clip, d = asset.create("soundClip", "hit", { pcm = buf, sampleRate = 48000, channels = 1 })
if not d.durable then log.warn(d.warning) end
local c = asset.create("soundClip", "step", { pcm = buf, sampleRate = 48000, channels = 1, durable = true }) -- lands on source during play

modules/asset/declareReferenceArg

declareReferenceArg(call: string, position: number, assetType: string)

Declare that call's argument at 1-based position names an asset of type, so a string literal written there is recorded as a reference. The positional counterpart of asset.declareReferenceField, for a call that takes its asset as a plain argument — including a world's own spawn helper, which is where a name most often stops being visible to the reference graph. A lookup whose asset is its FIRST argument (asset.resolve and its siblings) is already read and needs no declaration. Only a literal — or a name the file holds in a top-level string constant — is recorded; anything computed is reported as a dynamic resolve. An asset type states the same declaration as content, in the references.args of its type.yaml, which every reference table reads from the moment the type registers.

Parameters

• call string — The callee as it is written at a call site.
• position number — Which argument holds the name, counting from 1.
• assetType string

asset.declareReferenceArg("spawnModel", 3, "mesh")

modules/asset/declareReferenceField

declareReferenceField(call: string, field: string, assetType: string)

Declare that call's options table names an asset of type in its field, so a string literal written there is recorded as a reference by whatever writes the file. This is what puts an API that takes an asset BY NAME into the reference graph: the named asset becomes a dependency, travels with the content that names it into a pack or a pull, and a name nothing answers to becomes an unresolved dependency worldValidation reports and the push gate refuses. A field holding a TABLE of names — a material's textures — records every name in it. Declare once, beside the API; a call taking its asset as the FIRST positional argument is already read and needs no declaration. Only a literal is recorded; a computed name resolves at runtime and is reported as a dynamic resolve. An asset type states the same declaration as content, in the references.fields of its type.yaml, which every reference table reads from the moment the type registers.

Parameters

• call string — The callee as it is written at a call site.
• field string — The options-table field holding the name, read at the table's own level.
• assetType string

asset.declareReferenceField("fx.beam", "material", "material")

modules/asset/declareReferenceKey

declareReferenceKey(assetType: string, key: string, refType: string, via: ("asset_ref" | "settings_of")?)

Declare that, in a data file belonging to an assetType asset, the top-level key names an asset of type ("*" for any type) — a .material's mat.yaml naming the shader it draws with and the textures it binds. The names a format holds are references as surely as ones written in code: recording them carries a material's shader along with the material into a pack or a pull, and turns a name nothing answers to into an unresolved dependency instead of a surface that renders as the magenta error material. A key holding a table of names records one per entry; a { __ref = <guid> } envelope names its guid. via is the provenance the file's .refs records: "asset_ref" (default) for an asset the file uses, "settings_of" for the declarer whose settings schema the file's values follow. A type states the keys of its own files as content, in the references.keys of its type.yaml, which every reference table reads from the moment the type registers.

Parameters

• assetType string — The category owning the file, e.g. "material".
• key string — The top-level key holding the name(s).
• refType string
• via ("asset_ref" | "settings_of")? (optional) — "asset_ref" or "settings_of".

asset.declareReferenceKey("material", "shader", "shader")
asset.declareReferenceKey("preset", "target", "*", "settings_of")

modules/asset/deprecation

deprecation(ref: RefArg): Deprecation.Deprecation?

Whether an asset is deprecated, why, and what replaces it. An asset is deprecated when its own .metadata carries "deprecated": { "reason": "<one line why>", "replacedBy": "<identity>" }, when a container holding it at any depth does (a package, a toolbox, a folder asset), or when its asset type does. A deprecated asset still resolves and loads by identity and guid; search surfaces do not offer it, and resolving it warns once per session.

Parameters

• ref RefArg — Asset handle, identity, guid or VFS path.

local d = asset.deprecation("@builtin::deprecated.deprecatedParticles.DeprecatedParticleEmitter")

modules/asset/deps

deps(ref: RefArg, type: string?): DepsResult

Return the asset's outbound dependency graph — every other asset recorded as a content dependency of it.

Parameters

• ref RefArg — Any name the asset has.
• type string? (optional) — Category hint (optional).

for _, d in asset.deps("main.scene").deps do print(d.asset_guid) end

modules/asset/describe

describe(typeName: string): DescribeResult

The creation contract for an asset type: the parameters its onCreate(name, opts) hook accepts, as data. kind is "schema" (typed contract), "legacy" (untyped opts — anything passes), "none" (template scaffold — takes no opts), or "error" (the type's schema failed to parse; error says why). contract is the human-readable rendering validation errors print. frameworkParams and frameworkContract carry the options asset.create consumes itself: folder, into, dest, overwrite, durable, which every type accepts and none declares.

Parameters

• typeName string — Registered asset type to describe (e.g. "texture").

local contract = asset.describe("texture").contract

modules/asset/diagnose

diagnose(ref: RefArg): any

Why one asset can or cannot be used, read from the engine rather than from what the caller asked for. Always carries usable; when false, reason is one of asset.unusableReasons() and detail is the engine's own message. primary names the file the type's declared primary list resolved to, the file a load of the asset reads. The payload's bytes are read by the engine's own decoder wherever it has one for that container, so usable is the verdict a load would reach and the call costs that decode.

Parameters

• ref RefArg — Any name the asset has — handle, identity, guid, name or path.

local d = asset.diagnose("myTex") if not d.usable then print(d.reason, d.detail) end

modules/asset/exists

exists(name: string, typeName: string): boolean

Parameters

• name string
• typeName string

modules/asset/get_field

get_field(ref: RefArg, key: string): any

Read one top-level field from the asset's .metadata.

Parameters

• ref RefArg — Any name the asset has.
• key string — Field name.

local author = asset.get_field("brick", "author")
local tags = asset.get_field("tree", "tags") -- → a Luau table

modules/asset/gpuResident

gpuResident(ref: RefArg): boolean

True when the device holds a texture or mesh under this asset's guid, read off the inventory the renderer publishes.

Parameters

• ref RefArg — Any name the asset has — handle, identity, guid, name or path.

print(asset.gpuResident("@builtin::models.Sample.DamagedHelmet"))

modules/asset/guid

guid(ref: RefArg, type: string?): string

Return the guid for an asset.

Parameters

• ref RefArg — Any name the asset has.
• type string? (optional) — Category hint (optional).

local g = asset.guid("@builtin::components.Camera")

modules/asset/has_field

has_field(ref: RefArg, key: string): boolean

True when the asset's .metadata carries the named field.

Parameters

• ref RefArg — Any name the asset has.
• key string — Field name.

if asset.has_field("brick", "author") then end

modules/asset/has_tag

has_tag(ref: RefArg, tag: string): boolean

True when the asset's .metadata.tags contains tag.

Parameters

• ref RefArg — Any name the asset has.
• tag string — Tag to check for.

if asset.has_tag("brick", "wip") then end

modules/asset/identity

identity(ref: RefArg, type: string?): string

Return the canonical identity for an asset.

Parameters

• ref RefArg — Any name the asset has.
• type string? (optional) — Category hint (optional).

local id = asset.identity("brick")

modules/asset/import

import(path: string, opts: { importerSettings: { [string]: { [string]: any } }? }?): string?

Import a raw source file NOW and return the produced asset path (a .bundle for a model, .texture for an image, .audio for a sound, …), or nil if no importer claims it. While play runs and holds the source where it stands (vfs.playHoldsInPlace), the import is owed: this returns nil, the source's job in tools.use("importers", "status") reads owed, and the import runs when play ends or pauses. This is the deterministic, on-demand counterpart to the engine's automatic import-on-write: it runs in the calling task and returns only when the import is complete. Pair it with a quiet write — vfs.write(path, bytes, { quiet = true }) lands the raw bytes without firing the automatic importer, then asset.import(path) imports them under your control, so you can act on the result instead of polling for the import to appear.

Parameters

• path string — The raw source VFS path to import (e.g. a just-written .glb).
• opts { importerSettings: { [string]: { [string]: any } }? }? (optional) — Optional { importerSettings = { <importer name> = { <setting> = value } } }: settings for this import only, laid over the claiming importer's own. A setting that importer does not declare is an error.

local bundle = asset.import("/zero/source/generated/chest.glb")
local bundle = asset.import("/zero/source/generated/chest.glb", { importerSettings = { model = { keepSource = false } } })

modules/asset/inspect

inspect(ref: RefArg, type: string?): InspectRecord

Everything known about one asset in a single record: identity, guid, source, type, scope and origin, its description and tags, the ref methods its type exposes, and the type's own inspect detail when it declares one. The read-everything counterpart to asset.resolve, which hands back a ref.

Parameters

• ref RefArg — An AssetRef, an identity string, or a path.
• type string? (optional) — Narrow the resolve to one asset type when assets of several categories answer to the same bare name.

local rec = asset.inspect("@builtin::materials.default")
local rec = asset.inspect(name, "mesh"); print(rec.guid, #rec.tags)

modules/asset/interface

interface(ref: RefArg, category: string?): AssetInterface?

What the asset declares it takes and gives, read from its source without running it: the interface its type's interface: block says its sources declare (a .procNode declares one). description is what it does; each of inputs carries its name, type, default, min, max, options, optional and description as the declaration states them (a vector default reads as { ["$vector"] = { x, y, z } }); each of outputs its name and from, what makes it. problems lists each part of the declaration that is not written as literals, which a push refuses. The same data travels with the source's reference table to ZeroMind.

Parameters

• ref RefArg — Any name the asset has.
• category string? (optional) — Category hint (optional).

local iface = asset.interface("@builtin::systems.procgen.nodes.points.disc", "procNode")

modules/asset/isPrivateSubasset

isPrivateSubasset(path: string): boolean

Whether the asset at path is a private subasset: nested inside another asset whose type does not broadcast its subassets — a .bundle's interior meshes, materials and textures, an effect's own materials. A private subasset is part of its parent: it is not listed, searched or installed on its own, and it is excused from the files that describe an asset. Whether nested assets are private is the enclosing asset's type's to say: broadcasts_subassets: true in its type.yaml (a .package) makes its members public, and an asset nested in no other asset is never private. The same rule asset.list applies, where subassets = true is what reaches private subassets.

Parameters

• path string — The asset's VFS folder path.

asset.isPrivateSubasset("/zero/source/models/tree.bundle/material/Bark.material") -- true

modules/asset/list

list(type_or_opts: (AssetCategory | ListOpts)?, scope: string?, opts: ListOpts?): ListResult

Query registered assets, returning each match as a resolved AssetRef handle. Every filter narrows the same enumeration and they compose: path selects a VFS subtree (the folder and everything under it), type keeps only those asset types within it, scope keeps only that scope, and fields keeps only assets whose .metadata matches. type and path each take one value or a list matching any of its entries, and all / any / none group whole filters — none excludes what it matches. order, limit, and offset shape the result: matches come back ordered by identity unless order names another field (name / path / type / guid). subassets decides how deep the enumeration reaches into composite assets. An enumeration returns the assets each container broadcasts, which its type declares: a .package and a .toolbox broadcast theirs, so their members are listed on their own, and a .bundle keeps its interior meshes, materials and rigs to itself, so they are reached through the bundle and a list of the folder holding it comes back without them. subassets = true enumerates those private interiors as well — what an asset is built out of, beside what the world offers. Each entry is the same envelope asset.resolve returns (__ref / type / name / guid / identity / path), so it can be passed anywhere an AssetRef is accepted, and the result carries :first() / :random() / :filter() / :sort() and friends. type takes the same values asset.categories() lists. The first positional argument is a path when it is absolute, a type otherwise. A type naming none of those values raises, naming it and any near spelling, so an empty result means a type the engine has. A type-group name stands for a family of those types rather than naming one (model for glb/gltf/fbx/obj, and image, text, config and script for theirs), so it lists whichever members the engine carries, and raises naming them when it carries none. An unknown key raises, as does a table setting both type and its older spelling category. A static (literal) type or path makes the enumeration part of the calling file's content dependencies when it is saved — the set travels with published content, so consumers get at-least the authoring world's assets.

Parameters

• type_or_opts (AssetCategory | ListOpts)? (optional) — Type or VFS path filter (a static literal so the enumeration can be captured for publish), or the full query table.
• scope string? (optional) — Scope filter (when first arg is a type).
• opts ListOpts? (optional) — The query table — see ListOpts.

local hero = asset.list({ path = "/zero/source/props", type = "mesh", fields = { tags = "hero" } }):first()
local parts = asset.list({ path = "/zero/source/models", type = "mesh", subassets = true }) -- a bundle's interior meshes too

modules/asset/listRevision

listRevision(): (number, number)

Two numbers that together move whenever what asset.list could answer changes: an asset made, removed, moved or renamed, a name it answers to added, a file created in or removed from an asset's folder (a new entity in the open scene writes one), or the index rebuilt. Rewriting a file that already exists leaves them still, and so does a write to a path no asset can sit at. The copies play makes resident in the runtime-asset layer move neither number. Hold the pair beside something derived from a listing and list again only when either differs, so a per-frame reader lists only on the frames where the answer can have changed.

local e, g = asset.listRevision() if e ~= held.e or g ~= held.g then held.list = asset.list("texture") end

modules/asset/list_field_values

list_field_values(key: string): { any }

Distinct values seen for the named field across every asset's .metadata.

Parameters

• key string — Field name.

local authors = asset.list_field_values("author")

modules/asset/list_fields

list_fields(): { string }

Distinct top-level field keys observed across every asset's .metadata. Useful for tooling discovering custom keys in use.

for _, k in asset.list_fields() do print(k) end

modules/asset/meta

meta(ref: RefArg, type: string?): AssetMeta

Read the asset's engine-owned identity record (guid / checksum). Distinct from .metadata (agent-editable); for that use asset.metadata.

Parameters

• ref RefArg — Any name the asset has.
• type string? (optional) — Category hint (optional).

local m = asset.meta("brick") -- { guid = ..., checksum = ... }

modules/asset/metadata

metadata(ref: RefArg, type: string?): AssetMeta

Read the asset's agent-editable .metadata sidecar as a Lua table. Missing sidecar returns {}. Distinct from asset.meta (engine-owned).

Parameters

• ref RefArg — Any name the asset has.
• type string? (optional) — Category hint (optional).

local md = asset.metadata("brick")

modules/asset/observe

observe(): any

What the engine is holding for content right now, in one reading: textures and meshes (one row per resource the device holds, each with the bytes it costs, its dimensions or buffer split, and where it came from), cpu (one row per asset a live script-component context holds), offDevice (one row per mesh nothing displays, whose GPU buffers were given back: held is "definition" when the engine keeps the mesh's whole CPU definition and "source" when it keeps only the stored file source it reads the mesh from again, and bytes is the CPU memory that costs), and totals: the aggregates those rows sum to, so the listing reconciles against renderer.textureMemory() and renderer.gpuMemory() (offDeviceBytes sums the offDevice rows).

Each pool is named because they are different pools: an asset can be on the device and not CPU-resident, or the reverse. devicePublished is false when no renderer has published an inventory and cpuPublished when the scripting VM has not published its pool — an engine that cannot answer reads differently from one answering with nothing resident.

local r = asset.observe() print(#r.textures, r.totals.textureBytes)

modules/asset/pathHolding

pathHolding(guid: string, checksum: string): string?

The VFS path holding the asset guid at exactly the version whose content checksum is checksum (the pair asset.meta reports): the guid's home when its bytes are that version, else a copy of that version held beside it, such as an installed dependency's. Returns nil when this world holds that asset at no such version.

Parameters

• guid string — The asset's guid.
• checksum string — The content checksum of the version wanted.

local m = asset.meta(asset.resolve("@builtin::shaders.pbr", "shader")); local path = asset.pathHolding(m.guid, m.checksum)

modules/asset/pending

pending(): { count: number, entries: { PendingReference } }

Every asset reference a component on this engine holds that no asset answers yet. A reference arrives ahead of its bytes when a peer delivers a component whose asset has not synced here, when the carried mount it names is still filling, or when a scene applies before the content it names. Each one applies by itself the moment its asset resolves: a component waiting on it runs its awake() then, and a write held for a component already running (held) lands then and reaches its onPropertyChanged. state is pending, or refused when the carried mount the reference names settled without its content; reason and detail say why. A refused reference applies if a later mount of that key brings the content. A reference inside a list or struct field waits the same way at its place in the field (path, such as skins[2] or look.skin), the field keeps every other value it holds, and the reference applies in place. Every peer of a world holds and applies the references it was delivered the same way.

local waiting = asset.pending()
if waiting.count > 0 then print(waiting.entries[1].reference, waiting.entries[1].state) end
repeat task.wait() until asset.pending().count == 0

modules/asset/preview

preview(ref: RefArg, opts: { [string]: any }?, type: string?): { [string]: any }

Render a preview of an asset. Resolves the ref and dispatches to its type's preview ref-method when present; otherwise returns the { available = false } sentinel ("no preview available for this type").

Parameters

• ref RefArg — Any name the asset has.
• opts { [string]: any }? (optional) — Optional { size = { width, height }, angle = { yaw, pitch } }.
• type string? (optional) — Category hint (optional).

local p = asset.preview("@builtin::materials.gold", { size = { width = 512, height = 512 } })

modules/asset/primaryFile

primaryFile(ref: RefArg): any

The file the asset type's declared primary list resolves to inside this asset, as the loader itself resolves it. A *.<ext> entry resolves the lowest-named file with that extension, and never the asset's preview.png, the picture rendered from it. resolved is false when no declaration matched and path is then absent; declared is the type's own primary list in match order.

Parameters

• ref RefArg — Any name the asset has — handle, identity, guid, name or path.

print(asset.primaryFile("myTex").path)

modules/asset/ref

ref(ref: RefArg, type: string?): AssetRef

Build a reference handle for an asset — the canonical ref envelope constructor. Identical shape to asset.resolve; preferred name for the author-side use case (embedding refs in YAML / JSON / Luau output).

Naming the asset here reads exactly as naming it in asset.resolve, down to raising on a miss: a literal is recorded as this source's dependency, a computed name is a dynamic resolve — free in a tool, refused on the gameplay path. asset.exists(name, type) is the probe a computed name can ask.

Parameters

• ref RefArg — The asset to reference — an identity, a guid, a VFS path, or a handle.
• type string? (optional) — Category hint (optional).

local r = asset.ref("animations.idle", "animation")

modules/asset/reloadPending

reloadPending(ref: RefArg, typeName: string?): boolean

True while a write to this asset still owes it a reload — the write is inside the settle window that collects one authoring step's writes, or its reload is queued and the engine has not run it yet. False means every content change written so far has reached its subscribers, so a consumer bound to the asset now cannot be interrupted by a reload the earlier writes already earned. The recording is synchronous with the write, so a call made right after one already reads true.

Parameters

• ref RefArg — Any name the asset has — handle, identity, guid, name or path.
• typeName string? (optional) — Category to restrict the match to. Omit to search every category.

repeat task.wait() until not asset.reloadPending(ref)

modules/asset/reloadSeq

reloadSeq(ref: RefArg, typeName: string?): number

How many content-change reloads this asset has been through — the count of onAssetReload dispatches the engine has RUN for it. A write to a file inside an asset does not reload it on the spot: the writes of one authoring step are collected for a settle window and the reload runs on a later frame. Read this, write, then poll for a larger number to learn the write's reload has actually reached subscribers. Monotonic per asset and session-scoped; 0 for an asset whose content has not changed since boot.

Parameters

• ref RefArg — Any name the asset has — handle, identity, guid, name or path.
• typeName string? (optional) — Category to restrict the match to. Omit to search every category.

local at = asset.reloadSeq(ref)
vfs.write(asset.source(ref) .. "/graph.json", encoded)
repeat task.wait() until asset.reloadSeq(ref) > at

modules/asset/remove_field

remove_field(ref: RefArg, key: string)

Remove one top-level field from the asset's .metadata. No-op when the field isn't present.

Parameters

• ref RefArg — Any name the asset has.
• key string — Field name.

asset.remove_field("brick", "author")

modules/asset/remove_tag

remove_tag(ref: RefArg, tag: string)

Remove a tag from the asset's .metadata.tags. No-op when the tag isn't present.

Parameters

• ref RefArg — Any name the asset has.
• tag string — Tag to remove.

asset.remove_tag("brick", "wip")

modules/asset/resolve

resolve<C>(ref: RefArg, type: (C & string)?): AssetRef<C>

Find an asset. The returned handle carries every name form the asset has (guid, identity, path, type) so downstream code can read any one of them without calling resolve again. Raises when ref resolves to no asset — or, with a type, to no asset of that type — and when ref reaches more than one asset, where it names the candidates for you to pick from instead of picking one of them. A <scope>::-qualified identity reaches exactly one: @root::name for the asset this world holds at its source root, the library identity (@builtin::…) for a library's. For the same lookup answering a miss with nil, use asset.tryResolve(ref, type).

A name written as a string LITERAL is recorded as this source's dependency on that asset, so the asset travels with the content and still resolves once someone installs it in another world. A COMPUTED name cannot be written down, so nothing pins what it reaches: that is a dynamic resolve — free in a tool, refused on the gameplay path (a component or scene entrypoint). asset.tryResolve, asset.ref and asset.source read the name they are given exactly this way too, so which of the four you reach for changes neither answer. To ask whether a computed name has files without reaching a handle, use asset.exists(name, type).

Parameters

• ref RefArg — The asset to find — an identity, a guid, a VFS path, or a handle.
• type (C & string)? (optional) — Category to restrict the match to (optional). Separates a bare name that assets of different categories share (asset.resolve("cube", "mesh")); where several assets of the SAME category answer to it, the scope-qualified identity is what separates them. A reference naming a file an importer has since promoted (wall.png after the texture importer turned it into wall.texture) resolves to the promoted asset, and says so in the log once per reference.

local a = asset.resolve("@builtin::components.Camera")

modules/asset/rootKinds

rootKinds(): { string }

The kind of every asset folder that is a root of its contents (its category declares root: true; a package is one too): a ~ written in a file inside such a folder names that folder. The same answer in every VM, the engine thread's and each worker's.

local roots = asset.rootKinds() -- { "effect", ... }

modules/asset/schema

schema(ref: RefArg): any?

The typed settings schema governing this asset — the Field descriptors its type declares for every asset of that type, or the ones the asset declares for itself. Each descriptor carries its kind, default, constraint and description, so an editor renders it and an agent reads what a setting takes without guessing.

Parameters

• ref RefArg — The asset (ref, identity, guid or path).

local schema = asset.schema(texRef); print(schema.filter.constraint.values)

modules/asset/setSettings

setSettings(ref: RefArg, patch: { [string]: any })

Write a partial settings patch. The patch is merged over the asset's current values, the type's cross-field constraints are applied — a field the patch does not name moves to the only value the rest allows (a texture given a high-precision compression stops generating mipmaps), and a field the patch names that cannot hold refuses the write, saying why — and the result is checked against its schema; a violation refuses the whole write, naming every problem, and leaves the asset on its last valid settings. A valid write re-runs the type's onChange, which is where the type re-cooks whatever the settings describe. Older field names are accepted and stored under the current ones, and a field whose default follows another moves with it when the write does not name it.

Parameters

• ref RefArg — The asset (ref, identity, guid or path).
• patch { [string]: any } — Any subset of the schema's fields.

asset.setSettings(texRef, { filter = "nearest" })

modules/asset/set_field

set_field(ref: RefArg, key: string, value: any)

Set one field in the asset's .metadata, creating the sidecar if missing. Sibling fields are preserved. When the new value AND the existing value are both maps (objects), the new value DEEP-MERGES into the existing one, so writing one sub-key never drops the others — set_field(ref, "provenance", { bakedBy = "agent" }) keeps every other provenance key. Arrays and scalars replace. Clear a whole field with asset.remove_field; replace the entire sidecar with asset.set_metadata.

Parameters

• ref RefArg — Any name the asset has.
• key string — Field name.
• value any (optional) — Field value (any JSON-serialisable Lua value).

asset.set_field("brick", "author", "me")
asset.set_field("tree", "provenance", { bakedBy = "agent" }) -- merges; sibling keys kept

modules/asset/set_metadata

set_metadata(ref: RefArg, data: AssetMeta)

Replace the asset's .metadata sidecar with the given table. Pass an empty table to clear all fields.

Parameters

• ref RefArg — Any name the asset has.
• data AssetMeta — Full JSON-shaped contents for the sidecar.

asset.set_metadata("brick", { author = "me", tags = { "wip" } })

modules/asset/settings

settings(ref: RefArg): any?

This asset's settings values, with every declared default filled in.

Parameters

• ref RefArg — The asset (ref, identity, guid or path).

if asset.settings(texRef).filter == "nearest" then ... end

modules/asset/source

source(ref: RefArg, type: string?): string

Return the VFS source path for an asset.

It reaches the asset, so the name carries the same reference contract asset.resolve's does: a literal is recorded as this source's dependency, a computed name is a dynamic resolve — free in a tool, refused on the gameplay path. asset.exists(name, type) is the probe a computed name can ask.

Parameters

• ref RefArg — Any name the asset has.
• type string? (optional) — Category hint (optional).

local p = asset.source("brick") -- "/source/brick.material"

modules/asset/storeHoldsIdentity

storeHoldsIdentity(identity: string, typeName: string, reproduced: boolean): boolean

Whether an asset of type typeName that name reaches has files in the store asset.create writes from this context — the authored /source tree, plus the ephemeral /runtime/assets/ store when the caller is a script component or a scene entrypoint, which is where a create there files it. name is any name the registry answers to for that asset: its canonical identity ("a.b.thing"), a registered alias, or the bare leaf ("thing") — the spelling asset.list publishes as an entry's name and the spelling asset.create was given alongside opts.folder. So the if not asset.exists(n, t) then asset.create(t, n, opts) end pairing is satisfied by its own create, spelled the way the create was, in either store and at any folder depth. A plain existence probe — it does NOT resolve a handle or pin a content dependency, so it is safe to call with a COMPUTED name (unlike asset.resolve, whose handle would become a static-pinned dependency).

The name is read the way asset.resolve reads one; the ANSWER comes from the store, so a registered asset whose files live outside the store this context writes — every @builtin:: asset among them — is false. asset.tryResolve(name, typeName) asks the registry the wider question and hands back the handle — and because it reaches the asset, the name it is given follows the reference rule every lookup follows: a literal is pinned, a computed one is a dynamic resolve. So a name this source computed is what asset.exists is for. This call names the asset FIRST and its category second, as every asset.* call taking both does except asset.create(category, name, opts). A call carrying a category where the asset goes and a non-category where the category goes is refused, naming which way round the call reads, rather than reporting the asset absent.

Parameters

• identity string
• typeName string — The asset type (e.g. "mesh", "texture", "material") — one of asset.categories().
• reproduced boolean

if not asset.exists(meshName, "mesh") then asset.create("mesh", meshName, geo) end
if not asset.exists(n, "mesh") then asset.create("mesh", n, { folder = "props", positions = p, indices = i }) end

modules/asset/tags

tags(ref: RefArg): { string }

Convenience read of the .metadata.tags array.

Parameters

• ref RefArg — Any name the asset has.

for _, t in asset.tags("brick") do print(t) end

modules/asset/tryResolve

tryResolve(ref: RefArg, type: string?, base: string?): AssetRef?

The same lookup asset.resolve performs, answering a miss with nil instead of raising. Every name form, the same type narrowing, and the same handle on success — so "use it if it is there" needs no pcall around a call whose failure would otherwise be indistinguishable from a real error.

This consults the asset REGISTRY, so it sees registered assets wherever their files live, @builtin:: ones included. asset.exists(name, type) answers the narrower question of whether an asset's files are present in the current mode's store.

A name that reaches more than one asset of type (or more than one asset, with no type) still raises: that is a question about the reference, and a nil there would report absence for content that is present twice. A name that only assets of other types answer to reaches no asset of type, and answers nil.

It reaches the asset, so the name carries the same reference contract asset.resolve's does: a literal is recorded as this source's dependency, a computed name is a dynamic resolve — free in a tool, refused on the gameplay path. asset.exists(name, type) is the probe a computed name can ask.

Parameters

• ref RefArg — The asset to look up — an identity, a guid, a VFS path, or a handle.
• type string? (optional) — Category to restrict the match to (optional). A reference naming a file an importer has since promoted resolves to the promoted asset, the same as asset.resolve.
• base string? (optional) — Optional VFS path of the asset the reference is written in, or of its file: a data asset resolving the references it holds, such as a material resolving its mat.yaml. A ~ / ~.tail ref expands against the root enclosing it, and a ref its .refs recorded reaches the asset recorded there. Without it, both are read at the calling Luau source, as asset.resolve reads them.

local mat = asset.tryResolve(name, "material")

modules/asset/typeRef

typeRef(target: RefArg): string?

Return the pinned asset_type reference (the type's guid) that the asset is an instance of. Resolve the full type with asset.resolve(asset.typeRef(target)). Returns nil for loose files / assets with no pinned type.

Parameters

• target RefArg — Asset handle / identity / guid / VFS path.

local t = asset.resolve(assert(asset.typeRef("brick")))

modules/asset/unusableReasons

unusableReasons(): { string }

Every reason asset.diagnose can report an asset unusable for, sorted.

for _, r in ipairs(asset.unusableReasons()) do print(r) end

modules/asset/validate

validate(ref: RefArg, type: string?): ValidateResult

Validate an asset folder against its type's type.yaml, plus the type's own semantic validation. Structural problems come from type.yaml — missing required files, unsatisfied one_of_group alternatives, and (when allow_unlisted: false) unexpected children. validated = false when no type.yaml is registered — nothing structural to check. On top of that, when the asset's type ships a behavior.luau exporting a top-level validate(assetRef) -> { { code, message, severity? } }, its reported problems (severity defaults to "error") are appended to problems; error-severity problems flip ok to false, warnings leave it untouched. A hook that raises or returns a non-table is itself reported as a validate.hook_failed error problem — a broken hook blocks. A type with no validate export behaves exactly as the structural check alone. world.push calls this per user asset, so a type's semantic validation is enforced at publish time with no further wiring.

Parameters

• ref RefArg — Any name the asset has.
• type string? (optional) — Category hint (optional).

local v = asset.validate("@builtin::components.Camera")

modules/asset/warmup

warmup(ref: RefArg, opts: WarmupOpts?): WarmupResult

Warm an asset's bytes into CPU memory and follow its declared content dependencies to each referenced asset, deduped by guid. Type-agnostic (reads the generic ref graph) and CPU-only — never touches the GPU. Side-effect-free name resolution (uses asset.guid/asset.deps, not asset.resolve).

Parameters

• ref RefArg — Any name the root asset has — handle, identity, guid, or path.
• opts WarmupOpts? (optional) — Optional { vias, max } — restrict ref-edge kinds / cap closure size.

local w = asset.warmup("@builtin::scenes.test_arena")

modules/asset_tag/README

require("@builtin::modules.asset_tag") -- asset_tag

The assetTag field-constraint validator: a constrained value must be an asset carrying constraint.tag in its .metadata.tags. This is what lets a slot declare the KIND of asset it takes — a camera behavior, a player visual — without naming the assets themselves, so a new asset becomes assignable the moment it is tagged. Registers itself with the generic field_constraints registry on load. nil (no asset) passes — the field is optional.

Usage: local asset_tag = require("@builtin::modules.asset_tag")

modules/atmosphere/README

require("@builtin::systems.atmosphere.atmosphere") -- atmosphere

Physically-based atmospheric scattering — aerial perspective on distant geometry, and a sky whose colour follows from the sun's elevation rather than from an authored gradient.

Usage: local atmosphere = require("@builtin::systems.atmosphere.atmosphere")

modules/atmosphere/active

active(): boolean

Whether the atmosphere passes are currently running.

if atmosphere.active() then print("scattering") end

modules/atmosphere/clear

clear()

Turn the atmosphere off and release its passes. The other settings are kept, so a later set({ aerial = ... }) brings back the same look.

atmosphere.clear()

modules/atmosphere/get

get(): AtmosphereState

The atmosphere settings currently in force.

local km = atmosphere.get().worldUnitsPerKm

modules/atmosphere/paramsBuffer

paramsBuffer(): any?

The buffer this system's passes read. The render feature binds what this hands it, so the pass has the values this module packed.

local p = atmosphere.paramsBuffer()

modules/atmosphere/set

set(opts: AtmosphereOpts?): AtmosphereState

Set the scene's atmosphere. Any omitted field keeps its current value, so a call can adjust one knob without restating the rest. With aerial at 0 and sky off nothing is wanted and the passes are released.

Parameters

• opts AtmosphereOpts? (optional) — Atmosphere settings — see AtmosphereOpts.

atmosphere.set({ aerial = 1, sky = true, worldUnitsPerKm = 1000 })

modules/audio/README

require("@builtin::modules.api.engine.audio") -- audio (also available as global 'audio')

Engine-native audio: encode audio (or raw PCM) into the ZAUD compressed payload, decode/inspect it, play PCM a script synthesizes while it sounds (audio.stream), set what the mix is heard at — a level per named channel, a master level and a mute — and observe what the mixer is making audible right now: live voices, why a source is silent, master levels, mixer voice accounting, listener state and subsystem cost.

Usage: local audio = require("@builtin::modules.api.engine.audio") Also available as global: audio

modules/audio/audiostream_close

audiostream_close(self: AudioStream): boolean

Close the stream: its voice falls silent and the entity's audio source comes off. Despawning the entity, removing its audio source, putting another audio source in its place or rewriting the source's stream field closes the stream the same way.

Parameters

• self AudioStream — The stream audio.stream returned.

s:close()

modules/audio/audiostream_flush

audiostream_flush(self: AudioStream): boolean

Drop every frame queued on the stream, on the mixer's next buffer.

Parameters

• self AudioStream — The stream audio.stream returned.

s:flush()

modules/audio/audiostream_pause

audiostream_pause(self: AudioStream)

Pause the stream's voice. The queue holds what it has, and wanted() stays at 0 while it is full.

Parameters

• self AudioStream — The stream audio.stream returned.

s:pause()

modules/audio/audiostream_play

audiostream_play(self: AudioStream)

Start or resume the stream's voice. A voice started after an earlier one ended reads a fresh, empty queue.

Parameters

• self AudioStream — The stream audio.stream returned.

s:play()

modules/audio/audiostream_push

audiostream_push(self: AudioStream, pcm: any, frames: number?): (number?, string?)

Queue interleaved samples on the stream. pcm is a buffer or a string holding samples in the stream's format, or an array of numbers; frames takes only that many frames from its start, so one buffer can be reused frame after frame. Every sample must be finite and the samples a whole number of frames.

Parameters

• self AudioStream — The stream audio.stream returned.
• pcm any (optional) — A buffer or string of samples, or an array of numbers.
• frames number? (optional) — How many frames from the start of pcm to push; all of them when omitted.

local n = s:wanted(); fill(buf, n); s:push(buf, n)

modules/audio/audiostream_set

audiostream_set(self: AudioStream, settings: { [string]: any })

Change the stream's voice: any of volume, pitch, spatial, maxDistance, rolloff, doppler, channel, sourceType, pitchValue and volumeValue, as an Audio component carries them. A voice already sounding takes the change on the next frame, except spatial, which a voice takes as it starts: placed and attenuated, or played unplaced.

Parameters

• self AudioStream — The stream audio.stream returned.
• settings { [string]: any } — The settings to change.

s:set({ pitch = 1.2, volume = 0.5 })

modules/audio/audiostream_status

audiostream_status(self: AudioStream): AudioStreamStatus?

Where the stream stands, nil once it is closed: sampleRate, channels, format; queuedFrames and queuedMs (what is queued and how far ahead of the mixer that is); capacityFrames; targetFrames (the queue it asks for) and producerGapMs (the longest recent gap between pushes behind it); wantedFrames; framesPushed, framesRefused (frames the full ring could not take) and framesPlayed; underruns (times it ran dry while it played) and starvedFrames (the silence played in their place); voice ("waiting", "playing", "paused" or "ended"); rate (the rate the mixer reads it at, pitch times Doppler).

Parameters

• self AudioStream — The stream audio.stream returned.

local st = s:status(); print(st.queuedMs, st.underruns)

modules/audio/audiostream_wanted

audiostream_wanted(self: AudioStream): number

How many frames to push now to bring the queue up to its target: the stream's latency, or one and a half times the longest recent gap between pushes when that is longer. Push this many every frame and the stream stays fed through frames as long as the ones before them. 0 once the stream is closed.

Parameters

• self AudioStream — The stream audio.stream returned.

local n = s:wanted()

modules/audio/decode

decode(zaud: buffer | string): (string?, number?, number?)

Decode a ZAUD payload into interleaved f32 PCM. A PCM payload comes back as the frames its header accounts for, held to the whole frames the bytes behind it fill, so the sample count is always a whole number of channels and a consumer walking it channels at a time ends on a frame.

Parameters

• zaud buffer | string — A ZAUD payload — a buffer or a binary string.

modules/audio/device

device(): AudioDeviceStatus

What the engine's audio output is doing: state is "open" while a stream is running on an output device and "silent" while none is, and device names the device an open stream runs on. The counters record what the engine has been through keeping one open — faults a live stream reported, changes of the host's default output, reopens the engine made, failedOpens the platform refused, and the glitches a listener heard as dropouts, with lastError carrying what the platform said. A device that goes away leaves the mixer running and the engine opening a stream again as soon as one is there. parked is true while nothing plays: the output stream is paused and the mixer renders nothing, so the device rests, and the first sound started resumes it, reading false once its first period plays; parks counts the times it parked and resumeLatencyMs is how long the last resume took to play its first period.

local d = audio.device(); print(d.state, d.device, d.reopens)

modules/audio/encode

encode(sourceBytes: buffer | string, opts: { [string]: any }?): (string?, string?)

Encode container audio bytes (ogg / mp3 / wav / flac) into a ZAUD payload. Every decoded sample must be finite; a source whose samples carry a NaN or an infinity comes back as (nil, err) naming how many fail and where the first one sits.

Parameters

• sourceBytes buffer | string — Encoded source audio bytes — a buffer or a binary string.
• opts { [string]: any }? (optional) — { codec: "opus"|"pcm"?, bitrateKbps: number?, vbr: boolean?, sampleRate: number?, forceMono: boolean?, loopStart: number?, loopEnd: number? }

local zaud = audio.encode(oggBytes, { bitrateKbps = 96 })

modules/audio/encodePcm

encodePcm(pcm: any, sampleRate: number, channels: number, opts: { [string]: any }?): (string?, string?)

Encode raw interleaved f32 PCM into a ZAUD payload. Every sample must be finite; a buffer carrying a NaN or an infinity comes back as (nil, err) naming how many fail and where the first one sits, so a filter that diverged over part of a bake is caught before it is written. The sample count is a whole number of channels: a buffer with a tail over comes back as (nil, err) naming the whole frames it holds and the samples past them.

Parameters

• pcm any (optional) — Interleaved f32 samples — a buffer or a binary string of little-endian f32, the shape microphone.samples and audio.decode hand back, or a flat number array. A byte payload's samples are its 4-byte lanes, and a length that stops partway through one comes back as (nil, err) naming the whole samples it holds and the bytes past them.
• sampleRate number — Source sample rate in Hz.
• channels number — 1 or 2, and a divisor of the sample count.
• opts { [string]: any }? (optional) — Same shape as audio.encode.

local s = microphone.status(); local zaud = audio.encodePcm(microphone.samples(), s.sampleRate, 1)

modules/audio/info

info(zaud: buffer | string): (AudioInfo?, string?)

Read a ZAUD payload's header. A PCM payload's samples are its bytes, and the header is read against them: a sample count differing from frames * channels comes back as (nil, err) naming both counts, and a sample carrying a NaN or an infinity comes back as (nil, err) naming how many fail and where the first one sits, so the header handed back describes a clip that is as long as it says and can sound. The header describes the clip's shape — rate, channels, frames, duration, codec, loop points. What the samples do where a whole-clip loop wraps is a reading of its own, audio.loopSeam, which is the call that answers whether a bed cycles without a click.

Parameters

• zaud buffer | string — A ZAUD payload — a buffer or a binary string.

local info = audio.info(zaud); print(info.durationMs)

modules/audio/levels

levels(): AudioLevels

The master mix's peak and RMS over the meter's most recent closed window, measured without recording anything.

local l = audio.levels(); print(l.peak, l.rms, l.windowMs)

modules/audio/listener

listener(): AudioListenerState

Where the scene is heard from, how many active listeners exist, and which entity's listener drives the ears.

local l = audio.listener(); print(l.present, l.count, l.entity)

modules/audio/loopSeam

loopSeam(zaud: buffer | string): (AudioLoopSeam?, string?)

Measure what a clip's samples do where a whole-clip loop wraps, so a bed can be judged before anyone hears it tick. The wrap's own step (|x[1] - x[frames]|) is reported against the step the signal ordinarily makes between neighbouring samples, as ratio = step / meanStep — a figure in the units the signal itself moves in, so a quiet ambience and a loud drone are read the same way. A bed whose partials wrap reads near 1; one carrying a strike at its head and silence at its tail reads in the tens. ratio and the step / meanStep / maxStep beside it belong to the worst channel, channel names it, and channels carries every channel's own reading. seamless is ratio <= threshold, the same threshold asset.create("soundClip", ...) warns past. The reading is taken on the DECODED samples, so it answers for what the codec left behind and for a clip that arrived already encoded and whose source buffer nobody holds. Costs a decode of the whole payload; audio.info reads a header without one.

Parameters

• zaud buffer | string — A ZAUD payload — a buffer or a binary string.

local seam = audio.loopSeam(clipRef:getBytes()); print(seam.ratio, seam.seamless)

modules/audio/mixer

mixer(): AudioMixerLevels

The levels the mixer is applying to the mix right now: the master level, whether the mix is muted, and the level of every channel one has been set on. A channel absent from channels plays at unity, so a source naming it is heard at the volume it asks for.

local m = audio.mixer(); print(m.master, m.muted, m.channels.music)

modules/audio/observe

observe(): AudioObservation

Report what the mixer is making audible right now, and why a source is not. One read covering every live voice with the mixer's own playback state and effective gain, the master mix's level, the mixer's voice accounting, the listener, the output device the mix is reaching, and what the subsystem costs. Answers in edit mode as well as play mode.

local a = audio.observe(); print(a.audibleCount, a.levels.rms)
for _, v in audio.observe().voices do print(v.entity, v.mixerState, v.silence) end

modules/audio/peakSince

peakSince(window: number): number?

The loudest peak the master mix reached across the meter's windows that closed after its windows count stood at window. audio.levels() carries the window that closed last, so a reader sees the windows its own frames happen to land on; this spans all of them, which is what measuring a sound shorter than the gap between two reads takes. Take the mark from audio.levels().windows before the sound starts, wait until windows has advanced past the sound's length, then read the span.

Parameters

• window number — A windows count taken from audio.levels() earlier.

local mark = audio.levels().windows
local peak = audio.peakSince(mark)

modules/audio/peaks

peaks(zaud: buffer | string, buckets: number): ({ number }?, string?)

The loudest sample in each of buckets equal spans of a clip, across its channels, as an absolute value held to 1: the shape a waveform is drawn from. A span is frames // buckets frames (at least one), and the frames past buckets * span fall in no bucket; a clip shorter than buckets frames fills one bucket per frame and leaves the rest at 0. The payload is decoded a block at a time, so the work never holds the clip's whole PCM, however long it runs.

Parameters

• zaud buffer | string — A ZAUD payload — a buffer or a binary string.
• buckets number — How many spans to divide the clip into: an integer from 1 to 4096.

local bars = audio.peaks(clipRef:getBytes(), 96)

modules/audio/profile

profile(): AudioProfile

What the audio subsystem has cost since the profiling window opened — the streaming pump, clip decode, clip encode, voice starts, and building the observation itself. Every total is a SUM across that window rather than a per-frame figure, and the window runs from the last audio.resetProfile() or from engine start. For what a frame costs now, reset, let frames pass, then divide by the frames the window reports.

audio.resetProfile(); task.wait(1); local p = audio.profile()
print("per frame:", (p.pump.totalMs + p.observe.totalMs) / p.frames)

modules/audio/resetProfile

resetProfile()

Open a new audio profiling window, discarding what the previous one measured. Call this before timing a stretch of frames: without it audio.profile() reports totals reaching back to engine start.

audio.resetProfile()

modules/audio/setChannelVolume

setChannelVolume(channel: string, volume: number)

Set the level of one mixer channel — the channel an Audio component names, such as "sfx", "music" or "ambient", or any name the scene invents. It scales every voice on that channel and nothing else, reaches voices that are already playing, and comes back per voice as gain.channel. A channel no level has been set on plays at unity.

Parameters

• channel string — The channel name, matching Audio.channel.
• volume number — Channel level, 0..1.

audio.setChannelVolume("music", 0.3)
for _, v in audio.voices() do print(v.channel, v.gain.channel) end

modules/audio/setMasterVolume

setMasterVolume(volume: number)

Set the master level of the mix, on the engine's 0..1 amplitude scale. It scales every voice whatever channel it plays on, reaches voices that are already playing, and comes back per voice as gain.master.

Parameters

• volume number — Master level, 0..1.

audio.setMasterVolume(0.5)

modules/audio/setMuted

setMuted(muted: boolean)

Silence or unsilence the whole mix. A muted mix sounds nothing whatever its master and channel levels read, every voice reports masterSilent, and unmuting hands the levels back untouched.

Parameters

• muted boolean — Whether the mix is silenced.

audio.setMuted(true)

modules/audio/stream

stream(entity: any, options: AudioStreamOptions?): (AudioStream?, string?)

Play PCM a script produces while it sounds — synthesis, an emulator's sound chip, procedural engine or wind noise, decoded voice — through the voice of entity. Opens a stream at the options' sample rate and channels and puts an audio source on the entity that plays it, so the voice is placed, attenuated and Doppler shifted when spatial, follows pitchValue / volumeValue, and is levelled by its channel and the master mix like every other source. Push samples each frame with stream:push, as many as stream:wanted() asks for, and the stream stays latencyMs ahead of the mixer, further on a host whose frames run long; a frame longer than the audio queued runs it dry, which stream:status().underruns counts. Frames pushed before the voice starts are the first it plays, and a stream not yet fed counts no underrun. Any sample rate from 4000 to 192000 Hz plays at its own pitch. The entity carries one voice: one already carrying an audio source is refused. The stream lives while the entity's audio source names it: removing the source, despawning the entity, putting another source in its place or rewriting the source's stream field closes it.

Parameters

• entity any (optional) — The entity whose voice plays the stream: a proxy or its id.
• options AudioStreamOptions? (optional) — An AudioStreamOptions, every field optional. The PCM: sampleRate (4000 to 192000 Hz, default the mixer's rate), channels (1, the default, or 2 interleaved left then right), format ("f32", the default, or "i16": how a pushed buffer or string is read), latencyMs (the least audio kept queued ahead of the mixer, default 100), bufferMs (the most the ring holds, default four times latencyMs and at least 500). The voice, as an Audio component carries it: volume, pitch, spatial, maxDistance, rolloff, doppler, channel, sourceType, pitchValue, volumeValue, and autoplay (default true).

local synth = audio.stream(e, { sampleRate = 22050, channels = 2, latencyMs = 80, spatial = true })
local n = s:wanted(); for i = 0, n - 1 do buffer.writef32(buf, i * 4, math.sin(phase)); phase += step end; s:push(buf, n)

modules/audio/voice

voice(entityId: string): AudioVoice?

The voice on one entity, or nil when that entity carries no audio source. An entity despawned since the frame the observation describes answers with its report from that frame, so an onDestroyed handler reads how the entity's voice stood as it went.

Parameters

• entityId string — The entity's stable id.

local v = audio.voice(e.id); print(v and v.mixerState)

modules/audio/voiceAccounting

voiceAccounting(): AudioVoiceAccounting

How many voices the mixer can hold, how many are in use, how many are free — read off the mixer's own tracks, so the free count is the one a play call is granted or refused against. The two pools are reported apart: capacity / inUse / free are the main track, which carries the NON-spatial voices, while a spatial voice plays through its own sub-track and is counted by spatialInUse instead. sourcesHolding counts both pools from the sources that own them, so it equals inUse + spatialInUse while every voice answers to a source.

local v = audio.voiceAccounting(); print(v.inUse .. "/" .. v.capacity)
local v = audio.voiceAccounting(); print(v.sourcesHolding - (v.inUse + v.spatialInUse))

modules/audio/voices

voices(): { AudioVoice }

Every live audio source with the mixer's opinion of it.

for _, v in audio.voices() do print(v.clip, v.gain.effective) end

modules/audio/whySilent

whySilent(entityId: string): (string?, string?)

Why the source on an entity is making no sound. Returns nil when it IS sounding, and one of noBackend, noDevice, notResident, neverStarted, refused, paused, ended, gainZero, channelSilent, masterSilent, outOfRange when it is not — the nearest cause, so the answer names the thing to change. A second return carries the mixer's own words when it refused the source, and "no audio source on this entity" when nothing there plays at all.

Parameters

• entityId string — The entity's stable id.

local why = audio.whySilent(e.id); if why then print(why) end

modules/av/README

require("@builtin::modules.api.engine.av") -- av (also available as global 'av')

Audio/video encode + mux control — live streaming, recording, encoder/muxer primitives. Public Luau surface over the __av Internal FFI namespace.

Usage: local av = require("@builtin::modules.api.engine.av") Also available as global: av

modules/av/is_live

is_live(): boolean

True if a live-stream session is currently active.

if av.is_live() then av.stop_live() end

modules/av/is_recording

is_recording(): boolean

True if a recording session is currently active.

print("recording:", av.is_recording())

modules/av/live

live(opts: LiveOpts?): (string?, string?)

Start the live-stream encoder. The stream is served at /engine/live.stream and reverse-proxied at /stream/<instance>/live.stream as a binary length-prefixed protocol consumed by the multiviewer UI's WebCodecs decoder. A browser engine encodes it with the browser's WebCodecs encoder, and the proxy reads it over the ZeroMind bridge and serves it at the same /stream/<instance>/live.stream. When texture_handle is set, the encoder reads from that GPU texture's guid (a Camera pointed at it via setTargetTexture) instead of the scene's viewport: that's how spectator cameras work. A stream runs beside an av.record take. Returns the stream URL once the encoder is open and streaming, or nil and the reason it is not: no encoder on this engine that streams H.264, a stream already running, an odd dimension, a session the encoder refuses (a size it will not encode, a spectator texture with no size to stream at). The engine opens the encoder, so the call waits for it: run it where it can yield, wrapping it in task.spawn from a callback that cannot. The reason also stands on av.status().liveError, which is where a stream that ends on a failure later says why.

Parameters

• opts LiveOpts? (optional) — Encoder options.

local url, why = av.live({ width = 1280, height = 720, fps = 60 })

modules/av/record

record(path: string, opts: RecordOpts?): (string?, string?, Durability?)

Start recording the engine output to a VFS path. Default dir is /zero/runtime/recordings/ when path is not absolute: that directory is writable in every mode and stays out of the world's sync, so a take named relative to it is kept for the session and read back with vfs.read. A destination under /zero/source/ is world content, which the world's sync uploads when the take is filed. The take runs until av.stop_recording() unless opts bounds it with max_duration_sec (seconds of the take's own clock) or frames (captured frames); max_duration_sec wins when both are given, and the bound in force reads back as av.status().recordingBound. With no chroma/range opts the format defaults to full-range 4:4:4 HEVC where the GPU supports it, else 4:2:0. In the browser the browser's WebCodecs encoder converts the picture itself, so the take is 4:2:0 in the code range that encoder chooses, which an H.264 or AV1 file states, and grain above 0, chroma = "444" and any stated range are refused by name, and the master mix is encoded by the browser's WebCodecs AudioEncoder. On the "software" backend the take is H.264 encoded on the CPU, which costs the run it records: read av.status().recordingAchievedFps against recordingRequestedFps to see the rate it reached. What the take did with the master mix reads back as av.status().recordingAudio. cadence picks the clock the take stamps its frames from. "realtime" (the default) stamps each frame with the wall-clock slot it was captured in, so a recorded session is watched back at the speed it happened and an engine ticking under fps leaves slots empty. "frame" stamps every rendered frame one fixed slot after the last, so a timeline whose own clock advances a step per rendered frame — a cutscene, a scripted demo, anything on a fixed timestep — is delivered at the length that timeline runs to, however slowly the engine drew it: a take of frames = n at fps is n / fps seconds of film, and a max_duration_sec bound counts that film's seconds. A "frame" take records silent, because the master mix plays in wall-clock seconds and cannot share a file with a fixed-step picture; recordingAudio says so, and an explicit audio = true beside it is refused. Record the sound as a second "realtime" take. camera names the camera the take draws its film from — an entity proxy, an entity id, or an entity name. That camera holds the viewport for as long as the take runs, above the priority contest and above camera.setEditorOverride, so the film is its view and the frames carry everything the presented frame carries. Only frames that camera drew go into the film, and a camera that never draws the viewport ends the take with the reason on av.status().recordingError — so a take is the view it named or it is no take. The camera belongs to the take: nothing is written to it, and the viewport is back under its own contest the moment the take ends. It reads back as av.status().recordingCamera while the take runs. Omitted, the take records whichever camera holds the viewport, which in an engine on the editor profile is the editor's own fly camera rather than the scene's. renderLayers is the render-layer include spec the viewport is drawn under for as long as the take runs — the same token string a capture takes: all seeds every layer, name adds one and !name drops one, so "all !EditorUI !debug" films the scene without the editor's chrome or the authoring overlays (gizmos, light and probe icons, frustums, collider wireframes) over it, and "all !ui !EditorUI !debug" drops the authored HUD as well. The viewport admits geometry and screens by that one spec, so it states the whole picture. It belongs to the take: nothing is written to the camera it is stated against, and the moment the take ends — its bound reached, stopped, or refused — the viewport is back under the camera's own spec. While a take states layers, the window shows what the film holds, and av.status().recordingLayers reads the spec back. Omitted, the take records the engine output as presented. width / height are the film's size: the whole of the presented frame (in an editor layout, the rect the scene is drawn into) is resampled to it, and a side left out takes the presented frame's. Returns the destination path of a session that is open and recording, or nil and the reason it is not: an adapter that cannot encode, a take already running, an option the encoder rejects, a resolution the device refuses, a destination the VFS cannot write (a read-only path, a directory, a host filesystem path). The engine opens the session, so the call waits for it: run it where it can yield, wrapping it in task.spawn from a callback that cannot. How a take finished reads back as av.status().recordingEnd; a refused request puts its reason there and on recordingError and leaves no take report behind, while a request refused because a take is already running leaves that take's report as it is.

Parameters

• path string — VFS destination path, returned in its /zero form; a relative name records under /zero/runtime/recordings/.
• opts RecordOpts? (optional) — Encoder options (optional).

local clip = av.record("intro.mp4", { fps = 60 })
local film = av.record("cut.mp4", { fps = 24, frames = 24 * 181, cadence = "frame" })
local clean = av.record("take.mp4", { fps = 24, renderLayers = "all !EditorUI !debug" })
local shot = av.record("film.mp4", { fps = 24, frames = 240, camera = "FilmCamera" })
local take, why, d = av.record("take.mp4", { fps = 24 })
if d and d.playShadow then log.warn(d.warning .. " " .. d.playShadow) end

modules/av/save

save(path: string, opts: SaveOpts?): (boolean, string, SaveReport?)

Save a finished take to the device of the person at the screen, so the recording outlives the session: /zero/runtime/recordings/ is gone when the engine stops (and, in the browser, when the tab closes). path names the take the way av.record did: a relative name is the take of that name under /zero/runtime/recordings/, and any VFS path works too. The person decides where it lands. In the browser the take downloads at once when the save rides a click or key press of the person at the screen, so call it from a button's click handler; a save with no such gesture behind it (an agent, a timer, the end of a take) makes the page show the person an offer they save with a click of their own, because a browser starts a download only for a person who just acted. A native engine opens the host's save dialog in their downloads folder, with the take's name filled in, and writes it where they choose; an engine with no window has no person at its screen and refuses. The call waits for the first answer, so run it where it can yield (task.spawn from a callback). Returns true, a sentence saying where the take went, and the report { state, detail, name, size, path } with state "saved" (on the device) or "offered" (in front of the person, as the page's offer or the save dialog); or false and why it was refused: a take still recording (it is filed when it ends), no file at the path, a host path, a name with a folder in it, no window, or a take too large for the browser to hold, which the page shows the person as well. The saved file is the take byte for byte. userfile.save saves any other file the engine holds.

Parameters

• path string — The take: its name under /zero/runtime/recordings/, or a VFS path.
• opts SaveOpts? (optional) — { name }, the file name the device gets (the take's own when omitted).

local ok, where = av.save("take.mp4")
local ok, where, report = av.save("take.mp4", { name = "boss-fight.mp4" })

modules/av/status

status(): AvStatus

Report the encoder subsystem's state. Always available regardless of GPU support. backend is the encode backend in use: "vulkan" or "vaapi" on an adapter with a media engine, "software" where a native engine encodes on the CPU, and "webcodecs" in the browser, where the browser's own WebCodecs encoder takes the frames. hardware is true for the first two, and in the browser when the browser reports a hardware encoder for the default codec, so a caller that pays for the take in engine time knows which it is getting. codecs lists what the backend encodes with the recording default first (h264 in the browser, which every engine plays back with video.create). reason is "supported", "not_probed" before the engine has asked its encoder, "unsupported_adapter" for a native adapter with no encoder, or "unsupported_browser" for a browser whose WebCodecs encodes none of the codecs the engine offers. live is true while the av.live stream is running, and liveError is why the most recent stream was refused or ended on a failure: nil while one runs and after av.stop_live() ended one that had opened, and the reason that names av.stop_live() after it ended one still opening. A take of its own reads back on the recording fields: recording is the destination of the take in flight, recordingBound what will end it, recordingEnd how the most recent one ended, and recordingError why one produced no file. recordingAudio is the codec the take is writing the master mix with ("opus"), or the reason the file carries no audio track — read it to tell a film with a soundtrack from a silent one. recordingLayers is the render-layer include spec the armed take is drawing the viewport under, in the words its caller wrote, and nil for a take that stated none — the reading that answers what is in the picture rather than how much of it there is. recordingCamera is the entity id of the camera the take's most recent captured frame was drawn from, and stands as the source of the most recent take once that take has ended — it is read off the frame the engine drew, so it answers which view a film holds whether or not the take named a camera. recordingCadence is the clock the take stamps its frames from, "realtime" or "frame", and so what the tally below is a reading against. What the take produced reads off recordingFrames, recordingBytes (every byte the take has produced so far, climbing while it runs and ending equal to the size of the file), recordingSeconds (the timeline those frames cover), recordingAchievedFps (the rate they arrived at) and recordingRequestedFps (the rate asked for) — live while a take runs, and its final tally once it ends. On "realtime" the requested rate is a ceiling and an engine ticking under it reaches less; on "frame" every rendered frame is a slot of the recorded timeline, so recordingSeconds is that timeline's length and recordingAchievedFps is the rate it plays back at. recordingDurability is where the film in flight lands on the terms standing now — the report av.record returns as its third value, asked again for the take still running, so a caller polling status learns the play shadow is taking the film in time to keep it, a take that entered play after it opened included. It is present while a take names a destination.

local s = av.status(); print(s.backend, s.hardware, s.recordingAudio)

modules/av/stop_live

stop_live(): boolean

Stop any active live-stream session.

av.stop_live()

modules/av/stop_recording

stop_recording(handle: string?): (boolean, string?)

Stop the active recording (or the one for the given promise handle). Returns true when a recording was armed at call time. A false return carries a second value naming how the most recent recording already ended (the bound it reached, or the failure that cut it short), and nil when no recording has run at all. The engine finalizes the take once the call returns. A take stopped before its first frame is captured runs on until that frame lands and ends holding it, and one whose first frame has not landed 120 frames after the stop ends with none. Wait for av.is_recording() to go false, then read what it produced off av.status().

Parameters

• handle string? (optional) — Promise handle of a specific recording (optional).

local stopped, ended = av.stop_recording()

modules/base64/README

require("@builtin::modules.api.engine.base64") -- base64 (also available as global 'base64')

Base64 encode / decode between binary and text Luau strings (standard RFC 4648 alphabet, padded). Public Luau surface over the __base64 Internal FFI namespace.

Usage: local base64 = require("@builtin::modules.api.engine.base64") Also available as global: base64

modules/base64/decode

decode(text: string): (string?, string?)

Decode standard-alphabet base64 text back to the original binary string.

Parameters

• text string — Base64 text to decode.

local bytes = base64.decode(encoded)

modules/base64/encode

encode(bytes: buffer | string): string

Encode a binary string to standard-alphabet (padded) base64 text.

Parameters

• bytes buffer | string — Binary bytes to encode.

local text = base64.encode(jpegBytes)

modules/bitmask_bits/README

require("@builtin::modules.bitmask_bits") -- bitmask_bits

The bitmask field-constraint validator: a constrained value must be a whole number that fits the declared width, so what the field reads back is a mask the system consuming it can actually address. A rejection names the width and why the value is not a mask of it. Registers itself with the generic field_constraints registry on load. nil passes, so a mask field may be left unset.

Usage: local bitmask_bits = require("@builtin::modules.bitmask_bits")

modules/blend/README

require("@builtin::modules.api.engine.blend") -- blend (also available as global 'blend')

Record-stride blend primitives over Buffer slices — layout registry + weighted/lerp combiners. Public Luau surface over the __blend Internal FFI namespace.

Usage: local blend = require("@builtin::modules.api.engine.blend") Also available as global: blend

modules/blend/destroyLayout

destroyLayout(handle: number): boolean

Drop the layout from the registry.

Parameters

• handle number — Layout handle.

modules/blend/layout

layout(slots: { BlendSlot }, totalStride: number?): number?

Register a record-stride layout. Each slot is { offset, stride, op } where op is "lerp" / "slerp" / "sum" / "step". Slerp slots must have stride 4. totalStride defaults to max(offset + stride) across slots; pass an explicit value when records contain padding past the last slot.

Parameters

• slots { BlendSlot } — Array of slot tables.
• totalStride number? (optional) — Optional explicit record stride.

local l = blend.layout({ { offset = 0, stride = 3, op = "lerp" } })

modules/blend/lerpInto

lerpInto(outBuffer: Substrate.TypedBuffer, layout: number, aBuffer: Substrate.TypedBuffer, bBuffer: Substrate.TypedBuffer, t: number): boolean

Two-input crossfade shortcut. Equivalent to blend.weightedInto(out, layout, { {a, 1-t}, {b, t} }). Faster for the common A/B fade case because it skips the inputs-table walk.

Parameters

• outBuffer Substrate.TypedBuffer — The buffer written into.
• layout number — Layout handle.
• aBuffer Substrate.TypedBuffer — The A side of the fade.
• bBuffer Substrate.TypedBuffer — The B side of the fade.
• t number — Crossfade weight on B (0..1).

modules/blend/weightedInto

weightedInto(outBuffer: Substrate.TypedBuffer, layout: number, inputs: { BlendInput }): boolean

Combine N weighted input buffers into the output buffer using the layout's slot ops. The output buffer's length must be a whole multiple of layout.totalStride; every input buffer must be at least as long as the output. Returns false on any handle / size mismatch.

Parameters

• outBuffer Substrate.TypedBuffer — The buffer written into.
• layout number — Layout handle.
• inputs { BlendInput } — Array of { buffer, weight }.

modules/buoyancy/README

require("@builtin::systems.oceans.modules.buoyancy") -- buoyancy

Floats a rigid body on the water Physics.water answers for (a sea, a lake, a river, a pool) — displacement, damping and the righting moment that keeps a hull upright.

Usage: local buoyancy = require("@builtin::systems.oceans.modules.buoyancy")

modules/buoyancy/apply

apply(self, dt: number): boolean

Step the body once. The Buoyancy component calls this every frame; call it yourself only when driving a body without that component.

Parameters

• self any (optional)
• dt number — Seconds since the last step.

float:apply(1 / 60)

modules/buoyancy/attach

attach(target: any, options: any?): (any?, string?)

Float a rigid body on the water. The entity needs a dynamic Physics body; the hull is measured from what it draws unless sizeX/Y/Z say otherwise.

Parameters

• target any (optional) — The entity id or proxy to float.
• options any? (optional) — { density, damping, angularDamping, columns, sizeX, sizeY, sizeZ, mass, gravityScale, ocean }. density is relative to water, and the lower it is the higher the hull rides.

local float = buoyancy.attach(barrel, { density = 0.4 })

modules/buoyancy/clear

clear()

Stop floating every body. Each one is released, so a body driven by a Buoyancy component stops being pushed as well.

buoyancy.clear()

modules/buoyancy/columns

columns(size: any, columns: number): { { x: number, z: number } }

The local-space footprint of a hull's columns: an evenly spaced grid over its X/Z extent, each column standing for an equal share of the hull.

Parameters

• size any (optional) — { x, y, z } full extents of the hull in its own space.
• columns number — Grid resolution per horizontal axis. 1 gives a single central column, which floats but cannot right itself; 2 is the smallest grid that produces a righting moment.

local cols = buoyancy.columns({ x = 4, y = 1, z = 2 }, 2)

modules/buoyancy/configure

configure(self, options: any)

Reconfigure a floating body. Any field may be passed; anything omitted is left as it was.

Parameters

• self any (optional)
• options any (optional) — { density, damping, angularDamping, columns, sizeX, sizeY, sizeZ, mass, gravityScale, ocean }. mass and gravityScale stand in for the rigid body's own, which is what they are read from otherwise.

float:configure({ density = 0.8 })

modules/buoyancy/destroy

destroy(self)

Stop floating this body. The rigid body keeps everything else about it.

Parameters

• self any (optional)

float:destroy()

modules/buoyancy/forEntity

forEntity(entityId: string): any

The floating body on an entity, if it has one.

Parameters

• entityId string — The entity's id.

local float = buoyancy.forEntity(barrelId)

modules/buoyancy/list

list(): { any }

Every body currently floating.

print(#buoyancy.list())

modules/buoyancy/restingY

restingY(waterY: number, height: number, density: number): number

The height a hull of this density displaces its own weight at on flat water — the waterline its lift balances at, with no wave motion in it.

Parameters

• waterY number — World Y of the undisturbed surface.
• height number — The hull's full height.
• density number — The hull's density relative to water.

local y = buoyancy.restingY(0, 1, 0.45)

modules/buoyancy/submergedFraction

submergedFraction(centreY: number, waterY: number, height: number): number

How much of a column stands under water: 0 clear of it, 1 fully under.

Parameters

• centreY number — World Y of the column's mid-height.
• waterY number — World Y of the surface above it.
• height number — The column's full height.

local f = buoyancy.submergedFraction(0.2, 0.0, 1.0)

modules/buoyancy/submersion

submersion(self): number

The share of the hull that was under water on the last step, averaged over its columns. 0 is clear of the sea, 1 is fully submerged.

Parameters

• self any (optional)

print(float:submersion())

modules/buoyancy/waterline

waterline(self): number?

The world Y of the water surface under the hull's centre on the last step — where the waterline stood, wave motion included.

Parameters

• self any (optional)

print(float:waterline())

modules/cachedIndirect/README

require("@builtin::systems.radianceCache.cachedIndirect") -- cachedIndirect

Indirect diffuse light that is gathered once per patch of world and reused, rather than re-gathered for every pixel of every frame. It is the scene-wide user of @builtin::systems.radianceCache.radianceCache and the worked example of what a cache buys a lighting technique: the same bounce, converged over frames instead of within one, at a fraction of the gathering per frame.

Usage: local cachedIndirect = require("@builtin::systems.radianceCache.cachedIndirect")

modules/cachedIndirect/active

active(): boolean

Whether the cached-indirect passes are running this frame.

if cachedIndirect.active() then ... end

modules/cachedIndirect/cache

cache(): any

The cache this effect drives. The render feature takes its passes from here, and a script can read its counters or invalidate it through the same handle.

cachedIndirect.cache():stats()

modules/cachedIndirect/clear

clear()

Turn the cached bounce off and release the passes, the cache table and the resolve target. The other settings are kept, so a later set({ intensity = ... }) brings the effect back at the same settings and refills the table over history * stride frames.

cachedIndirect.clear()

modules/cachedIndirect/get

get(): { [string]: number }

The cached-indirect settings currently in force.

local s = cachedIndirect.get().stride

modules/cachedIndirect/invalidate

invalidate()

Declare that the lighting changed, so every patch takes its next gather whole instead of averaging it into light that is gone. The cache is rebuilt within stride frames.

cachedIndirect.invalidate()

modules/cachedIndirect/set

set(opts: CachedIndirectOpts?): { [string]: number }

Set the scene's cached indirect light. Any omitted field keeps its current value. An intensity of 0 turns it off and releases the passes.

Parameters

• opts CachedIndirectOpts? (optional) — Cached-indirect settings — see CachedIndirectOpts.

cachedIndirect.set({ intensity = 1.0, stride = 8 })

modules/camera/README

require("@builtin::modules.api.engine.camera") -- camera (also available as global 'camera')

Script-facing camera queries: the main scene camera, the on-screen render camera, the editor fly-camera, per-frame view data, and the camera observation — which cameras drew this frame, with what projection, into what, and at what cost. Public Luau surface over the __camera Internal FFI namespace. A physical camera on the machine (a webcam, a phone's front or back camera) is cameraInput, which shows its live picture as a texture.

Usage: local camera = require("@builtin::modules.api.engine.camera") Also available as global: camera

modules/camera/active

active(): string?

Entity id of the on-screen render camera this frame — whichever camera wins the viewport by priority (the editor fly-camera in edit mode, the gameplay camera in play). Render features, billboards, and input bases that must follow the human's on-screen view read this.

local camId = camera.active()

modules/camera/cut

cut()

Declare that the camera on screen cuts: the next frame it draws stands somewhere it did not travel to. Motion vectors are the difference between where a surface projects now and where it projected on the camera's previous frame, and everything temporal reads that difference — the shutter reconstructs the frame by walking it, a temporal resolve reprojects its history along it. Across a cut that difference describes a displacement no surface made, so the frame is reconstructed from taps a whole screen away and belongs to neither shot. A declared cut leaves the camera with no previous frame for exactly one frame, which is the state its very first frame is already in, so every consumer reads zero motion across the cut. Declare it in the same step that places the camera at the new station; declaring it again before that frame draws still costs the one frame. Handing the viewport from one camera to another is already a cut without being declared one: the incoming camera stands where it always stood, and the engine performs the handover, so it is what states it.

camera.cut(); entity(camId).position = { 40, 6, -12 }

modules/camera/editor

editor(): string?

Entity id of the editor fly-camera (the EditorOnly authoring camera), or nil if the scene has none. This is the camera the editor viewport renders through, so it is the one a capture of the screen sees. Its pose is its entity transform: assign entity(id).position to move it and aim it with the camera toolbox's lookAt, which makes a screen capture repeatable instead of whatever pose the instance booted with.

local camId = camera.editor()
local id = camera.editor(); entity(id).position = { 12, 8, 12 }; tools.use("camera", "lookAt", id, { 0, 0, 0 })

modules/camera/editorOverride

editorOverride(): string?

Entity id currently overriding viewport selection, or nil when the viewport is decided by highest-priority-wins.

local owner = camera.editorOverride()

modules/camera/get

get(target: (string | EntityRef)): CameraReport?

One camera's report from the observation — the same record camera.list yields, for the camera the caller names. Takes an entity id, an entity name, or an entity proxy, the same way the camera tools do.

Parameters

• target (string | EntityRef) — Entity id, entity name, or entity proxy of the camera to report on.

local c = camera.get(camera.active()); print(c.frame.far, c.authored.far)
local c = camera.get("minimapCam"); print(c.rendering, c.reason)

modules/camera/list

list(): { CameraReport }

Every camera in the world as a compact row each, ordered the way the renderer resolves the on-screen camera: highest priority first. Reads the same observation camera.observe does, so a row can never disagree with the full report about whether a camera is enabled or which one drew.

for _, c in ipairs(camera.list()) do print(c.name, c.enabled, c.rendering) end

modules/camera/main

main(): string?

Entity id of the main scene camera — the scene camera the viewport is drawn from, and while the editor fly-camera holds the screen, the scene camera that would take it. The gameplay/PlayerPrototype camera, an agent-placed scene camera, or a cutscene camera. Never the editor camera; nil if the scene has only the editor camera. It comes off the same selection the frame does, so writing a pose to it moves what is drawn whenever a scene camera is on screen. The scene camera with the highest authored priority takes it; cameras tied on priority settle on the order the frame visits them, so a scene that needs a specific camera — a prototype and the clone play makes of it both stand at 0 — states a distinct priority rather than resting on that order. For the camera drawn on screen whichever partition owns it, use camera.active().

local camId = camera.main(); local cam = camId and entity(camId)

modules/camera/motionTally

motionTally(): { frames: number, withoutHistory: number }

Frames the camera on screen has drawn, and how many of them had no previous frame to difference their motion vectors against — its first frame, every declared cut, and every frame the viewport changes hands on. Both counts are monotonic across the session, so two readings either side of a run say what happened in between.

local before = camera.motionTally().withoutHistory

modules/camera/observe

observe(): CameraObservation?

Every camera in the world, for the frame that has just been drawn. lastRender retains the latest submitted frame, target and pending build count while the camera exists, including frames when it is disabled. engineFrame identifies the script frame (time.frameCount()) that drew. Answers "why is this camera not showing what I expect" in one call: rendering says whether each camera drew and reason names the single cause when it did not — "disabled", "entityInactive", "targetMissing", "noLayers", "outranked", "notDrawn", "paced" for a texture camera whose per-frame render waits for the next frame the frame pacer admits, or "awaitingPipelines" for a deferrable render queued behind pipeline builds. Explicit camera renders draw the requested frame and report its pending builds in lastRender. pipelinesPending counts the builds a camera is waiting on: what a held render is queued behind, and — for a camera that DID draw — what the frame it drew was drawn WITHOUT. It is absent once a camera's frame was drawn with everything the scene asked for. Each camera carries both projections: authored is what the Camera component holds and frame is what the renderer actually built, with mismatch naming every field the two disagree on — so a clip range or a lens the frame did not use is one field read. frame, viewProj, frustum and the cost numbers describe a camera that drew; every cost is for that one frame. One snapshot is published per drawn frame, from after the frame is drawn, so a read describes the last frame rather than the world at the instant of the call — a write and a read in one script step return the frame that ran before the write. Put a task.wait() between them to compare a camera either side of a change; frame counts the frames observed, so a poll can wait for it to advance.

local obs = camera.observe(); for _, c in ipairs(obs.cameras) do print(c.name, c.rendering, c.reason) end
local dark = {}; for _, c in ipairs(camera.observe().cameras) do if not c.rendering then table.insert(dark, c.name .. ": " .. tostring(c.reason)) end end

modules/camera/setEditorOverride

setEditorOverride(entityId: string?)

Give one camera the viewport outright, or pass nil to clear it. While set, that camera IS the on-screen camera and priority is never consulted, so no authored priority can take the viewport from it — which is what makes an authoring camera safe to fly over a scene holding a camera at any priority. An override naming a camera that is despawned or disabled falls back to highest-priority-wins rather than blanking the screen. The override holds across a change of engine.mode: the flip rebuilds the scene and materialises its cameras again, and an override whose camera the rebuilt scene holds under the same entity id names it again once the rebuild has ended. One whose camera the rebuilt scene does not hold (a temporary camera, or one play replaces with a clone of its own) ends there: a warning notice and the engine log name the camera it held, and the wld.play / wld.edit result reports it under viewportOverride. An override on a camera that draws nothing in the new mode (an EditorOnly camera sits out play) stands, and the highest-priority camera holds the viewport until its camera draws again; viewportOverride.onScreen names the camera holding it.

Parameters

• entityId string? (optional) — Entity id of the camera to route the viewport to, or nil to clear.

camera.setEditorOverride(camera.editor())
camera.setEditorOverride(nil)

modules/camera/viewData

viewData(target: ((string | EntityRef)?)): CameraView?

Camera render data. Called with no argument it is the active viewport camera's data for this frame: world position, which projection it drew and the field describing that frame, viewport pixel size, the 6 world-space frustum planes (the same inward-pointing, normalized planes the renderer culls with), and the view-projection matrix. The camera state a render feature needs for camera-relative work — LOD selection, frustum culling, billboards. Render features also get it as ctx.camera. Called with an entity id it is that camera's data, read from the frame's camera observation, and carries the identity the bare form has no room for: which camera it describes, which frame it was built for, what it rendered into, and the render layers it resolved to.

Parameters

• target ((string | EntityRef)?) (optional) — Entity id, name, or proxy of the camera to read, or nil for the viewport camera.

local c = camera.viewData(); if c then print(c.position.x, c.fovY) end
local minimap = camera.viewData("minimapCam"); print(minimap.output.target, minimap.viewport.w)

modules/cameraInput/README

require("@builtin::modules.api.engine.cameraInput") -- cameraInput (also available as global 'cameraInput')

Physical cameras as live textures and pixel sources: list the capture devices (a webcam, a phone's front and back cameras), open one as a feed, show its live picture anywhere a texture goes (a material, a UI image, a recording), and read its pixels. Public Luau surface over the __cameraInput Internal FFI namespace.

Usage: local cameraInput = require("@builtin::modules.api.engine.cameraInput") Also available as global: cameraInput

modules/cameraInput/awaitRunning

awaitRunning(self: CameraFeed, timeoutSeconds: number?): (boolean, string?)

Wait until the feed is running, and report whether it got there. Returns as soon as the feed leaves starting and permissionPending, or when timeoutSeconds have passed, whichever comes first: a permission prompt nobody answers never settles, so the wait is always bounded.

Parameters

• self CameraFeed
• timeoutSeconds number? (optional) — Seconds to wait at most. Defaults to 10.

local ok, why = feed:awaitRunning(15); if not ok then print(why) end

modules/cameraInput/devices

devices(): { CameraDevice }

Every capture device the platform offers: id is what cameraInput.open takes as device, name the label a person recognises, facing which way it points. Until camera access has been granted, id and name read as empty strings and facing as "unknown": the list is part of what the permission protects, so a first open takes the default camera or a facing, and the list names the devices after that.

for _, d in ipairs(cameraInput.devices()) do print(d.name, d.facing) end

modules/cameraInput/feeds

feeds(): { CameraFeedEntry }

Every open feed, with the owning context that opened it (scope, the same tag scopes.list() shows), whose end stops the feed.

for _, f in ipairs(cameraInput.feeds()) do print(f.id, f.state, f.scope) end

modules/cameraInput/onDeviceChange

onDeviceChange(callback: (devices: { CameraDevice }) -> ()): () -> ()

Call callback with the new device list every time a camera is added or removed, or the platform names its devices after access is granted. Each listener is watched by a task of the context that registered it, so a listener a component registered ends when that component is removed, and every other listener goes on hearing changes.

Parameters

• callback (devices: { CameraDevice }) -> () — Receives the device list, as cameraInput.devices() returns it.

Returns () — A function that removes this listener.

local off = cameraInput.onDeviceChange(function(devices) print(#devices) end)

modules/cameraInput/open

open(opts: CameraOpenOpts?): (CameraFeed?, string?)

Open a camera as a feed. Returns the feed at once; it reads permissionPending while the platform asks for access, then running (or denied / failed with a reason). Wait with feed:awaitRunning().

feed.texture is a texture handle that shows the camera's current frame: put it on a surface as a session material's base_color_texture (renderer.material.create, worn with Model:applySessionMaterial) or in a slot of a material that exists (renderer.material.setTexture(key, "base_color_texture", feed.texture)), in UI as { type = "image", props = { src = feed.texture } }, and av.record films it like any other scene content.

device names a camera by the id or name cameraInput.devices() lists; facing asks for the "front" or "back" camera instead; with neither, the platform's default camera opens. width, height and fps are hints: the device delivers the nearest it can, and feed:status() reports what it delivers. A second feed on a camera already open shares it.

Returns nil and the reason for a request refused before any camera is touched: a hint outside its range, a facing other than front or back, a device the platform does not offer.

Parameters

• opts CameraOpenOpts? (optional) — { device, facing, width, height, fps }, every field optional.

local feed = cameraInput.open({ facing = "front", width = 1280, height = 720 })
local screen = feed and renderer.material.create({ shader = "unlit", textures = { base_color_texture = feed.texture } }, "tv_screen")

modules/cameraInput/readPixels

readPixels(self: CameraFeed, rect: CameraRect?): (any, string?)

Read the pixels of the frame the feed is showing now, without stopping it: the whole frame, or the rectangle { x, y, w, h } of it in pixels from the top-left corner. The answer is a TextureCpuHandle holding RGBA8 pixels (:readPixel(x, y), :rgba(), :encodePng()); :unload() it once done. Returns nil and the reason while no frame has arrived, after the feed stopped, or for a rectangle outside the frame.

Parameters

• self CameraFeed
• rect CameraRect? (optional) — Optional { x, y, w, h }.

local cpu = feed:readPixels(); if cpu then print(cpu:readPixel(0, 0)); cpu:unload() end

modules/cameraInput/status

status(self: CameraFeed): CameraStatus

Where the feed stands. width, height and fps are what the device delivers, whatever the open asked for. frames advances once per new frame, so two reads that show the same count saw the same picture. rotation is the degrees clockwise the picture turns to stand upright on the display, and follows a phone's screen as it turns; mirrored says the picture, once turned, reads as the person expects only when shown mirrored, which is how a front camera is shown. reason carries the platform's own message for denied and failed, and what is being waited on for permissionPending.

Parameters

• self CameraFeed

local s = feed:status(); print(s.state, s.width, s.height, s.frames)

modules/cameraInput/stop

stop(self: CameraFeed): boolean

Stop the feed. The camera is released once no other feed is reading it, which is what turns the platform's camera indicator off. True when the feed was open.

Parameters

• self CameraFeed

feed:stop()

modules/cameraInput/stopAll

stopAll(): number

Stop every open feed and release every camera, whatever opened them.

cameraInput.stopAll()

modules/camera_spawner/README

require("@builtin::modules.api.engine.camera_spawner") -- camera_spawner

DEPRECATED: v7 scenes author their own Camera entity. This procedural primary-camera spawner serves legacy v6 scenes only; M.ensure stands down (returns early) for any scene carrying a string playerIntent.

Spawns the scene's primary Camera entity on non-additive layers.onLoad, for legacy v6 scenes. The per-mode world default (world.camera_default_<mode>) is the fallback; scene-level overrides via sceneProxy.settings.camera win when present. Missing refs → log.error + skip (no hardcoded fallback).

Usage: local camera_spawner = require("@builtin::modules.api.engine.camera_spawner")

modules/carried/README

require("@builtin::modules.api.engine.carried") -- carried (also available as global 'carried')

Carried mounts: content of another world, mounted read-only for this session at /zero/runtime/carried/<key>/ without installing it. A closure is named by the address of its manifest (closureSha, the sha-256 ZeroMind serves the manifest at); the engine reads the manifest and every file it names through the device's content cache, lays the files out the way their world places them, and states where the mount stands in <key>/status. Nothing a mount holds is content of the open world: it is in no listing of its assets, no dependency table, no push and no zm status, and the open world's code cannot require from it. A mount lives while some caller holds it and the session lasts.

carried.mount(closureSha, { key = "ada.avatar" }) holds a mount and starts filling it; carried.wait(key) yields until it settles; carried.status(key) reads where it stands; carried.release(key) lets go of it. carried.mountDraft(assetPath) mounts the closure of an asset of the open world's working tree the same way, for a preview on this engine. carried.resolve(key, reference) answers what a reference written inside the closure names. guides { path: "core/carried" } covers the whole surface.

Usage: local carried = require("@builtin::modules.api.engine.carried") Also available as global: carried

modules/carried/heldBytes

heldBytes(): number

The bytes every carried mount holds in this engine's memory.

print(carried.heldBytes())

modules/carried/list

list(): { Status }

The status of every carried mount of this session.

for _, m in carried.list() do print(m.key, m.state) end

modules/carried/manifest

manifest(key: string): string?

The manifest of the ready mount at key: the JSON bytes the content store served ($schema zero/closure/v1, root, and entries, one per file and folder with its world path, asset_guid, checksum, size_bytes, kind and origin, plus one engine entry per builtin it was built against). Their sha-256 is the mount's closureSha. Nil until the mount is ready.

Parameters

• key string — The mount's key.

local entries = require("@builtin::modules.json").decode(carried.manifest("ada.avatar")).entries

modules/carried/mount

mount(closureSha: string, options: MountOptions?): Status

Hold the carried mount of the closure whose manifest address is closureSha and start filling it, unless it is already held. The mount stands at /zero/runtime/carried/<key>/; a key holds one closure for as long as anyone uses it, and every mount of the same closure at the same key holds it once more. Answers at once with the mount's status (state resolving while it fills); carried.wait yields until it settles. Raises when the key is malformed, closureSha is no sha-256, or the key holds another closure.

Parameters

• closureSha string — The sha-256 hex digest of the closure's manifest.
• options MountOptions? (optional) — key: the mount's folder name (one path segment of letters, digits, ., _, -), default closure-<first 16 hex digits>; commit: the commit the closure was published at, stated in the status.

local m = carried.mount(sha, { key = "ada.avatar" }); local s = carried.wait(m.key)

modules/carried/mountDraft

mountDraft(assetPath: string, options: MountOptions?): Status

Hold a draft carried mount of the asset at assetPath, an asset of the open world's working tree (or of your home folder): the engine walks the asset and every asset its files reference, writes that closure and its manifest into the device's content cache, and mounts it from there the way a published closure mounts, labelled draft = true. It is this engine's alone. Mounting it again rebuilds it from the tree as it stands. A draft holding a home folder's content is that folder's: it is made for code that reaches the folder, and its files, listing, status and manifest answer that code alone. Raises, naming the folder, when the asset or anything it reaches is in a home folder the calling code does not reach.

Parameters

• assetPath string — The asset, e.g. /zero/source/chars/ada.avatar.
• options MountOptions? (optional) — key: the mount's folder name, default draft-<asset name>.

local d = carried.mountDraft("/zero/source/props/lamp.model"); carried.wait(d.key)

modules/carried/release

release(key: string): number

Let one holder of the mount at key go. The last one takes it down: its folder leaves /zero/runtime/carried/ and its bytes leave this engine's memory, while the device's content cache keeps them for the next mount. Raises when no mount is held at key.

Parameters

• key string — The mount's key.

carried.release("ada.avatar")

modules/carried/resolve

resolve(key: string, reference: string): string?

What reference, written by content of the closure at key, names: a guid the closure carries, a path of its world (props/lamp.model, /zero/source/props/lamp.model) or an identity of its world (props.lamp) answers the file inside the mount; a reference to the engine library answers the library asset, taken to the version of an engine builtin the closure was built against when the mount holds that version. The open world's own content answers none of it. Nil when nothing answers.

Parameters

• key string — The mount's key.
• reference string — A guid, path, identity or library reference.

local tex = carried.resolve("ada.avatar", "chars.ada_albedo")

modules/carried/status

status(key: string): Status?

Where the mount at key stands, as <key>/status states it: state is resolving, fetching, measuring, ready, refused or none; reason is a word saying why nothing is mounted (unreachable, notFound, incomplete) or why the closure was refused, with detail the sentence; bytesFetched / bytesTotal count the files read; measured counts files, folders and bytes per kind once ready; builtin names how each engine builtin the closure was built against resolves (host, mount, or hostOtherVersion with why). Nil when no mount is held at key, and when the mount holds a home folder's content the calling code does not reach.

Parameters

• key string — The mount's key.

print(carried.status("ada.avatar").state)

modules/carried/wait

wait(key: string, seconds: number?): Status

Yield until the mount at key settles (ready, refused or none) or seconds pass, and answer its status then. Raises when no mount is held at key, or when it holds a home folder's content the calling code does not reach.

Parameters

• key string — The mount's key.
• seconds number? (optional) — How long to wait, default 120.

local s = carried.wait("ada.avatar", 30); assert(s.state == "ready", s.detail)

modules/channel/README

require("@builtin::modules.api.engine.channel") -- channel (also available as global 'channel')

Keyframe-channel sampling primitives — registry + sampleInto variants. Public Luau surface over the __channel Internal FFI namespace.

Usage: local channel = require("@builtin::modules.api.engine.channel") Also available as global: channel

modules/channel/create

create(opts: ChannelOpts): number?

Register a keyframe channel. times is the sorted keyframe time array; values is the packed value array (layout depends on interp); stride is the floats-per-sample width; interp is "step" | "linear" | "slerp" | "cubicHermite". Returns the channel handle, or nil on malformed input.

Parameters

• opts ChannelOpts — { times, values, stride, interp }.

local h = channel.create({ times = ts, values = vs, stride = 3, interp = "linear" })

modules/channel/destroy

destroy(handle: number): boolean

Drop the channel from the registry.

Parameters

• handle number — Channel handle.

modules/channel/sampleInto

sampleInto(ch: number, time: number, buf: Substrate.TypedBuffer, offset: number): boolean

Sample the channel at time and write stride floats into the buffer starting at f32 index offset. Returns false on unknown handle, layout mismatch, or out-of-bounds; the buffer is unchanged on failure.

Parameters

• ch number — Channel handle.
• time number — Sample time in seconds.
• buf Substrate.TypedBuffer — The buffer written into.
• offset number — Starting f32 index in the buffer.

modules/channel/sampleManyInto

sampleManyInto(ch: number, time: number, buf: Substrate.TypedBuffer, offsets: { number }): boolean

Sample once, blit the result into every position in offsets. Saves the per-offset binary search when one channel feeds many bones / particles / parameters.

Parameters

• ch number — Channel handle.
• time number — Sample time in seconds.
• buf Substrate.TypedBuffer — The buffer written into.
• offsets { number } — Array of f32 indices.

modules/channel/sampleQuat

sampleQuat(ch: number, time: number): (number?, number?, number?, number?)

Convenience accessor for stride-4 quaternion channels.

Parameters

• ch number — Channel handle.
• time number — Sample time.

modules/channel/sampleVec3

sampleVec3(ch: number, time: number): (number?, number?, number?)

Convenience accessor for stride-3 channels. Returns the three components as multiret, or nil if the channel is unknown / has a different stride.

Parameters

• ch number — Channel handle.
• time number — Sample time.

local x, y, z = channel.sampleVec3(h, t)

modules/color/README

require("@builtin::modules.api.engine.color") -- color (also available as global 'color')

Color construction, conversion, and perceptual ops (RGB / HSL / HSV / Oklch / hex). Public Luau surface over the __color Internal FFI namespace.

Usage: local color = require("@builtin::modules.api.engine.color") Also available as global: color

modules/color/coerce

coerce(value: any): Color?

Read a value written in any of the shapes a colour is authored in — a hex string, an {r=,g=,b=,a=} map, or an {r,g,b,a} array — as an sRGB color table. Returns nil when the value does not describe a colour, so a caller can name the value it was handed instead of substituting one. Channels absent from a map or array read as 0; alpha absent reads as 1.

Parameters

• value any (optional) — Value to read as a colour.

local c = color.coerce("#5a5a62") or color.coerce({ 0.2, 0.7, 0.2 })

modules/color/complementary

complementary(c: Color): Color

Complementary color — rotate hue 180° in Oklch space.

Parameters

• c Color — Input color.

local accent = color.complementary(primary)

modules/color/darken

darken(c: Color, amount: number): Color

Decrease the lightness of a color in Oklch perceptual space.

Parameters

• c Color — Input color.
• amount number — Lightness decrease 0-1.

local pressed = color.darken(base, 0.1)

modules/color/desaturate

desaturate(c: Color, amount: number): Color

Decrease the chroma (saturation) of a color in Oklch space.

Parameters

• c Color — Input color.
• amount number — Chroma decrease (typically 0-0.2).

local muted = color.desaturate(base, 0.05)

modules/color/hex

hex(hexString: string): Color?

Parse a hex color string into an sRGB color table. Accepts 3, 4, 6, or 8 hex digits with or without a leading # (e.g. "#f00", "f00f", "#ff0000", "ff000080"). Returns nil on parse failure.

Parameters

• hexString string — Hex color string.

local fromCss = color.hex("#ff8800")

modules/color/hsl

hsl(h: number, s: number, l: number): Color

Build a color from HSL (h: 0-360, s: 0-1, l: 0-1). Returned as sRGB.

Parameters

• h number — Hue (degrees, 0-360).
• s number — Saturation (0-1).
• l number — Lightness (0-1).

local teal = color.hsl(180, 0.5, 0.5)

modules/color/hsla

hsla(h: number, s: number, l: number, a: number): Color

Build a color from HSLA, returned as sRGB.

Parameters

• h number — Hue (0-360).
• s number — Saturation (0-1).
• l number — Lightness (0-1).
• a number — Alpha (0-1).

local fadedTeal = color.hsla(180, 0.5, 0.5, 0.3)

modules/color/hsv

hsv(h: number, s: number, v: number): Color

Build a color from HSV (h: 0-360, s: 0-1, v: 0-1).

Parameters

• h number — Hue (0-360).
• s number — Saturation (0-1).
• v number — Value / brightness (0-1).

local primary = color.hsv(220, 0.7, 0.9)

modules/color/lighten

lighten(c: Color, amount: number): Color

Increase the lightness of a color in Oklch perceptual space.

Parameters

• c Color — Input color.
• amount number — Lightness increase 0-1.

local hover = color.lighten(base, 0.1)

modules/color/linear

linear(r: number, g: number, b: number, a: number?): Color

Build a color from linear RGB values (not gamma-corrected), output converted to sRGB. Useful for GPU-correct blending. Alpha defaults to 1.

Parameters

• r number — Linear red (0-1).
• g number — Linear green (0-1).
• b number — Linear blue (0-1).
• a number? (optional) — Alpha (0-1, default 1).

local gpuBlue = color.linear(0.0, 0.0, 1.0)

modules/color/mix

mix(c1: Color, c2: Color, t: number): Color

Perceptually blend two colors in Oklch space — better than RGB mixing for gradients.

Parameters

• c1 Color — First color.
• c2 Color — Second color.
• t number — Blend factor 0-1 (0 = c1, 1 = c2).

local mid = color.mix(color.rgb(255, 0, 0), color.rgb(0, 0, 255), 0.5)

modules/color/mixRgb

mixRgb(c1: Color, c2: Color, t: number): Color

Linearly blend two colors in sRGB space — simple, but not perceptually uniform. Prefer color.mix for natural gradients.

Parameters

• c1 Color — First color.
• c2 Color — Second color.
• t number — Blend factor 0-1.

local plain = color.mixRgb(a, b, 0.5)

modules/color/oklch

oklch(l: number, c: number, h: number): Color

Build a color from Oklch perceptual color space (l: 0-1, c: 0-0.4, h: 0-360). Ideal for perceptually uniform gradients and color manipulation.

Parameters

• l number — Lightness (0-1).
• c number — Chroma / saturation (0-0.4).
• h number — Hue (0-360).

local accent = color.oklch(0.7, 0.15, 30)

modules/color/rgb

rgb(r: number, g: number, b: number): Color

Build an sRGB color from CSS-style 0-255 RGB channels. Alpha defaults to 1. Channels are normalised to 0-1 on the way out so the result composes with every other color helper.

Parameters

• r number — Red channel (0-255).
• g number — Green channel (0-255).
• b number — Blue channel (0-255).

local red = color.rgb(255, 0, 0)

modules/color/rgba

rgba(r: number, g: number, b: number, a: number): Color

Build an sRGB color from CSS-style 0-255 RGB channels with explicit alpha. RGB are normalised to 0-1; alpha is taken as-is in the 0-1 range.

Parameters

• r number — Red channel (0-255).
• g number — Green channel (0-255).
• b number — Blue channel (0-255).
• a number — Alpha (0-1).

local halfRed = color.rgba(255, 0, 0, 0.5)

modules/color/rotateHue

rotateHue(c: Color, degrees: number): Color

Rotate the hue of a color by a given number of degrees in Oklch space.

Parameters

• c Color — Input color.
• degrees number — Hue rotation (positive or negative).

local triadic = color.rotateHue(base, 120)

modules/color/saturate

saturate(c: Color, amount: number): Color

Increase the chroma (saturation) of a color in Oklch space.

Parameters

• c Color — Input color.
• amount number — Chroma increase (typically 0-0.2).

local pop = color.saturate(base, 0.05)

modules/color/toHex

toHex(c: Color): string

Convert a color to a hex string. Returns "#rrggbb" or "#rrggbbaa" if alpha is not 1.

Parameters

• c Color — Input color.

print(color.toHex(color.rgb(255, 136, 0))) -- "#ff8800"

modules/color/toHsl

toHsl(c: Color): HslColor

Convert a color to HSL.

Parameters

• c Color — Input color.

local hsl = color.toHsl(base)

modules/color/toLinear

toLinear(c: Color): Color

Convert a color from sRGB to linear RGB space — useful for GPU calculations that need linear-space values.

Parameters

• c Color — Input sRGB color.

local gpu = color.toLinear(base)

modules/color/toOklch

toOklch(c: Color): OklchColor

Convert a color to Oklch perceptual color space.

Parameters

• c Color — Input color.

local okl = color.toOklch(base)

modules/color/withAlpha

withAlpha(c: Color, a: number): Color

Return a copy of a color with a different alpha value.

Parameters

• c Color — Input color.
• a number — New alpha (0-1).

local ghost = color.withAlpha(base, 0.3)

modules/compute/README

require("@builtin::modules.api.engine.compute") -- compute (also available as global 'compute')

GPU compute pipelines — compile shaders, dispatch workgroups, read back results. Public Luau surface over the __compute Internal FFI namespace. A buffer belongs to the shader that owns it (shaderRef:createBuffer) or to the substrate (substrate.createBuffer), and reaches a dispatch as a handle.

Usage: local compute = require("@builtin::modules.api.engine.compute") Also available as global: compute

modules/compute/absentReasons

absentReasons(): { string }

Every reason compute.diagnose reports, sorted. resident is the one that means the resource is there.

for _, r in ipairs(compute.absentReasons()) do print(r) end

modules/compute/beginBvh

beginBvh(instances: { any }, opts: { [string]: any }?): (number?, string?)

Start the build compute.buildBvh runs, without running any of it. Takes the same instances and options and reports the same non-resident guids, and returns an id compute.stepBvh advances a bounded slice at a time and compute.finishBvh collects. Each mesh the instances name is copied as this is called — once per guid however many instances share it — so the CPU mesh may be unloaded on the next line and the build still finishes on the copy it holds. compute.buildBvhSliced is the whole loop as one call.

Parameters

• instances { any } — Array of { guid, transform, attributes? } mesh instances.
• opts { [string]: any }? (optional) — Optional { maxLeaf? } — max triangles per leaf.

local id = compute.beginBvh(gather.instances)

modules/compute/buildBvh

buildBvh(instances: { any }, opts: { [string]: any }?): (any, string?)

Build a bounding-volume hierarchy over the world-space triangles of a set of mesh instances and upload it as two named compute buffers — geometry never passes through the scripting heap. Each instance is { guid, transform, attributes? }: guid names a mesh resident in the meshcpu store (materialise with ref:load() / meshcpu.load), transform is 16 numbers, row-major, translation in slots 4/8/12, and attributes is up to 40 floats stamped onto every triangle of that instance (surface colors, material ids, physics tags — whatever the consuming shader wants per-surface). Triangles pack 18 vec4 each (v0/v1/v2, n0/n1/n2, uvs, then 10 attribute vec4s — float slots 32.. carry the instance attributes, zero when absent) in BVH leaf order; nodes 2 vec4 each (min + first-or-left, max + leaf-tagged count-or-right). Consumers: GI baking, ray-traced passes, GPU picking, navmesh and SDF generation.

Parameters

• instances { any } — Array of { guid, transform, attributes? } mesh instances.
• opts { [string]: any }? (optional) — Optional { maxLeaf? } — max triangles per leaf.

local bvh = compute.buildBvh(instances)
asset.resolve("raytrace", "computeShader"):dispatch({ buffers = { bvh.nodes, bvh.tris }, workgroups = { 64, 1, 1 } })

modules/compute/buildBvhSliced

buildBvhSliced(instances: { any }, opts: { [string]: any }?): (any, string?)

The hierarchy compute.buildBvh builds, spread over as many frames as it takes: a slice of the build per frame, so a scene's triangle count costs the frame loop budgetMs at a time instead of the whole build at once. Yields, so it is called from a task. The result is the same pair of buffers and the same counts compute.buildBvh returns.

Parameters

• instances { any } — Array of { guid, transform, attributes? } mesh instances.
• opts { [string]: any }? (optional) — Optional { maxLeaf?, budgetMs? } — max triangles per leaf, and the wall time one frame may spend on the build (default 4 ms).

local built, err = compute.buildBvhSliced(gather.instances, { budgetMs = 4 })

modules/compute/bvhBuilds

bvhBuilds(): { any }

What the builds started by compute.beginBvh and not yet finished are costing, oldest id first. Each row is { id, phase, triangles, units, slices, cpuMs, uploadedBytes }: phase is "gather", "build", "serialize", "upload" or "ready", triangles how many have been gathered, units the work units run, slices the compute.stepBvh calls they ran in, cpuMs the wall time spent inside those calls, and uploadedBytes how much of the hierarchy has reached the GPU.

print(#compute.bvhBuilds(), "hierarchies in flight")

modules/compute/cancelBvh

cancelBvh(id: number): boolean

Drop a build along with the triangles it has gathered.

Parameters

• id number — Build id from compute.beginBvh.

compute.cancelBvh(id)

modules/compute/compile

compile(nameOrHandle: string | { [string]: any } | AssetRef, opts: { [string]: any }?): (boolean, string?)

Compile a compute shader from inline WGSL + a declarative binding schema — the same codegen a .computeShader asset uses. The engine generates the @group/@binding declarations from bindings/params, so the source writes only @compute fn main. Symmetric with registerShader, but with zero-scaffolding bindings (incl. textures, samplers, storage textures and a params uniform). For asset-backed shaders prefer authoring a .computeShader (compiled automatically); use this for dynamic/generated compute shaders.

Parameters

• nameOrHandle string | { [string]: any } | AssetRef — Shader identity to register under (string or asset handle).
• opts { [string]: any }? (optional) — { source, entryPoint?, bindings, params? } — bindings is an ordered list of { name, kind, access?, element?, format?, array?, sample? }.

compute.compile("my_sim", { source = WGSL, bindings = { { name = "data", kind = "buffer", access = "read_write", element = "f32" } } })

modules/compute/compileByName

compileByName(ref: string | { [string]: any } | AssetRef)

Optional explicit pre-warm for a .computeShader asset (idempotent — fingerprint-guarded). NORMALLY UNNECESSARY: compute.dispatch / dispatchEx auto-compile a .computeShader on first use. Reach for this only to avoid the one-frame first-dispatch warm-up in a latency-critical spot. Accepts an identity/guid string or a resolved asset handle (its .identity is used).

Parameters

• ref string | { [string]: any } | AssetRef — A .computeShader identity/guid string, or a resolved asset handle.

compute.compileByName("@builtin::shaders.compute_double")

modules/compute/copyBufferToTexture

copyBufferToTexture(bufferName: string, textureKey: string, width: number, height: number, format: string?, rowBytes: number?): boolean

Copy a compute buffer into a cached GPU texture under textureKey, staying on the GPU. The path for an image a compute pass produced: the buffer holds tightly-packed rows in the format's texel layout, and the result is an ordinary cached texture — sample it from a material, or pack it into the shared feature-texture array. The copy reads rows 256-byte aligned: rows packed tight must be a multiple of 256 bytes (at rgba16f, any width that is a multiple of 32), and any other width is laid out with its rows padded to that alignment and rowBytes saying how far apart they are.

Parameters

• bufferName string — Source compute buffer.
• textureKey string — Cache key to register the texture under.
• width number — Texture width in texels.
• height number — Texture height in texels.
• format string? (optional) — Texel format: "rgba16f" (default), "rgba32f", "rgba8".
• rowBytes number? (optional) — Bytes from one row's start to the next when rows are padded past width texels — a multiple of 256 at least a row's texels long.

compute.copyBufferToTexture("gi_resolved", "lm_wall", 128, 128)
compute.copyBufferToTexture("heights_packed", "heights", 300, 300, "rgba16f", 2560)

modules/compute/createBuffer

createBuffer(name: string, opts: { [string]: any }): boolean

Allocate a buffer under name, sized in bytes.

Parameters

• name string — The name a dispatch binds it by.
• opts { [string]: any } — { size, readback? } — size in bytes.

modules/compute/createSampler

createSampler(name: string, opts: { [string]: any }?): boolean

Create a named GPU sampler. opts: filter/wrap settings.

Parameters

• name string
• opts { [string]: any }? (optional)

modules/compute/createStorageTexture2D

createStorageTexture2D(name: string, opts: { [string]: any }): boolean

Create a 2D storage texture (compute-writable render target). opts: { width, height, format? }.

Parameters

• name string
• opts { [string]: any }

modules/compute/createTexture3D

createTexture3D(name: string, opts: { [string]: any }): boolean

Create a 3D texture volume. opts: { width, height, depth, format?, storage? }.

Parameters

• name string — Unique volume name.
• opts { [string]: any } — Dimensions + format (r8/r16f/r32f/rgba8/rgba16f/rgba32f).

modules/compute/createTextureHistory

createTextureHistory(name: string, opts: { [string]: any }): boolean

Create a temporal history buffer (ping-pong textures) for a target. opts: { width, height, format? }.

Parameters

• name string
• opts { [string]: any }

modules/compute/destroyBuffer

destroyBuffer(name: string): boolean

Release the buffer allocated under name.

Parameters

• name string — The name it was created under.

modules/compute/destroySampler

destroySampler(name: string): boolean

Release a named sampler created by compute.createSampler and free it. The counterpart to that call, alongside destroyBuffer, destroyTexture, destroyTexture3D, destroyStorageTexture2D and destroyTextureHistory. The manager's own defaults (linear_clamp, linear_repeat, nearest_clamp) are kept for the session, since a compute pass binds them by name.

Parameters

• name string — Sampler name.

compute.createSampler("soft", { filter = true }); compute.destroySampler("soft")

modules/compute/destroyShader

destroyShader(name: string): boolean

Destroy a named compute shader pipeline.

Parameters

• name string — Shader name.

modules/compute/destroyShaderEx

destroyShaderEx(name: string): boolean

Destroy a shader registered via registerShaderEx.

Parameters

• name string

modules/compute/destroyStorageTexture2D

destroyStorageTexture2D(name: string): boolean

Destroy a named 2D storage texture.

Parameters

• name string

modules/compute/destroyTexture

destroyTexture(textureKey: string): boolean

Release the cached GPU texture copyBufferToTexture registered under textureKey, freeing its memory. Call it once the image is no longer sampled. Writing the same key again replaces the texture, so a key you keep re-using holds one allocation.

Parameters

• textureKey string — Cache key the texture was registered under.

compute.destroyTexture("lm_wall")

modules/compute/destroyTexture3D

destroyTexture3D(name: string): boolean

Destroy a named 3D volume and free its GPU memory.

Parameters

• name string

modules/compute/destroyTextureHistory

destroyTextureHistory(name: string): boolean

Destroy a named texture-history buffer.

Parameters

• name string

modules/compute/diagnose

diagnose(key: string): { [string]: any }

Whether a resource is filed under key right now, and when none is, which state the inventory says the key is in. A key out of a dispatch failure resolves here; a mistyped one reports why it does not.

Parameters

• key string — The resource key, verbatim.

local d = compute.diagnose(key)
if not d.exists then print(d.reason, d.current) end

modules/compute/dispatch

dispatch(shaderNameOrHandle: string | { [string]: any } | AssetRef, opts: DispatchOpts): boolean

Dispatch a compute shader with bound buffers. Accepts a shader name string or an asset handle from asset.load().

Parameters

• shaderNameOrHandle string | { [string]: any } | AssetRef — Shader name or asset handle.
• opts DispatchOpts — { buffers, workgroups }. A zero in any workgroup dimension is refused and recorded as a dispatch failure — clamp a computed count with math.max(1, math.ceil(n / 64)).

compute.dispatch("blur", { buffers = { "src", "dst" }, workgroups = { 8, 8 } })

modules/compute/dispatchEx

dispatchEx(shaderNameOrHandle: string | { [string]: any } | AssetRef, opts: { [string]: any }): boolean

Dispatch a compute shader with extended texture/storage/sampler bindings. Asset-backed .computeShaders resolve to their stable guid (collision-safe, lazily compiled on first dispatch); raw registerShaderEx names pass through. resources covers the bindings the shader DECLARES. A params: block's uniform is engine-owned — the compile creates and packs it, setParam writes it, and the dispatch binds it — so it takes no entry here.

Parameters

• shaderNameOrHandle string | { [string]: any } | AssetRef — Shader name or asset handle.
• opts { [string]: any } — { resources, workgroups } — each resource is { kind, name }. A zero in any workgroup dimension is refused and recorded as a dispatch failure — clamp a computed count with math.max(1, math.ceil(n / 64)).

modules/compute/dispatchOnVertices

dispatchOnVertices(shaderNameOrHandle: string | { [string]: any } | AssetRef, opts: DispatchOnVerticesOpts): boolean

Dispatch a compute shader with a model's vertex buffer bound at binding 0 (read_write). Use to mutate vertex positions directly. Asset-backed .computeShaders resolve to their stable guid (collision-safe, lazily compiled on first dispatch); raw registerShader names pass through.

Parameters

• shaderNameOrHandle string | { [string]: any } | AssetRef — Shader name or asset handle.
• opts DispatchOnVerticesOpts — { model, buffers?, workgroups }. A zero in any workgroup dimension is refused and recorded as a dispatch failure — clamp a computed count with math.max(1, math.ceil(n / 64)).

compute.dispatchOnVertices("flatten", { model = "@user/mesh", workgroups = { 64 } })

modules/compute/failing

failing(): { { [string]: any } }

Every compute dispatch whose most recent run FAILED, one record per (shader, target) pair. A dispatch is recorded into a command encoder frames after the call that asked for it returned, so a pass that stops running reports here rather than through that call's return value: each record carries the shader key, the target it writes (a mesh guid for a dispatch over vertices, the buffers it bound for one that writes only those), how many dispatches and failures it has had, and lastError. An empty result means every dispatch the engine has been given is running.

for _, d in ipairs(compute.failing()) do print(d.shader, d.lastError) end

modules/compute/finishBvh

finishBvh(id: number): (any, string?)

Hand over a finished build's hierarchy as the same two buffers compute.buildBvh returns, and release the build. The slices put every byte of it on the GPU as they ran, so this costs the frame it is called in the handover and nothing of the scene.

Parameters

• id number — Build id from compute.beginBvh, stepped until "ready".

local built = compute.finishBvh(id)

modules/compute/getReadbackResult

getReadbackResult(resultKey: string): { number }?

Poll for a completed read-back and return its bytes as a 1-indexed array of f32 values, nil if pending. The f32 reinterpretation applies to whatever the buffer holds: bytes written as u32 1, 2, 3, 4 read back here as 1.4e-45, 2.8e-45, 4.2e-45, 5.6e-45 — use getReadbackResultU32() for those, or getReadbackResultBytes() for a buffer the rest of the buffer surface accepts. Result is consumed on retrieval, and polling a key that was never issued raises rather than reading as forever-pending.

Parameters

• resultKey string — Key returned by readBuffer().

local floats = compute.getReadbackResult(key)

modules/compute/getReadbackResultBytes

getReadbackResultBytes(resultKey: string): buffer?

Poll for a completed read-back and get its raw bytes as a buffer, copied once. The read counterpart of writeBufferBytes: read values out with buffer.readf32 / buffer.readu32, or hand the buffer straight to writeBuffer — a payload that stays packed never becomes a table. Result is consumed on retrieval.

Parameters

• resultKey string — Key returned by readBuffer().

local bytes = compute.getReadbackResultBytes(key)
local firstTexel = buffer.readf32(bytes, 0)

modules/compute/getReadbackResultU32

getReadbackResultU32(resultKey: string): { number }?

Poll for a completed read-back interpreting bytes as u32. Returns array of integer values if ready, nil if pending.

Parameters

• resultKey string — Key returned by readBuffer().

modules/compute/isReadbackReady

isReadbackReady(resultKey: string): boolean

Check if a readback result is available without consuming it. Raises for a key this engine never issued, or whose result was already drained — nil/false already means "still in flight", so a mistyped key reports itself instead of polling forever. Use readbackState() to test that case without raising.

Parameters

• resultKey string — Key returned by readBuffer().

modules/compute/markBaseline

markBaseline(): number

Record which compute resources are resident right now, and make that the point compute.resetToBaseline returns to.

A caller that runs work in someone else's engine — a sweep of test suites sharing one, an editor tool driving a session — allocates as it goes: a pass builds the grid its quality asks for and keeps it, a shader files the uniform it was compiled with. Kept is right for a frame that draws again and wrong for the next caller, which then reads an inventory it did not make. This is how a caller says where its own allocations start.

local mark = compute.markBaseline() -- then run, then compute.resetToBaseline(mark)

modules/compute/observe

observe(): { [string]: any }

Every GPU resource the compute subsystem is holding right now — its storage and uniform buffers, its 3D textures, its 2D storage targets, its history pairs and its samplers — with what each one costs and which shader asked for it. This is the call to reach for when compute is holding memory and you do not know what, or when a key out of a dispatch failure needs matching against what exists.

local r = compute.observe()
print(r.totals.count, r.totals.bytes)
for _, res in ipairs(r.resources) do print(res.key, res.kind, res.bytes) end

modules/compute/program.compile

program.compile(key: string, spec: { [string]: any }): (boolean, string?)

Register a compiled program under key from WGSL plus a declared binding schema. The engine generates the @group/@binding declarations from the schema, expands #includes, naga-validates, and registers the result.

Parameters

• key string — The key to register under.
• spec { [string]: any } — { source, entryPoint?, bindings, params, ranges? } — the parsed schema. A buffer binding stating range = true (or every array buffer binding, with ranges = true) takes a range of a buffer: a dispatch binds it with zero_base_NAME / zero_len_NAME in its params, and the body's NAME[i] and arrayLength(&NAME) address that range. One that states no range binds the whole buffer.

modules/compute/program.destroy

program.destroy(key: string): boolean

Release the program registered under key.

Parameters

• key string — The program's key.

modules/compute/program.dispatch

program.dispatch(key: string, opts: { [string]: any }): boolean

Dispatch the program under key with one buffer per declared storage binding, in declaration order.

Parameters

• key string — The program's key.
• opts { [string]: any } — { buffers, workgroups, params? }. params gives values of the program's params: uniform, by name, to this dispatch alone: two dispatches of one program in a frame each read their own, and a value left out reads what the program holds. A zero in any workgroup dimension is refused and recorded as a dispatch failure — clamp a computed count with math.max(1, math.ceil(n / 64)).

modules/compute/program.dispatchEx

program.dispatchEx(key: string, opts: { [string]: any }): boolean

Dispatch the program under key with explicit resources — one { kind, name } per declared binding, in declaration order.

Parameters

• key string — The program's key.
• opts { [string]: any } — { resources, workgroups }. A zero in any workgroup dimension is refused and recorded as a dispatch failure — clamp a computed count with math.max(1, math.ceil(n / 64)).

modules/compute/program.dispatchOnVertices

program.dispatchOnVertices(key: string, opts: { [string]: any }): boolean

Dispatch the program under key over a mesh's vertices. The mesh opts.model names fills the shader's vertices binding, and opts.buffers fills the remaining storage bindings.

Parameters

• key string — The program's key.
• opts { [string]: any } — { model, buffers?, workgroups, params? }. params gives values of the program's params: uniform to this dispatch alone. A zero in any workgroup dimension is refused and recorded as a dispatch failure — clamp a computed count with math.max(1, math.ceil(n / 64)).

modules/compute/program.dispatches

program.dispatches(): number

How many dispatches the running thread has queued since it began, a run of a compute list counting each dispatch the list holds. Two readings taken around a piece of work give what that work dispatched.

modules/compute/program.dropList

program.dropList(key: string): boolean

Forget the compute list under key.

Parameters

• key string — The list's key.

modules/compute/program.forPlugin

program.forPlugin(key: string, bindings: number | { string }): any

The program under key as a handle a script passes a plugin in a call, for it to dispatch over the GPU buffers and textures it was handed. bindings is how many storage buffers the shader binds, or the kind of each binding in declaration order as bindings.yaml spells them (buffer, texture3d, storage3d, storage2d).

Parameters

• key string — The program's key.
• bindings number | { string } — A count of buffers, or each binding's kind.

modules/compute/program.list

program.list(key: string, entries: { { [string]: any } }): boolean

Register the compute list under key, replacing one already there: an ordered run of dispatches and buffer writes that runList queues in one call, each value a run supplies named as a slot.

Parameters

• key string — The key to register the list under.
• entries { { [string]: any } } — The dispatches and writes, in the order they run. A dispatch is { program, buffers, workgroups, params?, slots?, runs?, writes?, when? }, slots mapping a param name to the slot that gives it its value. runs names the runs the dispatch reaches through a page it binds and writes the ones of those it writes: the list holds them standing (a replay over a run that was let go of is refused, not run) and moves the write revision of the ones it writes. A write is { write = bufferName, offset?, values, unsigned?, slots?, when? }: offset in 32-bit words, values written as f32 (u32 when unsigned), slots mapping a value's place, from 1, to the slot that gives it. when names a slot: a run giving it 0 leaves the entry out.

modules/compute/program.listCost

program.listCost(key: string): (number?, number?)

What recording the runs of the compute list under key has cost the render side so far. A run is recorded on a frame after the one that queued it, so a cost read just after runList holds the runs before that one.

Parameters

• key string — The list's key.

modules/compute/program.record

program.record(fn: ({ { [string]: any } }) -> ()): { { [string]: any } }

Run fn and answer every compute.program.dispatch it made, in order, as the entries of a compute list: { program, buffers, workgroups, params } each. The dispatches are queued as they always are; the answer is what compute.program.list takes to replay them. fn is handed the entries as they are made, so it can add slots to one it just dispatched.

Parameters

• fn ({ { [string]: any } }) -> () — The work to run, given the entries recorded so far.

modules/compute/program.runList

program.runList(key: string, slots: { [string]: number }?, label: string?): boolean

Queue the compute list under key: every entry in order, each value an entry names a slot for taken from slots, every other value as the list holds it. While the GPU profiler is read the run is recorded as a compute pass of its own, and its GPU time is the compute.list:<label> row of the gpu report.

Parameters

• key string — The list's key.
• slots { [string]: number }? (optional) — The value of each slot for this run, by name.
• label string? (optional) — The name the run's GPU time is reported under; the list's key when absent.

modules/compute/program.setParam

program.setParam(key: string, prop: string, value: number): boolean

Write one scalar of the program's params: uniform. A value set before the program's first compile is the value it starts with.

Parameters

• key string — The program's key.
• prop string — Parameter name as declared.
• value number — New scalar value.

modules/compute/program.status

program.status(key: string): { { [string]: any } }

What the engine did with the dispatches of the program under key, one record per target.

Parameters

• key string — The program's key.

modules/compute/programState

programState(ref: string | { [string]: any } | AssetRef): (string, string?)

Where a shader's compiled program stands. A registration is queued from script and the pipeline is built on the render side frames later, so the call that asked for the compile cannot say whether it produced a program: "absent" (the engine holds nothing under this key and nothing is in flight — never asked for, or released), "pending" (asked for, not on the device yet — a recompile of a resident program reads pending too, because what it produces is a different program from the one bound now), "ready" (compiled and resident, so a dispatch binds it), or "failed" (the most recent registration produced no program), returned with the reason as a second value. A .computeShader whose bindings.yaml its compile refuses reads "failed", with the reason naming the file and the line, because no program is compiled from the file as it stands. Wait for "ready" before a dispatch whose result is read back, rather than for a count of frames.

Parameters

• ref string | { [string]: any } | AssetRef — A .computeShader identity/guid string, a resolved asset handle, or the name a raw registration chose.

if compute.programState(carve) == "ready" then carve:dispatch(opts) end

modules/compute/readBuffer

readBuffer(name: string): string

Start a GPU→CPU read of the buffer under name.

Parameters

• name string — The name it was created under.

modules/compute/readTexture3D

readTexture3D(name: string): string

Start a GPU→CPU readback of a named 3D volume. Returns a result key to poll.

Parameters

• name string

modules/compute/readbackPromise

readbackPromise(resultKey: string): any

The promise that settles when a read-back reaches a terminal state, delivered or given up on. task.await it to wait for the read without polling: where the engine can wait on the device the coroutine resumes in the frame the device answered, so a task that reads, uses the answer and reads again does all of it in one frame; elsewhere it resumes on the next frame the answer reaches the engine. Answers nil when the read-back is not in flight (already delivered, failed, drained or never issued), and readbackState() then says which.

Parameters

• resultKey string — Key returned by readBuffer().

local promise = compute.readbackPromise(key); if promise then task.await(promise) end

modules/compute/readbackState

readbackState(resultKey: string): string

Where a readback key stands, without consuming it and without raising: "pending" (issued, GPU has not delivered), "ready" (delivered, waiting to be drained), "failed" (given up on, with the reason as a second return), or "unknown" (never issued by readBuffer(), or already drained — a result is delivered once).

Every read leaves "pending": one the GPU does not answer inside the bound the engine holds it to reaches "failed" naming the buffer. A wait on readbackState(key) ~= "pending" therefore ends on what the read did, which a count of engine frames cannot say.

Parameters

• resultKey string — Key returned by readBuffer().

if compute.readbackState(key) == "ready" then ... end

modules/compute/registerShader

registerShader(nameOrHandle: string | { [string]: any } | AssetRef, opts: ShaderOpts?): boolean

Register a compute shader. Accepts an asset handle from asset.load(), or (name, opts) with inline WGSL source.

Parameters

• nameOrHandle string | { [string]: any } | AssetRef — Shader name or asset handle.
• opts ShaderOpts? (optional) — Shader options. bindings comes from the source's own @group(0) @binding(n) declarations when omitted; supplying a count that disagrees with them raises. Every readOnlyBindings entry names one of those declared bindings, as a whole number from 0 to bindings - 1; an entry outside that run raises.

compute.registerShader("blur", { source = WGSL, entryPoint = "main" })

modules/compute/registerShaderEx

registerShaderEx(nameOrHandle: string | { [string]: any } | AssetRef, opts: { [string]: any }?): boolean

Register a compute shader with extended texture/sampler bindings. Accepts a name + opts or an asset handle.

Parameters

• nameOrHandle string | { [string]: any } | AssetRef
• opts { [string]: any }? (optional)

modules/compute/releaseBaseline

releaseBaseline(generation: number): boolean

Drop the mark generation names, and every mark taken after it, once the caller that took it is done resetting to it. It touches the marks alone.

Parameters

• generation number — The mark to drop, as compute.markBaseline returned it.

compute.releaseBaseline(mark) -- the run is over

modules/compute/resetToBaseline

resetToBaseline(generation: number?): number

Release every compute resource allocated since compute.markBaseline, leaving the ones it recorded where they are.

Each kind this closes is one a caller allocated under a name it chose, so the next caller finds that name free. A storage buffer is such a resource and is not closed here: every one a caller can make is a substrate buffer, and substrate.resetToBaseline is what puts those back. A compiled shader's params uniform is not, and is left where it is: it is filed under its shader's guid, which no other caller can ask for, and it belongs to the .computeShader asset that compiled it, released when that is. mark is closed; nothing the mark recorded is touched.

Parameters

• generation number? (optional) — The mark to restore to, as compute.markBaseline returned it; the newest mark when omitted. The marks taken after it go with the reset.

local released = compute.resetToBaseline(mark)

modules/compute/resources

resources(owner: any?): { any }

The resource rows on their own, optionally narrowed to what one shader owns.

Parameters

• owner any? (optional) — A .computeShader ref, its guid, or its asset identity. Omit for every resource compute holds. A value carrying no shader raises, so a narrowing that cannot be done reads as an error rather than as the whole inventory. A guid stands for itself, so resources outlive the asset that made them and stay reachable by their owner.

for _, r in ipairs(compute.resources(shaderRef)) do print(r.key, r.bytes) end

modules/compute/setParam

setParam(nameOrHandle: string | { [string]: any } | AssetRef, prop: string, value: number): boolean

Set a named scalar parameter on a .computeShader (a params: entry in its bindings.yaml). Updates the shader's params uniform in place; the next dispatch sees the new value. No effect on raw registerShader shaders, which have no params block.

Parameters

• nameOrHandle string | { [string]: any } | AssetRef — Shader identity (the .computeShader asset name), or the handle asset.load / asset.resolve returns — the same forms dispatch takes.
• prop string — Parameter name as declared in bindings.yaml.
• value number — New scalar value (numbers only).

compute.setParam("my_sim", "scale", 4.0)

modules/compute/stepBvh

stepBvh(id: number, budgetMs: number?): (string?, string?)

Advance a build by as many work units as budgetMs buys, and report whether it has finished: "pending" means there is work left, "ready" means compute.finishBvh will hand over the buffers. The slices carry the hierarchy onto the GPU as well as building it, so a build that reads "ready" has already uploaded every byte of itself. A slice always runs at least one unit, so a budget of 0 advances the build by exactly one and the largest single unit sets the floor under a slice.

Parameters

• id number — Build id from compute.beginBvh.
• budgetMs number? (optional) — Wall time this slice may spend, in milliseconds (default 4).

while compute.stepBvh(id, 4) == "pending" do task.wait() end

modules/compute/textureForPlugin

textureForPlugin(name: string): any

The texture this script created under name as a handle a script passes a plugin in a call. The handle holds the texture by an id of its own, never by the name: once the texture is destroyed the handle refuses, even when the name is made again. Only a texture made by compute.createTexture3D or compute.createStorageTexture2D can be handed over.

Parameters

• name string — The texture's name.

modules/compute/textureFormatBytes

textureFormatBytes(format: string): number

Bytes-per-voxel for a texture format string (rgba16f, r8, ...).

Parameters

• format string

modules/compute/writeBuffer

writeBuffer(name: string, values: { number } | buffer | string, offset: number?): boolean

Write words into the buffer under name.

Parameters

• name string — The name it was created under.
• values { number } | buffer | string — The floats to write, or a buffer / binary string already holding them.
• offset number? (optional) — 32-bit word offset to write at.

modules/compute/writeBufferBytes

writeBufferBytes(name: string, bytes: buffer | string, offsetBytes: number?): boolean

Write packed bytes into the buffer under name.

Parameters

• name string — The name it was created under.
• bytes buffer | string — The payload.
• offsetBytes number? (optional) — Byte offset to write at.

modules/compute/writeBufferU32

writeBufferU32(name: string, values: { number } | buffer | string, offsetBytes: number?): boolean

Write 32-bit words into the buffer under name.

Parameters

• name string — The name it was created under.
• values { number } | buffer | string — The words to write.
• offsetBytes number? (optional) — Byte offset to write at.

modules/compute/writeFloatsTexture3D

writeFloatsTexture3D(name: string, floats: { number }, formatOrOpts: (string | { [string]: any })?): boolean

Upload float values into a named 3D volume, packed via the given format (default rgba16f).

Parameters

• name string
• floats { number }
• formatOrOpts (string | { [string]: any })? (optional)

modules/compute/writeTexture3D

writeTexture3D(name: string, data: buffer | string | { number }): boolean

Upload raw bytes (u8) into a named 3D volume. A buffer or a binary string holds the volume's byte layout verbatim and crosses in one copy — the shape a file's voxel payload arrives in; an array carries one byte value (0..255) per entry.

Parameters

• name string — Volume name.
• data buffer | string | { number } — Voxel bytes as a buffer, a binary string, or an array of bytes.

modules/compute_abi/README

require("@builtin::modules.compute_abi") -- compute_abi

The kernel ABI of a .computeShader: the bindings.yaml extensions (columns bindings, output count / capacity / append with a live counter, specialize compile-time parameters, determinism), lowered to the plain bindings and WGSL the engine compiles, and the host side that allocates outputs, packs column tables and dispatches a variant.

Usage: local compute_abi = require("@builtin::modules.compute_abi")

modules/compute_abi/accessorLines

accessorLines(name: string, element: string, lanes: number?, writable: boolean): { string }?

The lines lower generates for one buffer binding: its length, its read and, when it is written, its write.

Parameters

• name string — The binding's name.
• element string — The element type as the schema states it after specialization (vec3<f32>).
• lanes number? (optional) — How many scalars the element holds.
• writable boolean — Whether the binding is written.

local lines = abi.accessorLines("src", "vec3<f32>", 3, false)

modules/compute_abi/allocationCount

allocationCount(): number

How many device buffers this module has made (a table of columns, an output, a live counter) since the module state began; the buffers a kernel dispatch allocates are in it.

local before = abi.allocationCount()

modules/compute_abi/buffer

buffer(self: any): any

The GPU buffer holding the table.

Parameters

• self any (optional)

modules/compute_abi/compile

compile(baseKey: string, lowered: { [string]: any }, label: string?): string

Compile a lowered variant under <baseKey>#<hash of what it lowered to>; one variant compiles once.

Parameters

• baseKey string — The shader's registration key.
• lowered { [string]: any } — A value from lower.
• label string? (optional) — The name profiling rows carry.

local key = abi.compile(guid, lowered, "kernels.map")

modules/compute_abi/compileCount

compileCount(): number

How many variants compile has registered since the module state began: a count that grows while the same work repeats says the work asks for a program of its own each time.

local before = abi.compileCount()

modules/compute_abi/compiledSince

compiledSince(since: number): { { label: string, key: string } }

What compile registered after the count stood at since (compileCount), oldest first, for the latest 4096 compiles: each variant's label and the key it is dispatched under (loweredOf(key) reads what it lowered to).

Parameters

• since number — A count compileCount answered.

local before = abi.compileCount(); work(); for _, c in ipairs(abi.compiledSince(before)) do print(c.label) end

modules/compute_abi/copyWords

copyWords(src: string, dst: string, words: number, first: number?): boolean

Queue a word-for-word copy of the first words words of the buffer src into the buffer dst, from word first on.

Parameters

• src string — The source buffer's name.
• dst string — The destination buffer's name.
• words number — How many words.
• first number? (optional) — The word of dst the first one lands at. Default 0.

abi.copyWords(a:bufferName(), b:bufferName(), 64)

modules/compute_abi/directLimit

directLimit(schema: { [string]: any }, binding: string): number

How many columns of the columns binding binding a variant can bind directly, each as a binding of its own run: the storage buffers a shader stage holds on every device, less the buffers the schema's other bindings take and the binding's own table.

Parameters

• schema { [string]: any } — A parsed schema.
• binding string — The name of a columns binding that reads.

local limit = abi.directLimit(schema, "cols")

modules/compute_abi/directLimitOf

directLimitOf(program: any, binding: string): number

Program.directLimit for a program made by an earlier load of this module.

Parameters

• program any (optional) — A program from abi.program.
• binding string — The name of a columns binding that reads.

local limit = abi.directLimitOf(program, "cols")

modules/compute_abi/directPlan

directPlan(columns: { { [string]: any } }, limit: number): { number }

The column slots, in increasing order, that a table of columns takes as direct columns: the first limit columns that name a device buffer and hold no values of their own. A dispatch binds each buffer at one slot, so a column whose buffer an earlier direct column holds stays in the table.

Parameters

• columns { { [string]: any } } — The array abi.table is given.
• limit number — How many direct columns the variant can bind (abi.directLimit).

local direct = abi.directPlan(columns, abi.directLimit(schema, "cols"))

modules/compute_abi/directs

directs(self: any): { slots: { number }, buffers: { string } }

The column slots the table binds as direct columns, and the names of the buffers they are read from, in the order a variant binds them.

Parameters

• self any (optional)

modules/compute_abi/evaluate

evaluate(text: string, vars: { [string]: number }, lengths: (string) -> number): number

Evaluate a count / capacity expression.

Parameters

• text string — The expression.
• vars { [string]: number } — The names it may use, with their values.
• lengths (string) -> number — len(binding): the element count of a bound run.

abi.evaluate("n * 4", { n = 10 }, function() return 0 end) --> 40

modules/compute_abi/fingerprint

fingerprint(text: string): string

A fingerprint of a text, the one lowered variants and fused kernels are keyed by.

Parameters

• text string — Any text.

local tag = abi.fingerprint(source)

modules/compute_abi/forget

forget()

Forget every compiled variant, so the next compile of each registers it again; for a device that was rebuilt.

modules/compute_abi/isExtended

isExtended(schema: { [string]: any }): boolean

Whether a schema uses any extension, which is what makes a shader lowered rather than compiled as written.

Parameters

• schema { [string]: any } — A parsed schema.

if abi.isExtended(schema) then ... end

modules/compute_abi/lower

lower(schema: { [string]: any }, wgsl: string, spec: { [string]: any }?): { [string]: any }

Lower a shader's extensions to the bindings and WGSL the engine compiles.

Parameters

• schema { [string]: any } — A parsed schema.
• wgsl string — The shader body, with its #include literals already canonicalized.
• spec { [string]: any }? (optional) — { specialize = { NAME = value }, columns = { [binding] = { names } }, direct = { [binding] = { slot } } }. direct names, per read columns binding, the column slots read from a binding of their own run (NAME_d0, NAME_d1, ... after the table), so those columns are not copied into the table.

local lowered = abi.lower(schema, wgsl, { specialize = { T = "vec3<f32>" } })

modules/compute_abi/loweredOf

loweredOf(key: string): { [string]: any }?

What compile lowered the program under key from: { lowered, label, base }, the lowered value lower answered (its source, bindings, params, slots, workgroup and fusion). Nil for a key this module did not compile, or one compiled before the device was rebuilt.

Parameters

• key string — A key compile answered.

local made = abi.loweredOf(entry.program)

modules/compute_abi/names

names(self: any): { string }

The names of the table's columns, in slot order.

Parameters

• self any (optional)

modules/compute_abi/noteWrite

noteWrite(name: string, method: string, payload: any, offset: number?)

Tell whoever is recording that the host wrote payload into the device buffer name.

Parameters

• name string — The buffer's name.
• method string — write (words as f32, offset in words), writeU32 or writeBytes (offset in bytes).
• payload any (optional) — What was handed to the buffer's method.
• offset number? (optional) — The method's offset argument.

abi.noteWrite(handle.name, "writeU32", { 0 })

modules/compute_abi/observeWrites

observeWrites(fn: (any) -> ()): () -> ()

Hear the writes the host makes into device buffers: fn(entry) is called with each write as a compute list entry. Every call returns a function that stops listening.

Parameters

• fn (any) -> () — Called with { write = bufferName, offset = words?, values, unsigned? }.

Returns () — The function that stops listening.

local stop = abi.observeWrites(function(entry) entries[#entries + 1] = entry end)

modules/compute_abi/pageBinding

pageBinding(lowered: { [string]: any }, runs: { [string]: any }): { [string]: any }

What a dispatch of a lowered kernel with page and column bindings binds: the arena page each page binding names and the base and length of each column's run in it.

runs maps each column name to a buffer handle or name. A column's run stands in one arena page (substrate.placement); every column the kernel declares in one page binding must stand in one page, and a column outside an arena page (a buffer of its own) is a page of one column. A column in another page than the rest of its binding, or a page two bindings name, raises naming both: the kernel is lowered for the partition of columns it was given, and a partition that differs is a different kernel.

Parameters

• lowered { [string]: any } — A value from lower.
• runs { [string]: any } — { [column] = handle | name }.

local bound = abi.pageBinding(lowered, { pos = positions, vel = velocities })

modules/compute_abi/pageEntry

pageEntry(key: string, lowered: { [string]: any }, runs: { [string]: any }, opts: { [string]: any }): { [string]: any }

The entry of a compute list (compute.program.list) that dispatches a page-bound kernel over runs: the program, the pages it binds, the base and length of each column, and the runs it reaches through those pages, with the ones its column declarations write. A list holding the entry keeps those runs standing and moves the write revision of the ones the kernel writes, so a replay never runs over a run that was let go of, and what reads a written run sees it changed.

Parameters

• key string — The key compile answered for the kernel.
• lowered { [string]: any } — A value from lower.
• runs { [string]: any } — { [column] = handle | name }.
• opts { [string]: any } — { workgroups, params?, buffers?, slots?, when? } — params are the kernel's own, buffers names the buffer of each non-page binding, slots and when are a list entry's.

compute.program.list("step", { abi.pageEntry(key, lowered, runs, { workgroups = { 1, 1, 1 } }) })

modules/compute_abi/parse

parse(content: string, file: string?): { [string]: any }

Parse bindings.yaml into { bindings, params, specialize, determinism, workgroup }. A binding without a kind is a buffer. Every YAML list form reads: flow mappings, block mappings and flow lists. Raises, naming file, on text the YAML decoder refuses (with the line) and on a list key holding anything but a list of mappings (with the key).

Parameters

• content string — The text of bindings.yaml.
• file string? (optional) — The file named in an error; bindings.yaml when omitted.

local schema = abi.parse(vfs.read(path .. "/bindings.yaml"), path .. "/bindings.yaml")

modules/compute_abi/program

program(def: { [string]: any }): any

A shader's ABI, ready to specialize and dispatch.

Parameters

• def { [string]: any } — { key, label?, schema, wgsl, canonicalize? }: the registration key, the parsed schema, the shader body, and a function that resolves the #include literals of the lowered source.

local program = abi.program({ key = guid, schema = schema, wgsl = wgsl })

modules/compute_abi/read

read(handle: any, asU32: boolean?): { number }?

Read a buffer's words back, waiting for the frames the read takes.

Parameters

• handle any (optional) — A buffer handle created with usage = { "readback" }.
• asU32 boolean? (optional) — Answer the words as u32 (default f32).

local values = abi.read(out.buffer)

modules/compute_abi/release

release(baseKey: string): number

Release every variant compile registered under baseKey, and the program program made for it: each variant's compiled program and params uniform are destroyed, and the next compile of one registers it again. The teardown of a shader whose asset is gone.

Parameters

• baseKey string — The shader's registration key.

local released = abi.release(guid)

modules/compute_abi/repack

repack(self: any)

Copy the device buffers the table was packed from into it again, where they stand now: what a rewrite of those buffers in place leaves the table to read. The numbers it was given on the CPU stay as written.

Parameters

• self any (optional)

cols:repack()

modules/compute_abi/run

run(self: any, env: { [string]: any }): { [string]: any }

Dispatch the variant over env.n elements.

Parameters

• self any (optional)
• env { [string]: any } — { n, inputs = { [binding] = buffer | name | table }, outputs?, params?, values?, class?, owner? }: n is the element count; params sets the shader's own params; values adds names to count expressions; class ("effect" or "persistent") makes every buffer the run allocates a run of the device arenas, held for owner (substrate.createBuffer). Outputs with count or capacity are allocated here, except those outputs names: outputs[binding] is a buffer (or { buffer, count?, capacity?, counter? }) the dispatch writes in place, and an appended output given one needs its counter, whose count the dispatch keeps appending to. The first run of a variant waits for its program to be built, so a read of an output asked for after the run sees what the dispatch wrote.

local r = variant:run({ n = 10, inputs = { src = src } })

modules/compute_abi/slot

slot(self: any, name: string): number

The slot a named column holds.

Parameters

• self any (optional)
• name string

modules/compute_abi/specKey

specKey(spec: { [string]: any }?): string

The variant for a specialization: lowered and compiled once.

Parameters

• spec { [string]: any }? (optional) — { specialize = { NAME = value }, columns = { [binding] = { names } }, direct = { [binding] = { slot } } }.

local v = program:variant({ specialize = { T = "vec3<f32>" } })

modules/compute_abi/table

table(columns: { { [string]: any } }, opts: { [string]: any }?): any

Pack columns into one buffer a columns binding reads.

Parameters

• columns { { [string]: any } } — An array of { name, kind = "f32" | "i32" | "u32", lanes?, count, values? | buffer? }. values are numbers a column holds, element after element (lanes contiguous); buffer is a GPU buffer whose words are copied in on the device.
• opts { [string]: any }? (optional) — { name = string, direct = { slot }, class?, owner? }: the name the buffer is created under, and the 0-based slots of the columns a variant binds as direct columns (abi.directPlan). A direct column is not copied: its buffer is bound beside the table, and the table holds its header alone. class ("effect" or "persistent") makes the table a run of the device arenas, held for owner (substrate.createBuffer), which the substrate names in place of name.

local t = abi.table({ { name = "a", kind = "f32", count = 4, values = { 1, 2, 3, 4 } } }, { name = "cols" })

modules/compute_abi/wordCopyOf

wordCopyOf(entry: any): (string?, string?)

The source and destination of a recorded dispatch that is a copyWords from word 0: the copy of the first words words of src into the same words of dst. Nil for any other entry.

Parameters

• entry any (optional) — An entry of a recorded list.

local src, dst = abi.wordCopyOf(entry)

modules/connected_users/README

require("@builtin::modules.connected_users") -- connected_users

world.connectedUsers.* — server-replicated user registry. This module is user-scope and user-editable. The file you're reading is /zero/source/libs/@builtin/modules/connected_users.module/init.luau — anyone (any script, any agent, any user with VFS write) can rewrite it; hot-reload picks the change up and the engine uses the new version. There is no security boundary here. The read-only metatable below catches accidental writes loudly (API hygiene); it doesn't enforce anything. Trust boundaries that DO exist: - The Rust FFI (__connected_users.local_identity()) is registered into the VM state by the engine at boot and cannot be replaced from Luau. When it's called, it returns the real JWT sub. - The trusted VM (src/lua/trusted/**) is a separate Luau state, not on the user-writable VFS root, holds the auth.* namespace. User-scope Luau cannot reach it. - The server verifies the JWT on every RPC. Anything the server gates on flows through that check, not through whatever this module reports. What IS load-bearing: - __connected_users.local_identity() (Rust FFI) cannot be replaced. It always returns the real JWT sub of the engine's UserCredential, or nil for anonymous sessions. - The JWT bytes and session token NEVER cross any FFI exposed here; only the extracted identity string does. A malicious user-scope script can lie about identity but cannot exfiltrate the bearer token. - Authority on the server is established by the JWT the SDK presents on every request, not by anything this module reports. Multi-user replication plugs in on top of the same User metatable shape: the registry holds one record per person the published presence roster names (__presence.roster()), each carrying the engines they're connected through and the agents working for them (__presence.revision() gates the resync, so a re-send that changed nothing costs nothing). The local person always has a record — the roster view this engine reads folds it in even before any frame has arrived.

Usage: local connected_users = require("@builtin::modules.connected_users")

modules/contactShadows/README

require("@builtin::systems.contactShadows.contactShadows") -- contactShadows

Short screen-space shadow traces that supply the small-scale contact a shadow map cannot resolve — the grounding under a chair leg, a prop on a table, anything whose contact is finer than one shadow texel.

Usage: local contactShadows = require("@builtin::systems.contactShadows.contactShadows")

modules/contactShadows/active

active(): boolean

Whether the contact-shadow pass is running this frame.

if contactShadows.active() then ... end

modules/contactShadows/clear

clear()

Turn contact shadows off and release the pass. The other settings are kept, so a later set({ strength = ... }) brings back the same look.

contactShadows.clear()

modules/contactShadows/get

get(): ContactState

The contact-shadow settings currently in force.

local l = contactShadows.get().length

modules/contactShadows/lights

lights(): { ContactLight }

The point, spot and distant lights the last refresh packed for the trace pass, ranked by what each is worth at the main camera.

local n = #contactShadows.lights()

modules/contactShadows/lightsBuffer

lightsBuffer(): any?

The light buffer the trace pass reads — one row per light the scene's contact traces reach toward, packed by the last refresh.

local l = contactShadows.lightsBuffer()

modules/contactShadows/paramsBuffer

paramsBuffer(): any?

The buffer this system's passes read. The render feature binds what this hands it, so the pass has the values this module packed.

local p = contactShadows.paramsBuffer()

modules/contactShadows/refresh

refresh()

Re-read the scene's lights and re-push what the trace pass reads: the sun's direction and weight, and the lights supplying contact of their own. The render feature calls this every frame, so the traces follow lights that move, brighten or are spawned while the scene runs.

contactShadows.refresh()

modules/contactShadows/set

set(opts: ContactOpts?): ContactState

Set the scene's contact shadows. Any omitted field keeps its current value. A strength of 0 turns them off and releases the pass.

Parameters

• opts ContactOpts? (optional) — Contact-shadow settings — see ContactOpts.

contactShadows.set({ strength = 0.9, length = 0.35, steps = 16 })

modules/data_contract/README

require("@builtin::modules.data_contract") -- data_contract

The dataContract field-constraint validator: a constrained value must be a .data instance whose dataType contract chain includes constraint.contract. Registers itself with the generic field_constraints registry on load.

Usage: local data_contract = require("@builtin::modules.data_contract")

modules/debanding/README

require("@builtin::systems.debanding.debanding") -- debanding

Gradient debanding. Rebuilds a shallow ramp that eight-bit storage flattened into shelves, so a sky or a light falloff reads as continuous instead of as a stack of contour lines.

Usage: local debanding = require("@builtin::systems.debanding.debanding")

modules/debanding/active

active(): boolean

Whether the debanding pass is running this frame.

if debanding.active() then ... end

modules/debanding/disable

disable()

Turn debanding off and release the pass.

debanding.disable()

modules/debanding/enable

enable(strength: number?): State

Turn debanding on at a given strength.

Parameters

• strength number? (optional) — Strength in [0, 1]. Omit to keep the current value.

debanding.enable()

modules/debanding/get

get(): State

The debanding settings currently in force.

local s = debanding.get().threshold

modules/debanding/paramsBuffer

paramsBuffer(): any?

The buffer this system's passes read. The render feature binds what this hands it, so the pass has the values this module packed.

local p = debanding.paramsBuffer()

modules/debanding/set

set(opts: DebandOpts?): State

Set the debanding settings. Any omitted field keeps its current value.

Parameters

• opts DebandOpts? (optional) — Debanding settings — see DebandOpts.

debanding.set({ threshold = 3, radius = 16 })

modules/debugger/README

require("@builtin::modules.api.engine.debugger") -- debugger (also available as global 'debugger')

Luau debugger — breakpoints, stepping, stack inspection, watches. Public Luau surface over the __debugger Internal FFI namespace.

Usage: local debugger = require("@builtin::modules.api.engine.debugger") Also available as global: debugger

modules/debugger/__diagnostics

__diagnostics(): DebuggerDiagnostics

Internal diagnostic counters for debugging the debugger itself: { installs, debugbreakHits }.

modules/debugger/addWatch

addWatch(expr: string): number

Register an expression to re-evaluate on every pause.

Parameters

• expr string — Luau expression.

modules/debugger/continue_

continue_(): boolean

Resume the paused thread. The thread resumes on the next scheduler tick. A task's thread settles like any resumed task: a wait it reaches is armed, what it returns is its result, and an error it raises is the task's error, reported the way every task error is. A task cancelled while paused does not run on. A coroutine a task resumed itself runs on with nothing waiting for it, and an error it raises is logged.

modules/debugger/disableAll

disableAll()

Disable every registered breakpoint. Records persist; bytecode BREAK ops are cleared.

modules/debugger/disconnect

disconnect(handle: number): boolean

Disconnect an onBreak or onResume callback.

Parameters

• handle number — Handle returned by onBreak/onResume.

modules/debugger/enableAll

enableAll()

Enable every registered breakpoint and re-install them in the VM bytecode.

modules/debugger/evaluate

evaluate(expr: string, frame: number?): (string?, string?)

Evaluate an expression against the paused frame's environment. Returns (value, error).

Parameters

• expr string — Luau expression.
• frame number? (optional) — 1-based frame index (default 1).

modules/debugger/getLocals

getLocals(frame: number?): { [string]: string }

Locals captured at the active pause for the given frame index (1 = top). Values are stringified for safe display.

Parameters

• frame number? (optional) — 1-based frame index (default 1).

modules/debugger/getPauseInfo

getPauseInfo(): PauseInfo?

Info about the active pause, or nil if nothing is paused.

modules/debugger/getStack

getStack(): { Frame }

Captured stack from the active pause, top frame first. Empty when nothing is paused.

modules/debugger/getUpvalues

getUpvalues(frame: number?): { [string]: string }

Upvalues captured at the active pause for the given frame.

Parameters

• frame number? (optional) — 1-based frame index.

modules/debugger/getWatchValue

getWatchValue(id: number): (string?, string?)

Re-evaluate the watch expression against the paused frame's environment and return (value, error).

Parameters

• id number — Watch id.

modules/debugger/getWatches

getWatches(): { Watch }

Snapshot of all watches with their last evaluated value and error, sorted by id.

modules/debugger/isPauseOnError

isPauseOnError(): boolean

Current pause-on-error toggle state for this VM.

modules/debugger/isPaused

isPaused(): boolean

Whether the debugger currently has a paused thread.

modules/debugger/listBreakpoints

listBreakpoints(): { Breakpoint }

Snapshot of every registered breakpoint, sorted by id ascending. Each entry reports whether it is installed: chunkNames lists the loaded chunks carrying it, and pendingReason says why an empty list is empty.

modules/debugger/onBreak

onBreak(fn: (PauseInfo) -> ()): number

Register a callback invoked on every pause with { path, line, reason }. Returns a handle usable with debugger.disconnect.

Parameters

• fn (PauseInfo) -> () — Callback.

modules/debugger/onResume

onResume(fn: () -> ()): number

Register a callback invoked when the paused thread is resumed.

Parameters

• fn () -> () — Callback.

modules/debugger/removeBreakpoint

removeBreakpoint(id: number): boolean

Remove the breakpoint with the given id.

Parameters

• id number — Breakpoint id returned by setBreakpoint.

modules/debugger/removeWatch

removeWatch(id: number): boolean

Remove the watch with the given id.

Parameters

• id number — Watch id.

modules/debugger/setBreakpoint

setBreakpoint(path: string, line: number, opts: BreakpointOpts?): Breakpoint

Set a breakpoint at line in the script path names — its VFS path, its require identity, or the chunk name it loaded under. An installed breakpoint carries resolvedLine and lists the loaded chunks holding it in chunkNames; one whose script is not loaded carries pendingReason, an empty chunkNames, and installs itself when that script loads.

Parameters

• path string — VFS path, require identity, or chunk name.
• line number — 1-based source line.
• opts BreakpointOpts? (optional) — { condition?, logMessage?, hitCount?, notify?, enabled? }. notify makes it a TRACEPOINT: the hit fires onBreak handlers against the frame it stopped in — getStack, getLocals, getUpvalues and evaluate all answer for that frame — and then runs on, instead of holding the thread until something resumes it. That is how code observes a moment without stopping it; halting is for a person at a keyboard. A breakpoint on any line drops the enclosing function out of native code until its chunk reloads, so one left armed on a per-frame function costs more than it reports.

local bp = debugger.setBreakpoint("/zero/source/main.luau", 42)
print(bp.pendingReason or ("installed in " .. bp.chunkNames[1]))

modules/debugger/setPauseOnError

setPauseOnError(enabled: boolean)

When true, uncaught Luau errors fire the onBreak callback (observation only — the error still propagates).

Parameters

• enabled boolean — Toggle state.

modules/debugger/stepInto

stepInto(): boolean

Run until the next line, descending into any function call.

modules/debugger/stepOut

stepOut(): boolean

Run until the current frame returns; pauses in the caller.

modules/debugger/stepOver

stepOver(): boolean

Run until the next line in the current frame. Calls inside the current line are skipped.

modules/debugger/toggleBreakpoint

toggleBreakpoint(path: string, line: number): Breakpoint?

Toggle a breakpoint at the given line: removes if present, adds otherwise.

Parameters

• path string — VFS path, require identity, or chunk name.
• line number — 1-based line.

modules/denoiser/README

require("@builtin::systems.denoising.denoiser") -- denoiser

Edge-aware denoising a render feature routes a noisy signal through. A feature that shades from a few stochastic samples per pixel writes a result carrying that sampling noise, and the only way to quieten it in the feature itself is to cast more rays. Filtering the result instead buys the same quality far more cheaply, and the filter is the same one for every such feature, so it lives here rather than being rewritten per effect. A filter smooths in two directions. Across the frame it is an à-trous wavelet: successive passes with a doubling tap stride, so a handful of 5x5 passes reach the radius a single wide blur would need hundreds of taps for. Each tap is weighted by how much the surface under it resembles the surface under the centre pixel — its world position from @scene.depth and its normal from @scene.normal — so the smoothing follows geometry and stops at depth and normal discontinuities instead of bleeding an object's occlusion onto the wall behind it. Across time — with temporal set — it first carries the previous frame's estimate forward through @scene.motion, so the standing average holds far more samples than any one frame casts and the feature feeding it can trace fewer rays for the same quietness. A reprojected estimate is admitted only where the surface it was written on is the surface being shaded now, and never for longer than historyFrames. Each filter owns its targets and its compiled passes, keyed by the name it was created with, so two features denoising in the same frame do not interfere.

Usage: local denoiser = require("@builtin::systems.denoising.denoiser")

modules/denoiser/create

create(name: string, opts: DenoiseOpts?): Filter

Create a filter that owns its own targets and passes. name keys those resources, so two features denoising in the same frame each pass their own name and never share state.

Parameters

• name string — Identifies this filter's resources. Unique per feature.
• opts DenoiseOpts? (optional) — Filtering settings — see DenoiseOpts.

local d = denoiser.create("rt_ao", { iterations = 4, worldSigma = 0.5, temporal = true })

modules/denoiser/destroy

destroy(self: Filter)

Release the filter's targets. The filter rebuilds on its next run.

Parameters

• self Filter

filter:destroy()

modules/denoiser/passes

passes(self: Filter): number

Consecutive order slots run occupies, counted from the order it is given, so a caller knows where its own next pass can sit.

Parameters

• self Filter

local apply = 51 + filter:passes()

modules/denoiser/reset

reset(self: Filter)

Drop what the accumulation holds, so the next frame starts from its own samples. Call it at a camera cut, where nothing on screen was on the last frame and no reprojection could find it.

Parameters

• self Filter

filter:reset()

modules/denoiser/run

run(self: Filter, ctx: any, source: string, opts: { phase: string?, order: number? }?): string

Enqueue this filter's passes over source, and answer the guid holding the filtered result. Call it from a render feature's render, passing the same ctx; the result is ready for the phase and order given.

Parameters

• self Filter
• ctx any (optional) — The render context the calling feature received.
• source string — Guid of the texture holding the noisy signal.
• opts { phase: string?, order: number? }? (optional) — { phase, order } — where the filter's passes run. order is the first of passes() consecutive slots.

local clean = filter:run(ctx, noisy.guid, { phase = "afterLighting", order = 55 })

modules/denoiser/stats

stats(self: Filter): DenoiseStats

What the filter is doing right now — whether it accumulates, whether it holds an accumulation, how many times that has been dropped, and the size its targets are built for.

Parameters

• self Filter

if not filter:stats().warmed then print("first frame of the accumulation") end

modules/deprecatedParticles/README

require("@builtin::deprecated.deprecatedParticles.deprecatedParticles") -- deprecatedParticles

Particle emitters: create one, list the ones that are live — every emitter, or one creator's own — and read what each is simulating and drawing right now: whose it is, how many particles are alive, what it costs on the GPU, and when it is producing nothing, which reason explains it.

Usage: local deprecatedParticles = require("@builtin::deprecated.deprecatedParticles.deprecatedParticles")

modules/deprecatedParticles/create

create(spec: table?): any

Create a GPU particle system from a spec, allocating its buffers and registering it with the auto-update driver. The handle it returns carries :emit, :update, the setters, :observe, and :getCreator.

Parameters

• spec table? (optional) — { maxCount, rate, lifetime, speed, shape, ... } — every field optional, each falling back to the emitter's default. owner and name say whose the emitter is: owner is the key list(owner) matches, so a creator reaches exactly its own emitters after it has lost their handles, and name says which of them this one is. An emitter that states neither is still attributed to the module and line it was created from. optional, each falling back to the emitter's default. A field that names one of a closed set takes a name from it and raises with the whole set otherwise; a key the spec does not define is reported on its own, naming the key that writes what it was written for. man particles.create lists every key the spec defines.

local fire = particles.create({ maxCount = 2000, rate = 100 })
local star = particles.create({ owner = "starfield", name = "shell" })

modules/deprecatedParticles/list

list(filter: (string | ParticleCreatorFilter)?): { any }

Every particle system this VM has created and not destroyed, in creation order — or, given a filter, the ones whose creator matches it. Answered from the emitter registry, so finding an emitter costs nothing per entity in the scene.

Called with nothing it answers with every emitter in the VM, which is what makes it the way to reach one whose creator has lost its handle, and :getCreator() on an entry says whose that one is. A filter narrows it to one creator's own, so a module clears what a previous load of it left behind and leaves every other emitter in the world standing.

Parameters

• filter (string | ParticleCreatorFilter)? (optional) — Optional. A string matches the owner key a creator stated; a table matches every one of owner, name and source that it names.

for _, sys in ipairs(particles.list()) do print(sys:getActiveCount()) end
for _, sys in ipairs(particles.list("starfield")) do sys:destroy() end
local mine = particles.list({ source = debug.info(1, "s") })

modules/deprecatedParticles/observe

observe(system: any?): { [string]: any }

What the engine is simulating and drawing for particles right now. With no argument, every live emitter plus the totals they sum to; with an emitter, that one's reading. An engine holding no emitters answers count = 0 with an empty list, which reads differently from an engine whose emitters are all silent (count > 0, silent = count).

Parameters

• system any? (optional) — Optional particle system handle to read on its own.

local o = particles.observe(); print(o.count, o.alive, o.silent)
local r = particles.observe(fire); print(r.alive, r.bytes.total)

modules/deprecatedParticles/silenceReasons

silenceReasons(): { { reason: string, means: string } }

The closed set of reasons an emitter can be producing nothing, in the order a reading resolves them — nearest cause first — each with what it means. Every observe().reason is one of these.

for _, r in ipairs(particles.silenceReasons()) do print(r.reason, r.means) end

modules/deprecatedParticles/whySilent

whySilent(system: any): (string?, string?)

Why one emitter is producing nothing, from the closed set silenceReasons() enumerates — or nil when it is producing. The second return is the detail line naming what the reason is about.

Parameters

• system any (optional) — The particle system handle to ask about.

local why, detail = particles.whySilent(fire)

modules/deprecation/README

require("@builtin::modules.deprecation") -- deprecation

Whether an asset is deprecated, why, and what replaces it. An asset is deprecated when its own .metadata carries a deprecated marker, when any container holding it at any depth does (a package, a toolbox, a folder asset), or when its asset type does (every instance of that type). The marker is "deprecated": { "reason": "<one line why>", "replacedBy": "<identity of what to use instead>" }. of is the one function that answers it; search surfaces ask indexed, and resolving an asset asks warnOnce, which warns on the next frame.

Usage: local deprecation = require("@builtin::modules.deprecation")

modules/deprecation/describe

describe(subject: string, found: Deprecation): string

The sentence that names a deprecated asset, its reason and what replaces it.

Parameters

• subject string — What the deprecation is of: an identity or a name.
• found Deprecation — The deprecation of answered.

log.warn(deprecation.describe(identity, d))

modules/deprecation/forget

forget()

Forget which assets have warned, which were found clean and what each folder's .metadata was read to state, so the next use of each is read again.

deprecation.forget()

modules/deprecation/indexed

indexed(ref: any, memo: { [string]: any }?): boolean

Whether a search may index and offer an asset: true unless the asset is deprecated. Every search surface asks this before it reads an asset, so a deprecated asset is never read, ranked or listed.

Parameters

• ref any (optional) — An asset handle, identity, guid or path.
• memo { [string]: any }? (optional) — The table shared across one pass, as of takes it. Optional.

if deprecation.indexed(ref, memo) then print(deprecation.of(ref)) end

modules/deprecation/of

of(ref: any, memo: { [string]: any }?, site: string?): Deprecation?

The deprecation an asset stands under, from its own marker, a container's or its asset type's; nil when it is not deprecated. The nearest marker wins: the asset's own, then each enclosing folder outward, then its asset type's.

Parameters

• ref any (optional) — An asset handle, identity, guid or path.
• memo { [string]: any }? (optional) — A table shared across the calls of one pass, so a folder's .metadata is read once for every asset beneath it. Optional.
• site string? (optional) — The source a name given as ref was written in (__asset.callerSite(), read where the call came in): a ~.tail name expands against the root enclosing it and a name its reference table recorded reaches the asset recorded there. Optional.

local d = deprecation.of("@builtin::deprecated.deprecatedParticles.DeprecatedParticleEmitter")

modules/deprecation/settled

settled(): boolean

Whether every use warnOnce queued has been asked about, so each deprecated one among them has warned.

while not deprecation.settled() do task.wait() end

modules/deprecation/warnOnce

warnOnce(ref: any): boolean

Warn that an asset is deprecated, once per session per asset, naming the asset, the reason and the replacement. The use is asked about on the next frame, so the call that named the asset reads nothing beyond the index: a .metadata is read then, once for as long as it stands as it is. An asset found clean is not asked again for a few seconds, so a hot path resolving it pays one lookup.

Parameters

• ref any (optional) — An asset handle.

deprecation.warnOnce(handle)

modules/depthOfField/README

require("@builtin::systems.depthOfField.depthOfField") -- depthOfField

Depth of field from a lens — focus distance, focal length and aperture, so the falloff behaves the way a camera's does.

Usage: local depthOfField = require("@builtin::systems.depthOfField.depthOfField")

modules/depthOfField/active

active(): boolean

Whether the defocus passes are currently running.

if depthOfField.active() then print("shallow") end

modules/depthOfField/clear

clear()

Turn defocus off and release the passes. The lens is kept, so a later set({ fStop = ... }) brings back the same look.

depthOfField.clear()

modules/depthOfField/get

get(): DepthOfFieldState

The lens currently in force.

local f = depthOfField.get().focusDistance

modules/depthOfField/paramsBuffer

paramsBuffer(): any?

The buffer this system's passes read. The render feature binds what this hands it, so the pass has the values this module packed.

local p = depthOfField.paramsBuffer()

modules/depthOfField/set

set(opts: DepthOfFieldOpts?): DepthOfFieldState

Set the lens. Any omitted field keeps its current value, so a call can rack focus without restating the rest. An fStop of 0 turns defocus off and releases the passes.

Parameters

• opts DepthOfFieldOpts? (optional) — Lens settings — see DepthOfFieldOpts.

depthOfField.set({ focusDistance = 8, fStop = 1.8, focalLength = 85 })

modules/discovery/README

require("@builtin::modules.discovery") -- discovery

Content search in this engine: keyword mode over the files each asset type's type.yaml names, semantic mode through ZeroMind over the scope this world can reach. One question, one answer shape, two modes.

search { q, assetType, match, mode, limit } is the question; match applies to keyword mode only. q is a phrase or a list of them and the answer carries one results entry per query, in the order they were asked. searchGuides asks it the way a guides query does: over the documentation types DOC_TYPES names when it names no assetType, and an answer that found nothing names the surface that searches every other kind. Keyword mode reads the files each asset type declares under indexing.data in its type.yaml, for the slot match selects: identity is the identity role, capability is the capability, interface and implementation roles together, any is either and all is both. The query's words are matched against that text, each word counting once for the asset that carries it, and an asset ranks by what the words it carries as words of their own weigh, a word weighing more the fewer of the assets read carry it, then by how many it carries side by side in the query's order, then by how many it carries anywhere in its text. It runs on the files this engine holds, so unpushed content and a private world's own content are in it, and from code that can yield it reads them across frames, giving the frame back every SLICE_MS. Semantic mode is ZeroMind's ranking over what ZeroMind may embed. Say what you need in q, in plain words. The search decides which asset types the words are about and orders what it keeps by how relevant a judge read each hit to be. match does not apply to it, and naming an assetType replaces that decision: only the named types are searched, so a type guessed wrong answers nothing. Name one only when the task fixes the type. The answer names the worlds it covered. Every answer states the scope it ran from — from, the bound world, and the searched worlds — and every hit carries the local form of the asset this engine holds: its path, the identity a call names a tool by, the identity guides reads a guide or an assetType's README by.

Usage: local discovery = require("@builtin::modules.discovery")

modules/discovery/answer

answer(fields: {

Assemble an answer: the mode and match that ran, the scope it ran from, the results by query position, and the status they hold. A refused request ran no mode and names none. An answered semantic search from a private world is promoted to private_world and carries the note saying what was searched; every other status stands as given. An answered semantic search whose narrowed is false ran naming no kind, and carries the note saying the ranking covered every kind ZeroMind holds. An answered search whose results hold no hit at all carries emptyNote, the sentence its surface gives for having found nothing. The notes stand in one note, the private-world sentence first: status names that promotion, so the sentence it reads for opens what the answer carries. A keyword answer states scanned, the most assets one of its queries read, and cut, whether any query's walk stopped at KEYWORD_SCAN_MAX. A library answer ranked over the published library and carries the note saying so, and is not promoted to private_world, since it lists this world's own matches itself; kinds names the kinds the search read, and the note then says it read only those; librarySkipped is the reason a library search could not ask ZeroMind, and adds the note saying the hits are this world's own.

local out = discovery.answer({ mode = "keyword", match = "any", status = "answered", results = results, scope = scope })

modules/discovery/awaitJob

awaitJob(poll: () -> any, budgetMs: number): (any, number)

Poll poll until it reports a terminal status, giving up after budgetMs of wall clock. The budget is measured against the clock, so it means the same span whatever the frame rate is.

Parameters

• poll () -> any — Reads the job's current state.
• budgetMs number — How long to wait, in milliseconds.

local settled, ms = discovery.awaitJob(poll, 15000)

modules/discovery/boundGuid

boundGuid(): string?

The guid of the world this engine is bound to, or nil on an engine bound to none. Every read of the binding in this module goes through it.

local guid = discovery.boundGuid()

modules/discovery/boundWorld

boundWorld(): BoundWorld?

The world this engine is bound to, with whether it is private — which is what decides whether its own content is anything ZeroMind may embed. Reads the visibility through visibility, and holds a world whose visibility cannot be read as private. Nil when no world is bound.

local here = discovery.boundWorld()

modules/discovery/defaultMode

defaultMode(): string

The mode a call runs when it names none: semantic on a live engine, keyword on an offline boot.

local mode = discovery.defaultMode()

modules/discovery/fetch

fetch(

One semantic fetch: the trusted job for one query over worlds, read into { ok, hits, total?, types?, containers?, elapsedMs } or { ok = false, error, reason, elapsedMs }. semantic asks every query through it, so the answer ZeroMind sent is read in one place.

local answer = discovery.fetch("outline", {}, nil, 10, 15000, false)

modules/discovery/forget

forget()

Drop every held text. The next query reads its files again.

discovery.forget()

modules/discovery/guideTypes

guideTypes(): { string }

The types a guides query searches: the ones types() lists that DOC_TYPES names — the documentation this engine holds. In name order.

local names = discovery.guideTypes()

modules/discovery/identityOf

identityOf(hit: Hit): string

The name the surface acting on a tool-family hit takes: a tool's <toolbox>.<tool> identity, which tools.use calls, and a toolbox's name, which a search_tools { toolbox } drill-in lists. A tool the registry does not hold is named by the toolbox its folder sits in and the name of its own .tool folder; a hit this engine does not hold, by its name.

Parameters

• hit Hit — One hit of a search answer.

local identity = discovery.identityOf(hits[1])

modules/discovery/indexing

indexing(typeName: string): { IndexingEntry }?

The indexing recipe a type declares in its type.yaml, as { { role, extractor, files, order } } in declared order, or nil when the type declares none, is deprecated, or does not exist. A deprecated type is not indexed, so none of its instances is read. order is the entry's place in indexing.data, which is what ranks two hits that matched the same number of words.

Parameters

• typeName string — The asset type's name, in any casing ("guide").

local recipe = discovery.indexing("guide")

modules/discovery/installedOrigin

installedOrigin(row: any): SearchedWorld?

One searched entry for an installed row's origin world, or nil when the row names none. why is library for a package, import otherwise. title is read from the row's own record of its origin world's title; a row whose install carried none leaves it nil, so that origin is named by guid alone.

Parameters

• row any (optional) — One world.installedAssets() row.

local entry = discovery.installedOrigin({ origin_world_guid = "...", kind = "material" })

modules/discovery/installedPaths

installedPaths(): { [string]: boolean }

The paths of everything this world carries from ZeroMind, as installedRows lists them: every library, imported asset and dependency a pull wrote. Empty on an engine bound to no world.

local pulled = discovery.installedPaths()

modules/discovery/installedRows

installedRows(): { any }

What this world carries from ZeroMind, as world.installedAssets() lists it: one row per library, imported asset and dependency a pull wrote. Every read of the installed set in this module goes through it. Empty on an engine bound to no world, or when the list cannot be read.

local rows = discovery.installedRows()

modules/discovery/keyword

keyword(

Keyword mode over the assets this engine holds: the assets of the named types, read through each type's recipe for the slot match selects, ranked by what the query's words the asset carried as words of their own weigh together (hand in "hand it over", spawn in "spawns", and not off in "offline"). A word weighs more the fewer of the assets the walk read carry it, so in "roster who is here" the asset saying "roster" ranks above the many saying "who is here". Then by the most of them it carried side by side in the query's order, so a tool saying "hand off" ranks above one saying "hand" and "off" apart, then by how many it carried anywhere in its text, then by the order the type declares the role that matched, then by name. The walk takes this world's own assets first and the library's after them, each the types' assets in turn (the first of each type, then the second of each), and reads at most KEYWORD_SCAN_MAX of them. Called from code that can yield, it gives the frame back every SLICE_MS while it reads.

local hits, corpus, walk = discovery.keyword("outline", { assetType = "guide", match = "any", limit = 5 })

modules/discovery/keywordScope

keywordScope(corpus: Corpus): Scope

The scope a keyword answer names: the bound world, and the worlds whose content the query actually read. It asks ZeroMind nothing.

Parameters

• corpus Corpus — Where the assets a query read came from.

local scope = discovery.keywordScope({ builtin = true, world = false })

modules/discovery/kindParam

kindParam(assetType: string?): string?

The kind a semantic request names for a comma list of type names: each registered type travels as the guid of its .assetType, the identity ZeroMind files it under wherever it was declared, builtin types included. A name no registered type answers to travels as written in lowercase, so ZeroMind names the one it does not know.

Parameters

• assetType string? (optional) — A comma list of type names, or nil.

local kind = discovery.kindParam("guide,module")

modules/discovery/libraryScope

libraryScope(): Scope

The scope a library search names: no world at all. Naming no world is what widens the ranking from the content this engine can see to everything published, because the request carries a world filter only when it has worlds to name. The bound world still travels, so an answer can say where the search was made from.

local scope = discovery.libraryScope()

modules/discovery/newSlice

newSlice(): () -> ()

A function to call between the pieces of a long walk: it yields one frame once SLICE_MS has run since the slice began, and does nothing for a caller that cannot yield. Each walk makes its own.

Returns () — The function to call between pieces.

local between = discovery.newSlice(); for _, ref in ipairs(asset.list("tool")) do between() end

modules/discovery/onlyKinds

onlyKinds<T>(hits: { T }, kinds: { [string]: boolean }, limit: number): { T }

The hits of hits whose kind kinds holds, in their order, at most limit of them.

Parameters

• hits { T } — Hits, each carrying kind.
• kinds { [string]: boolean } — Lowercase kind names to keep.
• limit number — How many to keep.

local kept = discovery.onlyKinds(hits, discovery.DOC_TYPES, 10)

modules/discovery/resolve

resolve(guid: string): LocalForm?

The local form of an asset this world holds, by guid: its path, the identity a call names a tool by, the name a drill-in lists a toolbox by (for a tool, its own toolbox's), whether the registry holds what a tool or toolbox hit names, the identity guides reads a guide or an assetType's README by, and the VFS path of the asset's README when it holds one. Nil when this world holds no asset under that guid.

Parameters

• guid string — The published guid.

local here = discovery.resolve(hit.guid)

modules/discovery/resting

resting(): (number?, string?)

How long the semantic leg is still resting, in seconds, and the failure it is resting after. Nil when it is not resting; the window closes as soon as it has run out.

local seconds, why = discovery.resting()

modules/discovery/scope

scope(): Scope

The worlds a semantic search covers from this engine, and the bound world it runs from. The builtin library is always in reach; this world is in when it is public; the origin world of every installed library and imported asset is in through the public world that published it.

local scope = discovery.scope()

modules/discovery/search

search(req: { [string]: any }): { [string]: any }

Search this engine's content. req is { q, assetType?, match?, mode?, from?, limit?, budgetMs?, within? }: q is a phrase or a list of them, assetType a comma list of type names as types() lists them (a name types() does not list is refused, and the refusal names every type it lists; in semantic mode leave it out unless the task fixes the type, since naming one replaces the search's own choice of types), match (keyword mode only) one of identity / capability / any / all, mode one of keyword / semantic, within a folder path or a list of them that the walk of this engine's own files is held to (the library ranking is not), and from where results may come from: all is everything published (what library = true asks), bound the current world and its installed libraries, with no published-library leg, in either mode. Naming no from keeps a library the request states; stating neither searches everything published in semantic mode and this engine's own files in keyword mode. A name other than those two is refused, and from = "all" with mode = "keyword" is refused, since keyword mode reads this engine's own files. Every answer carries mode, from, status, the bound world, the searched worlds, and one results entry per query; a keyword answer also carries match.

Parameters

• req { [string]: any } — The request table. excerpts asks each hit to carry the passage it was ranked on, which costs the fuller hit payload; documentation searches ask for them already. library ranks over the whole published library instead of the content this engine can see, for a caller looking for something to install rather than something already here, and lists this world's own matches by their words after the library's hits, each marked from = "world"; when ZeroMind cannot be asked, those own matches still answer and the note says why the library was not searched. It is off by default, and mode: keyword refuses it, since keyword mode reads this engine's own files.

local out = discovery.search({ q = "outline", assetType = "guide", mode = "keyword" })
local out = discovery.search({ q = "outline", excerpts = true })

modules/discovery/searchGuides

searchGuides(req: { [string]: any }): { [string]: any }

Search as a guides query asks: search over the documentation types DOC_TYPES names, or over exactly the ones of them req.assetType names. Naming no type, keyword mode walks the types guideTypes() lists, and semantic mode asks ZeroMind over them (semanticKinds) and keeps only those kinds of its hits. An answered search that found nothing carries NO_DOCS_NOTE, saying which kinds it matched against. An assetType naming a type TOOL_TYPES holds is refused with a sentence that points to search_tools, and one naming any other type types() lists with a sentence that points to discovery.search. The answer is search's, in rank order.

Parameters

• req { [string]: any } — { q, assetType?, match?, mode?, from?, limit?, budgetMs?, excerpts? }, as search takes it. A semantic search here carries excerpt on each hit unless excerpts = false says not to: a reader asking the documentation a question is answered by the passage that answered it, not only by what the guide is.

local out = discovery.searchGuides({ q = "outline", mode = "keyword" })

modules/discovery/searchTools

searchTools(req: { [string]: any }): { [string]: any }

Search as a search_tools query asks: search over the types TOOL_TYPES names (tools, toolboxes and workflows), or over exactly the ones of them req.assetType names. Naming no type, keyword mode walks the types toolTypes() lists, and semantic mode asks ZeroMind over them (semanticKinds) and keeps only those kinds of its hits. An assetType naming any other type is refused with a sentence that points to the surface that searches it. The answer is search's, in rank order.

Parameters

• req { [string]: any } — { q, assetType?, match?, mode?, from?, limit?, budgetMs?, library?, within? }, as search takes it.

local out = discovery.searchTools({ q = "orbit the camera", mode = "keyword" })

modules/discovery/semantic

semantic(

Semantic mode: ZeroMind's ranking over scope for the types opts.assetType names (none: the search decides which types the words are about), spelled for the request through kindParam, each hit carrying the local form of the asset when this engine holds it. opts.only names the kinds the answer keeps: the request then names opts.kinds, asks for SEMANTIC_FETCH_MAX hits, and keeps the first limit of those kinds in ZeroMind's order, so a ranking that could not be narrowed on the request is narrowed here. A failure that cost more than EXPENSIVE_FAILURE_MS reached ZeroMind, and opens the rest window resting() reports.

local results, status, err = discovery.semantic({ "outline" }, opts, discovery.scope())

modules/discovery/semanticKinds

semanticKinds(names: { string }): string?

The kind a semantic request names to cover names: the guid of each one's .assetType, as kindParam spells it. A name no registered type answers to is left out. Nil when none of them resolves, which is the request that names no kind and ranks over all of them.

Parameters

• names { string } — Type names, as types() spells them.

local kind = discovery.semanticKinds(discovery.guideTypes())

modules/discovery/shape

shape(answer: { [string]: any }, form: string, query: string?): { [string]: any }

A search answer in the shape a surface hands it on, built where the search ran so every way of collecting it reads the same value. "answer" is the answer itself with each hit's local form named local. "guides" is { kind = "search", query, match_count, matches }, a row per hit: a guide's (assetType guide) or an asset type's (assetType assettype) names the guides { path } identity as path and carries summary, and the excerpt it was ranked on where the search asked for one; any other type's names its assetType, a one-line purpose and the VFS path of its README as vfs_path. Every row of either list form carries guid, installed (whether this world holds it), skill on an agent skill and workflow on a workflow this world holds, p when the search core judged it, and from = "world" on a match found in this world's own content after a library ranking. Every row of every form whose hit the search core ranked carries container_key and system_key, keys into the answer's containers: the container the hit ships in and the highest one above it (a tool's toolbox and the package it ships in), or the world it belongs to; each container entry names the one above it by parent_key. "answer" keeps containers on each query's result; both list forms carry it once, beside the rows. "tools" is { type = "functions", count, functions }, a row per hit naming its assetType (tool, toolbox or workflow), its identity (discovery.identityOf: the tools.use identity of a tool, the drill-in name of a toolbox), its toolbox, a one-line purpose and whether the registry holds what the identity names; a tool row carries tool, the tools.use identity while the registry holds it and empty while it does not. Both list forms carry the answer's mode, match, from, status, world, searched, note, error, retry_in_s, scanned and cut beside the rows, and total, how many the search matched of which the rows are the best, when it answered one query and counted them.

Parameters

• answer { [string]: any } — What search answered.
• form string — "answer", "guides" or "tools".
• query string? (optional) — The query a "guides" answer echoes.

return discovery.shape(discovery.searchGuides({ q = "outline" }), "guides", "outline")

modules/discovery/stats

stats(): { reads: number, bytes: number, visibilityReads: number }

What this module has read and what it is holding. reads is the number of vfs.read calls it has made — a query that reads content it already holds against an unchanged checksum leaves it where it stood. bytes is the asset text held right now, which stays under TEXT_BUDGET_BYTES. visibilityReads is the number of times it has asked ZeroMind for a world's visibility.

local before = discovery.stats().reads

modules/discovery/toolTypes

toolTypes(): { string }

The types a search_tools query searches: the ones types() lists that TOOL_TYPES names, the things an agent runs. In name order.

local names = discovery.toolTypes()

modules/discovery/toolboxKey

toolboxKey(path: string): string?

The name the tool registry carries a toolbox under, for a .tool at path. A toolbox under a library root other than the builtin one is registered scope-qualified (@lib::ns); every other toolbox is registered under its bare name.

Parameters

• path string — The tool's VFS path.

discovery.toolboxKey("/zero/source/libs/@builtin/tools/zm.toolbox/status.tool")

modules/discovery/types

types(): { string }

Every asset type whose type.yaml declares an indexing recipe — the types a search can read, in name order.

for _, name in ipairs(discovery.types()) do print(name) end

modules/discovery/visibility

visibility(guid: string): string?

A world's visibility as ZeroMind reports it, read through the trusted world read and waiting up to VISIBILITY_BUDGET_MS. An answer is held for the guid, so each world is asked once; nil when the engine cannot read it.

Parameters

• guid string — The world's guid.

local visibility = discovery.visibility(world.guid())

modules/discovery/withWorldMatches

withWorldMatches(results: { QueryResult }, own: { { Hit } }): { QueryResult }

A library ranking with this world's own matches listed after it, query by query: own[i] are the hits keyword mode found for results[i] in this world's own content. A hit the library already returned stays where the library put it; every other one is appended in the order keyword mode ranked it, marked from = "world". The library's hits keep the order the search core gave them, and no score is changed or combined.

Parameters

• results { QueryResult } — The library ranking, by query position.
• own { { Hit } } — This world's own matches, by the same positions.

local merged = discovery.withWorldMatches(results, { ownHits })

modules/discovery/worldHere

worldHere(): BoundWorld?

The world this engine is bound to, as the engine itself knows it: its guid and title, and private when a semantic search has already read the world's visibility. Nothing here waits on ZeroMind, which is what lets a keyword answer and a refusal name the world at once. Nil when no world is bound.

local here = discovery.worldHere()

modules/discovery/worldOwn

worldOwn(path: string, installed: { [string]: boolean }): boolean

Whether an asset at path is this world's own content: not the builtin library, not an installed library root (libs/@<name>/), not a dependency a pull brought (/source/deps/), and not at or inside a path installed holds. Those are the content a library ranking already covers; what is left is what this world's authors made here.

Parameters

• path string — The asset's VFS path.
• installed { [string]: boolean } — What installedPaths() answered.

local own = discovery.worldOwn("/source/tools/mine.toolbox/go.tool", discovery.installedPaths())

modules/diverged

modules.diverged() -> { { module: string, reason: string } }

The modules whose running code differs from their source: each one's hot reload failed (its new source did not compile, or its body raised while it ran), so the code it ran before that edit is still running. Each entry names the module by the key it is required under and gives the reason its reload failed. A module leaves the list once it loads cleanly, and each failure also posts an error notice that stands until then.

Returns { { module: string, reason: string } } — One entry per module whose running code differs from its source; empty when every module runs its source

modules/editor.asset_instance_inspector/README

require("@builtin::modules.editor.asset_instance_inspector") -- editor.asset_instance_inspector

The entity inspector's view of an Asset component — an instance of an asset placed in the scene. It says which asset the instance is linked to and how it stands against it: every part the asset composed, whether it is as the asset has it or was edited, removed or added in the scene, and what the edit changed. Each edited part can be reverted to the asset, selected, or the whole instance reverted or unpacked into plain scene entities.

Usage: local editor.asset_instance_inspector = require("@builtin::modules.editor.asset_instance_inspector")

modules/editor.asset_instance_inspector/build

build(ctx: any): { any }

The Asset component's card body on an entity (edui.inspector): the summary badges, the source field as the component's typed, undoable setting, the Overrides and Linked parts lists, and the revert / unpack actions, built from M.sections with ctx.widgets.

Parameters

• ctx any (optional) — The inspector Context of the Asset component on its entity.

modules/editor.asset_instance_inspector/sections

sections(entityId: string, proxy: any): any

The view's sections for one Asset component: a summary of how the instance stands against its asset, its source field, the parts that differ from the asset and the parts that match it, and the actions that revert or unpack it.

Parameters

• entityId string — The entity the component is on.
• proxy any (optional) — The live Asset component.

modules/edui.app/README

require("@builtin::editor.edui.app") -- edui.app

The edui reactive core: an App owns one ui.* screen, maps author closures to ui.* string callback ids, dispatches the broadcast that ui.registerCallbackEnv delivers, and rebuilds the widget tree on state change. This is the layer that lets editor chrome be written with closures (onClick = function() ... end) instead of hand-managed string ids — the footgun the deprecated zui grew three shapes for.

Usage: local edui.app = require("@builtin::editor.edui.app")

modules/edui.app/adoptHandlers

adoptHandlers(self: any, bucket: { [string]: (any) -> () })

Re-register a bucket of handlers collected by collectHandlers into the current build, keeping a cached subtree's callbacks live.

Parameters

• self any (optional)
• bucket { [string]: (any) -> () } — The handler bucket to adopt.

app:adoptHandlers(cached.bucket)

modules/edui.app/cb

cb(self: any, closure: (any) -> (), key: (string | number)?): string

Allocate (or reuse) a callback id bound to closure for this build. Pass a stable key so the id is identical across rebuilds — required for anything the renderer tracks by id (focus, drag, ui.widgetState). Without a key the id is a per-build sequence number (fine for a fire-and-forget button).

Parameters

• self any (optional)
• closure (any) -> () — The handler (data) -> () the id dispatches to.
• key (string | number)? (optional) — Optional stable key (unique within this screen).

props = { onClick = app:cb(function() doThing() end, "save") }

modules/edui.app/cbRaw

cbRaw(self: any, id: string, closure: (any) -> ()): string

Register closure under the EXACT id id, without the screen-name prefix cb adds. For wiring engine-emitted interaction ids that a widget publishes itself (e.g. a dockArea's <panelId>-close), which arrive unprefixed. Re-issue it each build, like cb.

Parameters

• self any (optional)
• id string — The exact callback id the engine will deliver.
• closure (any) -> () — The handler (data) -> ().

app:cbRaw(panelId .. "-close", function() closePanel(panelId) end)

modules/edui.app/collectHandlers

collectHandlers(self: any, fn: () -> any): (any, { [string]: (any) -> () })

Collect every callback registered while fn runs into a named bucket, returned alongside fn's result. A host that CACHES the subtree fn built re-adopts the bucket on later builds (adoptHandlers), so the cached tree's callback ids stay live across rebuilds that skipped it.

Parameters

• self any (optional)
• fn () -> any — The builder to run.

Returns () }) — fn's result, and the bucket of handlers it registered.

local tree, bucket = app:collectHandlers(function() return panel.build() end)

modules/edui.app/current

current(): any

The app whose builder is currently running, or nil outside a build. The edui.* primitive builders read this to register their closures, so authors don't thread the app through every call.

local app = edui.app.current()

modules/edui.app/dispatch

dispatch(self: any, id: string, data: any): boolean

Route a callback id to its closure and schedule a rebuild. This is what the screen's onCallback broadcast calls. Returns true when the id was handled by this app (an id from another surface returns false so a host can keep routing).

Parameters

• self any (optional)
• id string — The callback id the broadcast delivered.
• data any (optional) — The engine event envelope { value, eventType, widgetId, button, mouseX, mouseY }. The handler receives its value: a scalar for onChange (checkbox bool, input string, select value), a { dx, dy, shift, ctrl, alt } table for a canvas onDrag/onScroll, nil for a bare onClick.

function onCallback(id, data) app:dispatch(id, data) end

modules/edui.app/markDirty

markDirty(self: any)

Mark the app dirty and rebuild its tree. Coalesces a rebuild requested WHILE a build is running into a single follow-up build (so a handler that mutates state and a builder that reads it never recurse), and one requested WHILE a dispatch's handler runs into the single rebuild that dispatch performs after the handler returns.

Parameters

• self any (optional)

modules/edui.app/mount

mount(self: any, builderFn: (any) -> any): any

Mount the app: register the broadcast callback env and do the first build. builderFn(app) -> widgetTree is called now and on every rebuild; inside it, app:cb(...) (or the edui.* primitives) wire closures.

Parameters

• self any (optional)
• builderFn (any) -> any — (app) -> widgetTree.

app:mount(function(a) return { type = "vertical", children = { ... } } end)

modules/edui.app/new

new(screenName: string, opts: { [string]: any }?): any

Create an editor app that owns the ui.* screen screenName.

Parameters

• screenName string — Unique screen id (also the callback-id namespace prefix).
• opts { [string]: any }? (optional) — { layer? = <renderLayerMask>, order? = <number>, callbackKey? = <string> }. layer is a render-layer membership mask (e.g. the EditorUI bit) applied via ui.setScreenRenderLayer on first register; omit for the default. order is the screen's Z-ORDER — higher paints on top; a floating surface (the command palette) states one to stand over the dock.

local app = edui.app.new("myPanel", { layer = editorMask })

modules/edui.app/rebuild

rebuild(self: any)

Run the builder and push the resulting tree to the screen. First call registers the screen (+ render layer); later calls update it. Builder errors are logged, never thrown, so one bad build never wedges the editor.

Parameters

• self any (optional)

modules/edui.app/unchanged

unchanged(self: any, sig: string): boolean

Whether the tree this build would produce is the one the app's screen already shows. sig names every piece of state the build reads: an equal signature means the published tree already says it, so the builder returns nil and the App keeps what it published, at O(1) cost however large the tree. The signature belongs to the App that published the tree, so an App with nothing published reports a change and gets a tree to register.

Parameters

• self any (optional)
• sig string — The signature of the state this build reads.

if app:unchanged(buildSignature()) then return nil end

modules/edui.app/unmount

unmount(self: any)

Tear the app down: release the callback env and unregister the screen.

Parameters

• self any (optional)

modules/edui.argForm/README

require("@builtin::editor.edui.widgets.argForm") -- edui.argForm

The typed argument form — a declared argument list becomes a form of REAL controls, and the filled form becomes the typed values a call takes. A person never types a Luau literal: strings get a text field, numbers a numeric field, booleans a checkbox, string-literal unions a chip row, colours a colour swatch, Vec3 three axis fields, and an options table expands one level into typed rows of its own. Only a type outside the model falls back to the literal field. The command palette renders every tool through this; the Inspector renders an asset type's operations through the same form, so any surface that knows a signature can offer it.

Usage: local edui.argForm = require("@builtin::editor.edui.widgets.argForm")

modules/edui.argForm/fieldRows

fieldRows(self: any, path: string, t: string, optional: boolean,

The label + control rows for one argument (or one expanded table field). depth indents expanded option fields under their parent.

modules/edui.argForm/make

make(W: any): any

Bind the form builder to the widgets barrel W. The barrel calls this once; consumers reach the result as edui.argForm.

Parameters

• W any (optional)

modules/edui.argForm/new

new(o: { [string]: any }): any

A new form instance. o.ns (REQUIRED — the id namespace every control keys under), o.typeDefs (the schema's named definitions, { { name, definition } }), o.onSubmit (fired when Enter lands in a text field — the run affordance), o.onChanged (fired after any control writes a value, for hosts that gate rebuilds on an epoch).

Parameters

• o { [string]: any }

modules/edui.argForm/parseSignature

parseSignature(sig: string): { any }

Parse a method signature string — "(self, name: string, opts: T?)" — into the argument list a form renders: { { name, type, optional } }. A leading self is the receiver, not an argument, and is dropped. The arguments are the balanced parenthesised run at the head of the text, so a signature that goes on to declare what the call hands back — "(self, name: string): boolean" — renders the same form as one that stops at the arguments.

Parameters

• sig string — The signature text.

modules/edui.argForm/rows

rows(self: any, args: { any }): { any }

The rows for a whole argument list (each { name, type, optional, description? }), in order.

Parameters

• self any (optional)
• args { any }

modules/edui.argForm/values

values(self: any, args: { any }): (boolean, any, number?)

Assemble the positional values for args from the filled form. Returns (true, values, n) — n the last non-nil position for table.unpack(values, 1, n) — or (false, message).

Parameters

• self any (optional)
• args { any }

modules/edui.cmdPalette/README

require("@builtin::editor.edui.cmdPalette") -- edui.cmdPalette

The command palette — search everything under one keystroke. Ctrl+K (or the topbar's Tools button) opens a floating surface whose one query reaches the scene's entities (select + frame), the registered assets (select — the Inspector shows it), the editor's panels (focus), and the whole tool registry (pick one and its typed argument schema becomes a form, Run executing it in place). A t: / e: / a: / p: prefix narrows to one domain. Every domain reads its live registry, so what exists is findable with no UI work per addition.

Usage: local edui.cmdPalette = require("@builtin::editor.edui.cmdPalette")

modules/edui.cmdPalette/isOpen

isOpen(): boolean

Whether the palette is up. The screen's live visibility is the one answer every scope shares — the menu bar, the entrypoint, and a panel each hold their own copy of this module, and a module-local flag left them disagreeing about whether the palette was open, so a Close click handled by one copy re-showed what another copy had shown.

modules/edui.cmdPalette/mount

mount(layerMask: number?)

Mount the palette (idempotent): its own screen, hidden until toggled.

Parameters

• layerMask number? (optional) — Optional EditorUI render-layer mask (the menu bar passes its own).

modules/edui.cmdPalette/openTool

openTool(name: string)

Open the palette directly at a tool's form — the deep link another surface uses to hand a person a ready-to-fill tool ("run this operation" from an inspector, a docs page, an agent suggestion). Opens the palette if it is closed, then loads name's schema as the form.

Parameters

• name string — The tool's full name, toolbox.tool.

modules/edui.cmdPalette/screenName

screenName(): string

The palette's screen name (capture / element addressing).

modules/edui.cmdPalette/toggle

toggle()

Open / close the palette. Opening starts fresh at the search and puts the caret in it. The decision reads the screen's live visibility, never a module-local flag.

modules/edui.cmdPalette/unmount

unmount()

Tear the palette down.

modules/edui.confirmDialog/README

require("@builtin::editor.edui.confirmDialog") -- edui.confirmDialog

The editor's confirmation dialog: a question over the whole editor with a row of answers. One question shows at a time. Opening another while one is up puts the new one in front, and the earlier one comes back once the new one is answered. An answer's run decides whether its question closes: returning false, why keeps it up with why shown under it, anything else closes it.

Usage: local edui.confirmDialog = require("@builtin::editor.edui.confirmDialog")

modules/edui.confirmDialog/choose

choose(key: string): boolean

Answer the question on screen with the action keyed key — what clicking its button does. The action's run returning false, why keeps the question up showing why; otherwise it closes, and the question it stood in front of comes back.

Parameters

• key string — An action key of the question on screen.

edui.confirmDialog.choose("cancel")

modules/edui.confirmDialog/close

close(key: string?)

Close a question without answering it and run its onClose once: the one keyed key wherever it waits, or the one on screen when key is omitted.

Parameters

• key string? (optional) — The key the question was opened with.

edui.confirmDialog.close("close:code")

modules/edui.confirmDialog/current

current(): string?

The key of the question on screen, or nil while closed or when it was given none.

if edui.confirmDialog.current() == "close:code" then end

modules/edui.confirmDialog/errorText

errorText(): string?

Why the last answer to the question on screen kept it up, or nil.

modules/edui.confirmDialog/isAsking

isAsking(key: string): boolean

Whether a question with key is on screen or waiting behind one.

Parameters

• key string — The key the question was opened with.

modules/edui.confirmDialog/isOpen

isOpen(): boolean

Whether the dialog is on screen.

modules/edui.confirmDialog/mount

mount(layerMask: number?)

Create the dialog's screen (idempotent): hidden until a question is opened. Order 5100, over every dock panel, the bars and the other editor dialogs.

Parameters

• layerMask number? (optional) — The EditorUI render-layer mask; computed when omitted.

modules/edui.confirmDialog/open

open(request: Request)

Ask a question. It goes in front of any question already up, which comes back once this one is answered; a question opened with the key of one already open takes that one's place. Each action is a button, keyed edui_confirmdialog:cd:<action key> for ui.click; dismiss names the action Escape or a click outside runs, and without it the question can only be answered. onClose runs once when the question closes.

Parameters

• request Request — { key?, title, message, actions = { { key, text, primary?, run? } }, dismiss?, onClose? }.

edui.confirmDialog.open{ title = "Delete?", message = "It goes for good.", dismiss = "no", actions = { { key = "yes", text = "Delete", run = del }, { key = "no", text = "Keep" } } }

modules/edui.confirmDialog/screenName

screenName(): string

The dialog's screen name, for captures and element addressing.

modules/edui.confirmDialog/unmount

unmount()

Tear the dialog's screen down, closing every open question.

modules/edui.framework/README

require("@builtin::editor.edui.framework") -- edui.framework

Editor UI framework on the CSS-parity ui.* surface. A small, editor-ONLY toolkit: a reactive app that maps author closures to ui.* callback ids, a dock shell over ui.* native docking, and editor-chrome primitives (panels, trees, toolbars, inspector rows, context menus, drag-and-drop). Gameplay / normal UI authors raw ui.* trees and needs none of this — edui earns its keep only for the editor.

Usage: local edui.framework = require("@builtin::editor.edui.framework")

modules/edui.framework/createApp

createApp(name: string, opts: { [string]: any }?): any

Create + return an editor app that owns the ui.* screen name. Shorthand for edui.app.new. Call app:mount(builderFn) to bring it up.

Parameters

• name string — Unique screen id (also the callback-id namespace).
• opts { [string]: any }? (optional) — { layer? = <renderLayerMask> }.

local a = edui.createApp("myPanel"); a:mount(function(app) return tree end)

modules/edui.framework/current

current(): any

The app whose builder is currently running (nil outside a build). The edui.* primitives read this to register their closures.

modules/edui.inspector.assetSections/README

require("@builtin::editor.edui.inspector.assetSections") -- edui.inspector.assetSections

The generic sections every asset's Inspector shows, in default order: identity (name, type, scope, guid, description), problems (what asset.validate reports, present only when it reports any), tags (removable chips and an add row), move (relocate the asset's folder), settings (the typed, editable settings), preview (the live or still picture) and operations (every ref method the type declares, each a typed argument form run against the asset in place).

Usage: local edui.inspector.assetSections = require("@builtin::editor.edui.inspector.assetSections")

modules/edui.inspector.assetSections/generic

generic(ctx: any, only: { [string]: boolean }?): { any }

The generic sections for the asset ctx inspects, in default order. A section with nothing to show is left out: Move for an asset outside the world's own source tree, Settings for an asset with neither values nor a schema problem, Preview for an asset with no picture, Operations for a type with no ref methods. Operations lists every method but setSettings, and starts collapsed on a type that declares an inspector of its own.

Parameters

• ctx any (optional) — The inspector Context (asset scope).
• only { [string]: boolean }? (optional) — The ids of the sections to build; every one when nil. A section left out is not read at all, so an inline editor that shows Settings alone runs no validation, preview lookup or behavior load.

local sections = AssetSections.generic(ctx)

modules/edui.inspector.assetSections/releaseExcept

releaseExcept(keep: string)

Drop the interaction state (open operation rows, argument forms, the last result, pending tag and move inputs) and the validation problems read for every asset but keep.

Parameters

• keep string — The asset id whose state stays.

AssetSections.releaseExcept(guid)

modules/edui.inspector.parts/README

require("@builtin::editor.edui.inspector.parts") -- edui.inspector.parts

The building blocks a type's inspector.luau composes its sections from, reached as ctx.parts: fact rows, lists, tables, asset and entity links, actions, a file opener into the Code panel, problem lists, colour swatches, a cache keyed on content versions (and one for values read by running an asset's code), an lsp check, and typed controls over any values. Every function takes the section's Context first and returns edui nodes; every callback key starts with ctx.keyPrefix.

Usage: local edui.inspector.parts = require("@builtin::editor.edui.inspector.parts")

modules/edui.inspector.parts/action

action(ctx: any, id: string, label: string, run: () -> (), opts: any?): { any }

A button that runs run. A run that raises shows its message beneath the button until the next run.

Parameters

• ctx any (optional) — The Context.
• id string — Action id within this subject.
• label string — Button text.
• run () -> () — The action.
• opts any? (optional) — { primary? }.

ctx.parts.action(ctx, "compile", "Compile", function() ctx.ref:compile() end)

modules/edui.inspector.parts/bytes

bytes(n: number): string

A byte count as text: B below 1 KiB, KiB to one decimal below 1 MiB, else MiB to two.

Parameters

• n number — Bytes.

parts.bytes(1536) --> "1.5 KiB"

modules/edui.inspector.parts/cached

cached(key: string, paths: { string }, compute: () -> any): any

compute()'s value, computed again only when the content version of any of paths moves. Read through a Context's ctx.parts, the value is held while that Context, or another that read it, stays open; read through the module itself, it is held until the next Inspector.release.

Parameters

• key string — Cache key (make it unique per asset and purpose).
• paths { string } — The files the value is derived from.
• compute () -> any — Produces the value.

local geom = ctx.parts.cached("mesh:" .. guid, { path .. "/data.zmsh" }, decode)

modules/edui.inspector.parts/cachedCode

cachedCode(key: string, ref: any, compute: () -> any, opts: any?): any

compute()'s value where computing it runs ref's own code (a graph built from its init.luau, a module's declared settings): held until a file of ref's folder changes, it moves, a module its code requires changes (one it required before that module was known is asked about again at most every quarter second), a file opts.dependsOn(value) names changes, or a name opts.awaits(value) lists — one the value was read without because no asset answered to it — comes to answer (asked again when an asset is made, removed or renamed). A compute that raises holds nothing and raises, and a value opts.hold(value) answers false for is returned and not held, so either is read again on the next build. Read through a Context's ctx.parts, the value is held while that Context, or another that read it, stays open. Fold codeSignature(key) into the declaration's signature so a change to what the value came from rebuilds the section.

Parameters

• key string — Cache key (make it unique per asset and purpose).
• ref any (optional) — The asset whose code compute runs.
• compute () -> any — Produces the value.
• opts any? (optional) — { hold?, dependsOn?, awaits? }.

local graph = ctx.parts.cachedCode("graph:" .. guid, ctx.ref, function() return vfs.read(ctx.ref.path .. "/graph.json") end)

modules/edui.inspector.parts/check

check(ctx: any, path: string): { any }

A "Check" action running lsp.check(path), and the result of the last check of the file's current content.

Parameters

• ctx any (optional) — The Context.
• path string — The .luau file.

ctx.parts.check(ctx, ctx.ref.path .. "/init.luau")

modules/edui.inspector.parts/codeSignature

codeSignature(key: string): string

Text that moves when what the value behind cachedCode(key, ...) came from beyond its own folder changes: the modules its code requires, one of them becoming known, the files dependsOn named, and a name awaits listed coming to answer. Empty before the first read.

Parameters

• key string — The key cachedCode was read with.

signature = function(ref) return ctx.parts.codeSignature("graph:" .. guid) end

modules/edui.inspector.parts/entityLinks

entityLinks(ctx: any, ids: { string }, opts: any?): { any }

One button per entity — its name — that selects it. An id whose entity no longer exists is listed as text, marked despawned.

Parameters

• ctx any (optional) — The Context.
• ids { string } — Entity ids.
• opts any? (optional) — { max?, empty? }.

ctx.parts.entityLinks(ctx, compRef:listInstances())

modules/edui.inspector.parts/facts

facts(ctx: any, rows: { any }, empty: string?): { any }

Label/value rows; the value takes the width its label leaves and wraps within it. A row whose value is nil shows "—", so a value that could not be read is seen to be missing; a row that does not apply to the subject is left out of rows by the section. With no rows, empty (or "Nothing recorded.") is shown.

Parameters

• ctx any (optional) — The Context.
• rows { any } — { { label, value, mono? } }.
• empty string? (optional) — Text for no rows.

ctx.parts.facts(ctx, { { label = "Vertices", value = 24 } })

modules/edui.inspector.parts/forContext

forContext(keyPrefix: string): any

The parts as the Context keyPrefix names reads them — what ctx.parts holds. Its cached records that Context as one that read the value, so the value goes when every Context that read it is released; every other part is the module's own.

Parameters

• keyPrefix string — The Context's keyPrefix.

ctx.parts = Parts.forContext(ctx.keyPrefix)

modules/edui.inspector.parts/format

format(v: any): string

A value as display text: integers plain, other numbers to 4 significant digits, booleans yes/no, a list as its length, a map as its entry count.

Parameters

• v any (optional) — The value.

parts.format(3) --> "3"

modules/edui.inspector.parts/links

links(ctx: any, refs: { any }, opts: any?): { any }

One button per distinct asset — its name and type — that selects it; an asset named twice is listed once. An item is an AssetRef, a { __ref = guid } envelope, or a guid or name; one that does not resolve is listed as text.

Parameters

• ctx any (optional) — The Context.
• refs { any } — AssetRefs, { __ref } envelopes, or guids.
• opts any? (optional) — { max?, empty? }.

ctx.parts.links(ctx, { meshRef, materialRef })

modules/edui.inspector.parts/list

list(ctx: any, items: { string }, opts: any?): { any }

One text row per item, at most max (default 40), then "… and N more".

Parameters

• ctx any (optional) — The Context.
• items { string } — The texts.
• opts any? (optional) — { max?, empty?, mono? }.

ctx.parts.list(ctx, boneNames, { max = 30 })

modules/edui.inspector.parts/openFile

openFile(ctx: any, path: string, label: string?): { any }

An action opening path in the Code panel. Nothing when the file is absent. Its id names the file relative to the subject's folder, so two files of one name in different folders keep separate actions.

Parameters

• ctx any (optional) — The Context.
• path string — VFS path.
• label string? (optional) — Button text (default "Open ").

ctx.parts.openFile(ctx, ctx.ref.path .. "/init.luau")

modules/edui.inspector.parts/problems

problems(ctx: any, problems: { any }, clean: string?): { any }

One notice per problem (error or warning tone), or clean when there are none.

Parameters

• ctx any (optional) — The Context.
• problems { any } — { { message, code?, severity?, line? } }.
• clean string? (optional) — Text for no problems (default "No problems.").

ctx.parts.problems(ctx, asset.validate(ctx.ref).problems)

modules/edui.inspector.parts/release

release(keyPrefix: string)

Forget what the parts hold for the Context keyPrefix names and every key nested beneath it: the last failure of each action, each file's last check, its sections' state, and every cached value (a cached one or a cachedCode one) no other open Context read. A value read through the module itself, by no Context, goes too.

Parameters

• keyPrefix string — A Context's keyPrefix.

Parts.release(ctx.keyPrefix)

modules/edui.inspector.parts/state

state(ctx: any): { [string]: any }

The table a Context's sections keep state in between builds (a picked zoom, a chosen tab), forgotten when the Context is released.

Parameters

• ctx any (optional) — The Context.

local s = ctx.parts.state(ctx); s.zoom = s.zoom or "1"

modules/edui.inspector.parts/swatch

swatch(ctx: any, color: any, label: string): any

A colour square beside a label.

Parameters

• ctx any (optional) — The Context.
• color any (optional) — { r, g, b, a? } in 0..1.
• label string — The label.

ctx.parts.swatch(ctx, { r = 1, g = 0, b = 0 }, "accent")

modules/edui.inspector.parts/table

table(ctx: any, key: string, columns: { any }, rows: { any }, empty: string?): { any }

A table of records, each value shown through format.

Parameters

• ctx any (optional) — The Context.
• key string — Table id within this section.
• columns { any } — { { key, label?, align?, mono? } }.
• rows { any } — Records keyed by column key.
• empty string? (optional) — Text for no rows.

ctx.parts.table(ctx, "props", { { key = "name" }, { key = "type" } }, rows)

modules/edui.inspector.parts/values

values(ctx: any, opts: any): { any }

Typed controls over any values: one control per field of schema, validated with Field.check and written through write inside one undoable operation. undoable = false is for values that are session state, not content — a running render feature's live settings: each write goes through write with no undo operation, so undo and redo never reach it, and what it changes lasts as long as the thing it changed. readOnly shows the values with no control that writes. The controls' keys and rejections live under ctx.keyPrefix and subject, so the same subject shown by two Contexts keeps two states.

Parameters

• ctx any (optional) — The section's Context.
• opts any (optional) — { subject, schema?, values?, write?, undoable?, readOnly? }.

ctx.parts.values(ctx, { subject = guid .. ":live", schema = s, values = v, write = w })

modules/edui.inspector.presetActions/README

require("@builtin::editor.edui.inspector.presetActions") -- edui.inspector.presetActions

The Settings section's preset actions. "Save as preset" captures the values a Settings section shows as a typed preset targeting the declarer that governs them, named in a text field beneath the section, and selects the new preset. "Apply preset…" lists the presets whose target is that declarer and writes the one picked into the section's subject as one undoable operation. Both act on an asset's Settings section and on a component card's.

Usage: local edui.inspector.presetActions = require("@builtin::editor.edui.inspector.presetActions")

modules/edui.inspector.presetActions/applyInto

applyInto(p: any, name: string, targets: { any }): { text: string, tone: string }

Write preset p into each of targets (an asset ref, or { entity, component }) as one undoable operation — the operation already open, when one is, else its own. A target the preset refuses is reported by name and the rest are still written.

Parameters

• p any (optional) — The preset.
• name string — The preset's name as the outcome names it.
• targets { any } — What to write into.

local outcome = PresetActions.applyInto(p, "pixel_art", { texRef })

modules/edui.inspector.presetActions/outcomeNotice

outcomeNotice(ctx: any): any?

The outcome of the last save or apply under ctx, as a notice, or nil.

Parameters

• ctx any (optional) — The inspector Context.

local note = PresetActions.outcomeNotice(ctx)

modules/edui.inspector.presetActions/presetsFor

presetsFor(declarer: any): { Candidate }

Every preset whose target is declarer, by name.

Parameters

• declarer any (optional) — The declarer.

for _, c in ipairs(PresetActions.presetsFor(texTypeRef)) do print(c.name) end

modules/edui.inspector.presetActions/recordOutcome

recordOutcome(keyPrefix: string, outcome: { text: string, tone: string })

Record outcome as the last save or apply under keyPrefix, which outcomeNotice shows until the next one or a release.

Parameters

• keyPrefix string — A Context's keyPrefix.
• outcome { text: string, tone: string } — { text, tone }, as applyInto answers.

PresetActions.recordOutcome(ctx.keyPrefix, PresetActions.applyInto(p, name, { tex }))

modules/edui.inspector.presetActions/release

release(keyPrefix: string)

Forget the open action, typed name, listed presets and outcome kept under keyPrefix and every prefix nested in it.

Parameters

• keyPrefix string — A Context's keyPrefix.

PresetActions.release(ctx.keyPrefix)

modules/edui.inspector.presetActions/subjectOf

subjectOf(ctx: any): (any?, any?)

What a Settings section's preset actions write from and into, and the declarer that governs it: an asset's own ref, or { entity, component } for a component card. Nil for a Context whose values no preset targets — a preset's own values, a subject with no declarer.

Parameters

• ctx any (optional) — The inspector Context.

local subject, declarer = PresetActions.subjectOf(ctx)

modules/edui.inspector.settingsSection/README

require("@builtin::editor.edui.inspector.settingsSection") -- edui.inspector.settingsSection

The Settings section: every field of ctx.schema as its typed control, ctx.settings as the values, ctx.setSettings as the one write, each field's last rejection shown on it, and ACTIONS beneath.

Usage: local edui.inspector.settingsSection = require("@builtin::editor.edui.inspector.settingsSection")

modules/edui.inspector.settingsSection/actionRow

actionRow(ctx: any): any?

The row of ACTIONS that apply to ctx (only those ctx.actions names, when it is set), each acting on the whole of ctx.schema, with the panel of each open action and the outcome of the last preset save or apply beneath it; nil when no action applies.

Parameters

• ctx any (optional) — The inspector Context.

local row = SettingsSection.actionRow(ctx)

modules/edui.inspector.settingsSection/build

build(ctx: any): { any }

The section body for ctx. Reads only ctx.schema, ctx.schemaProblem, ctx.settings, ctx.setSettings, ctx.rejected, ctx.nameOf, ctx.widgets and ctx.keyPrefix, so any source of values (an asset, a component, a preset) renders through it. Fields show in the order the schema declares them.

Parameters

• ctx any (optional) — The inspector Context.

local nodes = SettingsSection.build(Inspector.valuesContext{ subject = key, schema = s, values = v, write = w, selection = sel })

modules/edui.inspector.settingsSection/fieldRows

fieldRows(ctx: any, fields: { [string]: any }): { any }

One typed control per field of fields (a schema, or part of ctx.schema), in declaration order, each writing through ctx.setSettings. Aliases are skipped. ctx.admit narrows every asset chip, asked with the chip's path from the field (presets[2].preset); ctx.openFields shows structs and lists open.

Parameters

• ctx any (optional) — The inspector Context.
• fields { [string]: any } — The field descriptors to show.

local rows = SettingsSection.fieldRows(ctx, ctx.schema)

modules/edui.inspector.settingsSection/fields

fields(ctx: any): { any }

The field rows alone — one typed control per schema field — for a caller that shows values without the actions beneath them. With no ctx.schema, the one row naming the schema problem, or that none is declared.

Parameters

• ctx any (optional) — The inspector Context.

local rows = SettingsSection.fields(ctx)

modules/edui.inspector.settingsSection/release

release(keyPrefix: string)

Forget what the Settings actions keep under keyPrefix (an open panel, a typed name, an outcome) and every prefix nested in it.

Parameters

• keyPrefix string — A Context's keyPrefix.

SettingsSection.release(ctx.keyPrefix)

modules/edui.inspector/README

require("@builtin::editor.edui.inspector") -- edui.inspector

The Inspector as an ordered list of sections. A subject (an asset, or a component on an entity) gets generic sections, merged with the sections its declarer's inspector.luau adds or replaces and put in the order it names; each section's build(ctx) receives one Context: the ref, its schema, its values with a validating, undoable setSettings, the selection and the edui widget set.

A section is { id, title, icon?, open?, build(ctx) -> { node } }. A type declares its own in the file its type.yaml names under inspector: (see @builtin::assetTypes.assetType.shared.inspector); material.assetType/ inspector.luau is a worked example. The Context every build receives:

Field	What it is
ref	the inspected asset (on an entity, the component asset)
info	asset.inspect(ref)
schema	asset.schema(ref), settingsOf resolved; nil when none is declared
schemaProblem	why a declared schema did not resolve
settings	the current values
setSettings(patch)	Field.checkSchema, then one undoable operation named for the field; answers (ok, violations)
rejected	field path -> the message of its last rejected edit
selection	{ scope = "asset" | "entity", id, component?, name? }; on an entity, component is the component's identity and name the name the entity lists it by
component	the live component proxy (entity scope)
nameOf(id)	the name an entity-reference field shows for an entity id (entity scope)
widgets	the edui framework table (field, schemaField, section, button, text, ...)
keyPrefix	the callback-key namespace for this subject
refresh()	rebuild the Inspector after a write that moves no revision
follow()	keep rebuilding while this section is shown: what it shows moves with nothing writing it (a clock that runs)
actions	when set, the ids of the Settings actions offered; nil offers every one that applies
parts	the building blocks a section composes (edui.inspector.parts)
The generic asset sections, in default order: identity, problems
(present when asset.validate reports any), tags, move, settings,
preview, operations. A declared section is added before
operations. settingsSection is the Settings section's body and the
actions offered beneath it.
A component on an entity (componentSections) has one generic section,
settings: its public fields as typed controls over the live component,
each write one undoable operation. A component that ships the file its
type names as inspector: { instance } adds, replaces and orders
sections the same way.

Usage: local edui.inspector = require("@builtin::editor.edui.inspector")

modules/edui.inspector/assetSections

assetSections(ref: any, info: any, keyPrefix: string?): ({ any }, any)

Generic plus declared sections for an asset, and the Context they share.

Parameters

• ref any (optional) — The asset ref.
• info any (optional) — Its asset.inspect record.
• keyPrefix string? (optional) — The Context's key prefix; one per asset when omitted.

local sections, ctx = Inspector.assetSections(ref, asset.inspect(ref))

modules/edui.inspector/buildSection

buildSection(section: any, ctx: any): ({ any }, string?)

Run one section's build for ctx. A build that raises, or returns anything but a list, yields one error row and the problem text.

Parameters

• section any (optional) — The section.
• ctx any (optional) — The Context.

local rows, problem = Inspector.buildSection(section, ctx)

modules/edui.inspector/componentSections

componentSections(entityId: string, componentName: string): ({ any }, any)

The sections of one component on one entity: the generic settings section (its public fields as typed controls over the live component, each write validated and one undoable operation) merged with what the file the component ships as its inspector: { instance } declares.

Parameters

• entityId string — The entity the component is on.
• componentName string — The component's name as the entity lists it.

local sections, ctx = Inspector.componentSections(id, "Camera")

modules/edui.inspector/componentSettingsRows

componentSettingsRows(ctx: any): { any }

The body of a component's generic Settings section: each three-number alias (a colour or a vector written as three channels) as one grouped control, then every other field through settingsSection.fieldRows, then the Settings actions over every declared field. A component that declares no fields reads "(no editable fields)".

Parameters

• ctx any (optional) — The component's Context.

local rows = Inspector.componentSettingsRows(ctx)

modules/edui.inspector/componentValuesSignature

componentValuesSignature(entityId: string, componentName: string): string

Text that moves whenever a declared field of componentName on entityId holds a different value — an edit, an undo, a redo, a script's write. Fold it into a panel's build signature to rebuild a card whose values moved without the entity revision moving.

Parameters

• entityId string — The entity the component is on.
• componentName string — The component's name as the entity lists it.

parts[#parts + 1] = Inspector.componentValuesSignature(id, "Camera")

modules/edui.inspector/epoch

epoch(): number return epoch end

Moves on every interaction the inspector's own state records (a disclosure, a rejection, a write). Fold it into a panel's build signature.

parts[#parts + 1] = tostring(Inspector.epoch())

modules/edui.inspector/following

following(): boolean

Whether a section built since the last call asked, through its Context's follow(), to be rebuilt while it is shown — what a panel reads after rendering to keep a running clock moving on screen.

if Inspector.following() then live = true end

modules/edui.inspector/isGenericSection

isGenericSection(id: string): boolean

Whether id names a section the generic builder adds where it applies (identity, problems, tags, move, settings, preview, operations), as opposed to one a type's own inspector declares.

Parameters

• id string — A section id.

if not Inspector.isGenericSection(s.id) then print("declared", s.id) end

modules/edui.inspector/mergeSections

mergeSections(generic: { any }, decl: any?, problem: string?, file: string?): { any }

Merge generic sections with a declaration: replace swaps a generic section by id, sections add (before operations when present, else at the end), order puts the ids it names first (a generic id this asset does not show is passed over). A problem becomes a first section naming it; every other section still renders.

Parameters

• generic { any } — Sections in default order.
• decl any? (optional) — The declaration, or nil.
• problem string? (optional) — Why the declaration could not be read, or nil.
• file string? (optional) — The declaring file, named in problems.

local sections = Inspector.mergeSections(generic, decl, problem, file)

modules/edui.inspector/release

release(keyPrefix: string)

Forget the rejections, section disclosures, Settings-action state and parts state (action failures, file checks, cached values no other open Context read) recorded under keyPrefix and every key nested beneath it — what a closed inline editor, or a subject the Inspector no longer shows, leaves behind.

Parameters

• keyPrefix string — A Context's keyPrefix.

Inspector.release(ctx.keyPrefix)

modules/edui.inspector/render

render(sections: { any }, ctx: any, opts: any?): { any }

Render sections as cards (or, nested, as titled groups inside a card). Each build runs through buildSection, so one that raises renders its error inside its own section.

Parameters

• sections { any } — The ordered sections.
• ctx any (optional) — The Context every build receives.
• opts any? (optional) — { nested? }.

local nodes = Inspector.render(sections, ctx, { nested = true })

modules/edui.inspector/renderAsset

renderAsset(assetId: string): { any }?

The rendered sections for the asset named by assetId, or nil when it cannot be read. A different asset than the last one clears the last one's rejections and its operation state.

Parameters

• assetId string — The asset's guid or identity.

local nodes = Inspector.renderAsset(guid)

modules/edui.inspector/signature

signature(assetId: string): string

Text that moves whenever what the Inspector shows for assetId can have moved: the asset folder's content version, which the change dispatcher moves after any write inside the asset has reached its type's hook — an edit, an undo or redo, a peer's synced write — and its settings values file's. A type's declaration adds what its own sections show beyond the asset's files (a render feature's running state) through a signature(ref) member. Fold it into a panel's build signature.

Parameters

• assetId string — The asset's guid or identity.

parts[#parts + 1] = Inspector.signature(guid)

modules/edui.inspector/typeSections

typeSections(ref: any, keyPrefix: string?): ({ any }?, any?)

The declared sections of ref's type, plus Settings when it has values — what an asset reference's inline editor shows. Nil when the type declares no type: inspector.

Parameters

• ref any (optional) — The asset ref.
• keyPrefix string? (optional) — The Context's key prefix — the inline editor's own, so two editors of one asset keep their own state and callback keys.

local sections, ctx = Inspector.typeSections(matRef, chipKey .. ":ed")

modules/edui.inspector/valuesContext

valuesContext(opts: any): any

The one Context builder. write(patch) performs a validated patch; this wraps it in Field.checkSchema, an undo operation named for the fields it sets, and the rejection record the Settings section shows. undoable = false names values that are session state rather than content (a running feature's live settings): their writes open no undo operation, so none reaches the undo history. keyPrefix names the callback keys and the state this Context keeps; it defaults to one per subject, and an inline editor passes its chip's own.

Parameters

• opts any (optional) — { subject, keyPrefix?, schema?, schemaProblem?, values?, write, undoable?, ref?, info?, selection, component?, nameOf?, actions?, admit?, openFields? }. admit(record, at) narrows what every asset chip offers and accepts (at = { path, parent }); openFields shows structs and lists open.

local ctx = Inspector.valuesContext{ subject = guid, schema = s, values = v, write = w, selection = sel }

modules/edui.query/README

require("@builtin::editor.edui.query") -- edui.query

Resolves the engine-provided query globals edui panels read — queryEntitiesTable, queryLogsTable, getProfilingDataTable, and the like. The engine installs these on _G at boot (before the global table is sealed read-only), so panels read them through this one indirection rather than each touching _G directly. override/restore swap a source for a stub or a mock feed without writing the sealed _G.

Usage: local edui.query = require("@builtin::editor.edui.query")

modules/edui.query/override

override(name: string, fn: any)

Shadow an engine query global with a function until restored.

Parameters

• name string — The global name.
• fn any (optional) — The function to resolve in its place.

modules/edui.query/resolve

resolve(name: string): any

Resolve a named engine query global, honouring any active override.

Parameters

• name string — The global name (e.g. "queryEntitiesTable").

modules/edui.query/restore

restore(name: string)

Clear an override so resolve falls back to the engine global again.

Parameters

• name string — The global name.

modules/edui.sceneInfo/README

require("@builtin::editor.edui.sceneInfo") -- edui.sceneInfo

Which scene asset each loaded layer came from, as the editor shows it. A layer is a loaded instance of a scene asset: its guid is the asset's guid, its name is the asset's display name, and its identity names the asset to open, save or reload (@builtin::scenes.test_arena, a world scene's name). The open scene is the one non-additive layer.

Usage: local edui.sceneInfo = require("@builtin::editor.edui.sceneInfo")

modules/edui.sceneInfo/describe

describe(guid: string): { name: string, identity: string?, path: string?, loaded: boolean }

The scene asset behind a layer guid — a loaded layer's info, or for a guid no layer is loaded under, the scene asset that guid names.

Parameters

• guid string — A layer guid (as entity.tree groups rows by).

modules/edui.sceneInfo/layers

layers(): { LayerInfo }

Every loaded layer with the scene asset it came from, in the order layers.list() reports them.

modules/edui.sceneInfo/open

open(): LayerInfo?

The open scene: the root (non-additive) layer and the asset it was loaded from.

modules/edui.sceneInfo/shortName

shortName(identity: string?): string?

A scene identity's last segment: @builtin::scenes.test_arena reads test_arena, /source/scenes/level01.scene reads level01.

Parameters

• identity string? (optional) — A scene identity or VFS path.

modules/edui.sceneInfo/signature

signature(): string

A one-line signature of the loaded layers — which are loaded, which is open, and what each is named — for a watcher to compare frame to frame.

modules/edui.shell/README

require("@builtin::editor.edui.shell") -- edui.shell

The editor dock shell on the CSS-parity ui.* surface. One edui app owns a ui.* native dockArea whose children are a dockPanel per registered edui panel — real egui_dock tabs, splits and drag. The shell keeps its OWN panel registry (separate from the deprecated zui editor registry) so the zui editor stays untouched while panels migrate one at a time; the two registries fold into one at cutover.

Usage: local edui.shell = require("@builtin::editor.edui.shell")

modules/edui.shell/activeLayout

activeLayout(): { name: string?, title: string, slot: string? }

The layout in force, as the layout switch shows it.

edui.shell.activeLayout().title

modules/edui.shell/addPanel

addPanel(spec: any): boolean

Register (or replace) an edui dock panel. A duplicate id replaces the prior registration; the live shell rebuilds so the change shows at once.

Parameters

• spec any (optional) — { id (REQUIRED), build (REQUIRED, () -> widget), title?, order?, dock?, badge?, badgeColor?, menu?, menuHint?, startClosed?, transient?, close?, dirty?, save?, discard? }. build is an edui builder: it may call the edui.* primitives, whose closures register on the shell app automatically. startClosed = true registers into the Window-menu catalog without opening a tab; the panel opens when someone opens it. title is text or an i18n.text value, which the tab, the menus and the catalog read in the editor's language each time they build. menuHint is a short note the menu entry carries on the right — a string, or a function read each time the menu opens. transient = true makes a panel that exists for this session alone: closing its tab forgets it, a layout or mode change keeps it open, and no saved arrangement records it. dirty: () -> boolean says whether the panel holds unsaved edits: its tab title ends in a dot while it does, and closing its tab asks first (Save & close / Discard / Cancel) — call refreshChrome when the answer changes. save: () -> (boolean, string?) writes the edits, returning false and why when it could not; discard: () -> () drops them before a Discard closes the tab. A layout or mode change closes a non-transient panel without asking, so a panel declaring dirty keeps its edits through its close hook and shows them again when it reopens.

edui.shell.addPanel{ id = "entities", title = "Entities", build = fn }

modules/edui.shell/app

app(): any

The mounted shell App, or nil when the shell is not up.

modules/edui.shell/applyLayout

applyLayout(name: string, opts: any?): (boolean, string?)

Apply the layout named: the world's .editorLayout of that name, else the built-in one. A layout listing panels rebuilds the dock from its panel set and region hints, so it comes out the same at any window size; one holding a captured arrangement restores it. The name is recorded under /source/local as the layout this world's editor comes up in.

Parameters

• name string — A name layouts reports.
• opts any? (optional) — { persist? = false, arrangement? } — persist = false applies without recording it (a boot's --layout); arrangement is a captured arrangement to restore in place of the layout's own seed, which is how the layout switch brings a layout back as it was left.

edui.shell.applyLayout("recording")

modules/edui.shell/assignLayout

assignLayout(side: string, name: string): (boolean, string?)

Assign a layout to side A or side B of the layout switch. The assignment is kept per world on this machine. A layout already standing for the other side swaps places with the one this side gave up. When this side is the one in force, the layout takes the editor at once.

Parameters

• side string — "a" | "b".
• name string — A name layouts reports.

edui.shell.assignLayout("a", "recording")

modules/edui.shell/catalog

catalog(): { any }

Every catalogued panel (open or closed), sorted by (order, id), each { id, title, order, dock, open } — the Window menu's source.

modules/edui.shell/catalogRevision

catalogRevision(): number

How many times the catalog's membership has changed — a registration, a re-registration or a removal each count once. A surface built from the catalog (the menu bar) compares this between frames and rebuilds when it moves, rather than walking the catalog every frame.

if edui.shell.catalogRevision() ~= seen then print("the panel catalog changed") end

modules/edui.shell/confirmClose

confirmClose(id: string): boolean

Ask the user whether to save a panel's unsaved edits before its tab closes: a dialog titled "Unsaved changes" offering Save & close (when the spec declares save), Discard and Cancel. While the dialog asks about another panel this one waits its turn.

Parameters

• id string — The panel id passed to addPanel.

edui.shell.confirmClose("code")

modules/edui.shell/confirmDiscard

confirmDiscard(request: any)

Ask whether to keep unsaved edits before something drops or replaces them: a dialog titled "Unsaved changes" saying "