shared.module
This package holds more than this page lists. See all of its files in its world.
README.md
Scene intent storage
Require @builtin::assetTypes.scene.shared.intents.
The store keeps one versioned JSON record per entity under a scene's authoring/entities folder. The filename is the entity id encoded as UTF-8 hex; the record carries its readable id, revision, field edits, per-edit attribution and component reconstruction metadata.
read(sceneFolder, entityId)captures the current record and exact source identity/bytes in a frozen snapshot.readAll(sceneFolder)discovers every entity record, including manual additions, and verifies that each filename matches its entity id.prepare(snapshot, generated, previous, current, bookkeeping?, attribution?)records an operation over normalized SceneRecords values. Use the accepted generated base and the visible values before and after the operation. Independent fields merge with existing intent. Overlapping unseen changes return a conflict for the caller to retain and resolve.apply(plan)creates an absent file withoverwrite=false, or updates it through sourceEditing's snapshot check. A stale plan leaves the newer file intact. Empty intent records retain their revisions.
prepareChanges(snapshot, generated, changes, bookkeeping?, attribution?) accepts field changes produced by FieldEdits.diff. Each change retains its observed and proposed values. It composes those changes over the latest accepted intent, preserving independent fields and returning conflicting values for overlapping edits. Entity identity and the settings document shape are validated before a prepared result is returned. prepare computes these changes from its before/after values and uses the same path.
readSettings(sceneFolder) reads the scene-wide record at authoring/settings.json. Pass that snapshot to prepare with the scene fields after removing entities, then apply the prepared result. All three settings values must be tables. Settings carry their own revision, and entity enumeration remains scoped to entity records. Supply the returned settings edits to SceneComposition.compose alongside the entity intents.
Version 3 stores field history as a readable JSON array under edits, one entry per field edit with its earlier and later values, and exposes active dependencies through references. The references describe the merged visible entity, including component identities and asset envelopes; the scene asset type declares references as the only field of these files that carries dependencies, so an asset a historical value names stays data. Historical values remain available for conflict detection. Reads accept version 1 records and version 2 records, whose history is an encoded string; the next changed operation, and a scene copy, writes version 3. Opening a scene rewrites nothing. Snapshot records expose decoded field edits to callers. unpackSettings(source) and packSettings(record) decode and encode a settings file in that form.
Scene inspection exposes a bounded authoring summary, also available through sceneRef:authoringStatus(): recorded pending scene edits, entity intent and field counts, settings field count, and explicit read errors. complete indicates that these reads succeeded; the summary observes recorded state without draining queued scene writes. hasRecordedEdits indicates that at least one recorded change exists. These counts include retained satisfied intents.
The returned VFS report distinguishes durable source, play shadow and scratch. This per-file operation uses the world's existing synchronization and conflict protocol. Callers coordinate these records with build sources and generated artifacts.