W1 spike: overworld schematic generator (epic #1640)

[100yenadmin]

W1 spike — overworld schematic generator

Deterministic, seeded, CPU-only, zero LLM/CU spend overworld schematic generator for The World Layer (epic #1640, Option C step W1). Pure stdlib + numpy + PIL — no new deps. New files only, under tools/overworld/; no existing file touched.

Seed 42 (1024², generated in ~6s)

Stylized world map (hillshade + biome tint + river/road vectors + settlements):

Raw biome schematic (rivers rasterized in):

Seed 7 (a second seed, same pipeline):

Pipeline

• Heightfield — hand-rolled value-noise fBm × radial continental falloff → island + coastlines (1024² @ ~32 m/cell ≈ 32 km world).
• Hydrology — priority-flood pit fill → D8 flow accumulation → vector river polylines (meander jitter + Chaikin smoothing, log-compressed width from flow). Rivers are vectors and rasterized into the biome map.
• Biomes — documented elevation+slope+water-distance threshold table (ocean/coast/plain/forest/hills/mountain/swamp) as a frozen dataclass constant.
• Settlements — Bridson Poisson-disk candidates scored by habitability (flat + near fresh water + fertile biome) → top-8, names left as biome-feature slots.
• Roads — cost field (slope + river-crossing + swamp penalties) → A* on an MST+kNN topology → explicit bridge nodes where a road crosses a river vector.

Output contract (all under --out)

• overworld.json — seed, params, settlements[], rivers[] (polylines+widths), roads[], bridges[], region grid.
• biome_map.png + height_map.png.
• area_constraints.json — the key downstream contract: one proposed AREA per settlement and per river/road crossing, each with edge_constraints (which edge a river/road enters, at what fraction, width). A future outdoor-area generator consumes exactly this so discrete painted areas stay globally coherent.
• seed_overworld_locations.py — DRY-RUN preview mapping the schematic to the engine's Location/WorldGraphNode shape (prints JSON; touches no engine state).

Tests

7 offline pytest cases (determinism, rivers-flow-downhill, roads-connect-two-settlements, bridges-on-both-vectors, constraints-reference-real-features, settlements-on-land, engine-shape preview). Green in 0.85s:

uv run --directory servers/engine --group dev python -m pytest tools/overworld/test_overworld.py -q -p no:xdist

Honest quality notes (seed 42)

1. Biome balance skews mountainous — the continental-falloff shaping lifts interior elevations, so much of the interior classifies as hills/mountain with plain/forest reduced to scattered patches. The biome table is a documented, tunable constant — this is a tuning knob, not a structural issue (settlement selection still correctly finds the rare fertile patches).
2. A few over-straight parallel river segments appear on flat filled basins — the known D8-on-flats artifact of priority-flood's epsilon gradient. Proper flat-routing (Barnes) is out of scope for a spike.
3. Settlement distribution leans coastal/eastern — habitability rightly favours flat riverside/coastal ground, so sites cluster where the map offers it; the dry interior is sparse (realistic, but a min-spread or region-quota pass could spread them if desired).

Design references

Two-resolution terrain, vector rivers/roads, D8-flow hydrology, Poisson settlements + habitability, A* roads + auto bridges are design references (ideas only, no code) from OpenMMO's doc/TERRAIN_GENERATION.md — their licence is noncommercial and blocks code reuse, not concepts.

Closes nothing; part of epic #1640. Draft — do not merge.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 87b7f78b-7b6d-4618-86be-7076b167b39d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch w1-overworld-schematic

---

_{Comment @coderabbitai help to get the list of available commands.}