VoxelForge/CODEMAP.md

VoxelForge — Code Map & Knowledge Index

Purpose: a navigation index so anyone (human or AI) can locate and modify code without re-reading the whole plugin. Anchors are File:line — line numbers drift as code is edited, so trust the symbol name first and the line as a hint.

Plugin root: Source/VoxelForge/ · ~8,300 lines of C++ across 25 files. Comments in the code are mixed French + English. UE modules: VoxelForge and VoxelForgeCore (Runtime), plus VoxelForgeEditor (Editor).

---

1. What this plugin is

A density-field voxel terrain plugin for Unreal Engine, built around underground "strates" (vertical geological layers, each a self-contained mini-world).

• No block grid. Terrain is a continuous scalar density field evaluated on the fly from world coordinates. Convention: negative = solid rock, positive = air (the Marching Cubes convention used throughout).
• Marching Cubes turns the density field into a smooth mesh per 32³ chunk.
• Strates stack downward from Z=0. Each strate is a UVoxelStrateDefinition data asset that picks a generator type and a huge bag of cave-shaping params.
• Async streaming: chunks load/unload around the player on background tasks; meshes are applied on the game thread under a per-frame budget.
• Player edits (carve/fill) are stored as a diff layer added on top of the procedural density — procedural generation stays deterministic.

Core terminology

Term	Meaning
Chunk	32×32×32 voxels (CHUNK_SIZE). Voxel = 12.5 cm (VOXEL_SIZE), so a chunk is 4 m.
Density	Scalar field. < 0 solid, > 0 air, 0 = surface (IsoLevel).
Strate	Vertical layer of the world, stacked downward. Has its own generator + params.
Generator type	Archetype per strate: TunnelNetwork, FlatPlain, CrystalChamber, Maze, SurfaceWorld, VerticalShafts, FloatingIslands, Underwater. See §8.
(0,0) spine	Guaranteed open landing column at world XY (0,0) in every strate; descent is player-dug through the seals. See §8.
Terrain op	Optional density modifier (pit, arch, terrace…) attached to a strate.
Passage	Carved tunnel connecting two adjacent strates (progression path).
Diff layer	Player carve/fill modifications stored on top of procedural density.
Epoch	Generation counter; stale async results are discarded on mismatch.

---

2. The big picture — data flow

                         AVoxelWorld (actor, orchestrator)
                         Tick → UpdateChunksAroundPosition
                                   │  (load/unload around player, by distance + LOD)
                                   ▼
                         LoadTile → UE::Tasks::Launch  ──────────► background thread
                                                                         │
   UVoxelMarchingCubesMesher::GenerateMesh(chunk, step) ◄────────────────┘
        │ samples density per cell corner
        ▼
   UVoxelGenerator::GetDensityAt(x,y,z)        ← THE density entry point
        │ asks StrateManager which strate/params/generator-type applies
        ├─ builds the chunk's operator stack once per chunk (VF_BuildOpStackForChunk;
        │   editor composer / cooked-season recipe stacks first)  → every archetype
        │     TunnelNetwork/Underwater → fused evaluator = GetDensityWithParams()
        │       └─ VoxelCaveMorphology::BuildChunkCache + EvaluateSDFCached  (room/tunnel SDF)
        │     others → FVoxelOpStack::EvalMC  (source → modifiers → structural posts)
        ├─ + disturbances + structural tail (landing floor, tunnel core, XY seal)
        └─ + UVoxelDiffLayer::GetDensityOffset()   (player carve/fill)
        │
        ▼ FVoxelMeshData (verts/tris/uvs/normals)
   ProcessQueue (lock-free) ──► game thread: ProcessPendingChunks → ApplyMeshToChunk
                                                                   (RealtimeMeshComponent)

UVoxelStrateManager is the side oracle: "what strate is at this Z, what params, what generator type, and is there a passage/elevator SDF near here?"

---

3. File-by-file reference

Paths relative to Source/VoxelForge/. Public/ = headers, Private/ = impl.

3.0 Human-scale generation contract (2026-10-01)

VOXEL_SIZE is 12.5 cm; 32³ voxels make each chunk 4 m. The gameplay capsule remains 0.34 m radius / 1.76 m tall (2.72 / 14.08 voxels). The default strate envelope is 16 chunks / 512 voxels / 64 m; serialized owner strate assets that still say 8 chunks must be changed to 16. Research-field dimensions are authored in metres and converted at runtime. The live strate generator continues to read voxel-valued parameters from its assets, so those authored dimensions become half as large in metres unless their asset values are doubled.

The intended metre-scale families remain: room diameters 8-20 m, origin hub 24 m, room cells 32 m, round tunnel bores 3-4 m, maze cells 16 m with a 6.25 m nominal bore (3.125 m radius; 3.0625 m worst-case usable floor after roughness), slab open span 22.4 m, shaft diameters 4-7 m, island diameters 12-24 m, and ordinary inter-strate bores 3-4 m. Source new fixed physical dimensions are authored in metres and converted to voxel counts at the boundary. The owner's voxel-valued live strate assets are not migrated by C++: unchanged saved values therefore produce half-size rooms, tunnels, features and noise periods in metres. See the step-3 migration list in the handoff report for the exact DA_Settings fields and values.

Owner asset migration (no packages were edited): preserve DA_Settings distances by changing ViewDistanceXY 32→64, ViewDistanceUp/Down 10→20, PawnCollisionRadiusChunks 2→4, StrateViewMarginChunks 6→12, ClipRadius 6→12, RenderDistanceChunks 1536→3072, EdgeSealThickness 128→256 voxels, decoration radius/near radius 12/6→24/12 chunks, region size 8→16 cells, spacing/far spacing 8→16 voxels, march step 4→8 voxels, column depth 320→640 voxels, OriginSpineRadius 28→56 voxels, MaxBrushRadius 30→60 voxels, and SkirtCells 1→2. If the density volume is enabled, set resolution 256→512 and debug radius 12→24 cells; it is currently disabled. Keep MaxClipLevel=6 and zero-valued disabled/unbounded limits unchanged; double finite world radii and gaps, and multiply finite voxel-volume caps by 8. The loaded Crystal Cave slot in DA_Strate3 is 64 chunks tall; use 128 chunks to preserve its former 512 m span. Its voxel-authored live-generator lengths remain half-size until that asset is re-authored; the editor-only research field is the step-3 target.

Step-3 six-worker scale benchmark (idle machine, Saved/Research/step3/scale/step3_scale_cacheperf_v1): the 519³ field took 7.133834–7.825292 s across three runs (median 7.347496 s); the 259³ field took 1.098521–1.194640 s (median 1.169567 s). The inclusive sample lattices span 64.75 m and 32.25 m between end samples respectively (the requested approximately 64 m / 32 m fields). Both runs were deterministic across three trials. This records evaluator time only, not game streaming. Six-worker 4³-brick proof, sound-bound audit, seam injection, and 1-vs-6-worker hashes pass. Reusing exact detail-lattice hash corners across adjacent mixed bricks reduced the earlier step-3 259³ median from 1.502908 s to 1.169567 s; the separate step-2f 600 ms worst-profile timing bar still does not pass at the finer voxel size.

The opt-in Core route resolves physical voxel size from AVoxelWorld::CoreVoxelSizeCm (default 25 cm) and keeps 32 voxels per Core tile. GetActiveVoxelSizeCm() is the runtime conversion point for coordinates, mesh vertices, collision, streaming, LOD, content, water, atmosphere, and brushes; WorldConfiguration::voxelSizeMicrons plus tileVoxelCount carries the resolved values through Core. A nondefault size participates in Core snapshot/season identity, while 25 cm preserves the recorded default hashes. Core-off continues using the legacy 12.5 cm grid. This is currently a per-world setting; per-strate sizes still need physical-coordinate sampling, transition stitching, cross-boundary edit rasterization, per-strate LOD agreement, and a canonically ordered size map in the hashed identity.

The reachable roughness envelope is roughness * VOXEL_NOISE_SCALE * 1.5, or roughness * 1.875 voxels. The new defaults keep it below the relevant feature radius: 0.625 of the minimum TunnelNetwork tunnel radius, 0.300 of Maze corridor radius, 0.469/0.625 of shaft/connector radii, 0.234 of the minimum island radius (0.484 including the 6-voxel island blend), and 0.625/0.938 of slab column radius for floor/ceiling roughness. SurfaceWorld has no radial cave feature, so its ratio is reported against the 80-voxel terrain-relief scale (0.047).

The complete generated name | voxels | METRES | body/level meaning audit is emitted by VoxelForge.Composer.Showcase and includes optional transport fields. The official Unreal blockout guidance (Unreal level blockout guidance) uses a player-sized reference and treats 2-3 m halls / 3-4 m heights as useful starting guidelines; the 2010 ADA Standards provide a 915 mm clear walking-width floor, not a game-space target; and NPS Lehman Cave dimensions show why natural chambers need a wide range rather than one universal volume ratio.

Maze topology is an origin-directed spanning tree, not independent edge percolation. Every non-origin lattice node chooses one hashed parent from the non-zero axes that point toward (0,0,0); Manhattan distance therefore falls by exactly one on every parent step, so every node reaches the root. Optional horizontal and vertical loop rolls are capped at 0.18 * BranchProbability and 0.10 * Verticality; removing them cannot disconnect the tree. A voxel cell evaluates the canonical lower-node +X/+Y/+Z edges in its local {-1,0}³ (2×2×2 = 8-node) window, and each edge checks both endpoints' parent choices. No wider collect region is needed, WorldRadiusVoxels remains 0, and lateral regions remain gated off.

3.1 Module & build

