BlueMap Documentation

BlueMap is a tool that reads Minecraft world files to generate 3D models of the world surface. These models can be viewed in a web browser, providing an in-game-like experience or a high-level overview of the world.

BlueMap is available in several formats:

• Plugin: Spigot/Paper or Sponge.
• Mod: Fabric or Forge.
• Standalone: A command-line tool that can be used without a Minecraft server.

When used as a Plugin or Mod, BlueMap renders asynchronously to the Minecraft server thread, meaning it should not slow down the server as long as the CPU is not fully utilized.

To get started with BlueMap, download the appropriate version from the official releases page.

For detailed setup steps, refer to the official installation instructions.

The BlueMap webapp is built using Vue 3 and Vite. To set up the development environment, follow these steps:

1. Install dependencies: Run npm install to install the necessary packages.
2. Run development server: Use npm run dev to start the project with hot-reload enabled.
3. Build for production: Use npm run build to compile and minify the project for production deployment.
4. Lint code: Use npm run lint to run ESLint and check for code quality issues.

For the best development experience with Vue 3 and TypeScript, use VSCode with the following extensions installed:

• Volar: The official Vue language service.
• TypeScript Vue Plugin (Volar): To enable TypeScript support within Vue files.
• Note: Ensure that the Vetur extension is disabled to avoid conflicts with Volar.

To build BlueMap, run the Gradle wrapper release command from the root directory. The compiled JAR files will be located in the ./build/release directory.

./gradlew release

To clone the BlueMap repository including all submodules, use the following command:

git clone --recursive https://github.com/BlueMap-Minecraft/BlueMap.git

After running an update command, you can monitor the progress of the scheduled render tasks by using the base command.

Command: /bluemap

When running the CLI, you can specify custom paths for configuration, mods, and Minecraft versions to ensure correct resource loading and environment setup.

• --config <path>: Specifies the directory where BlueMap looks for .conf files. If the directory is empty, BlueMap generates default configs there.
• --mods <path>: Specifies the directory containing Minecraft mods. This is useful if your rendering requires extra resources provided by mods.
• --mc-version <version>: Explicitly sets the Minecraft version to ensure the correct resource packs are loaded for rendering.

Use the -r flag to trigger map rendering. You can refine the rendering behavior with the following options:

• -f, --force-render: Forces a full render of all chunks, ignoring whether they have changed.
• -e, --fix-edges: Forces rendering of map edges instead of just modified chunks.
• -u, --watch: Enables a watcher service that monitors world files and automatically triggers updates when changes are detected.
• -m, --maps <id1,id2>: Limits rendering to specific map IDs (e.g., -m world,nether).

You can programmatically control several aspects of the application state via BlueMapApp methods:

• setTheme(theme): Sets the visual theme. Supported values are 'light', 'dark', and 'contrast'.
• setDebug(debug): Enables or disables debug mode. When true, it shows the performance stats panel.
• setChunkBorders(chunkBorders): Toggles the visibility of chunk borders in the renderer.
• setScreenshotClipboard(clipboard): Determines if screenshots should be automatically copied to the system clipboard.
• resetSettings(): Resets all user settings and reloads the page.