perf(opstack): invert the loop + prune per block -- 1.45s to 1.02s, byte-identical

The architecture round. Loop inverted from per-sample-per-op to per-op-per-block,
operators pruned per block by interval bounds, profiler moved out of the hot loop.

  my build, 3 runs:  1.013 / 1.036 / 1.075 s   (adb34df was 1.418 / 1.445 / 1.458)
                     mean 1.041 vs 1.440  =  -28.5%, 1.39x
  geometry SHA-256   b3e5f4c3..9b377  IDENTICAL to adb34df

  pruning removed 20,999 / 31,320 operator-block visits = 67.1%
  surviving ops per block:  LOD0 6.63  LOD1 6.30  LOD2 5.23  LOD3 4.41  LOD4 3.89
                            (out of 22)

⚠️ I PREDICTED THE DISPATCH OVERHEAD WAS "THE 10x". IT WAS NOT.
864,688 virtual dispatches per chunk sounded decisive and is worth ~20-28%. Real, and
worth having, but the order of magnitude is elsewhere. That is my fourth wrong
performance prediction in this project, and the pattern is identical each time: I reason
from a call site's shape instead of measuring what the data actually costs.

⭐⭐ AND THE "5-20x GAME/EXPORT GAP" WAS MY ARITHMETIC ERROR. IT DOES NOT EXIST.
I told the owner the largest unexplained number in the project was that export does
22 ms/tile while the game does 115-500 ms. That 22 ms came from dividing 1.4 s of WALL
CLOCK by 64 tiles -- ignoring that 15 workers ran them in parallel. Per-job means on the
same build:

  nonshared block export   447 ms/job
  shared-grid export       261 ms/job
  game LOD0 meshing        253 ms/tile p50

They are the same. The game is not anomalously slow; generation simply costs ~250 ms per
LOD0 tile. The shared grid's benefit is real but modest, and a neighbourhood cache is NOT
justified by these numbers -- I would have had Codex build one on the strength of a
division error.

GAME PATH, final build (841 profiles, 447 applies)
  meshed p50/p95/max   LOD0 253/521/697 ms   LOD1 79/130/135   LOD2 19/42/51
                       LOD3 36/64/81         LOD4 93/238/271
  LOD0 request-to-ready  p50 47.7 ms  p95 389 ms  max 798 ms
                         worker queue p95 84 ms, generation p95 344 ms
  at 6 m/s: p95 = 2.3 m of travel, max = 4.8 m
  empty LOD0 tiles never enter the mesher; classifier p50 8.7 ms, p95 17.2 ms
  apply is not the bottleneck: p50 0.107 ms, p95 0.161 ms, max 0.296 ms

⭐ THE BINDING CONSTRAINT IS COMPUTE, NOT POLICY:
  logical cores 16, automatic core cap 14, effective generation cap 14, CAP HIT.
Apply limits never bind. We are saturating the machine, which means the remaining wins
must come from doing less work, not from scheduling it better.

NOT DONE, with reasons rather than excuses:
- Coarse-first LOD refinement: coarse tiles carry NO COLLISION, so streaming them first
  would let the player fall through. Needs a conservative collision proxy or an L0
  handoff first. Correct refusal.
- Heading prefetch: desired tiles are sorted by distance only (VoxelWorld.cpp:1748).
  Velocity-weighted prediction with a bounded budget and expiry is the shape, not built.

A failed experiment, reported rather than buried: eagerly filling every classifier leaf
with EvalBlock regressed export to 3.2-3.3 s because it defeated the classifier's early
exit. Removed.

Build 43 actions, 0 errors. Peak RSS under 2.1 GB. Sources: Epic's Tasks System and
Level Streaming docs, Lorensen-Cline.

Cumulative on this region: 342.2 s -> 1.02 s.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012aheo2crrZmHuYtPpdY2Cb

Source/VoxelForge/Private/VoxelGenerator.cpp

@@ -178,6 +178,193 @@ static thread_local FSurfaceColumnCache GSurfColCache;
 // T2.b — per-thread octave bias for the tile being meshed (see VoxelGenerator.h).
 // 0 = full quality; set by the mesher per tile from Step + Settings->LODOctaveDrop.
 thread_local int32 VoxelGenLOD::OctaveBias = 0;