File	Role
../../VoxelForge.uplugin	Plugin manifest. Runtime modules VoxelForge and VoxelForgeCore, plus the Editor-only VoxelForgeEditor commandlet module. Beta.
VoxelForge.Build.cs	Deps: Core, CoreUObject, Engine, GameplayTags, RealtimeMeshComponent, VoxelForgeCore. AVoxelWorld::bUseVoxelForgeCore opts into the Core runtime route; it defaults off.
../../VoxelForgeCore/VoxelForgeCore.Build.cs	C++20 runtime module. Reads Standalone/Core/core_sources.txt, validates one include shim per canonical source, and fails UBT on missing, extra, or mismatched shims. No unity/PCH; private copied implementation stays under vfcore::detail.
../../VoxelForgeCore/Private/Manifest/VFCore_*.cpp	Eighteen one-source UBT shims that include canonical files under Standalone/; they do not copy Core implementation. The API-boundary row includes Core/src/VoxelForgeCore.cpp directly.
../../Standalone/Core/src/CoreNamespacePreamble.h	First include of every Core TU. Forces FP contraction off per compiler (Clang/MSVC/GCC pragmas; unknown compiler = #error) and defines vfcore::fp_contract::selfTest, which World::compile runs before building: a fused multiply-add (e.g. Clang -ffp-contract=fast) refuses world generation. The world depends on contraction (Linux2/Linux3 reports), so never remove either.
../../VoxelForgeCore/Private/ModuleEntry/	Unreal module entry and an isolated CoreMinimal.h shim for the actual engine header.
../../Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h	Standard-library-only public Core API. VOXELFORGECORE_API exports the API from the Unreal module and is empty for standalone builds.
../../Standalone/Core/src/FloatingIslandsInternal.h	Canonical standalone/Core floating-island planner, geometry-versioned field, manifest serializer, influence bounds, capsule-route checks, and thickness audit.
Tools/VoxelForgeTest.ps1	The single guarded test entry point. `-Scenario canonical
Step-3 scale and game validation	step3-scale measures the same 519³ and 259³ six-worker lattices at 12.5 cm. The cached medians are 7.347496 s and 1.169567 s respectively; determinism and brick sound-proof audits pass. step3-game routes in-game generation through the brick evaluator and records tile timings, spawn fill, moving frames, and profile-switch rebuilds. The visible D3D12 run measured tile generation p50/p95/max 3.326/31.045/169.867 ms, full-detail L0 fill 12.369 s for 2,765 tiles, and moving-frame p50/p95/p99/max 4.856/8.922/13.090/80.575 ms. Switching profiles rebuilt 5,815 loaded tiles. Both high-resolution screenshot requests were logged, but the harness found only one fresh PNG and it is a blank pale viewport; no lit comparison capture is accepted. Raw output: Saved/TestHarness/step3_game_visible_final; scale output: Saved/Research/step3/scale/step3_scale_cacheperf_v1.
Public/VoxelForgeModule.h / Private/VoxelForgeModule.cpp	FVoxelForgeModule boilerplate (Startup/Shutdown just log).
Source/VoxelForgeEditor/VoxelForgeEditor.Build.cs / Private/VoxelForgeExploreCommandlet.*	Editor/commandlet-only -run=VoxelForgeExplore; schema-v1 owner-asset export check and BuildHost Core actor tests. -coreworldassembly=PATH supplies a reviewed manifest transiently to -coreworldtest=1; it does not save a data asset. FStandaloneCoreAdapterScheduler runs Core work at 1/8/16 workers; VerifyStandaloneCoreAdapter checks hashes and walkability. Existing bounded render/VF_ walk/OBJ orchestration and research options remain editor/commandlet-only and are not linked by Game/Shipping.
Source/VoxelForge/Public/VoxelSettings.h / Private/VoxelSettings.cpp	UVoxelSettings owns optional canonical world-assembly JSON and its Core digest. The editor file picker plus ImportWorldAssemblyManifestJson imports the reviewed manifest into the cooked settings asset and validates the recipe seed against the effective settings seed.
Source/VoxelForge/Private/VoxelForgeCoreAdapter.cpp	Validates the optional manifest against each resolved SurfaceWorld slot (unique strate index and exact top/bottom chunks), then places canonical world_assembly JSON and its hash in the Core snapshot. Invalid plans fail Core initialization.
Source/VoxelForgeEditor/Private/VoxelForgeRegionEvalExperiment.*	Six-worker lattice drivers for step 2c through step 2f. The original path still compares live GetDensityAt with the editor chunk program. Research modes assign contiguous batches dynamically so surface-heavy work balances across workers; steps 2e and 2f use 4³ proof bricks and stage each evaluated brick before copying contiguous X rows, while step 2d retains 8³. Each skip requires a macro Lipschitz bound plus the complete final-detail supremum; uncertain bricks retain every 12.5 cm detail sample. Timings split classification, point evaluation, and uniform fill; step 2f compares all profiles and hashes workers 1 and 6.
Public/VoxelRedefinedDensityField.h / Private/VoxelRedefinedDensityField.cpp	Two default-off WITH_EDITOR research fields, selected by voxel.ResearchRedefinedDensityField (step 2d) and voxel.ResearchParameterizedCave (steps 2e/2f). Step 2f retains a metre-scaled 2e baseline for its rejection audit. New profiles use strongly jittered, individually rotated elliptical rooms capped against nearest neighbors and curved cubic-Bezier passages with deterministic centerline and width variation along each edge. Room heights and feature rolls vary by cell; ledges, occasional pillars, stalactites/stalagmites, basin floors, and bounded hanging masses remain features. Point and brick detail sampling share independently rotated 96/48/24-sample bands and a smooth ridge response, preserving 12/6/3 m wavelengths at 12.5 cm per sample. The parameterized mesher evaluates the exact field through prepared 4³ bricks and the same sound skip proof in commandlet and editor-game meshing. In-editor and in-game profile changes invalidate and rebuild all loaded tiles. In an editor game with this field enabled, sealed-solid, out-of-layout, and outer-classifier verdicts are declined without changing their console switches.
Private/Tests/VoxelForgeParameterizedGenerationTest.cpp	Separate three-seed functional sweep for the step 2f parameterized field; passage landing air/floor brackets and arrival-to-exit walking routes are checked without changing the live-world tests.
Private/Tests/VoxelForgeRedefinedDensityFieldTest.cpp	Three-seed functional sweep for the research field: authored passage endpoints must bracket open air and solid floor, and each tested strate must have a walkable arrival-to-exit route.
Public/VoxelGeometryHash.h	Header-only geometry digest shared by commandlet export and runtime tile-hash dump; hashes mesh counts and the vertex/normal/UV/color/triangle arrays with the historical CRC order.
Public/VoxelStats.h / Private/VoxelStats.cpp	stat VoxelForge DWORD counters for tile classification, skipping, meshing, operator-stack verdicts, and cave-bail diagnosis. Each Cave Bail * counter names one guard; Cave Bail No Stack counts slots with no buildable stack (no definition, or a degenerate strate).

3.2 Foundational types — Public/VoxelTypes.h (no UClass, everyone includes it)

Symbol	Line	Notes
CHUNK_SIZE (32)	211	Chunk dimensions. 64³ would cut draw calls but makes streaming too bursty; fps is fixed render-side instead.
VOXEL_SIZE (12.5f cm)	213	World scale; one 32³ chunk is 4 m.
EVoxelFace enum	266	6 cube faces.
WorldToChunkCoord	287	World cm → chunk coord (handles negatives via floor).
VoxelMath::IsFiniteFast / IsFinite	24 / 45	Exact IEEE bit test (voxel.FastIsFinite A/B switch).
VoxelMath::DetSinCos / DetSin / DetCos	63 / 181 / 189	The only sin/cos allowed where the world is decided (2026-09-16, 10fd0b6). Fixed double period reduction and float polynomial, no CRT: FMath::Sin/Cos are CRT sinf/cosf, whose FMA3 variant is picked by CPU. Pinned by VoxelForge.Determinism.DetSinCos; -voxel.CrtFma3=0 flips the CRT path to prove it.
SmoothStep01	306	3x²-2x³ — used everywhere for blends.
VOXEL_NOISE_SCALE (1.25f)	313	Rescales UE PerlinNoise3D to ~[-1,1].
EVoxelTileClass enum (Mixed/AllSolid/AllAir)	231	T1.d verdict. Lives here so VoxelDensityOp.h can share it without a UCLASS dependency. A false AllSolid/AllAir is a HOLE; a false Mixed only costs CPU.
FVoxelMeshData struct	365-400	Mesher output (Vertices/Triangles/UVs/Normals/Colors). Plain C++, not USTRUCT. NumSurfaceVertices marks the real isosurface prefix before LOD seam skirts are appended; visibility audit witnesses sample only this prefix. NumSkirtTriangles counts appended render skirts for collision-cook profiling without changing indices. Colors = F6 material masks (R=dominant biome palette, G=slope, B=border blend weight, A=neighbour biome palette). §8.15.

3.2b Density operator stack contract — Public/VoxelDensityOp.h (plain C++, no UHT)

The production density path — GetDensityAt builds and evaluates a stack for every strate of all eight archetypes; there is no other path. See Docs/archive/OPSTACK-PLAN.md for the decomposition.

Symbol	Notes
EVoxelOpRole	The four roles: FieldSource (what the field IS) · Combiner (how fields merge) · DetailModifier (today's UVoxelTerrainOpDefinition) · StructuralPost (spine→vertical seal→passage tube/landing floor→XY edge seal→diff, appended automatically, never author-omittable).
EVoxelOpChannel / EVoxelOpChannelMask	The explicit FVoxelOpSample channel set: Density and Sdf (plus None/All masks). Every density op declares the channels it reads and writes.
EVoxelOpCombine	Replace/Union(min)/Subtract(max)/SmoothUnion/SmoothSubtract/Add/Mask. Sign reminder: negative = solid, so "add solid" is min.
EVoxelOpEffect	Identity/CarveOnly/FillOnly/Both. Conservative: Both is always safe, the wrong one is a hole.
FVoxelOpContext	Chunk-constant inputs. Carries LayoutVersion plus the copied global WorldRadiusVoxels/EdgeSealThickness, so a new op cannot forget them.
IVoxelDensityOp	ChannelReads / ChannelWrites / IsAdditive plus RequiredResources / ProvidedResources, PrepareChunk / Eval, and intrinsic/state-aware EffectOverBox / MaxCarveOverBox / MaxFillOverBox / PropagateSdfOverBox / ClassifyBox / IsXYPure. Box-query methods are never called per voxel; channel/resource declarations are snapshotted during stack assembly.
IVoxelDensityOp::ClassifyBox	⚠️ not source-only. Forcing ops (the vertical seal and XY edge seal inside their proven bands) overwrite the input entirely, which pure direction cannot express.
FVoxelOpSample	The state threaded through the stack: two channels, Density (INTERNAL convention, positive = SOLID, negated to MC once by the caller) and Sdf (standard SDF, negative = inside). ⚠️ min() therefore means opposite things on the two channels.
FVoxelBoxHypotheses + FVoxelBoxSdfInterval + VF_ForceHypotheses / VF_FoldEffect / VF_FoldOp	The fold that turns a stack into an EVoxelTileClass, carrying the SDF interval between independent writers and consumers. Unknown is biased toward Mixed; the mapping and soundness rule are written out in the header.

3.2c Structural primitives — Public/VoxelDensityPrimitives.h

VF_ApplyOriginSpine · VF_ApplyBoundarySeal · VF_ApplyPassageCarving · VF_ApplyXYEdgeSeal — the four world invariants every archetype appends, with landing/floor geometry joined by the manager passage post, moved here 2026-07-27 so the generator and the operator stack share ONE copy. The XY helper is a radial smooth ramp in actor-space and is a true no-op when WorldRadiusVoxels == 0; VF_XYEdgeSealForcedMarginOverBox is the shared sound proof for ClassifyBox and T1.d's global shell skip. VoxelGenerator.cpp keeps same-named static FORCEINLINE forwarders for ApplyBoundarySeal and ApplyOriginSpine; the passage and edge helpers are called directly. Convention: INTERNAL (positive = solid); VF_ApplyXYEdgeSealMC is the output wrapper.

3.2d Operator stack — Public/VoxelDensityOpStack.h + Private/VoxelDensityOpStack.cpp

⚠️ This IS the game's generation path. GetDensityAt builds the stack in its per-chunk refetch block for every strate — all 8 archetypes: Maze, FlatPlain, CrystalChamber, SurfaceWorld, VerticalShafts, FloatingIslands, TunnelNetwork, Underwater. An editor composer candidate or a cooked-season recipe supplies its own stack; otherwise (or if that stack cannot be built) the archetype's native stack is used. A degenerate (zero-height) strate has no stack and is open air. UVoxelStrateManager::UsesOperatorStackForChunk only says whether a slot has a known archetype. ClassifyTile, for CAVE archetypes, builds the strate's stack through the same factory GetDensityAt uses (VF_BuildOpStackForChunk) and folds ClassifyBox. SurfaceWorld and bedrock gaps keep their hand-written proofs — the exact-lattice column test is better than any box bound. Guards, all failing to Mixed: one cave slot per tile, no mixed cave/surface/gap tile, a stack on every chunk the box touches, the params bit-identical across every chunk coord the box touches (blended transition bands make one stack unable to represent the tile — AUDIT §C2), a 27-chunk-coord cap, and the disturbances folded in by hand since they are applied after the stack. Brute-forced end to end by VoxelForge.OpStack.ClassifyTileSoundness.

Symbol	Role	Notes
FVoxelOpStack	—	Ordered move-only list of TUniquePtr entries. Add snapshots channel metadata; PrepareChunk / EvalInternal / EvalMC / ClassifyBox (the fold lets a later forcing post overwrite a dead hypothesis).
VoxelDensityProfile::BucketFromName (Private/VoxelDensityProfile.cpp)	710	Maps operator stack labels to profiler buckets. The sampled game stack attributed 4.86% of resolved leaves here; the linear name scan is now a CRC-keyed candidate lookup with exact string comparison for collision-safe bucket identity.
FVoxelOpStack::ValidateChannelOrder	—	Assembly/diagnostic-only channel/resource DAG validator. It requires prior producers, rejects write-only clobbers and invalid additive declarations, and requires room/shaft/surface state providers before consumers. It permits the one root SDF identity fold used by Maze. VoxelForge.OpStack.ChannelDAG validates all 8 shipping stacks.
FVoxelOpStack::AppendStructuralPost	4	Appends spine → vertical seal → passage tube/landing floor → XY edge seal in that fixed order. An author cannot omit or reorder them. The diff layer is NOT here yet — it still lives in GetDensityAt after the MC negate, with disturbances.
VoxelDensityOps::MakeConstantRockSource	1	Density = BaseDensity. ClassifyBox → AllSolid, exact and free. Shared by TunnelNetwork, Maze, VerticalShafts and bedrock gaps. Class is FConstantFieldSource (one class, two factories).
VoxelDensityOps::MakeConstantVoidSource	1	The same class, negated: Density = -BaseDensity, and ClassifyBox → AllAir — the first source in the plugin that can prove it. FloatingIslands' root; that verdict is what makes a mostly-empty island strate skippable.
VoxelDensityOps::MakeLatticeCorridorSource	1	Maze corridors, SDF channel. Each canonical lower-node/axis edge is open when it is a parent edge in the origin-directed tree or passes a capped loop roll; both endpoints are hashed locally, so adjacent chunks cannot disagree. The source reports its own conservative SDF interval; a later converter supplies its own carve/fill response, so the source is independent of the chosen consumer.
VoxelDensityOps::MakeSdfRoughnessMod	3	Wall roughness in SDF space (Maze/Shafts/Islands variant). TunnelNetwork's density-space roughness is a different op — see OPSTACK-DECOMPOSITION §1.
VoxelDensityOps::MakeSdfCarve	2	SDF → density carve. The same six lines currently copied in three archetypes. Class is FSdfConvertOp(Sign = -1).
VoxelDensityOps::MakeSdfFill	2	The same op with Sign = +1 — FloatingIslands' Density += Fill·Base·2. ±1 multiplication is exact in IEEE-754, so the carve path is bit-for-bit unchanged by the generalisation.
VoxelDensityOps::MakeSlabVoidSource	1	Floor surface + ceiling surface → void field. XY-pure since §3.1, which is what gives it an exact ClassifyBox with no sampling: the proved FBM supremum 1.5 bounds both surfaces into known Z bands. Serves FlatPlain and CrystalChamber.
VoxelDensityOps::MakeGridColumnMod	3	Infinite-height cylinders on a world grid, 3×3 cell memo. Adds solid only ⇒ FillOnly when a column reaches the box, Identity otherwise — and that Identity is what lets the source's AllAir verdict survive.
FShaftFieldSource (internal)	1	VerticalShafts' memoised inner 3×3 shaft/capsule source. Each rebuild uses a direct-indexed wider halo (default 9×9 tree-emission / 15×15 roll) so every emitted shaft has its complete 5×5 parent window plus capsule reach; the nearest strictly more-central shaft in ±2 cells is the deterministic parent, with a deterministic lower-origin ±3 fallback and a direct (0,0) spine fallback. Thus every shaft has a provable path to the spine. Existing VoxelHash::Pair/Spacing*1.6 links remain additive texture/loops. Tree and spine capsules use a radius strictly above `sup
VoxelDensityOps::BuildSlabStack	—	6 ops, no branch on archetype: FlatPlain and CrystalChamber differ only in defaults.
FSurfaceColumnSource (internal)	1	The bridge between the two spaces: consumes the ground + sky-cap height stacks and produces density. IsXYPure() false — the heights are XY-pure, a distance to them never is. Owns a six-box spatial LRU of direct-indexed per-column cells, keyed by PrepareChunk on (StrateBottomWorldZ, LayoutVersion, Seed, ParamsFingerprint) so it is shared down the whole vertical strate stack, exactly like GSurfColCache. Six 81×81 boxes preserve hot columns across interleaved regions at roughly 0.79 MiB TLS before padding (more memory, fewer whole-cache recenter/recompute misses). Fractional XY remains direct-compute. FSurfaceColumn is deliberately trivial: all five outputs are written before the cache's Computed publish, so removing its default initialization removes a TLS constructor leaf without changing a value.
VoxelDensityOps::BuildSurfaceStack	—	SurfaceWorld, complete: column + overhang + 4 structural, plus biome blending when PerBiomeParams is non-empty. Takes ownership of an IVoxelBiomeField.
VoxelDensityOps::BuildVerticalShaftStack	—	9 ops, and three are Maze's reused unchanged (ConstantRock, SdfRoughness, SdfCarve) with different tuning (freq 0.1 vs 0.12, window rough+4 vs R+rough+2). Passes the runtime spine radius into FShaftFieldSource, which mirrors the generator's connector-only origin endpoint and roughness-safe spine capsule. The measured proof of OPSTACK-PLAN §2.5's reuse claim.
FRoomGraphSource (internal)	1	TunnelNetwork's SDF spine. CALLS BuildChunkCache/EvaluateSDFCached — does not transcribe them: that is where §8.4's two-region discipline lives and a copy would fork it. Owns the cave warp (scope = this op alone; pits/chimneys read unwarped coords, which is why no FRAME op was needed). Its cache key adds a params CRC + LayoutVersion; the original lacked them until AUDIT §C2 was fixed (2026-07-28) and now carries them too. The source now publishes a conservative SDF interval through the box fold; it does not answer for the carve or detail stack. It builds the cache for the queried box into a second per-worker cache (never FState::Cache), and the interval uses the same cull/threshold disjunction as the per-voxel source: a primitive is harmless when it fails its cull or its own SDF stays ≥ T+K; T = max(3·SDFBlendRadius, WormNetworkRange), with −K slack for the final SmoothMin. Rooms, tunnels, pits and chimneys are bounded in their respective coordinate frames; warp dilation uses the proved `sup
FWormFieldSource (internal)	1	Fielded 3D-noise threshold carve, masked by the propagated SDF interval (reads InOut.Sdf after pits/chimneys). Its state-aware box response is Identity only when the preceding interval proves Sdf ≥ WormNetworkRange; otherwise it reports its own CarveOnly direction and bound. With no preceding SDF source it remains conservative, so it cannot inherit a verdict from an unrelated future writer.
VoxelDensityOps::BuildTunnelNetworkStack	—	COMPLETE, 20 ops — the biggest port in the plugin (~1080 lines), done in three stages: SDF spine (A) → the twelve detail modifiers of 4b–4h (B) → the per-room op override (C) → 4 structural posts. Serves TunnelNetwork and Underwater from one builder. Operator order is the original's, line for line. FFloorBiasMod is an independent additive term on the density accumulated before it; it is kept late because it does not undo the roughness delta. The requested 4b→4h fuse is not semantically justified.
FCaveRoughnessMod (internal)	3	STEP 4b, density space — a different op from MakeSdfRoughnessMod: two octave sets, optional domain warp, four noise types, an anti-fill clamp inside definite air, quadratic fade. ⚠️ Reads STRATE params, not the per-room copy — the original's shadow is declared after step 4b. Eleven of twelve modifiers read the room copy; this one does not.
FCaveTerraceMod (internal)	3	STEP 4c. The only modifier that re-queries the SDF (Z±1, through FRoomGraphSource::ProbeSdfUnwarped) for its horizontality gate — which is why the room source's cache is exposed at all. ⚠️ Those probes use unwarped X/Y and raw Z although the field was evaluated warped: transcribed as-is, see OPSTACK-PROGRESS.
FLayerLineMod / FRibbingMod (internal)	3	The same sine along Z: cubed and subtracted (grooves) vs quarter-phase-shifted, squared and added (ribs). CarveOnly / FillOnly — two of the few detail modifiers that keep a usable direction for the fold.
FCaveOverhangMod / FCaveCliffMod / FScallopMod (internal)	3	STEP 4c. ⚠️ The cliff's own comment promises a sampled vertical gradient; the code uses a Z-stretched Perlin as a proxy and samples nothing. Ported as written — fixing it would change the world.
FCaveArchMod / FDomeMod / FPinchMod / FFloorBiasMod (internal)	3	Room-relative: they read FRoomGraphSource::GetNearestRoomIdx() and the cached room. Their gate is SDF < SDFBlendRadius, not the shared ·3 one — they live in the cave's void, not its wall.
FRoomColumnMod (internal)	3	STEP 4d, and not MakeGridColumnMod: it walks SDFCache.Columns, pre-baked per room. ⚠️ It has no strate parameter at all — neither the bake nor the loop reads FStrateGenerationParams::ColumnDensity. Columns exist only through a Column terrain-op asset in the strate's pool, and the only way to prove they fired is to look at SDFCache.Columns.Num().
FRoomGraphSource::LocalParams()	—	The per-room op override (DECOMPOSITION §2's "no clean home"). Strate params + the nearest room's UVoxelTerrainOpDefinition::ApplyTo, memoised once per voxel and read by eleven modifiers. One op owns the shared state, the rest read it — the same pattern as FOverhangShelfMod ← FSurfaceColumnSource. The detail consumers use the propagated interval for their shared near/far gate; unknown remains conservative, and the per-room parameter override is never used to claim an unproved box identity.
FIslandBlobSource (internal)	1	Hash-placed tapered flat-top blobs, SmoothMin'd, in a domain-warped XY frame (the warp stays inside the op — see the deviation note vs DECOMPOSITION §7). SDF channel only. The source publishes an interval covering the full authored radius envelope (max(MinRadius, MaxRadius)), the two-axis warp·√2 envelope, top surface and SmoothMin dip; the fill converter makes its own decision. No lower Z bound exists — a hairline thread of matter hangs below each island down its axis, so only the TOP may reject.
VoxelDensityOps::BuildFloatingIslandStack	—	8 ops, and the stack runs backwards: void source + fill instead of rock source + carve, using the same classes with the opposite sign. Only the blob source is new. Reuse by inversion — a stronger result than reuse by identity, since it says the abstract axis (the density sign) is the right one.
VoxelDensityOps::BuildMazeStack	—	The 8-op Maze stack (4 structural posts included). Its lattice source mirrors the origin-directed tree + capped loops and rebuilds the 2×2×2 lower-node window once per cell; the per-voxel loop only evaluates cached capsules. If this ever becomes one op, the refactor failed its own test (§2.5). Callers must skip it on a degenerate strate (top−bottom ≤ 0): the stack has no such early-out by design — VF_BuildOpStackForChunk refuses it and GetDensityAt returns air.

Lateral region parent (Tier 4d)

VF_RollStrateRegionManifest rolls a deterministic count of 1–3 regions and gives each region its own native parameter vector and, for structure candidates, its own recipe. VF_QueryStrateRegion assigns XY through jittered VoxelHash::Cell sites on a 256-voxel lattice; the pure query is keyed by (WorldXY, Seed, StrateIndex) and the worker-side FVoxelStrateRegionPartitionCache prepares the site window and integer query grid once per chunk. FLateralRegionBlendOp evaluates the primary region core and, inside a 24-voxel band, the nearest different-region core, then lerps density (not native parameters). The four structural posts are appended once to the parent after the blend. Count==1 uses the ordinary one-stack path and is covered by native and recipe bit-identity oracles. ClassifyBox proves a single-region/non-band box only from a conservative Lipschitz gap bound; otherwise it folds every region and returns Mixed on any disagreement or unknown. The runtime/editor override reads the immutable manifest per chunk; it never searches lattice seeds per voxel. The dedicated VoxelForge.Composer.LateralRegions test reports cross-boundary brute-force box samples, interior-vs-band timing, 16 opposite-region passage-mouth trials, and a saved preview.

3.2e Height-space operators — Public/VoxelHeightOp.h + Private/VoxelHeightOpStack.cpp

⚠️ Feeds nothing yet — built and exercised only by VoxelForge.OpStack.SurfaceHeightEquivalence. A SECOND op family, and it exists for a reason worth knowing: SurfaceWorld's terrain ops (cliff / terrace / layer lines / beach) read and write an altitude, not a density. They have no input Z (they produce one), are XY-pure (once per column, not per voxel), and touch neither density nor SDF — so they do not fit IVoxelDensityOp at all. Forcing them in would need a per-voxel channel for what is a column property, or one opaque op (OPSTACK-PLAN §2.5's failure mode). Same lesson as §0.1 one step further: some things are not another channel, they are another space.

Symbol	Notes
FVoxelHeightSample	Two channels: Height (voxel Z) + Relief (the original's M). Relief is produced by the structural source and consumed by the terrace gate — threading it beats resampling it.
IVoxelHeightOp	Eval(X, Y, FVoxelHeightSample&). No IsXYPure (XY-purity is structural here — there is no Z to wrongly put in), no PrepareChunk (already per-column). MaxDisplacement() is the conservative vertical bound for a future heightfield ClassifyBox.
FVoxelHeightStack	Move-only, like FVoxelOpStack. EvalHeight / EvalSample / MaxTotalDisplacement.
VoxelHeightOps::MakeStructuralHeightSource	Continents + mountains + detail under a warp frame. Hands back a non-owning pointer so the cliff mod can resample it.
VoxelHeightOps::MakeCliffHeightMod	Slope-gated steepening; 4 resamples of the structural field (never the modified height — that would feed back).
VoxelHeightOps::MakeTerraceHeightMod	Relief-gated plateaus. The * Relief is the original's * M.
VoxelHeightOps::MakeLayerLineHeightMod / MakeBeachHeightMod	Sine bands; flatten toward the water line. Both have exact MaxDisplacement.
VoxelHeightOps::BuildSurfaceHeightStack	5 ops in ComputeSurfaceTerrainZ's order — structural → cliff → terrace → layer lines → beach. Order is not negotiable.

3.3 Chunk identity

Tile identity lives in FVoxelTileKey (VoxelTypes.h:326).

3.4 Settings — Public/VoxelSettings.h

UVoxelSettings : UPrimaryDataAsset — the single tuning asset assigned on AVoxelWorld.

Group	Fields (line)
Streaming	ViewDistanceXY=16, ViewDistanceUp/Down=5, MaxConcurrentTasks=16, MaxMeshAppliesPerFrame=4, PawnCollisionRadiusChunks=1 (defaults — actual values live on the data asset; the collision radius is independent from the render clipmap)
Clipmap	ClipRadius, MaxClipLevel=5, FullResClipLevels, CoarseTileCells, RenderDistanceChunks=768 (measured ship defaults; custom horizontal reach: the outermost shell keeps generating until it covers this many chunks; 0 = off), skirts, LODOctaveDrop (T2.b octave drop on coarse tiles — 0 = off/byte-identical). Existing serialized data assets retain their authored values until deliberately migrated.
World bounds	WorldRadiusVoxels=8192 and EdgeSealThickness=64 (actor-space XY radial shell; radius 0 = true legacy no-op)
Lighting	bEnableDensityVolume=false + DensityVolume* tunables (§3.11 density clipmap / mini-sun shadows). The disabled default creates no volume object, fill thread, uploads, or Tick updates; terrain MIDs receive neutral VolP0..4=black, VolP5=(0,25,0) (z enable is 0), VolP6..9=black, and VolTex0..2=null.
Rendering	VoxelMaterial (377)
Strates	Optional cooked Season; effective seed/spine/radius/season accessors read it when assigned. Otherwise Seed, CurrentSeason=1, StratePool, FixedStrates, and TotalStrates=10 retain the authored path.
Carving budget	MaxModifications=0 (449), MaxBrushRadius=15 (454), MaxTotalVolume=0 (459). 0 = unlimited.

3.5 World orchestrator — Public/VoxelWorld.h + Private/VoxelWorld.cpp

AVoxelWorld : AActor — owns everything, drives streaming. Also FChunkResult struct (VoxelWorld.h:99) = async task payload (coord, chunk, meshdata, LOD, Epoch, request timing, worker-built stream geometry counts/bytes, desired-set epoch and obsolete/cancellation state). Explicit visual-gap audits may add 24 sparse pre-skirt surface witnesses per non-empty tile; normal streaming does not capture or retain them.

Owned objects (UPROPERTY): Settings, Generator, Mesher, StrateManager, DiffLayer, ContentManager, AtmosphereManager, DensityVolume (VoxelWorld.h:188-228). Storage: LoadedTiles (TSet), TileComponents map + TileComponentPool (VoxelWorld.h:260-308), the four MPSC result queues CriticalProcessQueue / EditedProcessQueue / NearProcessQueue / ProcessQueue, and PendingTiles (TSet) (VoxelWorld.h:908-912). Async state: bShuttingDown, ActiveTaskCount (atomics), GenerationEpoch, and the game-thread PendingTileCancellation map whose per-request atomic flags are read-only on workers. S5 assigns request and worker-start ordinals to each tile, preserving epoch, resident-at-request, priority, queue-wait and build timing in the opt-in startup trace. All four result queues remain MPSC; EndPlay still waits for workers and drains every queue. S8 adds StartPendingCoreRegionCompile: by default voxel.CoreRegionConcurrentAdmission=1 lets LoadCoreTile admit keys independent of a pending region page; 0 restores the global compile gate. voxel.StreamingResultBacklogCap=256 limits queued result payloads + active tile tasks + held prequeue results without folding completed results back into worker-slot admission; 0 disables it. Core region pages are immutable shared owners while readers are active. See §8.29 and §3.15.

⭐ Espace ACTEUR / ACTOR SPACE (2026-08-17). Le champ de densite est defini en espace acteur : (0,0) est l origine de l acteur AVoxelWorld, pas celle du monde Unreal. WorldToLocalCm / WorldToLocalVoxel / LocalVoxelToWorld sont la SEULE frontiere autorisee entre coordonnees Unreal et coordonnees voxel. Invariant verifiable par grep : aucun / VOXEL_SIZE applique a un parametre nomme World* hors de ces trois fonctions. Avant cette date le plugin etait a moitie actor-relative (biome/deco/eau/volume/debug convertissaient ; le centre de streaming, les ancres, les 6 entrees carve/fill, GetStrateAtPosition et UVoxelAtmosphereManager::UpdateForPlayer ne le faisaient pas) — ce qui ne marchait que tant que l acteur restait a l origine. ⚠️ TRANSLATION SEULEMENT : tuiles, ClassifyBox, fenetre clipmap, culling et distance de streaming supposent tous des boites alignees sur les axes du MONDE. Une rotation ou une echelle non unitaire casse cette arithmetique structurellement — BeginPlay loggue une Error si on en met une.

Method	.cpp line	Role
AVoxelWorld() ctor	176	Enables Tick.
RegenerateAllChunks()	530	Bumps epoch, unloads all → Tick reloads. CallInEditor button.
ValidateDeterminism()	—	F2 CallInEditor button (PIE): re-samples boundary points under left- vs right-chunk cache warm-ups + a same-alignment repeat; any non-zero delta = window-invariance regression (§8.4). Run after every "bit-identical" hot-path refactor.
GetMaxConcurrentTasks()	—	T2.d — asset MaxConcurrentTasks capped to logical cores − 2 (all three budget checks use it).
GetActiveGenerationTaskCount()	—	Normal mode returns the existing pending count. With voxel.Step1PrequeueVisibleLOD0>0, completed held results are excluded from active worker admission so a full render corpus can be generated before the upload release.
StartPendingCoreRegionCompile() / LoadCoreTile()	—	Background Core region-page compile. voxel.CoreRegionConcurrentAdmission=0 is the global-stop control; default 1 withholds only keys in the pending/in-flight region sets. Independent tiles can proceed. Core pages use immutable shared_ptr ownership under a separate shared mutex. §8.29.
EnqueueStreamingResult() / IsStreamingResultBacklogCapped()	—	Central result accounting for all four MPSC queues. voxel.StreamingResultBacklogCap=256 caps queued results + active tile tasks + held prequeue results; 0 disables the cap. This bounds result-payload growth separately from worker-slot admission. §8.29.
PostEditChangeProperty	1000	Editor live-edit hook.
OnObjectModifiedInEditor	1022	Regenerates when a strate asset is edited (if bLiveEditStrates).
EndPlay	1118	Sets bShuttingDown, waits for ActiveTaskCount→0, unbinds delegate.
BeginPlay	1576	Constructs Generator/Mesher/StrateManager/DiffLayer, wires services, seeds. Creates UVoxelDensityVolume only when bEnableDensityVolume is true; otherwise seeds terrain MIDs with the disabled neutral parameters and null volume textures. Explicitly parses command-line profiling switches and the voxel.TestFullResClipLevels measurement override because headless module CVar startup ordering can otherwise leave the authored/default value active.
RebuildStrates	724	Reinitializes the volume only when enabled; when disabled, shuts down and clears any existing volume and reapplies neutral terrain material params.
Tick	5715	UpdateChunksAroundPosition(player, heading) + ProcessPendingChunks(); the clean LOD0 latency summary is flushed at EndPlay. Density-volume update/material work is inside the non-null volume branch, so it is absent when disabled.
GetPlayerPosition	4831	Pawn position or zero.
AdvanceHeadlessDigMotionTest / RecordHeadlessDigMotionFrame	3060 / 3217	Explicit -voxel.TestDigMotion=1 repro: optional near digs, then repeats underfoot digs and samples Generator->GetDensityAt immediately after each edit, on its first subsequent simulated frame, and on every following observation frame. -voxel.TestDigMotionFieldOverride=1 is a measurement-only prototype that clears CurrentFloor and switches CMC to falling when the sampled post-edit density is air; it is inactive by default. The test counts false support, false air and downward velocity beyond one gravity step. -voxel.TestDigMotionUnderfootDigCount is clamped to 1–100; -voxel.TestDigMotionUnderfootIntervalSeconds=0 performs per-frame rapid edits. The accompanying gap audit is scoped to the dig session.
MaybeFinishHeadlessStreamingTest	—	The existing voxel.TestExitSeconds diagnostic emits VoxelForgeStreamingExitDiag at most every 30 elapsed seconds, including threshold and early-return test flags; no output when the timer is unconfigured.
UpdateVisualStalenessAudit	5034	Test-only camera-frustum coverage audit: tracks up to 24 real pre-skirt isosurface points per visible component, then counts frames where no visible tile component covers a previously visible, still-desired point (excluding edited bounds). voxel.TestVisualGapInjectEarlyHide=1 hides a valid component for three frames and must be caught. voxel.TestGapAuditLegacyHandoff=1 restores old handoff culling for A/B baselines.
ProcessPendingChunks	7435	Drains CriticalProcessQueue, EditedProcessQueue, NearProcessQueue, then ProcessQueue; applies under the authored 4-mesh/2 ms budget during normal play and the bounded shared startup budget (12 meshes/14 ms) until the initial desired set and walkable ring are ready. voxel.StreamingStartupApplyBoost=0 restores the authored budget. startup_apply_config traces the actor-read CVar and both budgets; startup_apply_budget records activation/end. Reads per-request cancellation before removing its map entry, traces stale/obsolete/aborted discards with epoch and ordinal, then applies via ApplyTileResult. Step 1 prequeue still releases here and emits VFStep1UploadCorpusReleased.
ApplyTileResult	—	Shared game-thread apply for one FChunkResult (async drain + sync carve): discards stale generation epochs and keys no longer desired, marks loaded, ingests capture, EMPTY releases the tile's existing component (a re-gen can flip content→empty on band change — old geometry must not linger), else ApplyMeshToTile. Returns true iff a visible mesh uploaded (counts the budget). Doesn't touch PendingTiles (caller's).
FVoxelStackSampler / FScopedVoxelStackRegistration (VoxelStackSampler.h/.cpp)	—	Diagnostic raw stack sampler, off by default. A sampler thread captures registered generation workers' stacks (CaptureThreadStackBackTrace) every N µs and tags each with the tile's LOD. It writes bounded raw PCs to CSV plus a symbolization-free summary under Saved/; symbol resolution is deferred until after process exit so the measured process never initializes/calls DbgHelp for this diagnostic. Lifecycle teardown is serialized and registration TLS is session-tagged. Registration is per tile TASK in LoadTile (and the export's tasks), never per sample; disabled costs one relaxed atomic load. Game -voxel.SampleStacks=<us>, commandlet -samplestacks[=us].
Room-cache performance (2026-09-13): VF_FindPlayerFitPointForRoomMemoized / GPlayerFitMemo (VoxelCaveMorphology.cpp), voxel.TileCacheWindow + VoxelGenLOD::TileOriginVoxels/TileCellsPerAxis (VoxelGenerator.h), FChunkSDFSpatialIndex	—	Player-fit memo: exact 97-word key, process-wide, voxel.PlayerFitMemo. Tile cache window: the room cache covers the requesting tile's footprint plus a fixed collect margin. It is set via TGuardValue in GenerateMesh/classify, and is window-invariant by construction (the margin does not grow with the tile). LOD-gated: fused path at LOD ≥ voxel.TileCacheWindowMinLOD (3), op-stack at LOD ≥ voxel.TileCacheWindowOpStackMinLOD (4); lower LODs keep the 4-chunk worker window, because the tile window slowed LOD0 evaluation ~6%. Strates whose authored terrain ops exceed the proven 256-voxel extent (or are malformed/unloaded) fall back to the legacy window (VF_ComputeTerrainOpEnvelope). voxel.SpatialIndex is -1 auto (off at fused LOD0, on elsewhere), 0 or 1. Spatial index: ordered XY buckets over cache primitives, exact rejection. The static_assert in VoxelStrateTypes.h ties VF_STRATE_PARAM_FIELDS to FStrateGenerationParams (83 fields + 8 B padding).
GenerateTileResult	—	Shared worker-side gen for one tile (async LoadTile task + sync SyncRemeshTile): sealed-solid proof, out-of-layout air proof, optional ClassifyTile (T1.d) + exact validation only when voxel.OuterClassifierMode=1; default 0 since 2026-09-13 → GenerateMesh → BuildTileStreamSet; records vertex count and resident stream allocation bytes for the horizon trace. Density capture is requested only when the enabled volume can use that L0 tile; with the volume off, neither proof nor classifier is bypassed for capture. The explicit gap audit may request sparse surface witnesses, otherwise none are retained. Near the player it can capture the exact pre-edit L0 lattice into the result; a cache-hit sync remesh passes an edited per-call shared lattice. Reads Generator/Mesher only → safe on a worker or the game thread; fills FChunkResult, no enqueue.
RecordTileHash / WriteTileHashDump	—	Headless -voxel.TileHashDump=<absolute path> parity instrument. Records the exact FVoxelMeshData used by the streaming result, including empty/classified tiles, then writes sorted absolute tile keys, LOD step/cells, content-band limits, settings digest context, and the shared VoxelGeometryHash at EndPlay.
SyncRemeshTile	—	INSTANT DIG: level-0 same-frame re-mesh on the game thread. Uses PreEditDensityCache when the tile is resident in the bounded local cache, replays the current DiffLayer over that exact procedural lattice, then meshes/applies inline so a carve is visible THIS frame. A cache miss uses normal generation; it captures the unedited lattice if the tile needs meshing, while uniform-tile proofs remain enabled.
PreEditDensityCache / VoxelForgePreEditDensityCache::BuildEditedGrid	—	Per-world cache of the pawn's current L0 tile: exact 35³ pre-edit samples, max 171,500 bytes. It is pruned when the pawn crosses chunk boundaries and cleared on RegenerateAllChunks. BuildEditedGrid snapshots touched diff chunks once and reproduces GetDensityAt's final pre-edit - EvaluateMods operation before the per-call shared-grid mesher path.
UpdateChunksAroundPosition / GetGenerationAdmissionCount	10990 / 10971	Shared Core/legacy scheduler. Builds the desired set and delta-culls leavers; admits the occupied/support tile plus collision-required LOD0 tiles in the pawn's 3×3 XY ring as CollisionCritical. S5 coarse-first admission stays opt-in (voxel.StreamingCoarseFirst=1). voxel.StreamingDynamicNearReserve=1 is now the default: it keeps the authored near reserve while moving or until the stationary walkable ring is ready, then makes those slots available to coarse work. Admission counts submitted queued/running tasks, not completed results waiting in the MPSC result queues; voxel.StreamingLegacyPendingResultCap=1 restores the old PendingTiles-based cap for the negative control. PendingTiles still lasts through game-thread apply for duplicate suppression and result bookkeeping. The clipmap stays non-overlapping and load-before-unload / TransitionHold reconciliation remains authoritative. Standalone has no mirror of this actor scheduler. §8.10 + §8.26–8.28.
AdvanceHeadlessCollisionGateStressTest / ObserveHeadlessCollisionGateStressTest / MaybeFinishHeadlessCollisionGateStressTest / MeasureHeadlessCollisionGateStressTerrain	—	Explicit -voxel.TestCollisionGateStress=1 harness only. The normal spawn-height cvar offsets from the measured density surface; voxel.TestCollisionGateStressDeepDrop=1 carves a process-local box shaft from above the top to just above the floor tile, extending along the post-landing route so the pawn does not run into the shaft sidewall, temporarily raises only the transient test DiffLayer brush-radius allowance for that fixture, removes only the local pawn's redundant streaming anchor for this isolated repro, proves every sample in two complete outside-ring level-0 tiles is air before seeding their known-empty status, prewarms the known-empty in-ring column, and asserts that the support walk reaches the in-layout floor outside the aligned level-0 render ring before the pawn drops. The log reports whether the fixed gate retains that otherwise out-of-ring target. Other streaming anchors remain active. The fixture rejects a target or floor outside the layout, a non-air empty-tile proof, or a floor inside the aligned level-0 ring. The GetDensityAt column at capsule feet defines the local air/solid surface; the deep-drop column crossing is cached after its first exact scan. Each frame records actor position, velocity, direct foot tile and gate support readiness, gate state, signed feet clearance, and a ≤0.5-voxel sweep between positions. PASS requires no measured clearance below −5 cm; deep-drop gate-on also requires horizontal travel during a hold. Result logs include the terminal density column, first crossing below spawn height, hold count/time, and gated horizontal progress.
BuildDesiredTiles	6482	Builds DesiredSorted+DesiredStamped (player clipmap shells), then adds streaming anchors and the pending player's collision-only support column before the leaver sweep. It orders from the true local pawn position and builds CriticalDesiredTiles for the unresolved support target, occupied/support and heading tiles. Also rebuilds DesiredTransitionDescendants (ancestor → desired descendants, including face/edge-touching replacements) for the reconcile pass.
CollisionGateDesiredTiles / RequestCollisionGateSupportTile	5062	Retains an unresolved support target and up to three level-0 tiles below it across desired-set rebuilds. The additional keys are hidden collision-only tiles, queued ahead of ordinary streaming, and pruned once resolved or outside the active column.
IsPawnCapsuleOverlappingPendingFloor / UpdatePawnCollisionGate	4987 / 5195	Uses the current-to-next-step swept capsule bounds to start a hold only when the pending support tile is about to intersect the pawn. When current support is ready, it also requests and checks the next-step support tile before a horizontal boundary crossing. Character holds use gravity-free MOVE_Flying with horizontal input live, then restore movement mode, gravity, and saved downward speed when collision is ready.
VoxelClipmapDesiredTiles::Build / AlignedRingBounds (Private/VoxelClipmapDesiredTiles.h)	—	The pure clipmap selector. Every finer ring snaps outward to a child-pair boundary (AlignedRingBounds, alignment 2; the outermost ring needs none), so a coarser tile is wholly inside or wholly outside the finer ring: no two desired tiles of different levels overlap (an unaligned 7-wide odd ring leaves one half-covered coarse tile per axis side, drawn over the fine one: 635 pairs at the owner config). Cost: LOD0 ring 343 → 512 tiles. Guarded by VoxelForge.Streaming.ClipmapDesiredTilesNoOverlapCoverage. Anchor tiles appended later are outside this guarantee.
VF_AppendTouchingAncestors / ReconcileReadyTransitionVisibility / LogReadyTransitionVisibilityMeasure	5041 / 7939 / 5599	Boundary-safe visibility handoff: a desired tile sharing a closed face/edge with a retired tile counts as a replacement, so the old surface remains visible until the boundary neighbor is loaded. NeedsHold uses the same contact-inclusive readiness. Contact does not imply volumetric overlap; overlap audit remains strict. Indexed (dyadic ancestors + DesiredTransitionDescendants, visible retired tiles collected once per pass): moving p95 32 ms → 0.31 ms. voxel.MeasureReadyTransitionVisibility=1 logs per-frame game-thread time, sampled component counts, and 128-component count buckets.
IsTileCollisionDesired / ReconcileCollisionDesiredTiles / ApplyMeshToTile	—	Collision is independent of rendering: the player's level-0 PawnCollisionRadiusChunks box, each anchor's authored box, and the gate's retained support column union into CollisionDesiredTiles. Level-0 meshes outside that set remain visible with NoCollision and do not submit an RMC cook. Entering the set queues a remesh for already-loaded render tiles; leaving disables their component immediately; a late cook cannot restore readiness outside the set.
VoxelCollisionDesiredTiles::AddBox (Private/VoxelCollisionDesiredTiles.h)	—	Shared pure box selector for the pawn collision radius and anchor extents; tested for pawn radius bounds and an independent anchor box.
RequestCollisionGateSupportTile / UpdatePawnCollisionGate	—	The gate submits the pawn's level-0 support tile immediately as CollisionCritical, even before the first desired set exists, and retains up to three more support-column tiles across desired-set rebuilds. A previously rendered no-collision tile is remeshed before the gate can accept it. The gate holds only at swept contact, keeps horizontal input live, has no timeout, and restores movement mode, gravity and saved fall speed on release.
AddAnchorDesiredTiles	—	§9.3 multi-anchor: folds each FVoxelStreamingAnchor's thin level-0 box (XYRadiusChunks/ZBelowChunks/ZAboveChunks) into the SAME desired set and the independent collision set, so AI/remote players keep collision loaded around them; delta cull releases them on move/unregister. §9.4: a tile only a CollisionOnly anchor wants (clipmap didn't stamp it) → CollisionOnlyTiles → hidden at apply. Zero cost when no anchors.
ReconcileAnchorTileVisibility	—	§9.4: after each rebuild, toggle SetVisibility on ALREADY-LOADED tiles that flipped render↔collision-only (diff CollisionOnlyTiles vs prev — bounded, no O(loaded) scan; unhide only if still desired). No-op without CollisionOnly anchors.
RegisterStreamingAnchor / UnregisterStreamingAnchor	—	BlueprintCallable §9.3: add/remove an actor as a streaming anchor (EVoxelAnchorPolicy CollisionOnly/FullVisual + XY/ZBelow/ZAbove box). Idempotent; forces a rebuild next Tick. §9.4: CollisionOnly tiles cook collision but are hidden (no draw/VSM) unless the player clipmap wants them too.
LoadTile / LoadCoreTile	9033 / 11633	Budget check → background generation; RAII task guard. Both paths preserve Epoch, desired/modification epochs, cancellation state and MPSC result routing. Requests receive a monotonic request ordinal; workers assign a generation-start ordinal. VoxelStartupTrace joins those with priority, resident-at-request, queue wait, worker build, result wait, apply time and discard reason. Legacy LoadTile retains its classify/mesh and strate-band behavior; Core delegates to the resolved immutable snapshot. EndPlay still drains workers/results. §8.10.
VoxelStartupTrace::RecordRequest / RecordTile	—	Opt-in JSONL via -voxel.StartupTraceFile=...; -voxel.StartupTraceUntilEndPlay=1 keeps tracing through movement, otherwise it stops at initial settle. Each request is keyed by epoch and ordinal; applied tile records add worker-start order, priority, queue/build/apply timings. Discard events identify stale epoch, obsolete, no-longer-desired and aborted results.
UnloadTile	—	Clears tile state; marks any matching generation request obsolete without removing its pending slot, so a late result cannot clear a replacement request; the component is PARKED in the pool (T2.c), not destroyed.
ApplyMeshToTile	9838	Upload geometry. One component per tile (clipmap keeps count low; supersedes the old region batching); worker-built streams (T1.f) → CreateSectionGroup(MoveTemp). Reuses the component's existing URealtimeMesh (no per-apply mesh alloc). F17: two polygroups (0 ground / 1 sky-cap, per-triangle class from the mesher) → RMC auto-section per non-empty group; slot 0 = override/default material, slot 1 = CeilingMaterial (fallback ground); config gated by FChunkResult::bHasGroundTris/bHasCeilingTris. Takes FChunkResult&; strate lookups clamp Z into Result.BandChunkLo/Hi (strate content cut) — ground at clamped bottom chunk, cap at clamped top (mid = gap fallback). Collision level-0 only (T1.c) both groups; shadow per SECTION: ground casts at level≤1, cap never. Ordinary same-tile re-cooks retain the installed body while it is valid. A carve intersecting the pawn's current support tile and capsule bounds suppresses that old body until the replacement cook is installed. voxel.ProfileCollisionCookStages reports generation/apply waits, combined RMC time, completion hops, triangle/skirt counts and collision settings. With voxel.Step1PrequeueVisibleLOD0>0, logs apply frame and waits for GetLastRenderTime to advance for first-visible frame; voxel.Step1UploadDisableCollision=1 isolates render upload. Routes each terrain base through shared MIDs; disabled volume MIDs bind neutral VolP* and null VolTex*. §9.4: SetVisibility(false) when the tile is in CollisionOnlyTiles (anchor-only, hidden — collision still cooks). §8.10 + ARCHITECTURE SurfaceWorld row.
HandleRealtimeMeshCollisionBodyUpdated / HandleTileCollisionCookComplete / PollStep1SupportSweepProbes	6964 / 7192 / —	Correlate RMC body-install event and collision-future completion. voxel.ProfileCollisionCookStages=1 logs worker queue/gen, result wait, apply/upload/config submission, RMC submit→body update, body event→future, future→game-thread hop, submit frames, pending VoxelForge cooks, priority, collision flags, and triangle/skirt totals; it also reports mesh-generation-end→ready. voxel.Step1CollisionProbe=1 sweeps the pawn capsule against the exact component pointer, logs both the first hit and whether it is the target body, and checks every body in the captured support cohort. RMC's end-frame dequeue, async worker start, geometry extraction and core cook remain inside the external plugin and are not individually timestampable from this module.
FVoxelStep1CoreCookWork / FStep1CoreCookPoolOwner	—	Optional voxel.Step1CoreCookBenchmark=1 captures the pawn's first exact radius box (normally 27 L0 tiles) on the game thread, tags those results through worker meshing, and sends their streams plus any out-of-box critical support tile to a dedicated one-thread high-priority pool. It records queue delay, extraction and core cook separately. One approximately 4k-triangle cohort stream is retained and replayed after Step1PauseGenerationAfterSeconds pauses generation. The benchmark sidecar is not installed as the tile BodySetup and is disabled by default.
Step 1 measurement CVars	—	voxel.Step1GenerationCap=-1 uses the normal cap (0 pauses, positive values cap worker tasks); voxel.Step1ExitAfterFrames=0 disables a frame-counted clean test exit; voxel.Step1PauseGenerationAfterSeconds=0 disables the timed pause; voxel.Step1MaxMeshApplies=0 uses the asset cap; voxel.Step1PrequeueVisibleLOD0=0 disables the held upload corpus; voxel.Step1UploadDisableCollision=0, voxel.Step1CollisionProbe=0, voxel.Step1CoreCookBenchmark=0, and voxel.Step1CsvCaptureOnBeginPlay=0. All default off. The launch-only voxel.TestClipRadius transiently duplicates settings and clamps a positive requested radius to 1–16; it is absent by default and leaves the authored asset unchanged. The prequeue release emits the default-global VFStep1UploadCorpusReleased CSV event; voxel.Step1CsvCaptureOnBeginPlay=1 emits VFStep1GameBeginPlay. Use UE's -csvStartOnEvent=<event> to begin capture after RHI initialization.
AcquireTileComponent / ReleaseTileComponent	—	T2.c component pool (TileComponentPool, bounded): park on unload (geometry+collision stripped, hidden, stays registered), pop on apply — no NewObject/RegisterComponent/GC churn during travel & regen. §8.10.
GetStrateAtPosition	8351	Gameplay query → strate index.
GetBiomeAtWorldLocation	—	BlueprintCallable biome probe at a world point (undoes actor xf → voxel → Generator::QueryBiomeAt). Returns FVoxelBiomeQuery for BP debug ("what biome / how many decos under the cursor?").
GetVoxelSurfaceHeightAt	8385	BlueprintCallable ground finder (F7 bridge): world XY → terrain + sky-cap world-Z via Generator::GetSurfaceHeightAt, NO trace/collision, deterministic, available before the area meshes → self-arranging prefab/ruin BPs snap their parts to the real ground. False (outs=input Z) on non-SurfaceWorld strates; ignores passage/spine carving.
CarveAtPosition / FillAtPosition	10230 / 10239	Build FVoxelModification → ApplyModification.
ApplyModification	10248	Single funnel for all brushes: DiffLayer → when a negative brush intersects the pawn's capsule bounds and affects its ready support tile, disable that old body and withdraw readiness before remesh → sync-remesh the brush-centre level-0 tile (SyncRemeshTile, instant hole; skipped if that tile is mid-gen — would race a stale in-flight result) → RemeshDirtyChunks(..., ExcludeTile) for the neighbours → RemoveDecorationsInSphere. A successful replacement cook restores collision/readiness; neighboring edits that miss the capsule bounds keep the same-tile recook handoff.
ClearAllModifications	8696	Clears diff layer, regenerates.
ChangeSeed	8710	Legacy season reset: new seed everywhere, clear diffs, bump season, reload. Rejected while a cooked season owns the seed.
GetCurrentSeed / GetCurrentSeason / GetCurrentSeasonContentHash	—	Effective cooked-or-legacy identity; the hash is the join-time stale-season comparison value. The optional world-assembly digest joins the hash only while bUseVoxelForgeCore is active, so switch-off retains the previous legacy hash.
RemeshDirtyChunks	8801	Queue loaded level-0 dirty tiles onto DirtyRemeshQueue (async re-mesh, no pop) + MarkDirtyVoxelBox the volume. Optional ExcludeTile = the sync'd centre. Drained FIRST in the submit loop at BackgroundHigh (ahead of streaming/band) so a dig never waits behind streaming; in-flight tiles stay QUEUED (not dropped) so a stale pre-carve result is corrected once it lands — fixes "hole shows up a beat late / not until I move".

Game-thread profiling (Perf): AVoxelWorld::Tick and its sub-steps are wrapped in TRACE_CPUPROFILER_EVENT_SCOPE — VoxelForge_Tick / UpdateChunks / BuildDesiredTiles / CullTiles / SubmitTiles / ProcessPending / ProcessUnload / UpdateDecorations / UpdateWater. Capture a Count/Incl/Excl Insights timer export and read the Excl column to see which step owns the per-frame cost (the actor tick shows as BP_VoxelWorld_C if subclassed in BP). VoxelForge_ClassifyTile (T1.d) / VoxelForge_GenerateMesh + VoxelForge_BuildStreams are worker-side (off the frame): the RMC FRealtimeMeshStreamSet is now built on the gen worker (BuildTileStreamSet) and carried on FChunkResult::Streams (TSharedPtr), so ApplyMeshToTile is game-thread-cheap — just material/ceiling resolve + CreateSectionGroup(MoveTemp). See ARCHITECTURE §8.10 "Worker-built StreamSet (T1.f)".

3.6 Density generator — Public/VoxelGenerator.h + Private/VoxelGenerator.cpp

UVoxelGenerator : UObject — lightweight; holds Seed, a process-unique DensityCacheOwnerId, and injected services StrateManager + DiffLayer (both nullable). This is where terrain shape lives.

Symbol	.cpp line	Role
UVoxelGenerator / DensityCacheOwnerId	—	Constructor allocates a process-unique integer identity (relaxed atomic, once per object). GetDensityAt includes it in the CP_* thread-local key, preventing a worker from serving another generator/world's params, biome context, CP_UseOpStack, or stack when (ChunkCoord, LayoutVersion) happens to match. Hot-path cost: one uint64 compare per voxel. Scope is deliberately only the proved CP_* path.
FractalNoise3D (static)	931	fBM (layered Perlin).
RidgedNoise3D (static)	949	Ridged multifractal — craggy.
CellularNoise3D (static)	976	Worley/cellular — grotto/scallop.
ApplyBoundarySeal (static)	996	Solidifies strate top/bottom shells.
InitializeSettings	2691	Copies the effective seed, spine radius, and global XY world-bound settings from UVoxelSettings (the season owns all three when assigned); radius 0 preserves the unbounded field.
GetDensityAt	2712	Entry point. Picks strate + generator type and, on the per-chunk refetch, builds the chunk's operator stack (editor composer → cooked-season recipe → native archetype stack); evaluates it (TunnelNetwork/Underwater through the fused GetDensityWithParams), then adds disturbances and structural posts. Optional OutPreEditDensity receives the exact final procedural field immediately before the player DiffLayer tail, allowing the near-player dig cache to replay edits without regenerating the operator stack. Its ordinary one-argument behavior is unchanged. A degenerate strate has no stack and is air; CP_* state remains keyed by (DensityCacheOwnerId, ChunkCoord, LayoutVersion).
EvaluateDensityChunk	2728	Editor-only, default-off research API. Accepts a lattice region contained by one 32-voxel chunk. Routes once, reuses FVoxelDensityBlockSession::FillChunk / EvalBlock for supported TunnelNetwork and Underwater operator stacks, and applies the existing post-stack writers across all chunk points before returning. Unsupported routes use scalar GetDensityAt and return both fallback and general-path entry counts. The region evaluator prepares bounded cache/index state once per region or chunk. The API is absent from non-editor builds; streaming and gameplay continue through the original scalar API.
GetDensityWithParams	3749	TunnelNetwork pipeline (~1000 lines) — the fused evaluator of the TunnelNetwork/Underwater stack in GetDensityAt. See §4. ⚠️ Takes required ParamsFingerprint + LayoutVersion since the AUDIT §C2 fix (2026-07-28) — they go into the SDF cache key so a chunk can no longer be evaluated against a neighbour's rooms. Callers compute the CRC once per chunk (CP_TunnelFP), never per voxel. The optional voxel.WormBlockSkip path (default 0) uses VF_TryGetWormBlockSkip + a worker-local 4³ lattice-block cache to prove `
SampleSurfaceStructuralZ	—	F20: the RAW SurfaceWorld heightfield (continents+mountains+detail), BEFORE any terrain op; returns terrain Z + relief M. Cliff re-samples it at an XY offset for a cheap analytic slope.
ComputeSurfaceTerrainZ / ComputeSurfaceColumn	—	SurfaceWorld heightfield → terrain Z (+ sky-cap ceiling and overhang gate per column); biome output-blend lerps dominant/neighbour heights (ParamsD/ParamsN/weight). F20 surface ops (FSurfaceGenerationParams, biome-selected + slope/relief-conditioned, all default off): Cliff (slope-gated STEEPENING — push height from local mean where steep ⇒ sheer walls; 4 structural resamples only when on), Terrace (relief-gated + TerraceHardness), LayerLines (sedimentary shelves) — pure per-column height REMAPS applied here so the single height oracle stays consistent (MC/ClassifyTile/deco/BP bridge). Phase 2 OVERHANG (volumetric — real jutting shelves): in the stack's FOverhangShelfMod, for AIR voxels in a window (TerrainZ, TerrainZ+OverhangHeight] above a steep slope, the heightfield is re-sampled UPHILL (toward the cliff) by a reach that GROWS with height (tiny low ⇒ air over the void, full high ⇒ borrows the far cliff rock) and unioned in ⇒ a shelf attached to the cliff, tapering out over the void with air beneath (the sketch). Per-column OverhangAmp(=strength·slope-gate) + unit uphill (DirX,DirY) resolved once in ComputeSurfaceColumn (gradient sampled at the REACH scale so a spot over the void can see the cliff), cached on FSurfaceColumn. Genuine 3D (per-voxel structural re-eval, gated to steep overhang columns). Off ⇒ byte-identical. The field-preserving LOD0 pass removes only needless temporaries/default construction; every output remains bit-identical. §8.14.
VF_BuildOpStackForChunk (file-static)	—	The archetype → stack mapping, written down once. GetDensityAt and ClassifyTile both call it; params are passed in, never fetched here. A second copy would be the worst bug available in this file — a tile skipped on the verdict of a stack that is not the one producing its density is a hole. Returns false for an unknown archetype, missing params, or a degenerate strate (the stack deliberately has no degenerate early-out): GetDensityAt then returns air and ClassifyTile returns Mixed. Refs.Surface == nullptr makes it refuse SurfaceWorld, which is how ClassifyTile keeps its own exact-lattice proof.
ClassifyTile	—	T1.d trivial-tile reject. ⛔ Not called by streaming by default since 2026-09-13 (voxel.OuterClassifierMode=0; net-negative in game, see ARCHITECTURE §8.10). Cooked/editor recipes now build the exact recipe stack and call its proved ClassifyBox; a tile crossing a slot/gap, any diff, or any disturbance returns Mixed. This replaces the old global HasComposerRecipeOverride() force-to-Mixed. Native cave/surface/gap proofs and all §8.10 caches remain unchanged.
SampleRelief / SampleMoisture	—	Climate fields (pure XY, [0,1]). Relief = shared source of truth for the relief map M. §8.14.
SampleBiomeAt	—	Warped-Voronoi + climate biome query (dominant + neighbour + weight). Reference used by the preview bake + GetDominantBiomeAt. §8.14.
ResolveBiomeSampleAt / RebuildBiomeGrid	—	Hot-path biome resolve (FBiomeSample) via a box-validated per-chunk cell-grid cache. Bit-identical to SampleBiomeAt. §8.14, §8.10.
GetDominantBiomeAt	—	Game-thread query → dominant biome ASSET (content/atmosphere). §8.14.
QueryBiomeAt	—	Rich game-thread biome probe → FVoxelBiomeQuery (dominant/neighbour asset, relief/moisture, blend weight, dominant deco count). Diagnostic behind AVoxelWorld::GetBiomeAtWorldLocation. §8.14.
EvaluateTerrainConditions	6973	F7 aware placement: AND-evaluate an entry's FTerrainCondition[] (relief/moisture/biome-border) at a candidate voxel XY. Empty = true (zero cost). Pure query (SampleRelief/SampleMoisture/SampleBiomeAt) → worker-safe + game-thread; caller passes the strate's FBiomeContext (freq/contrast + Voronoi map). Consumed by deco BuildCellSpawns + SpawnLandmarkInstance; shared core of the future quest FindFeature locator.

Per-voxel hot-path memos (perf pass 2, all bit-identical — same hashes/math, hoisted per chunk/cell): GetDensityAt uses the DiffLayer snapshot cache (§3.9); GetDensityWithParams memoizes the strate index per (chunkZ, GetLayoutVersion()); thread_local per-cell lattice bakes cover slab columns (FGridColumnMod), maze open edges (FLatticeCorridorSource), vertical shafts + cross-connectors (FShaftFieldSource), floating-island constants (FIslandBlobSource), and the disturbance chasms/bridges/ridges; worm tunnels short-circuit the 2nd Perlin when N1 ≥ WormThreshold (N2 ≥ 0 ⇒ can't carve). With voxel.WormBlockSkip=1, a worker-local cache proves whole 4³ lattice blocks only when the actual 3D Perlin bound (L = 8.118988160, including VOXEL_NOISE_SCALE) plus a 1e-3 output-rounding margin clears the threshold; failed proofs use the original per-sample path. Room shapes are pre-baked in FCachedRoom (§3.7). T2.b: per-voxel fractal call sites take their octave count through VoxelGenLOD::Eff(N) (VoxelGenerator.h) — a thread_local bias set per tile by the mesher drops tail octaves on coarse tiles (opt-in LODOctaveDrop, default 0 = off); XY-field noise (heightfield/ceiling/relief/moisture) deliberately stays un-biased. §8.10.

3.6b Strate measurement — Public/VoxelStrateMeasure.h + Private/VoxelStrateMeasure.cpp

Headless, read-only Tier 2 measurement pass. VF_MeasureStrate samples one strate between a boundary-seal-derived (or explicitly overridden, including explicit zero) interior margin into a bounded grid. When both CoverPointA and CoverPointB are set, the XY window is their AABB expanded by CoverMarginVoxels; otherwise it is the legacy square centered on CenterXY with RadiusInVoxels. Origin-rooted callers set bIncludeOriginInCoverWindow to expand that fitted AABB to include (0,0) before the MaxCells check; an over-cap route window is refused rather than cropped back to a mouth-only box. It performs one deterministic 6-connected air flood fill, and derives fractions, components, walkability, feature scale, and clearance from that grid. It then performs one bounded 4-neighbour flood fill over the projected XY columns that contain a walkable surface; this is a floor-continuity indicator, not another source-density sample or a 3D route proof. Metrics report the resolved margin and the inclusive/exclusive voxel Z window used, the exact sampled dimensions/bounds, and the largest component's deterministic lowest-cell representative point, cell count, and count of components holding at least 1% of the air. The flood fill also retains component cell counts in discovery order, so diagnostics can classify small non-largest components without a second source sample. Callers may optionally receive that exact polarity grid and scalar values as FVoxelStrateSampleGrid; the editor-only composer preview consumes this hand-off rather than sampling the world again. The filled view uses the captured Air polarity, while the paired density=0 contour uses the captured scalar field directly (no blur of the coarse raster). Capture refuses a grid over MaxCells before allocating it; ordinary metric callers do not retain either buffer. VF_AreConnected recovers a deterministic BFS parent path from the same kind of grid and checks candidate routes at full voxel resolution before returning Connected. When a candidate is refuted, its specific coarse cell edge is added to a deterministic array blocklist and BFS is retried up to MaxRouteRetries (default 16). It returns an explicit EVoxelConnectivityResult; a solid endpoint cell is repaired by snapping to the nearest air cell among its 26 neighbours when possible, and reports the snap through its out flags. A missing coarse route after edge exclusions returns NotConnectedAtThisResolution: that is evidence only at the grid's resolution, because a corridor thinner than SampleStep is invisible. Exhausting the retry budget (or finding a refutation in an endpoint segment with no coarse edge to exclude) returns CoarseLiedBudgetExhausted, which is unknown rather than disconnected. Every Connected result has a full-resolution air-verified route, and the query reports the alternate route retry count. No UObject state, cache, actor, world, or PIE is required.

Symbol	Role
FVoxelStrateMeasureSettings / FVoxelStrateMetrics	Plain settings/result structs for bounded strate sampling and derived measurements; callers may override the interior margin (including zero to sample the seal) or fit the XY window to two points with a margin, and results identify the resolved window/dimensions/Z range, deterministic air-component facts, walkable floor-area columns/fraction, projected surface components/share, and median clearance.
FVoxelStrateSampleGrid	Optional one-pass density > 0 Air polarity plus exact scalar Density capture; player-fit walks may also export the exact PlayerFitMask and count. Bounded by MaxCells, shared by explorer render/walk/export, and never retained on ordinary metrics calls.
VF_MeasureStrate	One-grid/one-flood-fill strate metrics; resolves either the legacy centered square or the two-point fitted AABB, and refuses invalid bounds or a grid over MaxCells.
VF_AreConnected	Coarse 6-connected BFS plus deterministic blocked-edge retries, with a full-resolution air recheck for every candidate route and explicit endpoint-solid, out-of-window, NotConnectedAtThisResolution, CoarseLiedBudgetExhausted (unknown), and connected outcomes; diagnostics include endpoint component facts and the retry count from that same grid.
VF_DiagnoseConnectivity	The same query plus each mouth's air-component size/share and exact geometric distance to the nearest cell of the other component; proximity is measured in coarse-cell coordinates and does not claim a route through solid.
FVoxelPlayerFitWalkReport / VF_MeasurePlayerFitWalkWithSampler	Editor-only experiential instrument over the existing exact VF_ capsule/floor-fit mask: deterministic graph-walk distance, dead ends, reachable fit volume, and a labelled narrow-gap proxy; optionally exports the one sampled grid/mask for other explorer consumers; no second movement model.

VoxelForgeExploreCommandlet builds a transient, fixed-definition world and calls the production UVoxelGenerator::GetDensityAt and UVoxelMarchingCubesMesher::GenerateMesh paths. walk (or the private seed walk used by render-only runs) captures one exact sampled grid and player-fit mask; render and export reuse that hand-off. render calls the canonical 32³ mesher in a deterministic tile grid (four tiles per axis for the 128³ default), merges the region once, builds a deterministic CPU BVH, and rasterises eight viewpoints from the mesh without per-pixel density calls. export uses that same canonical aggregate for metre-space OBJ plus manifest.json (canonical UVs remain voxel-space). Output JSON/manifest are emitted by fixed-order writers and compared with a second serialization before they are written. The commandlet keeps WorldRadiusVoxels=0, does not touch an authored asset or diff layer, and enforces the default 25-minute / maximum 30-minute wall-clock budget, reporting partial artifacts and completed modes on truncation. -gameconfig=1 opts into the authored settings' skirts/LOD octave drop and permits export-only parity of a single-strate asset; the optional -exporttilex/y/z arguments choose a specific level-0 tile for export/game parity, while omitting them preserves center-derived region selection. The historical interior-slot requirement remains in force for walk/probe runs. VoxelGeometryHash.h is the shared digest used by Tools/VoxelForgeTest.ps1 -Scenario parity.

3.7 Cave morphology (SDF rooms/tunnels) — Public/VoxelCaveMorphology.h + .cpp

Header is rich with inline docs. Two namespaces + a per-chunk cache system.

• namespace VoxelSDF (h:78): Sphere, Ellipsoid, Capsule, RoundedBox, TaperedCapsule, SmoothMin, SmoothMax — all FORCEINLINE SDF primitives.
• namespace VoxelHash (h:210): Mix, Cell, Pair, ToFloat01, ToFloatSigned — deterministic hashing for room/tunnel placement (no storage, infinite worlds).
• Cache structs (h:520-950): FCachedRoom, FCachedTunnel, FCachedPit, FCachedChimney, FCachedColumn, FChunkSDFCache.
• FChunkSDFBrickIndex is an editor-only-at-use 8-voxel 3D bin beside the existing XY index. The default-off SetResearchBrickBinningEnabled selector builds/selects it only for the explore commandlet. VF_BuildResearchBrickIndices uses the cached room cull reach (shape, floor relief, blend and terrain-op envelope), room-floor-join bounds, and the union of SDF/world tunnel centerline influence and bounding-sphere bounds. Source item indices stay in ascending order; invalid or oversized grids fall back to today's XY broad phase. This step-2 candidate-bin ablation still routes every lattice point through the canonical GetDensityAt final field.
• namespace VoxelCaveMorphology:

  Function	.cpp line	Role
  BuildChunkCache	6782	Phase 1 (once/chunk): collect rooms, guaranteed backbone (bTunnelsFlowTowardOrigin: tree rooted at the (0,0) hub — every room reachable, links flow inward; false = legacy NN forest), slope-aware link metric (TunnelHorizontalBias now applies to backbone too), decide tunnels, cull zero-connection rooms (no sealed bubbles), store rooms by their OWN reach (fixes origin-room clipping at MaxInfluence), pre-bake pits/chimneys/columns via the shared BakeRoomFeature hash-placement skeleton (one gate/XY/radius pattern + per-type Emit lambda), hash-roll per-room terrain op.
  EvaluateSDFCached	8569	Phase 2 (per voxel): SmoothMin over cached rooms/tunnels; returns nearest room idx for terrain-op lookup. Signature changed (perf pass 2): RoomShapeVariety param REMOVED — the shape roll + capsule trig are pre-baked into FCachedRoom (ShapeType/ShapeA/ShapeB/ShapeR) by BuildChunkCache, bit-identical.

MakeStrateSeed (h:965) is the shared pure world-seed/strate-index salt used by both BuildChunkCache and the TunnelNetwork/Underwater destination landing queries. VF_SuggestLandingPoint (h:1121, implemented in VoxelCaveMorphology.cpp) is the pure player-fit landing-site query: it evaluates the local archetype source through the same capsule/support contract as the measurement pass — support within step height, walkable slope, and full capsule clearance. Room queries use a room-floor core, slabs keep their requested XY, and the sparse sources use bounded feature cores: a horizontal lattice corridor (one Maze cell), a selected VerticalShafts tree shaft plus deterministic ledge-side offsets (up to two local shaft spacings at the 0.6 site density), or a validated blob top (one IslandSpacing). It is intentionally not a flood fill: the pure query can prove a local pose, not a large component. The VerticalShafts result is therefore on the drainage tree, not merely in an open roughness disk. It returns false when those feature-bearing conditions cannot be proven inside the supplied budget; SurfaceWorld remains refused because its production height can depend on manager-owned biome/per-column context. It never touches a generator, operator stack, manager, cache, or mutable state.

FVoxelPassageLanding, VF_BuildPassageLanding, VF_EvaluatePassageLandingSDF, and VF_IsPassageLandingFloor (h:57/184-199, implemented near .cpp:6468) turn each inter-strate mouth into a deterministic rounded room plus a hard support slab. The room is sized from the player capsule (minimum 24 voxels / 3 m flat floor and clear height); the (0,0) origin landing is enlarged for the reserved future shaft, while inter-strate mouths remain local rooms and deliberately have no landing-to-root connector road. The manager's shared thread-local passage shortlist serves tube, room, and floor evaluation; no landing search occurs per voxel. GeneratePassages stores the full descriptors and the order-independence test compares them bit-for-bit.

Performance note (h:520-531): caching rooms/tunnels once per chunk instead of per voxel is the single biggest CPU win.

3.8 Strate system

Public/VoxelStrateTypes.h — shared structs/enums (1228 lines, the data vocabulary):

Symbol	Line	Role
EVoxelPassageType	42	Sloped/Vertical/Spiral/Cascading/Crack passage shapes.
ESurfaceType	81	Floor/Wall/Ceiling/Any (decoration placement).
EVoxelNoiseType	128	FBM/Ridged/Mixed/Cellular.
ECaveGeneratorType	175	TunnelNetwork / FlatPlain / CrystalChamber.
EVoxelStrateTransition	228	Gradient / Hard / Interleaved boundary blends.
FStrateGenerationParams	373	The giant TunnelNetwork param bag (rock, worms, rooms, tunnels, warp, roughness, live terrain-detail fields, dead terrain-op transport slots, boundary seal). Lerp() static blends two sets at boundaries — it expands the VF_STRATE_PARAM_FIELDS X-macro (defined just above the struct): adding a field to the struct? add it to that list or blends silently reset it to default.
FStrateTerrainOpEntry	1169	Soft-ptr to a terrain op + Weight + Probability.
FSlabGenerationParams	1223	Floor/ceiling heights, roughness, columns, seal — for slab generators.
FPlacementProfile	2000	Shared placement vocabulary for every scatter primitive (FStrateDecoration, FStrateLandmark; set-pieces are landmarks): spawn (ActorClass/InstancedMesh), Filter gates (surface/slope/overhang/water/RequiredBiome + F7 awareness Conditions[] — FTerrainCondition relief/moisture/biome-border predicates, AND-ed, evaluated by Generator::EvaluateTerrainConditions), Transform (align/offsets/RotationOffset+RandomRotation/scale), Render (cull/shadow). Each primitive embeds it as Profile + keeps only its own DISTRIBUTION fields. Per-primitive defaults set in each struct's ctor (deco: scale 0.8-1.2 + RandomRotation.Yaw=360; landmark: Ceiling + no align).
FStrateDecoration / FStrateLandmark	2207 / 2271	Profile + distribution: deco = StreamTier/SpawnDensity/MaxPerChunk; landmark = SpacingChunks/JitterFraction/SpawnProbability/StreamRadiusChunks + Light-Orb block.
ELandmarkAnchor (on FStrateLandmark)	2251	F7: AnchorMode = HashLattice / PassageMouth + passage toggles + exclusion (ExclusionRadiusChunks/Priority) folded into FStrateLandmark (set-pieces merged in — one primitive, one Landmarks list, UpdateLandmarks).
FStrateAmbientActor / FStrateCreature	2405 / 2425	Content spawn entries (consumed by future systems).

Public/VoxelStrateDefinition.h — UVoxelStrateDefinition : UPrimaryDataAsset (line 46). One asset = one strate type. Fields: identity, StrateHeightInChunks(75), TransitionType(93)/TransitionBlendChunks(103), GeneratorType(116), GenerationParams(137), SlabParams(148), Biomes[]+BiomeMapParams (the biome list + field tuning — empty ⇒ unchanged world, §8.14), TerrainOperations(252), visuals/fog/light, content lists, audio, GameplayTags(393). EditConditions show/hide param groups by generator type.

Public/VoxelStrateManager.h + .cpp — UVoxelStrateManager : UObject (h:152). Maps depth→strate at runtime; owns passages.

• FVoxelPassage (h:46): standing endpoints, radius, type, wandering control points, and upper/lower local landing descriptors (room, floor, and door; no root connector).
• FStrateSlot (h:128): definition + chunk-Z range + index.

  Method	.cpp line	Role
  Initialize	1164	Keeps the existing sequencing through GeneratePassages, but selects one slot source: a validated cooked season (exact ordered bounds/vector/recipe) or the unchanged authored fixed+sorted/shuffled pool. Assigned-invalid seasons fail closed. Authored source definitions are duplicated as content bags; generated slots use deterministic C++ defaults and zero auto-passages because schema 2 does not store passage configuration.
  GeneratePassages	1659	Deterministic passages between consecutive strates (per-strate PassageConfig::Style control points; auto passages retain the existing EVoxelPassageType default); placement and shape values are independently salted hashes of seed + boundary slot + connection index. Each mouth independently queries its own strate's pure player-fit VF_SuggestLandingPoint with its contract seed (cave room salt, otherwise world seed), may move within its archetype-specific budget, then receives a body-sized local room/floor. The origin landing is reserved for the future shaft; no landing-to-root road is generated. Unsupported/no-fit answers preserve the old random reach; a deterministic level dog-leg is inserted when the final ramp needs it to stay ≤44°. All descriptors and bounds are generated without reading another passage.
  EvaluateModifierSDF	2643	SDF of passage tubes plus local landing rooms at a point. A per-chunk thread_local shortlist (PassagesVersion-stamped) → far chunks return FLT_MAX without walking Passages; the same cache serves floor membership. FPassageEvaluationCache::FloorProjections reuses native/generic floor projections and walkable-air results once per (sample, passage) using exact double XYZ equality and unchanged float outputs; voxel.FloorRound1PassageProjectionCache=0 disables only this A/B cache. §8.10.
  ApplyPassageModifier	2772	Shared legacy/op-stack passage post: carves tube and local landing air through the idempotent landing primitive, then restores the local landing support slab in internal positive-solid density.
  VF_ApplyPassageLandingCarving	—	Idempotent density-independent landing-air threshold shared by the structural pass and the post-disturbance MC backstop, so the two agree bit for bit.
  ApplyPassageLandingFloorMC	2983	Reasserts the same support slab after MC-space disturbances and before the final XY edge seal.
  AnyPassageNearBox	—	Conservative sphere-vs-AABB test of every passage's bound against a voxel box (+carve blend pad). Per TILE (ClassifyTile guard), never per voxel.
  AnyPassageLandingFloorNearBox	—	Conservative local-landing-floor AABB guard. It kills the AllAir hypothesis wherever a proved landing floor can occur; the op-stack returns Both for the same box.
  FindSlotIndexForChunkZ	6111	Z → layout index.
  GetStrateAt / GetStrateIndex	6127 / 6139	World-Z queries.
  GetLayoutVersion	h:250 (inline)	Layout/passage generation counter (= PassagesVersion, bumped by every Initialize and by the editor composer override). Hot-path callers key thread_local memos on it (strate-index memo in GetDensityWithParams, passage shortlist) so live changes never serve stale data.
  GetStrateForChunk	6150	Chunk → definition.
  GetGeneratorTypeForChunk	6176	Chunk → generator type.
  UsesOperatorStackForChunk	6203	Chunk → does its slot have an operator stack? True for any in-layout slot with a definition whose archetype is one of the 8 (Maze, FlatPlain, CrystalChamber, SurfaceWorld, VerticalShafts, FloatingIslands, TunnelNetwork, Underwater); false outside the layout. That list is written down here and nowhere else. ClassifyTile guards on it; GetDensityAt uses it to share TunnelNetwork stacks by chunk Z.
  GetRecipeForChunk	—	Runtime immutable recipe/vector/strate-seed copy for cooked seasons; editor slot overrides use the same worker hand-off.
  GetSlabParamsForChunk	6263	Slab params with runtime Z bounds (no blend — slabs use Hard).
  GetBiomeContextForChunk	—	Flatten the strate's Biomes[] + BiomeMapParams into a POD FBiomeContext for the biome field. Empty ⇒ biomes disabled. §8.14.
  GetGenerationParams	6509	Blended TunnelNetwork params (handles Gradient/Hard/Interleaved transitions).
  SetComposerOverrideForStrate / GetComposerOverrideForChunk	editor-only	Temporary density-only candidate overlay for one existing slot. Copies immutable params/recipe into the worker refetch path, leaves layout/content/passages intact, and bumps PassagesVersion to invalidate generator memos.
  BuildParamsFromDefinition (static)	6815	Returns the definition's base GenerationParams only. Terrain-op assets are passed separately to BuildChunkCache, which applies one selected op per room and pre-bakes Column/Pit/Chimney features.

Public/VoxelTerrainOpDefinition.h + .cpp — UVoxelTerrainOpDefinition : UPrimaryDataAsset (h:67). One asset = one terrain op. EVoxelTerrainOpType (h:36): Terrace, LayerLines, Ribbing, Cliff, Scallop, Overhang, Arch, Column, Pit, Chimney, Dome, Pinch. Per-type param groups gated by EditCondition. ApplyTo(OutParams, Weight) (.cpp:6) copies only the active type's fields into FStrateGenerationParams, scaled by Weight.

Public/VoxelBiomeTypes.h (NEW) — biome vocabulary. FBiomeMapParams (Voronoi cell size / border warp+blend / climate field freqs), EBiomePreviewChannel (preview-bake selector), FVoxelBiomeQuery (BlueprintType result of GetBiomeAtWorldLocation — dominant/neighbour asset, climate, blend weight, deco count), and plain runtime PODs FBiomeResolved / FBiomeContext / FBiomeSample / FChunkBiomeCache (the box-validated per-chunk grid cache). See §8.14. FChunkBiomeCache::Invalidate() (added 2026-07-27, AUDIT C2) — force a rebuild when the strate layout version moves. The validity BOX says nothing about the FBiomeContext the cells were classified against, so after a RebuildStrates the grid is stale even though the box still covers the query. Called by all four callers on a GetLayoutVersion() change.

Public/VoxelBiomeDefinition.h + .cpp (NEW) — UVoxelBiomeDefinition : UPrimaryDataAsset. One asset = one biome: identity + DebugColor, climate placement box (ReliefMin/Max, MoistureMin/Max), terrain override (bOverrideTerrain + GeneratorType + archetype params), content profile (Decorations/AmbientActors, atmosphere override, WaterMaterial, MaterialPaletteIndex (F6 — baked to vertex colour, §8.15)), GameplayTags. Referenced from UVoxelStrateDefinition::Biomes[]. Generator-agnostic (surface biomes now, cave biomes later). §8.14.

Public/VoxelStrateComposer.h + Private/VoxelStrateComposer.cpp (Tier 4a/4b + Tier 5) — offline FVoxelStrateCorpus, VF_RollStrateParamsDetailed, and VF_RollStrateStructure. LoadFromAssetRegistry enumerates every project UVoxelStrateDefinition through the Asset Registry, excludes Saved/Autosaves and Saved/Cooked copies, and adds one VoxelStrateTypes.h default vector for each of the eight exact archetypes. The corpus is grouped by exact ECaveGeneratorType: the 2026-09-04 run loaded 4 project vectors + 8 defaults = 12 members in 8 groups. Sibling families use their native structs (FSlabGenerationParams, FMazeGenerationParams, FSurfaceGenerationParams, FVerticalShaftParams, FFloatingIslandParams); no cross-archetype blend is attempted. Spreads are measured per group, including the plain-native tunnel fields. The fixed-lattice audit found 23 live terrain-detail fields (Terrace, LayerLines, Overhang, Ribbing, Cliff, Scallop, Arch, Dome, Pinch) and 11 dead direct transport fields (Column, Pit, Chimney); only the latter remain excluded. Live fields receive one matching UVoxelTerrainOpDefinition header-default sample in addition to authored strate values, so an all-default strate corpus still has useful activation spread. Rolls are pure in (corpus contents, seed, index): weighted 2–3-parent same-archetype selection → FStrateGenerationParams::Lerp or reflected native-family blend → ±15% of measured field range jitter (or the season-zero ±25% own-magnitude bootstrap for near-zero ranges) → editor-reflection clamps → ordered-pair repair. Bool bTunnelsFlowTowardOrigin inherits from the dominant parent; integer/enum SNAP fields are not jittered. Normal runtime generation never calls this API; the editor-only AVoxelWorld bridge does so only from its PIE button. The settings audit found one unique path, /Game/VoxelForge/DA_Strate3, which explains the old one-vector corpus; the project assets were never in that pool.

FVoxelOpStackRecipe is the serialisable Tier 4b manifest: root polarity, root/source/conversion class IDs, an ordered modifier ID list, and one native parameter-family ID per entry. Posts are not represented in the manifest; VF_BuildStackFromRecipe appends spine, vertical seal, passage carve, and XY edge seal in the fixed order. The roller derives modifier legality from the op channel and resource declarations, rolls 4–8 unique modifiers, and validates the recipe before materialising it. Rolling is editor-only; VF_BuildStackFromRecipe is runtime evaluation and is used by cooked seasons. RequiredResources / ProvidedResources close the room-state hole that channel masks alone could not express. VoxelForgeComposerStructureRollTest rolls 64 candidates, measures them through the offline sampler, and brute-forces every uniform box verdict from the novel stack itself.

Tier 5 adds FVoxelStratePromotableRecord, FVoxelStratePromotionPolicy, and FVoxelStratePromotionBatchResult. VF_SaveStratePromotedRecords writes a sorted schema-2 JSON corpus store containing the complete six-family parameter vector, recipe, archetype, gate evidence, metrics, season/seed, and input corpus hash; VF_SaveStrateSeasonManifest writes one diffable JSON summary beside it. FVoxelStrateCorpus::LoadPromotedRecords re-verifies every record through the world-specific IVoxelStratePromotionVerifier before admission, remeasures project/default members when that verifier supplies the optional audit, and tags membership project / default / promoted. VF_SelectStratePromotions uses normalized measured-metric distance (threshold 0.20), the existing corpus contents hash, deterministic RecordId ordering, and a six-record season cap. The promotion test simulates five seasons and deliberately corrupts one stored metric to prove the loader replaces it with a fresh measurement.

EVoxelStrateCorpusFreeSamplingMode, VF_RollStrateParamsCorpusFree, and VF_ValidateStrateCorpusFreeConstraints are the offline corpus-free control/experiment. They never read a corpus entry or strate asset: NaiveUniform rolls every live scalar independently inside a finite, code-declared envelope, while ConstraintSampled draws geometry quantities and derives dependent quantities from the generator equations before applying the envelope as a final safety net. VoxelForgeComposerCorpusFreeTest.cpp compares both arms with today's corpus blend using the same structure recipe, fixed measurement window, one arrival/departure law, and box-verdict brute force. The requested 256×3 and 64×3 runs were abandoned before aggregate output because the fixed 8M-cell law/box workload was too slow; the completed equal-arm run is 16 candidates per arm and 22.995 s inside the test. Its final result is 13/16 corpus-blend survivors, 7/16 naive, and 7/16 constraint-sampled. Survivor quality is not equivalent: corpus survivors averaged 0.066071 walkable / 92.307693 voxel feature scale, versus 0.012566 / 64.571426 for naive and 0.012851 / 31.428572 for constrained. All three arms had 0 box-verdict violations; proved boxes / checked lattice voxels were 196 / 260,876, 310 / 412,610, and 262 / 348,722 respectively.

Public/VoxelWorld.h + Private/VoxelWorld.cpp — ApplyComposerCandidate exposes the four Live Edit|Composer properties and the CallInEditor button. It preflights the candidate, pauses generation before installing the manager override, and calls the existing epoch-aware full reset. The post-apply check compares eight densities against the shared native/recipe stack where the live world has no extra diff, disturbance, or biome context. It reports SKIPPED rather than comparing unlike fields.

Public/VoxelStratePreview.h + Private/VoxelStratePreview.cpp — editor/automation-only PNG renderer and self-contained contact sheet. It consumes FVoxelStrateSampleGrid from the measurement pass, emits deterministic centre-Y XZ and data-selected XY slices via IImageWrapper, and shows filled-cell and scalar density=0 contour views side by side without blurring the sampled raster. Each image is capped at 512 pixels (including its scale footer). FVoxelStrateFinePreviewSettings is a separate caller-selected fine pass: the composer selects only survivors at step 1, radius 64 (a 128×128 XY ROI), and MaxCells=4,000,000; the caller centres it on each coarse survivor's LargestComponentPoint and the writer labels it “largest open space” with its exact ROI and step; cap refusals and blank fine ROIs are recorded explicitly instead of showing empty evidence. The ordinary 64-card sheet remains sorted by survivor status then descending corpus-centroid distance. The VoxelForge.Composer.Showcase test additionally writes an alphabetized one-card-per-archetype PIE hand-off page with the Part A survivor distributions, exact seed / candidate / target-slot values, and no runtime generation hook.

Public/VoxelSeasonManifest.h + Private/VoxelSeasonManifest.cpp — Tier 4c's offline composer and runtime-readable schema-2 artifact. VF_ComposeSeason generates a bounded configurable candidate batch, applies the Tier 2 non-vacuous / largest-component / primordial-law gates, then selects an ordered Tier A spine with the explicit provisional grounded/outlier, adjacency, variety, and five-slot boss policy. The JSON stores the complete six-family parameter vector (float values carry both a readable number and exact IEEE-754 bits), seed/index/archetype/recipe, bounds, measured metrics, gate facts, candidate audit, and rejection counts. A canonical SHA-1 content_hash covers the complete payload. VF_DeserializeVoxelSeasonManifest verifies it in memory; VF_LoadVoxelSeasonManifest plus VF_RebuildVoxelSeasonStrate are the round-trip seam; generated recipe entries rebuild through the mandatory-post builder, while authored FixedStrates retain their absolute slot and native vector. The selected-only descent review reuses VoxelStratePreview, and all composition/review work is editor/build-box code; parsing and recipe materialisation are runtime. Lateral region manifests remain rejected because their post-landing cross-seam law is only 4/16 (the pre-landing snapshot was 9/16). The focused season test currently reports 24 generated / 19 hard-gate survivors / 6 selected / 18 unselected or rejected, with 4 vacuous, 1 primordial-law budget, 13 policy-not-selected, and 393,216 round-trip density samples bit-identical. The specified UE 5.7 editor build succeeded and the final VoxelForge namespace report VoxelForgeFullMazeTreeFinal3 recorded 30 clean successes, 2 warning-bearing, 0 failed, 0 not run in 2,523.978 s. The regenerated showcase produced 6 fine renders, 2 refusals, and 0 blanks; all box-verdict violations remained zero. The later focused production-height showcase history is recorded separately below.

The current landing validation is recorded in VoxelForgeLandingFinal5: 30 clean successes, 2 warning-bearing successes, 0 failures, 0 not-run across 32 tests in 3,607.746 s. The strict promotion assertions passed and no assertion was weakened. The landing-specific geometry test, both connectivity tests, all box verdicts, seals, determinism, and op-stack equivalence tests passed.

Public/VoxelSeasonAsset.h + Private/VoxelSeasonAsset.cpp — UVoxelSeasonAsset : UPrimaryDataAsset, the cookable carrier. Its editor button imports the reviewable JSON, stores the exact text plus independently copied metadata/hash, and retains soft references to any authored definitions. UVoxelSettings::Season is the only activation switch.

3.9 Player edits — Public/VoxelDiffLayer.h + .cpp

UVoxelDiffLayer : UObject (h:137). Stores FVoxelModification (h:60: Center/Radius/Strength; negative Strength = carve, positive = fill) grouped by chunk in TMap ChunkMods.

Method	.cpp line	Role
SetBudget	102	From VoxelSettings carving caps.
CanModify	112	Budget check (no consume) — for UI.
GetRemainingModifications / GetRemainingVolume	169 / 175	-1 = unlimited.
ApplyModification	185	Enforces budget, stores in all overlapped chunks, returns dirty coords.
GetDensityOffset	299	Per-voxel combined diff (smoothstep falloff, additive).
HasModifications	421	Fast reject for hot path.
HasAnyMods / GetModsVersion	h:246 / h:249 (inline)	Lock-free atomics: any-mod-exists flag + monotonic mod-state version (bumped by ApplyModification/Clear).
GetChunkModsSnapshot	—	Copy one chunk's mod list under ONE read lock. Workers snapshot per (chunk, version) instead of locking per voxel — GetDensityAt keys a thread_local 64-slot direct-mapped cache on it (~27 lock ops per tile task instead of ~86k once any carve exists).
HasAnyModInChunkRange	—	Any modified chunk key in an inclusive chunk box? One key walk under a read lock — ClassifyTile's diff guard (per tile, conservative by construction: mods are stored in every chunk their radius overlaps).
EvaluateMods (static)	—	Lock-free pure evaluation of a mod list at a voxel — shared core of GetDensityOffset and the generator's snapshot path.
Clear	435	Wipe all (season reset).
GetTotalModificationCount / GetModifiedChunkCount	454 / 465	Stats.

3.10 Mesher — Public/VoxelMarchingCubesMesher.h + .cpp

UVoxelMarchingCubesMesher : UObject (h:42). Holds Generator ptr, IsoLevel=0, skirt params. The pre-sampled grid supplies positions AND gradients inline (T1.b).

Method	.cpp line	Role
GenerateMesh	96	The MC loop over cells; Step controls LOD sampling. Sets the T2.b octave bias for the tile (TGuardValue on VoxelGenLOD::OctaveBias, from LODOctaveDrop × log2(Step); 0 at LOD0/off). Edge t + grid-gradient normals computed inline (SampleG/GradAt). Optional OutCaptureGrid (4th arg) captures the already-sampled CHUNK_SIZE³ R8 density clipmap. Optional OutPreEditDensityGrid captures exact float samples before player edits for full-res L0 tiles; optional InSharedDensityGrid is per-call (not the mesher's shared mutable setting) so sync carve reuse cannot race async tile tasks. Capture/reuse leaves §8.10's thread-local scratch, two-pass MC and density-grid semantics intact. F17 surface class: each unique vertex is classified sol/sky-cap in GetOrCreateVertex (down-facing only → memoized GetSurfaceHeightAt, nearer CeilSurf = cap); triangles bucket by majority into GroundTris/CapTris (thread_local), skirts emit per bucket and increment diagnostic NumSkirtTriangles, then Triangles = ground‖cap + FVoxelMeshData::NumCeilingTriangles (→ polygroups in BuildTileStreamSet). Same tris, only index ORDER changes. STRATE CONTENT CUT: optional BandZMin/MaxVox params restrict the cz cell loop (+ gz sampling rows) to the player-strate band — coarse straddling tiles mesh ONE strate; meshed cells bit-identical.
FVoxelMeshData::NumSurfaceVertices	375	Prefix length for density-isosurface vertices before seam skirt vertices are appended. The test-only visual-gap audit samples this prefix so artificial skirts cannot become expected terrain points.
FVoxelMeshData::NumSkirtTriangles	—	Counts skirt triangles appended by GenerateMesh; consumed only by opt-in collision-cook stage reports.

Public/MarchingCubesTables.h — EdgeTable + TriTable reference data (Paul Bourke). Cube corner/edge layout documented at top (lines 7-37). Rarely needs editing.

3.11 Per-chunk content & per-strate atmosphere (2026 redesign — see §8)

File	Role
Public/Private/VoxelContentManager.h/.cpp	UVoxelContentManager — distance-based world-grid decoration scatter (no LOD pop, surface-snapped via GetDensityAt) + level-0 water planes. F7 companions: each FStrateDecoration may list FDecoCompanion satellites (rocks/mushrooms around a tree) — emitted per placed parent in PlaceAtCrossing, deterministic (pure fn of the parent hash), inherit the parent's surface point; FDecoSpawn::CompanionIdx routes each back to its Companions[ci].Profile at apply. TWO streaming grids (FDecoGrid Near/Far, picked per entry via FStrateDecoration::StreamTier): NearGrid = short radius + fine column grid (groundcover); FarGrid = full radius + coarse grid (cheap rare/large props). Plus UpdateLandmarks — rare deliberately-placed objects: mini-suns, ruins, shrines, monuments (FStrateLandmark; set-pieces folded in 2026-07-06). Per entry an AnchorMode: HashLattice (coarse hash lattice, cell = SpacingChunks chunks → cheap at any radius, no per-chunk freeze) or PassageMouth (GetPassages() endpoints landing in this strate). Gated by Profile + Profile.Conditions; optional deterministic exclusion radius (Priority+hash rank, ExclusionRadiusChunks; 0 = off → pure scatter is unchanged, skips the O(n²) resolve). Synchronous, deterministic, strate-wide; spawns via SpawnFromProfile (+ orb wrapper). Exclusion is POP-FREE (gathers a MaxExcl ring of suppress-only candidates so a piece's fate is player-position-independent). bSuppressDecorationsUnder/SuppressRadiusChunks clear grass under a footprint (on spawn + re-cleared in ApplyRegion). RemoveDecorationsInSphere (world sphere → both grids' HISMs via GetInstancesOverlappingSphere+RemoveInstances) is the shared primitive, also called by AVoxelWorld::ApplyModification so player digging removes floating grass instantly. Owned by AVoxelWorld. §8.5.
Public/Private/VoxelAtmosphereManager.h/.cpp	UVoxelAtmosphereManager — per-strate fog/skylight + persistent ceiling/floor layer actors + full AtmosphereActor override. Owned by AVoxelWorld. §8.6.
Public/Private/VoxelDensityVolume.h/.cpp	UVoxelDensityVolume — opt-in player-centred DENSITY CLIPMAP (bEnableDensityVolume defaults false) with N toroidal R8 levels streamed to GPU UVolumeTextures for mini-sun shadows. When enabled, fills run on ONE dedicated thread (FVoxelDensityFillRunnable); level 0 is mostly fed by CAPTURE-DURING-MESHING (gated by IsTileCaptureUseful), and carve → MarkDirtyVoxelBox refills locally. VolumeEpoch drops stale fills. When disabled, no object/thread/fill/upload/Tick update/capture/proof bypass exists; SetDensityVolumeMaterialParamsDisabled sets VolP0..4/VolP6..9 black, VolP5=(0,25,0), and VolTex0..2 null on shared per-base MIDs. SetVolumeParamsOnMID carries these values to newly created MIDs.

The big 2026 redesign (8 archetypes, (0,0) spine, inter-strate gap, per-strate passages, disturbances, content/atmosphere, brush shapes, perf invariants) is documented in §8 — read it first when touching generation/strates/passages.

---

3.12 Automation tests — Private/Tests/ (added 2026-07-27, #if WITH_DEV_AUTOMATION_TESTS)

The plugin's first tests (Docs/archive/OPSTACK-PLAN.md Phase 0.5). Run them from the editor's Session Frontend → Automation, filter VoxelForge. The OpStack.*Equivalence names are historical: those tests check the shipped stacks themselves and no longer compare against a second density path.

File	Test name	What it proves
VoxelForgeTestFixture.h	—	FTestWorld: a headless world (transient strate definitions → UVoxelSettings → a real UVoxelStrateManager::Initialize) so tests hit GetDensityAt, where the thread_local caches live. One strate per archetype, pinned via FixedStrates so slot index → archetype is stable across seeds (SlotSurfaceWorld etc.). Bounded regression fixtures default to 4 chunks; the production/default definition and the owner-facing showcase explicitly use 8 chunks.
VoxelForgeDensityPurityTest.cpp	VoxelForge.Determinism.DensityPurity	10k points re-sampled in shuffled order, same thread and on N workers, asserting BIT equality. ValidateDeterminism is game-thread only and cannot see worker-cache divergence. Includes a flat-field canary (AUDIT C1) and a diff-layer pass.
″	VoxelForge.Determinism.LiveEditInvalidation	AUDIT C2 regression: triple the heightfield params, Initialize again, require the density to MOVE. The edit does not move the strate, so only LayoutVersion changes.
VoxelForgeClassifyTileTest.cpp	VoxelForge.Determinism.ClassifyTileSoundness	Scans for a non-Mixed verdict, then brute-forces the exact mesher lattice (g ∈ [-1, Cells+1]). A false verdict is an invisible, collisionless hole — T1.d v1 was reverted for exactly this. Errors out rather than passing if it found nothing to check.
VoxelForgeDiffLayerTest.cpp	VoxelForge.Determinism.DiffLayerContention	N readers running the worker call mix while the game thread writes and Clear()s. Survival + monotonic ModsVersion.
VoxelForgeClassifyTileTest.cpp	VoxelForge.OpStack.BoxVerdictFold	Pure-logic walk of the fold in VoxelDensityOp.h, case by case — including the seal-forces-AllSolid case that justifies ClassifyBox existing. Also the only .cpp that includes the op header, so the build actually sees it.
VoxelForgeHeightStackTest.cpp	VoxelForge.OpStack.SurfaceHeightEquivalence	The height-space stack vs ComputeSurfaceTerrainZ, in altitudes. Runs twice: defaults, then all F20 terrain ops ON — the load-bearing pass, since the ops are off by default and the defaults pass exercises only the structural source. Also brute-forces MaxDisplacement (a false bound would be a hole). Bar is bit-identity; a height delta is a visibly different world, not rounding.
VoxelForgeCrossPlatformTest.cpp	VoxelForge.Determinism.CrossPlatformDigest	SHAPE digest (sign of density = the world) + FIELD digest (bit-for-bit) over a fixed integer grid, plus NearIso bounding how many samples could flip sign. Reports rather than asserts until pinned. Run on Windows and Linux and compare.
VoxelForgeOpStackSlabTest.cpp	VoxelForge.OpStack.SlabEquivalence	The same 6-op slab stack run three times — FlatPlain, CrystalChamber and a tuned CrystalChamber (the worst case for the ClassifyBox amplitude bounds): finite density over 20k points, window-invariance across order and threads, and box-verdict brute force.
VoxelForgeOpStackTunnelTest.cpp	VoxelForge.OpStack.TunnelNetworkSpineEquivalence	Stage A of the last port. Zeroes the 13 detail-op amplitudes so the original takes the path stage A ported — that is what makes an incomplete stack verifiable now. Samples in clusters (24 chunks × 250 points), because the SDF cache rebuilds when a query leaves its box and uniform sampling would rebuild per point on both paths. Check 3 (two param sets, A/B interleaved) compares each stack to itself alone, never to the original — the original would fail it, see AUDIT §C2. Asserts zero box verdicts, which is the honest stage-A result.
VoxelForgeOpStackShaftTest.cpp	VoxelForge.OpStack.VerticalShaftEquivalence	The port that tests reuse, not fidelity: three of the five ops are Maze's, unchanged. Forces connectors + ledges on, because both are off or negligible at defaults and a resting param is an untested operator. The source and mirror now share a deterministic inner-3×3-emitted drainage tree whose parents come from rebuild-only ±2/±3 windows in a wider direct-indexed halo (default 9×9 emit / 15×15 roll), plus the old random links. Tree connector Z is exact and ledge-free; tree and random capsules are spatially culled from the cached rebuild. Fixed 2026-07-29: its box query used to return CarveOnly because a shaft merely existed within a Spacing*1.6 halo — true almost everywhere at ShaftSpacing 55 / ShaftDensity 0.6, hence 0 of 60 tiles. It now publishes an isolated interval for tree and random capsules (same row-major cell order ⇒ same VoxelHash::Pair, so symmetry of Pair() is not assumed), with Z exact and XY conservative; the ledge and converter decide their own effects. The sampler was also widened from ±48 voxels to ±440. Every proved tile is brute-forced over its full lattice, and the test reports rebuild-vs-hot cache cost.
VoxelForgeOpStackIslandTest.cpp	VoxelForge.OpStack.FloatingIslandEquivalence	The port that runs the stack backwards — void + fill vs rock + carve, same classes with the opposite sign. Counts interior-solid and open-void samples separately (on this archetype an aggregate "N solid" is dominated by the seal bands and says nothing about the islands). Counts AllSolid and AllAir verdicts separately too: AllAir is the one no cave archetype could ever prove, and it is the entire perf argument here.
VoxelForgeOpStackMazeTest.cpp	VoxelForge.OpStack.MazeEquivalence	The 8-op Maze stack: decomposition, purity across workers, a 64-seed spanning-tree/connectivity audit, corridor morphology, cache rebuild-vs-hot timing, and brute force on every box verdict the stack emits. Latest audit: 0 tree edge-count violations, 0 tree-disconnected, 0 Maze-disconnected; interior degrees d1=15.91%, d2=36.60%, d3=31.73%, d4=12.95%, d5=2.56%, d6=0.25%, mean 2.504 versus a cubic grid's degree-6/mean-6.000; runs min=1 / median=1 / p90=3 / max=18. Latest focused cache timing: 1.436 μs rebuild, 0.150 μs hot call; final namespace timing: 1.130 μs rebuild, 0.145 μs hot call. Latest box audit: 104 proved, 152 Mixed, 138,424 voxels, 0 violations.
VoxelForgeStrateParamCoverageTest.cpp	VoxelForge.Determinism.StrateParamBlendCoverage	The X-macro guard (added 2026-08-17). FStrateGenerationParams::Lerp blends the hand-written VF_STRATE_PARAM_FIELDS list, not the struct — so a field added to one and not the other compiles, tests green, and silently takes its default inside every Gradient/Interleaved transition band. This expands the X-macro a third way (after LERP and SNAP), into a name list, and diffs it against the struct's UObject reflection. Pure shape test: no fixture, no world, instant. GExemptFieldNames is empty — every reflected field is covered today, and any exemption must be written down as a decision. Stakes rise with the world composer, which intends to invent parameter sets through this same Lerp (COMPOSER-NOTES.md).
VoxelForgeComposerParameterRollTest.cpp	VoxelForge.Composer.ParameterRoll	Asset-Registry corpus audit + complete per-archetype spread/exclusion/clamp table; asserts bit-identical deterministic rerolls and same-archetype parents; measures 64 transient candidate strates with VF_MeasureStrate plus the exact unsnapped arrival→departure law; brute-forces every rolled production box verdict. World-scale run: 1,422 applications / 168 distinct fields; 36/64 survival, 60 non-vacuous, 58 largest-component, 40 exact-law passes; 1,411 Mixed + 731 AllSolid + 418 AllAir = 1,149 proved boxes, 1,529,319 lattice voxels checked, 0 violations, 148.387 s.
″	VoxelForge.Composer.TerrainDetailLiveness	Fixed 4,096-point GetDensityAt lattice on the TunnelNetwork slot; changes one terrain-detail group at a time with an empty terrain-op pool. Proves 9 live groups / 23 fields and 3 dead groups / 11 fields; all 12 rows must match.
VoxelForgeComposerPromotionTest.cpp	VoxelForge.Composer.Promotion	Re-measures the 12 project/default members, simulates five deterministic 24-candidate seasons with normalized measured-metric novelty (<0.20), cap 6, cumulative JSON promotion, provenance counts, corpus-hash checks, fresh-load gate verification, spread/survival reporting, and deliberate stale-metric corruption. The final landing validation passed the strict existing gates; no assertion was weakened.
VoxelForgeComposerStructureRollTest.cpp	VoxelForge.Composer.StructureRoll	Rolls root polarity → legal shape source → polarity-derived conversion → 4–8 declaration-legal modifiers → mandatory structural posts; blends the six native parameter families independently, measures 64 novel stacks, captures the same grid for the deterministic filled/contour XZ/XY preview, runs a separate step-1 radius-64 ROI pass for the 33 survivors centred on LargestComponentPoint, checks exact arrival→departure connectivity, rerolls every recipe/stack for determinism, and brute-forces every uniform box verdict. World-scale run: 33/64 survival (51.6%), 64 distinct recipes, 0 invalid recipes, 715 proved custom boxes / 951,665 lattice voxels / 0 violations, blank plan/card 4/33→5/33, 174.854 s, 0 refusals.
VoxelForgeComposerShowcaseTest.cpp	VoxelForge.Composer.Showcase	Exhausts the bounded parameter-roll set (seeds 0, 7331, indices 0–63), excludes multi-region rolls while the lateral gate is off, and measures every missing-family candidate in all six interior target slots at step 4 / radius 256 / MaxCells=8,000,000. Hard gates are non-vacuous, largest air share ≥ 0.50, and exact unsnapped arrival→departure connectivity; selection score is floor-area fraction + clearance tie-break + projected-surface tie-break. It asserts roll/manifest determinism, density sign, zero WorldRadiusVoxels, bit-identical metric reruns, and writes one alphabetized card per archetype to Saved/VoxelForge/Showcase/index.html, with step-1 radius-64 filled/contour plan + vertical ROI images centred on LargestComponentPoint. The final landing regeneration evaluated 256 rolls (82 eligible single-region, 174 skipped multi-region), produced 7 fine renders, 1 refusal, 0 blanks, and retained a diagnostic hard-gate survivor set of 0/8.
VoxelForgeComposerSeasonTest.cpp	VoxelForge.Composer.Season	Existing compose/review/393,216-sample round trip plus schema hash tamper rejection, two independent runtime manager/generator instances, season-authoritative seed/spine/radius, unset-season regression, and brute-force verification of every sampled non-Mixed recipe tile verdict (up to 64).
VoxelForgeComposerCorpusFreeTest.cpp	VoxelForge.Composer.CorpusFree	Shares each structure recipe across today's corpus blend, naive independent uniform rolls, and constraint-sampled rolls. The completed equal-arm world-scale run uses 16 candidates per arm, step 4 / radius 256 / MaxCells=8,000,000, fixed passage-law mouths, and 40 box probes per candidate. Result: 10/16, 9/16, 8/16 survival; survivor feature-scale ranges are 8..268, 8..60, 8..92 voxels. Box checks: 185/246,235, 260/346,060, 299/397,969 proved/voxels, 0 violations in every arm; constraint parameter and box-stop violations were also 0.
VoxelForgeLayoutOrderIndependenceTest.cpp	VoxelForge.Determinism.LayoutOrderIndependence	Builds a known transient soft-pointer pool, then rebuilds it in original, reversed, and swapped orders. Requires a non-empty layout and passage set, and compares every slot's definition/Z/height plus passage endpoints, landing descriptors, control geometry, and bounds bit-for-bit.
VoxelForgePassageOpenSpaceTest.cpp	VoxelForge.Determinism.PassageLandsInOpenSpace	Uses the real fixture density path to check both generated mouths against independent source queries (Maze/VerticalShafts/FloatingIslands footings are probed on the archetype stack built without a strate manager, i.e. without passage carving), then audits all inter-strate landing ends: body-derived room dimensions, final-density flat-floor slope, local floor/join geometry, seal containment, hot-call/rebuild timing, and targeted ClassifyTile box soundness. Reports source-fit/refused mouths and per-archetype landing slopes; fails on any floor, join, seal, or box violation.
VoxelForgeStrateConnectivityTest.cpp	VoxelForge.Generation.StrateConnectivity / VoxelForge.Generation.StrateConnectivityRefinement / VoxelForge.Generation.VerticalShaftSeamFreedom	Bounded strate metrics with density-polarity and solid-gap controls, deterministic route rechecks, and refinement sweeps. The refinement test uses the bounded 4-chunk density fixture, fits each measurement AABB to the arrival/departure mouth pair plus three shaft spacings (the prescribed local tree fallback), and caps the fitted control at 120,000,000 cells. It reports exact before/after seed-6 cell counts, reruns every negative with the fitted margin doubled, measures tree orphan candidates/path reachability and roughness-bubble proxies, asserts mouths remain inside the deterministic shaft feature core (the exact axis is an unsupported open cylinder), checks source/mirror physical paths, and requires 16/16 effective arrival→departure results across the 16 VerticalShafts seeds. Margin-binding negatives are reported as measurement limits, never as gap findings. The shaft seam test re-evaluates cell-boundary positions after warming distinct neighbouring chunk contexts.
VoxelForgeMazeSeamTest.cpp	VoxelForge.Generation.MazeSeamFreedom	Re-evaluates 42 cell-boundary probes through GetDensityAt after warming six different neighbouring chunk contexts; must report 0 mismatches. The Maze source's 2×2×2 lower-node window is deliberately local; no wide collect is involved.
VoxelForgeClipmapNoOverlapTest.cpp	VoxelForge.Streaming.ClipmapDesiredTilesNoOverlapCoverage	Sweeps 5,145 cases (343 centres with negative coords and every parity × 5 radius/level/render-distance settings × 3 vertical clamps): zero overlapping desired pairs AND coverage ⊇ the frozen 7486c29 selector. Failed on 7486c29 (1,022,679 overlapping pairs) as intended.
VoxelForgeCollisionDesiredTilesTest.cpp	VoxelForge.Streaming.CollisionDesiredTiles.PawnAndAnchors	Checks the pawn collision box stays within its configured radius, includes support tiles below, and unions an independent anchor box at its authored XY/Z extents.
VoxelForgePreEditDensityCacheTest.cpp	VoxelForge.Determinism.PreEditDensityCacheCarveParity	Captures one exact 35³ L0 pre-edit lattice, applies 16 deterministic random carves cumulatively, and requires each cached remesh's complete geometry hash to match full GetDensityAt regeneration; also requires non-empty carve geometry.
VoxelForgeDensityBlockEquivalenceTest.cpp	VoxelForge.Density.OperatorBlockMatchesScalarGrid	Block evaluation (EvalBlock after BuildActiveOpList pruning) vs scalar, bit-identical: 5.1M mesher-grid samples (6 seeds × 8 archetypes × levels 0–5, with edits) + 300k direct EvalBlock samples. Scopes voxel.UseFusedEvaluator=0 so the real block path runs. An injected optimistic FPassageCarveOp::EffectOverBox produced 5,612 mismatches.
VoxelForgeWorldEdgeSealTest.cpp	VoxelForge.Generation.WorldEdgeSeal	Positive samples outside the radius across every fixture strate, bit-identical interior negative control against radius 0, monotonic smooth-ramp check, radius-0 no-op, radial ClassifyBox/T1.d proofs brute-forced for every reported voxel, and synthetic plus generated near-rim passage coverage. Emits one aggregate summary with proved-box and voxel counts.
VoxelForgeCorrectnessRoundTest.cpp	VoxelForge.Determinism.DiffApiBoundary / DiffLayerIdentity / EmptyPassageVersion / SurfaceBiomeCacheIdentity / TileCacheContextSwitch / ZeroTransitionBlend	Regression coverage for the cold-audit correctness fixes (diff-layer API edges, cache identities, empty-passage layout version, zero transition blend).
VoxelForgeDescentCorridorTest.cpp	VoxelForge.Descent.OwnerPassageCorridor / VoxelForge.Descent.OwnerSeedSweep	Samples the authored A-to-B passage as a body-sized walking corridor in the final owner field.
VoxelForgeDetSinCosTest.cpp	VoxelForge.Determinism.DetSinCos	Pinned contract for VoxelMath::DetSin / DetCos / DetSinCos.
VoxelForgeIsFiniteTest.cpp	VoxelForge.Math.IsFiniteExact	Bit-exact equivalence of the generation-path finite predicate (VoxelMath::IsFinite).
VoxelForgeLargeSeedTest.cpp	VoxelForge.Determinism.LargeSeedSurvives	AUDIT C1: the world must still be a world at a large seed (bounded VoxelHash::SeedOffset).
VoxelForgeLateralRegionsTest.cpp	VoxelForge.Composer.LateralRegions	Tier 4d lateral region partition, density blending, conservative box proofs, and the arrival→departure gate (asserts VF_LateralRegionsAreShippable stays false while the seam rate is imperfect).
VoxelForgeOpStackChannelTest.cpp	VoxelForge.OpStack.ChannelDAG	Channel/resource declarations are executable stack-assembly metadata (FVoxelOpStack::ValidateChannelOrder).
VoxelForgeScaleDiagnosisTest.cpp	VoxelForge.Composer.ScaleDiagnosis	Measurement-only scale diagnosis for the player-fit showcase.
VoxelForgeSealedSolidProofTest.cpp	VoxelForge.Determinism.SealedSolidProofSoundness	Sealed-solid tile proof soundness and invalidation (one-sided: may say false too often, never a wrong true).
VoxelForgeTilePostReachTest.cpp	VoxelForge.Correctness.TilePostReachProof	The tile-reach proof must fail loudly when its envelope is deliberately made too small.
VoxelForgeVerticalStrateReachTest.cpp	VoxelForge.Streaming.VerticalStrateReach	Surface-strate streaming keeps the ground visible when the pawn is high in the same strate.
VoxelForgeWormBlockSkipTest.cpp	VoxelForge.Determinism.WormBlockSkipSoundness	Soundness and coverage of the worker-local worm N1 block proof (voxel.WormBlockSkip).
VoxelForgePlayerFitWindow.h	—	Shared measurement-window policy for player-fit diagnostics (test/editor side only).

3.13 Core runtime integration (rounds 2–5)

Scale symbols: AVoxelWorld::CoreVoxelSizeCm is the opt-in per-world Core size setting and AVoxelWorld::GetActiveVoxelSizeCm() is the authoritative runtime conversion. CoreTileVoxelCount in the public Core API is 32 voxels per tile. UVoxelContentManager::MeasurePlacementCostForValidation is a headless diagnostic only; it measures placement-grid cell queries and steady manager update cost without changing normal spawning. FloatingIslandTileListAudit.cpp and BuildFloatingIslandTileListAudit.ps1 under WorldAssemblerM3/Round5 hold the candidate-list benchmark and dropped-feature negative control. See ARCHITECTURE §8.22.

The public Core API is linked as the VoxelForgeCore runtime module, with canonical implementation sources still under Standalone/. UBT validates the 18-row manifest and its shims; BuildHost linked the module and passed CheckCoreSymbols.ps1 against the actual shim objects. See Standalone/UNREAL_INTEGRATION_REPORT.md for build and headless evidence and the run ledger.

World assembler field types and AuditHeightfieldBounds, AuditHeightfieldShelfThickness, and AuditHeightfieldRoute are declared in Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h and implemented in Standalone/Core/src/WorldAssemblerInternal.h. FloatingIslandRecipeV1, FloatingIslandManifestV1, FloatingIslandFieldV1, AuditFloatingIslandBounds, AuditFloatingIslandRoute, and AuditFloatingIslandThickness are in the same public header; their canonical implementation is Standalone/Core/src/FloatingIslandsInternal.h. M3 round 2 added geometry version 2's thick crust, lobed roots, bounded detail and arched spans while preserving version-1 field and hash behavior. The standalone audit driver remains under Standalone/Research/WorldAssemblerM3/Round1/FloatingIslandsAudit.cpp; round-2 matched capture source and results are under Standalone/Research/WorldAssemblerM3/Round2/. RefineLod8NativeCap in Standalone/Core/src/VoxelForgeCore.cpp replaces coarse LOD8 ceiling surfaces with the planned 2D cap field while retaining ceiling skirts. The standalone SurfaceWorld plan composer (AttachRound1WorldAssemblyPrototype) lives in Standalone/Source/WorldAssemblyPrototype.h, and the streaming benchmark/hash pipeline (RunPipelinedStreamingBenchmark, HashTileRows) in Standalone/Source/StreamBenchmarkPipeline.h; both are shared by the D3D11 viewer (StandaloneViewer.cpp, which keeps the capture/audit entry points) and the Linux headless tool (StreamBenchmarkHeadless.cpp, built by Standalone/BuildLinux.sh; see Standalone/Research/WorldAssemblerM3/Linux1/REPORT.md).

RunStandaloneWorldExport in VoxelForgeExploreCommandlet.cpp serializes owner assets on the game thread to schema-v1 JSON. The adapter parses it through ResolvedWorldSnapshot::FromJson and keeps UObjects off Core workers. The runtime switch is AVoxelWorld::bUseVoxelForgeCore (default false), with independent CoreClipRadius=3 and CoreMaxClipLevel=8; it does not read or mutate the old clip settings or assets.

When enabled, AVoxelWorld uses Core desired keys and priorities, compiles/generates through Unreal tasks, carries Epoch through the existing MPSC result queues, and uploads converted payloads through RealtimeMesh and its collision cook. Core voxel coordinates use the size resolved from CoreVoxelSizeCm (25 cm by default); Core tile keys remain in 32-voxel units, and mesh vertices are in centimetres. Legacy brush dimensions and density strength are converted from the 12.5 cm owner grid using the resolved Core size, preserving their physical effect. SurfaceWorld owner-chunk mapping uses the owner/Core ratio as well. Edits use sequenced applyEditTransaction calls after in-flight Core work drains, then regenerate Core's affected keys under a new epoch. Existing streaming anchors participate; the headless move proof covers CollisionOnly policy.

The reusable BuildWorldAssemblyFeatureTileListV1 accepts conservative inclusive feature bounds. ScopedWorldAssemblyFeatureQueriesV1 replaces the island-only ShapeWorld worker context: meshing, derived shells, decoration cells and landmark columns share its nestable worker scope. Recipe/plan identity and an inclusive domain guard each query; outside queries fall back to the full evaluator. See ARCHITECTURE §8.23 and WorldAssemblerM3/Round6/REPORT.md.

Symbol	Canonical file	Role
WorldAssemblyFeatureTileListV1, WorldAssemblyFeatureGroupBoundsV1, WorldAssemblyFeatureQueryV1	Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h	Stable-order candidates, optional exact value-side group certificates and borrowed recipe/plan identity. Old island names remain aliases.
ScopedWorldAssemblyFeatureQueriesV1::{find,ScopedWorldAssemblyFeatureQueriesV1}, WorldAssemblyFeatureTileListV1::candidateEvaluationUseful	Standalone/Core/src/WorldAssemblerInternal.h / public header	Worker-local domain, cost hint resolved once per query, forced validation, nested restoration and full-scan fallback; replaces ShapeWorld's island context.
Heightfield2D::buildFeatureTileList, world_assembly_detail::FeatureRange	Standalone/Core/src/WorldAssemblerInternal.h	XY bounds for column writers; exact no-op bounds for finite boxes/shelves; canonical operation order.
FloatingIslandFieldV1::{solidSupportBounds,buildFeatureTileList,densitySubvoxels}	Standalone/Core/src/FloatingIslandsInternal.h	Finite support declarations, root-aware distance certificates, automatic shared-scope consumption.
WorldAssemblyFeatureColumnRangeV1, BuildWorldAssemblyFeatureColumnRangeV1	Public Core header / Standalone/Core/src/WorldAssemblerInternal.h	Conservative column support union for air-base families; invalid bounds are unknown.
VF_ContentFeatureQueries, VF_ConstrainContentMarch	Private/VoxelContentManager.cpp	Immutable queries prepared per cell/landmark; skips proven air while preserving march phase and exact crossing refinement.
UVoxelContentManager::MeasurePlacementCostForValidation	Private/VoxelContentManager.cpp	Authored/populated full-versus-candidate transforms, canonical anchor checks, batch and isolated HISM application cost.
UVoxelContentManager::ApplyRegion	Private/VoxelContentManager.cpp / Public/VoxelContentManager.h	Normal region application retains landmark footprints; its default-true footprint flag isolates the temporary populated validation fixture.
RunCoreSharedFeatureCostAudit, RunCoreContentPlacementCostAudit	Source/VoxelForgeEditor/Private/VoxelForgeExploreCommandlet.cpp	Paired owner-plan tile/shell timings and hashes, placement metrics and transient BuildHost plan exports.
TileGenerationOptions::useAssemblyFeatureQueries, TileGenerationStats::{featureListMilliseconds,farShellMilliseconds}	Public Core header / Standalone/Core/src/VoxelForgeCore.cpp	Default-on candidate route, full-scan validation control and stage timing; no identity change.
SharedFeatureListAudit.cpp, BuildSharedFeatureListAudit.ps1	Standalone/Research/WorldAssemblerM3/Round6/	Owner-plan/stress hashes, shared-scope probes and deliberately dropped needed features.

-coreworldtest=1 in the BuildHost editor commandlet validates initial tiles, expected collision bodies/empty tiles, anchor movement, a carve transaction, travel to the B landing and native surface strate, full desired visual-key coverage, neighbour/LOD face coverage, and W1/W8/W16 hash parity. -coreworldassembly=PATH supplies a reviewed manifest transiently for this test. The native surface probe samples Heightfield2D directly from the Core snapshot; every one of its 2,553 expected visual tile hashes is compared with an independent standalone Core reference. The 125 collision-desired surface tiles are checked for expected cooked bodies or empty geometry. VoxelForge.Determinism.CrossPlatformDigest remains the standalone legacy digest check. Switch-off was reviewed at the source branch and hash boundary; there is no separate flag-off actor replay. See the report for exact hashes, timing, run ledger, and owner-editor instructions. Core remains opt-in and the legacy path remains default.

Round 4 adds a temporary SurfaceWorld density bridge in ShapeWorldInternal.h. SurfaceWorld samples, including biome resolution and terrain operations, route through the copied owner evaluator at full resolution; the Core edit layer is applied afterward. Surface density hashes match the owner field across the tested LOD0–LOD3 tiles, and the BuildHost actor layout identifies Biome_Surface_Plain at the surface travel point. The CPU bridge costs approximately the legacy field route: 23.085 s wall / 180.562 worker-seconds for the matched 1,294-tile CPU view.

Round 5 adds the native surface route. UVoxelSettings stores canonical reviewed manifest JSON and its Core digest. The SourceWorldAssemblyManifestJson file picker plus ImportWorldAssemblyManifestJson editor button populate the cooked data asset. The Core adapter requires an exact unique match for every planned SurfaceWorld stratum and adds the canonical plan to the resolved Core snapshot. GetCurrentSeasonContentHash() includes this digest only while bUseVoxelForgeCore is enabled; disabling Core retains the legacy generation route and legacy content hash. The collision gate defers out-of-desired-set Core support tiles until Core region compilation admits them, so collision work cannot publish a competing tile before the native surface region snapshot. Existing cave Core strates still use the no-manifest snapshot path.

Round 6 corrects the Core 25 cm ↔ legacy 12.5 cm boundary in VoxelWorld.cpp, VoxelContentManager.cpp, and VoxelAtmosphereManager.cpp. VoxelMarchingCubesMesher now exposes GeometryVoxelSizeCm so Core geometry is emitted at 25 cm while legacy stays at its 12.5 cm default. The Core bridge adapts carve/fill signs and scales Blueprint brush radius, extent, falloff and strength. Standalone/Core/src/FarShellsInternal.h subdivides LOD7+ far-stratum repairs, and Standalone/Core/src/VoxelForgeCore.cpp enables a guarded heightfield Z-band path for unhashed native tiles, combining ground/cap heights with intersecting bounded 3D feature extents; overlapping edits keep the full mesh path. The BuildHost commandlet adds height-anchor agreement, brush sign/size, geometry and per-tile-kind pawn-lag checks; see round 6 in Standalone/ASSEMBLER_M1_REPORT.md.

M2 round 3 adds EVoxelForgeCoreMesherRecipe / CoreMesherRecipe in Source/VoxelForge/Public/VoxelWorld.h, defaulting to MarchingCubesV1; VoxelWorld.cpp maps opt-in hybrid choices to Core MesherRecipe values and adds the selected version to Core content identity. V1 retains the original feature-aware DC path. V2 keeps MC topology and snaps only eligible interior LOD0 edge roots to exact type-2 box planes; the mesher support is in VoxelHybridSharpMesher.h and VoxelMarchingCubesMesher.cpp. Coarse LODs and roots whose incident cells reach a tile border remain MC. VoxelForgeExploreCommandlet.cpp owns the five production-mesher fixtures, border probes and Core actor collision contacts. BuildHost evidence and remaining doorway transition failures are recorded in Standalone/UNREAL_INTEGRATION_REPORT.md and Standalone/Research/WorldAssemblerM2/REPORT.md. Likely compile touchpoints are VoxelWorld.h/.cpp, VoxelMarchingCubesMesher.h/.cpp, VoxelHybridSharpMesher.h, Standalone/Core/include/VoxelForgeCore/VoxelForgeCore.h, Standalone/Core/src/VoxelForgeCore.cpp, and the editor commandlet/build rules.

OwnerWorldLoader.h now reads SlabParams, MazeParams, VerticalShaftParams, and FloatingIslandParams. The shape-world evaluator still lacks their native terrain fields: FlatPlain, CrystalChamber, Maze, VerticalShafts, FloatingIslands, and water presentation remain missing or approximate. Passage type/style chains are extracted from manager control points, but Worm and Cascading currently fail the centerline walkability audit. Gradient, Hard, and Interleaved transitions produce the same Core probe hash and are not faithfully represented. See the round-4 coverage table and small matched captures and probe artifacts.

World Assembler M3 Round 7 adds a shared far-horizon path. WorldAssemblyPlanV1::strates is the SurfaceWorld declaration: World::generateTile evaluates native ground on a globally aligned grid with step min(tile step, 128 voxels), and cap on the shared 128-voxel grid. It clips both surfaces to the tile and to cap >= ground, and replaces nearby upward coarse-MC ground faces. An unedited SurfaceWorld tile at LOD7/8 that intersects a native surface plan and no island plan uses those profile surfaces instead of derived far stratum/connector repairs. Tiles with edits or intersecting FloatingIslands plans keep the canonical field and repairs. FloatingIslands keeps the shared 3D field and repair path, with a common 256-voxel axial station/ring grid at LOD7/8; closer LODs retain 128-voxel stations. TileGenerationStats reports classification, column, meshing, shell and horizon time, repair field calls, skipped repairs and replaced triangles. farHorizonVersion salts far mesh/payload/topology hashes only. The BuildHost commandlet owns warmed eight-key timings and the exact-density-root LOD7/8 agreement audit with its datum-offset negative control.

World Assembler S4 repairs the planar cap datum and far tile selection. Heightfield2D::farSurfaceCapHeightSubvoxels clips the rendered cap to (topChunkZ + 1) * 32 voxels while preserving Heightfield2D::point density; capHeightBounds provides the matching conservative bands. World::desiredTiles adds only non-overlapping cap-height keys at LOD4–8, and RefineFarNativeCap emits the globally aligned cap surface (16 voxels at LOD4, 128 at LOD5–8). Evaluator v5 opts into this render-surface contract; older serialized evaluator versions retain their cap behavior. Far recipe v2 salts mesh/payload/topology from LOD4 upward. The standalone viewer audit measures cap-band census, near-root agreement and upward-ray coverage; the editor BuildHost check measures the staged owner actor and W1/W8/W16. VoxelWorld::ApplyMeshToTile uses explicit section ranges for ground and cap. Likely compile spots are the Core public/internal heightfield API and VoxelForgeCore.cpp, VoxelWorld.cpp, the editor commandlet, and the standalone viewer. See ARCHITECTURE §8.25 and Standalone/Research/WorldAssemblerM3/Round8/REPORT.md.

3.14 Cold streaming admission and apply trace — World Assembler S7 / M3 Round 11

AVoxelWorld::UpdateChunksAroundPosition writes a scheduler_admission record on each submission pass, plus scheduler_skip for core-readiness bypasses and all-loaded latches that still have missing work. The admission record includes desired/missing/pending keys by LOD, task caps, submitted attempts, stop level, decline reason, bCoreRegionCompilePending, pending-result estimate, and cumulative worker-task time. Rule codes are 1=full task cap, 2=near reserve, 3=all-loaded latch, 4=inner LoadTile/LoadCoreTile rejection, and 5=desired work still missing with apparent capacity. This is the trace used to separate the old near-reserve stop from completed-but-unapplied results counted as active. The default admission count uses queued/running ActiveTaskCount; voxel.StreamingLegacyPendingResultCap=1 restores the old pending-result cap. The negative-control harness sets that together with voxel.StreamingDynamicNearReserve=0. ProcessPendingChunks still records result draining, visible-mesh applies, per-LOD counts and budget use; direct tile events separate worker queue, task time, result queue and game-thread apply. collision_ready records RealtimeMesh submit-to-body update latency. The per-frame running_workers sample aliases short task bursts, so use the cumulative task intervals for worker-seconds. VoxelForgeExploreCommandlet.cpp drives the staged owner-plan trace and moving actor check. See ARCHITECTURE §8.27–8.28 and Standalone/Research/WorldAssemblerM3/Round11/REPORT.md.

3.15 Moving region admission and result-backlog safety trace — World Assembler S8 / M3 Round 12

core_region_compile_request/start/complete record why the desired region is being built (initial set, player-center move, or same-center desired-set change), center delta, pending tiles, compile wall time, accumulated pending interval, independent submissions and dependent-key declines. While a compile is pending, scheduler_skip.reason=core_region_compile_pending records per-LOD missing counts, motion and speed. The default concurrent mode should have no global region-pending skip; its negative control is voxel.CoreRegionConcurrentAdmission=0.

walkable_gate logs every support-center change and whether all nine required LOD0 collision tiles are ready there. result_queue_frame samples queued results, payload bytes, active tile tasks and the cap; result_queue_summary stores peak queue length/bytes and admission stops. These counters include slow-apply, teleport and high-speed controls added to VoxelForgeExploreCommandlet.cpp and Tools/TestVoxelForgeCoreWorldHost.ps1. Keep the cap negative control (voxel.StreamingResultBacklogCap=0) separate from the region-gate control. Round12 found 11/11 ready support centers at 6 m/s and 8/113 immediately ready at 60 m/s with a 400 m teleport; see the traces under Saved/BuildHost and Standalone/Research/WorldAssemblerM3/Round12/REPORT.md.

3.16 Velocity-scaled support-ring lookahead — World Assembler S9 / M3 Round 13

voxel.StreamingCollisionLookahead defaults on; 0 is the negative control. The shared GetStreamingHeadingStep uses actor-local motion, including vertical speed. The support tile from GetPlayerSupportTile is the reference for both the active 3x3 critical ring and up to two future 3x3 rings. GetStreamingCollisionLookaheadTiles aims 350 ms ahead, rounded up to whole LOD0 tiles and capped at two. Prediction only promotes keys already inside the desired clipmap. The collision_lookahead trace records stream/support centers, direction, speed, ring count and any missing desired keys. VoxelForgeExploreCommandlet.cpp and Tools/TestVoxelForgeCoreWorldHost.ps1 accept a movement vector so the same trace covers horizontal and vertical travel. See ARCHITECTURE §8.30 and Standalone/Research/WorldAssemblerM3/Round13/REPORT.md.

3.17 LOD8 planar far-horizon sampling — World Assembler S10 / M3 Round 14

Native planar SurfaceWorld horizon refinement uses the LOD8 marching-cubes step for its interior grid (512 voxels / 128 m at 25 cm), retaining globally aligned 128-voxel boundary strips for tile and LOD joins. LOD4–LOD7 keep their previous grids. Far recipe version 3 salts changed LOD4–LOD8 mesh outputs; density and LOD0–LOD3 output are unchanged. The ground and cap passes use the same coordinate lattice but still sample separately. The per-thread column cache remains local to each worker; no cross-worker page cache was added. Diagnostics report exclusive column, MC, ground, cap and output-assembly costs, plus opt-in duplicated LOD8 XY evaluations. The Standalone-only --far-horizon-lod8-step=128 restores S9 sampling for the negative control. See ARCHITECTURE §8.31 and Standalone/Research/WorldAssemblerM3/Round14/REPORT.md.

3.18 Streaming worker supply and ready queue — World Assembler S12 / M3 Round 16

AVoxelWorld::LoadTile and LoadCoreTile retain the existing UE::Tasks::Launch background priorities (BackgroundHigh for near work, BackgroundNormal for horizon work). The shared scheduler now sizes streaming admission to the TaskGraph background worker count by default (voxel.StreamingBackgroundWorkerCap=1) and admits a bounded ready queue of up to one worker-set (voxel.StreamingReadyQueueDepth=8 on the 8-background-worker host). This lets UE dispatch the next already-admitted task as a worker becomes free without waiting for the next actor tick. Setting the worker cap to 0 restores the prior logical-core cap; setting queue depth to 0 restores one-slot-per worker admission. The moving near reserve grows with the ready queue, coarse/horizon work remains under its separate cap, and moving LOD0 admission is limited to the actual worker slots so far work cannot occupy reserved headroom. bStreamingPlayerMoving is a game-thread scheduler snapshot used by both admission helpers. worker_backend_config, streaming_worker_cap_readback, and scheduler_admission record the pool counts and effective CVar values. Per-tile trace rows record submit/start/end times and the OS worker thread ID. No tile generation, mesh, density, collision, or Core recipe output changes; recipe versions remain unchanged. See ARCHITECTURE §8.33 and Standalone/Research/WorldAssemblerM3/Round16/REPORT.md.

3.19 Exclusive tile cost and all-LOD column overlap — World Assembler S13 / M3 Round 17

VoxelForgeCore::TileGenerationStats now exposes classification-exclusive time and the column evaluation performed during marching cubes, ground refinement, and cap refinement. The BuildHost shared-feature audit reports these p95 stages and per-density-sample costs for owner SurfaceWorld tiles at LOD0, 1, 3, 4, 5, and 8. Standalone --profile-column-overlap opts into XY miss-coordinate capture for all LODs and reports repeated evaluations across same-LOD tiles and workers; the older --profile-far-column-overlap spelling remains an alias. --profile-column-overlap changes no generation output. Measurement-only stride and octave probes are confined to the shared-feature audit and are not runtime controls. The result and limits are recorded in Standalone/Research/WorldAssemblerM3/Round17/REPORT.md.

3.20 MC stage audit and coarse column-cache conflicts — World Assembler S14 / M3 Round 18

Standalone/Source/VoxelForge/Private/VoxelMarchingCubesMesher.cpp records the sampled density grid, cell classification, grid-gradient normals, edge interpolation, and vertex/dedup stream stages for the BuildHost audit. Its exact per-worker gradient memo is controlled and trace-read back through voxel.CoreMCGradientMemoization. Standalone/Core/src/WorldAssemblerInternal.h keeps the 65,536-entry worker-local column cache, using the S13 direct-map for LOD0–2 and a deterministic four-way set-associative route for LOD3–8; voxel.CoreColumnCacheDirectMapped=1 restores the S13 path for the negative control. Runtime CVar capture lives in Source/VoxelForge/Private/VoxelWorld.cpp; stage and conflict counts are reported by Source/VoxelForgeEditor/Private/VoxelForgeExploreCommandlet.cpp. The measurements, controls, and cold-path decision are in Standalone/Research/WorldAssemblerM3/Round18/REPORT.md.

4. The density pipeline (most-edited hot path)

4.1 GetDensityWithParams (TunnelNetwork) — VoxelGenerator.cpp:3749

Stage order (negative=solid throughout). Each stage's anchor:

Step	Line	What
1 — Vertical scale	3799	Stretch Z before noise (VerticalScale).
2 — Base density	3808	Everything starts solid at BaseDensity.
3 — Cave warp	3813	Domain-warp the SDF query coords (organic shapes).
4 — SDF morphology	3863	Rooms+tunnels via BuildChunkCache/EvaluateSDFCached.
4b — Surface roughness	4267	Volumetric noise near surfaces (fBM/Ridged/Mixed).
4c–4h — Terrain ops	4395	Per-room op applied near surfaces. Sub-anchors below.
· Terracing	4437	Step-like ledges.
· Layer lines	4534	Horizontal grooves (sin of Z).
· Ribbing	4564	Parallel ridges (sin of Z).
· Overhangs	4593	Low-Z-freq noise shelves.
· Cliff sharpening	4629	Amplify vertical gradient.
· Scallop	4673	Cellular erosion bowls.
· Arch/Bridge	4709	Hash-placed capsules across voids.
4d — Columns	4738	Pre-baked vertical cylinders.
4g — Domes	4766	Room-relative hemispherical ceilings.
4h — Pinch	4831	Passage bottlenecks.
5 — Worm tunnels	4905	abs(noise1)+abs(noise2), masked by distance-to-network (WormNetworkRange: braids hugging rooms/tunnels, no far-field speckle; 0 = legacy unmasked).
6 — Boundary seal	4987	Solid top/bottom shells (ApplyBoundarySeal).
7 — Inter-strate passages + landings	5008	Carve wandering passage tubes and deterministic local landing rooms, restore their support floors, then leave the final XY seal to the outer MC post (ApplyPassageModifier / ApplyPassageLandingFloorMC).

4.2 BuildSlabStack (FlatPlain / CrystalChamber) — VoxelDensityOpStack.cpp

Step	Op	What
1 — Floor surface	FSlabVoidSource	Noisy floor height (XY-pure).
2 — Ceiling surface	FSlabVoidSource	Formations hang downward (abs(noise)).
3 — Void→base density	FSlabVoidSource	Solid outside [floor,ceiling].
4 — Columns	FGridColumnMod	World-space hash grid, full-height.
5+6 — Seal + passages	AppendStructuralPost	Spine, vertical seal, passage tube/landing floor, XY seal — the same structural post as every stack.

---

5. "I want to change X" → go here

Goal	Location
Chunk size / voxel scale	VoxelTypes.h:211-213 (rebuild everything).
View distance / task budget / LOD distances	VoxelSettings.h (no recompile of logic — data asset).
LOD step mapping	LoadTile VoxelWorld.cpp:9033, effective cell selection near :9071: extent CHUNK_SIZE << Level, cells from FullResClipLevels/CoarseTileCells, Step = Extent / Cells; tile selection in VoxelClipmapDesiredTiles::Build (Private/VoxelClipmapDesiredTiles.h).
How chunks stream in/out	UpdateChunksAroundPosition VoxelWorld.cpp:6870.
Async threading / stale-result handling	LoadTile :9033, ProcessPendingChunks :7435, generation Epoch + per-request cancellation token.
Add a new cave feature / terrain op	Add enum in VoxelTerrainOpDefinition.h:36, params there, ApplyTo (.cpp:6), transport fields in FStrateGenerationParams, consume it in a new Step inside GetDensityWithParams.
Tweak room/tunnel shapes	VoxelCaveMorphology.cpp BuildChunkCache :6782 / EvaluateSDFCached :8569.
Worm tunnel behavior	GetDensityWithParams Step 5, VoxelGenerator.cpp:4905.
Strate stacking / which strate where	UVoxelStrateManager::Initialize :1164.
Publish/use an offline season	Create UVoxelSeasonAsset, set SourceManifestJson, press ImportSeasonManifestJson, then assign it to UVoxelSettings::Season.
Boundary blend between strates	GetGenerationParams :6509 + FStrateGenerationParams::Lerp (expands VF_STRATE_PARAM_FIELDS, StrateTypes.h — new fields go in that list).
Passages / landing geometry between strates	GeneratePassages :1659 + EvaluateModifierSDF :2643 + ApplyPassageModifier / ApplyPassageLandingFloorMC (StrateManager.cpp) + ClassifyTile floor guard (Generator.cpp).
Player carve/fill	CarveAtPosition/FillAtPosition VoxelWorld.cpp:10230/10239 → AVoxelWorld::ApplyModification :10248 → UVoxelDiffLayer::ApplyModification :185.
Mesh smoothness / normals	Grid-gradient in GenerateMesh (GradAt lambda), IsoLevel (h).
New slab/flat-world generator	VoxelDensityOps::BuildSlabStack + FSlabVoidSource / FGridColumnMod (VoxelDensityOpStack.cpp) + FSlabGenerationParams (StrateTypes.h:1223).
Biome placement / layout	BiomeMapParams on the strate (cell size, warp, climate freqs) + each biome's climate box. Bake AVoxelWorld::BakeBiomePreview to tune. §8.14.
What a biome does to terrain	A full archetype param override on the biome (bOverrideTerrain + SurfaceParams); surface output-blends dominant/neighbour heights in the surface stack (BuildSurfaceStack with per-biome params) and in ComputeSurfaceColumn. Caves = content/atmosphere only (determinism, §8.14).
Add a biome / biome content	New UVoxelBiomeDefinition asset → add to the strate's Biomes[]. §8.14 / §8.12.
Season reset	AVoxelWorld::ChangeSeed :8710.

---

6. Conventions & gotchas

• Density sign is the #1 source of confusion. Internally (MC) negative = solid, positive = air. Carve = subtract density (toward positive); Fill = add (toward negative). FVoxelModification::Strength negative = carve. Comments sometimes say the inverse in different layers — trust the MC convention at the mesher.
• Coordinate units: density functions take voxel coords (not cm). World↔voxel conversions live in VoxelTypes.h. Mesher converts before calling the generator.
• Espace ACTEUR / actor space: le champ de densite est en espace acteur — (0,0) = origine de l acteur AVoxelWorld, pas du monde Unreal. Tout point venant d Unreal (pion, trace, ancre) passe par AVoxelWorld::WorldToLocalCm / WorldToLocalVoxel / LocalVoxelToWorld. Regle grep : aucun / VOXEL_SIZE sur un parametre World* hors de ces trois fonctions. ⚠️ Translation seulement — rotation/echelle cassent les boites alignees sur les axes (tuiles, ClassifyBox, clipmap, culling) ; BeginPlay loggue une Error. The density field is in ACTOR space; translation only.
• Determinism: all randomness is hash-of-(coord, seed, strateIndex) — no RNG state. Same seed ⇒ identical world. Player edits are the only non-deterministic overlay.
• Async safety: background tasks must check bShuttingDown and only touch the generator/mesher (no UObject mutation). Results return via ProcessQueue. EndPlay blocks until ActiveTaskCount == 0.
• Epoch: every regeneration bumps GenerationEpoch; results tagged with an old epoch are dropped in ProcessPendingChunks. Always carry the epoch through new async paths.
• Generated code under Intermediate/ and Binaries/ is build output — never edit. *.generated.h / *.gen.cpp are UHT output for the UCLASS/USTRUCT above.
• UPackage completeness: files that call NewObject(..., GetTransientPackage(), ...) must include UObject/Package.h directly; files that do not include VoxelForgeTestFixture.h do not get it transitively.

---

7. Files NOT to touch

Binaries/, Intermediate/ — compiler/UHT output, regenerated on build. MarchingCubesTables.h — canonical reference tables, only change if switching MC variant.

---

8. Architecture & design deep-dive → ARCHITECTURE.md

Moved out of the codemap to keep this file a fast navigation index. The archetypes, (0,0) spine, disturbances, content/atmosphere, biomes, and the performance invariants (§8.10 — read before optimizing the hot path) now live in ARCHITECTURE.md. All §8.x cross-references throughout this file point there. §9 = the MULTIPLAYER model (listen-server-first, design-only) — read before touching streaming / carve / AI: terrain is never replicated (determinism = replicate seed+layout+diff events only), streaming goes multi-anchor (collision-only vs full-visual policy per anchor), carves are server-authoritative.