Substrata

Makes your flat Minecraft world deeper. Your builds stay exactly where they are. You get hundreds of blocks of ground, stone and ores below to dig. Works with worlds from 1.12 to 26.2 (version is detected automatically) on every loader: Vanilla, Fabric, Forge, NeoForge.

Download

• Releases -> Substrata.exe. One file, run it, done. No install, no Python needed.
• Or grab substrata.py from this repo and run py substrata.py. Same program, same GUI, needs Python 3 from python.org.

What it does

You have a flat creative world with lots of builds and only 3-4 blocks of ground under your feet. Substrata adds real depth under it without touching a single build, chest, item frame, villager or dropped item.

Two modes:

Raise the world (recommended)

The whole world (builds, chests with their items, animals, villagers with their bed/job memory, villages, spawn point, player positions) moves up by e.g. 240 blocks, and the space below is filled with layers you choose (dirt / stone / deepslate / anything).

• 100% vanilla result. No mods, no datapacks, nothing to keep installed. The world stays normal forever.
• The only thing that changes is the Y number on F3 (you stand at 180 instead of -60).
• Works on every version from 1.12 up and every loader, because it only edits world files.
• New chunks generate with the same added layers, so there are no seams and no cliffs.

Deepen downward

The world bottom moves lower (e.g. from -64 to -304). Everything stays at its current Y. A small datapack is placed inside the world automatically and it works on Vanilla, Fabric, Forge and NeoForge. Minecraft 1.18 to 1.21.8 only, because negative Y and datapack-driven world height do not exist before 1.18 and the format changed after 1.21.8.

Features

• Layer editor: stack any layers you want, any thickness, with a live sum check
• Every block in the game (1105 of them) with autocomplete while you type
• Random ore veins: pick a block (e.g. diamond ore), a Y range and a density in % and it gets scattered through your layers, same seed = same world every time
• Safety checks: the tool refuses to place blocks that would break themselves: flowers demand dirt directly below, nether wart demands soul sand, sugar cane / cactus / tall plants are blocked entirely, doors and torches demand a solid block below
• Full automatic backup of the world before any change
• English and Polish interface, dark and light theme

How to use

1. Close Minecraft / stop the server. The world must not be open.

2. Run Substrata.exe.

3. Pick your world folder, the one that contains level.dat:

   • server: the world subfolder next to server.jar
   • singleplayer: %APPDATA%\.minecraft\saves\YourWorld
   • CurseForge/Modrinth/Prism: ...\Instances\<pack>\saves\YourWorld

   The tool checks the folder and shows the detected version. If you pick a wrong folder it tells you where to go.

4. Choose a mode, adjust layers (or keep the defaults), optionally add ore veins.

5. Click Preview. It prints the full plan and changes nothing.

6. Click RUN. It makes the backup first, then does the conversion. A 2000-chunk world takes about a minute.

7. Start the game. Done.

If something looks wrong afterwards: your untouched world copy is in the substrata_backups folder next to the program and copy it back and you are where you started.

Why flat worlds only?

The chunk editing itself works on any world. The problem is new chunks.

Minecraft only generates terrain where someone has been. A flat world's generator is a simple layer list and Substrata just extends that list, so chunks generated later match the converted ones perfectly.

A normal world's generator is a noise function with heights baked in (sea level 63, bedrock floor -64). It cannot be told "generate everything 240 higher". So on a normal world:

• after raising, newly generated chunks would appear at the old height, so you get a 240-block cliff wall around everything you have explored
• after deepening, newly generated chunks would have void below -64, so you get holes in the ground

The tool does not hard-refuse non-flat worlds. It converts the existing chunks and warns you. If your world is fully explored and fenced off, it will work. But for any world where new terrain can still generate, expect the seams described above. That is a Minecraft world-generation limitation, not something a file tool can patch around.

Command line

Everything also works headless:

Substrata.exe "C:\path\to\world" --raise 240
Substrata.exe "C:\path\to\world" --raise 128 --below "bedrock:1,stone:100,dirt:27"
Substrata.exe "C:\path\to\world" --raise 240 --scatter diamond_ore:-40:0:3 --scatter iron_ore:0:60:5
Substrata.exe "C:\path\to\world" --datapack            (deepen mode, 1.18-1.21.8)
Substrata.exe --help

A log of every run is written to substrata_log.txt inside the world folder.

Build the exe yourself

pip install pyinstaller
pyinstaller --onefile --noconsole --name Substrata substrata.py

Tested

Every release is tested end-to-end on real dedicated servers: worlds are generated, filled with builds, chests, villagers, items and signs, converted, then verified in-game block by block on versions from 1.12 to 26.2, with zero errors in the server log as the pass condition.