saver
Luau-side scene saver. Writes `scene.json` v6 — **authored intent only**. No captured runtime state.
scene.shared.saver
Luau-side scene saver. Writes scene.json v6 — authored intent
only. No captured runtime state.
Public surface
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._velocityon 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.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2module scene_saver Luau-side scene saver. Persists scene state via a delta-overlay model: Canonical (committed work) <scene folder>/scene.json Dirty (work-in-progress, deltas only) <scene folder>/scene_dirty/manifest.json scene-level config overrides (lighting, player, camera, format, version) <scene folder>/scene_dirty/entities/<id>.json one file per CHANGED entity: * full body — modified or newly spawned * tombstone — { tombstone = true } for despawn The dirty directory carries ONLY the deltas. Entities unchanged since the last canonical save have NO entry under entities/. Editing one cube in a 100k-entity scene writes exactly one ~1KB file per drain; the manifest is touched only when scene-level config changes. The entity-id list is NOT carried in the manifest — it's derived at load / promote time from `canonical.entities[]` plus a filesystem listing of `entities/`. Concurrent writes to per-entity files therefore never produce manifest-conflict orphans (the conflict surface is one entity at a time, not the whole-scene index). Tombstones survive in dirty until the next save (when `clearDirty` wipes the directory). An orphan tombstone — one targeting an entity that wasn't in canonical either (i.e. the entity was spawned and deleted inside the same edit session before save) — is a no-op at compose time, so the file shape is robust regardless of operation order. The composer (`composeMerged`) is the canonical merge point used by both this saver's promote/save paths AND `scene_loader.M.load`, so there's exactly one place that knows how to combine canonical with the overlay. Captures authored intent only: no spawner-managed entities (player identities, primary camera), no temporary entities, no runtime player position. FFI shapes (discovered at runtime — differ from plan): - entity.findAll() → array of {id: string, name: string} tables. - localPosition / localScale expose number components .x/.y/.z. - localRotation exposes quaternion components .x/.y/.z/.w. - entity(id).getParent() → parent entity proxy or nil; its `.id` is the id string. - entity(id).name → string name (direct field, no function call). - lighting snapshot is read directly from settings.lighting. require @builtin::assetTypes.scene.shared.saver
isSpawnerManaged(id: ?) → void
Filter: identifies player identities (entities carrying UserIdentity) + the primary camera so we don't serialize and double them on next load.
| arg | type | description |
|---|---|---|
| id | ? |
entityIsRemoteSynced(id: ?) → void
A synced entity that belongs to another session: one another peer owns, or one the relay delivered (other peers' players and objects, and the ghosts the relay retains, all of which carry `origin = "relay"`). It stays out of YOUR scene's dirty overlay and canonical file, which keeps the live shared state of other sessions out of your scene. A synced entity this session built that no peer has claimed (`owner() == 0`, which is how every peer holds a scene's synced entities in edit mode, where no peer announces scene content to the room) is the scene's own, as is a synced entity this peer owns and every entity that is not synced.
| arg | type | description |
|---|---|---|
| id | ? |
entityIsComponentProduced(id: ?) → void
An entity a component created while the engine was running that component's own lifecycle. The engine records where every entity came from at the spawn site and answers it as `origin`; `"component"` is the value it gives a spawn made from a callback the engine dispatches — `awake`, `start`, `update`, `onEnable` and their siblings — and the engine dispatches every one of those again on the next load and the next edit↔play flip. So the component puts the entity back itself, and a record of it in the scene file describes a second copy: the load restores the record AND runs the callback, the save writes both, and the scene grows by the callback's whole output every time it is opened. A component's own attaches are already read this way — `component.add` from a component's lifecycle records the same `"component"` origin, and the record gate leaves those out — so this is that rule reaching the entities beside the components. What an AUTHOR spawns through a component method keeps the origin of the call that ran it and stays the scene's.
| arg | type | description |
|---|---|---|
| id | ? |
entityIsLocallyReproduced(id: ?) → void
Whether THIS session's own world puts this entity back every time: the spawner owns it (a player identity, the primary camera), a component's own lifecycle created it, or it is temporary (a bundle instantiation, a runtime-only helper). All three are statements this session made about content this session has, which is why they are the ones that license taking a record out of the overlay.
| arg | type | description |
|---|---|---|
| id | ? |
entityIsReproduced(id: ?) → void
Whether something other than the scene file puts this entity in the world every session: this session's own world reproduces it, or it arrived replicated from another peer.
| arg | type | description |
|---|---|---|
| id | ? |
standsUnder(id: ?, selfVerdict: (any) → void
Returns true if `id` itself is reproduced, or stands under a temporary ancestor. Temporariness is the one verdict that reaches descendants, because the spawn that makes a temporary root makes the tree under it in the same act: a bundle instantiation drops a temporary root with non-temporary helpers underneath, and a helper written to `entities/` re-instantiates on the next load, producing duplicates that compound on every edit→play cycle. The primary camera and every player avatar / prototype clone are spawned temporary, so their machinery is covered by the same walk. The other two verdicts speak about the entity in front of them — a record the spawner puts back, a record the relay delivers — and the author's own work below one of those belongs to the scene file. Its `parent` stands when the record set provides that parent (a peer's replicated copy of a record the same file carries), and `closeUnderParent` clears it when the set does not while the excluded parent itself stands in the world, so the entity comes back at the scene root rather than beneath something the file never names. The walk stops at an ancestor that is gone: a broken parent link is nobody's ownership claim, and the entity below it stands on its own state. Its record keeps the reference — neither the file nor the world answers to it — and a load reports the record it cannot place rather than standing the entity at the scene root as one the scene has no record for.
| arg | type | description |
|---|---|---|
| id | ? | |
| selfVerdict | (any |
entityIsUnderReproduced(id: ?) → void
| arg | type | description |
|---|---|---|
| id | ? |
entityIsUnderLocallyReproduced(id: ?) → void
The same walk over the local half of the verdict: this session's own world puts the entity — or the temporary root it stands under — back every time.
| arg | type | description |
|---|---|---|
| id | ? |
isAuthored(id: ?, _layerName: ?) → void
Decide whether an entity belongs in the dirty file for `layerName`. Drops anything the scene file does not put in the world: entities the spawner manages, temporary ones and everything under them, and those replicated in from another peer. A nil/empty layerName treats every authored entity as in-scope.
| arg | type | description |
|---|---|---|
| id | ? | |
| _layerName | ? |
componentShortName(t: string) → string
The component type's short name: the leaf of the identity every spelling of the component resolves to, so a saved record (`Model`, `Door`) and a live one (`@builtin::components.Model`, `doors.Door`) read alike.
| arg | type | description |
|---|---|---|
| t | string | A component type name in any form. |
examples
require("@builtin::assetTypes.scene.shared.saver").componentShortName("@builtin::components.Model")transformDiffLines(oldRec: any, newRec: any, driven: { [string]: boolean }?) →
Diff lines for an entity's transform channels (position / rotation / scale), comparing the live record against the record the scene carries. A channel the saved record OMITTED defaults to the identity transform, so a move away from origin registers even for an entity saved at identity (which carries no transform block) — while an unmoved entity whose live record materializes the identity transform produces no line. A channel named in `driven` holds the running simulation's state and takes no part. drove in play, as a set; nil compares every channel.
| arg | type | description |
|---|---|---|
| oldRec | any | The scene's entity record (may omit `transform` or channels). |
| newRec | any | The live entity record. |
| driven | { [string]: boolean }? | Channel names (`position` / `rotation` / `scale`) a component |
examples
require("@builtin::assetTypes.scene.shared.saver").transformDiffLines({}, { transform = { position = { 0, 1, 0 } } })componentDrivenFields(id: any) →
The component fields on a live entity whose current value a component callback wrote while the engine was in play, keyed by SHORT component name. A lamp component writing `Light.intensity` every frame reports `Light = { intensity = true }`; an authoring call writing that same field takes it back off. These name the running simulation's state rather than authored intent, so the record comparison passes over them. type resolves to without its library prefix; empty for an entity no component drove.
| arg | type | description |
|---|---|---|
| id | any | The live entity's id. |
examples
require("@builtin::assetTypes.scene.shared.saver").componentDrivenFields("ent_0")transformDrivenChannels(id: any) →
The transform channels of a live entity whose current value a component callback wrote while the engine was in play, as a set. A camera rig turning its camera every frame reports `{ rotation = true }`; an authoring call writing that same channel takes it back off. These name the running simulation's state rather than authored intent, so the record comparison passes over them.
| arg | type | description |
|---|---|---|
| id | any | The live entity's id. |
examples
require("@builtin::assetTypes.scene.shared.saver").transformDrivenChannels("ent_0")withoutDrivenState(rec: any, base: any?) → any
An entity record with the running simulation's state taken out: every transform channel and component field a component drove in play on the entity the record names carries the value `base` states for it, and is left out where `base` states none. With the scene's record as `base`, it is what a verdict writes into the scene for a live entity: accepting an author's change records that change and leaves the value a running component happened to hold that frame where the scene had it. With no `base`, it is what a write to the scene applies to a live entity in play, leaving each channel and field a running component drives to that component. read. leaves them out.
| arg | type | description |
|---|---|---|
| rec | any | The entity record; its `id` names the entity whose driven state is |
| base | any? | The record whose values the driven channels and fields take; nil |
examples
local ss = require("@builtin::assetTypes.scene.shared.saver"); ss.withoutDrivenState(ss.serializeEntity(id), saved)recordDiffLines(oldRec: any, newRec: any, maxLines: number?) →
Human lines describing how a live entity record differs from the record the scene carries: transform channels, component fields, component additions and removals, and attribute additions, changes and removals. Compares authored intent: a component field participates where either record states it and while its live value is an author's (a field only the live record states was set after the scene's record was made, and one the instance wrote about its own runtime is left out), numbers compare within a float-noise epsilon, and asset references compare by the asset they name rather than by the shape they are written in. A field or transform channel a component drove in play holds the running simulation's state, which the scene's record puts back, so it states no difference. An EMPTY result is the "unchanged" verdict.
| arg | type | description |
|---|---|---|
| oldRec | any | The scene's entity record. |
| newRec | any | The live entity record. |
| maxLines | number? | How many lines to report before summarizing the rest as "…". |
examples
local ss = require("@builtin::assetTypes.scene.shared.saver"); ss.recordDiffLines(saved, ss.serializeEntity(id))push(s: string) → void
| arg | type | description |
|---|---|---|
| s | string |
sceneFolderFor(target: ?) → void
Resolve `target` (full VFS path with / without `scene.json`, or a bare scene name) to the .scene folder path with trailing `/`.
| arg | type | description |
|---|---|---|
| target | ? |
canonicalPathFor(target: ?) → void
| arg | type | description |
|---|---|---|
| target | ? |
dirtyDirFor(target: ?) → void
Dirty directory: <scene folder>/scene_dirty/. Per-entity body files live alongside the manifest under entities/.
| arg | type | description |
|---|---|---|
| target | ? |
dirtyManifestPathFor(target: ?) → void
| arg | type | description |
|---|---|---|
| target | ? |
dirtyEntitiesDirFor(target: ?) → void
| arg | type | description |
|---|---|---|
| target | ? |
dirtyEntityFilePathFor(target: ?, entityId: ?) → void
| arg | type | description |
|---|---|---|
| target | ? | |
| entityId | ? |
tombstoneBody(id: ?) → void
| arg | type | description |
|---|---|---|
| id | ? |
isTombstone(body: ?) → void
| arg | type | description |
|---|---|---|
| body | ? |
withdrawnKey(target: ?) → string
| arg | type | description |
|---|---|---|
| target | ? |
isWithdrawn(target: ?, eid: ?) → boolean
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? |
noteWithdrawn(target: ?, eid: ?, wasLive: boolean) → void
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? | |
| wasLive | boolean |
endWithdrawalForMark(target: ?, eid: ?) → void
End `eid`'s withdrawal in `target` because a mark named it. A mark is a statement the author made after the verdict, and the scene takes it — with one exception the withdrawal already answered: a withdrawn removal whose entity is still absent, where the mark restates that removal and the withdrawal stands.
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? |
clearAbsentWithdrawals(target: ?) → void
Drop `target`'s withdrawn removals. Called wherever the scene is composed: the composed body is the record a withdrawn removal was made to keep, so reading it out is that withdrawal answered.
| arg | type | description |
|---|---|---|
| target | ? |
recordCanonicalIds(target: ?, body: ?) → void
| arg | type | description |
|---|---|---|
| target | ? | |
| body | ? |
wasCanonical(target: ?, eid: ?) → void
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? |
ledgerKey(target: ?) → string
| arg | type | description |
|---|---|---|
| target | ? |
noteHeld(target: ?, eid: ?) → void
Record that `eid` is live in `target` for this session.
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? |
isHeld(target: ?, eid: ?) → boolean
Whether this session has ever seen `eid` live in `target`.
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? |
noteBuildRemoved(eid: string) → void
Say that a scene build took the entity `eid` out of the world. A save of the scene then states the removal of the record the scene holds for it, however the build ran. A build that runs as its scene loads reaches `scene.json` this way and records nothing in the scene's unsaved edits.
| arg | type | description |
|---|---|---|
| eid | string | The entity id the build despawned. |
examples
require("@builtin::assetTypes.scene.shared.saver").noteBuildRemoved(id)noteStatedRemoval(target: ?, eid: ?) → void
Record that this session stated the removal of an overlay-only `eid`.
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? |
resetStatedRemovals(target: ?) → void
Drop the removals this session is carrying for `target`. The records they name are what they track, so emptying the overlay is what retires them.
| arg | type | description |
|---|---|---|
| target | ? |
forgetHeld(target: ?, eid: ?) → void
This session stops claiming it held `eid` in `target`. What a session says about an entity's absence rests on having had it, so an entity it no longer claims is one the removal reconciliation leaves to whoever authored it, and the statements this session already made about that entity retire with the claim.
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? |
statedRemovalIds(target: ?) → void
The overlay-only removals `target` carries, stated and published alike.
| arg | type | description |
|---|---|---|
| target | ? |
add(set: { [string]: boolean }?) → void
| arg | type | description |
|---|---|---|
| set | { [string]: boolean }? |
retireUnrecorded(target: ?, removed: { string }) → void
Let go of what this session keeps for an entity no record of `target` names any more: its held id, and the handles its records left out, which only a load building the entity from a record puts back. A held id is what lets this session state a removal about a record the scene still carries; an id whose entity is gone, which the canonical file the last compose read does not carry, and which an empty overlay names nowhere, is an entity whose removal the scene already states by the row's absence, and nothing reads it again. `removed` names the overlay-only removals the emptied overlay took away, which left the held set when they were stated. Called once the overlay is empty, so what is kept is the size of the entities the scene carries rather than of every entity this session ever held in it. A scene no compose has read keeps its held set: the file may still carry any of them.
| arg | type | description |
|---|---|---|
| target | ? | |
| removed | { string } |
noteRecordWaits(target: ?, eid: ?) → void
Record that `eid`'s overlay record in `target` waits for a parent no entity provides. While it waits, the saver writes nothing over that record from the entity's live state, until a mark on the entity or `endRecordWait` ends the wait.
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? |
endRecordWait(target: ?, eid: ?) → void
End the wait `noteRecordWaits` recorded for `eid` in `target`, so the saver records that entity's live state again.
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? |
recordWaits(target: ?, eid: ?) → boolean
Whether `eid`'s overlay record in `target` waits for its parent, so the saver leaves that record as it stands.
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? |
fireOnBeforeSave( ) → void
lightingSnapshot( ) → void
Scene-level lighting for the manifest delta. The scene.json `lighting` block persists only the non-entity state the loader's `settings.lighting` schema owns: `clear_color` and the legacy `sky` config block. Lights and the sky are entities and are captured by the entity delta like everything else. Returns nil when the settings block isn't available (early boot, headless harness) so the delta walker leaves the `lighting` key out.
defaultPlayerCfg( ) → void
defaultCameraCfg( ) → void
unwrapConfig(block: ?, fallback: ?) → void
Unwrap a typed config block (metatable-wrapped — see `newConfigBlock` in layers.module) into a plain copy of the backing data so Json.encode + the manifest delta-walker can iterate it normally. The wrapper's own table is empty (__newindex needs to fire on every write, so the wrapper can't store data on itself); without unwrapping, the saver would serialize `player = {}` regardless of what the user set. A plain-table fallback (no _snapshot method) passes through directly for callers that build a SceneProxy by hand or pre-typed-block tests.
| arg | type | description |
|---|---|---|
| block | ? | |
| fallback | ? |
proxyForLayer(layerName: ?) → void
Resolve the scene proxy for `layerName` (guid or display name) via the live layers registry, or nil when none is found.
| arg | type | description |
|---|---|---|
| layerName | ? |
proxyConfigs(layerName: ?) → void
Snapshot the proxy's player + camera config blocks (under `proxy.settings.{player,camera}`). Authored intent only; falls back to "required in both modes, inherit world default" when no settings table is attached.
| arg | type | description |
|---|---|---|
| layerName | ? |
sceneFolderChecksum(target: string) → string
The checksum the scene folder of `target` carries now, or nil when it has none to read.
| arg | type | description |
|---|---|---|
| target | string |
loadedVersionForLayer(layerName: ?) → void
The version a scene was loaded as, read from its canonical scene.json. Absent canonical (a brand-new scene) → CURRENT_VERSION. A v6 scene re-saves as v6; a v7 scene re-saves as v7, so the manifest never silently upgrades the version.
| arg | type | description |
|---|---|---|
| layerName | ? |
buildManifest(layerName: ?) → void
Build the manifest body — scene-level config ONLY. No entity list. The delta-overlay model derives entity identity from `canonical.entities[]` + `entities/` listing, so the manifest is small + writable without contending for an entity-list array. The `version` is the version the scene was loaded as (v6 stays v6), never a forced upgrade. v6 emits the declarative player{}/camera{} blocks; v7 emits `player` as the string intent it carries on the proxy (`playerIntent`) and omits the camera block, which v7 does not use.
| arg | type | description |
|---|---|---|
| layerName | ? |
recordFieldValue(v: any) →
The durable form of one component field value — what a record states for it. An asset reference keeps the identity a later session re-resolves it from; a live GPU resource handle names a slot in this session's GPU registry, so it is left out and named in the second return instead. Reading a live field through this is what lets a consumer of a record compare what it holds against what the record says in one form. was left out when one was.
| arg | type | description |
|---|---|---|
| v | any | A field value read off a live component. |
examples
require("@builtin::assetTypes.scene.shared.saver").recordFieldValue(model.material) -- { __ref = "..." }, nillayerProxyFor(layerKey: ?) → void
The live layer proxy answering to `layerKey`, or nil when no loaded layer does. Accepts either the layer's display name (resolved via asset.ref by Layers.find) or its guid (resolved by iterating Layers.list and matching proxy.guid); dirty marks arrive via the sync FFI tagged with SceneOwner.scene, which carries a guid in the guid-keyed scene model.
| arg | type | description |
|---|---|---|
| layerKey | ? |
layerIsAdditive(layerKey: ?) → boolean
Whether the layer answering to `layerKey` is additive. An additive layer is composed from its own source on every load, so it carries no dirty state and a mark naming one describes an entity no overlay is ever asked about — which is the one absence of a scene folder that is the layer's design rather than a record with nowhere to go.
| arg | type | description |
|---|---|---|
| layerKey | ? |
sceneLoadRunning( ) → boolean
Whether a scene load is in flight (`layers.loadInFlight`). The layer it brings in resolves to its scene folder once the engine holds a slot for it, which is frames after the entities the load restores are attributed to it.
targetForLayer(layerKey: ?) → void
Resolve a target VFS path for `layerKey` by walking the live layer proxy. Returns nil for additive layers (they don't carry dirty state) unless a build is baking one, and for layers we can't find a proxy for.
| arg | type | description |
|---|---|---|
| layerKey | ? |
writeOverlayRecord(filePath: string, body: any) → string
Write `body` as the overlay record at `filePath`. Returns nil when the record is on disk, else the reason it is not — the caller decides what a record it could not write means for the operation it is part of.
| arg | type | description |
|---|---|---|
| filePath | string | |
| body | any |
readOverlayRecord(filePath: string) → any
The body the overlay record at `filePath` currently states, or nil when there is no record there or its bytes do not decode to one. What a record says is what the flush below decides against: a tombstone already states the removal it would otherwise state again.
| arg | type | description |
|---|---|---|
| filePath | string |
removeOverlayRecord(filePath: string, durable: boolean?) → string
Delete the overlay record at `filePath`. Returns nil when the file is gone, else the reason it is still there.
| arg | type | description |
|---|---|---|
| filePath | string | |
| durable | boolean? |
retractOverlayRecord(target: ?, eid: ?, opts: ?) → string
Take `eid`'s overlay record in `target` back out of the scene: the record is deleted, the id is withdrawn so no writer re-states it, and this session stops claiming it held the entity so the removal reconciliation has nothing to say about its absence. What the scene carries for the entity is then its canonical record, whichever way the withdrawn record differed from it. Returns nil when the record is off disk, else the reason it is still there — a caller that reports the change settled while the record still stands would be reporting work the scene never took. `opts.durable` states that this retraction settles the scene's source. A verdict on a review says it, so the record comes out with play still running and the session it is running in keeps its frames; a caller that says nothing takes the terms play is on, and reads the lock's refusal as the reason the record is still there.
| arg | type | description |
|---|---|---|
| target | ? | |
| eid | ? | |
| opts | ? |
overlayRecordIsRetractable(target: string, eid: string) → boolean
Whether `eid`'s overlay record in `target` is one this session may take out. Declining to WRITE a record and DELETING one that is already there are two different acts, and only the first is safe to base on a session-relative verdict. An overlay row is a plain VFS file that any session sharing the world can have written, so a row whose entity merely arrived replicated from a peer belongs to the session that authored it: this session composes it into the scene, and never deletes it. Two conditions therefore have to hold — this session's writer holds the entity, and this session's own world is what puts the entity back (the spawner owns it, or it is temporary or stands under a temporary root).
| arg | type | description |
|---|---|---|
| target | string | |
| eid | string |
retractReproducedRecord(target: string, eid: string) → void
Take `eid`'s overlay record in `target` out. A save writes no record for an entity this session's world reproduces, so a record standing from before it became reproduced states content the scene never writes: the compose bakes it into the canonical file and the publication gate counts it as a pending edit. Taking it out leaves the overlay saying exactly what a save would.
| arg | type | description |
|---|---|---|
| target | string | |
| eid | string |
flushEntityRecords(layerName: ?, entityIds: ?, stopAt: number?) → void
Per-entity flush. For each id, decide what the dirty file should carry by examining live ECS state + prior dirty contents + the canonical-id tracker: Live + isAuthored → write full body as override. Live + !isAuthored → RETRACT. The mark fired (Rust doesn't know the authored filter) but the entity is spawner-managed / temporary / remote; nothing to record, and any record standing from before it became reproduced comes out. Keeps `entities/` saying what a save writes. !Live + had body in dirty → write tombstone (user authored then deleted in the same session). The record is the only place the removal is stated, and every session sharing the scene reads it there. !Live + canonical-tracked → write tombstone (user deleted a or in canonical now previously-saved entity that was never touched this session, or one a verdict baked and swept from the overlay, so no dirty body file exists for the merger to find). !Live + neither → SKIP. Spawner-machinery transient (e.g. player-identity respawn on edit↔play transitions); orphan tombstones would just clutter the directory. The marks it drains are what the engine noticed; `forceRecordRemovals` is what the scene's own records say, and the two together are the whole reconciliation. `stopAt` is an `os.clock()` reading the flush stops at: once it has passed, the flush ends after the id it is on. The second return is how many of `entityIds`, from the front, the flush has settled; the rest are the caller's to hand back later.
| arg | type | description |
|---|---|---|
| layerName | ? | |
| entityIds | ? | |
| stopAt | number? |
canonicalFileCarries(eid: string) → boolean
| arg | type | description |
|---|---|---|
| eid | string |
flushEntitiesForLayer(layerName: ?, entityIds: ?) → void
| arg | type | description |
|---|---|---|
| layerName | ? | |
| entityIds | ? |
sceneRemoved(layerName: string) → void
Stop writing anything for the loaded layer `layerName`: the scene it was loaded from was removed from the world, so its dirty overlay has no scene left to belong to. The marks it holds and every mark it takes until it loads again are dropped, and nothing is written into the removed scene's folder, which would otherwise bring that folder back.
| arg | type | description |
|---|---|---|
| layerName | string | The layer's name, as `layers.list()` names it. |
examples
Saver.sceneRemoved(proxy.name)
sceneReturned(layerName: string) → void
Write the loaded layer `layerName`'s edits again: a scene of that name loaded, so the layer has a scene to write into. Undoes `M.sceneRemoved`.
| arg | type | description |
|---|---|---|
| layerName | string | The layer's name, as `layers.list()` names it. |
examples
Saver.sceneReturned(proxy.name)
recordsWritten( ) → number
How many entity records this session has written into a scene's dirty overlay, counted as each one lands. A record already holding the bytes it would be written with is left as it is and not counted. Read twice, the difference is the record writing done between the two reads, which is how a frame's share of a save or of the continuous writer is seen.
examples
local before = Saver.recordsWritten()
marksWaitForLoad(layerKey: ?) → boolean
Whether the writer holds the marks for `layerKey` until a scene load is through: the layer resolves to no scene folder while a load is in flight, which is how the layer a load brings in reads until the load hands it back, and a build running inside the load marks what it changes in the scene before then. An additive layer's marks are discarded by the flush whenever they reach it.
| arg | type | description |
|---|---|---|
| layerKey | ? |
releaseParked( ) → void
Put back into the backlog the marks that waited for a scene load, for each layer that resolves now, and for every layer once no load is in flight: a layer that still resolves nowhere then is one no load is bringing in, and the flush answers for its marks. A mark that waited is taken the way `takeMarks` takes one whose layer resolves, so it ends a withdrawal and a record's wait for its parent the same.
takeMarks( ) → void
Take the engine's dirty marks into the backlog. A mark is an author acting on the entity after any verdict withdrew its record, so the withdrawal is over and the record written for it says what the mark says: the body of an entity that is here, the tombstone of one that has since been removed. One mark leaves the withdrawal standing: an id still absent, restating the removal the verdict took back.
settleEntries(token: { thread: thread }, limit: number?, stopAt: number?) → void
The loop behind `settleBacklog`: writes the oldest waiting records until `limit` of them are written or `os.clock()` passes `stopAt`. `token` is the settle's own entry in `BACKLOG.settling`; a settle that finds another has taken that over leaves the backlog to it, with the records it just wrote standing.
| arg | type | description |
|---|---|---|
| token | { thread: thread } | |
| limit | number? | |
| stopAt | number? |
settleIsRunning(held: any) → boolean
Whether the settle `held` names is one this call is inside: it runs on this thread and its loop is on this thread's stack. Any other settle entry is one the caller takes over. The watchdog ends a script that overruns its budget wherever it stands, a settle included, and what that leaves is an entry whose loop never runs again.
| arg | type | description |
|---|---|---|
| held | any |
settleBacklog(limit: number?, stopAt: number?) → boolean
Write the records of the oldest waiting entries: at most `limit` of them, stopping once `os.clock()` passes `stopAt`. Each nil means no bound, which settles the whole backlog. At least one entry is settled whenever any is waiting, so a backlog always drains. Returns whether entries still wait. One settle runs at a time. A read of the overlay made from inside a record's serialization finds the settle already running and returns to it, rather than moving the head out from under the run the outer settle is part way through. A settle entry left by a script the watchdog ended is taken over, and `settleEntries` checks its token after every run it writes, so a settle that was taken over stops without moving the head.
| arg | type | description |
|---|---|---|
| limit | number? | |
| stopAt | number? |
settleWaitingRecords( ) → void
Write every waiting record now. The overlay a reader lists is then every mark the writer has taken.
deepEqual(a: ?, b: ?) → void
Structural equality. Two nil values are equal; two tables are equal if every key in `a` is in `b` with a deepEqual value, and `b` has no extra keys.
| arg | type | description |
|---|---|---|
| a | ? | |
| b | ? |
flushManifestForLayer(layerName: ?) → void
`flushManifestForLayer` below reaches for `readCanonical`, defined further down with `composeMerged` (they share helpers) and bound to the forward declaration near the top of this module. Rewrite the manifest for `layerName` as a TRUE DELTA: only the scene-level fields that differ from canonical land in the overlay. If the live state matches canonical (or no canonical exists yet and the live state matches the saver's defaults), nothing is written and any stale manifest is removed. The merger in `composeMerged` already treats missing overlay fields as "use canonical's value", so writing only the diff is sufficient. Same property as `entities/`: edit nothing → no overlay file created; edit one lighting field → only the `lighting` block appears in the overlay. Without this, every spawner-machinery mark would flood the manifest with full default snapshots and make it impossible to tell what the user actually changed. Returns one line per manifest state this pass could not put on disk. The manifest carries the scene's own lighting / player / camera config, so a delta it cannot write is authored work the composed scene does not carry and a stale block it cannot delete is config the next load applies over the author's own.
| arg | type | description |
|---|---|---|
| layerName | ? |
liveAuthoredIds(layerKey: ?) → void
The live entities of the ACTIVE layer, which the explicit persist points (save / writeDirty) re-serialize. The continuous writer only re-serializes entities whose per-entity dirty mark has landed, and a public-field value edit reaches the ECS without landing such a mark, so the incremental overlay keeps the entity's add-time body; reading the live set at a persist point captures current ECS truth regardless of which marks fired. The per-edit continuous-writer cost stays O(1); that O(authored) pass runs only on an explicit save or a mode flip. Keyed to the active layer, which is what `serializer.activeLayerEntityIds` enumerates; `layerKey` is the guid (save) or name (writeDirty) the overlay was written under, so `flushEntitiesForLayer` resolves the same path.
| arg | type | description |
|---|---|---|
| layerKey | ? |
recordAcrossFrames(layerKey: ?) → void
The record pass of a save, spread over frames at the continuous writer's rate: the marks already taken, then every live authored entity of the layer, at most `FRAME_RECORD_BUDGET` records a frame, a frame boundary between one share and the next. A save runs in a scheduler task, so how long its frames take is set by that budget rather than by how many entities the scene holds. The marks that land while it runs go into the backlog, and the pass ends by settling what they left, so the overlay it hands the compose is every mark taken up to its last frame and a record of every entity live in it. Returns one line per record it could not put on disk, as the force-flush does.
| arg | type | description |
|---|---|---|
| layerKey | ? |
isCodeReproduced(eid: string) → boolean
Record every entity live in the active layer as one this session holds, so the removal reconciliation can tell an entity this session had and lost from one it never built. A load is the moment a scene's whole set becomes live at once, and it happens before the session's first persist point, which is why the load calls this rather than waiting for the flush to sample it. An entity the composed scene names is noted whatever made it: the record is what a removal is stated against. An entity no record names and that code puts back on every load is left out: anything an entrypoint or component created under a fresh id (the freeze gate's reproduced contexts), the spawner's player body and camera, a component's own output, a temporary tree. Each load makes those under new ids, and a ledger that noted them would gain ids per load that nothing reads. The record lookup comes first and the freeze gate's cached tag second, so a scene the load built from its records pays one table read per entity.
| arg | type | description |
|---|---|---|
| eid | string |
noteHeldEntities(layerKey: ?) → void
| arg | type | description |
|---|---|---|
| layerKey | ? |
readDirtyEntityOverlay(target: ?) → void
Read every file under `entities/` and return a list of { id, body, tombstoned } rows. Files that fail to decode are dropped with a warning so a single bad file doesn't break the load. A file that exists and whose bytes this engine cannot read raises, naming it. The filesystem listing IS the source of truth for the dirty entity set — the manifest deliberately doesn't carry an id list, so the composer never has to reconcile a stale list with the actual files on disk.
| arg | type | description |
|---|---|---|
| target | ? |
reconcileReproducedRecords(target: string) → void
Sweep the overlay for records of this session's own that the live world has since made reproduced, so a compose reads only what a save would write. The per-mark retraction above covers every entity the engine marks; this covers the one it does not mark again after the change — a spawn marked temporary by the code that made it — and runs at the persist points, which already walk the overlay. A row for an entity replicated in from a peer is left exactly as it stands: the session that authored it says what the scene carries for it.
| arg | type | description |
|---|---|---|
| target | string |
decodeCanonicalBody(path: ?, src: ?) → void
Read the canonical scene.json into a body table. Returns nil when canonical doesn't exist; falls back to an empty-scene body on decode failure so a bad canonical doesn't lock the user out. Bound to the forward-declared upvalue above so `flushManifestForLayer` (defined earlier) sees this function. Decode one canonical body, or an empty scene when the text does not parse. Shared by the fresh read and the cached one so both report a bad file the same way.
| arg | type | description |
|---|---|---|
| path | ? | |
| src | ? |
contentAddressOf(path: string) → string
The address the bytes at `path` are stored under, or nil where memory holds them (a synchronous read returns those) or nothing does.
| arg | type | description |
|---|---|---|
| path | string |
holdCanonicalText(path: string, text: string, address: string?) → void
Take `text` as what `path` holds, under `address`: the one the path answered before the read that produced `text`. A read that yields can finish after a write has replaced the bytes, so the copy is taken only while the path still answers that address. Text memory holds needs no copy: a synchronous read returns it.
| arg | type | description |
|---|---|---|
| path | string | |
| text | string | |
| address | string? |
watchCanonicalText(path: string) → void
Watch a canonical file this engine read, so the text each write lands is taken while it is still in reach. A file read while small is watched too: a later write can carry it past the size memory keeps, and that write is the moment its text is readable without a fetch.
| arg | type | description |
|---|---|---|
| path | string |
heldCanonicalText(path: string) → string
The held text of `path`, while the address it was taken under still names the bytes the path holds.
| arg | type | description |
|---|---|---|
| path | string |
readInReach(path: string) → void
The bytes at `path` as this caller can read them, or nil and the reason the read found none. Code that can yield waits for bytes still on their way, and a fetch that finds none answers nil and its reason. Code that cannot yield is refused with `VFS_READ_CANNOT_WAIT` for them, and that refusal answers nil and the refusal: the file exists and is out of this caller's reach, which the held copy answers for. Any other refusal is raised as it came.
| arg | type | description |
|---|---|---|
| path | string |
readCanonicalSource(name: ?) → void
Read the canonical source text, or nil when there is nothing to read. The third answer is set when the file exists and this caller cannot read it: the read found no bytes and no held copy answers for them, while the path is still there. It names why: the caller's context when the read refused it bytes still on their way (the caller runs where a coroutine cannot yield, and a caller that can yield waits for them), and the read's own reason otherwise (a fetch that found no bytes, which every caller meets alike). That is a different answer from an absent file, and each reader decides what it means for what it reads.
| arg | type | description |
|---|---|---|
| name | ? |
readCanonical(name: ?) → void
The canonical body for `name`, a table of the caller's own, or nil when the scene has no canonical file. Every reader of the whole body composes, diffs or rewrites the scene from it, and a body read as absent while the file exists is a scene with every entity it carries missing: a load would place the overlay alone, the leave-play count would name each of the file's entities as play work, and a save or a verdict would write the scene without them. A file this caller cannot read therefore raises, naming the file and why.
| arg | type | description |
|---|---|---|
| name | ? |
readCanonicalShared(name: ?) → void
The canonical body for `name`, decoded once per distinct file content. The returned table is shared with every other holder of the same content, so it belongs to readers. `readCanonical` returns a body of the caller's own for anything that edits what it reads — `composeMerged` folds the dirty overlay into its copy in place. A dirty flush reads the canonical body twice per frame and looks at scene-level fields only (`version` for the manifest's version, and `lighting` / `player` / `camera` for its delta). Decoding a saved scene to reach them costs the whole document, entity list included, so on a large scene a per-frame transform edit spent its frame in `Json.decode`. A file this caller cannot read answers nil, as an absent one does, and the reason as a second answer, which an absent file does not give. The continuous writer reads through here from the engine's frame, where a coroutine cannot yield, for the scene's version and config, which fall back to the current version and the saver's defaults; a raise there would drop the records of that frame instead. Those records go to the overlay, never to the file, so the file's own records stand.
| arg | type | description |
|---|---|---|
| name | ? |
canonicalEntityIdsFor(name: ?) → void
The entity ids canonical names for `name` — what `scene.json` carries on its own, before the dirty overlay merges over it. The removal reconciliation asks this to pick the record it writes for an absent entity: an id canonical carries needs a tombstone over it, because a plain absence from the overlay lets the merge carry the canonical row through. The returned table is shared with every other caller reading the same canonical content, so it belongs to readers.
| arg | type | description |
|---|---|---|
| name | ? |
namesLiveEntity(ref: string) → boolean
Whether `ref` — a record's `parent`, in either spelling a load resolves one against — names an entity standing in the world right now. `entity.findAll` answers for an id and for a display name in the one call. The two answers cost different things, so a probe that cannot be made answers the cheaper one: "the world provides it" clears the reference and composes the record at the scene root, which keeps the entity across the round trip, while "nothing provides it" leaves a reference the load abandons the record over. A world that cannot be asked is not evidence that a record is broken.
| arg | type | description |
|---|---|---|
| ref | string |
closeUnderParent(name: ?, entities: ?, aside: { [string]: boolean }?, forWrite: boolean?) → void
Close a composed record list under `parent`: every `parent` a record carries names a record the SAME list carries, by id or by display name — the two spellings a load resolves a parent against. A record whose parent names neither is answered by what the WORLD says about that parent, and the two answers are different repairs: * The parent stands in the world and the file simply leaves it out — a temporary root, a spawner's own machinery, the entity a component rebuilds. The author's work below it belongs to the scene, so the reference is cleared and the record composes at the scene root: the file is closed under `parent` and the entity survives the round trip. * Nothing answers to the reference at all. Clearing it would turn a broken record into a root entity the author never made, which is what a load then puts in the world and a save then writes down as authored. The reference stands instead, so the record keeps stating the parent it wants and a load reports the one record it cannot place rather than inventing a placement for it. Both are reported once, naming the scene and a sample of the records. A composition for a write (`forWrite`) reports only the first: the records of the second kind are held back from the file it writes (`splitUnplaced`), and the writer reports them as it holds them back. `aside` names, by id and by display name, the records a save keeps in the overlay beside the list it writes. They are records the scene carries, so a reference to one stands, the same as a reference to a record in the list. The rule lives here because this is the one list both ends read. The canonical bytes a save writes and the records a load spawns are the same composition, so a file left behind by an older engine, a hand edit, or a partial sync is answered on the way in as well as on the way out.
| arg | type | description |
|---|---|---|
| name | ? | |
| entities | ? | |
| aside | { [string]: boolean }? | |
| forWrite | boolean? |
splitUnplaced(entities: { any }) → void
Split a composed record list into the records a load of that list alone places and the records it abandons: a record whose `parent` no record of the list provides, by id or by display name, and every record beneath one, whatever order the records come in. The first return keeps the list's order and the second holds the abandoned records in the order they had in it. One pass: each reference counts the records of the list that provide it, and a record that is held back takes its references out of those counts, so the records under a reference no record provides any longer are held back in turn. A display name several records carry stays provided while any of them is kept.
| arg | type | description |
|---|---|---|
| entities | { any } |
refsOf(rec: any) → void
The references a record provides: its id, and its display name beside it.
| arg | type | description |
|---|---|---|
| rec | any |
buildIdentityOf(rec: any) → void
The build a record is the output of: the `buildOwner` and `buildKey` attributes a build's reconcile writes onto every entity it places, which a record carries beside the entity's name. Nil for a record no build placed.
| arg | type | description |
|---|---|---|
| rec | any |
buildOutputIndex(records: { any }) → void
The record id each build output among `records` stands for, by build and record identity.
| arg | type | description |
|---|---|---|
| records | { any } |
sceneBuildModule( ) → any
The scene build module, or nil where it cannot be loaded.
replacedByItsBuild(rec: any, written: { [string]: string }, SceneBuild: any) → boolean
Whether `rec`, a record no load of the records `written` beside it places, is build output its build has replaced. Its entity stands nowhere in the world, and either `written` carries another record for the same build and record identity (the build placed that identity again, on a new entity), or the build ran in this session and places nothing for that identity any more (`SceneBuild.states`). A build states its whole output on every run, so such a record states nothing the scene carries.
| arg | type | description |
|---|---|---|
| rec | any | |
| written | { [string]: string } | |
| SceneBuild | any |
splitReplacedBuildOutput(written: { any }, held: { any }) → void
Split the records a write holds back (`splitUnplaced`) into the ones that wait for their parent and the build output its build has replaced (`replacedByItsBuild`), which the write takes out of the scene. `written` is the record list the write carries. Both returns keep the order `held` had.
| arg | type | description |
|---|---|---|
| written | { any } | |
| held | { any } |
recordsAwaitingParent(target: string, overlay: { any }?) → void
The records of `target` that wait for their parent: the ids of the records a load of the scene abandons because the parent each names is provided by no record it places and by no entity standing in the world. A record under one that waits waits with it, whatever order the records are in. `overlay` is the overlay's rows when the caller already read them. Such a record states an entity that stands nowhere yet, and goes on stating it until an entity providing its parent arrives, so its entity's absence is the wait. A save leaves the record in the overlay, where the overlay applier builds it once its parent builds; every load of `scene.json` abandons it. One pass over the records: each reference counts the placed records that provide it, by id and by display name, and a record that starts to wait takes its references out of those counts, so the records under a reference no placed record provides any longer wait in turn.
| arg | type | description |
|---|---|---|
| target | string | |
| overlay | { any }? |
standsInWorld(ref: string) → boolean
| arg | type | description |
|---|---|---|
| ref | string |
nameBeside(key: string, rec: any) → string
The display name `rec` provides beside its key, or nil when it provides none or the name is its key.
| arg | type | description |
|---|---|---|
| key | string | |
| rec | any |
wait(key: string) → void
| arg | type | description |
|---|---|---|
| key | string |
release(ref: string) → void
A reference whose last placed provider now waits: the records under it wait with it, as a load abandons every record under one it abandons, whatever entity the world holds under that id or name. The world answers only for a reference no record provides at all.
| arg | type | description |
|---|---|---|
| ref | string |
readDirtyManifest(name: string) → any
The dirty manifest for `name` as a table, or nil when there is none to read.
| arg | type | description |
|---|---|---|
| name | string |
mergedSceneConfig(canonical: any, manifest: any) → void
The scene-level config a bake of `manifest` over `canonical` writes. A scene's v6/v7 identity is fixed by its CANONICAL body, never by a dirty overlay. Genuinely v7 = canonical version 7, or an authored string `player` intent. A legacy v6 scene (declarative player{}/camera{} blocks, numeric version below 7) stays v6: a stray `version: 7` or string `player` overlay — a defaulted "spawns" intent the v7 machinery persisted onto a legacy scene — does not upgrade it, or the loader discards its procedural player/camera and errors on every entity for a missing `synced` flag the v6 records never carried. A genuinely-v7 scene carrying a string `player` intent then settles its version to 7 and drops any legacy `camera` block a prior v6 serialization left behind, so a v7 scene stuck at version 6 heals to a clean v7 body on the next save instead of perpetuating the mismatch.
| arg | type | description |
|---|---|---|
| canonical | any | |
| manifest | any |
overlayEmptying(name: ?, canonical: ?, rows: ?) → void
Whether `rows`, the dirty overlay of the scene `name`, carries a tombstone for every entity the canonical body holds: `{ entities, tombstones, path }` when it does, nil when the overlay leaves the scene something.
| arg | type | description |
|---|---|---|
| name | ? | |
| canonical | ? | |
| rows | ? |
composedSceneBody(name: ?, opts: { setAside: { [string]: boolean }?, keepSavedWhenEmptied: boolean? }?) → void
Canonical + dirty overlay composed into one body, by the rules `composeBody` states: the body, and the overlay `opts.keepSavedWhenEmptied` left out of it.
| arg | type | description |
|---|---|---|
| name | ? | |
| opts | { setAside: { [string]: boolean }?, keepSavedWhenEmptied: boolean? }? |
composeMerged(name: ?, opts: { setAside: { [string]: boolean }?, keepSavedWhenEmptied: boolean? }?) → void
The composed body, with the canonical-id tracker refreshed to the entity set it states. Composing for a load settles what the scene holds, so the tracker moves with it: a subsequent despawn mark reads the merged view to decide whether it needs a tombstone (the entity was in the scene) or nothing (it was transient spawner machinery). A reader that only wants to know what the scene composes to calls `composedSceneBody` and leaves the tracker where the last load put it.
| arg | type | description |
|---|---|---|
| name | ? | |
| opts | { setAside: { [string]: boolean }?, keepSavedWhenEmptied: boolean? }? |
composeForWrite(name: string, setAside: { [string]: boolean }) → void
The body a write of scene `name` puts in its `scene.json`, with the records `setAside` names left in the overlay: `composeBody` with `closed`, the canonical-id tracker refreshed as `composeMerged` refreshes it. Returns the body, the records held back to wait for their parent, and the build output its build has replaced.
| arg | type | description |
|---|---|---|
| name | string | |
| setAside | { [string]: boolean } |
sceneBodyForReading(name: string) → any
The body a scene composes to, for a caller that only reads it. A scene with no dirty state composes to its saved `scene.json`, so the body is the one decoded for the file's current bytes and shared with every other reader of them: asking again costs no decode while the file holds still. A scene with dirty state is composed afresh, as `composedSceneBody` does. The tracker of canonical ids is left where the last load put it. The table belongs to its readers and is never written to; `composeMerged` is the call for a body the caller edits. A saved file that exists and that this engine cannot read (its bytes are not on this engine, or the caller cannot wait for them) raises, naming the file and why, as `composeMerged` does.
| arg | type | description |
|---|---|---|
| name | string | The scene: its path or identity. |
examples
local body = Saver.sceneBodyForReading("/source/scenes/arena.scene"); print(#body.entities)overlayEmptiesScene(name: string) →
Whether the scene's dirty overlay carries a tombstone for every entity its saved `scene.json` holds, which composes the scene to nothing it was saved with. An overlay of a scene that is being edited removes some of its entities; one that removes all of them is a record of something other than an author's edits (a build that stated nothing, a damaged journal), so the loader loads the saved scene instead and the pending-edit verdict names it. saved scene holds, how many of them the overlay removes, and the overlay folder.
| arg | type | description |
|---|---|---|
| name | string | The scene: its path or identity. |
examples
local emptied = Saver.overlayEmptiesScene("/source/scenes/arena.scene")buildOutputOf(savedRec: any?, pendingRec: any?) → string
The scene build whose output a pending edit is, or nil when an author made it. A scene build (a scene's `build.luau`, a `SceneModule` placement) writes its name, the record each entity stands for and what it stated onto every entity it places, and a rebuild that states something new restates that last part; those attributes travel in the records, so the answer is read off the two records alone. An edit is the build's output when the build placed the entity, the pending record holds exactly what the build stated (`SceneBuild.recordDrift` finds nothing an author changed or added), and, for an update, the build's statement is not the one the saved record holds. A removal is the build's when the build that placed the entity has run in this session and no longer states it (`SceneBuild.states`); an entity its build still states was taken away by an author, and the build's next run puts it back. an addition. removal. that build has run in this session (`/game/district.sceneModule/init.luau`), else by its placement (`placement 'districtHost' (ent_…)`) or its name; nil for an author's edit.
| arg | type | description |
|---|---|---|
| savedRec | any? | The record the scene's saved file holds for the entity, nil for |
| pendingRec | any? | The record the scene's unsaved edits hold for it, nil for a |
examples
local by = require("@builtin::assetTypes.scene.shared.saver").buildOutputOf(saved, pending)attributesOf(rec: any?) → void
| arg | type | description |
|---|---|---|
| rec | any? |
pendingConfigKeys(name: string, canonical: any) → void
The scene-level config keys a bake would write differently from the way the canonical file states them. Read through `mergedSceneConfig`, the same decision `composeMerged` writes by, so a key the merge declines to apply — a `version: 7` or a string `player` standing over a legacy v6 canonical — is not reported as pending over a bake that provably leaves the file alone.
| arg | type | description |
|---|---|---|
| name | string | |
| canonical | any |
pendingRecordDiffLines(oldRec: any, newRec: any) → void
What baking one overlay record over the record the scene carries would write, as human lines — AND the verdict that it would write anything: an empty result is the "the canonical file already says this" verdict. One walk answers both, over the same `diffEqual` the merge's own equality uses. Every top-level key the two records disagree on is reported, by the field-by-field renderers where they speak about it and by name where they do not — so a record the gate refuses over always names what it refuses over, and a record the gate passes has nothing left unsaid.
| arg | type | description |
|---|---|---|
| oldRec | any | |
| newRec | any |
pusher(key: string) → void
| arg | type | description |
|---|---|---|
| key | string |
trackingReason( ) → string
Why an authored scene edit made from THIS call's own context would not be recorded right now, or nil while it would be. A scene records its edits in edit mode, outside a scene load, outside the world entrypoint's respawn pass, and outside a component or entrypoint callback tick; inside any of those a spawn or a change reaches the live session and no file. This is the question an empty `pendingSceneEdits` list cannot answer on its own — the same list stands for "the scene is saved" and for "nothing is watching it".
examples
require("@builtin::assetTypes.scene.shared.saver").trackingReason()pendingSceneEdits(name: string) →
Every edit a scene's dirty overlay holds that baking it would write into the canonical scene file: an added entity, an updated one, a removed one, or a change to the scene's own lighting / player / camera config. An EMPTY result is the verdict that the canonical scene already says what the overlay says, whatever rows the overlay carries. Each entry names the entity and describes the difference. scene name. `"updated"`, `"removed"` or `"config"`, and `builtBy` names the scene build whose output the edit is (`buildOutputOf`), nil for an author's edit. Second, `trackingReason()`: why an authored scene edit made from THIS call's own context would not be recorded right now, or nil while one would be. It describes the caller's context, so it answers the same way for a scene the list is complete for.
| arg | type | description |
|---|---|---|
| name | string | The scene — a `.scene` folder path, a `scene.json` path, or a bare |
examples
require("@builtin::assetTypes.scene.shared.saver").pendingSceneEdits("/zero/source/scenes/main.scene")hasPendingSceneEdits(name: string) → boolean
Whether baking the scene's dirty overlay into its canonical file would change the scene. False when the overlay is absent, and false when it holds only records the canonical file already states. scene name.
| arg | type | description |
|---|---|---|
| name | string | The scene — a `.scene` folder path, a `scene.json` path, or a bare |
examples
require("@builtin::assetTypes.scene.shared.saver").hasPendingSceneEdits(layers.active.name)standingConfigKeys(name: string) → void
The config keys the scene still states a difference over, read through the verdict itself so a discard and the gate cannot answer differently. Nil when the scene has no config difference left.
| arg | type | description |
|---|---|---|
| name | string |
discardOverlayManifest(name: string) → string
Take the scene's overlay manifest out, so the scene's config is the one its canonical file states. A difference the canonical body carries on its own — the version and camera keys a legacy scene settles the next time it is written — outlives the manifest, so the removal is followed by the verdict's own question and a difference still standing is said as the reason rather than reported as dropped.
| arg | type | description |
|---|---|---|
| name | string |
discardSceneEdits(name: string, select: (string | { string }) →
Take a scene's unbaked overlay edits back out, leaving the canonical file as what the scene carries. This is the second verdict on the edits `pendingSceneEdits` reports and a publication call refuses over: staging bakes them into the scene, this drops them. Each edit's overlay record is deleted and its entity withdrawn so no writer re-states it, whichever session wrote the record and however long it has stood. scene name. them. Omitted, every edit the scene has pending. and the ones still standing, each with the reason it does. While play runs unpaused the lock holds every removal under `/source`, so the edits come back blocked carrying that reason; `engine.paused = true` or `engine.mode = "edit"` opens the overlay.
| arg | type | description |
|---|---|---|
| name | string | The scene — a `.scene` folder path, a `scene.json` path, or a bare |
| select | (string | { string } | Which edits to drop: an entity id or entity name, or a list of |
examples
require("@builtin::assetTypes.scene.shared.saver").discardSceneEdits(layers.active.name)require("@builtin::assetTypes.scene.shared.saver").discardSceneEdits("/zero/source/scenes/main.scene", "look")forceRecordRemovals(layerKey: ?, target: ?) → void
Record, at an explicit persist point, every removal the overlay does not already carry: an entity the scene HAS a record for that is no longer live. The overlay learns of a despawn from that entity's dirty mark, and a mark is dropped wherever the engine REPRODUCES content rather than authors it — the spawn/despawn traffic of a scene load, a suppressed-marks window, a callback tick. An entity ADDED inside one of those windows still reaches the record, because `recordLiveAuthored` reads the whole live authored set at this same point whichever marks fired. This walks the other side of the same reconciliation — the records, against liveness — so an addition and a removal are equally durable however each was made. Scoped to the ACTIVE layer in EDIT mode: those are the conditions under which a record's entity being absent from the world means an author removed it. For any other layer the entities were never spawned, and the overlay takes authored marks only in edit, so absence elsewhere says nothing about intent. Scoped further to the ids this session has HELD. A scene is edited by several sessions at once, and a session that never built the entity a record names reads the same absence as the author of a despawn does — a record delivered while the session was away, an id whose entity its load did not build. What separates the two is whether the entity was ever here, so that is what is asked, and an id this session never held is left to the session whose entity it is. An entity whose record waits for its parent (`recordsAwaitingParent`) is absent because a load abandoned that record, so it is left to wait: its record stays as it stands, this session lets go of its claim on the entity, and the entity is built from the record once its parent arrives. `target` is the scene folder the caller goes on to compose from, passed in rather than re-resolved here so the removals land in the very overlay that compose reads. Returns one line per removal it could not record; empty when every removal the scene needs is on disk.
| arg | type | description |
|---|---|---|
| layerKey | ? | |
| target | ? |
record(eid: string, inCanonical: boolean) → void
A removal is a tombstone naming the entity, whichever side of the merge the record it removes came from: canonical carries its row through unless the overlay tombstones it, and an overlay-only body is read by every other session as the entity being there.
| arg | type | description |
|---|---|---|
| eid | string | |
| inCanonical | boolean |
recordBakedRemovals(target: ?) → void
The rows of `target`'s file whose entity no longer lives, recorded as removals: what the bake of an additive layer writes, since that layer holds exactly the entities its file names.
| arg | type | description |
|---|---|---|
| target | ? |
collectStatedRemovals(target: ?) → void
Take out of `target`'s overlay the removals this session stated a generation ago. An overlay-only id is absent from canonical, so a load composes without it whether or not its tombstone is still on disk — what the record does after the compose is reach the sessions already holding the entity, and one persist point of grace is what it is kept for. The overlay is then back to the size of the live authored set, so a scene rebuilt many times in one session (despawn- all + respawn with fresh ids) does not accumulate a file per entity ever made. Only this session's own statements are collected, and only while the record still says what this session wrote: a body at that path is another session authoring an entity onto the id, and a canonical row makes the tombstone the durable thing that suppresses it.
| arg | type | description |
|---|---|---|
| target | ? |
unrecordedRecordsError(op: string, name: any, unrecorded: { string }) → string
The message a persist point refuses with when it holds records it cannot put on disk. Composing a scene over an overlay missing them writes a file that still holds entities the author removed and lacks the ones they authored, so the operation states what it could not do instead of reporting the write it went on to make.
| arg | type | description |
|---|---|---|
| op | string | |
| name | any | |
| unrecorded | { string } |
joinUnrecorded(a: { string }, b: { string }) → void
Every line two record passes could not write, in one list.
| arg | type | description |
|---|---|---|
| a | { string } | |
| b | { string } |
withoutBuildBookkeeping(rec: any, bookkeeping: { string }) → any
`rec` without the attributes a scene build writes about itself, which describe the build rather than the scene.
| arg | type | description |
|---|---|---|
| rec | any | |
| bookkeeping | { string } |
recordLiveAuthored(layerName: ?, target: ?) → void
Record, at a persist point, every live authored entity of `layerName` whose record tells the scene something: one the overlay already holds a record for, one the canonical file has no record for, and one whose live record differs from the canonical one by the verdict `pendingSceneEdits` gives, leaving out the attributes a scene build writes about itself. An entity the canonical file already states as it stands is left without a record, so a persist point that finds no edit leaves the overlay as it was. Returns one line per body this pass could not put on disk. A persist point composes the scene over the overlay this pass just wrote, so a record it could not write is authored work the composed scene does not carry, and the caller states it rather than reporting the write it went on to make.
| arg | type | description |
|---|---|---|
| layerName | ? | |
| target | ? |
writeDirty(name: ?, opts: ?) → void
Force a synchronous drain + manifest rewrite so the dirty directory reflects every pending edit-mode mutation + the current scene-level config. Used by `wld.play()` before flipping mode and by explicit `SceneProxy:writeDirty()` callers. In the delta-overlay model `writeDirty` no longer snapshots the whole scene — it just ensures every pending mark has landed on disk and the manifest carries the latest scene-level config. Cheap regardless of scene size.
| arg | type | description |
|---|---|---|
| name | ? | |
| opts | ? |
hasDirty(name: ?) → void
True iff any dirty state exists for this target — manifest OR any per-entity overlay file. Either signals a pending change the loader needs to merge over canonical.
| arg | type | description |
|---|---|---|
| name | ? |
canonicalSignature(target: ?) → void
Signature of the CANONICAL scene.json bytes for `target`. Two calls return an identical string iff the on-disk canonical scene is byte-for- byte unchanged. The dirty overlay is deliberately excluded: it is the live session's working state and the continuous dirty writer rewrites it on every authored edit, so folding it in would make an idempotent same-scene reload trigger a full respawn on every keystroke. The idempotent same-guid `layers.load` uses this to tell a no-op (canonical unchanged) from a reload (canonical edited via write_file / edit_file). Returns "" when the canonical file is unreadable (treated as "unknown", which the caller resolves by reloading).
| arg | type | description |
|---|---|---|
| target | ? |
clearDirtyPerFile(name: ?, keep: { [string]: boolean }?) → void
Remove every file under the dirty directory one at a time. Fallback for environments where recursive remove is disabled (`vfs.allow_recursive_remove = false`).
| arg | type | description |
|---|---|---|
| name | ? | |
| keep | { [string]: boolean }? |
overlayHoldsOnly(name: ?, keep: { [string]: boolean }) → boolean
Whether the dirty overlay of `name` holds no manifest and no entity record but those of the entity ids `keep` names.
| arg | type | description |
|---|---|---|
| name | ? | |
| keep | { [string]: boolean } |
clearDirty(name: ?, keep: { [string]: boolean }?) → void
Wipe the dirty overlay (manifest + every per-entity file), all but the records of the entity ids `keep` names, which stay where they are. Returns true if anything was removed. The per-frame writer can accumulate thousands of per-entity files across one edit session (every map rebuild despawns the previous entities and spawns fresh-id ones). Removing them one VFS call at a time is an FFI round-trip per file — a bake on a large overlay then runs for minutes. A single recursive remove collects the subtree once and drops it in one operation, so clearDirty cost is independent of overlay size.
| arg | type | description |
|---|---|---|
| name | ? | |
| keep | { [string]: boolean }? |
filesSignature(target: ?) → string
What a scene's files hold, as one string: its canonical `scene.json` and every file of its dirty overlay, each with its bytes. Two reads give the same string exactly when neither the canonical file nor any overlay file changed between them, which is how a caller that rewrites files underneath a loaded scene tells whether it moved that scene. `scene.json` path, or a bare scene name.
| arg | type | description |
|---|---|---|
| target | ? | The scene's authoring target: a `.scene` folder path, its |
examples
local before = require("@builtin::assetTypes.scene.shared.saver").filesSignature(layers.active.asset.path)addFile(path: string) → void
| arg | type | description |
|---|---|---|
| path | string |
respawnFromFiles(layer: any, target: string, change: (() →
Take a loaded scene's live layer to what its files hold: the layer is respawned from the canonical `scene.json` composed with the overlay records standing beside it, with the scene-load gate held so the entities that come back are not marked as edits. `change`, when given, runs first inside the same gate: it is the act that changes the files, such as a discard deleting the overlay. Once the overlay holds nothing, what this session keeps about the overlay's records is let go, as clearing the overlay lets it go. Returns once the respawn's detached work (player, camera, avatar) has settled. Raises when the respawn raises.
| arg | type | description |
|---|---|---|
| layer | any | The layer holding the scene (a `SceneProxy` from `layers.list()`). |
| target | string | The scene's authoring target, the path its overlay is filed under. |
| change | (( | Optional function run inside the gate before the respawn. |
examples
local Saver = require("@builtin::assetTypes.scene.shared.saver")Saver.respawnFromFiles(layers.active, layers.active.asset.path)
promoteDirty(name: ?) → void
Compose canonical + dirty overlay → write canonical → clear dirty. Idempotent; nil when there are no dirty deltas to promote. A canonical write the VFS declines raises, the way `M.save` answers the same refusal: the clear below takes the overlay away, so that write is the whole bake, and nil is already this call's answer for a scene that had nothing to bake.
| arg | type | description |
|---|---|---|
| name | ? |
saveInto(name: ?, opts: ?) → void
Public `layers.active:save(opts)` entry point. Drains pending marks + freshens the manifest so live ECS state is captured even when the per-frame writer hasn't run since the last edit, then composes canonical + overlay → writes canonical → clears dirty. Same merge path as `promoteDirty`; this just guarantees the live state is in the overlay before composing.
| arg | type | description |
|---|---|---|
| name | ? | |
| opts | ? |
save(name: ?, opts: ?) →
Write the live layer of scene `name` into its canonical `scene.json`: the overlay of the session's edits merged over what the file holds. A record waiting for a parent that no record and no entity provides stays in the overlay, where it is built once its parent arrives, so `scene.json` carries no record a load of it cannot place; such a record that is a build's output, when the build has since placed its record identity on a new entity or places it no longer, is taken out of the scene instead. `opts.layer` names the source layer (default: `name`), `opts.sourceGuid` and `opts.sourcePath` the scene it was loaded from. `opts.bake = true` is a build baking what it placed: an additive layer, which records no edits of its own, is then recorded into the scene's own folder for the save.
| arg | type | description |
|---|---|---|
| name | ? | The scene to write: its path or identity. |
| opts | ? | `{ layer?, sourceGuid?, sourcePath?, bake? }`. |
examples
saver.save("/source/scenes/arena.scene", { layer = "arena" })drainManifests( ) → void
Rewrite the manifest of every layer whose scene-level config (lighting, config blocks) changed since the last drain.
drainOnce( ) → void
Take `__save.takeDirtyEntities()` + `__save.takeDirtyManifests()` and write every affected file, including every record still waiting from earlier frames. Idempotent / cheap to call when nothing is dirty.
writerFrame( ) → boolean
The continuous writer's frame: take the marks that landed, write one frame's budget of the oldest waiting records, and rewrite changed manifests. Answers whether records still wait, which has the engine run it again on the next frame whether or not another mark lands.
flushDirty( ) → void
Synchronous flush. Used by `wld.play()` immediately before the mode flip so every pending edit-mode mutation lands on disk before the VFS write-lock takes hold.
pendingRecords( ) → number
How many entity records the writer holds to write: the marks the engine has noticed, taken into the backlog, plus the records already waiting there. A caller about to wait for the writer reads this to know how long the wait is.
examples
if saver.pendingRecords() > 64 then log.info("the writer is behind") endflushDirtyAcrossFrames( ) → void
Put every pending edit-mode mark into the dirty overlay the way the continuous writer does: one frame's budget of records at a time, with the frame handed back between shares, so the time the calling frame spends is set by the budget however many entities the marks name. Returns once the overlay holds every mark taken. Where the caller cannot yield the whole backlog is written in the one frame, as `M.flushDirty` does. The edit to play flip calls this before it takes the write lock.
examples
saver.flushDirtyAcrossFrames()
getInstalledWatcherId( ) → void
setInstalledWatcherId(id: ?) → void
| arg | type | description |
|---|---|---|
| id | ? |
startDirtyWriter( ) → void
Event-driven drain. Subscribes once to `__save.onMarksLanded(callback)`; the engine schedule fires the callback once per frame whenever the dirty set transitions empty to non-empty since the previous drain, and again on the frame after any run that answers records are still waiting. Zero per-frame cost on idle frames. A reactive subscriber on each transition (`writerFrame`) plus the synchronous `M.flushDirty` (which `wld.play()` calls just before the mode flip) covers: • single mark: recorded on the next frame • marks across multiple frames: taken on every frame one lands, each entity waiting once however often it is marked • more marks than one frame's budget: written over the frames after, oldest first • mode flip: `flushDirty` synchronously writes everything before the VFS lock
PendingSceneEdit = {BlockedSceneEdit = { id: string, name: string?, reason: string }SceneEditDiscard = {Luau-side scene saver. Serializes the current scene state to scene.json v6 — authored intent only (no runtime player position, no captured camera transform). Wrapped by layers.active:save({to=name}).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.