docs: bring all READMEs current with actual code (post-sweep-10 truth pass)
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>
This commit is contained in:
parent
f9ea2da3f4
commit
d72ffc0183
13 changed files with 579 additions and 409 deletions
124
README.md
124
README.md
|
|
@ -1,28 +1,108 @@
|
|||
# IslaApocalypse - Voxel Engine Architecture
|
||||
# IslaApocalypse
|
||||
|
||||
**Current Version:** v0.0.1 (Phase 2 - Voxel Engine Online, v0.0.x Prototyping / Tech Demo)
|
||||
**Engine:** Godot 4 (C#)
|
||||
**Version:** v0.0.1 — prototyping / salvage. Not a playable build.
|
||||
**Engine:** Godot **4.7.1** · C# / .NET 8 (`Godot.NET.Sdk 4.7.1`)
|
||||
|
||||
## Project Overview
|
||||
IslaApocalypse is a procedurally generated, multiplayer-ready survival/driving game. The engine uses a two-phase generation system: first building a massive 4096x4096 2D topographical blueprint, and then dynamically translating that data into a 3D Marching Cubes voxel world at runtime.
|
||||
A procedurally generated, multiplayer-ready voxel survival game on a post-nuclear Caribbean island.
|
||||
Terrain is smooth (Marching Cubes), not blocky.
|
||||
|
||||
## Development State
|
||||
* **Phase 1: 2D Blueprint Engine** -> **[COMPLETE]**
|
||||
* **Phase 2: 3D Voxel Engine** -> **[IN PROGRESS - Basic Rendering Online]**
|
||||
> **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`).
|
||||
|
||||
### Current Capabilities (What works right now):
|
||||
1. **The 2D Blueprint (`MapGenerator.cs`):** Generates a 4096x4096 map using `FastNoiseLite`. It features dynamic sea levels, a massive impact crater, tiered city placements (Capitol, Hubs, Villages), and a heavily optimized A* pathfinding network (Highways, Branch Roads, Trails) that utilizes Chaikin's smoothing algorithm.
|
||||
2. **Binary Serialization:** Exports the entire 16-million pixel array and path vectors into a lightweight, byte-aligned `.dat` file.
|
||||
3. **The Data Bridge (`MapDataParser.cs`):** Seamlessly deserializes the `.dat` file back into RAM as a `WorldBlueprint` for the server to read.
|
||||
4. **Authoritative Chunk Management (`ServerChunkManager.cs`):** Dynamically locates the Capitol City, converts pixel coordinates to 3D chunk coordinates, and generates a grid of `ChunkData` objects (32x32x256 meters) around the player.
|
||||
5. **Marching Cubes Rendering (`MarchingCubes.cs`):** Translates 2D heightmaps into 3D geometry. Features analytical normals for smooth lighting and dynamically paints Vertex Colors based on the 2D `BiomeMap` (Wasteland, Sand, Grass, Stone).
|
||||
---
|
||||
|
||||
## Directory Architecture
|
||||
* `/Tools/`: Contains the v1.0 2D Map Generator and preview scenes. Run `MapCaptureTool.tscn` to generate a new world seed.
|
||||
* `/Core/`: The math and data foundation. Contains the Binary Parser, Marching Cubes algorithm, Biome Palettes, and `ChunkData` structs.
|
||||
* `/Server/`: The Authoritative Server logic. Manages chunk loading, calculates voxel densities, and handles chunk culling.
|
||||
* `/Client/`: The visual layer. Takes raw `ChunkData` and translates it into Godot `MeshInstance3D` objects with vertex-colored materials.
|
||||
## How the world gets built
|
||||
|
||||
## Next Immediate Steps (Phase 2, Step 4)
|
||||
* **Road Carving:** Inject A* road vector data into the `ServerChunkManager` to override the natural heightmap, physically flattening the 3D terrain and painting Asphalt blocks to create drivable highways through the mountains.
|
||||
* **Chunk Seams:** Implement normal-blending across chunk borders to remove grid-line lighting artifacts.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue