Class MazeSnapshot

java.lang.Object
dev.despical.mazeengine.api.model.MazeSnapshot
public final class MazeSnapshot extends Object
Captures an immutable description of a saved maze at one point in time.

The description contains identity, world bounds, frozen preset metadata, topology statistics, and the saved lifecycle state. It can be retained after regeneration or deletion and read on other threads, but never updates itself.

Typical use cases:

  • Displaying maze ownership, dimensions, and generation settings
  • Recording the final state delivered by an operation event
  • Comparing a previous description with a newly queried record
Coordinates and graph statistics describe saved metadata, not a live scan of the world. A captured custom destination does not retain a Bukkit world.

  • Constructor Details

    • MazeSnapshot

      public MazeSnapshot(MazeId id, String worldName, UUID owner, MazeBounds bounds, CellSize cells, long seed, PresetSnapshot preset, MazeSnapshot.Status status, boolean hasSnapshot, Instant createdAt, TeleportDestination teleportDestination, CellPosition entrance, CellPosition exit, int routeLength, int deadEnds, String error)
      Constructs a point-in-time description from saved maze metadata.

      The custom destination is supplied directly, or as null when the default entrance should be used. Other values describe the record at capture time; this constructor does not query the world or persist a maze.

      Parameters:
      id - the normalized saved maze identifier
      worldName - the saved world name
      owner - the creator UUID, or the zero UUID for administrative creation
      bounds - the complete world block bounds
      cells - the logical grid dimensions
      seed - the saved generation seed
      preset - the maze's saved preset metadata
      status - the captured lifecycle state
      hasSnapshot - whether original terrain capture is recorded
      createdAt - the initial creation timestamp
      teleportDestination - the custom destination, or null to use the default entrance
      entrance - the entrance cell
      exit - the exit cell
      routeLength - the shortest route length in cell edges
      deadEnds - the number of graph dead ends
      error - the recorded failure text, empty when none is recorded

  • Method Details

    • id

      public MazeId id()
      The normalized identifier of the captured maze.

      The identifier can be reused after deletion. Retaining a snapshot does not make it a description of a later maze created under the same name.

      Returns:
      the normalized saved maze identifier

    • worldName

      public String worldName()
      The world name stored in the maze record.

      Use MazeBounds.origin() and its world UUID for coordinate identity; the name is descriptive metadata captured in the record.

      Returns:
      the saved world name

    • owner

      public UUID owner()
      The UUID of the player who originally created the maze.

      Creation by a non-player administrative actor uses the zero UUID. This value records ownership rather than the actor of the latest operation.

      Returns:
      the creator UUID

    • bounds

      public MazeBounds bounds()
      The inclusive world block volume occupied by the maze.

      The volume includes the floor, walls, passages, and any roof. Logical cell coordinates must be interpreted with the saved geometry.

      Returns:
      the complete world block bounds

    • cells

      public CellSize cells()
      The logical dimensions of the maze graph.

      These dimensions count cells rather than blocks. Corridor width and wall thickness are described by preset().

      Returns:
      the logical grid dimensions

    • seed

      public long seed()
      The deterministic seed retained by this maze.

      Together with the saved generation settings, the seed describes topology generation. It does not describe later player edits to world blocks.

      Returns:
      the saved generation seed

    • preset

      public PresetSnapshot preset()
      The frozen preset metadata retained by this maze.

      Configuration reloads do not replace this captured metadata. Query the preset registry separately to inspect settings for new mazes.

      Returns:
      the maze's saved preset metadata

    • status

      public MazeSnapshot.Status status()
      The lifecycle state at the time this description was captured.

      The snapshot does not change as an operation progresses. DELETED is used for successful removal results rather than a live registry entry.

      Returns:
      the captured lifecycle state

    • hasSnapshot

      public boolean hasSnapshot()
      Whether the record indicates an original terrain snapshot was captured.

      This flag does not verify that the schematic file still exists. Restore operations check snapshot availability when they are submitted.

      Returns:
      whether original terrain capture is recorded

    • createdAt

      public Instant createdAt()
      The timestamp of the maze's initial creation record.

      Regeneration and repair retain this timestamp. It is distinct from the completion time of a later operation.

      Returns:
      the initial creation timestamp

    • teleportDestination

      public Optional<TeleportDestination> teleportDestination()
      The saved custom arrival point, when one exists.

      Absence selects the default entrance destination. A custom point can refer to a different world, and capturing it does not require that world to be loaded.

      Returns:
      the custom destination, or empty when no custom point is saved

    • entrance

      public CellPosition entrance()
      The zero-based cell containing the entrance portal.

      This is a logical graph coordinate. Use the maze registry to resolve the world-space arrival position and inward-facing yaw.

      Returns:
      the entrance cell

    • exit

      public CellPosition exit()
      The zero-based cell containing the exit portal.

      The generator selects a farthest boundary exit. The coordinate describes the saved graph even if the corresponding world blocks have been edited.

      Returns:
      the exit cell

    • routeLength

      public int routeLength()
      The shortest entrance-to-exit distance in the saved graph.

      Distance is measured in cell edges, so a route containing N cells has length N minus one. It is not a distance in world blocks.

      Returns:
      the shortest route length in cell edges

    • deadEnds

      public int deadEnds()
      The number of cells with exactly one internal graph connection.

      External entrance and exit portals are not additional internal edges. This statistic describes topology rather than the current world terrain.

      Returns:
      the number of graph dead ends

    • error

      public String error()
      The failure explanation retained by the maze record.

      An empty string means no failure explanation is recorded. Use the failure event's cause when the underlying exception is needed.

      Returns:
      the recorded failure text, empty when none is recorded

    • equals

      public boolean equals(Object other)
      Compares all captured values with another instance.

      Equality is based on contents rather than object identity, including any absent override or custom destination.

      Overrides:
      equals in class Object
      Parameters:
      other - the object to compare
      Returns:
      whether the other instance contains the same values

    • hashCode

      public int hashCode()
      Returns a hash code based on all captured values.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code corresponding to equals(Object)

    • toString

      public String toString()
      Formats the captured values for diagnostics.

      The representation is intended for logging, not as a persistence format.

      Overrides:
      toString in class Object
      Returns:
      a description containing the captured field values