2. What the reference actually does

7 Days to Die as a structural reference — and this repo's own prior attempt at it, which is the case study with actual evidence behind it.

Confidence

The first section is reverse-engineered community knowledge, not documented internals. Treat the broad structure as likely and the specifics as plausible. Since parity is now the explicit target (D3), anything here that turns out to be wrong changes the target — so these are claims to verify against the game, not facts to build on blindly. The second section, drawn from this repo's git history, is fact.

The structure, as far as it is knowable

One grid, two representations, never blended.

Terrain cells carry a density value and are meshed with Marching Cubes. Materials are applied with triplanar mapping and splatting between neighbouring material weights, which produces the soft grass-to-dirt-to-stone transitions on a slope.
Construction is discrete and drawn by a separate path. Rather than deforming, it selects from a large library of predefined block shapes — wedges, ramps, poles, plates, corner pieces. Organic-looking rooflines come from a shape palette, not from a mesher.
Terrain destruction is quantised to a cell, but expressed continuously. A dig reduces a cell's density and the surface re-marches, so the terrain visibly recedes under the tool before the cell finally disappears. This is the behaviour D5 adopts, and it is why the holes are scalloped and lumpy rather than either cubic or smoothly brushed.
Construction destruction is textural. A damaged block keeps its exact shape and gains crack overlays, stepping through visible damage stages until it breaks. This is D6.
Structural integrity runs over both: blocks need support, and undermining a structure collapses it. Orthogonal to the mesher, and arguably a bigger contributor to the "living world" feeling than the terrain shape is.
The world is finite. Typically a few kilometres square, generated or authored up front. VoxelCut now matches this — D7 and D9. An earlier draft chose an effectively infinite world and called it the design's one deliberate divergence; that divergence has been withdrawn, so there is no longer any point at which parity is knowingly given up. See section 5.

The lesson that actually transfers

Key insight

The reference never tries to make its smooth terrain surface meet a block face cleanly. The two representations interpenetrate. Terrain marches past the wall, the block is drawn on top, and nobody notices.

This matters because Epic #24 in this repo was a war fought over exactly that junction — a junction the reference does not attempt to solve. Reading the history back:

Commit	Attempt	Outcome
`bc959a1`	Fix see-through cracks at the junction	Partial
`2095e3e`	Add terrain skirts at construction boundaries	Reverted by `b80c502`
`f91c69f`	Snap terrain boundary vertices onto adjacent construction faces	Superseded
`bb4db56`	Extend snapping to corners and edges	Superseded
`4774aad`	Extend snapping to inner (concave) corners	Superseded
`4656681`	Replace snapping with a watertight "seal + natural" seam	Then the whole isosurface path was deleted in the same commit

Five successive attempts at one junction, one revert mid-stream, and a final solution landed and discarded in the same commit. That is the strongest available evidence about where the difficulty in this project actually is — and it is not in the isosurface algorithm, which worked. It is in making two representations share a boundary.

The prescription for the second attempt follows directly: do not share the boundary. Mesh terrain with construction cells reading as full density so the surface closes against them, draw the cubes over the top, and accept interpenetration. No skirts, no vertex snapping, no watertight junction.

What the final commit says it landed on

Worth quoting from 4656681, because it had arrived close to the reference design immediately before the whole path was cut:

Replace the terrain isosurface's "skip + snap" seam handling with "seal + natural": the surface is now watertight across the junction (no dropped quads = no see-through holes at sharp edges), while construction stays crisp via the existing cube mesher/pipeline drawn on top. […] Remove the vertex-snapping onto cube faces entirely (the flat/coincident look that was rejected).

"Watertight base surface, crisp cubes drawn over the top, no snapping" is essentially the reference architecture. The one mechanism it did not adopt is the cheaper one: letting the two simply interpenetrate, without sealing the terrain surface across the junction at all.

What survived the deletion

The data model was left deliberately intact, which materially lowers the cost of the second attempt:

Voxel::density — the per-cell density byte, still stored and still written by the generator with a soft band of 40 units per voxel of depth. Under D5 this becomes the terrain damage store as well.
kSolidDensity — the shared isovalue at 128, still the single source of truth for the physics solidity test.
terrainFieldDensity() — reports construction cells as full density, so the isosurface closes flush against a wall. Exactly what the "do not share the boundary" prescription needs.
VoxelClass — the Terrain / Construction tag on every voxel. Nothing branches on it today, but it is the hook the two-representation design runs on.
The trilinear density sampler and gradient normal in Raycast.h, plus the faceNormal / normal split on RayHit.
The IMesher strategy interface, whose comment still names a second mesher.

What did not survive: SurfaceNetsMesher.{h,cpp}, the triplanar terrain.{vert,frag} shaders, the terrain texture array and its art, the density brush edit ops, and roughly 500 lines of tests. Of these, only the brush is genuinely obsolete — D5 replaces it with per-cell density reduction.