beezm
a7e6c17422
Byte-accurate v2 contract (magic/version, tagged sections, registered FourCC table, validation rules, re-encode sentinels, extension path) plus the v1 legacy summary — v1 stays live per the safety-net plan. READMEs updated additively: parser dispatch, dual-write outputs, harness usage, server params cross-check, wire-format hazard rewording (u8 on v2 path, range-checked; append-only rule unchanged). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
60 lines
3.6 KiB
Markdown
60 lines
3.6 KiB
Markdown
# /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`) with a safe `GetBlock` lookup.
|
|
- **`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 and per-town highway-node
|
|
flag). 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.
|
|
- **`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.
|
|
- **`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).
|
|
|
|
### 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.
|