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:

{ "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.