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

build

Turns builder code into scene records, and scene records into scene entities.

by◐lumi·posted 3mo ago
What it does

scene_build

Turns builder code into scene records, and scene records into scene entities.

run(builder) opens an entity capture scope, calls builder, and composes every entity it created into records — then despawns them. The builder writes ordinary spawn code; what comes back is data. A builder that raises leaves nothing behind.

What a component the builder attached creates while running its own lifecycle belongs to that component: the record names the COMPONENT, and the same lifecycle runs again wherever the record is put back. That is what makes a nested build one build — a placement the builder makes runs its own module and owns what it lands, and the build around it describes the placement.

reconcile(records, target, owner) applies records to the scene under target, writing owner and the record's place in the hierarchy onto each entity it places as the buildOwner / buildKey attributes. A rebuild reads that pair back off the entities under target and lands on the same ones, so nothing has to be remembered between two rebuilds — the pair is in the scene, and a reload brings it back with the entity. It returns the ids it landed on, keyed by record identity.

A record is identified by its place in the hierarchy — the chain of names from the build root down to it, base/coin_3 — so dropping a line from the middle of a builder, inserting one, or emitting two entities in the other order leaves every other entity's id where it was. Children of one parent that share a name carry their rank among those, base/crate#2, counted in the order the builder created them.

Together these are the bake: code in, durable static-id scene content out.

Who states an entity

An entity names the build that placed it, so ownerOf(id) answers which build owns it — and answers nil for an entity an author spawned. sourceOf(owner) names the file that build is written in, from the source the reconcile running it passed.

That pair is what makes ownership legible where an author meets it. notePreview(id, values) records what an entity carries after an author's change and takePreview(id) reads it back exactly once, in the run that states the entity again, which is where what the author set and what the build says can be named side by side.

What a rebuild keeps

Every entity a build places records what that build stated about it. A rebuild whose code states a value the way the last build did leaves that value as the scene holds it, so a hand edit to a built entity (a move, a rename, an attribute, a component field) survives every plain rebuild. The scene's build answers for all of it:

local report = layers.active.asset:build({ save = false })
print(report.message)  -- opens with one line counting all four lists

kept lists the hand edits to entities the build placed, driven the fields another component writes at runtime, handAdded the components and attributes added by hand to built entities, and handPlaced the entities no build placed. layers.active.asset:build({ restate = true }) lands every value build.luau states over the kept ones. reconcile(records, target, owner, { restate = true }) is the same at this level, and its third return value is the kept list. kept covers every value a build states about an entity it placed: its name, internal flag, transform, active flag, lifecycle mode, replication scope, synced flag, attributes and components. A restate writes exactly those: a number the scene holds within the precision a saved record keeps, and the bookkeeping a component writes about its own runtime, stay as they are. drift() reads the entity's own values alone; the build's report is the whole answer. guides { path: "core/scenes-as-code" }, "What a rebuild touches", gives the shape of every entry.

Interface

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

conforms to

zero/source-extract/v2

module 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. require @builtin::assetTypes.scene.shared.build

capturedRoots(ids: { string }) → void

Reduce captured ids to the roots of the captured set: an id whose parent was ALSO captured is reached by walking its parent, so composing from it too would emit it twice. Ids whose parent is nil, or lies outside the capture, are roots.

argtypedescription
ids{ string }

captureRank(ids: { string }) → void

The capture hands back its ids in the order the builder created them, so an id's position in that array is the rank the record walker orders siblings by. Two runs of the same builder create the same entities in the same sequence, which is what makes the emitted record order — and therefore reconcile's keys — the same across rebuilds.

argtypedescription
ids{ string }

idSet(ids: { string }) → void

A set from an id array, for the membership questions the composition asks.

argtypedescription
ids{ string }

without(ids: { string }, excluded: { [string]: boolean }) → void

The ids the array holds that the set does not name, in the same order.

argtypedescription
ids{ string }
excluded{ [string]: boolean }

republishWhenCaptureCloses(ref: any) → void

argtypedescription
refany

flushRepublish( ) → void

authorFrame(traceback: string) → string

The frame in a refusal's traceback that belongs to the code being BUILT. A traceback runs innermost first and opens with the frames that issued the refusal: the `[C]` binding and the engine module that called it. The first frame past those is the line an author wrote, which is the contributor a build composed from several of them has to name. A traceback holding no such frame has no contributor to name and says so by answering nil; the whole traceback travels beside it either way.

argtypedescription
tracebackstring

