Interface MapView

public interface MapView
A map known to the server: the picture behind every filled_map item with its id.

A map is made of three things, drawn in this order:

  1. its canvas, the pixels it stores. On a map that shows a world and is not locked, the terrain is drawn there as players carrying it explore, like in vanilla;
  2. its layers, painted by plugins on top, never stored;
  3. icons: the persistent markers, those of the layers, and the arrows of players when the map tracks them.

Players see a map while they carry it, while it is shown to them, and while it hangs in a frame only they see. Changes reach them on the next tick, or right away with flush(). A map is safe to use from any thread.

Since:
0.1.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addLayer(MapLayer layer)
    Adds a layer on top of the others, and paints it.
    MapCanvas
    canvas()
    Returns the pixels the map stores.
    void
    center(int x, int z)
    Moves the area the map shows.
    int
    centerX()
    Returns the X coordinate of the block at the center of the map.
    int
    centerZ()
    Returns the Z coordinate of the block at the center of the map.
    void
    flush()
    Sends what changed to everyone who sees the map, now rather than on the next tick.
    Collection<MapFrame>
    frames()
    Returns the frames this map hangs in.
    MapFrame
    hang(Player viewer, BlockPosition block, BlockFace facing, boolean invisible)
    Hangs the map in an item frame that only one player sees.
    void
    hide(Player player)
    Stops sending the map to a player who does not carry it.
    int
    id()
    Returns the id, stored on items in the minecraft:map_id component.
    ItemStack
    item()
    Creates an item showing this map.
    List<MapLayer>
    layers()
    Returns the layers, bottom to top.
    boolean
    locked()
    Returns whether the terrain stopped being drawn, like a map locked in a cartography table.
    void
    locked(boolean locked)
    Locks or unlocks the terrain.
    MapMarkers
    markers()
    Returns the icons the map stores.
    double
    pixelX(double x)
    Converts a world X coordinate to a canvas column.
    double
    pixelY(double z)
    Converts a world Z coordinate to a canvas row.
    boolean
    removeLayer(MapLayer layer)
    Removes a layer.
    CompletableFuture<@Nullable Void>
    renderTerrain()
    Draws the terrain of the whole map now, instead of waiting for players to explore it.
    void
    repaint()
    Repaints every layer on the next tick.
    void
    repaint(MapLayer layer)
    Repaints one layer on the next tick.
    MapScale
    scale()
    Returns how many blocks a pixel covers.
    void
    scale(MapScale scale)
    Changes how many blocks a pixel covers.
    void
    show(Player player)
    Sends the map to a player even when they do not carry it, until hide(Player) or they leave.
    boolean
    temporary()
    Returns whether the map is temporary: never saved, and forgotten with the server.
    boolean
    tracksFarPlayers()
    Returns whether players far away from the map are still shown, as small dots on its edge.
    void
    tracksFarPlayers(boolean tracksFarPlayers)
    Shows or hides players far from the map.
    boolean
    tracksPlayers()
    Returns whether players in the world of the map are shown as arrows.
    void
    tracksPlayers(boolean tracksPlayers)
    Shows or hides the arrows of players.
    Collection<Player>
    viewers()
    Returns the online players who currently see the map.
    Optional<Key>
    world()
    Returns the world whose terrain and players the map shows; empty for a blank map.
    void
    world(@Nullable Key world)
    Sets the world the map shows.

  • Method Details

    • id

      int id()
      Returns the id, stored on items in the minecraft:map_id component.
      Returns:
      the id, stored on items in the minecraft:map_id component
      Since:
      0.1.0

    • temporary

      boolean temporary()
      Returns whether the map is temporary: never saved, and forgotten with the server.
      Returns:
      whether the map is temporary: never saved, and forgotten with the server
      Since:
      0.1.0
      See Also:

    • world

      Optional<Key> world()
      Returns the world whose terrain and players the map shows; empty for a blank map.
      Returns:
      the world whose terrain and players the map shows; empty for a blank map
      Since:
      0.1.0

    • world

      void world(@Nullable Key world)
      Sets the world the map shows. Pixels already drawn stay until explored again.
      Parameters:
      world - the key of the world, or null to show none
      Since:
      0.1.0

    • centerX

      int centerX()
      Returns the X coordinate of the block at the center of the map.
      Returns:
      the X coordinate of the block at the center of the map
      Since:
      0.1.0

    • centerZ

      int centerZ()
      Returns the Z coordinate of the block at the center of the map.
      Returns:
      the Z coordinate of the block at the center of the map
      Since:
      0.1.0

    • center

      void center(int x, int z)
      Moves the area the map shows. Pixels already drawn stay until explored again.
      Parameters:
      x - the X coordinate of the new center
      z - the Z coordinate of the new center
      Since:
      0.1.0
      See Also:

    • scale

      MapScale scale()
      Returns how many blocks a pixel covers.
      Returns:
      how many blocks a pixel covers
      Since:
      0.1.0

    • scale

      void scale(MapScale scale)
      Changes how many blocks a pixel covers. Pixels already drawn stay until explored again.
      Parameters:
      scale - the scale
      Since:
      0.1.0

    • locked

      boolean locked()
      Returns whether the terrain stopped being drawn, like a map locked in a cartography table.
      Returns:
      whether the terrain stopped being drawn, like a map locked in a cartography table
      Since:
      0.1.0

    • locked

      void locked(boolean locked)
      Locks or unlocks the terrain. The canvas can still be drawn on by plugins either way.
      Parameters:
      locked - whether to stop drawing the terrain
      Since:
      0.1.0

    • tracksPlayers

      boolean tracksPlayers()
      Returns whether players in the world of the map are shown as arrows.
      Returns:
      whether players in the world of the map are shown as arrows
      Since:
      0.1.0

    • tracksPlayers

      void tracksPlayers(boolean tracksPlayers)
      Shows or hides the arrows of players.
      Parameters:
      tracksPlayers - whether to show players
      Since:
      0.1.0

    • tracksFarPlayers

      boolean tracksFarPlayers()
      Returns whether players far away from the map are still shown, as small dots on its edge.

      Otherwise, only players up to 320 blocks outside it are, like vanilla maps that were not made from an explorer map.

      Returns:
      whether players far away from the map are still shown, as small dots on its edge
      Since:
      0.1.0

    • tracksFarPlayers

      void tracksFarPlayers(boolean tracksFarPlayers)
      Shows or hides players far from the map.
      Parameters:
      tracksFarPlayers - whether to show far players
      Since:
      0.1.0

    • canvas

      MapCanvas canvas()
      Returns the pixels the map stores.
      Returns:
      the pixels the map stores
      Since:
      0.1.0

    • markers

      MapMarkers markers()
      Returns the icons the map stores.
      Returns:
      the icons the map stores
      Since:
      0.1.0

    • addLayer

      void addLayer(MapLayer layer)
      Adds a layer on top of the others, and paints it.
      Parameters:
      layer - the layer
      Since:
      0.1.0

    • removeLayer

      boolean removeLayer(MapLayer layer)
      Removes a layer.
      Parameters:
      layer - the layer
      Returns:
      whether the map had it
      Since:
      0.1.0

    • layers

      List<MapLayer> layers()
      Returns the layers, bottom to top.
      Returns:
      the layers, bottom to top
      Since:
      0.1.0

    • repaint

      void repaint()
      Repaints every layer on the next tick.
      Since:
      0.1.0

    • repaint

      void repaint(MapLayer layer)
      Repaints one layer on the next tick.
      Parameters:
      layer - the layer
      Since:
      0.1.0

    • viewers

      Collection<Player> viewers()
      Returns the online players who currently see the map.
      Returns:
      the online players who currently see the map
      Since:
      0.1.0

    • show

      void show(Player player)
      Sends the map to a player even when they do not carry it, until hide(Player) or they leave. Needed when the map is only visible to them in a frame or another item.
      Parameters:
      player - the player
      Since:
      0.1.0

    • hide

      void hide(Player player)
      Stops sending the map to a player who does not carry it.
      Parameters:
      player - the player
      Since:
      0.1.0

    • hang

      MapFrame hang(Player viewer, BlockPosition block, BlockFace facing, boolean invisible)
      Hangs the map in an item frame that only one player sees.

      The frame takes up block in the world of the viewer and shows its front towards facing: a frame facing BlockFace.SOUTH hangs on the north side of the block and is looked at from the south. Nothing needs to be behind it. Several frames, even of the same map, may take up the same block.

      Parameters:
      viewer - the only player who sees the frame
      block - the block the frame takes up
      facing - the direction the front of the frame faces
      invisible - whether to hide the frame itself, leaving only the map
      Returns:
      the frame, hanging until removed
      Throws:
      IllegalArgumentException - if the viewer is not connected, or the map was deleted
      Since:
      0.1.0

    • frames

      Collection<MapFrame> frames()
      Returns the frames this map hangs in.
      Returns:
      the frames this map hangs in
      Since:
      0.1.0

    • flush

      void flush()
      Sends what changed to everyone who sees the map, now rather than on the next tick.
      Since:
      0.1.0

    • renderTerrain

      CompletableFuture<@Nullable Void> renderTerrain()
      Draws the terrain of the whole map now, instead of waiting for players to explore it.

      Chunks that are not loaded are loaded, or generated, in the background. Does nothing on a map without world.

      Returns:
      completed once the canvas holds the whole area
      Since:
      0.1.0

    • item

      ItemStack item()
      Creates an item showing this map.
      Returns:
      a single filled_map
      Since:
      0.1.0

    • pixelX

      double pixelX(double x)
      Converts a world X coordinate to a canvas column.
      Parameters:
      x - the X coordinate
      Returns:
      the column, outside 0-128 when the coordinate is off the map
      Since:
      0.1.0

    • pixelY

      double pixelY(double z)
      Converts a world Z coordinate to a canvas row.
      Parameters:
      z - the Z coordinate
      Returns:
      the row, outside 0-128 when the coordinate is off the map
      Since:
      0.1.0