settled-reach/docs/design/planetary-terrain-generation.md

Planetary Terrain Generation — Design Reference

Status: Research complete, spike proposed Date: 2026-03-25 Source: Tyre feasibility assessment + PO direction

Approach

Tile-first generation using tectonic simulation. The pipeline outputs a tile grid with terrain type per cell, not a heightmap that needs post-processing. The heightmap is an intermediate artifact inside the simulation; the deliverable is classified terrain tiles at the resolution the game consumes.

This follows the PerfectWorld (Civ 4) philosophy: each cell IS a game tile with a terrain type, produced by geological process rather than noise functions.

Pipeline Architecture

Input:  PlanetProfile (from wiki/LocationProfile)
        → planet_type, tectonic_activity, atmosphere, age, gravity, water_coverage

Stage 1: Base terrain (tectonic simulation)
        → IF tectonic_activity > 0: run PlaTec simulation
           Parameters: plate_count (3-30), simulation_steps (50-500),
                      sea_level, folding_ratio, erosion_period
        → IF dead/cratered: Poisson-disk crater field + fractal base
        → IF volcanic: hotspot placement + shield volcano profiles

Stage 2: Erosion passes (parameterized by planet type)
        → Hydraulic erosion (rain worlds, Earth-like)
        → Thermal erosion (all rocky bodies)
        → Glacial erosion (cold worlds, optional)
        → Aeolian erosion (thin atmosphere + wind, optional)
        → Passes = f(planet_age, atmosphere_density)

Stage 3: Climate / biome (habitable worlds only)
        → Geostrophic wind model (latitude bands + Coriolis)
        → Moisture transport from bodies of water
        → Temperature from latitude + altitude + stellar distance
        → Biome classification (Holdridge or simplified Koppen)

Stage 4: Hydrology (worlds with liquid water)
        → Flow accumulation from elevation grid
        → River network extraction
        → Lake filling at local minima
        → Coastline extraction from sea_level threshold

Stage 5: Tile classification
        → Each cell gets a terrain type: ocean, coast, shelf, plains, hills,
          mountains, desert, tundra, forest, jungle, ice, volcanic, crater, etc.
        → This IS the output — a tile grid the game reads directly

Stage 6: Export
        → tiles.json or tiles.bin (terrain type per cell, game-consumable)
        → heightmap.png (16-bit grayscale, for world map viewer)
        → rivers.png (binary overlay)
        → coastlines.png (binary overlay)
        → biome_zones.json (polygon regions + biome type)
        → settlements.json (candidate settlement points)

Planet Type Profiles

Tectonic worlds (atmosphere, liquid water possible)

Planet Type	Plates	Activity	Erosion Mix	Result
Earth-like	8-15	High	Hydraulic + thermal	Continents, mountain chains, river basins
Young volcanic	3-6	Very high, short sim	Minimal erosion	Sharp rifts, volcanic plains, calderas
Ice world	5-10	Moderate	Glacial dominant	U-valleys, fjords, ice caps, tundra
Desert/wind	5-10	Low	Aeolian dominant	Eroded plateaus, sand seas, mesas
Ocean world	5-10	High	Hydraulic + volcanic	Archipelagos, mid-ocean ridges, island chains
Tidally locked	5-10	Moderate	Hydraulic on day side	Twilight habitable band, ice cap dark side, scorched light side

Non-tectonic bodies (no/thin atmosphere, no liquid surface water)

Body Type	Generation Method	Tile Types	Examples
Cratered lunar	Poisson-disk impact craters + fractal base elevation, crater size distribution follows power law, regolith plains between craters	crater_floor, crater_rim, crater_wall, regolith_plain, highland, basin	Luna, Callisto, Ganymede, most moons
Volcanic dead	Lava flow simulation from vent points, shield volcano height profiles, collapsed caldera basins, mare (flood basalt plains)	mare_plain, shield_slope, caldera_floor, caldera_rim, lava_channel, highland	Mercury-analog, dead volcanic moons
Active volcanic	Tidal heating driven, continuous resurfacing, minimal cratering, sulfur/silicate deposits	lava_field, active_vent, sulfur_deposit, cooling_crust, plume_deposit	Io-analog
Aeolian sculpted	Prevailing wind direction + erosion passes on fractal base, dune field formation, yardang carving, ventifact plains	dune_field, yardang_ridge, ventifact_plain, dust_basin, mesa, canyon	Mars-analog, thin-atmosphere worlds
Ice shell	Fractal base with crack propagation (tidal stress), cryovolcanic vent placement, tiger stripe lineae, smooth refrozen plains	ice_plain, crack_ridge, cryovent, refrozen_smooth, chaotic_terrain, crater (sparse)	Europa, Enceladus-analog
Barren rock	Minimal processing — fractal base + sparse cratering + thermal erosion only, no atmosphere effects	rock_plain, ridge, crater, scarp, dust_plain	Airless small bodies, dead worlds

Gas giants and belts (no surface tiles)

Gas giants and asteroid belts do not generate terrain tiles. They exist as orbital entries in the atlas with atmospheric/compositional metadata only.

Key Libraries

• pyplatec — Python bindings for PlaTec C++ tectonic simulator Mindwerks/pyplatec
• WorldEngine — erosion, rain shadow, Holdridge biome model Mindwerks/worldengine
• Totestra — PerfectWorld2 fork with parameterized controls samboy/Totestra-mapscript

Performance

• PlaTec at 1024x512: ~2-10 seconds per planet
• Erosion passes: ~5-30 seconds
• Climate + hydrology: <2 seconds
• Total per planet: ~10-45 seconds
• 1000 planets: 3-12 hours (offline batch)

Proposed Spike

Stand up pyplatec, generate 5 tile grids with different planet profiles (Earth-like, volcanic, dead, ice, desert), render as preview images, evaluate geological variety. Half a day.

References

• PerfectWorld 1+2 (CivFanatics, Python) — midpoint displacement + plate boundary elevation
• PerfectWorld 3 (Civ5, Lua) — layered Perlin, dropped tectonics, kept climate
• PlaTec thesis: Lauri Viitanen "Physically Based Terrain Generation" (2012)
• SimpleTectonics: clustered convection approach (weigert/SimpleTectonics)
• World Orogen (orogen.studio) — browser-based, strong algorithm design
• Nixis (MightyBOBcnc/nixis) — spherical planet generation