beezm
3b5bc5e5d6
Core: BlockRegistry gains WATER, with the reason it is wire-safe (block IDs are never serialized) AND the reason it is a registry identity only rather than a voxel the terrain path writes. Corrects the now-false line "Nothing at runtime consumes the water data yet" -- it does, as of this task. ChunkData's new per-column water fields and the Constants tunables. Client: how the water sheet is built and, more importantly, WHY it is a second mesh instead of a block in the density field -- the trap here is that writing water into a Marching-Cubes field fuses it into the terrain instead of laying it on top, and that is not obvious until you have done it. Notes translucency came free from the separate material. Server: the per-column water rule, which section is the authority for what (WBID presence, WSRF level, WBTB fallback), that an unknown body leaves the column dry rather than guessing, and why depth for shading comes from blueprint heights rather than the clamped rendered geometry. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
71 lines
4.6 KiB
Markdown
71 lines
4.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`, `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.
|