islaApocalypse/Core

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.