VoxelForge/Standalone/Research/WorldAssemblerM3/Research1/shared-notes.md

Shared notes (researcher R1 <-> implementer L37), newest at bottom

• Separate cave shape from cave dressing: Ghost Ship describes a constrained room-and-exit skeleton, then biome-specific surface noise and debris; its designers test generated variants for traversal, wayfinding, visibility and class playability (official DRG cave-generation post). For VoxelForge, keep ResolvedLayoutInternal.h responsible for the deterministic route / clearance skeleton and keep material-scale irregularity in ShapeWorldInternal.h; do not let a wall-noise change move the walk floor or route.
• Use distinct tunnel and cavern scales: Minecraft 1.18 explicitly separates large “cheese” rooms from spaghetti and narrow noodle passages, and lets those noise caves form mouths where they intersect the surface (Mojang 1.18 notes). This supports a broad, irregular crater-to-bore transition from intersecting fields, while preserving a narrower path-aligned walk lane; a single uniform portal cylinder is the wrong visual abstraction.
• Layer deterministic noise, with a gameplay mask: Astroneer’s published terrain system uses layered noise and separate cave layers evaluated on the fly without neighboring-cell dependency (Unreal Engine interview). This maps to pure seeded coordinate noise in ShapeWorldInternal.h, masked by distance-from-route / wall orientation so only the rock contour gets warped; keep the walk surface’s slope and capsule clearance under the existing route constraints.
• Treat navigation as a hard constraint, then test variety: DRG’s designers say a structurally valid room can still be unplayable after generator variation and playtest it repeatedly; No Man’s Sky’s patch notes identify navigability as an explicit terrain-generation goal (DRG, NMS terrain update). For this code, keep the capsule/support/open-air and max-grade audits as geometry gates across seeded styles; visual naturalness checks supplement, never replace, them.
• Author macro topology, procedurally fill the in-between: Enshrouded’s world team describes sculpted rough models and hand-placed voxel stamps for topology between POIs (official AMA recap). Translation: route points and surrounding crater shape should determine the large form; use bounded relief as finish. Noise alone is not a substitute for an intentional entrance profile.
• Avoid a single axisymmetric tube at the entrance: The karst SDF work describes passage sections as irregular and asymmetric; for tortuous curves it switches from sweeps to a union of spheres to retain a continuous, 1-Lipschitz field (Paris et al., Synthesizing Geologically Coherent Cave Networks, PDF). ShapeWorldInternal.h::considerCarveSegment already smooths eligible route joins; a later shape pass could add a small asymmetric cross-section / radius profile there, but preserve a conservative bound and leave floor geometry constrained. Risk: true curved cross-section frames and nearest-point evaluation cost more than the present capsule sweep.
• Use erosion as a shape model, not a per-voxel simulation: Cave-network research produces natural branching/channel forms with hydraulic flow and erosion simulation (Pytel & Mann, JCGT; Franke & Müller, karst caves). Translate the erosion cues (unequal scallops, asymmetric channel widening, larger pockets at bends) into fixed-seed route descriptors or one bounded noise term; do not run flow/erosion iterations in ApplyResolvedStratePassageCarves, which is on the per-voxel CPU path.
• Smooth the solid/void intersection locally and watch the field bound: Polynomial smooth-min gives a cheap continuous blend for implicit surfaces (Quilez, smooth minimum); for solid carving, apply the corresponding smooth-max to the solid and negated void field. Restrict it to the opening region and fade it by distance along the path. Smooth CSG shifts the zero-set and may round away a floor or thin rock, so use capsule, support and crease audits after each change.
• Do not warp the walk plane: Domain warping samples a field at noise-displaced coordinates (Quilez, domain warping). It can break periodic wall bands, but its derivative changes the field slope and repeated warps add several noise evaluations; in ShapeWorldInternal.h apply only bounded low-frequency displacement to the wall/ceiling contour, masking by wall orientation and distance from the floor, not to the whole carve or tread field.
• Keep the existing broad phase; use Lipschitz pruning only with proven bounds: VoxelForge already selects passage candidates per tile with an AABB BVH and bounds the nearest-segment search with a per-passage BVH (architecture §8.45). Recent SDF pruning work is explicit that pruning needs exact 1-Lipschitz fields or valid updated bounds for smooth operators (Barbier et al., Lipschitz Pruning, Computer Graphics Forum). Keep new fields inside those bounds; do not assume warped/smoothed noise remains 1-Lipschitz. Cached/trilinearly interpolated fields are a later option only if profiling shows repeated exact queries; interpolation can move the zero surface and needs an exact fallback near the walk surface.
• Bridge code lead for L37: In the current capture-matching source, ApplyResolvedStratePassageCarves unions PassageBridgeSignedDistance for IsPassageShortSpanSegment; that field is a separate deck with 3.3–3.65 m half-width and about 4 m thickness (ShapeWorldInternal.h, around PassageBridgeSignedDistance). Also check IsPassageColumnSegment, which routes through the same support-deck path. The render can therefore come from a planned support feature, independent of cave-wall relief; trace the flagged segment back to its bridge/column plan before changing mouth noise.
• Some examples use authored pieces rather than SDF mouths: Valheim documents room assets consumed by DungeonGenerator (official modding FAQ); Teardown documents a voxel asset tool used for complex campaign terrain (VoxTool). These are useful for authored topology and asset tooling, but neither documents a natural carved mouth algorithm. No Man’s Sky publicly promises more navigable cave systems and reports dual marching-cubes performance work, while leaving its cave-shape algorithm unspecified (NMS terrain update, Worlds Part I); don't infer its internal method.
• Implementer control, L37: Disabling the FI short-span deck left the owner ground-mouth and overview JPEGs byte-identical, while the rock-column audit failed on its four short spans. The deck is needed elsewhere in the route and is not the visible crater-mouth bridge; restored it and traced the entrance carve/support path instead.
• Implementer control, L37: Passage tread and native-route blend ablations left the crater ridge; disabling the route-to-mouth support handoff broke 18 FI route support samples. Current trace points to the final FloatingIslands surface-route heights: its 17-probe maximum footing and grade envelope lift the approach over the crater. L167 tests centerline footing for that final segment, with route audits still binding.
• Implementer trace, L37: FloatingIslandsInternal.h::ConnectorDensity adds an arch up to twice the connector thickness (8 m here), so lowering connector endpoints alone leaves a crater-crossing hump. Testing the v171 version removes that arch and seats connectors 1 m below native island tops; the route is still derived and checked from the resulting field.
• Implementer correction, L37: The owner FI JSON defaults to geometryVersion=4; v171's >=5 experiment gate was inert and its capture matched v170. The actual L37 fix is gated by WorldAssemblyEvaluatorVersion>=172.
• Implementer result, L37: The active v172 no-arch/−1 m connector build retained the surface route but its close capture still showed a central fin. L173 tests the previously effective −2 m sink with the arch removed; passage and both route audits remain gates.
• Implementer result, L37: L173 removed the visible fin; its four surface-route misses were on the western island-0-to-1 connector at x≈−5…−3.5 m. L174 sinks only links touching anchored island 2 by 2 m, preserving the western connector height.
• Implementer trace, L37: L37 ripple diagnostics show later coil queries matching the entrance relief by XY although they are about 55 m below it. The versioned L175 correction also gates the mouth fade to a 4 m vertical window around the entrance floor; the signed carve-distance lerp stays intact.
• Implementer experiment, L37: The largest failing ripple window crosses two helix turns only 0.05 m apart horizontally and 4.17 m apart vertically at 3 m radius. L176 tests the 14.54° (still below 15°) route grade to increase turn separation.
• Implementer result, L37: L176 reduced wall ripple to 3.01 cm but failed capsule support at one sample and left floor ripple at 2.18 cm. L177 restores the prior grade and tapers the anchored tunnel from 3 m to 2 m radius over 8–16 m from the mouth, after the fixed close camera.
• Implementer result, L37: L177's 2 m tunnel radius was rejected: 103 blocked capsule samples and 3.15 cm floor ripple. The final source reverts L176/L177 route experiments and uses the v175 tunnel profile.
• Implementer correction, L37: The final v175 close capture still shows a fin, so root-only connector sinking was insufficient. The global −2 m v173 view removed it, while four support misses were confined to island 0–1; v178 keeps that single link at −1 m and sinks every other connector to −2 m.
• Implementer result, L37: v178 still shows the fin. L179 tests the island-0-to-1 connector at −1.5 m as a visual/support compromise; all other links stay at −2 m.
• Implementer result, L37: L179's capture is byte-identical to the all−2 m v173 control, but route0 has two unsupported samples. L180 tests −1.25 m on the western link to recover those supports while keeping that appearance.
• Implementer trace, L37: The crater bridge is the FI passage helix, not the island connector or short-span deck. Current control points put the route floor 5.4 m above native ground at radius 3 m inside the crater; the mesh at radius 7 m is about 0.1–0.3 m below the intended route floor. L185 tests moving the non-spiral FI passage ring from 3 m to mouth-offset+2 m (7 m), onto the native crater rim; the route/capsule/support audits remain gates.
• Implementer result, L37: v188 fixes the bridge by placing the FI passage coil at 7 m (the 5 m mouth offset plus 2 m), on the native crater rim, and splitting the FI route legs after the entry into 1.375 m supports. The bridge is absent in the 6 m and 17 m views. FI route/capsule/support/open-air checks pass; floor ripple falls to 1.39 cm (1.5 cm gate), wall ripple passes. Full style/compiler audits still pending.
• Implementer result, L37 resumed: v208 passes owner FI styles 0–3. Style 0 uses the terrain-following crater route and crater tread; other FI styles keep the native route/tread profile. The 8.5–12.5 m native mouth filter now applies to every FI passage style; this cleared open-air and style 1/2/3 ripple regressions. Full SW/fixture and compiler matrix still pending.
• Implementer follow-up, L37 v208: a temporary support-off build reproduces the same 25.542° overview sample as the final mesh, so the remaining crease is not the route tread/support. At the 6 m view it is 4.396°; at 17 m the failing sample interval is 0.125 m and projects to 14.34 px at 2560×1440. The 20° overview gate remains a measured failure; no source change was made after the owner accepted the crater appearance.
• Implementer cost, L37 v208: five interleaved pairs completed; median whole-view change was +0.63% surface-world and +2.04% floating-islands, within pair noise.