# IslaApocalypse

**Version:** v0.0.1 — prototyping / salvage. Not a playable build.
**Engine:** Godot **4.7.1** · C# / .NET 8 (`Godot.NET.Sdk 4.7.1`)

A procedurally generated, multiplayer-ready voxel survival game on a post-nuclear Caribbean island.
Terrain is smooth (Marching Cubes), not blocky.

> **Design intent, decisions and rationale live in the design vault, not here.** This README and the
> per-directory ones describe **what the code does**. For *why*, see the vault repo
> (`islaApocalypse-vault-v0.1`).

---

## How the world gets built

Two phases, with a file in between.

1. **2D blueprint** (`Tools/Scripts/MapGenerator.cs`) — FastNoiseLite topography, dynamic sea level,
   an impact crater, biome zoning, tiered town placement, and an A\* road network in four tiers
   (Highway, Branch, Rugged, Trail). Written to a binary `.dat`.
2. **3D voxel world** (`Server/` + `Core/`) — the `.dat` is parsed into RAM, and chunks are built
   around the Capitol: a density field per chunk, meshed with Marching Cubes, vertex-coloured by
   biome and depth, with roads carved into the terrain.

**Map size is config-driven**, not fixed. The shipped `ServerConfig.json` selects the `8K` profile →
**8192 × 8192**, where 1 pixel = 1 metre = 1 voxel footprint.

---

## ⚠️ How to actually run it

**Pressing Play (F5) does NOT run the game.** The project's main scene is the 2D map generator, so F5
regenerates the entire world (minutes — and it currently stalls in the A\* road pass) and overwrites
your `.dat`.

**To view the 3D world:**
1. Open `Scenes/Main.tscn`.
2. Press **F6** — *Run Current Scene*.

It reads `ServerConfig.json`, loads the existing `.dat`, and builds the chunk grid.

**To generate a new world** (only when you actually want a new map): press **F5**, or open
`Tools/Scenes/MapPreview.tscn` and press F6.

### Before you run it — set `ChunkRadius`

`ServerConfig.json`, at the project root:

```json
{ "WorldSeed": 1063685222, "MapProfile": "8K", "TownDensity": "Normal", "ChunkRadius": 32 }
```

`ChunkRadius` is a **load radius in chunks**, not a chunk size. The grid built at boot is
`(2 × radius)²` chunks, all synchronously:

| ChunkRadius | Chunks built | Cost |
|---|---|---|
| 4 | 64 | loads in seconds |
| 8 | 256 | still quick |
| 32 (shipped) | 4,096 | ~3.6 GB, minutes |

**Use 4–8 while iterating.** 32 is for looking at a lot of world at once.

`MapProfile` accepts `4K` / `6K` / `8K` / `10K` → 4096 / 6144 / 8192 / 10240.

### Where the generated world lives

Outputs go to Godot's `user://`, **not** into this repo — on Linux,
`~/.local/share/godot/app_userdata/islaApocolypse/`:
- `MapData_Seed_<seed>.dat` — the blueprint (~512 MB at 8K)
- `Map_Seed_<seed>.png` — a visual snapshot of the map, for reviewing and picking seeds

**`WorldSeed` must match an existing `.dat`**, or the load fails with
`CRITICAL ERROR: Map file not found` and you get an empty scene.

---

## Directory layout

| Path | What's in it |
|---|---|
| `Core/` | Shared, stateless logic: the `.dat` parser, Marching Cubes, chunk data, block registry, biome palette, constants. Used by both the server and client paths. |
| `Server/` | Authoritative world building: loads the blueprint, builds chunks around the Capitol, computes densities, carves roads. |
| `Client/` | Rendering: turns finished chunk data into `MeshInstance3D` geometry with a vertex-coloured material. |
| `Tools/` | Offline developer tooling — the 2D map generator and its scenes. Never shipped. |
| `Scenes/` | Runtime scenes. `Main.tscn` is the 3D world. |
| `Data/` | Handoff folder for static world data. Currently documentation only. |
| `Resources/` | Intended home for Godot `.tres` asset definitions. Currently documentation only. |

---

## Current state

**Working:** 2D generation end to end at 8K · `.dat` write and read · chunk building · Marching Cubes
meshing with analytical normals and seam-free integer vertex welding · road carving for **all four
tiers** with per-tier width and grade · biome/depth vertex colouring with soft material fades.

**Known issues:**
- **A\* road generation is slow enough to stall a full regeneration** — a 67-million-node grid at
  1 px granularity, with a same-sized setup loop. The dominant open problem.
- **Faint seam lines along chunk borders** — a normals/shading difference between independently
  meshed chunks, not a gap in the geometry.
- **No player, no collision, no water, and no camera controller** — there is no input handling in the
  codebase at all. Inspect the world with the editor camera.
- The world is built once at boot: **no chunk streaming or unloading** yet.
- Two road issues remain: roadbed elevation can jump where two separate stretches of road pass close
  together, and road *materials* are only a coarse asphalt/dirt split.