README

A dynamic web-based world map for PocketMine-MP servers.
For a full overview over all functions of the plugin, go to the documentation

What is new in v0.5

The /pocketmap (or /pmap) command is now available, the previous commands (/render and /reload) are now sub-commands!
- For a list of all available commands, use: /pmap help
Markers - Now you can mark spots on your map with icons using commands (/pmap marker).

Go to the changelogs

How to install

Download the newest version of the plugin from Poggit CI
Place the plugin in the plugins folder of your PocketMine-MP server
Restart your server, this will load the plugin data.
- If you are not hosting your server locally, you have to allocate a new port to your server.
1. Allocate a new port for your server. If you don't know how to do this, contact your hosting provider.
2. Go to the config.yml and change web-server.port to your new allocated port (replace 3000).
3. Restart your server again.
Go to http://<server_ip>:<web-server.port> to see the map.

The default webserver port is 3000, so if you haven't changed it, use this port.

How to use

Render a full world

If you have already created a world, and it is not yet (completely) visible on PocketMap, do the following:

Execute /pmap render full <world> This will start a full world render for the given world. It can take a while before the complete map is loaded, and if your server stops/restart during the full render you have to start the full render again.

Render new chunks

When you load new chunks in your world which have not been added to the map, the chunks will automatically be rendered.
If there are still chunks missing, make a full render of the world by executing /pmap render full <world>

Render updated chunks

When a player breaks or places blocks, the map will automatically be updated after some time.

Change rendering speed

If the rendering speed is too slow for you, or your server can't handle it anymore, you can change some values in the config.yml to resolve these issues.

Go to the config.yml
Look in the settings under renderer
If you want to alter the rendering speed, change some values in scheduler
If you want to alter the rendering speed of updated chunks, change values in chunk-scheduler

Issues

Please report all issues you encounter here.

TO DO

This is a list of all things that have to be added before the release of v1.0.0

Commands

Create fork of Commando to make use of commands with different argument overloads
Add an x z (vector 2) argument type instead of x y z (vector 3)

WebPage

List of all online players
Option to hide map icons
- markers, players, etc
Cleaner UI
Show time in the world

Renderer

Better visualization of height difference
Block Lighting
Test/add support for other dimensions

API

Support for plugins to add their own API's to PocketMap
- Let a plugin register files to /api/<plugin_name>
Support for JS modules to extend the functionality of the web page.
- These modules can be used to access a plugin's API endpoint on the web server.
Add better documentation for the MarkerManager class such that plugins are able to make use of the build in marker system.

Credits

PMMP WebServer by me for creating the website and API.
LibSkin by HimbeersaftLP for player heads.
Commando fork by Paroxity for commands.
SimplePacketHandler by Muqsit for Commando.
Bedrock Samples by Mojang for the latest block textures used in the map
Leaflet.js for the interactive map
OpenMoji for a large range of default icons

Documentation

This is the documentation of a lot of the PocketMap features.

Commands
Web Map
Textures
Markers

Commands

Command Arguments

Some commands also need arguments, the following argument types are provided in this readme:

< ... >: required
{ ... }: optional for players but required for console, current location of the player is used when not provided
[ ... ]: optional, default values will be used

Help Command

Get a list of all command. Usage: /pmap help

Marker Command

Usage: /pmap marker

Common command arguments

name: Name of the marker, required.
world: Name of the world the marker is in
id: Custom identifier for a marker
position: Position (x y z)
icon: Name of the icon defined in markers/icons.json
- Look here for more info about adding your own markers.
pos1: First position (x y z)
pos2: Second position (x y z)

Add Markers Command

Add markers to you map

Icon markers: /pmap marker add icon <name> <icon> {position} {world} [id]
- Create an icon marker on the given position
Circle markers: /pmap marker add circle <name> <radius> {position} {world} [id]
- radius: The radius (in blocks) of the circle, required
- Create a circle with the given radius at the given position
Area Markers: /pmap marker add area <name> <pos1> {pos2} {world} [id]
- Create a rectangular area with pos1 and pos2 as corners
Line Markers: /pmap marker add line <name> <pos1> {pos2} {world} [id]
- Create a line between pos1 and pos2

Remove Markers Command

You can remove any marker with the marker remove command. Usage: /pmap marker remove <id> {world}

You can only remove markers which have there id defined in markers/markers.json.

Reload Command

Reload some parts of the plugin data, this will apply most changes in the running plugin.

Not all changes will be applied with this command, to make sure all changes are applied, a restart is recommanded.

Available parts:

config: Reload the plugin config
data: Reload the folder structure
web: Reload the web config

Usage: /pmap reload <part>

Render Command

You can render a specific area of the map by using the render command.
Usage: /pmap render {x} {z} {world} {zoom}

x: The x coordinate of the region
z: The z coordinate of the region
world: THe world name of the region
zoom: The zoom level of the region in the interval [0,8], where zoom is an area of 2^zoom * 2^zoom chunks (0=1 chunk, 8=256*256 chunks)

Full Render Command

Start a full world render for the given world.
Usage: /pmap render full {world}

Render Lookup Command

Lookup the chunk and region coordinates of a given world position.
Usage: /pmap render lookup {x y z} [zoom]

x y z is the position in the world
zoom is the amount of zoom regions you want the region coordinates from.
- Default: 0 Output:
- Coords (x,z): the given x and z coordinates
- Chunk (x,z): The chunk x,z coordinates where the given position is in.
- Regions (zoom/x,z): A list of all zoom regions in the range [0,zoom]

Web Map

