beezm/islaApocalypse
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
islaApocalypse/Core
History
beezm 566abe9784 feat: submarine coast shelf + elongation dials (terrain-water task 11) 
COAST. The task's premise -- "the island edge is the steepest part" -- is
right, and the diagnostic locates it precisely: it is the SEABED, not the
land. HeightCurve.Apply returns early at and below sea level, so tasks
05-09 reshaped the land and never touched the water. Measured on the same
seed, distance-from-shore vs height:

                       land reaches 10 m   seabed reaches 10 m   gradient
  curve OFF                   31 px               31 px       0.254/0.258
  curve ON (ships)           186 px               31 px       0.038/0.258

So the landward side is ALREADY the broad shallow shelf terrain_design.md
asks for -- 54% of the island sits under 14 m -- and flattening it further
would only make it mushy. What is left is a shoreline that shelves gently
on land and then drops 6.7x steeper the moment it goes under.

CoastShelf fixes that side: depth' = depth * (1 - 0.775*exp(-depth/100 m)).
The seabed leaves the waterline at 22.5% of its former gradient and
recovers smoothly, so deep water and the Trench keep their shape. Measured
after: 5 m depth at 43 px (was 15), 10 m at 75 (was 31), 30 m at 150 (was
94) -- a 2.4-2.9x wider shallows.

It is strictly positive for positive depth, so it CANNOT move the waterline
by one pixel. Biomes and water bodies come out bit-identical, which is why
the coast is separable from elongation in the batch rather than tangled
with it -- contrary to the task's expectation that all coast work moves
biomes.

ELONGATION. IslandAxisX/Y replace the 1.15/0.90 literals (the spine shares
AxisX, as it always shared the literal). Sized by replaying candidate
falloffs against real terrain rather than guessing -- the replay reproduces
the shipped extents exactly, bbox and land count.

That replay says the task's suggested 1.30/0.85 buys +2.0% aspect, because
THE ISLAND IS ALREADY TRENCH-CLAMPED IN X: it spans 90.5% of the map width,
and 1.15 -> 1.40 moves the west coast only 393 -> ~360 px. Aspect responds
almost entirely to AxisY, which costs land:

  1.30/0.85  +2.0% aspect  +2.9% land      1.30/0.80  +4.9%  -2.2%
  1.30/0.82  +3.7% aspect  -0.1% land      1.30/0.75 +11.5%  -7.3%

Default 1.30/0.78 -- a visible step (+~8% aspect, measured 1.137 -> 1.200)
at ~4% land. The developer's eye tunes it from the batch; the table above
is the price list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-08 23:29:49 -04:00
..
Scripts feat: submarine coast shelf + elongation dials (terrain-water task 11) 2026-08-08 23:29:49 -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.