beezm
d72ffc0183
Every README was read first, checked against the code in its directory, then rewritten to describe what the code actually does now. Corrected throughout: map size is config-driven (8192 default) not a fixed 4096; chunks are 24x24x256 not 32x32; road carving is implemented for all four tiers, not a 'next step'; Data/ and Resources/ are empty, not populated. Also fixed MATH_MARCHING_CUBES.md, which documented the density sign convention exactly backwards — it claimed positive was underground, where the code treats positive as above the surface and counts a corner inside when density < iso. Getting that backwards inverts every normal, a bug this project has hit before. The root README now carries accurate run steps: F5 runs the map generator (not the game), F6 on Scenes/Main.tscn runs the 3D world, and ChunkRadius is a load radius that should be dropped to 4-8 while iterating. Docs only. No code changed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
57 lines
3.7 KiB
Markdown
57 lines
3.7 KiB
Markdown
# 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.
|