Lost Lily/Grid ToolkitDocs 1.0
Table of Contents
IntermediateValidated 1.0.0

Save and restore state

When to use

Save and restore state when a game must capture a board, continue mutating it, and later restore the saved values atomically without exposing partial changes to observers.

Before you start

Start with a ready board and all structure definitions and extension resolvers needed by the saved state.

Register resolvers for every persisted extension and keep the structure-definition resolver available when restoring definition and runtime state together. This example has no extensions, so the empty resolver set is sufficient.

Procedure

Excerpt — create a snapshot and restore it atomically. Tested using public APIs.

public static RestoreWorkflowResult SaveMutateAndRestore()
{
    using GridBoardState state = CreateProgrammaticBoard();
    GridStructureDefinition crate = CreateCrate();
    GridActionRunner.Apply(
        state,
        GridActions.PlaceStructure(
            crate,
            new SquareGridCoordinate(0, 0),
            instanceId: "crate-1"));
    GridBoardStateSnapshot snapshot = state.CreateSnapshotOrThrow();

    GridActionRunner.Apply(
        state,
        GridActions.MoveStructure(
            crate,
            "crate-1",
            new SquareGridCoordinate(2, 1)));
    GridActionResult restored = GridActionRunner.ApplySnapshot(state, snapshot);
    state.TryGetStructure("crate-1", out GridStructureInstance structure);

    return new RestoreWorkflowResult(
        restored.Success,
        snapshot.Revision,
        state.Revision,
        structure?.Anchor);
}

Serialize the detached GridBoardStateSnapshot with the game’s save format. On load, deserialize it and call BuildRestorePlan to inspect a result before Apply, or call ApplySnapshot directly.

Result

The snapshot records revision 1. Movement advances the live board to 2; restoration returns the structure to (0,0) and advances the live board to revision 3. The restore event records that revision 1 was the snapshot source.

Troubleshooting

Symptom Check
The snapshot schema is unsupported. Migrate from a supported source or recreate the save.
Restore cannot resolve an extension payload. Register the resolver for the exact stable extension and payload IDs.
An unknown payload is rejected. Choose the intended preserve, drop, or error policy explicitly.
Current admission policies reject saved occupancy. Decide whether to change those policies or reject the restore; no partial state is committed.