beezm/islaApocalypse
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
islaApocalypse/Core
History
beezm 6960c2a2e8 feat: river bed carving with SHORT/LOWGROUND lowland routing A/B (terrain-water task 22, C0b part 2a) 
Executes the frozen task-21b plan as real terrain — the first river pass to
modify the render map. NO WATER (part 2b waters the gated routing style).

RiverCarvePass (D-035 numeric): reruns DrainageAnalysis in-pipeline
(deterministic — same seed, same eroded surface, same plan), routes each routed
giant's lowland reach to the nearest ocean by deterministic Dijkstra under two
config-gated cost models — 'short' (distance + uphill penalty; heads direct) vs
'lowground' (cost ~ elevation above sea; follows the lowest ground and
meanders) — then carves every promoted course as a parabolic channel with a
smoothstep shoulder. Width/depth grow downstream with sqrt(drainage); bed
profile forced monotone non-increasing toward the outlet (water must flow) and
clamped to sea + RiverSeaMargin EVERYWHERE, with below-sea cells read-only and
the crater core excluded — the erosion flood-guard discipline, asserted per
generation by the water-pixel A/B (throws on any change).

Pipeline slot: AFTER GenerateTowns (towns read the render map for land/slope/
water checks — carving first would move towns and destabilise every A/B) and
BEFORE roads (a full run's A* should see the beds).

ISLA_SERVER_CONFIG env override added to ConfigManager: batch/A-B tooling loads
an alternate config file and the developer's live ServerConfig.json is never
written by tooling again (the task-19 restore near-miss class is retired).

Measured, seed 1280587109 (both variants): oracle md5-identical to baseline
(BIOM/WBID bitwise equal), 0 newly-below-sea cells, below-sea untouched, island
top 457.65 m exact, lowest carved cell exactly sea+margin (37.85 m), and
Rivers='off' is bitwise identical to the task-19 blueprint. All routed giants
reach the ocean in both styles. Wander (polyline/straight): SHORT 1.02-1.06 vs
LOWGROUND 1.24-1.38; SHORT carves 811k m3 (cuts through rises, max cumulative
cut 14.6 m), LOWGROUND 481k m3 (goes around, 14.3 m). Pass cost ~25 s (plan
21 s, routing 1.4-2.5 s, carve 0.3 s).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-11 19:16:37 -04:00
..
Scripts feat: river bed carving with SHORT/LOWGROUND lowland routing A/B (terrain-water task 22, C0b part 2a) 2026-08-11 19:16:37 -04:00
README.md docs: water sections (WBID/WBTB/WSRF), no-BSIN rationale, SkipRoads + water stage in READMEs (terrain-water task 03) 2026-08-07 01:40:48 -04:00

README.md

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, all four tiers of A* road vectors (Highways, Branch Roads, Rugged Roads, Trails), and — from v2 files — the embedded generation params (seed, sizes, impact centre, provenance) and each town's highway-node flag.

Two formats are live (byte-accurate contract: Core/Scripts/BLUEPRINT_FORMAT.md). The parser dispatches on the file's first byte:

  • v2 (primary) — raw ISLA magic, u32 version gate, then tagged sections [u32 tag][u64 length][payload]. Unknown tags are skipped by length, so future sections are invisible to older readers. Validated on read: version, MapSize bounds, section lengths against the file, biome/tier ordinal ranges. Since the water-bodies stage, v2 files also carry the optional WBID/WBTB/WSRF water sections (per-pixel body ids, the body table, quantized surface levels) — parsed into WorldBlueprint and consumed by nothing at runtime yet.
  • v1 (legacy) — the positional "ISLA_V1" format, still written beside v2 as _v1.dat and still loadable (with a deprecation warning) until a future removal task.

⚠ Wire-format hazard. Biome and town-tier enums are serialized as their ordinal values (u8 in v2, i32 in v1). Never reorder or insert members in Enums.cs — append only, at the end. v2's range checks make drift fail loudly at parse time; legacy v1 has no validation and silently reinterprets every pixel. (RoadTier is exempt: road tiers are stored in separate file sections — tagged in v2, positional in v1 — 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.