BlueMap Guide: a 3D Web Map for Your Minecraft Server

What BlueMap is

BlueMap reads your world files, renders them into 3D map tiles and serves them through a small built-in web server. Zoomed in, you see blocks in full 3D; zoomed out, a flat overview. Live markers show where players are, and the map updates as the world changes.

It renders Java Edition worlds only. The current release, BlueMap 5.29, comes in versions for:

For an older Minecraft version, download an older BlueMap release that lists it. Each release on Modrinth and Hangar shows the versions it supports.

Install BlueMap

1. Download the file that matches your server from Modrinth, Hangar or the BlueMap GitHub releases: the -paper jar for Paper, -fabric for Fabric, and so on.
2. Put it in the plugins folder (Paper, Spigot) or the mods folder (Fabric, Forge, NeoForge) and restart the server. Uploading plugins is covered in how to install Minecraft plugins.
3. BlueMap creates its configuration in plugins/BlueMap/, or config/bluemap/ on modded servers, with a map for each of your worlds already set up.

At this point the console tells you BlueMap is waiting. It will not render anything until you accept the download, which is the next step.

Accept the download in core.conf

To draw blocks, BlueMap needs the textures and models from the Minecraft client, which it downloads from Mojang. Open core.conf and change:

accept-download: true

By setting it you accept Mojang's EULA and confirm you own Minecraft Java Edition. Save the file and run /bluemap reload, or restart. BlueMap downloads the resources and starts rendering.

Give the web map its own port

BlueMap's web server listens on port 8100 by default. On your own machine, open that port and visit http://your-ip:8100. On hosted servers you usually cannot pick a port freely, so you use one that is assigned to your server:

1. Get a second port for your server. On HytHost, open the Network tab in the panel and add an allocation: the panel picks a free port and opens it for you.
2. Open webserver.conf and set port to that number:

   port: 25570

3. Run /bluemap reload and open http://your-server-ip:25570 in a browser.

Do not use the game port; that is Minecraft's. To show the map on your own domain without a port number, put a reverse proxy such as nginx in front of it; BlueMap's documentation has ready examples.

BlueMap commands

Each command has a permission of the form bluemap.<command>, for example bluemap.reload. Most of the time you need none of them: BlueMap notices changes in the world and renders them on its own.

Keep rendering light

BlueMap renders in background threads, not on the server's main thread, but rendering still uses CPU. The first render of a big world is the heavy part; after that, only changed chunks are redrawn.

• Render threads: set render-thread-count in core.conf. BlueMap's documentation suggests 1 on machines with four cores or fewer.
• Render when it is quiet: run /bluemap stop during busy hours and /bluemap start at night while the first render runs.
• Pause with players online: player-render-limit in plugin.conf stops rendering once that many players are on.
• Set a world border. It keeps the map, and the rendering work, from growing forever as players explore.
• Freeze maps you do not need live, such as the End once it is explored.

Storage: files or a database

By default BlueMap stores the map as compressed files in bluemap/web/maps, inside your server's storage. The map grows with the explored area, so keep an eye on disk space on a large world.

You can move a map to a database instead. In storages/sql.conf, set the connection to MySQL, MariaDB, PostgreSQL or SQLite, then set storage: "sql" in the map's config file and reload:

connection-url: "jdbc:mysql://DB_HOST:3306/DB_NAME"
connection-properties: {
    user: "DB_USER",
    password: "DB_PASSWORD"
}

Paper ships a MySQL driver; Spigot, Fabric and Forge need a JDBC driver added. Every HytHost Minecraft plan includes MySQL databases, which you create in the panel's Databases tab.