build
Turns builder code into scene records, and scene records into scene entities.
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/v2module 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.
| arg | type | description |
|---|---|---|
| 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.
| arg | type | description |
|---|---|---|
| ids | { string } |
idSet(ids: { string }) → void
A set from an id array, for the membership questions the composition asks.
| arg | type | description |
|---|---|---|
| ids | { string } |
without(ids: { string }, excluded: { [string]: boolean }) → void
The ids the array holds that the set does not name, in the same order.
| arg | type | description |
|---|---|---|
| ids | { string } | |
| excluded | { [string]: boolean } |
republishWhenCaptureCloses(ref: any) → void
| arg | type | description |
|---|---|---|
| ref | any |
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.
| arg | type | description |
|---|---|---|
| traceback | string |
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.
| arg | type | description |
|---|---|---|
| refusals | { Refusal } | The refusal array `entity.capture` hands back. |
examples
local named = SceneBuild.attribute(select(4, entity.capture(fn)))
despawnAll(ids: { string }) → void
| arg | type | description |
|---|---|---|
| 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.
| arg | type | description |
|---|---|---|
| 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.
| arg | type | description |
|---|---|---|
| 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.
| arg | type | description |
|---|---|---|
| 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?".
| arg | type | description |
|---|---|---|
| source | string | The script body to digest. |
examples
local key = SceneBuild.digest(vfs.read(path))
readGeneratedState(folder: string) → void
| arg | type | description |
|---|---|---|
| folder | string |
writeGeneratedState(folder: string, state: { [string]: string }) → void
| arg | type | description |
|---|---|---|
| folder | string | |
| 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.
| arg | type | description |
|---|---|---|
| ref | any |
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.
| arg | type | description |
|---|---|---|
| folder | string | The build's own folder, which the assets it produces are authored |
| sourceDigest | string | The 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
| arg | type | description |
|---|---|---|
| kind | string | |
| name | string | |
| 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.
| arg | type | description |
|---|---|---|
| name | string |
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.
| arg | type | description |
|---|---|---|
| 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.
| arg | type | description |
|---|---|---|
| target | any |
runKey(owner: string, destination: Destination) → string
The key `runningReconciles` holds a reconcile of `owner` at `destination` by.
| arg | type | description |
|---|---|---|
| owner | string | |
| destination | Destination |
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.
| arg | type | description |
|---|---|---|
| owner | string | |
| destination | Destination | |
| key | string | |
| generation | number |
ownerAttribute(entityId: string) → string
The build named on `entityId`, or nil for an entity carrying no build name.
| arg | type | description |
|---|---|---|
| entityId | string |
keyAttribute(entityId: string) → string
The record identity named on `entityId`, or nil for an entity carrying none.
| arg | type | description |
|---|---|---|
| entityId | string |
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.
| arg | type | description |
|---|---|---|
| entityId | string | |
| destination | Destination |
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.
| arg | type | description |
|---|---|---|
| owner | string | |
| destination | Destination | |
| key | string |
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.
| arg | type | description |
|---|---|---|
| entityId | string | Runtime entity id. |
examples
if SceneBuild.ownerOf(id) ~= nil then print("a build states this") endsourceOf(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.
| arg | type | description |
|---|---|---|
| owner | string | Build 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.
| arg | type | description |
|---|---|---|
| guid | string | The asset's guid. |
| origin | string? | `"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.
| arg | type | description |
|---|---|---|
| guid | string | The 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.
| arg | type | description |
|---|---|---|
| owner | string |
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.
| arg | type | description |
|---|---|---|
| owner | string | Build name, as `M.ownerOf` reports it. |
| key | string | The 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.
| arg | type | description |
|---|---|---|
| entityId | string | Runtime entity id of the owned entity. |
| values | { [string]: any } | The values the entity carries now, by name. |
| componentType | string? | 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.
| arg | type | description |
|---|---|---|
| entityId | string | Runtime 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.
| arg | type | description |
|---|---|---|
| entityId | string | Runtime 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.
| arg | type | description |
|---|---|---|
| owner | string | |
| destination | Destination |
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.
| arg | type | description |
|---|---|---|
| target | EntityRef | 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.
| arg | type | description |
|---|---|---|
| a | any | |
| b | any |
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.
| arg | type | description |
|---|---|---|
| value | any | |
| depth | number |
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.
| arg | type | description |
|---|---|---|
| data | any | |
| given | any |
resolveEntityRefs(comp: any, runtimeByOriginal: { [string]: string }) → any
| arg | type | description |
|---|---|---|
| comp | any | |
| 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.
| arg | type | description |
|---|---|---|
| comp | any | |
| statedRefs | { [string]: string } |
componentDigests(rec: any, statedRefs: { [string]: string }) → void
| arg | type | description |
|---|---|---|
| rec | any | |
| statedRefs | { [string]: string } |
componentBakedKey(typeName: string) → string
| arg | type | description |
|---|---|---|
| typeName | string |
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.
| arg | type | description |
|---|---|---|
| n | any |
vecText(v: any, count: number, fallback: { number }) → string
| arg | type | description |
|---|---|---|
| v | any | |
| count | number | |
| 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.
| arg | type | description |
|---|---|---|
| name | any |
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.
| arg | type | description |
|---|---|---|
| value | any |
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.
| arg | type | description |
|---|---|---|
| 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.
| arg | type | description |
|---|---|---|
| held | any |
readBaked(rid: string) → void
| arg | type | description |
|---|---|---|
| rid | string |
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.
| arg | type | description |
|---|---|---|
| prev | { [string]: string } | |
| name | string |
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.
| arg | type | description |
|---|---|---|
| prev | { [string]: string } | |
| name | string | |
| wanted | string |
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.
| arg | type | description |
|---|---|---|
| a | string | |
| b | string |
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.
| arg | type | description |
|---|---|---|
| merge | Merge | |
| prev | { [string]: string } | |
| name | string | |
| wanted | string |
entityName(rid: string) → string
The entity's name, or an empty string when it cannot be read.
| arg | type | description |
|---|---|---|
| rid | string |
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.
| arg | type | description |
|---|---|---|
| merge | Merge | |
| rid | string | |
| property | string | |
| instances | { string }? | |
| held | string? |
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`.
| arg | type | description |
|---|---|---|
| rid | string | |
| rec | any | |
| prev | { [string]: string } | |
| merge | Merge |
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.
| arg | type | description |
|---|---|---|
| rid | string |
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.
| arg | type | description |
|---|---|---|
| owner | string? | 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.
| arg | type | description |
|---|---|---|
| rec | any | An 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.
| arg | type | description |
|---|---|---|
| entry | any |
heldInstance(entry: any) → HeldInstance
One `component.getAll` entry as a held instance, or nil for an entry naming no type.
| arg | type | description |
|---|---|---|
| entry | any |
drivenNames(driven: { [string]: FieldDriver }?) → void
The names of the fields `driven` holds, sorted, in the shape `withoutFields` takes.
| arg | type | description |
|---|---|---|
| driven | { [string]: FieldDriver }? |
heldComponents(proxy: any) → void
Per type, the instances the entity carries, in the order it reports them.
| arg | type | description |
|---|---|---|
| proxy | any |
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.
| arg | type | description |
|---|---|---|
| proxy | any | |
| typeName | string |
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.
| arg | type | description |
|---|---|---|
| proxy | any | |
| typeName | string |
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.
| arg | type | description |
|---|---|---|
| proxy | any | |
| typeName | string |
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.
| arg | type | description |
|---|---|---|
| rid | string | |
| typeName | string | |
| instanceName | string? | |
| data | any |
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`.
| arg | type | description |
|---|---|---|
| rid | string | |
| typeName | string |
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.
| arg | type | description |
|---|---|---|
| proxy | any | |
| typeName | string | |
| instance | WantedInstance |
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.
| arg | type | description |
|---|---|---|
| rid | string |
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.
| arg | type | description |
|---|---|---|
| rid | string |
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.
| arg | type | description |
|---|---|---|
| rid | string | |
| record | boolean |
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.
| arg | type | description |
|---|---|---|
| typeName | string |
same(a: HeldInstance, b: WantedInstance) → boolean
| arg | type | description |
|---|---|---|
| a | HeldInstance | |
| b | WantedInstance |
stated(instanceName: string?, data: any) → any
| arg | type | description |
|---|---|---|
| instanceName | string? | |
| data | any |
fieldText(value: any) → string
A component field's value as the text a kept entry reports it in.
| arg | type | description |
|---|---|---|
| value | any |
liveValue(field: any) → any
| arg | type | description |
|---|---|---|
| field | any |
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.
| arg | type | description |
|---|---|---|
| driver | FieldDriver |
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.
| arg | type | description |
|---|---|---|
| rid | string | |
| typeName | string |
isPlacement(typeName: string) → boolean
| arg | type | description |
|---|---|---|
| typeName | string |
holdsPlacement(proxy: any) → boolean
Whether the entity carries a placement component now.
| arg | type | description |
|---|---|---|
| proxy | any |
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.
| arg | type | description |
|---|---|---|
| hostId | string | |
| record | boolean |
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.
| arg | type | description |
|---|---|---|
| proxy | any | |
| 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.
| arg | type | description |
|---|---|---|
| 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.
| arg | type | description |
|---|---|---|
| rid | string | |
| rec | any |
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.
| arg | type | description |
|---|---|---|
| rec | any | |
| participationOverride | string? |
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.
| arg | type | description |
|---|---|---|
| rid | string | |
| stated | { [string]: string } | |
| prev | { [string]: string } | |
| merge | Merge |
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.
| arg | type | description |
|---|---|---|
| key | string | The key the scene is known by: its guid, else its path. |
| landing | Landing | `{ 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.
| arg | type | description |
|---|---|---|
| key | string | The key the scene is known by. |
| landing | Landing | The 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.
| arg | type | description |
|---|---|---|
| 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() endisStatedNothingRefusal(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.
| arg | type | description |
|---|---|---|
| err | any | The 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.
| arg | type | description |
|---|---|---|
| count | number | |
| 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.
| arg | type | description |
|---|---|---|
| rid | string |
place(index: number) → void
| arg | type | description |
|---|---|---|
| index | number |
passes( ) → void
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.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ 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".
Scoped to this part · feeds back into the world's score.