Log inGet started
Package

shared.module

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

Scene composition transactions

capture(folder, inputs) reads a scene and its authored records under a world-bound source transaction. Capture build inputs before evaluating the builder, and pass the resulting document to rebuild. edit accepts saved entity records before and after an authored change. Both compose and validate before preparing an atomic update of the accepted generated base, intent records, and scene.json.

editChanges(snapshot, entities, settingsEdits, opts, retirePaths?, attribution?) accepts compact observed field changes. Each entity row has id, changes from FieldEdits.diff over normalized records, and optional component bookkeeping. Settings use field edits over the scene fields. Changes retain their original observed values when retried against a newer snapshot. retirePaths names captured journal files removed atomically with the accepted composition; a newer journal revision makes the entire transaction stale. editDocument projects saved documents into this same field-change path.

Journal consumers pass a session/sequence receipt to editChanges with the corresponding captured operation path in retirePaths. The coordinator checks the consecutive sequence, records its checksum in accepted state and retires that source atomically. Rebuilds preserve these receipts. assetTypes.scene.shared.journal handles operation creation, persistence, recovery and retry checks.

migrate accepts a legacy visible document derived from the captured scene and overlay, together with a recovered generated base when available. It retains the canonical and visible documents as recovery history and records unresolved baseline identities.

An unresolved identity holds the entity as a whole-entity addition, because its generated value was unknown. rebuild and incorporate resolve it against their candidate through resolveBaselines: a candidate that states the identity states its baseline, so the addition becomes field intents over that generated value (every field the authored entity holds differently stays authored) and the identity leaves the unresolved list. An identity the candidate does not state stays unresolved.

incorporate prepares source replacements together with selected intent retirement. Each selection names an entity (or scene settings), the captured intent revision, and exact field paths. The candidate generated value must reproduce every selected value. Unselected intents remain. Candidate source fingerprints, the generated base, build digest and artifact advance together.

For a loaded scene’s build.luau, scene:prepareSourceChange(sourcePlan, selections) evaluates the candidate from SourceEditing.prepareTarget. It returns the coordinator plan together with the target’s scope and known outputs. Candidate evaluation uses isolated capture: persistent writes, external requests, deferred task work and foreign-entity changes are refused. Component lifecycle work on candidate-owned entities is captured and cleaned up.

awaitApplied(folder, revision, scope) waits for an accepted complete revision to arrive through the local subscription. A committed result acknowledges backend persistence; this wait establishes local visibility.

commit returns the durable source-operation result. Its operation identity supports inspection, retry and cancellation through modules.sourceOperations. Runtime scene activation observes the committed files. Structural conflicts return a plan with ready=false and preserve the last valid document.