// documentation

Documentation

How Meld turns a map selection into one seamless Minecraft world. Start here, then pick a guide that explains how each piece works.

What Meld is

Meld is a slim orchestrator around a custom Arnis fork. Arnis converts one OpenStreetMap bounding box into one Minecraft world. Meld adds the thing Arnis cannot do on its own: areas bigger than a single run. It tiles the area into a grid, builds the tiles with many Arnis runs at once, and melds them into one world with the same terrain height and building style everywhere.

It is one Flask process, one single page map UI, and a thin worker pool. A few hundred lines, not a framework.

How a build flows, end to end

You draw an area on the map. Meld does the rest in a few clear steps:

  1. It picks an origin, one fixed anchor that every block coordinate is measured from.
  2. It runs a quick elevation survey and locks one height range, so the land lines up everywhere.
  3. It splits the area into cells that fall on region file boundaries, so seams land in clean spots.
  4. It downloads the area's map data once and shares it to every cell, so nothing gets rate limited.
  5. It builds many cells in parallel with the Arnis fork, all using the same origin, seed, and height lock.
  6. It merges each finished cell into one master world, keeping only the part each cell owns.
  7. A drift guard refuses any cell that does not line up, so a built world is never corrupted.

The result is one Minecraft world with no cliffs and no seams. The guides below explain each piece.

The guides

Each page explains the why, the mechanism, and how to use it in the app.

// the core idea

How it works

The full pipeline: origin, the elevation lock, region aligned cells, map prefetch, parallel generation, the region perfect merge, and the drift guard. The mental model behind everything else.
// terrain

Elevation

The whole elevation system: the global height lock, region data packs you download once, selectable detail with Auto, the no-data hole repair, and the height preview that shows you what is cached.
// going big

Parallel generation

Cells and the worker pool, the CPU budget and staggered starts, stream to disk for huge cells, auto retry, spiral build order, and why small cells can finish faster.
// the generator

The Arnis fork

What the custom Arnis fork changes and the knobs you get: no buildings, road detail modes, automatic flat bridges, seam free rendering, offline elevation, a custom Overpass URL, and how to run map data offline or self-hosted.

Looking for what changed between releases? That lives in the changelog.

Quickstart

  1. Clone the repo and install the Python deps: 
    git clone https://github.com/Teddy563/meld
cd meld
pip install -r requirements.txt
    Pillow is only needed for the automatic elevation survey. You can set the range manually without it.
  2. Get the Arnis generator. Two options:
    • Use the arnis.exe bundled with the release or clone, or
    • Download the latest from the Teddy563/arnis releases and drop arnis.exe next to server.py.
    Meld auto finds the binary at ./arnis.exe, ../arnis.exe, or ../arnis-source/target/release/arnis(.exe).
  3. Run the server: 
    python server.py        (open http://127.0.0.1:5630)
  4. Draw a rectangle on the map, or search a place. Meld auto centers the origin, tiles the selection into cells, and runs an elevation survey.
  5. Pick a cell size (regions per cell), then Generate and merge. Open the world in Minecraft from the save location shown in the panel.