# 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`.