CLAUDE.md — worldgen

Procedural world generator (H3 grid, tectonics → erosion → climate → hydrology → render). Terse everywhere. Private notes (tasks, specs, area maps) are kept outside this repo; never add them here (see .gitignore).

Layout

• mapgen.py — CLI (new-world, build, check, era, compare; --res, --final, --low-memory, --from/--stop <stage>)
• mapgen/ — pipeline stages, order = STAGES in pipeline.py: grid sketch plates crust elevation erosion climate hydrology seabed environment ice fields render; mapgen/testing.py + mapgen/testdata/world.toml = test fixtures (also used by worldmap-viewer's tests: keep small_world / built_world stable)
• example/ — starter world; tests/ — unittest. worldhistory reads cells.npz.

Build / test

• Setup: python3 -m venv .venv && .venv/bin/pip install -r requirements.txt; in a git worktree link the main tree's .venv (ln -sfn <main>/.venv .venv; .venv is ignored without trailing slash: it may be a link).
• Verify: .venv/bin/python -m unittest discover -s tests -t . (270 tests, ~2 min, multi-core).

Gotchas

• System python lacks scipy/h3: always .venv/bin/python.
• numba optional (not in requirements): JIT fast paths in graph.py / noise.py / render.py; WORLDGEN_NO_JIT=1 forces numpy paths; WORLDGEN_THREADS caps workers; test_sphere_noise skips without numba.
• Outputs must stay byte-identical across --low-memory (test_low_memory) — memory work never changes results.
• Real builds at r5 / --final are big (README Troubleshooting).

Git

• Work in a git worktree on a branch (.worktrees/<topic>), not in the main tree; ff-merge when green.