# Core Module

Shared, stateless logic used by both the server and client paths: the `.dat` parser, the mesher, the
voxel data containers, and the material lookups. **No Godot nodes, no scene state.** These scripts
define what things are and how to calculate them; they never remember what is currently happening.

## Components

### `MapDataParser.cs` — the data bridge
Deserializes the binary `.dat` blueprint written by `/Tools` into a `WorldBlueprint` held in RAM:
map size, the float heightmap, the biome map, town locations, and **all four tiers** of A\* road
vectors (Highways, Branch Roads, Rugged Roads, Trails).

Read order is fixed and must match the writer exactly: magic string `"ISLA_V1"` → map size →
per-pixel `{height float, biome int}` in x-major order → towns → the four road tiers in order.

⚠ **Wire-format hazard.** Biome and town-tier enums are serialized as their **ordinal values**, with
no version gate and no range validation on read. **Never reorder or insert members** in `Enums.cs` —
append only, at the end. Reordering silently reinterprets every pixel of every existing `.dat`.
(`RoadTier` is exempt: road tiers are stored in separate file sections, so that enum never hits disk.)

### `ChunkData.cs` + `Constants.cs` — voxel containers and tuning
- **Chunk dimensions:** `24 × 24` horizontal, `256` vertical (`Constants.cs`).
- **The `+1` padding is structural.** `Densities` and `BlockIDs` are one cell larger on every axis —
  `[25, 257, 25]` — so the mesher can evaluate the boundary cells shared with the neighbouring chunk
  and the meshes meet without gaps.
- **Per-column data for rendering:** `SurfaceHeights` (the true, unrounded surface), `ColumnBiomes`,
  and `ColumnRoadMaterial` (0 = not a road). These let the mesher colour by real height rather than a
  rounded integer.
- **Tunables in `Constants.cs`:** `BLEND_BAND_METERS` (how far one surface material fades into the
  next) and the per-tier road block — width, shoulder, grade-smoothing and surface material for each
  of the four road tiers, plus the derived cull padding.

### `MarchingCubes.cs` — the mesher
Turns a chunk's density field into a Godot `ArrayMesh`.
- **Analytical normals:** exact density gradients at each cell corner, interpolated along the edge by
  the same fraction used for the vertex position — smooth lighting without Godot's normal pass.
- **Deterministic vertex welding:** shared vertices are keyed by an integer `EdgeKey` ordered
  lowest-to-highest, so neighbouring chunks compute identical keys and no float drift creeps in.
- **Vertex colouring:** each vertex is coloured from its true float depth below the surface, fading
  between the two materials either side of a boundary rather than switching at an integer depth.

**Density sign convention (load-bearing):** density is **positive above** the surface and **negative
below** it. A corner counts as inside the terrain when `density < ISO_LEVEL`.

### `BiomePalette.cs` + `BlockRegistry.cs` + `BlockData.cs` — materials
- **`BlockRegistry`:** byte-ID lookup for every block (`AIR`, `BEDROCK`, `STONE`, `DIRT`, `SAND`, the
  three grasses, `SNOW`, `WASTELAND_DIRT`, `ASPHALT`).
- **`BiomePalette`** answers "what material is here?" twice, deliberately:
  - `GetVoxelID(...)` — the authoritative **integer** classification by whole-block depth. Decides
    what is actually stored in each voxel; used for everything non-visual.
  - `GetBlendedVoxelIDs(...)` — the **rendering** version. Same question by *float* depth, returning
    the two materials either side of the nearest boundary plus how far between them the point is, so
    the renderer fades instead of snapping.

  Both take a road-surface byte, so a trail is surfaced in dirt where a highway is surfaced in
  asphalt.