islaApocalypse/Core/README.md

Core Module - IslaApocalypse

Phase 2 Status: Active (Voxel Math & Parsing Online)

Overview

The Core directory contains the mathematical foundation, data structures, and parser required to bridge the 2D procedural generation with the 3D Voxel Engine. It is strictly logic-driven and contains no Godot Nodes or visual elements.

Key Architecture & Components

1. The Data Bridge (MapDataParser.cs)

Responsible for deserializing the highly compressed binary .dat file generated by the /Tools pipeline.

• Outputs: A WorldBlueprint object held in RAM.
• Capabilities: Reads the 2D heightmap, biome map, and town locations. Crucially, it parses all four tiers of A* road vectors (Highways, Branch Roads, Rugged Roads, Trails) for the Server to use in terrain flattening.

2. Voxel Data Containers (ChunkData.cs & Constants.cs)

• Chunk Dimensions: Defined in Constants.cs. Currently optimized to 32x32 horizontal with a massive 256 vertical height limit to allow for true AAA-scale mountain ranges without heightmap compression.
• Seamless Borders: ChunkData.cs expands its scalar field arrays (Densities and BlockIDs) by +1 on all axes. This allows the Marching Cubes algorithm to sample the neighboring chunk's data, ensuring meshes connect perfectly without gaps.

3. The Math Engine (MarchingCubes.cs)

Transforms the raw ChunkData scalar fields into physical Godot ArrayMesh geometry.

• Analytical Normals: Instead of flat shading, the algorithm calculates exact 3D slope gradients at the corners of each voxel. This produces smooth, realistic lighting across curved terrain.
• Vertex Painting: Reads the BlockID assigned to each voxel corner and applies physical RGB colors directly to the mesh vertices before committing the geometry.

4. Biome & Material Mapping (BiomePalette.cs, BlockRegistry.cs)

Translates the 2D world into physical 3D materials.

• BlockRegistry: A byte-based lookup table defining physical materials (SAND, STONE, WASTELAND_DIRT, ASPHALT).
• BiomePalette Logic: Uses the 2D Biome pixel combined with the 3D currentY depth to determine the block type. For example, Biome.Wasteland combined with a depth of 0 yields WASTELAND_DIRT, while a depth > 4 yields STONE.