Data Sources

Data Sources

TerraForge ships no geodata. This repository contains code only — .gitignore excludes every raster and vector format so datasets cannot be committed by accident. The server operator downloads the data and is responsible for complying with its licence, including attribution.

What TerraForge needs

Provider	Dataset kind	Recommended source	Required?
Elevation	DEM raster	Copernicus DEM GLO-30	yes — without it there is no terrain
Water	coastline + water polygons	Natural Earth ocean/lakes, HydroLAKES	strongly recommended
Land cover	land cover raster	ESA WorldCover	recommended — otherwise biomes fall back to a climate estimate
Boundaries	admin boundaries	Natural Earth Admin 0/1	optional — needed for /earth whereami
Gazetteer	populated places	GeoNames cities15000	optional — needed for /earth city

Only the DEM is mandatory. Everything else degrades gracefully: no boundaries means "unknown country", not a crash.

Choosing a resolution

Match the source resolution to the world scale — finer data than one block can show is wasted disk.

blocks-per-km	Ground per block	Useful DEM resolution
0.5	2 km	90 m (GLO-90)
1.0	1 km	90 m or 30 m
2.0	500 m	30 m
5.0	200 m	30 m

Licences and attribution

Elevation (DEM)

Dataset	Resolution	Coverage	Licence	Notes
Copernicus DEM GLO-30	30 m	global, 85°N–85°S	free, attribution to ESA/Copernicus	recommended default
Copernicus DEM GLO-90	90 m	global	same	smaller download, fine at 1 block/km
NASA SRTM 1 Arc-Second (SRTMGL1 v3)	30 m	60°N–56°S	public domain, attribution to NASA/USGS	no high latitudes
ASTER GDEM v3	30 m	83°N–83°S	free with attribution to METI/NASA	noisier than Copernicus
GEBCO 2024	~450 m	global, bathymetry	free with attribution to GEBCO	use for ocean depth

Land DEMs stop at the shoreline. For realistic ocean floors, merge a land DEM with GEBCO during preparation, or accept the configured water.default-ocean-depth fallback.

Required attribution examples:

• Copernicus: "Produced using Copernicus WorldDEM-30 © DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA; all rights reserved."
• GEBCO: "GEBCO Compilation Group (2024) GEBCO 2024 Grid."

Country and region boundaries

Dataset	Detail	Licence
Natural Earth Admin 0/1	1:10m, 1:50m, 1:110m	public domain
geoBoundaries	high	CC BY 4.0
GADM	very high	free for non-commercial use only — check before using on a public server

Natural Earth 1:10m is the recommended default: public domain, small, and detailed enough for country and first-level region detection.

Populated places (gazetteer)

Dataset	Licence
GeoNames cities500 / cities15000	CC BY 4.0
Natural Earth Populated Places	public domain

Cities are stored as a name plus a coordinate. They are used for teleporting, "nearest city" and map labels. Nothing is built in the world.

Land cover (biomes)

Dataset	Resolution	Licence
ESA WorldCover 2021 v200	10 m	CC BY 4.0
Copernicus Global Land Cover	100 m	free with attribution
MODIS Land Cover (MCD12Q1)	500 m	public domain (NASA)

Built-up and cropland classes are deliberately mapped to the natural vegetation of the surrounding climate — TerraForge renders no settlements or fields.

Water

Dataset	Contents	Licence
Natural Earth lakes / ocean	coastlines, large lakes	public domain
HydroLAKES	detailed lake polygons	CC BY 4.0
HydroRIVERS	natural river network	CC BY 4.0
OpenStreetMap natural=water, waterway=river/stream	detailed natural water	ODbL 1.0

OpenStreetMap usage policy

If OSM data is used at all, it may supply only natural features:

• allowed: natural=water, natural=coastline, waterway=river|stream|riverbank, administrative boundaries, place names
• forbidden: highway=*, building=*, railway=*, bridge=*, aeroway=*, power=*, landuse=industrial|residential|commercial, and every other man-made feature

The importer enforces this by whitelist: unlisted tags are dropped at preparation time, so man-made geometry never reaches the database, let alone the world. ODbL is share-alike — read it before redistributing derived data.

The natural-features-only rule

The importer works from a whitelist, enforced in code, not by convention:

• accepted: coastlines, ocean, lakes, natural watercourses, administrative boundaries, place names, land cover
• rejected: highway, building, railway, bridge, aeroway, power, industrial and residential land use, and anything else man-made

Land cover to biome

Land cover is the primary biome signal; elevation, latitude and water state refine it.

gdal_translate -of AAIGrid WorldCover.tif worldcover.asc
java -jar terraforge-cli.jar prepare-landcover -i worldcover.asc \
  -o plugins/TerraForge/data/landcover/region.tflc

Real-world class	ClimateBiome	Minecraft
desert / bare	DESERT	Desert
tundra	TUNDRA	Snowy Plains
needleleaf forest	BOREAL_FOREST	Taiga
broadleaf forest	TEMPERATE_FOREST	Forest
tropical forest	TROPICAL_RAINFOREST	Jungle
savanna	SAVANNA	Savanna
grassland / cropland	GRASSLAND	Plains
wetland	WETLAND	Swamp
permanent snow	GLACIER	Ice Spikes / Snowy Slopes
water	ocean / lake / river variants	Ocean, Lake, River

Place names

prepare-cities stores the primary name, the ASCII form and up to twelve GeoNames alternate names, so /earth city Munich, /earth city Muenchen and /earth city München all find the same place, with tab completion matching any of them.

Checking a prepared database

java -jar terraforge-cli.jar validate -d server/plugins/TerraForge/terraforge.db

Checks overlapping country polygons, duplicate ISO codes and names, regions outside their country, countries with no capital or with several, and cities assigned to a country they do not lie in. Errors exit with code 65; --strict makes warnings fail too, so the command works as a CI gate. Nothing is ever repaired — the fix belongs in the source dataset.

Storage estimates

Region	DEM (30 m, int16)	Database
central-europe test region	~2.2 GB	~50 MB
Europe	~20 GB	~200 MB
whole Earth	~1.5 TB	~2 GB

Use GLO-90 to cut DEM size roughly nine-fold when the scale does not justify 30 m.

---

Next: DEM Pipeline · Configuration