On the webpage of PocketMap (http://<server_ip>:<pocketmap_port>/) you can view the real map. On the map you can do the following:

View the location of all online players
View all world maps (Currently only the overworld is tested)
- You can select the world you want to view using buttons on the page
View all created markers at each world
View coordinates you are currently hovering on
- When you click on the map, the coordinate will be added in the URL which can be used to share the location with others.
Zoom in and out of the map.
- This is managed by different zoom levels for the world, the zoom levels are in the interval [0,8], default zoom level is 4. You can change some of these items in the config.yml or web/config.json

Textures

PocketMap makes use of the vanilla resource pack provided by bedrock-samples. To make PocketMap more consistent with your server, all resource packs you use in your server are also used in PocketMap.

Encrypted packs are not yet implemented

Rendering

To show the map on the webpage, the minecraft world has to be rendered as images first. This is a complex process, and I'm constantly improving the rendering algorithm to make it faster and more efficient.

From chunk to image

When a chunk is being rendered, we loop through all x,z positions in the chunk and get the highest block at each of the positions.
For each block we get the block type name and the block state. With these values, the correct texture is inside the resource_packs/terrain_textures.json is found and used as the texture in the map.
Not all blocks are the same, and PocketMap tries to make all blocks appear like in the minecraft world, such as

Apply the right color from the color map for grass and foliage (leaves, etc)
Apply biome colors for water
Apply models for blocks like fences, buttons, etc. such that they have the right position and size on the map.
Apply height difference for blocks
- For now, blocks with y%2 = 1, will appear a bit darker than blocks with y%2 = 0
Apply water transparency for blocks that are underwater using the correct values per biome
Opaque blocks are visible through transparent blocks

Markers

There are different types of markers you can use in PocketMap. You can add three different types of markers using commands, but it is also possible to add markers by hand. The markers that are visible on the web map are all defined in the file markers/markers.json. It is also possible to add markers by hand.

Marker types

icon: An icon displayed at a given position
circle: A circle with its center at the given position and a given radius in blocks
polygon: An area with the given corners, at least 3 corners need to be provided.
polyline: A line with multiple points, lines will be drawn between one point and the next.

Command Markers

You can add some markers using commands. Please go to the marker command documentation for more details.

Plugin Markers

It is possible for plugins to make use of PocketMaps built-in marker system.

Add PocketMap to the softdepend list in your plugin.yml. (Don't use the depend list, as this requires all users to use PocketMap otherwise they can't use your plugin).

softdepend: [
  ..., # Other plugins
  PocketMap
]

Include use Hebbinkpro\PocketMap\PocketMap; where you want to use the add markers.
Add your markers

if (class_exists(PocketMap::class)) {
    $markers = PocketMap::getMarkers(); 
}

If you don't include PocketMap in the (soft)depend list, you cannot make use of the MarkerManager in the plugin's onEnable function.
You cannot use the MarkerManager in the plugin's onLoad function.

Available functions

$markers->getIcons(): array
$markers->getMarker(string $id, World $world): ?array
$markers->removeMarker(string $id, World $world): bool

$markers->addIconMarker(string $name, Position $pos, string $icon, ?string $id = null): bool
$markers->addCircleMarker(string $name, Position $pos, int $radius, ?string $id = null, string $color = "red", bool $fill = false, ?string $fillColor = null): bool
$markers->addPolygonMarker(string $name, array $positions, World $world, ?string $id = null, string $color = "red", bool $fill = false, ?string $fillColor = null): bool
$markers->addPolylineMarker(string $name, array $positions, World $world, ?string $id = null, string $color = "red", bool $fill = false, ?string $fillColor = null): bool

Stored Markers

Open the file markers/markers.json
Go to the world your marker has to be displayed in
Add the following to the world markers:

{
  "<id>": {
    // replace <id> with the custom identifier for the marker
    "name": "string",
    // the name of the marker
    "data": {
      // ... the data fields of the marker
    }
  }
}

Marker Type Data

These are all marker data types that are implemented for the front-end using Leaflet's marker system.

Common data fields

These are commonly used fields for the data types given below

Position

{
  "x": "int|float",
  // the x coordinate in the world
  "z": "int |float"
  // the z coordinate in the world
}

Options

{
  "color": "red",
  // the border color
  "fill": false,
  // if the marker is filled
  "fillColor": "red"
  // the color of the filled area
}

Icon

{
  "type": "icon",
  // the data type
  "icon": string,
  // the name of the icon
  "pos": position
  // position of the marker
}

Circle

{
  "type": "circle",
  // the data type
  "options": {
    // ... default options
    "radius": "int|float"
    // the radius (in blocks) of the circle
  },
  "pos": position
  // postion of the marker
}

Polygon

{
  "type": "polygon",
  // the data type
  "options": options,
  // options
  "positions": []
  // list of all corner positions
}

Polyline

{
  "type": "polyline",
  // the data type
  "options": options,
  // options
  "positions": []
  // list of all positions of the line
}

hebbinkpro / pocketmap

Maintainers

Details

README

What is new in v0.5

How to install

How to use

Render a full world

Render new chunks

Render updated chunks

Change rendering speed

Issues

TO DO

Commands

WebPage

Renderer

API

Credits

Documentation

Commands

Command Arguments

Help Command

Marker Command

Common command arguments

Add Markers Command

Remove Markers Command

Reload Command

Render Command

Full Render Command

Render Lookup Command

Web Map

Textures

Rendering

From chunk to image

Markers

Marker types

Command Markers

Plugin Markers

Available functions

Stored Markers

Marker Type Data

Common data fields

Position

Options

Icon

Circle

Polygon

Polyline