VoxelForge/Standalone/Research/WorldAssemblerM3/Research21/first-pass.md

R21 — Native Core Caves

Finding: Core already stores and evaluates resolved cavern room and edge records, but it has no native Caves stratum kind or graph planner. Those records currently carve over another generator’s field. A native cave needs its own bound field, resolved capabilities and interval classifier. Core field binding · cavern records · R20 inventory

Legacy inventory

Path	What it does
UVoxelGenerator::VF_BuildOpStackForChunk, GetDensityAt, GetDensityWithParams	Routes TunnelNetwork and Underwater into the cave stack. The legacy field starts as rock, carves rooms and tunnels, then applies boundary and passage work. GetDensityAt retains manager routing and thread-local chunk caches; it is not an immutable bound Core field. Its density sign convention is opposite Core’s.
BuildTunnelNetworkStack	Builds the constant-rock source, cached room graph and SDF carve; then optional near-wall roughness, terraces, layer lines, ribbing, overhangs, cliffs, scallops, arches, columns, domes, pinch and floor bias; then worm carving and structural seals. The production route also has a fused evaluator.
BuildChunkCache, EvaluateSDFCached	Resolves seeded rooms, corridors, floor profiles and morphology features into a per-window cache, then evaluates candidate room/tunnel SDFs. Room shapes are pre-baked; local relief and smooth room/tunnel joins provide much of the natural look.
VoxelWormField::Evaluate	Uses two offset Perlin fields; their intersecting low-value sheets create winding worm cuts and organic braids.

The legacy defaults combine room spacing and density, variable room radii, curved corridors, vertical bias, cave warp, floor relief and roughness. For example, the authored RoomSpacing=128 is 16 m at the 12.5 cm owner-voxel scale; some header comments describe it as 32 m. Convert from the recorded legacy units, not those comments. Params · R8 unit audit

The cave field is deliberately seeded: room placement and graph choices use hashes, and worm noise uses seed offsets. I found no unseeded random stream in these evaluators. The remaining determinism risk is unproven bitwise parity across compilers and floating-point paths, not an observed global-random dependency. The bigger gameplay gap is route semantics: the legacy graph is rooted around the origin, not planned between resolved arrival and departure mouths. Frontier rooms may fail to bridge back to the origin; optional worm cuts can also create space outside the required route. Its default 44° floor threshold and climbable ledges do not establish the project’s 15° capsule-swept route guarantee. Legacy graph rules · Core planner proposal

The archived 128³ legacy TunnelNetwork profile measured about 591 ms to fill 2.25 million density samples; its separate classifier route averaged 2.06 s, with 479,872 boxes classified wholly Mixed and none wholly Air. This is historical Unreal-path evidence, not a Core benchmark. It shows why cave intervals must be designed alongside the field. Profiler results

Native design

Add a native cave evaluator to the L40 bound-field table and resolve cave floor and passage behavior as L42 capabilities. Bind immutable, metre-authored graph records once; keep manager lookups and route selection out of sample evaluation. The existing graph resolver derives seeds and bounds for supplied records but does not place rooms or find routes. Plan after passages and stamps resolve, before layout finalization. R12 field and capability design · current resolver · Paris et al., cave skeletons and SDF construction

Build a mandatory spine first between the resolved arrival and departure mouths, with ≤15° maximum local grade, capsule clearance, headroom and support checked on the final composed field. Put at least one room on that route. If the resolved bounds and mouth heights do not admit a feasible route, reject that plan. Graph connectivity alone is not a walkability proof. R18 route plan

Keep legacy room motifs, curved passages, bounded wall roughness and floor relief. Preserve the worm look through seeded, bounded meandering side edges attached to the graph. Do not use unrestricted intersecting noise sheets as the backbone. Add optional pits, chimneys, columns and other morphology only as bounded features after the required route passes.

For floors, make the bore, sloped walk plane and rounded wall-foot one void shape. Avoid a hard cap after passages and stamps; reserve route keepouts and validate the complete composition so later features cannot re-block it. L47–L48 show that floor rails missed wall-foot teeth and the rounded-cap trial still failed its whole-surface audit. Use a geometric fillet of at least 2h, preferably 3h, with coarse-LOD filtering or feature-aware handling. L47–L49 evidence and proposal · R16 fillet guidance

Performance and proof plan

Build a stable-ID BVH over expanded room bounds and subdivided Bezier-edge hulls. Include blend width, roughness reach, floor support, junctions and any detail displacement in every bound. The current graph tile list scans feature bounds linearly, and any box touching a cavern record is classified Mixed. A BVH will reduce candidates, but only conservative intervals can prove air or solid. Graph candidate scan · current graph classification

Provide outward-rounded intervals from day one: analytic ranges for room shapes and floor profiles; conservative subdivided bounds for curves; explicit amplitude budgets for smooth blends and noise. Evaluate roughness only in a bounded band around cave surfaces. Outside finite cave bounds, prove solid; prove uniform air or solid where the whole box permits it; leave boxes Mixed when the field interval crosses zero. Cave-field audits should have no unknown boxes or unsound skips. Extend the isTileShapeFree influence envelope so every structural feature is represented or forces fallback; L44 found that omitting passage support columns caused worker-count-dependent output. L44 finding · L51 interval lesson

Current whole-view references are 1.756 s for SurfaceWorld and 7.355 s for FloatingIslands. A sparse, bounded cave graph is a medium-cost target: likely above SurfaceWorld because it has volumetric interior surfaces, but below FloatingIslands if intervals prune uniform rock and detail stays narrow-band. Dense topology or weak proofs could approach or exceed FI cost. About one second is plausible but unmeasured. The L51 timings are headless whole-view results, not VR frame rates. L51 timings

Migration

Map legacy lengths and displacements in FStrateGenerationParams using 0.125 m per owner voxel; convert inverse-owner-voxel frequencies to cycles per metre by multiplying by eight. Keep ratios, probabilities and degrees unitless. Preserve TunnelFloorTerraceStepHeight as deprecated compatibility data; it is ignored. Convert to integer micrometres once at the adapter boundary. This preserves physical scale, not legacy topology or output hashes. R8 mapping

Keep existing assets on the legacy route by default. Add native caves as explicit opt-in data, preferably an optional per-strate CoreGeometry block with stable IDs and metre fields, and version the serialized asset conversion. The existing strate asset already has a custom-version hook; keep old fields loadable through migration and only change generator identity for opted-in assets. R17 asset and adapter flow · current automatic Core plans

Slices and verification

1. Bound field and fixed spine: one room and one edge joined to resolved mouths; add cave intervals, BVH and final-field route checks. Generalize the L48 whole-surface audit and wire it into verify.py; currently the verifier’s cavern fixture expects one room and one edge, and L48 says its audit is not wired into the tiers. Verifier fixture · L48 audit status
2. Planner: multiple rooms and a deterministic mouth-to-mouth backbone; audit graph connectivity, capsule fit, support, headroom, grade, seals and full-surface defects across a seed matrix.
3. Optional morphology: bounded worm-like side branches, loops, roughness and floor styles; keep the same whole-surface gate and check LOD transitions.
4. Asset and runtime integration: versioned asset migration, Unreal preview/collision/cook, worker/compiler determinism, and paired graph-off/on timings. verify.py can gate Core fixtures; the Unreal adapter also needs its UHT/UBT and owner-asset checks.

Owner question: Should converted legacy settings preserve broad style and scale while the native graph topology is versioned as new? That is the recommended default; close visual parity would need a separate target.

Read-only research only. No scripts, tests, builds, binaries or tree changes were made.