VoxelForge/Standalone/Research/WorldAssemblerM3/Astra2/PROMPT.md

VoxelForge — read-only design review: stamp tunnels along the curve instead of searching the curve per sample

You are reviewing a design idea against real code. Do not edit, create or delete any file, and do not build or run anything. Read code and reason. Be thorough; mark each claim as [CODE] (with file:line), [MEASURED] (from a report), or [INFERENCE].

Context

VoxelForge Core (Standalone/Core) generates a density field: negative = solid, positive = air, 25 cm voxels, 32³ tiles, LOD0–8 clipmap, marching cubes. Same seed must give the same world on every machine and worker count; byte-identity with older versions is NOT required.

Inter-strate tunnels ("passages") on branch wip/l111-halfpipe-spline (HEAD 707bc61) are a smooth spline swept tube:

• a D-shaped walkable floor with a continuous floor height h(s), max grade 15°;
• a rounded crest;
• an open-air half-pipe where there is no rock;
• a thin solid shell ("plain shell rule": interior always air, a thin shell always solid);
• smooth-min where tunnels meet;
• mouths that ramp into the ground.

Key code: Standalone/Core/src/ShapeWorldInternal.h (FScopedPassageTileQueries, prepareSweptTubeBase, around lines 374 and 11436), Standalone/Core/src/VoxelForgeCore.cpp:~2747. Reports: Standalone/Research/WorldAssemblerM3/Linux109 … Linux119 (REPORT.md each).

Cost today [MEASURED, L117–L119]: the smooth tunnel is 13–22% slower than the coarse L109 tunnel at LOD0–2 readiness. About 95% of the extra cost is in passage-feature tiles. The causes: sweep pairs (sample × curve segment), exact fallbacks that re-scan segments for off-grid queries, segment visits, per-tile prepare, and smooth-min.

The idea to review (owner + orchestrator)

Today each sample "pulls": it searches for the nearest curve segment and computes a distance. Proposed: "push"/stamp. For each tile, walk the curve in rings (frames: position, forward, up, as with an Unreal spline mesh) and write the tube's signed distance into only the lattice samples near each ring. Only a narrow band of about one voxel around the wall needs an exact value; deep rock only needs "rock" and the tunnel interior only needs "air". Off-grid queries (normals/gradients at seams, gameplay point queries) would read the stamped lattice, interpolating, instead of re-searching the curve. Also: accept curve accuracy at one voxel (25 cm) rather than 2.5–10 cm, and build the curve frames once per route rather than per tile.

Questions

1. Is the cost model right? From the code, what does a passage-feature tile do per sample today, and what would stamping replace? Estimate the work ratio (samples touched × ops) for a typical LOD0 tile and for LOD1–2.
2. What breaks or gets harder, concretely in this code?
   • box verdicts/tile skipping (ClassifyTile-style proofs that a tile is all solid/air);
   • seams between tiles: both neighbours must stamp identical values at shared samples, deterministically;
   • LOD levels (coarser lattices);
   • off-grid DensityAtUnclamped queries and gradients;
   • min/smooth-min with the rest of the field and with other tunnels;
   • the floor h(s), half-pipe, shell, mouths;
   • walk audits;
   • thread safety.
3. Is "write into the lattice" compatible with how density is evaluated (lattice fill vs point evaluation)? If the pipeline is pull-only, what is the smallest change that gets the push benefit? For example, a per-tile sparse band list built by walking rings, then lookups during fill.
4. Is there a simpler or cheaper alternative we're missing? For example, an analytic local frame per sample from the spline parameter, or a coarse per-tile segment window that is already almost free.
5. Recommendation: the design you would build, in steps, with the evidence bar (what measurement would prove or kill it). Keep it short.

Write your answer as plain Markdown, at most ~1,200 words.