beezm/islaApocalypse
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
islaApocalypse/Core
History
beezm 0e39538604 feat: tributary water (tapered), significant-lake targeting, finer steps + deeper beds (terrain-water task 24) 
All three gate polish items — they interleave in the same files, so they land as
one buildable commit rather than three that do not compile independently.

1. TRIBUTARY WATER. Tributaries carved in task 22/23 but stayed dry: they were
   never registered with the water stage. They now are (as CarvedRiver entries
   named 'trib', kept OUT of the per-river console table so it stays the 6
   mains). RiverTribWaterMinFlow (40k px of along-course flow) sets where water
   starts; RiverTribTaperPx (120 px) makes the wet->dry transition a FADE, not a
   wall — across the taper the wet strip narrows (0.25x -> 1x half-width) AND its
   surface drops toward the bed, so a stream head thins out and vanishes.
   Along-course flow is modelled quadratically from headwater trickle to full
   drainage at the mouth (the plan records drainage per river, not per sample).
   RiverTribWaterMinFlow=0 waters them end to end — the documented fallback.

2. LAKE-ENDER TARGETING. The join routed to the nearest classify-water CELL,
   which a 322-px puddle satisfies; it stopped ~80 px short of the 197k-px
   lagoon beside it. It now routes to a SIGNIFICANT water mask (bodies of at
   least RiverLakeMinTargetPx = 20k cells, built from the water-body table),
   falling back to any classify water only if no significant body is reachable,
   so a seed with genuinely small ponds still connects. Proven by adjacency:
   task 23 had 63 river cells touching the puddle and 0 touching the lagoon;
   task 24 has 49 touching the lagoon and 0 touching the puddle.

3. FINER STEPS + DEEPER BEDS. RiverStepDropM 2.0 -> 0.6 and RiverWaterDepthM
   1.2 -> 2.2, RiverDepthScale 1.0 -> 1.5. Reaches 298 -> 1034; the level gap
   between adjacent reaches drops from median 0.571 m / p95 2.08 m to median
   0.124 m / p95 0.74 m — the pond-staircase reads as a graded descent. Reaches
   stay trivial bodies (median 44 px).

Guards all held: flood guard 0 newly-below-sea and 0 below-sea cells modified,
BIOME oracle md5-identical to the task-22 baseline (output-only unchanged),
island top 457.65 m exact, crater core excluded, lowest carved cell exactly
sea+margin (37.85 m). Cumulative max cut 25.98 m with 339 cells >20 m —
identical to task 23, so deepening the WATER did not deepen the worst cuts.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-11 20:24:38 -04:00
..
Scripts feat: tributary water (tapered), significant-lake targeting, finer steps + deeper beds (terrain-water task 24) 2026-08-11 20:24:38 -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.