Home

Real Earth terrain generation for Paper — natural geography in, player-built history out.

REAL EARTH DATA → TerraForge CLI → natural Minecraft terrain → players build → Towny governs → BlueMap displays

0.1.x preview software. Test on a new world and keep backups. Changes to projection, scale or terrain settings between versions can create permanent seams between old and new chunks — read the changelog before upgrading.

Welcome to the TerraForge wiki — the player- and operator-facing documentation for the plugin. If you are looking for API references and contribution rules instead, see the developer docs in the repository.

Start here

New to TerraForge? Follow these in order:

1. Installation — get the plugin and CLI running, prepare a test region, create the world.
2. Data Sources — which datasets to download and how they map onto the world.
3. Configuration — every terraforge.yml option explained.
4. Commands — the full /earth command reference.

Guides

Page	What it covers
Installation	Requirements, first start, data preparation, world creation
Configuration	Every terraforge.yml key, defaults and meaning
Data Sources	Choosing DEM, land-cover, boundary and gazetteer datasets
DEM Pipeline	Preparing elevation data and the .tfdem format
Projections and Scale	Projections, world size, origin, vertical scale
Commands	Full /earth command and permission reference
Towny Integration	Real-world geography on Towny towns
BlueMap Integration	City, country and region markers on the web map
Pregeneration	Generating chunks ahead of players safely
Performance	Budgets, caching, benchmarks and profiling
Troubleshooting	Fixes for the most common problems
FAQ	Short answers to the questions that come up most

What TerraForge is (and isn't)

TerraForge turns prepared real-world elevation, coastlines, water and land-cover data into deterministic Minecraft terrain.

✅ Generated from real data	❌ Never generated
Continents, coastlines and islands	Roads, highways and streets
Ocean depth, lakes and natural rivers	Buildings, villages and structures
Mountains, valleys, plains and deserts	Railways, bridges and airports
Biomes from real land cover	Power lines or industrial areas

generation.natural-only: true is the default and cannot be turned off. There is no code path in TerraForge that places a man-made structure.

Getting help

• Read Troubleshooting and the FAQ first.
• Ask a question in Discussions.
• Found a reproducible bug? Open an issue.
• Security vulnerability? Use the private process in SECURITY.md — never a public issue.