VoxelForge/Standalone/Research/WorldAssemblerM3/Research12/REPORT.md

# Research R12 — Composite cavern graph

**Read-only review; no source changes, scripts, tests, or binaries.**

## Design

Build one immutable cavern field per selected strate. Its resolved graph has stable chamber nodes, tunnel edges, and a required arrival-to-departure backbone. Resolve it before tile jobs from `(world seed, absolute strate, recipe/version, stable node or edge ID)`. Store positions, radii, floors, and conservative bounds in integer micrometres; sort records by stable ID. The field must return the same value for a physical coordinate at every LOD.

Build the required spine first, connecting the actual resolved mouth anchors. Add optional branches and dead ends afterward; add loops only as edges between already connected nodes. Graph connectivity alone does not guarantee a walkable route: room and tunnel portals must overlap with clearance, their floors must meet, and the final field must pass the arrival-to-departure player-fit audit.

Use smooth ellipsoid or blob SDFs for chamber envelopes and swept capsule SDFs for tunnel edges. Keep an explicit floor profile on each room and edge; cap the void at that floor and keep the floor cap separate from smooth unions and wall relief. Start from the native substrate, carve the graph into it, then let the existing shared boundary and inter-strate passage composition run. With Core’s signed-field convention, carve using smooth maximum with the negated void SDF. Keep seeded, bounded relief on walls and ceilings, away from the walk plane.

For floors, apply R1’s floor-first carve and narrow native-solid support fallback. R3 warns that overlapping coils can select the wrong floor owner: for floor samples, consider only candidates within half a voxel (0.125 m) and within the bore radius; choose by floor-point distance, then stable feature ID. Keep tube ownership separate from floor ownership. R3’s synthetic result does not prove that rule fixes the real L38 floor behavior, so verify it on the actual field before adoption. [R1](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research1/REPORT.md:10>) · [R3](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research3/REPORT.md:1>)

