worldgen: initial public history

2 files changed, 42 insertions, 0 deletions

diff --git a/example/config/world.toml b/example/config/world.toml
new file mode 100644
index 0000000..667c224
--- /dev/null
+++ b/example/config/world.toml
@@ -0,0 +1,28 @@
+# World builder settings. Every [section] below except [planet] and [build] is optional:
+# leave a key out to keep its default (README.md → "Tuning" lists them all).
+
+[planet]
+radius_km = 6371.0              # Earth 6371. Bigger planet = more cells per continent, slower builds
+gravity_g = 1.0                 # surface gravity (Earth = 1)
+day_hours = 24.0                # length of a day (sky panel)
+year_days = 365.0               # days per year (sky panel, seasons)
+tilt_deg = 23.44                # axial tilt: seasons, tropics, polar circles
+sea_level_pressure_bar = 1.0
+scale_height_km = 8.0           # how fast air thins with height
+o2_fraction = 0.21
+
+[build]
+seed = 1                        # noise seed: same seed + same config = same world
+res_dev = 3                     # H3 resolution for quick builds (3 ≈ 2–3 min, 4 ≈ 5–10 min)
+res_final = 4                   # `--final` builds (5 ≈ 30+ min and 16–30 GB RAM)
+raster_width = 8192             # equirectangular output width at res_final
+dev_raster_width = 2048
+preview_width = 2048
+land_fraction = 0.29            # share of the surface above sea level (Earth ≈ 0.29)
+
+[climate]
+hadley_edge_deg = 30.0          # dry subtropical belt (Earth ≈ 30°)
+ferrel_edge_deg = 60.0          # wet westerlies → polar front
+
+[sketch]
+warp_km = 800.0                 # how loosely the drawing is followed (0 = exact)
diff --git a/example/masks/README.md b/example/masks/README.md
new file mode 100644
index 0000000..eea3162
--- /dev/null
+++ b/example/masks/README.md
@@ -0,0 +1,14 @@
+# Override masks (optional)
+
+Paint in GIMP/Krita as **equirectangular** grayscale PNGs, any size (2:1), 8- or 16-bit.
+Mid-gray (32768 in 16-bit, 128 in 8-bit) = neutral / no change. Transparent or missing = neutral.
+
+| File | Effect (white = +1, black = −1) |
+|---|---|
+| `land_hint.png` | bias toward land (+) or sea (−) on top of the sketch |
+| `mountain_hint.png` | extra uplift (+) |
+| `o2_zones.png` | O₂ modifier: 1 + 0.5·v (world.toml `[masks] o2_range`) |
+| `gravity_zones.png` | gravity modifier: 1 + 0.7·v; v < 0 = low-g zone (relief ×, spires) |
+| `lock.png` | where brighter than 75% grey (> +0.5), coastline follows land_hint strictly |
+
+Rebuild: `.venv/bin/python mapgen.py build` (masks are part of the cache key).