diff --git a/CODEMAP.md b/CODEMAP.md index d025fa3..29341d4 100644 --- a/CODEMAP.md +++ b/CODEMAP.md @@ -134,14 +134,15 @@ per-chunk info later. | `UnloadChunk` | 493 | Destroys mesh component + map entries. | | `ApplyMeshToChunk` | — | Upload geometry. **LOD0 → own component (`ChunkMeshes`, collision); LOD1/2 → batched into one component per region (`ChunkRegions`), each chunk a SectionGroup, no collision.** Handles LOD promote/demote between the two. §8.10. | | `ChunkToRegion` / `ChunkSectionGroupName` / `RemoveChunkFromRegion` / `DestroyIndividualChunkComponent` | — | Plumbing for the batched far-chunk scheme. | -| `GetStrateAtPosition` | 679 | Gameplay query → strate index. | +| `GetStrateAtPosition` | 965 | 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?"). | | `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). | -> **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_GenerateMesh` is worker-side (off the frame). +> **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_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`, and injected services @@ -163,6 +164,7 @@ per-chunk info later. | `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. | ### 3.7 Cave morphology (SDF rooms/tunnels) — `Public/VoxelCaveMorphology.h` + `.cpp` Header is rich with inline docs. Two namespaces + a per-chunk cache system. @@ -229,9 +231,10 @@ param groups gated by EditCondition. `ApplyTo(OutParams, Weight)` (.cpp:6) copie 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), and plain -runtime PODs `FBiomeResolved` / `FBiomeContext` / `FBiomeSample` / `FChunkBiomeCache` (the -box-validated per-chunk grid cache). See §8.14. +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. **`Public/VoxelBiomeDefinition.h` + `.cpp`** (NEW) — `UVoxelBiomeDefinition : UPrimaryDataAsset`. One asset = one biome: identity + `DebugColor`, climate placement box (`ReliefMin/Max`, @@ -366,420 +369,9 @@ Stage order (negative=solid throughout). Each stage's anchor: --- -## 8. Archetypes, spine, disturbances, content & carving (2026 redesign) +## 8. Architecture & design deep-dive → [ARCHITECTURE.md](ARCHITECTURE.md) -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: domain-warped continents+ridged mtns+detail, a low-freq **relief map** (`M`) that scales mountains/elevation for plains↔highland variety, opt-in plateau **terracing**, beaches at water line, high sky-cap ceiling. The cap is shapeable terrain in its own right (`ComputeSurfaceCeiling`, `Surface|Sky` params: `CeilingUndulation` broad inverted hills/valleys, `CeilingRidgeStrength` hanging ridgelines, `CeilingRoughness`+freq fine bumps, `CeilingWarp*`) — defaults (strengths 0, freq 0.04) = old flat-ish cap. (`Surface|Macro` params = the cheap precursor to biomes; `ReliefStrength=0` ⇒ old uniform terrain.) **Sky-cap tiles don't cast shadows**: `ApplyMeshToTile` classifies a near tile as ceiling (centre above the terrain↔cap midpoint via the `GetSurfaceHeightAt` oracle) and drives the **RMC per-section** `FRealtimeMeshSectionConfig::bCastsShadow` (NOT the component `SetCastShadow` — RMC's proxy ignores the component flag; this is also why level≥2 far tiles only stopped casting once the section flag was wired). So the rock ceiling never shadows the terrain below it (cap and ground are one mesh but live in different clipmap tiles). The same `bIsCeiling` classification (now computed at every LOD, not just near tiles) also selects the strate's `CeilingMaterial` when set, so the shadowless overhead rock can be tinted/darkened separately from the ground instead of reading flat/bright. | -| 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). -On top of the archetype, an optional **biome** layer (§8.14) modulates terrain & content WITHIN a -strate via a window-invariant XY field — currently wired into SurfaceWorld. - -### 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). TWO INDEPENDENT subsystems: - -**(A) DECORATIONS — distance-based WORLD GRID (the no-pop system, 2026-06-17).** Decorations are placed -on a fixed world XY cell grid (**1 cell = 1 chunk footprint**, `DECO_CELL_VOXELS = CHUNK_SIZE`) and streamed -by DISTANCE from the player, **fully decoupled from clipmap tiles / LOD**. **THE MARCH RUNS ASYNC ON WORKER -THREADS** (mirrors mesh gen — `GetDensityAt` is thread-safe; the synchronous-on-game-thread first cut was a -perf disaster + starved streaming → seams, so it was moved off-thread). Driven by `AVoxelWorld::Tick → -UpdateDecorations(playerWorldPos)`, three phases: **(1)** recompute the desired cell set (`RebuildDesiredCells`) -only when the player crosses a cell boundary OR changes strate — clears out-of-range loaded cells, queues -cells that are NOT loaded and NOT in flight (`PendingLaunch`, nearest-first). **SINGLE radius, NO near/far tiers:** -a loaded cell is NEVER re-streamed in place while it stays in range (only cleared when it leaves), so -decorations don't FLICKER as the player moves / as terrain LOD shells shift (re-streaming on tier crossings was -the flicker cause — tiers removed). **(2)** `LaunchDecoTasks`: -resolve the cell's decoration list on the GAME thread (biome — see below) then fire an async `UE::Tasks` march -(`BuildCellSpawns`, `BackgroundNormal`, capped at `MaxConcurrentDecorationTasks` in flight via `InFlightCells`). -**(3)** `ProcessDecoResults`: drain finished tasks' results (`Mpsc` queue → `ReadyResults`), epoch-guarded -(`DecoEpoch`, bumped on clear/strate-change so stale in-flight results are discarded) + range-checked, and -**apply (spawn) budgeted** (`MaxDecorationCellsPerFrame` — the only game-thread cost, SpawnActor/AddInstance). -`BuildCellSpawns` (worker) finds each column's surface point(s) and rolls the entries there (shared -`PlaceAtCrossing`). Candidate columns are **snapped to INTEGER voxel XY** (integer jitter) so the generator's -surface-column cache (T1.a, §8.10) applies — FRACTIONAL XY bypasses it and recomputes the noise-heavy -heightfield+biome on every sample. **TWO column strategies by archetype:** -**(a) SurfaceWorld → HEIGHT ORACLE (`Ctx.bSurfaceWorld`), NO marching.** `Generator::GetSurfaceHeightAt(x,y, -chunkZ → TerrainZ, CeilSurf)` returns the heightfield surface + sky-cap ceiling in O(1) (it shares the density -path's `ResolveSurfaceChunkParams`/`ComputeSurfaceColumn` via its own thread_local per-chunk cache, so it's -bit-identical to the rendered ground). Per column: query centre + 4 neighbours (gradient → floor/ceiling -normals), place a Floor crossing at `TerrainZ` and a Ceiling crossing at `CeilSurf` (if open space below). A -single `GetDensityAt` at the surface verifies the column isn't CARVED (passage/spine/diff make it air → skip; -the oracle is the raw heightfield and doesn't know carving). ~5 height evals + 1-2 density samples/column vs -hundreds marched. **(b) other archetypes (caves/shafts/islands) → ray-march** the strate Z-band -(`GetStrateUnrealZRange`, voxel coords) via `GetDensityAt` at a COARSE step (`DecorationMarchStepVoxels`), each -air↔solid sign change **bisection-refined** (4 iters → accuracy independent of step). Either way **a prop sits at -the SAME world position at every LOD → no pop**. (march) The top cap/seal + the open air are always marched first; the scan only stops after -`DecorationColumnDepthVoxels` of CONTIGUOUS solid once it has ENTERED the open space (trims dead bedrock below -the ground without ever stopping short of it — a "below the first crossing" cap was wrong: on a surface world -the first crossing is the high CEILING, so it stopped mid-air before reaching the ground = no floor props). -Outward normal = normalized density gradient (solid→air, matches the mesher), classified -Floor/Wall/Ceiling by `normal.Z`. Each crossing rolls every `FStrateDecoration` independently: surface-type, -density gate (`DecoHash(cell,column,crossing,entry,seed)`), water-relative, align/yaw/scale, per-cell -`MaxPerChunk` + global actor cap → a `FDecoSpawn{EntryIdx, bInstanced, Xf}`. The game thread spawns from the -result's `Entries` snapshot. `DecorationMaxCrossingsPerColumn` caps cave columns (surface worlds have 1). -**Shutdown:** `NotifyShutdown()` (called from `AVoxelWorld::EndPlay`) flags + spin-waits on the in-flight -task count before UObject teardown (tasks read the Generator); `BeginDestroy` is the backstop. **Determinism:** -pure hash of (cell, column, crossing, entry, seed) + the density surface snap. **Decorations exist ONLY in -the player's current strate** (march is strate-bounded) → a strate change wipes + rebuilds them, and there -is **no cross-strate light bleed to cull** (the old `SetActiveStrate` light-culling pass is SUBSUMED — gone). -**Render paths:** `ActorClass` → real actors (lights/logic, pricey game-thread spawn); `InstancedMesh` → HISM -(no tick/actor/collision, emissive glows far), per-cell-per-entry. **Per-entry HISM tuning for dense groundcover** -(`FStrateDecoration`, only the InstancedMesh path): `CullDistance` (cm; 0 = no cull — the lever that makes dense -grass affordable: placed thickly, drawn only near → GPU cost bounded by area-within-cull, NOT the stream radius), -`bCastShadow` (default true; turn OFF for grass — dense instanced shadows are the dominant foliage cost), -`MaxSlopeAngle` (deg from flat = acos(|N.Z|); 90 = no filter, ~35 keeps grass off cliffs — applied in the worker's -`PlaceAtCrossing`). `ApplyDecoResult` buckets spawns per entry and builds each HISM with ONE batched `AddInstances` -(single cluster-tree build, set cull/shadow BEFORE `RegisterComponent`) — the game-thread hitch-killer for dense cells. -Note: NO per-entry placement radius (it would fight the no-re-stream cell model — cells stream once at the outer ring -and persist, so a smaller radius would never populate already-loaded far cells as the player approaches; CullDistance -covers the render cost instead). **All entries stream within ONE radius** -(`DecorationRadiusChunks`) — the old near/far tier split was removed (it caused flicker). `MaxLODLevel` and -`DecorationActorRadiusChunks` are now LEGACY/unused. **No LOD area-density compensation** (placement is per real -surface point, density-stable with distance). **SpawnDensity semantics CHANGED** vs the old vertex scatter: it -rolls per column surface-point (not per mesh vertex) → expect a one-time density re-tune. **Settings -(`Voxel|Content`):** `DecorationRadiusChunks` (6 — reach in cells), `DecorationSpacingVoxels` (4 → 8×8 cols/cell), -`DecorationMarchStepVoxels` (2 — coarse, bisection-refined; cave march only), `DecorationMaxCrossingsPerColumn` -(4 — cave march only), `DecorationColumnDepthVoxels` (160 — bedrock march cap; cave march only), -`MaxDecorationCellsPerFrame` (2 — apply/spawn budget), `MaxConcurrentDecorationTasks` (4 — in-flight task cap; -0 disables decorations). **COST:** surface worlds now use the O(1) oracle (cheap); caves ray-march. The work is -OFF the frame (worker threads) — game thread only pays the budgeted spawn. If streaming slows, lower -`MaxConcurrentDecorationTasks` / raise `DecorationMarchStepVoxels` / shrink radii/spacing. Default -`DecorationRadiusChunks=6` ≈ props ~48 m out — raise for far flora (cost ~r²). - -**(B) WATER — tile-driven, level-0 only (continuous plane, never pops).** `PopulateTileWater(tile)` in -`ApplyMeshToTile` (level-0 tiles), `ClearTileWater(tile)` in `UnloadTile`. One scaled engine plane -(`/Engine/BasicShapes/Plane`) per water-surface chunk (per-chunk-Z plane logic assumes a single chunk's -vertical span — hence level-0 only), keyed `TMap` (reflected UPROPERTY). -Water Z: `bHasWater` + `WaterLevelRelative` → `StrateManager::GetWaterLevelWorldZForChunk`. Biome -`WaterMaterial` overrides `UVoxelStrateDefinition::WaterMaterial` (level stays strate-global). - -`ClearAll`/`SetSeed` on `ChangeSeed`/regenerate clears both subsystems (decorations re-stream on the next -Tick via the INT_MIN sentinels). **Per-biome content (§8.14):** the cell-centre (decorations) / chunk-centre -(water) dominant biome (`Generator::GetDominantBiomeAt`, game-thread, uncached — once per cell, NOT per -column) supplies the decoration list (replaces the strate's) + water material. `Initialize` now also takes -`UVoxelSettings*` (for the grid tunables). `ContentMaxLevel` is now legacy/dead for decorations. - -### 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.) -**Per-biome atmosphere (§8.14):** `UpdateForPlayer` also resolves the player's dominant biome and, -when the biome has `bOverrideAtmosphere`, its fog/sky beats the strate's (reacts on biome change, not -just strate change). `ApplyFogSky(Def, Biome)` is the shared path; layer actors + the full `AtmosphereActor` -BP stay strate-level. Needs the generator injected (`Initialize(..., Generator)`). - -### 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) first builds a `thread_local` **per-chunk shortlist** of passages -whose bounds reach this chunk (rebuilt on chunk change / `PassagesVersion` bump) — chunks with no -passage near return `FLT_MAX` immediately — then **bounding-sphere-culls** each shortlisted passage -(`FVoxelPassage::BoundCenter/BoundRadiusSq`). Both are perf-critical (§8.10). 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. -- **Biome cache** (`ResolveBiomeSampleAt`/`FChunkBiomeCache`, §8.14): validity is a world-XY BOX + - ChunkZ + Seed, NOT a chunk key — same reason as the SDF cache. The cell classification is - noise-heavy; a chunk-key would thrash it on gradient-normal / +X/+Y boundary samples. Keep - the box halo (≥ CHUNK_SIZE) + cell margin (warp + CellSize) so the 3x3 lookup never misses. -- **Passage cull** (§8.8) + **morphology two-region** (§8.4): both are per-voxel-cost critical. -- **Per-chunk passage shortlist** (`EvaluateModifierSDF`): runs per voxel and is called from every - archetype's `ApplyPassageCarving`. Keeps a `thread_local` shortlist (passage INDICES) of passages - whose bounds reach the current chunk, rebuilt only on chunk change or `PassagesVersion` bump - (incremented in `GeneratePassages`). Most chunks have NO passage near → instant `FLT_MAX` return - instead of walking the whole `Passages` array per voxel. Conservative superset (chunk bounding - sphere vs passage bound) ⇒ bit-identical carve. Store indices + version, never pointers (the array - is rebuilt on `RebuildStrates`). -- **Gen tasks run at `UE::Tasks::ETaskPriority::BackgroundNormal`** (`LoadTile`): worker gen yields - to foreground game/render tasks. Without it, raising `MaxConcurrentTasks` past the spare-core count - saturates the scheduler and starves the frame (the "concurrency > ~12 = stutter" symptom). Keep gen - at background priority so the frame keeps its cores. -- **Mesher density grid + margin ring** (`GenerateMesh`): sample each grid point ONCE into a flat - `(CHUNK_SIZE/Step + 1 + 2)³` array (the `+2` is a 1-point MARGIN ring, indices −1..GridDim, for - T1.b normals). The cell loop reads 8 corners from it; per-cell sampling would call `GetDensityAt` - ~8× too often. Geometry is bit-identical (edge positions unchanged). Don't refactor back to - per-corner `GetDensity` and don't drop the margin ring (normals + seamless borders need it). - The cell loop is **two-pass**: pass 1 reads the 8 corner densities + builds the MC case index and - `continue`s on no-surface cells (≈70% of cells); pass 2 computes the 8 positions + grid-gradients - ONLY for surface cells. Don't hoist position/gradient back above the case-index test. The - `DensityGrid` and vertex-dedup `TMap` are `thread_local` and reused per worker (Reset / keep - capacity) — don't make them per-call locals (re-allocates ~170 KB + a hash map every tile). -- **Normals from the density grid (T1.b)** (`GenerateMesh`): corner gradients = central differences - on the (margin) grid; edge normals interpolate the two corner gradients by the SAME `t` as the - position → seamless across chunk borders (both sides use identical pure samples). NO per-vertex - `GetDensityAt` (was ~6/vertex, often as costly as the whole grid). `ComputeGradientNormal` is now - unused. Only NORMALS changed vs the old path; geometry is identical. -- **Surface column cache (T1.a)** (`FSurfaceColumnCache` = LRU of `FSurfaceColumnBox`, `GetDensityAt` - SurfaceWorld branch): the heightfield + sky-cap + biome blend are a PURE function of (XY, seed, - strate) — **ZERO Z dependence** (climate/Voronoi are pure-XY; surface params are per-strate constant - under Hard transitions) — yet sampled ~33× per column (once per Z grid-point). Cached per integer XY - (box-valid, like the SDF cache) and reused down the column. **Keyed by (XY box, StrateKey, Seed), NOT - ChunkZ** (`StrateKey = round(StrateBottomWorldZ)`, taken from the params so it can't disagree with - them) and held as a small **LRU of 6 boxes** so the WHOLE vertical view-distance stack — and XY - neighbours the scheduler interleaves — share one another's heavy column noise instead of each - recomputing it ~once per vertical chunk (this was the dominant `GenerateMesh` cost: the same 2D - heightfield recomputed per altitude). It also makes pure-air / pure-solid chunks cheap (they hit the - shared box). Box `Halo = CHUNK_SIZE + 8` each side so the T1.b margin ring stays inside (no thrash). - **Used ONLY for integer-XY queries**; fractional queries compute directly → bit-identical. Don't - re-introduce a ChunkZ key, don't feed it fractional coords. (`GetSurfaceHeightAt`'s own `OC_*` oracle - cache is separate and still per-chunk — lower volume, not worth the LRU.) -- **Collision only at LOD0 (T1.c)** (`ApplyMeshToChunk`): `UpdateSectionConfig(..., LOD==0)`. - LOD1/2 chunks are unreachable (the §8.10 reconciliation hot-swaps to LOD0 before the player - arrives), so cooking their Chaos collision is waste. Don't force collision on for all LODs. -- **CHUNKED-LOD CLIPMAP — the streaming model** (`FVoxelTileKey` in VoxelTypes.h; `UpdateChunksAroundPosition` - / `BuildDesiredTiles` / `IsTileInClipRange` / `LoadTile` / `UnloadTile` / `ApplyMeshToTile`; mesher - `GenerateMesh(OriginVoxels, Step)`). Replaces the fixed-32³-chunk + LOD-step-on-fixed-extent model - AND supersedes the old region-batching / strate-Z-clamp / wide-ceiling (all removed). A **level-L tile** - spans `CHUNK_SIZE<