Interface MazeRegistry

public interface MazeRegistry
Provides read-only access to saved maze records and their cell graphs.

All queries must be called on the server thread while MazeEngine is enabled. Calling from another thread or using the provider after disable throws IllegalStateException. Returned lists and snapshots are immutable; retaining them does not retain live Bukkit worlds or update their contents.

The registry includes records that are busy or have failed. A creation request still planning its topology has no record yet and is absent from queries. Use an operation handle to track that request until its record exists.

  • Method Details

    • all

      List<MazeSnapshot> all()
      Returns all records currently held by the maze service.

      Records are ordered by maze name and include preparing, generating, deleting, and failed mazes. Later changes are not reflected in this list.

      Returns:
      an immutable list of maze snapshots, or an empty list when none exist

    • find

      Optional<MazeSnapshot> find(MazeId id)
      Looks up a saved maze by its normalized identifier.

      A missing name and a new maze still in topology planning both produce an empty result. An existing busy or failed record can still be returned.

      Parameters:
      id - the maze identifier to look up
      Returns:
      the current maze snapshot, or empty when no record exists
      Throws:
      NullPointerException - if id is null

    • at

      Optional<MazeSnapshot> at(MazeLocation position)
      Finds a maze whose block volume contains the supplied world position.

      The world UUID and all three coordinates are checked against the inclusive bounds. A block above the roof or below the floor is outside the volume.

      Parameters:
      position - the world block position to test
      Returns:
      the containing maze snapshot, or empty when the block is outside every maze
      Throws:
      NullPointerException - if position is null

    • entrance

      TeleportDestination entrance(MazeId id)
      Resolves the default arrival point at the maze's entrance cell.

      The destination is centered in the corridor, one block above the floor, and faces inward from the entrance portal. This only resolves coordinates; it does not teleport a player or check current arrival-block safety.

      Parameters:
      id - the maze whose entrance should be resolved
      Returns:
      the entrance destination in the loaded maze world
      Throws:
      IllegalArgumentException - if the maze is missing or its world is not loaded

    • destination

      TeleportDestination destination(MazeId id)
      Resolves the maze's saved custom destination or its default entrance.

      A custom point may belong to a different world. The selected destination's world must be loaded. This query does not move a player or validate the current terrain at the returned point.

      Parameters:
      id - the maze whose arrival point should be resolved
      Returns:
      the custom destination, or the entrance when no custom point is saved
      Throws:
      IllegalArgumentException - if the maze is missing or the destination world is not loaded

    • route

      List<CellPosition> route(MazeId id, CellPosition from, CellPosition to)
      Finds a shortest route between two cells in the saved maze graph.

      Coordinates are zero-based logical cells, not world blocks. The returned route contains both endpoints; identical endpoints produce a single cell. The query uses saved topology and does not inspect blocks placed by players.

      The search is proportional to the maze's cell count and runs on the calling server thread. Retain a returned route when displaying it repeatedly.

      Parameters:
      id - the maze whose graph should be searched
      from - the starting cell within that maze
      to - the target cell within that maze
      Returns:
      an immutable ordered list from from to to
      Throws:
      IllegalArgumentException - if the maze is missing or either cell is outside its grid