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

# Research R18 — Core cavern graph planner

**Read-only report.** The R17 question is settled: authors provide motifs, size ranges and rules; Core places the rooms and routes from the seed, strate and stable IDs. This fits the composer’s generated-strate vision in [COMPOSER-NOTES.md](/home/jahni/VoxelM/Plugins/VoxelForge/COMPOSER-NOTES.md:18).

## Planner algorithm

1. **Freeze the planning inputs.** Use integer micrometres for the resolved strate content bounds, arrival and departure mouths, existing passages, stamps, and motif limits. Leave clearance inside the resolved ceiling and bedrock bands. Key each random choice by `(world seed, strate ID, motif stable ID, feature role/ordinal)` so one choice does not shift when another motif is added. Sort inputs and final records by stable ID.

2. **Build the guaranteed spine first.** Plan a grade-limited route between the actual resolved mouths. Use a bounded waypoint search through the usable volume, allowing contact with existing passages only at named mouths. Place at least one room on the route: current strict graph validation requires both a room and an edge. Split the route at room portals into edges, with matched floor heights and enough overlap for the player capsule.

3. **Place additional rooms.** Use bounded 3D Poisson-disk sampling for candidate centers, then draw motif and dimensions from their authored ranges with feature-keyed randomness. Reject candidates whose expanded bounds leave the content band, collide with a fill stamp or passage, overlap another room, or lack clearance. Treat carve stamps as usable space only where a deliberate connection is allowed. Bridson’s sampler is relevant for its minimum-spacing samples and spatial search grid; variable room sizes require a variable-radius spacing check. [Bridson, *Fast Poisson Disk Sampling in Arbitrary Dimensions*](https://www.cs.ubc.ca/~rbridson/docs/bridson-siggraph07-poissondisk.pdf)

4. **Attach branches and form loops.** Make 3D Delaunay neighbors candidate connections; reject edges that fail grade, clearance, protected-band or portal checks. Connect accepted off-spine rooms to the spine with a constrained, deterministic spanning tree. Add a bounded number of extra feasible links afterward to create loops; leaves naturally provide dead ends. Space colonisation can bias branch growth toward unfilled parts of the strate, but the spine and clearance checks remain authoritative. This combines the POI/Delaunay/A* ideas in the cave-generation literature with a required path and a spanning-tree connection policy; that combination is a VoxelForge design inference. [Santamaría-Ibirika et al., *Procedural Playable Cave Systems*](https://santosgrueiro.com/papers/2014/2014-Santam-Cave.pdf) · [Runions et al., *Modeling Trees with a Space Colonization Algorithm*](https://www.algorithmicbotany.org/papers/colonization.egwnp2007.html)

5. **Emit and check the records.** Convert accepted features into the existing room and edge records, derive conservative bounds, then validate graph endpoints, connectivity, grade, floor continuity, clearance and protected-band separation. Give each record a stable semantic ID; sort records and all equal-cost choices deterministically.

This order follows Spelunky’s documented practice of generating a safe exit path before adding randomized interest. Deep Rock Galactic offers a useful room-and-tunnel model: room templates have exits that connect through winding tunnels. Minecraft’s cheese, spaghetti and noodle caves suggest useful scale families for chambers and passages. [Spelunky 2 interview](https://blog.playstation.com/archive/2018/08/29/first-look-at-spelunky-2-gameplay-plus-new-derek-yu-interview/) · [Deep Rock Galactic cave-generation article](https://store.steampowered.com/news/posts/?appgroupname=Deep+Rock+Galactic&appids=548430&enddate=1730296516&feed=steam_community_announcements) · [Minecraft, *Caves & Cliffs: Part II*](https://www.minecraft.net/en-us/article/caves---cliffs--part-ii-out-today-java)

## Grade routing in 3D

A 15° walk grade allows at most `tan(15°) ≈ 0.268 m` of vertical change per metre of horizontal run. Check the maximum local grade along each smoothed edge, including its joins—not just endpoint heights or average grade. A 10 m elevation change therefore needs at least 37.3 m of horizontal run.

Place backbone-room floors along a grade-feasible route, and constrain their heights to that profile. When the direct route lacks enough run, use broad switchbacks whose legs progress monotonically in height. Keep legs far enough apart to avoid overlapping XY projections and ambiguous floor ownership; use separate smooth edges for separate legs.

Avoid tight helical coils in the first planner. R3 links L38’s 0.939 m floor-ripple period to the coil’s segment spacing and explains how a nearby turn can win floor ownership. Its proposed floor-near ownership rule improved a synthetic case, but did not prove a fix on the real route. [R3](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research3/REPORT.md:5>) · [R3 coil analysis](</home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research3/REPORT.md:9>)

If the mouths, bounds and grade limit admit no route, reject that candidate; keep the 15° limit fixed.

## Fit with Core and the artifact

The resolved snapshot already carries cavern rooms and edges, and includes them in canonical layout identity. The current `ResolveResolvedCavernGraphV1` copies supplied positions, derives irregularity seeds and bounds, then validates records; it does not choose room positions or routes. A separate Core planning entry point can produce those records before snapshot finalization. [Snapshot records](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h:945) · [Current resolver](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ResolvedLayoutInternal.h:1294) · [R17 finding](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research17/REPORT.md:13)

Run planning after passages and stamps are resolved, before `Layout.finalize` and JSON export. `isTileShapeFree` already rejects tiles whose padded bounds touch graph bounds. Keep those bounds conservative: include supports, blends, relief and junctions. The graph tile-list builder currently scans graph feature bounds per tile; a graph BVH would reduce candidate work as networks grow. Keep candidate order stable after the spatial query. [Adapter order](/home/jahni/VoxelM/Plugins/VoxelForge/Source/VoxelForge/Private/VoxelForgeCoreAdapter.cpp:1259) · [Shape-free proof](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/VoxelForgeCore.cpp:1396) · [Graph tile list](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:3431)

The floor/wall artifact remains unresolved. L47 found sawtooth teeth at the wall foot beyond its floor rails. L48’s rounded-cap trial still failed the whole-surface gate and increased flagged area. L48 describes L49’s next idea—build the bore and floor as one filleted SDF before stamps—but no L49 report or artifact is present in this checkout, so that remains unverified. [L47](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Linux47/REPORT.md:31) · [L48 results and L49 proposal](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Linux48/REPORT.md:13)

For planned rooms and edges, preserve native solid under the walking floor wherever possible; make the floor part of each shape’s profile, with narrow support fallback. Build the floor, bore and rounded wall-foot as one shape. Avoid a hard post-pass floor cap, tangent-only room/edge contact, and wall relief near the walk plane. R16 gives a practical geometric fillet target of at least `2h`, preferably `3h`: at the 25 cm base spacing, 0.5–0.75 m. These are sampling targets, not guarantees; coarse LODs need separate filtering or feature-aware handling. [R16 composition and sizing](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research16/REPORT.md:3) · [Current composition order](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Core/src/ShapeWorldInternal.h:1787)

## Verification plan and implementation slices

- **Graph:** Check endpoint IDs, connectedness, spine reachability, loop counts, room/edge clearance, and mouth joins. Treat links as undirected for reachability; current validation requires an edge’s end ID to name a same-strate room, while its start ID only has to be nonempty.
- **Walkability:** Flood-fill the final composed field from arrival to departure using the project’s player-fit capsule (0.34 m radius × 1.76 m height), support and headroom checks. Graph connectivity alone does not prove a traversable route. [R12 verification guidance](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research12/REPORT.md:51) · [Capsule dimensions](/home/jahni/VoxelM/Plugins/VoxelForge/Standalone/Research/WorldAssemblerM3/Research1/REPORT.md:10)
- **Geometry and determinism:** Sweep seeds, including tight bounds and maximum mouth-height differences. Check edge grades, ceiling/bedrock clearance, wall-foot defects and floor profiles. Extend the L48 audit from its current one-room/one-edge assumption to all graph surfaces; check LOD0 and transitions. Compare layout, density, mesh and topology hashes across worker counts and reordered inputs.
- **Cost:** Measure planner time separately from tile evaluation. Run five paired graph-off/on views with matching tiles; report total and density time, graph BVH candidates, per-feature evaluations and memory. The current edge evaluator searches the curve per sample, so track cost as room and edge counts rise. No graph-scale cost result is established by this read-only review.
- **Slices:** First, one mandatory spine with one room and no optional links. Second, Poisson room placement and connected branches. Third, loops, graph BVH and the generalized whole-surface audit. Run the seed sweep and paired cost measurements before enabling optional topology.

**Questions for the owner:** None blocking; the R17 authoring decision settles the main open question.

Read-only research only; no source edits, builds or tests were made.