The design follows useful patterns from prior work: Minecraft names distinct large “cheese” caverns, winding “spaghetti” tunnels, and narrow “noodle” passages; Deep Rock Galactic connects authored room templates with narrow tunnels and varies room interiors; Spelunky 2 constructs a safe route from room templates before adding optional exploration. Cave-generation papers likewise separate network topology from its SDF geometry: one uses Voronoi/Delaunay structure for playable cave connections, and another builds a cave graph and derives conduit geometry from an SDF construction tree. [Minecraft](https://www.minecraft.net/de-de/article/caves---cliffs--part-ii-out-today-java) · [Deep Rock Galactic](https://store.steampowered.com/news/posts/?appgroupname=Deep+Rock+Galactic&appids=548430&enddate=1730296516&feed=steam_community_announcements) · [Derek Yu interview](https://blog.playstation.com/archive/2018/08/29/first-look-at-spelunky-2-gameplay-plus-new-derek-yu-interview/) · [Santamaría-Ibirika et al., 2014](https://santosgrueiro.com/papers/2014/2014-Santam-Cave.pdf) · [Paris et al., 2021](https://onlinelibrary.wiley.com/doi/full/10.1111/cgf.14420)

## Fit with R6 and current code

- **Resolved layout:** Add optional, versioned graph records to the resolved snapshot, following L43’s optional stamp vocabulary pattern. Include active graph records in canonical identity; bump the selected recipe/evaluator version when its geometry changes. Existing graph-free layouts should retain their identity. The snapshot currently holds strates, passages, and stamps in [VoxelForgeCore.h:907](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h:907>).

- **Bound field table:** L40 binds one concrete evaluator per strate in `BindResolvedStratumFields`; its variant currently covers SurfaceWorld, FloatingIslands, and legacy fields. Add a native cavern-network adapter that binds the graph and substrate once. Keep evaluation free of manager lookups. R6’s target uses physical metre queries; today’s adapter evaluates in voxel coordinates, so keep graph data in micrometres and convert at the binding boundary, or add the physical-coordinate API as a separate migration step. [R6 §2](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research6/REPORT.md:22>) · [L40 adapter and binding](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:136>) · [Binding function](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:286>)

- **Capabilities and shared composition:** L42 resolves interface and passage policy before sampling. Resolve graph-floor policy at the same stage; avoid per-sample generator-name branches. Preserve the current ceiling/content/bedrock order and let shared passages retain ownership of inter-strate openings. `ApplyResolvedStrateComposition` currently applies boundary bands, passage carving, then stamps. Put cavern carving inside the bound field evaluator, before shared boundary composition, so a chamber cannot cut through protected bands. [L42 architecture](</home/jahni/VoxelM/Plugins/VoxelForge/ARCHITECTURE.md:2218>) · [Composition](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:1781>)

- **Stamps and BVH culling:** Reuse L43’s ellipsoid SDF, bounded relief, stable IDs, and BVH implementation patterns. Keep graph rooms as graph records rather than generic landmark stamps: stamp placement rejects route/walk-corridor intersections, while network features intentionally connect to the route. Add room and edge bounds to the tile feature query so tiles evaluate only relevant graph features. [Stamp records](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h:736>) · [Stamp BVH](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:3327>) · [Passage feature BVH](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:3497>)

- **Shape-free proofs:** Extend `World::isTileShapeFree` with conservative bounds for every graph room, edge, blend radius, relief reach, and support feature. Any overlap must make native-only eligibility fail; box classification must remain mixed/unknown on graph overlap. L44 traced a worker-count mismatch to omitted support-column bounds in this proof. [Proof function](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/VoxelForgeCore.cpp:1359>) · [L44 finding](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Linux44/REPORT.md:5>)

The legacy `TunnelNetwork` already has room/corridor SDFs and worm tunnels, but R6 describes it as a legacy evaluation route. A resolved Core graph adds the missing precomputed connectivity, floor ownership, bounded feature records, and field contract.

## Risks

| Risk | Control and evidence |
|---|---|
| Connected graph, unwalkable field | Keep explicit floor profiles and portal overlap; audit final-density capsule clearance, support, grade, and mouth-to-mouth connectivity. |
| Floor errors at loops or crossings | Use floor-near ownership with stable tie-breaking; measure the real owner field because R3’s synthetic case did not reproduce L38. |
| Per-voxel cost grows with graph size | Use conservative feature AABBs and tile BVH candidates; record candidates and SDF evaluations per tile and benchmark paired graph-off/on views. |
| Chamber or support crosses a seal | Include smooth blend, relief, and support extents in graph bounds; reject placements touching ceiling, bedrock, or protected bands. |
| Nondeterminism or stale identity | Hash sorted graph records and versions; use fixed-point placement and keyed per-feature seeds; compare worker counts and compilers. |

## Smallest slices

1. **Owner demo:** Add one large chamber and one floor-capped tunnel edge connected to the existing tested arrival-to-departure route. Keep that route as the guaranteed spine. Use the accepted L45 chamber record as the first room node if its bounds and connection fit; otherwise use one fixed, opt-in demo record. No random branches or loops. Verify a deterministic layout round trip, readable approach/entrance/interior captures, and the existing walkability and boundary checks.

2. **Resolved graph generator:** Support multiple room motifs and a mandatory connected backbone, with per-node/edge bounds and graph-aware culling. Verify seed stability, graph connectivity, and arrival-to-departure walkability across the owner seed matrix.

3. **Optional topology and detail:** Add bounded branches, dead ends, then loops; add seeded wall relief after floor and clearance gates pass. Verify loop crossings, floor ownership, cost scaling, worker/compiler parity, and LOD ring behavior.

4. **Authoring and runtime integration:** Expose motif and rule data to the owner, then connect the opt-in recipe to Unreal preview, collision, and cave presentation.

## Measurements to run

- Snapshot round-trip and canonical identity across repeat resolves, worker counts, and reordered inputs.
- Graph connectivity plus final-density six-neighbour player-fit flood fill from resolved arrival to departure; require the project’s full seed law gate, not just graph reachability.
- Passage audits for capsule fit, floor support, ≤15° grade, open air, floor ripple, and mouth transitions.
- Strict bounds and hole/bedrock-band audits, including negative controls that force a graph feature into a protected band.
- W1/W8/W12 determinism at the L44 failure camera plus random cameras; compare density, mesh, payload, and topology hashes.
- Five paired graph-off/on cost runs at matching tile sets; report whole-view time, density time, BVH candidates, and per-feature evaluations. Repeat at increasing graph sizes after the first slice.

## Owner authoring

Start from the project’s existing scale families: chamber radii of 4–10 m, tunnel radii of 1.5–2 m, and metric bounds relative to strate interfaces. [ARCHITECTURE §8.0](</home/jahni/VoxelM/Plugins/VoxelForge/ARCHITECTURE.md:17>)

The owner should author chamber motifs and floor styles; connector radius, bend, and widening rules; required route and allowed degree; branch, loop, and dead-end limits; and bounded wall-relief palettes. Keep the required spine’s clearances and floor-grade limit fixed across motifs.

**Owner question:** May the accepted L45 chamber become the first graph node, with the existing arrival-to-departure route retained as the guaranteed spine?