Lost Lily/Grid ToolkitDocs 1.0
Table of Contents
IntermediateValidated 1.0.0

Snapshots and restoration

A snapshot is independent, versioned save data. Restoration applies it as a new validated commit.

Snapshot, resolver, and restore

A GridBoardStateSnapshot is independent versioned data. Extension resolvers translate owned extension types to stable payload formats and back. Restoring an existing board builds a normal revision-checked action plan, compares current and target state, and commits the difference atomically.

Restore an earlier board

Save a board at revision 1, move a structure at revision 2, and then restore the saved snapshot. The structure returns to its saved anchor, but the live board advances to revision 3. Restoration records the snapshot's source revision instead of rewinding the board's revision counter.

Rules for safe restoration

  • CreateSnapshotOrThrow fails when owned data cannot be serialized.
  • The diagnostic-returning creation API can report missing resolvers without throwing.
  • Combined snapshots include both definition and runtime state.
  • Unknown extension payloads remain independent data and are preserved when policy allows; malformed or disallowed payloads still reject restoration.
  • Restore validates schema, coordinates, structures, extensions, and admission rules before commit.
  • Every successful restore advances the current board revision once, including an identical restore. It does not rewind revision to the saved value. GridBoardRestoredEvent records the source snapshot revision.

Save and restore flow

flowchart TB
    accTitle: Snapshot creation and atomic restoration
    accDescr: Owned state passes through resolvers into an independent snapshot, which is validated, diffed, planned, and committed atomically during restoration.
    A["Owned state"] --> B["Resolver set"]
    B --> C["Versioned snapshot"]
    C --> D["Restore validation + diff"]
    D --> E["Revision-captured plan"]
    E --> F["Atomic commit"]
    F --> G["GridBoardRestoredEvent"]

What snapshots do not own

Grid Toolkit creates and restores typed snapshots. File paths, encryption, compression, JSON options, cloud transport, and save-slot policy belong to the game.