# 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](https://github.com/Mindwerks/pyplatec)
- **WorldEngine** — erosion, rain shadow, Holdridge biome model
  [Mindwerks/worldengine](https://github.com/Mindwerks/worldengine)
- **Totestra** — PerfectWorld2 fork with parameterized controls
  [samboy/Totestra-mapscript](https://github.com/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