# /Tools

Offline developer utilities. **Nothing here ships.** These generate the source data that `/Server`
and `/Client` later consume, which keeps world-generation logic out of the shipped client.

## The 2D world generator

**Script:** `Tools/Scripts/MapGenerator.cs` · **Scenes:** `Tools/Scenes/MapPreview.tscn` and
`Scenes/MapCaptureTool.tscn`

Builds the topographical and logistical foundation of the island before any 3D exists.

- **Resolution is config-driven**, from `ServerConfig.json`'s `MapProfile`: `4K`/`6K`/`8K`/`10K` →
  4096 / 6144 / 8192 / 10240. **Shipped default is 8K.** 1 pixel = 1 in-game metre = 1 voxel
  footprint. (The `MapSize` field initialiser in the script says 4096, but it is overwritten from
  config before use.)
- **Topography:** FastNoiseLite plus distance-falloff maths for a guaranteed mainland island, a
  mountain spine, dynamic temperature-driven sea level, and an impact crater pushed into the northern
  coast (carved at 80 % of its radius so a landbridge always survives).
- **Logistics:** `AStarGrid2D` pathfinding producing a looping continental highway, a branch to the
  mountain hub, and county roads daisy-chained outward with Prim's algorithm. Paths are decimated
  (Ramer–Douglas–Peucker) then smoothed (4 Chaikin passes).
- **Zoning:** biome mapping and tiered town/POI placement by slope, temperature and proximity.

### ⚠️ A\* is the known bottleneck

The grid is one node per pixel — **67 million nodes at 8K** — and the weight-setup pass walks every
one of them. A full generation can stall long enough that runs get abandoned. `await` yields are
sprinkled through the road stage, but they cannot interrupt a single engine-side `GetPointPath` call,
so they only help between paths. Expect a regeneration to take minutes, or to need abandoning.

### Outputs — written to `user://`, not into the project

| File | What it is |
|---|---|
| `MapData_Seed_<seed>.dat` | The binary blueprint the server reads (~512 MB at 8K) |
| `Map_Seed_<seed>.png` | Visual snapshot of the map, for reviewing and picking seeds |

On Linux: `~/.local/share/godot/app_userdata/islaApocolypse/`.

### Running it

Open `Tools/Scenes/MapPreview.tscn` and press **F6**. It is also the project's main scene, so
**pressing F5 anywhere runs this** — which is why F5 regenerates your world instead of starting the
game. Use `Scenes/MapCaptureTool.tscn` when you specifically want the full-resolution PNG.

## Rules
1. **No client dependencies.** Nothing here may reference UI, player controllers or shaders in
   `/Client`.
2. **Data out, nothing in.** Tools emit `.dat`/`.png`/`.json`; they never write to a live server save.
3. **No magic numbers.** Distances and radii scale off `MapSize` or the derived `scaleFactor`, so the
   generator behaves the same at every profile.