Upload of all files, starting point

CODEMAP.md

@@ -0,0 +1,489 @@
+# 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 22 files.
+> Comments in the code are mixed **French + English**. UE module = `VoxelForge` (Runtime).
+
+---
+
+## 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 = 25 cm (`VOXEL_SIZE`). |
+| 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)
+                                   ▼
+                         LoadChunk → 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
+        ├─ TunnelNetwork → GetDensityWithParams()  (rooms+tunnels+ops+worms+seal+passages)
+        │       └─ VoxelCaveMorphology::BuildChunkCache + EvaluateSDFCached  (room/tunnel SDF)
+        ├─ FlatPlain / CrystalChamber → GetSlabDensity()  (floor+ceiling+columns+seal+passages)
+        └─ + 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.1 Module & build
+| File | Role |
+|------|------|
+| `../../VoxelForge.uplugin` | Plugin manifest. One Runtime module `VoxelForge`. Beta. |
+| `VoxelForge.Build.cs` | Deps: Core, CoreUObject, Engine, **GameplayTags**, **RealtimeMeshComponent**. |
+| `Public/VoxelForgeModule.h` / `Private/VoxelForgeModule.cpp` | `FVoxelForgeModule` boilerplate (Startup/Shutdown just log). |
+
+### 3.2 Foundational types — `Public/VoxelTypes.h` (no UClass, everyone includes it)
+| Symbol | Line | Notes |
+|--------|------|-------|
+| `CHUNK_SIZE` (32), `CHUNK_SIZE_SQUARED`, `CHUNK_VOLUME` | 19-21 | Chunk dimensions. |
+| `VOXEL_SIZE` (25.0f cm) | 23 | World scale. |
+| `EVoxelFace` enum + `GetFaceDirection` / `GetFaceNormal` | 33-61 | 6 cube faces. |
+| `WorldToChunkCoord` / `WorldToLocalCoord` / `ChunkToWorldPos` | 74-104 | Coord-space conversions (handle negatives via floor/positive-modulo). |
+| `LocalToIndex` / `IndexToLocal` / `IsValidLocalCoord` | 107-131 | Flat-array 3D↔1D indexing. |
+| `SmoothStep01` | 140 | 3x²-2x³ — used everywhere for blends. |
+| `VOXEL_NOISE_SCALE` (1.25f) | 147 | Rescales UE PerlinNoise3D to ~[-1,1]. |
+| `FVoxelMeshData` struct | 157-173 | Mesher output (Vertices/Triangles/UVs/Normals). Plain C++, not USTRUCT. |
+
+### 3.3 Chunk identity — `Public/VoxelChunk.h`
+`FVoxelChunk` (USTRUCT, line 19): just a `ChunkCoord` + `GetWorldPosition()`. In a
+density-only world the chunk stores no voxels — it's a coord wrapper. Room to cache
+per-chunk info later.
+
+### 3.4 Settings — `Public/VoxelSettings.h`
+`UVoxelSettings : UPrimaryDataAsset` — the single tuning asset assigned on `AVoxelWorld`.
+| Group | Fields (line) |
+|-------|---------------|
+| Streaming | `ViewDistanceXY=16` (26), `ViewDistanceUp/Down=5` (29/32), `MaxConcurrentTasks=16` (36), `MaxMeshAppliesPerFrame=4` (40) |
+| LOD | `LOD0Distance=4` (48), `LOD1Distance=8` (53) |
+| Rendering | `VoxelMaterial` (61) |
+| Strates | `Seed` (69), `CurrentSeason=1` (73), `StratePool` (78), `FixedStrates` map (83), `TotalStrates=10` (87) |
+| Carving budget | `MaxModifications=0` (97), `MaxBrushRadius=15` (102), `MaxTotalVolume=0` (107). 0 = unlimited. |
+
+### 3.5 World orchestrator — `Public/VoxelWorld.h` + `Private/VoxelWorld.cpp`
+`AVoxelWorld : AActor` — owns everything, drives streaming. Also `FChunkResult` struct
+(VoxelWorld.h:35) = async task payload (coord, chunk, meshdata, LOD, **Epoch**).
+
+**Owned objects (UPROPERTY):** `Settings`, `Generator`, `Mesher`, `StrateManager`,
+`DiffLayer` (VoxelWorld.h:55-78). **Storage:** `Chunks` map, `ChunkMeshes` map,
+`ChunkLODs`, `ProcessQueue` (TQueue), `PendingChunkCoord` (TSet) (VoxelWorld.h:85-312).
+**Async state:** `bShuttingDown`, `ActiveTaskCount` (atomics), `GenerationEpoch`.
+
+| Method | .cpp line | Role |
+|--------|-----------|------|
+| `AVoxelWorld()` ctor | 12 | Enables Tick. |
+| `RegenerateAllChunks()` | 21 | Bumps epoch, unloads all → Tick reloads. CallInEditor button. |
+| `PostEditChangeProperty` | 45 | Editor live-edit hook. |
+| `OnObjectModifiedInEditor` | 58 | Regenerates when a strate asset is edited (if `bLiveEditStrates`). |
+| `EndPlay` | 140 | Sets `bShuttingDown`, **waits for `ActiveTaskCount`→0**, unbinds delegate. |
+| `BeginPlay` | 177 | Constructs Generator/Mesher/StrateManager/DiffLayer, wires services, seeds. |
+| `Tick` | 220 | `UpdateChunksAroundPosition(player)` + `ProcessPendingChunks()`. |
+| `GetPlayerPosition` | 231 | Pawn position or zero. |
+| `GetLODForChunk` / `LODToStep` | 242 / 268 | Distance→LOD (0/1/2) → step (1/2/4). |
+| `IsChunkInRange` | 275 | View-distance test. |
+| `ProcessPendingChunks` | 301 | Drains ProcessQueue under per-frame budget; **discards stale epochs**; applies meshes. |
+| `UpdateChunksAroundPosition` | 362 | Builds desired set, sorts by distance, loads/unloads, handles LOD changes. |
+| `LoadChunk` | 445 | Budget check → `UE::Tasks::Launch` background gen+mesh; RAII task guard. |
+| `UnloadChunk` | 493 | Destroys mesh component + map entries. |
+| `ApplyMeshToChunk` | 503 | Get/create RealtimeMeshComponent, upload geometry, assign material. |
+| `GetStrateAtPosition` | 679 | Gameplay query → strate index. |
+| `CarveAtPosition` / `FillAtPosition` | 691 / 709 | Build `FVoxelModification` → DiffLayer → RemeshDirtyChunks. |
+| `ClearAllModifications` | 726 | Clears diff layer, regenerates. |
+| `ChangeSeed` | 740 | **Season reset**: new seed everywhere, clear diffs, bump season, reload. |
+| `GetCurrentSeed` / `GetCurrentSeason` | 784 / 789 | Accessors. |
+| `RemeshDirtyChunks` | 798 | Re-queue loaded chunks for async re-mesh (no visual pop). |
+
+### 3.6 Density generator — `Public/VoxelGenerator.h` + `Private/VoxelGenerator.cpp`
+`UVoxelGenerator : UObject` — lightweight; holds `Seed`, and injected services
+`StrateManager` + `DiffLayer` (both nullable). This is **where terrain shape lives.**
+
+| Symbol | .cpp line | Role |
+|--------|-----------|------|
+| `FractalNoise3D` (static) | 25 | fBM (layered Perlin). |
+| `RidgedNoise3D` (static) | 55 | Ridged multifractal — craggy. |
+| `CellularNoise3D` (static) | 101 | Worley/cellular — grotto/scallop. |
+| `ApplyBoundarySeal` (static) | 170 | Solidifies strate top/bottom shells. |
+| `ApplyPassageCarving` (static) | 197 | Punches passages/elevator through the seal. |
+| `InitializeSettings` | 211 | Copies seed from settings. |
+| **`GetDensityAt`** | 218 | **Entry point.** Picks strate + generator type, dispatches, adds diff offset. |
+| **`GetDensityWithParams`** | 277 | TunnelNetwork pipeline (~1000 lines). See §4. |
+| **`GetSlabDensity`** | 1306 | FlatPlain/CrystalChamber pipeline. See §4.2. |
+
+### 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:46): `Sphere`, `Ellipsoid`, `Capsule`, `RoundedBox`,
+  `TaperedCapsule`, `SmoothMin`, `SmoothMax` — all FORCEINLINE SDF primitives.
+- `namespace VoxelHash` (h:158): `Mix`, `Cell`, `Pair`, `ToFloat01`, `ToFloatSigned`
+  — deterministic hashing for room/tunnel placement (no storage, infinite worlds).
+- Cache structs (h:224-330): `FCachedRoom`, `FCachedTunnel`, `FCachedPit`,
+  `FCachedChimney`, `FCachedColumn`, `FChunkSDFCache`.
+- `namespace VoxelCaveMorphology`:
+  | Function | .cpp line | Role |
+  |----------|-----------|------|
+  | `BuildChunkCache` | 47 | **Phase 1** (once/chunk): collect rooms, nearest-neighbor backbone, decide tunnels, pre-bake pits/chimneys/columns, hash-roll per-room terrain op. |
+  | `EvaluateSDFCached` | 589 | **Phase 2** (per voxel): SmoothMin over cached rooms/tunnels; returns nearest room idx for terrain-op lookup. |
+  | `EvaluateSDF` | 738 | Convenience wrapper (builds temp cache) for one-off queries. |
+
+  Performance note (h:209-220): 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` | 38 | Sloped/Vertical/Spiral/Cascading/Crack passage shapes. |
+| `ESurfaceType` | 78 | Floor/Wall/Ceiling/Any (decoration placement). |
+| `EVoxelNoiseType` | 99 | FBM/Ridged/Mixed/Cellular. |
+| `ECaveGeneratorType` | 146 | TunnelNetwork / FlatPlain / CrystalChamber. |
+| `EVoxelStrateTransition` | 183 | Gradient / Hard / Interleaved boundary blends. |
+| **`FStrateGenerationParams`** | 213 | The giant TunnelNetwork param bag (rock, worms, rooms, tunnels, warp, roughness, all terrain-op transport fields, boundary seal). `Lerp()` static at 844 blends two sets at boundaries. |
+| `FStrateTerrainOpEntry` | 965 | Soft-ptr to a terrain op + Weight + Probability. |
+| **`FSlabGenerationParams`** | 1019 | Floor/ceiling heights, roughness, columns, seal — for slab generators. |
+| `FStrateDecoration` / `FStrateAmbientActor` / `FStrateCreature` | 1160 / 1192 / 1212 | Content spawn entries (consumed by future systems). |
+
+**`Public/VoxelStrateDefinition.h`** — `UVoxelStrateDefinition : UPrimaryDataAsset`
+(line 36). One asset = one strate *type*. Fields: identity, `StrateHeightInChunks`(60),
+`TransitionType`(79)/`TransitionBlendChunks`(89), `GeneratorType`(102),
+`GenerationParams`(113), `SlabParams`(124), `TerrainOperations`(147), visuals/fog/light,
+content lists, audio, `GameplayTags`(223). EditConditions show/hide param groups by generator type.
+
+**`Public/VoxelStrateManager.h` + `.cpp`** — `UVoxelStrateManager : UObject` (h:108).
+Maps depth→strate at runtime; owns passages.
+- `FVoxelPassage` (h:39): endpoints, radius, type, control points.
+- `FStrateSlot` (h:84): definition + chunk-Z range + index.
+| Method | .cpp line | Role |
+|--------|-----------|------|
+| `Initialize` | 10 | Builds the stacked layout from settings+seed (fixed slots + shuffled pool), then `GeneratePassages`. |
+| `GeneratePassages` | 146 | Deterministic passages between consecutive strates (per-type control points). |
+| `EvaluateModifierSDF` | 371 | SDF of all passages + elevator shaft at a point (for carving). |
+| `FindSlotIndexForChunkZ` | 427 | Z → layout index. |
+| `GetStrateAt` / `GetStrateIndex` | 443 / 455 | World-Z queries. |
+| `GetStrateForChunk` | 466 | Chunk → definition. |
+| `GetGeneratorTypeForChunk` | 476 | Chunk → generator type. |
+| `GetSlabParamsForChunk` | 490 | Slab params with runtime Z bounds (no blend — slabs use Hard). |
+| `GetGenerationParams` | 515 | **Blended** TunnelNetwork params (handles Gradient/Hard/Interleaved transitions). |
+| `BuildParamsFromDefinition` (static) | 771 | Base params + merge all referenced terrain op assets. The one place ops fold into params. |
+
+**`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.
+
+### 3.9 Player edits — `Public/VoxelDiffLayer.h` + `.cpp`
+`UVoxelDiffLayer : UObject` (h:77). Stores `FVoxelModification` (h:43: Center/Radius/Strength;
+**negative Strength = carve, positive = fill**) grouped by chunk in `TMap ChunkMods`.
+| Method | .cpp line | Role |
+|--------|-----------|------|
+| `SetBudget` | 10 | From VoxelSettings carving caps. |
+| `CanModify` | 20 | Budget check (no consume) — for UI. |
+| `GetRemainingModifications` / `GetRemainingVolume` | 47 / 53 | -1 = unlimited. |
+| `ApplyModification` | 63 | Enforces budget, stores in all overlapped chunks, returns dirty coords. |
+| `GetDensityOffset` | 131 | Per-voxel combined diff (smoothstep falloff, additive). |
+| `HasModifications` | 160 | Fast reject for hot path. |
+| `Clear` | 170 | Wipe all (season reset). |
+| `GetTotalModificationCount` / `GetModifiedChunkCount` | 182 / 192 | Stats. |
+
+### 3.10 Mesher — `Public/VoxelMarchingCubesMesher.h` + `.cpp`
+`UVoxelMarchingCubesMesher : UObject` (h:21). Holds `Generator` ptr, `IsoLevel=0`,
+`GradientOffset=1`.
+| Method | .cpp line | Role |
+|--------|-----------|------|
+| `GetDensity` | 11 | Local coord → world → `Generator->GetDensityAt`. |
+| `InterpolateEdge` | 28 | Linear edge crossing between two corner densities. |
+| `ComputeGradientNormal` | 48 | Central-difference gradient → smooth normal. |
+| **`GenerateMesh`** | 75 | The MC loop over cells; `Step` controls LOD sampling. |
+
+**`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` — deterministic decoration scatter (LOD0) + aesthetic water planes, per chunk. 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. |
+
+> 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.
+
+---
+
+## 4. The density pipeline (most-edited hot path)
+
+### 4.1 `GetDensityWithParams` (TunnelNetwork) — VoxelGenerator.cpp:277
+Stage order (negative=solid throughout). Each stage's anchor:
+| Step | Line | What |
+|------|------|------|
+| 1 — Vertical scale | 307 | Stretch Z before noise (`VerticalScale`). |
+| 2 — Base density | 316 | Everything starts solid at `BaseDensity`. |
+| 3 — Cave warp | 321 | Domain-warp the SDF query coords (organic shapes). |
+| 4 — SDF morphology | 368 | Rooms+tunnels via `BuildChunkCache`/`EvaluateSDFCached`. |
+| 4b — Surface roughness | 564 | Volumetric noise near surfaces (fBM/Ridged/Mixed). |
+| 4c–4h — Terrain ops | 688 | Per-room op applied near surfaces. Sub-anchors below. |
+| · Terracing | 727 | Step-like ledges. |
+| · Layer lines | 823 | Horizontal grooves (sin of Z). |
+| · Ribbing | 853 | Parallel ridges (sin of Z). |
+| · Overhangs | 882 | Low-Z-freq noise shelves. |
+| · Cliff sharpening | 918 | Amplify vertical gradient. |
+| · Scallop | 962 | Cellular erosion bowls. |
+| · Arch/Bridge | 998 | Hash-placed capsules across voids. |
+| 4d — Columns | 1053 | Pre-baked vertical cylinders. |
+| 4g — Domes | 1077 | Room-relative hemispherical ceilings. |
+| 4h — Pinch | 1142 | Passage bottlenecks. |
+| 5 — Worm tunnels | 1241 | abs(noise1)+abs(noise2) connectivity. |
+| 6 — Boundary seal | 1274 | Solid top/bottom shells (`ApplyBoundarySeal`). |
+| 7 — Inter-strate passages | 1281 | Carve passages/elevator (`ApplyPassageCarving`). |
+
+### 4.2 `GetSlabDensity` (FlatPlain / CrystalChamber) — VoxelGenerator.cpp:1306
+| Step | Line | What |
+|------|------|------|
+| 1 — Floor surface | 1317 | Noisy floor height. |
+| 2 — Ceiling surface | 1343 | Formations hang downward (`abs(noise)`). |
+| 3 — Void→base density | 1379 | Solid outside [floor,ceiling]. |
+| 4 — Columns | 1399 | World-space hash grid, full-height. |
+| 5+6 — Seal + passages | 1461 | Same seal/passage carving as TunnelNetwork. |
+
+---
+
+## 5. "I want to change X" → go here
+
+| Goal | Location |
+|------|----------|
+| Chunk size / voxel scale | `VoxelTypes.h:19-23` (rebuild everything). |
+| View distance / task budget / LOD distances | `VoxelSettings.h` (no recompile of logic — data asset). |
+| LOD step mapping | `AVoxelWorld::LODToStep` VoxelWorld.cpp:268; `GetLODForChunk` :242. |
+| How chunks stream in/out | `UpdateChunksAroundPosition` VoxelWorld.cpp:362. |
+| Async threading / stale-result handling | `LoadChunk` :445, `ProcessPendingChunks` :301, Epoch logic. |
+| 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` :47 / `EvaluateSDFCached` :589. |
+| Worm tunnel behavior | `GetDensityWithParams` Step 5, VoxelGenerator.cpp:1241. |
+| Strate stacking / which strate where | `UVoxelStrateManager::Initialize` :10. |
+| Boundary blend between strates | `GetGenerationParams` :515 + `FStrateGenerationParams::Lerp` (StrateTypes.h:844). |
+| Passages between strates | `GeneratePassages` :146 + `EvaluateModifierSDF` :371 + `ApplyPassageCarving` (Generator.cpp:197). |
+| Player carve/fill | `CarveAtPosition`/`FillAtPosition` VoxelWorld.cpp:691/709 → `UVoxelDiffLayer::ApplyModification` :63. |
+| Mesh smoothness / normals | `UVoxelMarchingCubesMesher::ComputeGradientNormal` :48, `IsoLevel`/`GradientOffset` (h:51/55). |
+| New slab/flat-world generator | `GetSlabDensity` Generator.cpp:1306 + `FSlabGenerationParams` (StrateTypes.h:1019). |
+| Season reset | `AVoxelWorld::ChangeSeed` :740. |
+
+---
+
+## 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.
+- **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.
+
+---
+
+## 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. Archetypes, spine, disturbances, content & carving (2026 redesign)
+
+A large A-to-Z expansion. The world is a stack of strates the player descends through;
+each strate can be a fundamentally different *archetype*, connected at (0,0).
+
+### 8.1 Archetypes (`ECaveGeneratorType`, VoxelStrateTypes.h)
+Each archetype has its own param `USTRUCT` (on `UVoxelStrateDefinition`, EditCondition-gated
+by `GeneratorType`) and its own density function in `VoxelGenerator.cpp`, dispatched by the
+`switch` in `GetDensityAt`.
+
+| Archetype | Params struct | Density fn | Idea |
+|-----------|---------------|------------|------|
+| TunnelNetwork | `FStrateGenerationParams` | `GetDensityWithParams` | rooms+tunnels (original) |
+| FlatPlain / CrystalChamber | `FSlabGenerationParams` | `GetSlabDensity` | floor/ceiling void (original) |
+| Maze | `FMazeGenerationParams` | `GetMazeDensity` | tight corridors on a 3D lattice (per-voxel, no cache; edge = lower node + axis hash) |
+| SurfaceWorld | `FSurfaceGenerationParams` | `GetSurfaceDensity` | heightfield terrain (continents+ridged mtns+detail), beaches at water line, high sky-cap ceiling |
+| VerticalShafts | `FVerticalShaftParams` | `GetVerticalShaftDensity` | full-height shafts + horizontal connectors + partial ledges |
+| FloatingIslands | `FFloatingIslandParams` | `GetFloatingIslandDensity` | asymmetric islands: flat land top + underside tapering to a point, lobed (domain-warped) outline, in an open void |
+| Underwater | `FStrateGenerationParams` + water | (reuses `GetDensityWithParams`) | tunnel rock + high water table |
+
+All density fns share the convention: internal **positive=solid**, apply origin spine →
+boundary seal → inter-strate passages, then `return -Density` (MC: negative=solid).
+StrateManager provides params per chunk via `GetMaze/Surface/VerticalShaft/FloatingIslandParamsForChunk`
+(macro `VF_ARCHETYPE_PARAMS_GETTER`) — no cross-boundary blend (Hard transitions between archetypes).
+
+### 8.2 (0,0) spine & hybrid connections
+- `ApplyOriginSpine` (VoxelGenerator.cpp, static helper) carves a guaranteed open vertical
+  column at XY (0,0) in every strate's **interior** (seals untouched). Radius =
+  `UVoxelGenerator::OriginSpineRadius` ← `VoxelSettings::OriginSpineRadius`. Called before
+  every `ApplyBoundarySeal`.
+- Descent is **player-dug** through the thin seals at (0,0). The single auto-opened
+  connection is the **surface entry shaft** at (0,0) through the top of strate 0
+  (`GeneratePassages`, `bOpenSurfaceEntry`).
+- **Hybrid extras:** auto-carved *shortcut* passages per boundary, placed away from (0,0).
+  Now fully **per-strate** — see §8.8 (the upper strate's `PassageConfig` drives count/style/shape).
+
+### 8.3 Disturbance layer (the "wow" post-process)
+`FStrateDisturbanceParams` (on the definition, all archetypes). `ApplyDisturbances`
+(VoxelGenerator.cpp static, **MC convention**) runs in `GetDensityAt` after dispatch:
+chasms (carve air), bridges (solid spans), ridges (solid blades). Stays inside seal bands.
+Provided per chunk by `StrateManager::GetDisturbanceParamsForChunk`.
+
+### 8.4 Cross-chunk determinism (the seam-prevention invariant)
+`BuildChunkCache` (VoxelCaveMorphology.cpp) uses **two regions**: a wide *COLLECT* region
+(`2*MaxTunnelLength + MaxInfluence`) over which connectivity is decided (NN filtered to
+`<= MaxTunnelLength`, origin cap = deterministic top-N by hash), and a tight *STORE* region
+(`+MaxInfluence`) kept for per-voxel eval. This makes the room/tunnel graph window-invariant.
+**If you add a connectivity rule with longer edges, the COLLECT region must still cover the
+max edge reach, and decisions must not depend on the stored window.**
+
+### 8.5 Content scatter & water — `VoxelContentManager.h/.cpp` (NEW)
+`UVoxelContentManager` (owned by `AVoxelWorld`, game-thread). Chunk lifecycle:
+`PopulateChunk(coord, mesh, LOD)` in `ApplyMeshToChunk`, `ClearChunk` in `UnloadChunk`,
+`ClearAll`/`SetSeed` in `ChangeSeed`. Deterministic decoration scatter on mesh vertices
+(surface-type / water-relative / align-to-normal / random-yaw / scale / `MaxPerChunk`, from
+`FStrateDecoration`) — **only at LOD 0** (perf). Aesthetic water = one scaled engine plane
+(`/Engine/BasicShapes/Plane`) per water-surface chunk (any LOD), material
+`UVoxelStrateDefinition::WaterMaterial`. Water Z: `bHasWater` + `WaterLevelRelative`
+(Surface/tunnel params) → `StrateManager::GetWaterLevelWorldZForChunk`.
+
+### 8.6 Atmosphere — `VoxelAtmosphereManager.h/.cpp` (NEW)
+`UVoxelAtmosphereManager` (owned by `AVoxelWorld`, gated by `bManageAtmosphere`).
+`UpdateForPlayer(pos)` each Tick, reacts only on strate change. Drives a managed
+`UExponentialHeightFogComponent` + movable `USkyLightComponent` from the player's strate
+(`FogColor/FogDensity/bVolumetricFog/AmbientLightColor/AmbientLightIntensity`), and spawns
+PERSISTENT ceiling/floor "layer" actors (`Def->CeilingLayerActor`/`FloorLayerActor` + ZOffsets
++ rotations) that follow the player in XY — the sky-island sea-of-clouds / two-sided fog.
+`Def->AtmosphereActor` (a full BP with your own fog/sky/postprocess) OVERRIDES the managed
+fog+sky for that strate. `Reset()` on ChangeSeed/EndPlay. (Skylight ambient underground is
+weak — captures a dark scene; fog is the strong visual.)
+
+### 8.7 Inter-strate bedrock gap
+`VoxelSettings::InterStrateGapChunks` (N) inserts N chunks of SOLID bedrock between consecutive
+strates (`StrateManager::Initialize` leaves the gap in the layout). `IsGapChunk` detects it;
+`GetDensityAt` renders gap chunks as solid + passages only (no caves/spine/seal) so the player
+digs (0,0) through the gap to descend. `GetStrateUnrealZRange` gives a strate's cm Z range.
+
+### 8.8 Inter-strate passages — PER-STRATE (`FStratePassageConfig` on the definition)
+Each strate's `PassageConfig` (VoxelStrateTypes.h) controls its descent tunnels to the layer
+below: `Connections`, `Style` (`EVoxelPassageStyle`: Straight/Worm/Spiral/Cascading),
+`MouthRadius`/`MidRadius` (tapered width → `FVoxelPassage::ControlRadii` + `VoxelSDF::TaperedCapsule`),
+`ReachMin/Max` (depth into each strate), `DistanceMin/Max` (from the (0,0) spine), `Wander`,
+`Segments`, `VerticalWobble`, Spiral/Cascade params. Built in `StrateManager::GeneratePassages`
+as control-point chains. **Worm = independent fBM per horizontal axis** (`PassageFBM` static)
+with a flat-top envelope → organic squirm (NOT a 1D zigzag, NOT a same-freq 2-channel spiral).
+`EvaluateModifierSDF` (per voxel) **bounding-sphere-culls** each passage
+(`FVoxelPassage::BoundCenter/BoundRadiusSq`) — perf-critical. The (0,0) surface entry is a
+simple straight tube. Global passage settings were removed from `VoxelSettings`.
+
+### 8.9 Carving — brush shapes + editor controls
+`FVoxelModification` has `EVoxelBrushShape {Sphere,Box,Capsule}` + `BoxExtent`/`CapsuleEnd`/
+`Falloff` + `GetWorldBounds`. `UVoxelDiffLayer::GetDensityOffset` switches per shape; chunk
+overlap uses the shape AABB. `AVoxelWorld`: `CarveBox/FillBox/CarveCapsule/FillCapsule/
+ApplyModification` (BlueprintCallable) + `EditorCarveSphere/EditorFillSphere` (CallInEditor)
+driven by `EditorBrush*` props.
+
+### 8.10 Performance invariants (DON'T regress)
+- **Streaming** (`UpdateChunksAroundPosition`): rebuild/cull the desired set ONLY when the
+  player crosses a chunk boundary (`LastUpdateCenter`); use the `DesiredSet` TSet for the cull;
+  idle via `bAllChunksLoaded`. Stationary player ≈ free. (Old per-frame O(loaded×desired) scan = 22ms.)
+- **LOD** changes HOT-SWAP (`LoadChunk` only, never unload-first) → no holes. LOD
+  reconciliation lives in the PERSISTENT per-frame submit loop (same loop as new-chunk loads),
+  NOT as a one-shot on the boundary-cross frame — a one-shot drops every chunk past the task
+  budget and strands it at a stale LOD. Idle (`bAllChunksLoaded`) only when a full scan finds
+  no loads AND no LOD mismatches outstanding.
+- **SDF cache** (`GetDensityWithParams`): search-BOX validity, not chunk-key — gradient ±1
+  sampling must not thrash the (expensive) rebuild.
+- **Per-chunk param cache** in `GetDensityAt`: GenType + param struct + disturbance cached
+  thread-locally per chunk; don't move the fetch/blend back to per-voxel.
+- **Passage cull** (§8.8) + **morphology two-region** (§8.4): both are per-voxel-cost critical.
+- **Mesher density grid** (`GenerateMesh`): sample each grid point ONCE into a flat
+  `(CHUNK_SIZE/Step + 1)³` array, then the cell loop reads its 8 corners from it. Adjacent
+  cells share corners, so per-cell sampling calls `GetDensityAt` ~8× too often (262k→36k at
+  LOD0). Output is bit-identical (`GetDensityAt` is pure in world coords). Don't refactor
+  back to per-corner `GetDensity` calls inside the cell loop.
+- **`ProcessQueue` MUST be `EQueueMode::Mpsc`** (`VoxelWorld.h`): up to `MaxConcurrentTasks`
+  `ChunkGen` worker threads `Enqueue` concurrently; the game thread is the sole consumer.
+  The default `Spsc` is single-producer — concurrent enqueues race the tail link and silently
+  DROP results, leaking `PendingChunkCoord` slots until the budget is exhausted and streaming
+  stalls for good (intermittent; worst during the completion bursts right after the player moves).
+
+### 8.11 Live tuning & debug (`AVoxelWorld`, CallInEditor / PIE)
+- `RebuildStrates` — re-reads ALL of `VoxelSettings` and rebuilds layout/gap/passages/spine +
+  regenerates. Use after changing those (plain `RegenerateAllChunks` keeps the old layout/passages).
+- `bDebugDrawPassages` — draws every passage (cyan path, green=upper / red=lower endpoints).
+- `EditorCarveSphere`/`EditorFillSphere` + `EditorBrush*` props — manual carve/fill in PIE.
+
+### 8.12 Authoring a strate (data asset)
+1. Create `UVoxelStrateDefinition`, pick `GeneratorType` → its param group appears; tune it.
+2. `PassageConfig` → how THIS strate connects DOWN (count / style / tapered width / length / placement).
+3. `Disturbances` for chasms/bridges/ridges; `bHasWater`+`WaterMaterial`(+`WaterLevelRelative`) for water.
+4. Atmosphere: `FogColor/Density`, `AmbientLight*`, `bVolumetricFog`, or a full `AtmosphereActor` BP;
+   `CeilingLayerActor`/`FloorLayerActor` (+offsets/rotations) for cloud seas.
+5. `Decorations`/`AmbientActors` (placement rules) for content + lights.
+6. Reference from `VoxelSettings` (`StratePool`/`FixedStrates`). Global knobs there:
+   `OriginSpineRadius`, `bOpenSurfaceEntry`, `InterStrateGapChunks`, view distances, LOD, carving budget.
+
+### 8.13 New files this redesign
+`Public/Private/VoxelContentManager.h/.cpp` (§8.5) · `Public/Private/VoxelAtmosphereManager.h/.cpp` (§8.6).
+Everything else extended existing files: `VoxelStrateTypes.h` (archetype params, disturbance,
+`FStratePassageConfig`, enums), `VoxelStrateDefinition.h`, `VoxelGenerator.h/.cpp` (archetype
+density fns + spine/disturbance/param-cache), `VoxelStrateManager.h/.cpp` (per-archetype getters,
+passages, gap, atmosphere Z helper), `VoxelWorld.h/.cpp` (managers, streaming perf, brush API,
+editor buttons), `VoxelDiffLayer.h/.cpp` (brush shapes), `VoxelSettings.h`, `VoxelCaveMorphology.cpp`
+(two-region determinism). Status: compiles & runs in-editor.