# /Core/Scripts

Pure C# data structures, shared enums, and static maths. Compiled into the shared assembly used by
both `/Server` and `/Client`.

**"Pure data, zero state."** These scripts define *what* things are and *how* to calculate them. They
never track live game events — who is online, which chunks are loaded, what time it is.

## What's actually here

### Voxel materials
- **`BlockData.cs`** — struct describing one block type (ID, name, IsSolid, BaseColor).
- **`BlockRegistry.cs`** — the byte-ID master list (`AIR` 0, `BEDROCK`, `STONE`, `DIRT`, `SAND`, the
  three grasses, `SNOW`, `WASTELAND_DIRT`, `ASPHALT`, `WATER`) with a safe `GetBlock` lookup.
  **Block IDs are never serialized** — the blueprint stores heights, biome ordinals and water data,
  never block IDs, and chunks are not persisted — so appending to this table is wire-safe.
  `WATER` is a registry identity only: it is not written into `ChunkData.BlockIDs`, because water is
  drawn as its own surface rather than as part of the terrain iso-surface (see `Client/README.md`).
- **`BiomePalette.cs`** — decides which material sits where, given biome, depth, and whether the
  column is roadbed. Two paths on purpose: an **integer** classification that decides what is stored
  in each voxel, and a **float-depth** version used for rendering that returns the two materials
  either side of a boundary so colours fade rather than snap.

⚠ Note that `BlockRegistry` and the mesher's colour table hold **different RGB values** for some
blocks. The mesher's table is what you actually see; `BlockData.BaseColor` is currently unused by
rendering.

### Shared identifiers
- **`Enums.cs`** — `Biome`, `TownTier`, `MapHalf`, `RoadTier`.

  ⚠ **`Biome` and `TownTier` are the `.dat` wire format** (u8 in the v2 container, i32 in legacy
  v1). They are declared without explicit values, so each member's ordinal *is* the number written
  to disk. **Append only, at the end — never reorder or insert.** The v2 reader range-checks
  ordinals so drift fails loudly at parse time, but only the append-only rule keeps old files
  *meaning* the same thing. Legacy v1 has no gate and no validation at all.
  `RoadTier` is exempt: road tiers live in separate sections of the file, so it is never serialized.

### World data
- **`BLUEPRINT_FORMAT.md`** — the byte-accurate `.dat` container contract (v2 tagged sections +
  the v1 legacy summary). Read this before touching the writer or parser.
- **`BlueprintFormat.cs`** — the single registry of v2 constants: magic, version gate, section
  tags (FourCC), validation bounds, re-encode sentinels.
- **`BlueprintWriter.cs`** — writes a `WorldBlueprint` as a v2 file. Blueprint-typed on purpose:
  the map generator and the round-trip harness are both just callers.
- **`MapDataParser.cs`** — decodes a `.dat` blueprint into a `WorldBlueprint` (heightmap, biome map,
  towns, four road tiers, and — v2 only — the embedded generation params, per-town highway-node
  flag, and the optional water-bodies data: `WaterBodyIds`, `WaterBodies` table, `WaterSurfaceQ`).
  Dispatches on the first byte: v2 tagged-section files get validation (version gate, size
  bounds, section-length and ordinal range checks); legacy v1 files still load, intact, with a
  deprecation warning. **The water sections are consumed at runtime since task 13** — the server
  reads them per column and the client draws the result (see `Server/README.md`).
- **`ChunkData.cs`** — one chunk's density and block-ID fields, `+1` padded on every axis so the
  mesher can reach into the neighbouring chunk, plus the per-column data the renderer needs —
  including `WaterSurfaceY` (world Y of the water surface, or `Constants.NO_WATER`), `WaterDepthM`
  (true depth from blueprint heights) and `HasAnyWater`.
- **`Constants.cs`** — chunk dimensions, `ISO_LEVEL`, `VOXEL_SCALE`, and the visual/road tunables
  (material blend band; per-tier road width, shoulder, grade smoothing and surface), plus the
  water-at-rest tunables: `HEIGHT_SCALE` (the one raw-height→metres mapping, shared by the terrain
  surface and the water sheet so they cannot drift apart), `NO_WATER`, and the depth-shading
  colour/alpha ramp.

### Maths
- **`MarchingCubes.cs`** — density field → `ArrayMesh`, with analytical normals and deterministic
  integer-keyed vertex welding.
- **`MATH_MARCHING_CUBES.md`** — an explainer of the algorithm.

## Rules
1. **No Godot node inheritance.** Pure classes, structs and statics.
2. **No `_Process` / `_Ready`.** Nothing here is attached to a live scene object.
3. **Dependencies flow inward only.** `/Server` and `/Client` reference `/Core`; `/Core` never
   references them.