islaApocalypse/Tools/Scripts/README.md

# /Tools/Scripts — generation logic

C# backend for the offline developer tools. Decoupled from the live server and client.

## `MapGenerator.cs`

Generates the entire 2D blueprint. Roughly in order:

1. **Config** — reads `ServerConfig.json`, which sets `MapSize` (8192 by default) and the crater
   radius. The `MapSize = 4096` field initialiser is a fallback that is immediately overwritten.
2. **Topography** — FastNoiseLite base height plus a mountain spine, minus a squircle distance
   falloff, giving a guaranteed island. Noise frequency is divided by `scaleFactor`
   (`MapSize / 1024f`) so terrain features stay the same real-world size at any map profile.
   The island's proportions are the `IslandAxisX`/`IslandAxisY` dials (`1.30`/`0.78`; the
   pre-task-11 shape was `1.15`/`0.90`). **`IslandAxisX` is a weak lever** — the island is
   already Trench-clamped at ~90 % of the map width, so aspect responds almost entirely to
   `IslandAxisY`, which trades against land area. These move the coastline, so they move biomes.
   The mountain spine shares `IslandAxisX` for its width, and its crest is rounded
   (`IslandFalloff.SmoothAbs`) — `1 - |x - centre|` used to peak with a slope discontinuity that
   was, measured, the largest slope step on the map outside the Trench walls. **The spine's AXIS
   is still a straight line down the map centre; that is known, deferred, and its own task.**
   With `CoastProfile: "wide"` (the default) the *seabed* leaving the shoreline is shelved
   (`IslandFalloff.CoastShelf`): the height curve is identity at and below sea level, so it never
   reached the water, and the shoreline used to shelve gently on land then drop 6.7× steeper the
   moment it went under. The shelf cannot move the waterline — it is strictly positive for
   positive depth — so biomes and water are bit-identical with it on or off. `OffshoreIslandDensity`
   (`0.02`, `0` disables) seeds sparse discoverable islets in the open ocean; they are held off the
   mainland by a depth moat and out of the Trench by a distance mask, both by construction.
   When `TerrainCurve: "v5"` (the default — the task-09 gate's BALANCED winner), the calibrated
   height-redistribution curve
   (`HeightCurve.cs` — the terraced ascent with spatially modulated shelves: flat farmable
   lowlands, a walkable foothill bench at 100±12 m, the white mountain-town plateau at
   220±20 m — shelf heights and strength drift across the island so no two flanks wear the same
   ring — and a per-seed-normalized summit spike to the 420 m cap) reshapes above-sea terrain
   after noise/falloff/Trench and before the crater carve; biome classification reads a
   retained uncurved map, so biomes are identical either way. With `TerrainDetail: "v1"` (the
   default) two detail passes ride along with the curve (`TerrainDetailPass.cs`): shelf
   micro-relief (`ShelfReliefAmp`, ±3 m rolling skin on the benches/plateaus) and shelf-edge
   variation (`ShelfEdgeVariation`, 12 m) — a per-column shift of the shelf/riser knot block that
   makes the shelf edge scallop into notches, coves and peninsulas instead of tracing a clean
   height contour. Both touch exported heights only, and neither can reach below the red ceiling
   or above the 420 m cap: the curve's K2 and K6 knots do not move, so a warped column is
   bit-identical to an unwarped one outside the shelf/riser stack. Drops the `0_height` hillshade
   snapshot (hypsometric bands × NW hillshade) in both modes.

   **No rivers, no erosion, no flow routing anywhere in this pipeline.** A D8 drainage-incision
   pass was written and reverted in task 10 — per-cell steepest descent on a regular grid can only
   route along eight headings, and at map scale that reads as straight hatching, not drainage.
   Erosion is Phase C work: a hydraulic pass over final terrain, after the shape stops moving.
3. **Sea level and water** — sea level per the configured model (`SeaLevelModel`: `"flat"` scalar
   — the default, `SeaLevelValue` 0.15 — or the legacy `"field"` latitude Lerp); flood fill
   separates true ocean from inland lakes; a mainland fill guarantees one contiguous landmass.
4. **The crater** — placed along the northern coast and carved to below sea level, but only out to
   **80 % of its radius**, which guarantees a landbridge rather than severing the island.
5. **Water bodies** — promotes the classified water into explicit data: the ocean as body 1, each
   lake connected-component labeled (same 4-connectivity as the true-ocean fill), one transitional
   surface level per body. Classification comes from the shared `IsOceanPixel`/`IsLakePixel`
   predicates that the biome stage also uses, so the two can never disagree. A priority-flood
   pit-fill runs here as validated diagnostics (basin statistics to console; serializes nothing).
   Drops the `0_water` snapshot.
6. **Biomes and towns** — biome zoning by height and temperature; tiered town placement (Capitol,
   Hubs, Villages, Outposts, POIs) filtered by slope, water proximity and spacing.
7. **Roads** — see below. Skipped entirely when the `SkipRoads` config toggle is on (the ~25-min
   A\* pass is the bottleneck; a skip run exports a road-less iteration blueprint in ~80 s with a
   loud console banner).
8. **Export** — writes the `.dat` blueprint (dual-write: the v2 tagged container under the primary
   seed name, plus the legacy v1 format beside it as `_v1.dat` — see
   `Core/Scripts/BLUEPRINT_FORMAT.md`), then renders the PNG snapshot. The v2 file embeds the
   resolved generation params (seed, MapSize, crater radius, density, impact centre, provenance).

### The road network

`AStarGrid2D` over the whole map at one node per pixel. Mountains are made expensive rather than
impassable (`1 + elevation³ × 400`), water and the crater are marked solid.

- **Continental loop** — highway nodes sorted by radial angle and connected in a ring.
- **Mountain branch** — a spur from the loop to the snow hub.
- **County roads** — Prim's algorithm daisy-chains remaining towns onto the network. Villages become
  Rugged roads, everything else Trails.
- **Abandon protocol** — a town further than 8 % of the map from the network is skipped rather than
  pathed to, so one unreachable outpost cannot hang generation.
- **Smoothing** — every path is decimated with Ramer–Douglas–Peucker (tolerance 4.0) then smoothed
  with 4 Chaikin passes.

⚠ **This is the project's dominant performance problem.** At 8K the grid is 67 million nodes, and the
weight-setup pass touches every one before the first path is requested. The `await` yields between
stages cannot interrupt a single engine-side `GetPointPath` call, so a long path still blocks. Full
regenerations frequently get abandoned.

### The PNG snapshot

`SaveMapSnapshot()` builds an offscreen `SubViewport` in code rather than relying on the scene's
layout, because Godot's UI layout engine will otherwise crush a 4096+ render down to the editor
window size. A `MapDrawProxy` control re-issues the `_Draw()` calls into that viewport — `GetImage()`
captures only the base texture and would otherwise miss the roads and towns entirely — and the code
awaits two `RenderingServer.FramePostDraw` signals so the GPU has actually painted before the image
is read back.

Road colours on the snapshot, useful for identifying a road: **red** = Highway, **black** = Branch,
**dark brown** = Rugged, **light brown** = Trail.

### Outputs
`MapData_Seed_<seed>.dat` (v2), `MapData_Seed_<seed>_v1.dat` (legacy dual-write), and the staged
snapshots `Map_Seed_<seed>_{0_height,0_water,1_biomes,2_towns,3_roads}.png`, all to `user://`.
(`0_height` is the hypsometric hillshade of the curved terrain; `0_water` is painted from the
water stage's own outputs — ocean deep blue, lakes lighter blue, land neutral; `3_roads` is
absent on a SkipRoads run.)

## `RoundTripHarness.cs`

The blueprint format regression test (scene: `Tools/Scenes/RoundTripHarness.tscn`). Loads a
known-good blueprint through the real parser, re-writes it as v2 through the real writer, re-loads
it, and asserts semantic equality (heights bitwise, biomes, towns, every road point). Headless,
seconds per cycle, no generation. Exit code 0 = pass.

## Rules
1. **No magic numbers.** Distances, radii and thresholds derive from `MapSize` or `scaleFactor`, so
   the generator behaves identically at 4K and 10K.
2. **Respect the GPU.** Anything exporting visual data must `await` the appropriate frame signals
   before reading pixels back.