# Research R1 — natural, walkable cave mouths and tunnels

## What the references show

- **Deep Rock Galactic** separates room/exit structure from biome noise and debris; designers test generated variants for traversal and wayfinding. **Minecraft 1.18** distinguishes caverns from spaghetti and noodle tunnels, and its noise caves form entrances where they intersect the surface. These support a planned route plus a terrain-native mouth, not a portal stamp. [Ghost Ship’s cave-generation post](https://store.steampowered.com/news/posts/?appgroupname=Deep+Rock+Galactic&appids=548430&enddate=1729500950&feed=steam_community_announcements), [Mojang 1.18 notes](https://www.minecraft.net/de-de/article/caves---cliffs--part-ii-out-today-java)
- **Astroneer** describes layered on-the-fly noise with separate cave layers. **No Man’s Sky** identifies navigable caves as a goal and documents dual marching-cubes performance work, but does not publish the cave-shape algorithm. Use these as support for deterministic layers and navigation goals, not as evidence of a specific implementation. [Astroneer](https://www.unrealengine.com/spotlights/how-system-era-softworks-leveraged-ue4-to-create-astroneer-s-wonderful-universe?lang=en-US), [NMS terrain](https://www.nomanssky.com/next-update/), [NMS meshing](https://www.nomanssky.com/worlds-part-I-update/)
- **Enshrouded** describes sculpted macro-topology and hand-placed voxel stamps. **Valheim** documents room assets used by its dungeon generator; **Teardown** documents VoxTool for complex voxel terrain assets. These are topology/tooling examples, not disclosed SDF mouth techniques. [Enshrouded](https://enshrouded.com/ja-JP/news/enshrouded-world-design-team-reddit-ama-recap), [Valheim](https://valheim.com/support/modding-faq-for-the-asset-bundle-update-0-217-40/), [Teardown](https://teardowngame.com/voxtool/)
- Cave research separates playable topology from cave appearance. A karst SDF paper models irregular cross-sections and warns that curved sweeps can lose continuity at high curvature; tortuous paths use a union of spheres. Erosion papers model morphology at generation time, not per voxel. [Playable cave systems](https://santosgrueiro.com/papers/2014/2014-Santam-Cave.pdf), [geological cave SDFs](https://diglib.eg.org/items/a4e7985c-af52-4b55-bd1a-eeeff6c47422), [karst erosion](https://www.sciencedirect.com/science/article/pii/S0097849321002132)

These references do not guarantee VoxelForge’s walk-only contract. Keep its deterministic route, 0.34 m × 1.76 m capsule, supported floor, and slope checks authoritative.

## Ranked proposals

| Rank | Proposal and code location | Expected gain | Main risk / cost |
|---|---|---|---|
| **1** | **Limit the carve by a route floor.** Keep grade-safe route/floor data in [`PlanResolvedLayoutPassagesV1`](../../../../Standalone/Core/src/ResolvedLayoutInternal.h); in [`ApplyResolvedStratePassageCarves`](../../../../Standalone/Core/src/ShapeWorldInternal.h), constrain the tunnel void to above that floor and subtract it from native solid. For negative-is-solid fields: `void = max(tubeSdf, floorZ - z)`, then `carvedSolid = max(nativeSolid, -void)`. Blend the floor to native terrain height along route distance. Replace broad decks where native rock supports the route; keep only narrow fallback support where it does not. | Best chance of a worn path that remains part of the crater/rock instead of reading as a platform. The floor stays explicit and testable. | Medium walkability risk where the source has no solid underfoot or where FI coils overlap. Keep capsule, support, open-air, and slope gates. Low-to-moderate per-sample cost. |
| **2** | **Blend the mouth along route distance.** Refine `mouthCarveFade` / `roughSignedDistance` in `ApplyResolvedStratePassageCarves` (around lines 1168–1209) with a local smooth CSG transition between native terrain and bore. Carving uses smooth-max with the negated void field. Keep the floor cap separate. [Smooth-min reference](https://iquilezles.org/articles/smin/). | Removes a visible seam while letting the entrance follow the local landform. | Smooth CSG moves the zero surface and can round off thin rock or support. L36’s broad filter still left a 27° crease against the earlier 20° probe. Keep it local and hold the crease gate before comparing. Small field cost. |
| **3** | **Shape walls, not the walk plane.** Extend `considerCarveSegment` / `VF_FieldPassageWallRelief` (around lines 933–1043) with one bounded, seeded, low-frequency displacement or asymmetric profile, masked by wall orientation and distance from floor. [Domain warping](https://iquilezles.org/articles/warp/), [karst SDFs](https://diglib.eg.org/items/a4e7985c-af52-4b55-bd1a-eeeff6c47422). | Unequal pockets and folds add geology without ribs or a straight tread outline. | Too much detail can narrow capsule clearance or become periodic. One noise term is cheap; nested warps and curved cross-section sweeps are more expensive and need updated slope/Lipschitz bounds. |
| **4** | **Reuse the current spatial culling.** Bound each new mouth feature so `BuildPassageFeatureTileList`, `PassageMayAffectDensity`, and the nearest-segment BVH skip distant voxels. These AABB and route BVHs already exist ([architecture §8.45](../../../../ARCHITECTURE.md)). Lipschitz pruning is safe only with proven bounds that include smooth blend radii and warp derivatives. [SDF pruning research](https://onlinelibrary.wiley.com/doi/10.1111/cgf.70057). | Protects CPU budget with little geometry risk; lowest-risk performance path. | Little visual gain. Full cached/interpolated distance volumes add memory and can move the zero surface; consider only after profiling, with exact evaluation near the walk surface. |

## What not to repeat from L33–L37

- Regular world-space octaves produced visible 8 m / 4 m wall ribs. Keep relief irregular and seeded.
- Per-segment one-sided tread clamps produced floor washboard. Removing support altogether then caused unsupported samples; keep one continuous floor profile.
- The L34 apron, L36 trapezoid, and L37 raised bridge read as built geometry. The bridge SDF is a separate deck primitive in `ShapeWorldInternal.h`; do not widen it to repair cave shape.
- L36’s broad field filter removed most fragments but left a 27° crease, above the earlier 20° gate. Avoid broad blur and do not tune gates after seeing results.
- Wall-only ripple checks missed the floor beat. Keep walk-floor profiles and negative controls for periodic relief and built shapes.

## Recommendation

Prioritize the floor-limited carve and local terrain-to-bore blend. Let `ResolvedLayoutInternal.h` own the deterministic walk route and grade; let native density provide visible support; confine seeded detail to walls and ceiling. The owner has accepted the current L37 crater mouth, so apply this to the remaining bridge and future shaping without reopening that look.