scene.assetType
This package holds more than this page lists. See all of its files in its world.
README.md
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.
Explicit placement keys keep identity across name, hierarchy and emission-order
changes. A build declares one with build.key(entity, "logical-key"); the same
surface is returned by buildSurface(folder, digest). Keys are unique within a
build owner and target. identityOf(entityId) reads the declared key.
The first key assigned to an existing unkeyed placement adopts the entity at its current hierarchy/name key. Changing an explicit key creates a new placement. Duplicate explicit keys are refused before the live build changes.
Reconciliation returns a third result: an explicit-key-to-entity-id map. A caller
can persist it in its authoring state and pass it back as opts.identityMap.
The returned map retains removed keys, so a placement emitted again after
removal regains its original id. Reconcile copies the supplied map and rejects
duplicate ids, conflicts with live keys, and ids owned by another target or
build before mutation. Keep one map per target and owner.
plan(records, target, owner, identityMap?) assigns persistent ids before
application. It returns placements (captured id to persistent id),
identityMap, byKey, and removed. Planning leaves live entities unchanged,
so a caller can project the captured records and validate a complete candidate
scene. Pass placements and identityMap to reconcile to apply those ids;
reconciliation revalidates them and refuses ids claimed by another entity.
project(records, plan, owner, componentGuid, componentName, rootParent?)
turns a placement plan into persisted entity records. It remaps captured parent
and component references, preserves explicit build identities and stamps build
ownership. Pass a persistent rootParent for an entity-scoped build, or omit it
for scene roots. The returned records can form the generated document supplied
to SceneComposition.compose before any live placement changes. Projection
checks capture identity and hierarchy against the plan.
Scene builds capture both content and editorOnly, then plan both surfaces,
then apply their placements. A capture failure leaves the previous placements
and saved scene standing.
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.