islaApocalypse/README.md

IslaApocalypse - Voxel Engine Architecture

Current Version: v0.0.1 (Phase 2 - Voxel Engine Online, v0.0.x Prototyping / Tech Demo) Engine: Godot 4 (C#)

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.

Development State

• Phase 1: 2D Blueprint Engine -> [COMPLETE]
• Phase 2: 3D Voxel Engine -> [IN PROGRESS - Basic Rendering Online]

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.

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.