BiomeMap

Generates a lightweight JSON file mapping each world region to its dominant biome. Ideal for creating stylized biome maps on external web apps.

📋 Overview

BiomeMap exports the dominant biome of a rectangular selection. You choose a world and 2 corners (x/z), and the plugin builds a grid of cells over that area.
Then it samples biomes and writes:

• a JSON file
• optionally a PNG preview (1 pixel = 1 cell)

✨ Features

• Rectangular selection defined by two coordinates (/biomemap world x1 z1 x2 z2 [cellSize] [preview])
• Cell size with chunk-friendly alignment (8, 16, 32, ...)
• Chunk-based sampling to smooth biome transitions
• Asynchronous processing with frequent progress updates (no server freeze)
• One export at a time (global lock)
• Stop command to cancel running exports cleanly
• Structured JSON output with min/max bounds per cell and namespaced biome IDs
• Optional PNG preview output (1 pixel = 1 cell) using a biome RGB palette

🚀 Installation

1. Install PaperMC server with Java 21+
2. Download the latest biomemap-x.x.x+mcx.x.x.jar from the releases page
3. Drop the jar into your server’s plugins/ folder
4. Restart the server or run /reload confirm

🕹 Command Usage

Only one export can run at a time.

Commands

Command	Description
/biomemap <world> <x1> <z1> <x2> <z2> [cellSize] [preview]	Starts a biome export (JSON + optional PNG).
/biomemap status [map]	Shows current progress, ETA, outputs. Add map for compact ASCII completion map.
/biomemap stop	Stops the current export and removes files from that run in exports/.

Arguments

Argument	Required	Description
<world>	Yes	World name, for example world or world_nether.
<x1> <z1>	Yes	First corner of the area.
<x2> <z2>	Yes	Opposite corner of the area.
[cellSize]	No	Cell size in blocks. Default 16 (common values: 8, 16, 32, 64, ...).
[preview]	No	Add preview to generate a PNG (1 pixel = 1 cell).

cellSize resolutions

📁 Output files

All files are written to plugins/BiomeMap/exports/.

File	Pattern	Created when
JSON	<world>_<cellSize>_<index>.json	Always
PNG	<world>_<cellSize>_<index>.png	Only if preview is used

Rules:

• index starts at 1 and increases if the filename already exists.
• If you run /biomemap stop, files from the canceled export are removed.

⚙️ Configuration

config.yml exposes performance throttles.

Key	Default	Description
performance.chunks-per-tick	1	How many new chunk jobs are started each tick. Lower = safer, slower.
performance.max-in-flight	4	Max number of BiomeMap jobs currently in pipeline (queued/running).
performance.max-concurrent-chunks	64	Max real chunk loads at the same time (main server pressure knob).

Quick tuning guide:

• If players feel lag, lower max-concurrent-chunks first.
• If export feels too slow but server is stable, increase chunks-per-tick a bit.
• Keep max-in-flight >= chunks-per-tick.

🗺 JSON Format

{
  "cellSize": 16,
  "selectionMin": { "x": -200, "z": -200 },
  "selectionMax": { "x": -50, "z": -20 },
  "gridOrigin": { "x": -208, "z": -208 },
  "width": 10,
  "height": 12,
  "cells": [
    {
      "i": 0,
      "j": 0,
      "bounds": {
        "min": { "x": -208, "z": -208 },
        "max": { "x": -193, "z": -193 }
      },
      "biome": "minecraft:plains"
    },
    {
      "i": 1,
      "j": 0,
      "bounds": {
        "min": { "x": -192, "z": -208 },
        "max": { "x": -177, "z": -193 }
      },
      "biome": "minecraft:forest"
    }
  ]
}

Field	Type	Description
cellSize	number	Cell size in blocks (minimum 8; values above that are aligned to the chunk grid).
selectionMin/Max	object	Raw coordinates provided in the command.
gridOrigin	object	North-west corner of the grid (min X, min Z).
width, height	number	Number of cells on the X and Z axes.
cells[].bounds.min/max	object	Inclusive bounds delimiting the cell.
cells[].biome	string	Namespaced biome ID (e.g. minecraft:savanna).

---

Crafted by Sukikui