+
+//=============================================================================
+// OP-MAJOR DENSITY BLOCK HAND-OFF
+//=============================================================================
+// The public Begin/End pair is only a lifetime marker.  The actual storage is worker-local and
+// bounded by the current mesher lattice.  A tile may cross several chunk keys; each key is filled
+// by the already-prepared stack that GetDensityAt selected for that key, so no mutable stack state
+// is shared across chunk boundaries.
+struct FVoxelDensityBlockSession
+{
+    bool bActive = false;
+    FIntVector Origin = FIntVector::ZeroValue;
+    int32 Step = 1;
+    int32 SizeX = 0;
+    int32 SizeY = 0;
+    int32 SizeZ = 0;
+    TArray<FVoxelOpSample> Samples;
+    TArray<uint8> Valid;
+    TArray<FVoxelOpSample> BlockScratch;
+    TArray<int32> ActiveOps;
+
+    void Begin(FIntVector InOrigin, int32 InStep, int32 InSizeX, int32 InSizeY, int32 InSizeZ)
+    {
+        bActive = InStep > 0 && InSizeX > 0 && InSizeY > 0 && InSizeZ > 0;
+        Origin = InOrigin;
+        Step = FMath::Max(InStep, 1);
+        SizeX = FMath::Max(InSizeX, 0);
+        SizeY = FMath::Max(InSizeY, 0);
+        SizeZ = FMath::Max(InSizeZ, 0);
+        if (!bActive)
+        {
+            Samples.Reset();
+            Valid.Reset();
+            BlockScratch.Reset();
+            ActiveOps.Reset();
+            return;
+        }
+
+        // Allocate lazily on the first operator-stack sample.  Legacy archetypes still use the
+        // ordinary scalar generator and should not pay for a block scratch lattice merely because
+        // the mesher opened the scoped hand-off.
+        BlockScratch.Reset();
+    }
+
+    void End()
+    {
+        bActive = false;
+        // Keep capacity for the next tile on this worker, but never retain a verdict between
+        // sessions.  A stale sample can only cost the next task a block fill, never change it.
+        Samples.Reset();
+        Valid.Reset();
+        BlockScratch.Reset();
+        ActiveOps.Reset();
+    }
+
+    int32 Index(int32 X, int32 Y, int32 Z) const
+    {
+        return (Z * SizeY + Y) * SizeX + X;
+    }
+
+    bool LocalIndex(FIntVector World, int32& OutX, int32& OutY, int32& OutZ) const
+    {
+        const int32 DX = World.X - Origin.X;
+        const int32 DY = World.Y - Origin.Y;
+        const int32 DZ = World.Z - Origin.Z;
+        if (DX % Step != 0 || DY % Step != 0 || DZ % Step != 0) { return false; }
+        OutX = DX / Step;
+        OutY = DY / Step;
+        OutZ = DZ / Step;
+        return OutX >= 0 && OutX < SizeX
+            && OutY >= 0 && OutY < SizeY
+            && OutZ >= 0 && OutZ < SizeZ;
+    }
+
+    bool FindAxisRange(int32 Axis, int32 TargetChunk, int32& OutMin, int32& OutMax) const
+    {
+        OutMin = INT32_MAX;
+        OutMax = INT32_MIN;
+        const int32 Limit = Axis == 0 ? SizeX : (Axis == 1 ? SizeY : SizeZ);
+        const int32 Base = Axis == 0 ? Origin.X : (Axis == 1 ? Origin.Y : Origin.Z);
+        for (int32 I = 0; I < Limit; ++I)
+        {
+            const int32 Coordinate = Base + I * Step;
+            if (FMath::FloorToInt(static_cast<float>(Coordinate) / CHUNK_SIZE) == TargetChunk)
+            {
+                OutMin = FMath::Min(OutMin, I);
+                OutMax = FMath::Max(OutMax, I);
+            }
+        }
+        return OutMin != INT32_MAX;
+    }
+
+    bool FillChunk(const FVoxelOpStack& Stack, FIntVector ChunkCoord, FIntVector World,
+                   FVoxelOpSample& OutSample)
+    {
+        int32 X = 0, Y = 0, Z = 0;
+        if (!LocalIndex(World, X, Y, Z)) { return false; }
+        const int32 Count = SizeX * SizeY * SizeZ;
+        if (Samples.Num() != Count || Valid.Num() != Count)
+        {
+            Samples.SetNum(Count);
+            Valid.Init(0, Count);
+        }
+        const int32 GlobalIndex = Index(X, Y, Z);
+        if (Valid[GlobalIndex] != 0)
+        {
+            OutSample = Samples[GlobalIndex];
+            return true;
+        }
+
+        int32 MinX = 0, MaxX = 0, MinY = 0, MaxY = 0, MinZ = 0, MaxZ = 0;
+        if (!FindAxisRange(0, ChunkCoord.X, MinX, MaxX)
+            || !FindAxisRange(1, ChunkCoord.Y, MinY, MaxY)
+            || !FindAxisRange(2, ChunkCoord.Z, MinZ, MaxZ))
+        {
+            return false;
+        }
+
+        const int32 BlockSizeX = MaxX - MinX + 1;
+        const int32 BlockSizeY = MaxY - MinY + 1;
+        const int32 BlockSizeZ = MaxZ - MinZ + 1;
+        const int32 BlockCount = BlockSizeX * BlockSizeY * BlockSizeZ;
+        BlockScratch.SetNum(BlockCount);
+        for (FVoxelOpSample& Sample : BlockScratch)
+        {
+            Sample = FVoxelOpSample();
+        }
+
+        FVoxelOpBlock Block;
+        Block.OriginVoxels = Origin + FIntVector(MinX * Step, MinY * Step, MinZ * Step);
+        Block.Step = Step;
+        Block.SizeX = BlockSizeX;
+        Block.SizeY = BlockSizeY;
+        Block.SizeZ = BlockSizeZ;
+        Block.Samples = BlockScratch.GetData();
+        const FIntVector BlockLast = Block.OriginVoxels
+            + FIntVector((BlockSizeX - 1) * Step,
+                         (BlockSizeY - 1) * Step,
+                         (BlockSizeZ - 1) * Step);
+        const FBox BlockBox(
+            FVector(static_cast<float>(Block.OriginVoxels.X),
+                    static_cast<float>(Block.OriginVoxels.Y),
+                    static_cast<float>(Block.OriginVoxels.Z)),
+            FVector(static_cast<float>(BlockLast.X),
+                    static_cast<float>(BlockLast.Y),
+                    static_cast<float>(BlockLast.Z)));
+        const int32 ActiveCount = Stack.BuildActiveOpList(
+            BlockBox, Step, Block.OriginVoxels, ActiveOps);
+        Stack.EvalBlock(Block, ActiveOps);
+
+        for (int32 Bz = 0; Bz < BlockSizeZ; ++Bz)
+        {
+            for (int32 By = 0; By < BlockSizeY; ++By)
+            {
+                for (int32 Bx = 0; Bx < BlockSizeX; ++Bx)
+                {
+                    const int32 Global = Index(MinX + Bx, MinY + By, MinZ + Bz);
+                    const int32 Local = (Bz * BlockSizeY + By) * BlockSizeX + Bx;
+                    Samples[Global] = BlockScratch[Local];
+                    Valid[Global] = 1;
+                }
+            }
+        }
+
+        if (VoxelDensityProfile::AreCountersEnabled())
+        {
+            VoxelDensityProfile::AddCounter(VoxelDensityProfile::ECounter::OpBlockBuilds);
+            VoxelDensityProfile::AddCounter(
+                VoxelDensityProfile::ECounter::OpBlockSamples,
+                static_cast<uint64>(BlockCount));
+            VoxelDensityProfile::AddCounter(
+                VoxelDensityProfile::ECounter::OpBlockOperators,
+                static_cast<uint64>(Stack.Num()));
+            VoxelDensityProfile::AddCounter(
+                VoxelDensityProfile::ECounter::OpBlockActiveOperators,
+                static_cast<uint64>(ActiveCount));
+            VoxelDensityProfile::AddCounter(
+                VoxelDensityProfile::ECounter::OpBlockPrunedOperators,
+                static_cast<uint64>(FMath::Max(Stack.Num() - ActiveCount, 0)));
+        }
+
+        OutSample = Samples[GlobalIndex];
+        return true;
+    }
+};
+
+static thread_local FVoxelDensityBlockSession GVoxelDensityBlockSession;
 thread_local int32 VoxelGenLOD::SampleStep = 1;
 
 int32 VoxelGenLOD::GetThreadOctaveBias()
