beezm
d72ffc0183
Every README was read first, checked against the code in its directory, then rewritten to describe what the code actually does now. Corrected throughout: map size is config-driven (8192 default) not a fixed 4096; chunks are 24x24x256 not 32x32; road carving is implemented for all four tiers, not a 'next step'; Data/ and Resources/ are empty, not populated. Also fixed MATH_MARCHING_CUBES.md, which documented the density sign convention exactly backwards — it claimed positive was underground, where the code treats positive as above the surface and counts a corner inside when density < iso. Getting that backwards inverts every normal, a bug this project has hit before. The root README now carries accurate run steps: F5 runs the map generator (not the game), F6 on Scenes/Main.tscn runs the 3D world, and ChunkRadius is a load radius that should be dropped to 4-8 while iterating. Docs only. No code changed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
108 lines
4.7 KiB
Markdown
108 lines
4.7 KiB
Markdown
# 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.
|