Interface Snapshot

public interface Snapshot
Defines indexed capture, restoration, and persistence of original terrain.

Capture and restore operate on the same bounded volume and use its linear block index. Implementations retain complete block state, including block entity data, so deletion can restore the terrain recorded before generation.

Live world capture and restoration run on the server thread in operation tick budgets. Writing the completed snapshot runs on the serial storage executor. The operation owner waits for persistence before marking the snapshot usable or starting the corresponding world mutation.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    capture(long index)
    Copies the original state of one world block into this snapshot.
    void
    restore(long index)
    Writes one captured block back to its original world position.
    void
    write(Path path)
    Persists the completed snapshot for a later terrain restoration.

  • Method Details

    • capture

      void capture(long index) throws Exception
      Copies the original state of one world block into this snapshot.

      The index uses the bounded volume's X-first, then Z, then Y traversal. Implementations retain block state and supported block-entity data at the corresponding position. Call this method on the server thread before the operation replaces that block; capture does not mutate the world.

      The operation owner divides capture across its tick budget and waits until the full volume has been captured before persisting the snapshot.

      Parameters:
      index - the zero-based block index within the snapshot volume
      Throws:
      Exception - if the original block state cannot be captured

    • restore

      void restore(long index) throws Exception
      Writes one captured block back to its original world position.

      The index follows the same traversal used during capture. Restoration replaces the live block and restores the block-entity data supported by the implementation. The caller must run on the server thread and perform permission, region, and player-safety checks before beginning restoration.

      Restoring one index does not complete or commit the surrounding operation. The operation owner advances the remaining indices under its tick budget and records the terminal result after all required writes succeed.

      Parameters:
      index - the zero-based block index within the snapshot volume
      Throws:
      Exception - if the captured state cannot be restored to the world

    • write

      void write(Path path) throws Exception
      Persists the completed snapshot for a later terrain restoration.

      All capture calls must finish before writing begins. This method consumes the retained snapshot data without reading live world blocks, allowing the operation owner to invoke it on the serial storage executor. Concurrent capture, restoration, or writes against the same snapshot are unsupported.

      Returning normally means the implementation completed its file write. The caller still owns the operation journal and marks the snapshot usable only after persistence succeeds.

      Parameters:
      path - the destination snapshot file
      Throws:
      Exception - if the snapshot cannot be encoded or written