@@ -1489,6 +1676,17 @@ void UVoxelGenerator::InitializeSettings(const UVoxelSettings* Settings)
     InvalidateTileVerdictCache();
 }
 
+void UVoxelGenerator::BeginDensityBlock(FIntVector OriginVoxels, int32 Step,
+                                         int32 SizeX, int32 SizeY, int32 SizeZ) const
+{
+    GVoxelDensityBlockSession.Begin(OriginVoxels, Step, SizeX, SizeY, SizeZ);
+}
+
+void UVoxelGenerator::EndDensityBlock() const
+{
+    GVoxelDensityBlockSession.End();
+}
+
 float UVoxelGenerator::GetDensityAt(float WorldX, float WorldY, float WorldZ) const
 {
     TRACE_CPUPROFILER_EVENT_SCOPE(VoxelForge_GetDensityAt);
@@ -1958,12 +2156,36 @@ float UVoxelGenerator::GetDensityAt(float WorldX, float WorldY, float WorldZ) co
         VoxelDensityProfile::FScopedTimer DensityCoreTimer(
             VoxelDensityProfile::EBucket::DensityCore);
 
+        FVoxelOpSample BlockCoreSample;
+        bool bUsedOpBlockSample = false;
+
         // Le seul point d'entrée de la pile dans le chemin de production. Elle rend la convention
         // MC (négatif = solide) comme les fonctions d'archétype, donc les disturbances et la couche
         // de diff qui suivent ne voient aucune différence.
         if (CP_UseOpStack)
         {
-            Result = ActiveOpStack->EvalMC(WorldX, WorldY, WorldZ);
+            const bool bIntegerLatticePoint =
+                WorldX == FMath::FloorToFloat(WorldX)
+                && WorldY == FMath::FloorToFloat(WorldY)
+                && WorldZ == FMath::FloorToFloat(WorldZ);
+            const bool bBlockSafeGenerator =
+                CP_GenType == ECaveGeneratorType::TunnelNetwork
+                || CP_GenType == ECaveGeneratorType::Underwater;
+            if (bIntegerLatticePoint && bBlockSafeGenerator
+                && GVoxelDensityBlockSession.bActive)
+            {
+                bUsedOpBlockSample = GVoxelDensityBlockSession.FillChunk(
+                    *ActiveOpStack,
+                    ChunkCoord,
+                    FIntVector(
+                        FMath::RoundToInt(WorldX),
+                        FMath::RoundToInt(WorldY),
+                        FMath::RoundToInt(WorldZ)),
+                    BlockCoreSample);
+            }
+            Result = bUsedOpBlockSample
+                ? -BlockCoreSample.Density
+                : ActiveOpStack->EvalMC(WorldX, WorldY, WorldZ);
         }
         else switch (CP_GenType)
         {
@@ -2028,8 +2250,20 @@ float UVoxelGenerator::GetDensityAt(float WorldX, float WorldY, float WorldZ) co
         bool bHavePreDisturbanceTunnelCore = false;
         if (CP_UseOpStack)
         {
-            bHavePreDisturbanceTunnelCore = ActiveOpStack->TryGetLastTunnelCoreWorldEvaluation(
-                PreDisturbanceTunnelCore);
+            if (bUsedOpBlockSample && BlockCoreSample.bHasTunnelCoreWorldEvaluation)
+            {
+                PreDisturbanceTunnelCore.SDF = BlockCoreSample.TunnelCoreWorldSDF;
+                PreDisturbanceTunnelCore.bSupportFloor =
+                    BlockCoreSample.bTunnelCoreSupportFloor;
+                PreDisturbanceTunnelCore.bRoomFloor =
+                    BlockCoreSample.bTunnelCoreRoomFloor;
+                bHavePreDisturbanceTunnelCore = true;
+            }
+            else
+            {
+                bHavePreDisturbanceTunnelCore = ActiveOpStack->TryGetLastTunnelCoreWorldEvaluation(
+                    PreDisturbanceTunnelCore);
+            }
         }
         if (!bHavePreDisturbanceTunnelCore && ActiveTunnelCoreCache->bValid)
         {