beezm/islaApocalypse
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: BLUEPRINT_FORMAT.md + README updates for the v2 container (terrain-water task 02)

Browse source 
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>
This commit is contained in:
Stewart Howe 2026-08-06 07:31:03 -04:00
parent 8532d88771
commit a7e6c17422
7 changed files with 185 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

15
Tools/Scripts/README.md
View file

@ -18,7 +18,10 @@ Generates the entire 2D blueprint. Roughly in order:
5. **Biomes and towns** — biome zoning by height and temperature; tiered town placement (Capitol,
Hubs, Villages, Outposts, POIs) filtered by slope, water proximity and spacing.
6. **Roads** — see below.
7. **Export** — writes the `.dat` blueprint, then renders the PNG snapshot.
7. **Export** — writes the `.dat` blueprint (dual-write: the v2 tagged container under the primary
seed name, plus the legacy v1 format beside it as `_v1.dat` — see
`Core/Scripts/BLUEPRINT_FORMAT.md`), then renders the PNG snapshot. The v2 file embeds the
resolved generation params (seed, MapSize, crater radius, density, impact centre, provenance).
### The road network
@ -52,7 +55,15 @@ Road colours on the snapshot, useful for identifying a road: **red** = Highway,
**dark brown** = Rugged, **light brown** = Trail.
### Outputs
`MapData_Seed_<seed>.dat` and `Map_Seed_<seed>.png`, both to `user://`.
`MapData_Seed_<seed>.dat` (v2), `MapData_Seed_<seed>_v1.dat` (legacy dual-write), and
`Map_Seed_<seed>.png`, all to `user://`.
## `RoundTripHarness.cs`
The blueprint format regression test (scene: `Tools/Scenes/RoundTripHarness.tscn`). Loads a
known-good blueprint through the real parser, re-writes it as v2 through the real writer, re-loads
it, and asserts semantic equality (heights bitwise, biomes, towns, every road point). Headless,
seconds per cycle, no generation. Exit code 0 = pass.
## Rules
1. **No magic numbers.** Distances, radii and thresholds derive from `MapSize` or `scaleFactor`, so