shared.module
- ..
- .metadata273 B
- README.md3.5 KB
- init.luau343 KB
- recordDiff.module
- serialize.module
This package holds more than this page lists. See all of its files in its world.
README.md
scene.shared.saver
Scene persistence for authored entities and scene settings. Persistent v7 scenes compose their generated base with durable authored intent and materialize scene.json through a source transaction.
The loader establishes observed entity and setting values before returning the scene to its caller. Authored mutations are recorded as ordered session operations. Incoming accepted revisions first drain pending marks, compose recorded changes over the accepted artifact, and refresh the observed values after application. Reload uses the same pending composition. Capture retries remain in the saving phase until they settle or produce a terminal error.
save and promoteDirty consume observed operations under scene_dirty/operations in session order. They retire each accepted entry with its composition and receipt. A conflicting entry remains durable; authoringPersistence reports its path, conflicts, error and pending-operation count. hasDirty includes these entries. Mixed legacy overlays and observed operations are retained with an explicit reconciliation error.
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.