attribute(refusals: { 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.

argtypedescription
refusals{ Refusal }The refusal array `entity.capture` hands back.

examples

local named = SceneBuild.attribute(select(4, entity.capture(fn)))

despawnAll(ids: { string }) → void

argtypedescription
ids{ string }

markRowFields(records: { any }, stamps: { [string]: { string } }) → void

Name, on each component entry a Preset Manager row reached during the build, the fields the row gave that the builder did not state (`row_fields`). The digest a rebuild compares leaves them out, so what decides whether a component is restated is what the code says: a row edit alone restates nothing already built.

argtypedescription
records{ any }
stamps{ [string]: { string } }

markSelfFields(records: { any }) → void

Note on each captured component entry the fields its instance wrote about its own runtime while the builder ran (`self_fields`): the bookkeeping a component keeps about what it produced, such as the id map an asset component records for the children it spawned. The record leaves them out of what it states, and the reconcile reads this list to tell such a field, which the scene holds because the component wrote it, from a field an author set that the code leaves out.

argtypedescription
records{ any }

run(builder: () →

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. the builder created them; and the array of refusals the scope issued, each with `message`, `at` and the `source` frame naming who was refused.

argtypedescription
builder(Function taking no arguments; spawns whatever it wants.

examples

local records, refused = SceneBuild.run(function() entity.spawn("chair") end)

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?".

argtypedescription
sourcestringThe script body to digest.

examples

local key = SceneBuild.digest(vfs.read(path))

readGeneratedState(folder: string) → void

argtypedescription
folderstring

writeGeneratedState(folder: string, state: { [string]: string }) → void

argtypedescription
folderstring
state{ [string]: string }

republishContent(ref: any) → void

Hand a re-authored asset to its own type's change handling. Re-authoring in place keeps the guid, which is what holds every reference to the asset — and the same guid is the key every live consumer already resolved through. So the new content reaches those consumers only through the type's own `onChange`: the mesh registry hands back the resident GPU mesh rather than re-reading bytes, and every other type that materialises something answers the same way. The type is given a ref with nothing cached from the previous bytes. A type memoizes what it derived from the content and judges a write by whether that memo still stands; the records those memos compare against do not all move for an in-place re-author, so a type can read a replaced payload as no change at all and leave live consumers on the old one for the rest of the session. Forgetting first states the one thing that is certainly true — this asset's content is not what it was — and leaves what to DO about it to the type.

argtypedescription
refany

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. inside. reports it — what decides whether an asset it produced is still the asset the code states.

argtypedescription
folderstringThe build's own folder, which the assets it produces are authored
sourceDigeststringThe digest of the build script running now, as `M.digest`

examples

local surface = SceneBuild.buildSurface(dir, SceneBuild.digest(src))

asset(kind: string, name: string, produce: () → void

argtypedescription
kindstring
namestring
produce(

escapeSegment(name: string) → string

A key spends `/` on the step from a parent to a child, `#` on the ordinal that separates same-named siblings, and `%` on the escape itself. A name carrying one of the three is written with that character as `%XX`, so a key splits back into exactly one chain of names and one ordinal.

argtypedescription
namestring

recordKeys(records: { any }) → void

A record's identity ACROSS rebuilds: its place in the HIERARCHY, written as the chain of names from the build root down to it — `base/pusher`, `base/coin_3`. `original_id` is a runtime id from the build that produced it, so it differs on every run and cannot key the map on its own; a name chain is the same on every run of a builder that produces the same shape. A sibling dropped, inserted or emitted at a different moment moves no other record's chain, so every other entity keeps its id. Several children of one parent may carry the same name, and those share a chain. An ordinal separates them: the rank among the siblings sharing that name, counted in emission order, which is the order the builder created them in. The first of a name carries no ordinal — `base/crate`, `base/crate#2` — so a builder that starts emitting a second `crate` leaves the first alone. The keys are read out of the record array alone, so a record set keys the same way before anything is spawned as it does after. A record whose `parent_id` names no earlier record keys as a root, which is where reconcile parents it.

argtypedescription
records{ any }

resolveTarget(target: any) → Destination

The destination `target` names, whether it arrives as an entity ref, an entity id, or a scene layer. A table is asked for its `id` first. An entity proxy answers only the names it knows and raises on the rest, so a layer's `guid` is a question to put to a table that turned out not to be one.

argtypedescription
targetany

runKey(owner: string, destination: Destination) → string

The key `runningReconciles` holds a reconcile of `owner` at `destination` by.

argtypedescription
ownerstring
destinationDestination

builtEntityId(owner: string, destination: Destination, key: string, generation: number) → string

The id a build gives the entity it creates for the record identity `key`: a digest of the build, its destination and the key, so every session that runs the same build at the same destination creates that entity under the same id. Several sessions share a world, and each one runs a build as its scene loads; one whose load reads the scene before another session's build output has reached it creates the entities that output holds, and the records arriving after it land on those same entities rather than beside them. `generation` counts the ids of one record identity from 1: generation 1 is the id the build gives the entity first, and each later one is the id it gives the entity when every earlier one is held.

argtypedescription
ownerstring
destinationDestination
keystring
generationnumber

ownerAttribute(entityId: string) → string

The build named on `entityId`, or nil for an entity carrying no build name.

argtypedescription
entityIdstring

keyAttribute(entityId: string) → string

The record identity named on `entityId`, or nil for an entity carrying none.

argtypedescription
entityIdstring

standsInside(entityId: string, destination: Destination) → boolean

Whether `entityId` stands inside `destination`: beneath the entity a placement's build lands under. A layer's build derives its ids from the layer, so an entity under one of them stands in that layer's build.

argtypedescription
entityIdstring
destinationDestination

arrivedEntity(owner: string, destination: Destination, key: string) → string

The entity standing under one of the ids this build derives for `key` that carries this build's name and `key` and stands inside the destination, or nil when none does. A reconcile reads what the build holds once, as it starts, and lands across several frames; another session's records of the same build reach the scene in those frames and place the entity that session's build created, under the id this build derives for it. That entity is the one this reconcile lands the record on. An entity carrying the pair outside the destination is one an author moved out of the build, and keeps its id.

argtypedescription
ownerstring
destinationDestination
keystring

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.

argtypedescription
entityIdstringRuntime entity id.

examples

if SceneBuild.ownerOf(id) ~= nil then print("a build states this") end

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.

argtypedescription
ownerstringBuild name, as `M.ownerOf` reports it.

examples

local file = SceneBuild.sourceOf(SceneBuild.ownerOf(id))

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. `"remote"` for one another session sharing the world made.

argtypedescription
guidstringThe asset's guid.
originstring?`"local"` for a write this session made (the default),

examples

SceneBuild.noteSourceWrite(ref.guid, change.origin)

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.

argtypedescription
guidstringThe asset's guid.

examples

local record = SceneBuild.sourceWrittenHere(ref.guid)

releaseStatement(owner: string) → void

The build named `owner` states nothing any more: another build took its placement out of the scene, or stopped stating the placement on it.

argtypedescription
ownerstring

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. it ran and placed none, or another build has since taken the build's placement out of the scene; nil when the build has not run in this session.

argtypedescription
ownerstringBuild name, as `M.ownerOf` reports it.
keystringThe record identity, as the entity's `buildKey` attribute holds it.

examples

local stillStated = SceneBuild.states(owner, key)

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. that type again instead of leaving it to the scene.

argtypedescription
entityIdstringRuntime entity id of the owned entity.
values{ [string]: any }The values the entity carries now, by name.
componentTypestring?The component that states them, so a rebuild knows to state

examples

SceneBuild.notePreview(id, { count = 9 }, "SceneModule")

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.

argtypedescription
entityIdstringRuntime entity id of the owned entity.

examples

if SceneBuild.previewedComponentType(id) == "SceneModule" then end

takePreview(entityId: string) →

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.

argtypedescription
entityIdstringRuntime entity id of the owned entity.

examples

local set = SceneBuild.takePreview(id)

ownedEntities(owner: string, destination: Destination) → void

The entities under `destination` that a build with this owner has placed: every one of them by id, and the id each record identity landed on. Read off the live scene rather than remembered, so it is correct on the first rebuild after a reload just as it is on a rebuild in the same session — a load brings the attributes back with the entity, so the pair the last run wrote is there to be read. A layer's build owns only what that layer holds. Every scene's build goes by the same owner name, so a scene loaded additively beside the root reads its own entities here and never the root's, which a rebuild would otherwise sweep away as entities it no longer emits. Two entities carrying one key leave the reverse index naming one of them; the other stays in the owned set, which is what the sweep at the end of a reconcile despawns.

argtypedescription
ownerstring
destinationDestination

handPlaced(target: EntityRef | string | { guid: string }) →

The entities under `target` that no build placed: each one an author, a tool or a script put in the scene, with everything under it. They carry no build's owner attribute, so `build.luau` states nothing about them and a rebuild leaves them exactly where they are. Only entities the scene file holds count: what a component produces, a spawner puts back or a peer replicates in is left out. An entity under another one listed here comes with it and is not listed again. is `e`, the code for the whole entity, beside the codes a kept, driven or hand-added entry carries, so one reader walks all four lists alike; `components` the short names of the components it carries, in the order the scene lists them; `builtTwin` the id of an entity a build placed under the same name, when there is one: `build.luau` now states the entity, so the hand-made one is a second copy beside the build's. The four lists are the build's answer: `layers.active.asset:build({ save = false })` returns `kept`, `driven`, `handAdded` and this list as `handPlaced`, with a `message` whose first line counts all four.

argtypedescription
targetEntityRef | string | { guid: string }Entity ref, entity id, or scene layer, as `M.reconcile` takes it.

examples

local loose = SceneBuild.handPlaced(layers.active)

sameValue(a: any, b: any) → boolean

Whether two snapshot values state the same thing, structure and all. Both sides come from the same snapshot shape — the record's and the live entity's — so a plain deep comparison is what decides whether the entity already holds what the record says.

argtypedescription
aany
bany

canonicalText(value: any, depth: number) → string

A value as one deterministic string: keys in sorted order, so two tables holding the same thing read the same however they were built. Depth-bounded, because what is being answered is "did the code change what it says", and a structure deeper than this states more than a component's configuration does.

argtypedescription
valueany
depthnumber

withoutFields(data: any, given: any) → any

What this build says about each component TYPE the record names, as one digest per type. A digest rather than the text because this is recorded on every entity the build places and travels into `scene.json` with it; the question it answers is only whether the code says what it said, which a digest answers exactly. Per TYPE, not per field, because that is the granularity the reconcile already works at: an instance is put back by being removed and re-added, so a type is the smallest thing a build can restate. What that costs is stated plainly: a build that changes ONE field of a component restates that component whole, so an author's edit to a DIFFERENT field of the same component goes with it. An attribute, which the build writes one at a time, is recorded one at a time and keeps that resolution. A field naming another entity is digested as what the code names: an entity the same build places reads as that entity's record key, which every run of the build gives it, rather than the id the capture minted for it this run or the runtime id a reconcile resolves it onto. So the digest states the code and not the run or the scene the code landed in, and a build whose code did not change reads its own digest back. `data` without the fields `given` names, each a field name or a `group.field` path into a group. Only the tables on a named path are copied.

argtypedescription
dataany
givenany

resolveEntityRefs(comp: any, runtimeByOriginal: { [string]: string }) → any

argtypedescription
company
runtimeByOriginal{ [string]: string }

statedData(comp: any, statedRefs: { [string]: string }) → any

What the build's code stated for one component entry: its data, each entity it names read as `statedRefs` names it, without the fields a Preset Manager row gave it.

argtypedescription
company
statedRefs{ [string]: string }

componentDigests(rec: any, statedRefs: { [string]: string }) → void

argtypedescription
recany
statedRefs{ [string]: string }

componentBakedKey(typeName: string) → string

argtypedescription
typeNamestring

numText(n: any) → string

Numbers are compared as text so that what was written and what is read back agree exactly. `%.17g` round-trips a double, so a value that survived a save and a reload reads as the value that was baked rather than as drift.

argtypedescription
nany

vecText(v: any, count: number, fallback: { number }) → string

argtypedescription
vany
countnumber
fallback{ number }

isRuntimeAttribute(name: any) → boolean

Whether an attribute name belongs to the RUNTIME rather than to the scene. A `_`-prefixed name is the same contract the scene saver spends on component data: the saver drops those keys, so the value lives on the live entity and never reaches `scene.json`. The persistence layer's own origin tag is written that way, and it decides where an asset a builder creates is authored. A build therefore leaves every such name alone at all three points it would otherwise touch one: it does not record it in the baked baseline, does not diff it, and does not remove it. The PREFIX is the contract — a name the build has never heard of is safe the moment it carries one — so this is the single predicate all three read, and a value the build cannot bake is a value it has no business deleting.

argtypedescription
nameany

attributeText(value: any) → string

An attribute value as the text the baked record holds for it. A table is written out by content, keys sorted, so two runs stating the same table bake the same line and a reload of the scene reads back the value it baked.

argtypedescription
valueany

bakedText(fields: { [string]: string }) → string

The baked record as `key=value` lines. One line per property, so a property is compared on its own and a rebuild that changed one leaves the others to whatever the scene holds.

argtypedescription
fields{ [string]: string }

parseBaked(held: any) → void

Read back what `bakedText` wrote. An entity with no record — one placed before this was kept, or by a build that never ran again — reads as an empty set, which makes every property "the code has not spoken about this yet" and so leaves the code in charge.

argtypedescription
heldany

readBaked(rid: string) → void

argtypedescription
ridstring

statedBefore(prev: { [string]: string }, name: string) → void

What the last build stated about `name`, reading a lifecycle property the baked record leaves out as its default.

argtypedescription
prev{ [string]: string }
namestring

codeWins(prev: { [string]: string }, name: string, wanted: string) → boolean

The three-way answer for one property: does the build write it? the code changed what it says -> the code wins, any override is dropped the code says what it said -> whatever the scene holds stands, so an author's change survives the rebuild A property the last build never recorded has no previous answer to compare against, so the code writes it — which is what a first build, and every entity placed before this record existed, needs.

argtypedescription
prev{ [string]: string }
namestring
wantedstring

sameBakedText(a: string, b: string) → boolean

Whether two texts the baked record holds state the same value: equal text, or the same numbers within the precision a saved record keeps. A record read back from `scene.json` carries its numbers through a JSON round trip, which can shorten the digits `%.17g` baked them with.

argtypedescription
astring
bstring

buildWins(merge: Merge, prev: { [string]: string }, name: string, wanted: string) → boolean

Whether the build writes one property: the three-way answer, or always when the reconcile restates.

argtypedescription
mergeMerge
prev{ [string]: string }
namestring
wantedstring

entityName(rid: string) → string

The entity's name, or an empty string when it cannot be read.

argtypedescription
ridstring

noteAdded(merge: Merge, rid: string, property: string, instances: { string }?, held: string?) → void

Record that the entity carries `property`, a component or an attribute no build stated.

argtypedescription
mergeMerge
ridstring
propertystring
instances{ string }?
heldstring?

applyTransform(rid: string, rec: any, prev: { [string]: string }, merge: Merge) → void

Write a record's local transform onto a runtime entity, channel by channel. A record omitting a channel leaves that channel as the entity has it, and a channel the entity already holds is left alone rather than rewritten with the value it has. A channel the build states the same way it did last time is left to the scene, so a channel an author moved keeps their move, and the move is noted in `merge.kept`.

argtypedescription
ridstring
recany
prev{ [string]: string }
mergeMerge

liveBaked(rid: string) → void

What the entity holds RIGHT NOW, in the same shape the build records what it said. Read against a recorded set, a property that reads back differently is one an author has changed since the build stated it.

argtypedescription
ridstring

drift(owner: string?) →

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 values a rebuild KEEPS: a plain rebuild leaves each one as the scene holds it, and `layers.active.asset:build({ restate = true })` lands `build.luau`'s value instead. This list reads the entity's own values alone: its name, internal flag, transform, active flag, lifecycle mode, replication scope, whether its live state replicates, and its attributes. The build's own report is the whole answer: `layers.active.asset:build({ save = false })` answers `kept` (these and every component field, each with the value `build.luau` states), `driven` (fields another component writes at runtime), `handAdded` and `handPlaced`, and its `message` opens with one line counting all four. Read that report to know where a scene and its `build.luau` disagree before deciding which should win. Numbers compare within the precision a saved record keeps, the tolerance the build reads `kept` with, so a value the report keeps nothing of is never listed here. Property names are the ones the build records: `n` name, `i` internal, `p` position, `r` rotation, `s` scale, `o` active, `m` lifecycle mode (participation), `w` replication scope (network scope), `y` whether the live state replicates (synced), and `a:<name>` for an attribute. build. Omitted, every build-owned entity in the scene is read. drifted property, sorted by entity then property.

argtypedescription
ownerstring?Optional build name, as `M.ownerOf` reports it, to read just that

examples

for _, d in ipairs(SceneBuild.drift()) do print(d.name, d.property) end

recordDrift(rec: any) →

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, lifecycle mode, replication scope, `synced` flag and attributes are compared, numbers within the precision a saved record keeps. and `attributes`. rotation, `s` scale, `m` lifecycle mode, `w` replication scope, `y` synced, `a:<name>` an attribute). Empty for a record that holds what its build stated, and for a record no build placed.

argtypedescription
recanyAn entity record: `name`, `transform = { position, rotation, scale }`

examples

local drifted = SceneBuild.recordDrift(record)

entryType(entry: any) → string

The name the entity reports one `component.getAll` entry under, or nil for an entry naming no type.

argtypedescription
entryany

heldInstance(entry: any) → HeldInstance

One `component.getAll` entry as a held instance, or nil for an entry naming no type.

argtypedescription
entryany

drivenNames(driven: { [string]: FieldDriver }?) → void

The names of the fields `driven` holds, sorted, in the shape `withoutFields` takes.

argtypedescription
driven{ [string]: FieldDriver }?

heldComponents(proxy: any) → void

Per type, the instances the entity carries, in the order it reports them.

argtypedescription
proxyany

entriesOfType(proxy: any, typeName: string) → void

The `component.getAll` entries of the component `typeName` names that the entity carries, in the order it reports them. The engine resolves `typeName` to the component it is registered as and answers every instance of that component, under whichever of its names the entity reports it: the same answer `component.add` refuses a second anonymous instance by. A record can name a component by another of its names than the one the entity reports, such as the short name a scene file was saved with beside the package-qualified name the component is registered under now, and the reconcile finds the instance either way. A name the engine refuses to resolve is matched as written, and the add that follows names the refusal.

argtypedescription
proxyany
typeNamestring

heldOfType(proxy: any, typeName: string) → void

The instances of the component `typeName` names that the entity carries, in the order it reports them, each with its live state read back.

argtypedescription
proxyany
typeNamestring

reportedNamesOf(proxy: any, typeName: string) → void

The names the entity reports its instances of the component `typeName` names under, one per instance. Reads the names alone, none of the instances' state.

argtypedescription
proxyany
typeNamestring

comparableData(rid: string, typeName: string, instanceName: string?, data: any) → any

The part of an instance's data a rebuild has anything to say about: what states how the component was CONFIGURED, without the bookkeeping the live instance keeps about its own runtime. Both sides of every comparison go through here, against the LIVE instance's own account of which fields it wrote, so the two are judged on one set of fields. The record was captured from a different instance of the same component — one that lived as long as the build that produced it — and two instances of one component reach different points in their own bookkeeping. Comparing what each recorded about itself would read as a change on every rebuild, and the diff would replace a component nothing had configured differently. What the record STATES is what a rebuild is entitled to judge.

argtypedescription
ridstring
typeNamestring
instanceNamestring?
dataany

markStated(rid: string, typeName: string) → void

Say that the instance of `typeName` on the entity is authored content, a record of the scene put in the world, the way the loader says it of every component it restores from `scene.json`.

argtypedescription
ridstring
typeNamestring

addInstance(proxy: any, typeName: string, instance: WantedInstance) → void

Add one instance of `typeName` to the entity. An instance's name is carried by the record's `instance_name` and written back through the `name` key `component.add` reads it from, so a named instance comes back under its own name instead of collapsing into an anonymous one. A reconcile puts a record back into the scene, so the instance it adds is authored content the same way one the loader restores from `scene.json` is — and it says so by name, the way the loader does. Without it the instance would be classified by whatever context happened to be running the build — a scene load, an edit to `build.luau` — and the next save would leave out the component the rebuild just placed. Every add here puts back a record: an instance the build creates or restates carries what the capture scope stamped, Preset Manager rows included, and one the code states as it did last time carries what the scene holds. Either way no row reaches it a second time.

argtypedescription
proxyany
typeNamestring
instanceWantedInstance

markPlaced(rid: string) → void

Say that an entity this reconcile just created is a record of the scene put in the world, the way the loader says it of every entity it restores. What a build places is the scene's own content whatever code asked for the build, a `SceneModule` placement building from its own `awake` included, so the scene saver writes it to `scene.json` and a reload restores it under the id it has.

argtypedescription
ridstring

markBuilt(rid: string) → void

Hand an entity this reconcile created or changed to the scene saver's per-entity writer. A build's product is the scene's own content, so the mark lands from a component's lifecycle as well: a `SceneModule` placement that builds from its `awake`, or rebuilds when its module's source is edited, reaches the scene's unsaved edits the way a build an author's own call ran does, and a play session entered before the next save loads it. A build that runs as its scene loads reruns on every load, so the mark is dropped there and the scene file receives that build's output through an explicit save.

argtypedescription
ridstring

unbuild(rid: string, record: boolean) → void

Despawn an entity a build placed and no longer states, together with every entity beneath it, and with `record` state the removal of each to the scene saver. The records the scene file holds for them leave it with the entities when the build runs in a window that records; a build that runs as its scene loads reruns on every load, so its removals are recorded nowhere. Either way the saver hears that the build took each one away, so the scene's next save in this session states the removal: a build that records nothing leaves the live scene without the entity, and a save writes what the live scene holds. A placement among them takes its own build's statement with it.

argtypedescription
ridstring
recordboolean

declaredDefaults(typeName: string) → void

The default each public field of the component `typeName` declares, read from its schema; empty when the component answers no schema.

argtypedescription
typeNamestring

same(a: HeldInstance, b: WantedInstance) → boolean

argtypedescription
aHeldInstance
bWantedInstance

stated(instanceName: string?, data: any) → any

argtypedescription
instanceNamestring?
dataany

fieldText(value: any) → string

A component field's value as the text a kept entry reports it in.

argtypedescription
valueany

liveValue(field: any) → any

argtypedescription
fieldany

drivenByOf(driver: FieldDriver) → void

The component driving a field, as a kept report names it: its type by the last segment of its name, and the entity it is on with that entity's name while the entity stands.

argtypedescription
driverFieldDriver

statesItsOwn(rid: string, typeName: string) → boolean

Whether `typeName` is the component that recorded a preview on this entity. The record names a type as `@builtin::components.SceneModule` and a component knows itself as `SceneModule`, so a bare name matches the tail of a qualified one; anything else is compared whole.

argtypedescription
ridstring
typeNamestring

isPlacement(typeName: string) → boolean

argtypedescription
typeNamestring

holdsPlacement(proxy: any) → boolean

Whether the entity carries a placement component now.

argtypedescription
proxyany

releasePlacedBuild(hostId: string, record: boolean) → void

Despawn the build a placement on `hostId` placed: every entity beneath it that names `hostId` as its owner. A despawn cascades to children, so an entity whose parent is also going is left to its parent. `record` is the reconcile's own: whether the removals reach the scene saver.

argtypedescription
hostIdstring
recordboolean

previouslyRecordedNames(proxy: any, prev: { [string]: string }) → void

For each component type the entity reports, the name the last build recorded that component under in `prev`. A build records a component under the name its record gave it, and a component can be reported under another of its names, so each recorded name is resolved through the instances the entity holds of it. A recorded name spelled exactly as the entity reports the type is the one kept.

argtypedescription
proxyany
prev{ [string]: string }

carrySelfFields(wantedInstances: { WantedInstance }, heldInstances: { HeldInstance }) → void

The record's instances, each coming back carrying what the held instance it replaces wrote about its own runtime (the fields the build captured it writing, such as an avatar's map of the bones it expanded into). A restate of a type whose statement is unchanged lands the record's values; the component's own bookkeeping is none of them and no `kept` entry names it, so the instance put back keeps it and re-derives what it produced onto the same entities. Matched the way `carryHeldData` matches.

argtypedescription
wantedInstances{ WantedInstance }
heldInstances{ HeldInstance }

stateRecordedTypes(rid: string, rec: any) → boolean

State every component type the record names as the build's own, whichever code attached the instance the entity holds of it. A component's lifecycle can attach a type the build also states: a component the build placed on one entity puts the collider it relies on onto another before that entity's record is applied, or after it. An instance that already matches the record is left running, so it keeps the provenance of that attach, and a code-attached instance is left out of the scene's unsaved edits and out of `scene.json`: play and the next load would come up without a component the build placed. Run once every record's components have landed, so an attach made by any component of the build is seen. Returns whether any of them was code-attached, which is a change to what the entity's saved record holds.

argtypedescription
ridstring
recany

lifecycleStatement(rec: any, participationOverride: string?) → void

What a record states about the entity's lifecycle mode (`m`), its replication scope (`w`), whether its live state replicates (`y`) and whether it is active (`o`), each as the text the baked record holds it in. A record naming none of the first three states an ordinary local world entity, and one naming no active flag an active one. `participationOverride` states one mode for a whole record set and wins over what a record carries.

argtypedescription
recany
participationOverridestring?

applyLifecycle(rid: string, stated: { [string]: string }, prev: { [string]: string }, merge: Merge) → void

Land the lifecycle mode, the replication scope and whether the entity's live state replicates the way the rest of a record lands: a value the code now states differently is written, and one it states the way it did last time is left as the scene holds it and noted in `merge.kept`. A record that stopped naming one states the default, which is a change the code made.

argtypedescription
ridstring
stated{ [string]: string }
prev{ [string]: string }
mergeMerge

noteLanding(key: string, landing: Landing) → void

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. started the build, and a function answering whether the build is still being carried out.

argtypedescription
keystringThe key the scene is known by: its guid, else its path.
landingLanding`{ scene, startedBy, advancing }`: the scene's name, what

examples

SceneBuild.noteLanding(guid, { scene = "main", startedBy = "a write to build.luau", advancing = function() return true end })

landed(key: string, landing: Landing) → void

Record that the build `landing` stands for is through. An entry a later build of the same scene put in its place stands.

argtypedescription
keystringThe key the scene is known by.
landingLandingThe entry `noteLanding` recorded for this build.

examples

SceneBuild.landed(guid, entry)

landing( ) →

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.

examples

if #SceneBuild.landing() == 0 then engine.mode = "play" end

landingFor(scene: { guid: string?, path: 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.

argtypedescription
scene{ guid: string?, path: string? }`{ guid, path }` of the scene, either one or both.

examples

while SceneBuild.landingFor({ guid = ref.guid, path = ref.path }) do task.wait() end

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.

argtypedescription
erranyThe value a build raised.

examples

local refused = SceneBuild.isStatedNothingRefusal(err)

enterLayer( ) → void

leaveLayer( ) → void

afterBoundary( ) → void

Past a frame boundary, the reconcile goes on only while it is still the newest of its build at its destination, and an entity it lands under still stands.

eachRecord(count: number, step: (number) → void

Run `step` over `1..count`. Spread, the steps go in shares of the frame's remaining budget, a frame boundary between one share and the next; the active layer is handed back across each boundary, so nothing else that runs in between spawns into this build's layer.

argtypedescription
countnumber
step(number

stillPlaced(rid: string) → boolean

Whether a record's entity is still there to finish. Once a frame boundary has passed, the frames before it were frames anything else may run in, and an entity somebody removed in them is theirs to have removed.

argtypedescription
ridstring

place(index: number) → void

argtypedescription
indexnumber

passes( ) → void

⌬ Types
Refusal = {Kept = {Driven = {HandAdded = {HandPlaced = {BuildSurface = {Drift = {Landing = {

Sub-parts

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

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

68+items
·
assettype · born here
❒asset
# Module (asset type) A module is a reusable, stateless (or globally-stateful) Luau library that other code pulls in with `require()`. Modules are the unit of factored-out logic in a world: helpers, math libraries, format parsers, registries, shared algorithms. ## When to use one - You have logic you want to share across multiple components, services, scenes, or tools. - You have a registry, lookup table, or shared cache that callers all read from / write to. - You want a stable API surface (`M.fn`) other code can depend on. If the logic is bound to one entity, use a `.component`. If you want a named UI of fields rather than functions, use a `.preset`. ## Where it lives - Source: `/zero/source/.../<name>.module/` - Identity: the source path with `/` written as `.` and each segment's type suffix dropped — `/zero/source/demo/beats.module` is `demo.beats`, and `/zero/source/kit.package/beats.module` is `kit.beats`, the container's name kept and its `.package` suffix gone. `asset.create` returns this string, `asset.resolve(...).identity` reads it back, and the `require` forms below write it as `<identity>`. - Folder shape: - `init.luau` (or `init.lua`) — module body. **Required.** Returns a table (conventionally named `M`). - `README.md` — instance-level documentation. **Required.** - `.metadata` — agent-editable tags + free-form fields. **Required.** ## How to create one ```luau asset.create("module", "<name>") -- Creates: /zero/source/<name>.module/ -- init.luau (canonical `local M = {} … return M`) -- README.md (instance README template) -- `folder` places it in a subfolder of /source, and that subfolder -- leads the identity: `{ folder = "lib" }` produces `lib.<name>`. -- `into` authors it inside a resolved container (a package, a toolbox), -- whose own identity leads the same way: asset.create("module", "<name>", { folder = "lib" }) asset.create("module", "<name>", { into = asset.resolve("myPkg.package") }) ``` ## How it operates 1. **Registration.** Writing `init.luau` into a `.module/` folder indexes the asset and registers the module path with the resolver. 2. **Loading.** The first `require("<identity>")` runs the file's body and caches the returned table. Subsequent requires from anywhere return the **same table** — this is the shared-state lever for "module-local" registries. The body runs in an environment of the module's own: a name it declares without `local` is readable by the module's own functions and by no other script, so an export reaches its callers through the returned table and nothing else. Requiring a component's folder runs its chunk the same way, once, and its `update`, `start` and `public` stay in that environment; a component runs on an entity through `entity(id).component.add(name)`. 3. **Hot reload.** Editing the file re-runs the module body and folds what it returns into the table already loaded, so that table keeps its identity: a caller that captured it with `require` reads the new source's functions and values through the reference it already holds, and a later `require` returns that same table. A key the new source drops goes away; a key something set at runtime stays. The body's own `local`s start again from their initial values, so state that must outlive an edit lives in `modules.state()` (`guides { path: "core/scripting-and-tasks" }`). 4. **Identity resolution.** A module is reached by its `<identity>`, and where the caller lives decides which spelling of it resolves. For a module in a **world**, from a caller in that same world — another module, a component, a scene entrypoint, or an `execute` chunk: - `require("<identity>")` — the identity on its own, resolved against the caller's own root. It carries every folder segment, so a module created with `{ folder = "demo" }` is `require("demo.beats")`. - `require("@root::<identity>")` — the same root-relative resolution, written out. - `require(".sibling")` — a module in the same folder, by its bare name; `..name` steps up one folder, `...name` two. Logs, stack traces and hot-reload notices name that same module `@local.source.<identity>` — its key under the world source root. The `<identity>` tail of that key is the form above, so a trace reading `@local.source.demo.beats` is `require("demo.beats")`. For a module in a **library** — content under `/zero/source/libs/@<lib>/` — `@<lib>::` addresses that library's root from anywhere: `require("@builtin::modules.transform")`. Mounting a world as a library moves its files under such a root and flips the caller root to `@<lib>::`, which is what keeps the root-relative forms above resolving across the move. ## Discovery - `asset.list("module")` — every registered module. - `asset.inspect("<name>")` — public functions, source path, this type README. - `ls /zero/source/<name>.module` lists the files the folder holds. ## Authoring conventions - Return a single `M` table from `init.luau`. Top-level statements with side effects run on first require — useful for one-time initialization, dangerous if they touch the engine before it's ready. - Write exported functions as `typed function`, not `function`: the argument types are enforced at the call and the checker knows the signature, so a caller's mistake is reported where they made it. - Annotate exported functions with `--!desc` / `--!arg` / `--!return` / `--!example` so the LSP, `tools.list`, and `asset.inspect` surface them. A function with no `--!desc` is reachable only by someone already reading this file. - Declare a VALUE with `Field.<kind>(default, mode, description)`, and a table whose members are reached through a metatable with `--!members <TypeName>` — the latter gives the surface its accepted member set, its type, and its documentation from one table. See `guides { path: "core/authoring" }` for all four rules and `modules/api/engine/entity.module/members.module` for a worked member table. - Keep module state in module-local upvalues or in `modules.state()`. A name the body declares without `local` lives in the module's environment, which every run of the module shares: a function the previous run left in place reads what the reload assigned. Module-locals start again from their initial values with each hot reload; the table `modules.state()` returns is the same table on both sides of every reload. - Prefer focused modules over kitchen-sink modules. If two halves of a module have no shared state, split them. ## Common pitfalls - **Cyclic requires.** A `require` chain that loops will return the partial table (the half built before the cycle was detected). Design for one-way dependencies. - **Engine-time side effects.** Don't `entity.spawn` at module top-level — the engine may not be ready. Expose an `M.init` and call it from a scene entrypoint. - **Hot-reload + module-local cache.** A module that caches expensive computation in upvalues loses that cache on reload — fine for dev, but be aware in performance work. - **`init.lua` vs `init.luau`.** Either works, `.luau` is canonical. - **Writing one while play runs.** A `/source` write made while play is running lands on the play shadow, and a guarded play-exit discards it unless it is kept. One `.module` write shadows `init.luau`, the `README.md` and the `.metadata` together. `vfs.write(path, bytes, { durable = true })` skips the shadow, and `vfs.promotePlayShadow` keeps what is already on it — the `core/vfs` guide has the model and what each route costs. ## Related types - `.component` — for entity-bound state + lifecycle hooks. - `.service` — generates content you don't have yet (a mesh, sound, texture, …) via a metered provider. - `.tool` — for a single agent-callable function with a YAML schema. - `.package` — to group several modules + components + scenes into one shippable folder. ## In the Inspector Exports: what the module exports (name, kind, signature), parsed from its source without running it, with **Check** (the LSP's diagnostics for its entry file) and **Open**.
▲ 0↑ born
▣
module · born here
❒asset
# Source bindings Captures editable inputs supplied by builders, remaps their generated output ids to persistent scene ids, and retains exact source revisions for later checked edits. ```lua local Bindings = require("@builtin::modules.sourceBindings") local inputs, result = Bindings.capture(function() Bindings.attach(target) -- target from SourceEditing.bind return "built" end) local registry = Bindings.pack({{owner="build",targets=inputs,placements={captured="persistent"}}}) local available = Bindings.list(registry, "persistent") local reopened = Bindings.resolve(registry, "build", available[1].id) ``` Inside a scene build, `build.source()` returns the exact `build.luau` snapshot being evaluated, including proposed source during candidate preparation. Use it with `SourceEditing.calls` to locate editable arguments, then call `build.bindSource(target)` after creating the entities named by the target. The scene captures these registrations, maps their outputs to persistent placements, and saves the registry in `authoring/state.json` under `build.bindings`. Source files discovered through bindings join the transaction read set; a changed original input or edit record refuses the build. A tool can reopen that saved registry with `Bindings.resolve` to prepare a checked source replacement. The registry deduplicates source versions by asset guid and stores their exact-byte SHA-256 revisions. Resolving an input follows its asset identity to its current path and refuses changed bytes. Repeated registrations of one owner/input id combine known outputs only when their source occurrence and scope agree. Every output must occur in the supplied placement map. Scope completeness remains explicit. Nested capture scopes keep their registrations separate and restore the outer scope after an error.
▲ 0↑ born
▣
module · born here
❒asset
# Field edits Scene authoring uses FieldEdits to keep structured field intent separate from generated data. Each edit carries a path, the value that field was based on, and the authored value, with explicit presence flags for additions and removals. ```lua local Fields = require("@builtin::modules.fieldEdits") local base = {position={0,0,0}, light={intensity=1}} local visible = {position={2,0,0}, light={intensity=1}} local edits = Fields.diff(base, visible) local rebuilt = Fields.compose({position={0,0,0}, light={intensity=3}}, edits) assert(not rebuilt.blocked) assert(rebuilt.value.position[1] == 2) assert(rebuilt.value.light.intensity == 3) ``` - `copy(value)` validates and copies structured data without sharing mutable tables. - `diff(before, after)` creates deterministic field edits. Objects merge by string key; arrays and asset references are atomic values. - `compose(generated, edits)` applies authored values and reports divergence from their stored baseline. Missing parents, missing edited targets and conflicting root additions block the result. Satisfied paths identify intent the generated value already matches. - `update(generated, previous, current, edits)` records a new authoring operation while retaining existing baselines and satisfied intent. An addition followed by its removal cancels that addition. - `updateChanges(generated, current, changes, edits)` records original observed changes against their merged visible result. A change already satisfied by the current generated value remains an authored intent for subsequent builds. - `keep(generated, edits, paths?)` acknowledges reviewed generated changes while retaining the authored values at the selected exact paths. Inputs are copied, edit paths are non-overlapping dense arrays of strings, and values are finite serializable data with bounded nesting. Scene-level hierarchy, reference and component validation belongs to the scene composer consuming these field results.
▲ 0↑ born
▣
module · born here
❒asset
# component_snapshot Serialized snapshots of script-component public data. A component's `public` table is a live proxy — its fields live behind `__iter` / `__index` metamethods, so copying or JSON-encoding the proxy directly yields an empty table. This module materializes the plain, serializable form. It is the script-component parallel to `ecs.snapshot` (native components). ```lua local componentSnapshot = require("modules.component_snapshot") -- one component: live proxy -> plain table local data = componentSnapshot.snapshot(entity(id).component.get("Camera")) -- whole entity: { [type] = data }, named/multi instances nested as -- { [type] = { [instanceName or "__default"] = data } } local all = componentSnapshot.snapshotEntity(entity(id)) ``` `componentSnapshot.plainCopy(value)` materializes ONE live value the same way — a table behind a proxy is walked into a plain table, every other value passes through — for callers reading a single field rather than a whole component. Serialized form: entity refs become id strings, asset refs become `{ __ref, name, type }` envelopes, vectors and colors their plain-table forms; framework functions are omitted. `snapshot` returns nil for a proxy with no serializable fields. Persistence (scene serializer, bundle capture, prototype spawn) and inspection tooling (`debug.inspect`) read component data through this module. Live gameplay reads and writes stay on the proxy itself via `entity(id).component.get` / `getAll`.
▲ 0↑ born
▣
module · born here
❒asset
# `scene.shared.loader` Luau-side scene loader. Reads `scene.json` v6, dispatches to engine FFIs, runs the sibling `entrypoint.luau`. ## Public surface ```lua local loader = require("@builtin::assetTypes.scene.shared.loader") loader.load(ref, opts?) -- ref: AssetRef<scene> | identity string | VFS path -- opts.layer: layer name (default "main") -- Returns: the Scene proxy (with player_config + camera_config attached). loader.unload(layerName) -- Wrapper around layers.unload(name); symmetric to M.load. -- Cannot unload "main". ``` ## Behavior 1. Resolve `ref` to a VFS path; append `/scene.json` if needed. 2. `vfs.read` + `Json.decode` (from `modules.json`) → body table. 3. Version check — refuse anything but `version: 6`. 4. Attach `body.player` + `body.camera` to the Scene proxy as `player_config` / `camera_config` (consumed by player_spawner + camera_spawner). 5. Activate the target layer via `layers.find(layerName)` (the loader threads the layer through `entity.spawn` opts), spawn `body.entities` in two passes (shells + transforms first, parents + components second), then restore the previous active layer. 6. Apply `body.lighting` via `lights.setup` + `lights.addPointLight`. Field name mapping: `directional` → `sun`, `clear_color` → `clearColor` (both engine API names and v6 field names are accepted). 7. Auto-discover sibling `entrypoint.luau` via `vfs.exists`; if present, compile with `loadstring` + run. ## Performance ~5 ms for a 1000-entity scene (≈5k FFI calls × ~1 µs each). Acceptable for a load-time operation. If a particular call class becomes hot, batch primitives can be added in a narrow follow-up. ## Why pure Luau Per § 10 of the unification integration design, the scene format is data + dispatch — no Rust-only primitives needed. The existing ECS FFI (`entity.spawn`, `entity(id).component.add`, etc.) covers everything. Keeping the loader in Luau means iteration speed, auditability, and hot-reload. ## FFI corrections vs. the original plan The plan was drafted against assumed API names. The actual engine FFIs differ: | Plan assumed | Actual engine API | |---|---| | `json.parse(s)` | `require("..json").decode(s)` (`modules.json`) | | `json.encode(t)` | `require("..json").encode(t)` | | `entity.spawn(n, { layer }).id` | layer activation via `layers.find(layer)` + `entity.spawn(n, opts).id` | | `entity.setParent(id, pid)` | `entity(id).setParent(pid)` | | `unloadLayer(name)` | `layers.unload(name)` | | `lights.setup({ directional })` | `lights.setup({ sun })` | | `lights.setup({ clear_color })` | `lights.setup({ clearColor })` | | `lights.addPointLight(table)` | `lights.addPointLight(name, x, y, z, opts)` | The loader accepts both the v6 field names and the engine API names for the lighting fields so that round-tripping through the scene saver and back works without a conversion step.
▲ 0↑ born
▣
module · born here
❒asset
# entity_records Walks a live entity hierarchy into the flat record array the engine's entity templates use — `{ name, original_id, parent_id, position, rotation, scale, hidden, components }` per entity, root first, parents before children. `bundle` composes its `entity_template` through this module; scene builds compose their baked output through it. One record shape, one implementation. `compose(rootId)` walks one hierarchy. `composeMany(rootIds)` walks several, which is what a build needs — a builder may leave more than one unparented root. Temporary descendants are pruned; an explicitly-named temporary root is kept. `compose(rootId, nil, nil, true)` keeps the temporary descendants too, so the records hold every entity under the root.
▲ 0↑ born
▣
module · born here
❒asset
# `scene.shared.saver` Luau-side scene saver. Writes `scene.json` v6 — **authored intent only**. No captured runtime state. ## Public surface ```lua local saver = require("@builtin::assetTypes.scene.shared.saver") saver.save(name, opts?) -- name: logical scene name ("main") OR full VFS path -- opts.layer: layer name to read from (default layers.active.name or "main") -- Returns: the absolute VFS path written. ``` ## What is captured | Field | Source | Notes | |---|---|---| | `format`, `version` | constants | Always `"scene"` + `6`. | | `entities` | `entity.findAll()` walk | Excludes `temporary` entities + the spawner-managed Player + primary Camera. | | `entities[].transform` | local position / rotation / scale | NOT world transform — local only. | | `entities[].components` | component.list + component.get | Strips `_`-prefixed runtime fields. | | `entities[].attributes` | `attribute.list` + `attribute.get` | The entity's key/value bag, written as a `{ [key] = value }` map; omitted for an entity that holds none. Holds the authored keys — a `_`-prefixed key is the engine's own session bookkeeping. | | `lighting` | `lights.snapshot()`, filtered | Scene-level `clear_color` + `sky` only. Directional / ambient / point lights persist as `Light` entities in `entities[]`. | | `player` | `sceneProxy.player_config` | Carried forward from load-time, authored only. | | `camera` | `sceneProxy.camera_config` | Carried forward from load-time, authored only. | ## What is NOT captured - Local player's position / rotation. Runtime drift; not authored intent. - Primary camera's transform. Runtime; behavior-driven. - Any entity flagged `temporary = true`. Debug helpers, runtime markers. - Internal component fields prefixed with `_` (e.g. `_velocity` on CharacterController). The spawner-managed entities (Player + primary Camera) are excluded because they're created on load by player_spawner / camera_spawner from the scene's declarative `player` + `camera` blocks. Saving them would double them on the next load. ## Parts The module is a folder of parts, each a module of its own that `init.luau` requires: - `scene_saver.serialize`: one live entity as the record a scene file carries. - `scene_saver.recordDiff`: the comparisons the record diffs are built from. ## When to use `layers.active:save(name)` (Phase 6) routes through this module. Callers that want a state snapshot (save-game systems, undo stacks) should use `world.debugSaveToDisk(...)` instead — that captures runtime state by design.
▲ 0↑ born
▣
module · born here
❒asset
# Scene record projection Require `@builtin::assetTypes.scene.shared.records`. `saved(record, componentGuid)` converts a persisted entity into `{value, bookkeeping}`. `captured(record, ids, componentGuid)` converts an entity-record capture and remaps captured entity references to persistent placement ids. The resolver receives a component type spelling and returns its stable identity; unresolved types must raise an error. Captured entities require an entry in `ids`. `value` holds editable fields with normalized transform and lifecycle defaults. Components are grouped by stable type identity: `named[name]` addresses one named instance, while `anonymous` preserves an ordered group. Saved `instance_index` markers are reconstruction metadata, and restoration emits them alongside named `instance_name` markers. FieldEdits treats that anonymous array atomically. Asset references compare by guid and type. Component references retain their entity, instance information and stable component type. `bookkeeping` holds build ownership attributes, component order, and captured reference paths and row-field declarations. These capture annotations describe reconstruction and stay outside field comparisons. Compose edits over `value`, then call `restore({value=composed, bookkeeping=current.bookkeeping}, componentName)` to produce the saved record. The reverse resolver supplies the current component type spelling. Surviving instances retain their order; added instances are appended in deterministic order. The module validates structured input before copying it. Duplicate named instances and missing identities fail before any scene mutation.
▲ 0↑ born
▣
module · born here
❒asset
# assetType.shared.ref Builds the metatable every `AssetRef` (the `{ __ref, type, name, guid, identity, path }` envelope returned by `asset.resolve` / `asset.ref`) carries. Replaces the per-call C metatable that used to live in `crates/zero_scripting/src/ffi/bindings/asset.rs::attach_asset_ref_metatable`. ## Public API ```lua local assetRef = require("@builtin::assetTypes.assetType.shared.ref") -- Called by the Rust factory (push_asset_ref_handle) via -- _G.__build_asset_ref_proxy after the envelope fields are set. assetRef.build(envelope) -- attaches AssetRefMT, returns the table ``` The module exposes no invalidation surface — discovery is registry-driven and hot-reload is transparent (see "Discovery and hot-reload" below). ## Method dispatch order `ref.foo` is resolved in this order: 1. **Default methods** — `getSource` / `getBytes` / `getText` / `exists` / `inspect` and the lazy `meta` property. Per-type definitions cannot override these (engine contract from gh#1889). 2. **Per-type `ref` table** — discovered through `asset.resolve(<typename>, "assetType")` + `require(<identity>.behavior)`. The lookup resolves to whichever `<typename>.assetType/` folder is currently registered for the typename (built-in, user, or library-vendored) and pulls its `ref` methods. 3. **Nil** — unknown key, same shape as the original C metatable. ## Adding methods for a new asset type Drop a `behavior.luau` into the type folder: ``` src/lua/lib/assetTypes/<typename>.assetType/ ├── type.yaml -- structural spec (existing) ├── behavior.luau -- ref + global behaviour (new) └── template/ -- placeholder body (existing) ``` `behavior.luau` returns: ```lua return { ref = { --!desc Per-instance method on every `<typename>` AssetRef. myMethod = function(self, ...) ... end, }, global = { -- Reserved for the asset.<typename>.* surface — not consumed -- yet; included so the contract from gh#1889 lands cleanly. }, } ``` Within `ref` methods, `self` is the AssetRef envelope: `self.path`, `self.identity`, `self.guid`, `self.type`, `self.name` are available. Engine-required fields (`guid`, `path`, `identity`, `type`) must not be redefined. ## Discovery and hot-reload Type discovery uses the asset registry, so it doesn't matter where a `<typename>.assetType/` folder lives — engine built-ins under `@builtin::assetTypes.<X>`, user types dropped under `/zero/source/<X>.assetType/`, or types vendored inside an imported library all resolve identically. The dispatcher walks `asset.resolve(<typename>, "assetType")` → canonical identity → `require <identity>.behavior` on every miss; the asset registry is the cache for the resolve half and Luau's `_LOADED` is the cache for the require half. Hot-reload is transparent. When a `<typename>.assetType/behavior.luau` is rewritten through VFS, the engine's `invalidate_require_cache_for_state` re-runs the module and mutates the cached `_LOADED[<identity>.behavior]` table in place. Dispatch reads `mod.ref` on every access (rather than caching a sub-pointer), so existing AssetRefs see the new methods on the very next access — no Rust-side hook into this module is needed, and no invalidation API is exposed for callers to call. The same registry-driven path also handles type **registration** correctness: dropping a new `<typename>.assetType/behavior.luau` updates the asset registry, the next `asset.resolve(<typename>, "assetType")` returns the new ref, and AssetRefs of that type immediately gain the new methods. ## Why Luau, not Rust The asset surface needed per-category behaviour (`material:getProperties()`, `bundle:instantiate(entityId)`, `tool:run(args)`) and the old shape couldn't grow without an FFI change per method. Owning the proxy in Luau means: - Type-specific methods ship as content (the `<typename>.assetType/` folder), not engine code. - Adding a new asset type drops in a new folder; no Rust rebuild. - Methods can call any other Luau global (`vfs`, `asset`, `Material`, `entity`, etc.) directly, instead of going through narrow FFI primitives. ## Consumers - `crates/zero_scripting/src/ffi/bindings/asset.rs::attach_asset_ref_metatable` — the Rust factory that pushes envelopes invokes `_G.__build_asset_ref_proxy` once per push. - Every Luau call site of `asset.resolve` / `asset.ref` / `entity(id).component.X.material` / any binding declared `AssetRef<...>` — they all receive envelopes built through this module.
▲ 0↑ born
▣
module · born here
❒asset
# defaults 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. A component row's filter reads the entity's hierarchy path (names from the root down, joined with `/`). What a scene build's capture scope adds takes the rows in any mode, whoever runs the build; outside a build, a component takes a row when it is added in edit mode. A component put back from existing content takes none: one added inside `materializing` (a saved scene, a peer's record, a template clone, a bundle's hierarchy, a build's records), and one a component's own code adds outside a build, on any coroutine that code runs. A scene build records which fields the rows gave each component, and a rebuild restates a component only when the code states it differently, so a row edit alone changes nothing a build already placed. Rows are written as guid envelopes and checked as a whole. A row is refused when its target does not resolve, is consulted at no creation, or declares no settings; when its preset does not resolve, is not a preset, or targets another declarer; or when its filter is not a string. A write replaces the `[[presets]]` block and keeps the rest of the file byte for byte. ## The row format ```toml [[presets]] target = { __ref = "8cc28fc8-ed63-48ee-83a6-15f4192e27e1", type = "importer", name = "texture" } preset = { __ref = "0b6c1f0e-5d0c-4d5e-9d64-3c1b7f2a9e11", type = "preset", name = "pixel_art" } filter = "sprites/**" ``` `target` and `preset` are guid envelopes: `__ref` is the guid, and `type` and `name` tell a person reading the file what it names. A row written by hand may name either by identity or guid; the next write rewrites it as envelopes. `.world_settings`'s `.refs` pins each row's target and preset by guid. ## Matching For a new thing a declarer governs, the rows are read in order and the first naming that declarer whose filter matches the thing's path applies; the rest are not consulted. A filter is a glob (`preset.glob`) over the path relative to `/source` with forward slashes, or an entity's hierarchy path for a component row; the empty filter matches everything, and a filter that is not a string matches nothing. A matching row whose preset does not resolve, or targets another declarer, is the match and contributes nothing, with one warning. A preset value the declarer's schema rejects is left out and the rest apply. ## Sync The rows are part of `.world_settings`, so they sync with the world like any other file and every peer reads the same rows. A row applies where the creation happens, when it happens: a peer's edit reaches only what is created after it arrives, and what was created before keeps the settings it was stamped with. A runtime asset lives for the engine process; a peer that started before a row edit keeps its old settings on a re-created runtime identity until it restarts. ## Exports - `Defaults.PATH`, `Defaults.BLOCK` — the file and the array-of-tables name. - `Defaults.SCHEMA` — the block's Field schema, `{ presets = Field.list(row) }`. - `Defaults.rows() -> { Row }` — every row, resolved, with its problems. - `Defaults.write(rows)` — normalise, check, and replace the rows. - `Defaults.normalize(input) -> StoredRow` - `Defaults.rowProblems(row) -> (problems, targetRef, presetRef)` - `Defaults.consultedAt(declarer) -> "asset.create" | "import" | "component.add" | nil` - `Defaults.relativePathOf(path) -> string?` — the path a filter reads. - `Defaults.match(declarerGuid, relPath) -> (Row?, index?)` - `Defaults.layerFor(declarerGuid, relPath) -> (values?, Match?)` - `Defaults.check(value, constraint) -> (ok, reason)` — the `presetDefaultRow` constraint. - `Defaults.removeAt(index)` — remove one row, writing every other row back as the file holds it. - `Defaults.importerSettings(importerRef, sourcePath) -> (settings, Match?)` - `Defaults.materializing(fn, ...) -> ...` — run `fn` with no row reaching a component add. - `Defaults.entityPath(id) -> string` — the hierarchy path a component row's filter reads. - `Defaults.forComponent(entityId, typeName, data?) -> data?` — the data a component add takes. - `Defaults.batchLayers(targets, typeName, data?) -> { { targets, data } }` — a batch add split into runs. - `Defaults.resolveValue(v) -> AssetRef?` — a row value as the asset it names. - `Defaults.recordingStamps(fn, ...) -> (stamps, ...)` — run `fn` and return what the rows gave the components a capture scope added meanwhile, per `stampKey`. - `Defaults.stampKey(entityId, componentGuid, instanceName?) -> string` The `preset` global exposes the rows as `preset.defaults`, `preset.setDefaults`, `preset.addDefault`, `preset.removeDefault` and `preset.defaultFor`.
▲ 0↑ born
▣
module · born here
❒asset
# frame_budget The share of a frame that cooperative engine work spends before it hands the frame back. Some engine work is one long sequence of small units run on a task: a scene load applies one record after another, and the world-load `onRegister` sweep fires one instance's hook after another. Run back to back in one frame, a long sequence holds that frame for its whole length, and nothing else the engine does (answering a call, drawing, input) happens until it is through. Asking `due()` before each unit and yielding when it answers true runs the same work across as many frames as it needs, a slice of each. ```luau local FrameBudget = require("@builtin::modules.frame_budget") for _, item in ipairs(items) do FrameBudget.yield() process(item) end ``` - **One slice per frame, shared.** Each caller is charged the time it runs between its readings of the slice in a frame (`task.runTime`), whoever runs it, and the charges of every caller add up to the frame's slice. What the rest of the frame runs (systems, components, other tasks) is not charged, so a busy frame still gives the slice to the work. Two long pieces of work running at once share a frame's slice rather than taking one each. - **A unit is never split.** The first unit of a frame always runs, so a frame holds at most the slice plus the one unit that crossed it. A unit that is itself long stays one piece of work. - **Code that cannot yield runs in its frame.** `due()` answers false outside a coroutine that can yield, so a caller called from such code does all its units in the frame it was called in, as it would without the budget. A caller that does work of its own around the yield asks `due()` and calls `wait()`, which yields to the next frame and opens that frame's slice as the caller resumes; `yield()` is the two together. Work whose unit is a native call that bounds itself by time is told how long it may run: `remainingMs()` answers what is left of the current frame's slice, or nil for code that cannot yield, which then runs the whole of its work in the frame it was called in. The publish gate's script check runs this way: ```luau local block, checking = __spacetime_vcs.scriptPublishBlock(FrameBudget.remainingMs()) while checking do FrameBudget.wait() block, checking = __spacetime_vcs.scriptPublishBlock(FrameBudget.remainingMs()) end ``` ## The background lane Some work is started early so it is ready when asked for, and no picture waits on it, such as the search text an editor reads ahead of the first `tools.search`. `background(fn)` runs `fn` on the background lane: every `yield`, `due` and `wait` its work makes on that coroutine hands the frame back for as long as a hold on the lane stands, and takes its slice as usual once none does. ```luau FrameBudget.background(function() for _, path in ipairs(paths) do FrameBudget.yield() warm(path) end end) ``` Work the picture waits on holds the lane while it runs: `holdBackground(key)` until `releaseBackground(key)`. A world's entry holds it under `"world entry"` from the moment the world is ready (its `onRegister` sweep) until its `onWorldLoad` has returned, so the frames of the entry carry the world's load and the background work runs in the frames before and after it. A hold no one releases lapses after `BACKGROUND_HOLD_SECONDS` (or the seconds it was taken for), with a warning naming its key, so work on the lane always runs in the end. `backgroundHolds()` lists the keys holding the lane now, and `backgroundWaits()` answers whether the calling code's next unit waits for it (a walk with a clock of its own asks it between its pieces). `FrameBudget.DEFAULT_MS` is the slice a call that names none spends. `spent()` answers how much of the current frame's slice is gone. A caller with a budget of its own reads `mark()` where its work starts. `ranMs(mark)` answers how long it has run since, none of the time it spent suspended; `cpuMs(mark)` answers the CPU time of its work since: those stretches and the stretches of every coroutine it resumes, and every one they resume, while it waits on them, which a machine whose cores are taken by other work does not stretch, so a bound that refuses work for running too long refuses the same work on a loaded machine as on an idle one, and work handed to a coroutine as work run in place. A task it starts and waits for runs while it is suspended, which `cpuMs` does not count.
▲ 0↑ born
·
assettype · born here
❒asset
# assetType (asset type) An asset type says what a kind of asset is: the files an asset of the kind is made of, the code that gives it behaviour, the interface a person uses to work with it, and how it is found, pictured and checked. A `<typename>.assetType/` folder declares a type called `<typename>`, and every `<name>.<typename>/` folder is an asset of it. `assetType` is itself a type, so a type is an asset like any other: it is created, versioned, installed and contributed the same way. ## Making a type `asset.create("assetType", "<typename>")` scaffolds a type. The type registers the moment its folder is written, anywhere under `/zero/source/`, and from then on `<name>.<typename>/` folders are its assets. An asset of a type that is not registered yet is not an asset, so make the type first. A type folder is a root: `~.x` in any file inside it names the type's own `x`, wherever the type is installed. Keep the type's whole implementation inside its folder and reach it that way. What a type folder must hold is set by this type's own `type.yaml`, the same way every type's `type.yaml` sets what its assets hold. `asset.validate` on a type reports anything missing, and the scaffold produces a folder that passes. ## What sets your type's schema (`type.yaml`) `type.yaml` is the structural contract every asset of the type is checked against. The keys below are the ones the engine reads; a key not listed here is ignored. | Key | What it controls | |---|---| | `suffix` | The folder suffix of the type's assets. Defaults to `.<typename>`. | | `primary` | The file or files that are the asset's content: what the asset resolves to when it is used. | | `entry_files`, `primary_aliases` | Further files that load as the asset or share its identity. | | `is_container` | Whether the suffix stays in the identities of what the asset holds. | | `is_opaque_walker` | Whether a walk of the tree stops at the asset and registers only its primary. | | `plural_dir`, `classify_exts` | Loose files in a folder of this name, or with these extensions, are assets of the type. | | `is_text_default` | Whether the asset's files are text unless stated otherwise. | | `broadcasts_subassets` | Whether assets nested inside an asset of the type are found by their own short name. | | `root` | `true` makes every asset of the type a root, so `~.x` inside one names that asset's own `x`. | | `contract_ref: { field, category }` | A key of the primary file that names another asset the asset is built on. | | `files: { required, optional }` | The files an asset holds (below). | | `allow_unlisted` | `false` reports every file the type does not declare. | | `aliases_from: [{ file, key }]` | Further names an asset answers to, read from its own files. | | `settings:` | Typed per-asset settings (below). | | `inspector:` | The interface people use for the type and its assets (below). | | `preview:` | How an asset is pictured (below). | | `references:` | Names of other assets the type's files carry (below). | | `indexing:` | What search reads for each asset (below). | | `describe:` | How a missing description is generated (below). | ### The files an asset holds Each entry under `files.required` or `files.optional` is `{ path, kind: file | folder, one_of_group?, content? }`. `*` in a path matches within one segment. Entries that share a `one_of_group` are satisfied by any one of them. `content` lists checks on the file's bytes: | Check | Passes when | |---|---| | `non_empty` | the file has content | | `json_field { key, type?, non_empty?, accept? }` | the JSON holds the key (a dotted path) with that shape | | `yaml_field { key, type?, non_empty?, accept? }` | the same for YAML | | `described { keys?, headings?, message? }` | the file says what the asset is (see "Ask your assets to say what they are") | Each check takes a `message`, which is what the author is told when it fails. ### Settings `settings: { values, schema: { type | instance, export? } }` gives every asset typed settings. `values` names the file an asset's values live in; `schema.type` declares one schema for the whole type, and `schema.instance` names a file each asset declares its own in. `asset.create` writes the resolved values, and a write to the values file reaches `onChange` with what changed. ## The human side (`inspector.luau`) A type is used by people through its Inspector, and without one the type is usable only from code. The Inspector is the type's interface for a person: for a procedural graph it is the graph editor, for a kit it is the tracking view of what the kit holds and what is still missing. Writing it is part of writing the type. `inspector: { type, instance? }` in `type.yaml` names the files. `type` is the interface for the type itself and for its assets; `instance` names a file an asset may ship to add its own. Each returns: ```luau return { sections = { { id = "graph", title = "Graph", build = function(ctx) ... end } }, replace = { contents = { ... } }, -- replace a default section by id order = { "graph", "contents" }, -- section order } ``` `build(ctx)` receives the asset and builds the section. A section's `title`, and the text its rows carry, is a string or an `i18n.text` value read from a catalog (`i18n.text("inspectors.mesh.title")`), which follows the editor's language. `asset.create("assetType", ...)` scaffolds a working `inspector.luau` to start from. `asset.validate` on a type that names no inspector, or names one that does not load, reports it. ## Say what your type is for (`about.yaml`) Every type carries an `about.yaml` that says what the type is for, in three plain-language texts: ```yaml intent: "Sets the typeface of the text in your game: UI, labels, signs and 3D lettering." function: "A font, from a TTF, OTF or WOFF file, made available to all of Zero's text, including 3D text." usage: "You choose it by name for your UI or your text, and the text appears in that typeface." ``` - **`intent`** is what the type is for in someone's game, in the words a game maker uses. Up to 800 bytes. - **`function`** is how it works today: what an asset of it is made of and what the engine does with it. Up to 1500 bytes. - **`usage`** is what a person or an agent does with one. Up to 1200 bytes. Write about the type as a whole, not one asset of it, and say what it does now. Agents read these texts to learn when to reach for the type and how; people searching find the type by them. The scaffold starts each text with `[[describe]]` and a note on what to write; a text that still starts that way counts as not written. `services describe` can write them. They show up in `asset.inspect` as `detail.about`, in `assetTypeRef:getAbout()`, at the end of the type's `types/<typename>` guide, and at the top of the type's Inspector. ## Ask your assets to say what they are A type can require each asset to carry a description: a file, written by the author or generated, saying what the asset is and what it is for. Declare it with a `described` check: ```yaml files: required: - path: "README.md" kind: "file" content: - { check: "described", message: "Say what this widget is for and where it goes." } ``` A file that is missing, empty or still has a line starting with `[[describe]]` fails the check, and so does a YAML file whose named `keys` are missing or over their `max_bytes`, or a Markdown file missing a named heading. `asset.validate` names the asset, and a push that carries it is refused with `message`. `services describe` finds such assets and writes their descriptions. `describe:` steers what is generated: ```yaml describe: guidance: "Say what the widget shows, what input it reacts to, and where it fits in a UI." examples: - "<identity of an asset of this type whose description reads well>" ``` An example is an asset of your type whose description is a true, written one, never a placeholder and never the asset being described; with none, leave `examples` empty. A type whose assets the model cannot perceive (a sound, a motion) says so in `guidance`, and the description is drawn only from what the asset's own files state. Start the file unwritten in your `template/`: a heading and one line starting with `[[describe]]`, never example content, which every new asset would carry verbatim. A type whose assets say what they are through their own content (a mesh, a texture) declares no check. ## The type's code (`behavior.luau`) `behavior.luau` returns one table. These are the keys the engine reads from it; anything else on the table is the type's own. ### What the type's assets can do | Key | Shape | What the engine does with it | |---|---|---| | `ref` | `{ [name] = function(self, ...) }` | Every function becomes a method on every asset of the type: `ref:name(...)`. | | `modules` | `{ [name] = require(".x") }` | Code the type's assets reach with `asset.containing(__FILE__).modules.<name>`. | | `events` | an events schema | Events an asset fires. Readers subscribe through `ref.events.<name>:connect(...)`; the type fires them. | | `refShapes` | `{ [method] = function(self) -> (typeExpr, source?) }` | The result type of a `ref` method for one particular asset (below). | | `namePattern` | a Lua pattern | The names `asset.create` accepts for the type's assets. Default `^[A-Za-z][A-Za-z0-9_]*$`. | | `derive` | `{ output, module, compute, fingerprint, matches?, required?, timeout? }` | A file computed from the asset when it is committed; a `required` one holds the commit until it lands. | Some `ref` names mean the same for every type, and the engine calls them: - **`instantiate(self, target?, opts?) -> (root, idMap)`**: puts the asset in a scene. Defining it is what makes the type scene-instantiable. Its return is a contract (below). - **`inspect(self) -> detail`**: what `asset.inspect` reports for the asset beyond the common record (below). - **`preview(self, opts)`**: renders the asset's picture; it wins over the type's `preview:` recipe. - **`previewMaterial(self) -> { material }`**: the material a `surface` preview paints. - **`saveDefinition(self)`**: writes the asset's in-memory edits back to its files in edit mode. Some names are answered for every asset before the type is asked, so a `ref` entry of the same name is never reached: `getSource`, `getBytes`, `getText`, `exists`, `deps`, `canInstantiate`, `canPreview`, `preview` (which calls yours when you define one), `meta`, `runtime`, `events`, `typeRef`, `modules`, and the residency flags `has_backing_asset`, `has_runtime_changes`, `cpu_resident`, `gpu_resident`. ### When the engine calls the type | Hook | Signature | When it runs | |---|---|---| | `onCreate` | `(name, opts) -> { [path] = contents }` | On `asset.create`. Returns the files of the new asset, laid over the type's `template/`. Annotate `opts`: its type is the schema `asset.create` checks the caller's arguments against. A `""` key writes a single loose file. | | `onReplace` | `(dest, files) -> files` | On an `asset.create` over an asset already at `dest`, after `onCreate`, so what the author added can be carried into the replacement. | | `onRegister` | `(self)` | Once per asset, when it first registers: when the world loads, on a live `asset.create`, and when an asset arrives later (installed, pulled, synced). This is what makes an asset take effect the moment it is written. | | `onChange` | `(ref, change)` | On every write to a file inside an asset of the type. `change` is `{ path, asset, type, kind, origin }`, plus `settings` and `settingsChanged` for a write to the settings values file; `kind` is `edited` or `seeded`, `origin` is `local` or `remote`. Filter on `change.path`. Writes to one asset arrive in order, each after the hook for the one before has finished, and the hook may wait on what it reads. A write the hook makes inside its own asset arrives later like any other, so keep the hook convergent. | | `onDependencyChange` | `(ref, change)` | When a module the asset's code requires is re-run, or a name the asset carries starts resolving. `change.kind` is `dependency`. | | `onDelete` | `(ref)` | When an asset of the type leaves the world: deleted, or the world it is in is swapped away. | | `validate` | `(ref) -> { { code, message, severity?, path? } }` | On `asset.validate`, after the `type.yaml` checks, for the type's own rules. `severity` defaults to `error`. Runs on every push, so a type's rules hold at publish. A hook that fails reports `validate.hook_failed`. | ### Settings hooks | Hook | When it runs | |---|---| | `settingsDefaults(name, opts, asked) -> table` | Once per `asset.create`, for values the schema's defaults do not give. | | `settingsCorrections(values, name, opts) -> (corrections?, reasons?)` | On every settings write. A correction to a field the writer named refuses the write, giving the reason. | | `settingsDerivedDefaults(values, explicit, changed)` | On a settings write, for fields derived from others. | | `normalizeSettings(values, stored?)` | On every read and write, to map an earlier spelling of a field to the current one. | | `settingsHealed(values, stored)` | On a read, to repair stored values. | | `settingsSchemaProblem(schema, ref) -> string?` | When an asset's own schema is read; a returned string refuses the schema. | `creationInputs` (`{ [opt] = true | selectorOpt }`) names `asset.create` options that are inputs to the type rather than settings. ### Reloading An edit to `behavior.luau` reaches existing assets with no restart. ## How an asset is pictured (`preview:`) | `kind` | The picture is | The type provides | |---|---|---| | `instantiate` | the asset placed in the preview studio through its `instantiate` | `ref.instantiate` | | `image` | a file the asset holds, fitted to the frame | `source: { files }`, the candidate files in order | | `surface` | the asset painted on a mesh | `mesh`, and `ref.previewMaterial` | | `custom` | whatever `ref.preview` returns | `ref.preview` | ```yaml preview: kind: surface mesh: sphere ``` `angle: [yaw, pitch]` turns the camera. The studio owns the light, the backdrop and the framing, so an asset pictures the same in every world. A type with no `preview:` that defines `instantiate` still answers `ref:preview()`. A picture is rendered when something asks to view it (the editor showing the asset, `ref:preview()`), when previews are generated on request (`assets.generatePreviews`), and when the asset is staged. An edit alone renders nothing. The picture records what it was made from, so a stale one is told from a current one. ## The names your type's assets hold (`references:`) Where your type's own format or API carries the name of another asset, declare it here: ```yaml references: keys: # a top-level key of the type's files that holds a name, or a table of them - { key: "shader", type: "shader" } args: # an argument of a call, counting from 1 - { call: "g:node", position: 2, type: "procNode" } fields: # a field of the options table a call takes - { call: "fx.beam", field: "material", type: "material" } ``` `type` is the category the name resolves in. `asset.declareReferenceKey`, `asset.declareReferenceArg` and `asset.declareReferenceField` declare the same from a script. ## What search reads (`indexing:`) `indexing:` is how assets are found. Search reaches an asset only through what its type's `indexing:` names, and adds nothing of its own. That includes you: an asset indexed badly is one you cannot find later, when you are making something else and need it. A type whose assets are never looked for says `indexing: none`. ```yaml indexing: data: # text, read from the asset's files - role: identity extractor: verbatim source: { file: "README.md" } - role: interface extractor: symbols source: { files: ["init.luau"] } - role: implementation extractor: verbatim source: { files: ["init.luau"] } content: # the picture - role: identity modality: image source: { file: "preview.png" } facets: # what a query filters and re-ranks by file: ".metadata" rigged: { type: bool, from: { components: { contains: SkinnedModel } } } roughness: { type: number, filter: range, from: { file: "mat.yaml", field: "floats.roughness" } } ``` **Roles.** Each `data` and `content` entry has a `role`, and a query matches in two slots: - **`identity`**: what an asset is. For anything you look at, the picture; for anything else, the text that says what it is. - **`capability`**: what it does and how it is made. `interface` (the signatures or shape a caller uses) and `implementation` (the body) both count as capability, and a type with code usually declares both. Ask what a person would recognise an asset of the type by, and what it does, and point each role at the file that says it. For text, that is the asset's description: the file your template starts with a `[[describe]]` block, which the author writes or `services describe` fills in (see "Ask your assets to say what they are"). **`data`.** `extractor: verbatim` embeds a file's text as it is; `symbols` embeds the declared signatures of code. `source` is `{ file }` or `{ files: [...] }`. Never index a file name (`source: { field: name }`): one or two words carry nothing to match. **`content`.** `modality: image` embeds the picture itself, so a text query matches what the asset looks like. A type whose assets are looked at makes the picture its identity. **`facets`.** What a query narrows and re-ranks the matches by. `file` is embedded whole, so keys nobody declared in it are still found. Each further key is computed for every asset and states a value for every one, including `false`: a file can imply "not rigged" but never say it, and a query separates rigged from unrigged only because the unrigged ones say `rigged: false`. A key is `{ type: bool | number | enum, filter?: range, from }`, where `from` is `{ file, field }` (a field of one of the asset's files, dotted for nesting), `{ metadata: key }`, or `{ components: { contains | any_outside } }` (what the asset's entities carry). ## What blocks a push A push checks every asset it carries against its type. These refuse it: - a required file that is missing, a `content` check that fails, a `described` file not written yet; - an error from the type's `validate`. Unlisted files and warnings do not. A `described` file blocks only a push that changes the asset. When a push is refused, the message names each asset and what it lacks. `world.publishBlockers()` and `zm status` read the same list without pushing. ## Typing a result from the asset (`refShapes`) A `ref` method whose result depends on the asset (one entry per child folder, per row of a config, per control a map declares) can only be annotated as `{ [string]: Thing }`, which accepts any key. `refShapes` states the result for each asset instead: a function returning a Luau type expression for that asset, and the module whose types the expression uses. Read the asset; never run it. ```lua -- inputMap.assetType/behavior.luau M.refShapes = { activate = function(self): (string, string) local names = {} for _, control in ipairs(M.ref.controls(self)) do table.insert(names, control.name .. ": Handle") end if #names == 0 then return "", "" end return "{ " .. table.concat(names, ", ") .. " }", "@builtin::modules.zinput.scheme" end, } ``` With it, `map.jump:onPressed(fn)` is checked and `map.noexisting` is reported. A per-asset type applies where the call site names which asset: a component field whose default names it, or an annotation `AssetRef<"inputMap", "<identity>">`. `asset.resolve(name, category)` carries only the category, and a name computed at runtime carries nothing, so calls on those keep the declared return. The type belongs to the call's result: index it there, or bind what you need from it there, and the names stay checked. `require("@builtin::assetTypes.assetType.shared.refShapes").published()` shows what was published: `categories` (each type's method surface) and `returns` (per-asset results by identity, then method). An identity missing from `returns` was never published. Results are recomputed when an asset is written; at most 64 assets of one type are read. ## Putting an asset in a scene (`ref.instantiate`) A caller writes one piece of code against every instantiable type, so what `instantiate` returns is fixed: ```lua local Instantiable = require("@builtin::assetTypes.assetType.shared.instantiable") M.ref = { instantiate = function(self, target, opts) local root = Instantiable.root(self, target, opts) -- compose the asset under `root`, now return Instantiable.result(self, root, idMap) end, } ``` **In.** `target` is the entity the asset lands under, or onto for a hierarchy type; with none, the type spawns a new root. `position`, `rotation` (three numbers in degrees, or a quaternion), `scale`, `name` and `temporary` mean the same for every type: `Instantiable.root` applies them to a root you make, `Instantiable.place` to one you adopt. Document any options of your own in the hook's `--!arg` docs. **Out.** `(root, idMap)`. `root` is the composed root, live when you return: build synchronously, never defer to a component's `awake`. `idMap` maps each original id to the spawned one, so a component that composes the asset again on every load can pass it back in and keep references into the composition. Every call goes through `Instantiable.result`, which refuses a root that is not live and turns a missing `idMap` into `{}`. ## Inspecting an asset (`ref.inspect`) `asset.inspect(ref)` builds a record every asset shares (`identity`, `name`, `guid`, `source`, `typeName`, `typeDefinitionPath`, `scope`, `origin`, `description`, `tags`), then calls `ref.inspect(self)` for the type's own `detail`: ```lua M.ref = { inspect = function(self) -- read the asset's own files, never runtime state: inspect works on an asset -- that has not been compiled, uploaded or registered return { --[[ what makes this asset what it is ]] } end, } ``` Without it, the record is the shared part alone, and an agent inspecting the asset learns nothing of what it is. A hook that raises leaves `detail` empty and sets `record.warning`. ## Discovery - `asset.list("assetType")`: every registered type. - `asset.inspect("<typename>")`: the type, its README and its `about.yaml` texts. - `asset.resolve("<typename>", "assetType")`: the type itself.
▲ 0↑ born
▣
module · born here
❒asset
# scene runtime What a `.scene` folder does when it is loaded, saved, built, or swapped. A `<name>.scene/` carries `scene.json` (the entity arrangement), an optional `build.luau` (the code author's half), an optional `entrypoint.luau`, and a `scene_dirty/` overlay of unsaved edits. Reading, composing and writing all four is the scene type's own behaviour, so it lives in the type. ## Sub-modules | Module | Responsibility | |---|---| | `loader.module` | Reads scene.json v6 and v7, refuses versions it does not know, composes canonical + dirty overlay, spawns the entities, and runs the entrypoint. | | `saver.module` | Persists scene state as a delta overlay against the canonical file, promotes that overlay on save, and answers which edits are still pending. | | `build.module` | Runs a `build.luau` inside an entity capture scope and composes what it spawned into scene records. | | `observe.module` | The read side — the per-scene counts and costs `layers` and `loader` write. | | `swapOrchestrator.module` | Drives multiplayer room transitions and the scene-swap gate, so a local swap does not leak despawns to peers in the old room. | ## Reaching it ```luau local rt = require("@builtin::assetTypes.scene.shared") rt.saver.hasPendingSceneEdits(layers.active.name) ``` Fields resolve lazily. The prelude installs `swapOrchestrator` and starts `saver`'s dirty writer in a fixed order, which a table that required all five on load would take away from it.
▲ 0↑ born
▣
module · born here
❒asset
# scene_saver.recordDiff The comparisons the saver's record diffs (`transformDiffLines`, `recordDiffLines`, the pending scene edits) are built from. - `diffEqual(a, b)` and `valuesEqual(a, b)` compare two record values, numbers within a tolerance that absorbs the f32 round trip of a live read. - `componentMatchName(t)` answers the name a component type matches by, whichever spelling the record used; `componentList(rec)`, `componentMatchNameOf(c)`, `componentInstanceLabel(c, typeName)` and `componentData(c)` read a record's components the way the comparison needs them, answering empty for a malformed record. - `selfWrittenFieldSet(entityId, componentType, instanceName)` answers the fields a component instance wrote about its own runtime. - `pushAttributeDiffLines(oldRec, newRec, push)` hands `push` one line per attribute added, changed or removed. ```luau local RecordDiff = require("@builtin::assetTypes.scene.shared.saver.recordDiff") assert(RecordDiff.diffEqual({ 1, 2 }, { 1.00001, 2 })) RecordDiff.pushAttributeDiffLines({ attributes = { hp = 1 } }, { attributes = {} }, print) -- - attribute.hp ```
▲ 0↑ born
▣
module · born here
❒asset
# scene_saver.serialize One live entity as the record a scene file carries, and the reads the saver asks of a live entity while it decides what to record. - `serializeEntity(id, parentById)` answers the record for a live entity: its name, parent reference, transform, components (each field value serialized), participation, network scope, render layer and attributes. A field holding a runtime GPU handle is reported once, with the remedy, and left out of the record. - `serializeFieldValue(v)` answers one component field value as a record states it, with the reason when the value has no record form. - `entityDisplayName(id)` answers the name an entity is shown by, and `entityIsTemporary(id)` whether it is marked as never saved. ```luau local Serialize = require("@builtin::assetTypes.scene.shared.saver.serialize") for _, e in ipairs(entity.findAll()) do print(Serialize.serializeEntity(e.id).name) end ```
▲ 0↑ born
▣
module · born here
❒asset
# assetType runtime The machinery that reads a `<typename>.assetType/behavior.luau` and turns its declarations into live behaviour. A `behavior.luau` is a table of declarations — `ref` methods, `modules` shared code, an `events` schema, a `namePattern`, `refShapes`, and the `onCreate` / `onRegister` / `onChange` / `onDelete` / `validate` / `settingsDefaults` / `settingsCorrections` hooks. None of it runs itself. This is the code that runs it, and it lives here because reading a type's declarations is the **assetType type's own behaviour** — the same way `material.assetType` owns what a `.material` does. ## Sub-modules | Module | Reads | Responsibility | |---|---|---| | `ref.module` | `ref`, `modules` | Builds every `AssetRef` envelope, attaches the shared metatable, and dispatches per-type methods and shared modules onto it. Also owns edit-mode write-behind persistence. | | `create.module` | `onCreate`, `namePattern`, `validate` | Backs `asset.create`: resolves the type, checks the name against its pattern, runs `onCreate` (or clones `template/`), and writes the instance. `validate.module` beside it checks a creation `opts` table against the type's `createSchema`. Before running `onCreate`, resolves the type's settings chain (below) and hands the result to the hook as `opts.settings`. | | `settings.module` | `settings`, `settingsDefaults`, `settingsCorrections` | A type's declared settings schema and where its values live (`type.yaml`'s `settings:` block). `Settings.resolveForCreate` layers the schema's own defaults, the type's own `settingsDefaults(name, opts, asked)` hook (a DEFAULT the schema can't express — a name-derived convention, a fact read off a payload the caller handed it, a value following a field `asked` shows a higher layer naming; any later layer overrides it), the Preset Manager, an importer's settings, the caller's `settings` table, then the type's own `settingsCorrections(values, name, opts)` hook (a CROSS-FIELD CONSTRAINT the schema can't express, applied last over the fully merged values). A correction over a default/preset/importer value lands silently; a correction that would override what the caller's own `settings` table explicitly asked for refuses the creation instead, naming the field and why. Neither hook is ever handed a table to mutate; each returns what it wants changed (`settingsCorrections` may also return a `{ [field]: reason }` table for that refusal message). `Settings.cloneValues` deep-copies a values table — `create.module` hands `onCreate` a copy, never the table it stamps. `Settings.valuesOf` / `writeValues` read and write an asset's own values file. | | `typeYaml.module` | `type.yaml` | The folder a type lives in and its parsed `type.yaml`, decoded once per content version of the file. `settings.module` and `inspector.module` read their blocks through it. `about` / `aboutAt` read a type's `about.yaml` (`intent`, `function`, `usage`), leaving out any key that is empty or still starts with `[[describe]]`; `aboutRows` and `aboutMarkdown` lay the texts out for the Inspector and the `types/<name>` guide. | | `inspector.module` | `type.yaml`'s `inspector:` block | Which inspector a type declares for its assets (`inspector: { type: ... }` or `{ instance: ... }`), and the declaration that file returns — the sections it adds, the generic ones it replaces, and their order — or the problem that kept it from loading. | | `onRegister.module` | `onRegister` | Fires an instance's once-only registration hook — on arrival, on world load, and for `@builtin` library instances. | | `changeDispatch.module` | `onChange`, `onDelete`, `refShapes` | Routes a VFS source write or a folder delete to the enclosing typed asset's type hooks. | | `refShapes.module` | `refShapes`, `ref` | Publishes what every `AssetRef<category>` answers to, so a member read on an asset-typed value is checked against that category's real surface. | | `events.module` | `events` | The per-asset event runtime behind `ref.events`. | | `instantiable.module` | `ref.instantiate` | The instantiation contract an asset type opts into: `root` stands the root entity, `place` applies the base placement opts to one the type adopted, and `result` shapes the `(root, idMap)` every `instantiate` returns. Also registers the `sceneInstantiable` field-constraint validator. | | `declaration.module` | `type.yaml` | The type's decoded declaration, read once and held until a write inside an `.assetType` folder; what every question about a type as a whole reads. | | `previewRecipe.module` | `type.yaml` `preview:` | How an instance's `preview.png` is produced: which of the four recipes (`instantiate`, `image`, `surface`, `custom`) the type declares, and what that recipe needs. | ## Reaching it ```luau local rt = require("@builtin::assetTypes.assetType.shared") rt.ref.loadTypeBehavior("material") ``` Fields resolve lazily. The prelude requires the sub-modules directly, in dependency order (`ref`, then `changeDispatch`, `onRegister.install()`, `refShapes.install()`) — a table that required all six on load would take that ordering away from it.
▲ 0↑ born
▣
module · born here
❒asset
# preset A preset holds typed values for one declarer's settings schema: an assetType's, an importer's, a component's, or any asset that declares its own settings. `preset.capture` saves the settings something has now, `preset.apply` writes a preset's values into something its target governs, `preset.values` reads them checked against the target's current schema, and `preset.setValues` replaces them, checked first. Exposed as the `preset` global via `--!global preset`. A preset's `preset.yaml` names its target as a guid envelope, `target: { __ref: <guid>, type: <type>, name: <name> }`, which the preset's `.refs` pins by guid with the target's checksum. A target written as an identity string is accepted on read, resolves by identity, reads as unpinned, and is rewritten as the envelope on the preset's next local edit. ## Exports - `preset.values(source: AssetRef<preset>) -> ({ [string]: any }, Report)` — the values that pass the target's current schema, and a report naming every one that does not. - `preset.apply(source: AssetRef<preset>, into: AssetRef | ComponentTarget) -> ApplyResult` — write the valid values into an asset the target governs, or into a component on an entity whose component is the target. Struct groups merge field by field. Raises when another declarer governs `into`. - `preset.capture(from: AssetRef | ComponentTarget, name: string, opts?: CaptureOpts) -> AssetRef<preset>` — save an asset's settings, or a component's live values on an entity, as a new preset targeting the declarer that governs them. A bare name lands in `/source/presets/`; an absolute `.preset` path lands where it says. - `preset.setValues(source: AssetRef<preset>, values: { [string]: any })` — replace the whole values table; any violation refuses the write, naming every one. - `preset.defaults() -> { DefaultRow }` — the world's Preset Manager rows, in order, each resolved with its problems. - `preset.setDefaults(rows: { DefaultRowInput })` — replace every row; every row is checked first and any problem refuses the write, naming every one. - `preset.addDefault(source: AssetRef<preset>, opts?: { filter: string?, at: number? }) -> number` — add a row for the declarer the preset targets; returns its index. - `preset.removeDefault(index: number)` — remove one row, keeping every other row as written. - `preset.defaultFor(declarer: AssetRef | string, path: string) -> ({ [string]: any }?, Match?)` — the values a new thing at `path` would take from the rows, and the row that gives them. Types: - `ComponentTarget = { entity: string, component: string }` — a component on an entity. - `Report = { format: string, target: string, targetGuid: string?, pinned: boolean, targetChanged: boolean, rejected: { Violation } }` — `target` is the target's identity; `pinned` is true when `.refs` pins the target's guid; `targetChanged` is true while the pinned checksum differs from the target's current one. - `Violation = { path: string, message: string }` - `ApplyResult = { applied: { string }, rejected: { Violation }, targetChanged: boolean }` - `CaptureOpts = { overwrite: boolean? }` — `overwrite = true` re-authors an existing preset, keeping its guid. - `DefaultRowInput = { preset: any, target: any?, filter: string? }` — a preset, its declarer (the preset's own target when omitted) and a filter (empty matches everything). - `DefaultRow = { index, target, preset, filter, targetGuid, presetGuid, targetName, presetName, problems }` - `Match = { index, target, preset, path, rejected, problem? }` — the row a creation took and the path it read. ## Usage ```luau -- Capture a texture's settings, then apply them to another texture local p = preset.capture("hero_sprite", "pixel_art") preset.apply(p, "enemy_sprite") -- Apply a component preset to a component on an entity preset.apply("synty", { entity = id, component = "Locomotion" }) -- Capture a component's live values local tint = preset.capture({ entity = id, component = "Model" }, "red_tint") -- Read the values and what the target rejects local values, report = preset.values("pixel_art") for _, v in ipairs(report.rejected) do print(v.path, v.message) end -- Replace the values preset.setValues("pixel_art", { filter = "nearest", generateMipmaps = false }) ``` ## Notes - Every read re-checks the values against the target's current schema, so a value a later schema drops or retypes is reported by path rather than applied. - `asset.create("preset", name, { target = <identity or guid>, values = { ... } })` authors a preset directly, with the same checks as `preset.capture`. - The Preset Manager rows are documented in `preset.defaults`; the filter grammar in `preset.glob`. - Submodules: `preset.document` (the `preset.yaml` format), `preset.target` (target resolution and checking), `preset.heal` (rewriting an older preset document in the current form on a local edit).
▲ 0↑ born
▣
module · born here
❒asset
# luau_introspect (module) Parses Luau/asset source TEXT into structured declarations. Pure string/pattern parsing (`string.find` / `string.match` / `string.gmatch`) over the literal source — no compiling, no VM spawn, no runtime state, no engine FFI. Given source text, it extracts what is written in the file. This is the shared parser every per-assetType `M.ref.inspect` hook uses to turn a component/module/tool's own source into the structured record `asset.inspect` returns. ## Exports - `docstrings(src) -> DocMap` — scans `--!desc` / `--!arg` / `--!return` / `--!example` comment runs and binds each run to the name of the declaration on the next non-comment line (the identifier after `function`, `public:`, `local function`, or `M.`). - `publicFields(src) -> { FieldEntry }` — parses `public = { name = Field.<kind>(default, mode), ... }` table-literal entries and module-scope `public.<name> = Field.<kind>(...)` assignments. - `events(src) -> { EventEntry }` — parses `events = { name = Event(payloadSchema?, syncMode?), ... }` table-literal entries. - `methods(src) -> { MethodEntry }` — parses `function public:<name>(...)` / `typed function public:<name>(...)` declarations (params + optional return type). - `lifecycleHooks(src, catalog) -> { string }` — top-level `function <name>(` declarations whose name is in the caller-supplied `catalog` array. - `moduleExports(src) -> { ExportEntry }` — parses `M.<name> = function` assignments, `function M.<name>(...)` declarations, and a trailing `return { foo = foo, ... }` export table. - `forSource(src, computeFn) -> any` — memoises `computeFn(src)` keyed on `src` itself in a module-local table. The same source text returns the cached result without re-running `computeFn`; different source text recomputes. Keyed on the source content (not an asset checksum) because composite/container assets (component folders, scene folders, etc.) all hash to the empty-string checksum — a checksum-keyed cache collapses every such asset's detail onto whichever one was inspected first. ## Usage ```luau local Introspect = require("modules.luau_introspect") local src = self:getInitScript() local detail = Introspect.forSource(src, function(s) return { fields = Introspect.publicFields(s), events = Introspect.events(s), methods = Introspect.methods(s), hooks = Introspect.lifecycleHooks(s, lifecycleCatalog), } end) ``` ## Notes - Every function is a pure string→table transform: same source text in, same structured table out, every time. No reads of live component state, no entity/world queries. - Structural scanning runs over a comment- and string-aware **mask** of the source (a same-length copy where comment bodies and string-literal contents are blanked to spaces, delimiters and newlines preserved). Pattern matches and brace/paren balancing run on the mask — so a brace, `Field.`, `Event(`, or a whole entry that appears inside a comment or a string literal never registers — while captured values are sliced from the original source at the same (aligned) indices. This makes the parser robust to apostrophes in comments, commented-out entries, string defaults containing `}` / `Field.` / `Event(`, and `[[ ]]` long strings. - `default` / `category` are raw trimmed source-text slices (with any trailing comment stripped), not evaluated values. - For a **ref constructor** (`Field.assetRef` / `dataRef` / `resource` / `componentRef`) the FIRST positional argument is the category / contract / componentType selector, captured under `category`; the SECOND argument is captured under `default`. - For every **other** Field kind the first argument is the `default` and `category` is nil. - A trailing `Sync` / `NoSync` identifier is captured as `sync`, tolerating a trailing comma or a trailing comment after the last argument. - Field/Event entries whose key is a computed or indirect expression (`[expr] = Field.number(...)`) are omitted — only literal identifier keys are recognised. - `methods` captures a `...` variadic parameter (as `name = "..."`), with its `: <type>` annotation when present. - A `--!desc` written above a field/event declaration (`<name> = Field.<kind>(...)` / `<name> = Event(...)`) or a `public.<name> =` assignment binds to that name in `docstrings`, and is folded into the corresponding `publicFields` / `events` entry's `desc`. - `lifecycleHooks` never hardcodes the lifecycle-callback catalog; the caller passes the list of names to match against. - `forSource`'s memo is bounded (oldest-key eviction) so a long session touching many distinct asset versions can't grow it without limit.
▲ 0↑ born
▣
module · born here
❒asset
# yaml.module YAML decode + encode for authored engine content. Pure Luau, no engine dependencies — a general parsing library, not data-system plumbing. ```luau local Yaml = require("@builtin::modules.yaml") local doc = Yaml.decode(vfs.read(path)) vfs.write(path, Yaml.encode(doc)) ``` ## Supported subset - Block mappings (`key: value`) and block sequences (`- item`), nested to any depth. - Compact sequence-of-mapping entries (`- path: x` / ` kind: y`). - Flow collections — `{ a: 1, b: 2 }` and `[1, 2, 3]` — single line. - Plain scalars with type inference: `~` / `null` → nil, `true` / `false` → boolean, numeric literals → number, everything else → string. - Single- and double-quoted strings (`''` escapes a literal quote inside a single-quoted string; `\n` `\t` `\r` `\\` `\"` inside a double-quoted one). A quote opens a quoted scalar where a scalar begins — after `key:`, after a `- ` entry marker, or inside a flow collection — so a plain scalar carries an apostrophe as data (`note: the world's rules`). Quoted keys are read in flow mappings. - `#` comments — honored outside quotes, so a `#` inside a quoted string is kept as data. - Literal (`|`) and folded (`>`) block scalars, with a chomping indicator (`-` strips the final newline, `+` keeps every trailing blank line, none keeps one newline) and an indentation indicator (`1`-`9`: the content's indent past the parent's), in either order (`|-`, `>+`, `|2`, `>1-`). A block scalar's content is literal text: quotes (balanced or not), `#`, `key: value` and `---` inside it are data. - An optional leading `---` document marker. ## Loud-error contract Constructs outside the subset above raise instead of misparsing: anchors/aliases (`&`, `*`), tags (`!`), directives (`%`), multi-document streams (a second `---`), a block-scalar header it cannot read (`|x`, `|-+`, `|0`), tab indentation, and inconsistent indentation (both block structure and block-scalar bodies). Every error carries the offending line number (`yaml: line N: ...`), so a bad config points straight at the line to fix. Tab indentation is rejected everywhere — including block-scalar body lines whose leading whitespace contains a tab. A tab after the first non-space character of a line is content and passes through. ## API - `Yaml.decode(text: string): any` — decode a YAML document into a Luau value (table, scalar, or nil for an empty document). Raises on malformed input or an unsupported construct. - `Yaml.decodeWithComments(text: string): (any, boolean)` — decode as `decode` does, and report whether the text carries a comment by the decoder's own rule: a `#` at a line's start or after whitespace, outside a quoted scalar and outside a block scalar. Re-encoding the value drops such comments, so an editor that writes a document back reads this first. - `Yaml.encode(value: table): string` — encode a Luau table as YAML (block style, two-space indent, alphabetically sorted keys). Raises on values YAML can't represent (functions, userdata, non-string mapping keys). A top-level empty table encodes to an empty document, which decodes back to `nil` (the YAML empty-document ambiguity).
▲ 0↑ born
▣
module · born here
❒asset
# json JSON encode/decode library for Luau. Encodes Lua values to JSON strings and decodes JSON strings back to Lua values. Used for communication with the Rust side of the engine, the VFS read/write bridge, and any wire-format that needs JSON. Pure Luau, no engine dependencies. Compact and pretty-printed encoders, plus a hand-rolled decoder that streams the input by position so it works under WASM as well as native. ## Exports - `Json.encode(value: any, indent?: string, currentIndent?: string) -> string` — compact encode. Functions / unknown types and NaN/Inf encode as `null`. - `Json.encodePretty(value: any, indentStr?: string) -> string` — pretty-printed encode with sorted object keys (diff-friendly). - `Json.encodeArgs(...: any) -> string` — encode varargs as a JSON array. - `Json.decode(str: string) -> any` — decode a JSON string. Returns the decoded value, or `nil` + error message on failure. ## Usage ```luau local Json = require("@builtin::modules.json") local widget = { type = "button", text = "Click Me" } local compact = Json.encode(widget) -- '{"text":"Click Me","type":"button"}' local pretty = Json.encodePretty(widget, " ") local decoded = Json.decode(compact) local v, err = Json.decode("oops") -- v = nil, err = error message ``` ## Notes - Object keys are sorted alphabetically in both encoders for consistent output across runs. - Numeric keys on objects are stringified at encode time (JSON has no numeric keys). Pure-integer key sets get detected as arrays via `isArray` and encoded with brackets. - NaN, +Inf, -Inf encode as `null` — JSON has no representation. Round trips through `decode` recover `null` (Lua `nil`), so they don't preserve. - Unicode `\uXXXX` escapes decode to UTF-8 by hand to stay WASM-safe. Only the BMP is covered; supplementary planes via surrogate pairs are not. - Functions encode as `null`. - Decode is character-streamed — no regex, no `string.match` patterns on the whole input — so the line-and-column information needs to be reconstructed from the position offset.
▲ 0↑ born
backing path · assetTypes/scene.assetType/shared.module/build.module

Problems

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

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

Usability ratings

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

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

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

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