VoxelForge/CODEX-TASK-001-tile-skip-stats.md

Codex task 001 — make tile-skipping observable in the running game

Owner: Codex (Model Luna, xHigh) · Orchestrator: Claude · Branch: experimental Status: specified, not started

---

Why this exists

Jahni built the world, looked at it, and said: "I don't know if it dropped any meshing? but it looks alright by the eye."

He's right to be unsure — there is no way to answer that question from inside the game. The plugin has zero stat counters (grep INC_DWORD_STAT → nothing). Tile-skipping is the largest perf item in the whole plan and it is currently unobservable in production; it has only ever been measured in an automation harness, on 40 sampled tiles.

And a visual check cannot answer it: skipped correctly and skipped nothing render identically. This codebase has paid repeatedly for exactly that confusion — see the "coverage is a number, not a boolean" lessons in OPSTACK-HANDOFF.md.

The real prize: with no strate opted in, cave-archetype skips must read 0. After ticking bUseOperatorStack on one TunnelNetwork strate and flying underground, they must become non-zero. That is the production-side proof of T1.d, which does not exist today.

The sites — there are TWO, and the second one is the one that answers the question

Site A — the skip itself

Source/VoxelForge/Private/VoxelWorld.cpp, in AVoxelWorld::GenerateTileResult (~line 1501). Trust the symbol, not the line number.

bool bTrivialEmpty = false;
if (!bSheetTile && !bWantCapture && Generator && Mesher && Mesher->IsoLevel == 0.0f)
{
    TRACE_CPUPROFILER_EVENT_SCOPE(VoxelForge_ClassifyTile);
    bTrivialEmpty = (Generator->ClassifyTile(OriginVoxels, Step, Cells) != EVoxelTileClass::Mixed);
}

FVoxelMeshData MeshData;
if (!bTrivialEmpty)
{
    TRACE_CPUPROFILER_EVENT_SCOPE(VoxelForge_GenerateMesh);
    MeshData = bSheetTile ? Mesher->GenerateSheetMesh(...) : Mesher->GenerateMesh(...);
}

Site B — where the OPERATOR STACK's verdict is produced

Source/VoxelForge/Private/VoxelGenerator.cpp, in UVoxelGenerator::ClassifyTile, at the exit of the if (bAnyCave) block (~line 3009) — the last two lines of that block:

if (bCanSolid == bCanAir) { return EVoxelTileClass::Mixed; }
return bCanSolid ? EVoxelTileClass::AllSolid : EVoxelTileClass::AllAir;

Why site A alone cannot answer the question — this is the correction that makes the task meaningful. ClassifyTile has two independent ways to reach a non-Mixed verdict:

• the hand-written path, which predates all of this work: a chunk in a bedrock gap sets bCanAir = false (VoxelGenerator.cpp ~2835) and, absent a passage or the origin spine, the tile resolves AllSolid. Likewise the SurfaceWorld column scan. This fires with no strate opted in at all;
• the operator-stack path, the if (bAnyCave) block, which is the only thing T1.d added.

So TilesSkippedAllSolid at site A will already be non-zero underground before any strate is ticked — the bedrock between strates guarantees it. A single lumped counter would make the before/after unreadable, and that is exactly the "when a zero has several possible causes, give each one its own number" lesson this project already paid for.

Site B's counters have the opposite property, and it is a strong one: ClassifyTile returns Mixed outright at the cave branch when UsesOperatorStackForChunk(CC) is false (~line 2809, and again per chunk of the box at ~2914). With no strate opted in, the site-B counters are zero by construction, not merely by observation — so a non-zero reading after ticking the box cannot come from anywhere else.

What to build

1. A stat group. New header Source/VoxelForge/Public/VoxelStats.h: DECLARE_STATS_GROUP(TEXT("VoxelForge"), STATGROUP_VoxelForge, STATCAT_Advanced); plus DECLARE_DWORD_COUNTER_STAT_EXTERN for each counter below. DEFINE_STAT for each goes in one .cpp — put them in a new Source/VoxelForge/Private/VoxelStats.cpp.

2. Six per-frame counters (DWORD_COUNTER, so stat VoxelForge shows a rate, not a total):

   counter	site	incremented when
   TilesClassified	A	the classifier gate was entered (the if above ran ClassifyTile)
   TilesSkippedAllSolid	A	verdict was AllSolid
   TilesSkippedAllAir	A	verdict was AllAir
   TilesMeshed	A	GenerateMesh / GenerateSheetMesh actually ran
   TilesOpStackSolid	B	the bAnyCave block returned AllSolid
   TilesOpStackAir	B	the bAnyCave block returned AllAir

   Splitting solid from air is the point, not decoration: cave archetypes prove AllSolid. Splitting site B from site A is the whole deliverable — see "Why site A alone cannot answer the question" above. TilesOpStackSolid ≤ TilesSkippedAllSolid always, and the difference is the pre-existing bedrock/surface skipping.

   At site B, increment on the return line only — not before the if (bCanSolid == bCanAir) return Mixed; guard, which is where the block bails out with no verdict.

3. To get the verdict you need it as a value, not a bool. Changing bTrivialEmpty = (Classify(...) != Mixed) into a stored EVoxelTileClass Verdict = Classify(...) followed by bTrivialEmpty = (Verdict != Mixed) is fine and expected.

⚠️ Invariants — a violation here is not a bug, it is a hole

1. DO NOT change bTrivialEmpty's value or the control flow. That bool decides whether a tile gets geometry and collision. A wrong value is invisible until a player falls through the floor. Refactor the expression, never the condition.
2. DO NOT touch the gate !bSheetTile && !bWantCapture && Generator && Mesher && Mesher->IsoLevel == 0.0f. Every clause is load-bearing and documented in the comment above it — sheet tiles have no marching cubes, capture tiles need the grid even when uniform, and the verdicts assume the MC iso is exactly zero.
3. Thread safety: this runs on WORKERS. GenerateTileResult is called from the async ChunkGen task and the synchronous carve path. Use the INC_DWORD_STAT family, which is per-thread-packet safe. A plain static int32 counter, even ++ on an int32, is a data race — do not.
4. Zero cost when stats are compiled out. The INC_DWORD_STAT macros already vanish when STATS == 0. Do not wrap them in an if that survives, and do not compute anything solely to feed a counter outside the macro.
5. No new includes in a public header beyond Stats/Stats.h; the plugin follows IWYU and the include debt was cleared deliberately (AUDIT §C9 work).
6. At site B, do not touch ClassifyTile's control flow either — and do not add an early return. That function is a chain of conservative guards that all fail to Mixed; every return in it is load-bearing. Add the counter to the existing return expression's statement, nothing else. ClassifyTile is const and runs on the same workers as site A, so the same INC_DWORD_STAT-not-static int32 rule applies.

Acceptance

• Editor, stat VoxelForge on screen, fly around: the numbers move.
• TilesClassified == TilesSkippedAllSolid + TilesSkippedAllAir + TilesMeshed for tiles that entered the gate. (Tiles that fail the gate are meshed without being classified, so TilesMeshed is legitimately larger than the classified total — say so in a comment rather than "fixing" it.)
• TilesOpStackSolid ≤ TilesSkippedAllSolid and TilesOpStackAir ≤ TilesSkippedAllAir, always. A violation means site B is counting a verdict that site A did not act on.
• With no strate opted in, flying underground through a TunnelNetwork strate:
  • TilesSkippedAllSolid is expected to be non-zero — that is the pre-existing bedrock/surface skipping, not a bug, and it is why the lumped counter cannot be the deliverable;
  • TilesOpStackSolid and TilesOpStackAir are 0. This is the baseline, and it must be observed before the next step even though it is guaranteed by the flag gate.
• Tick bUseOperatorStack on one TunnelNetwork strate, fly the same route: TilesOpStackSolid becomes non-zero. ← this is the deliverable, and it is the first production-side evidence T1.d has ever had.

Notes for the reviewer (Claude)

• Check the verdict refactor byte-for-byte against the original condition. != Mixed is the whole contract.
• Check the counters are DWORD_COUNTER (per-frame) and not DWORD_ACCUMULATOR.
• Confirm no counter is incremented outside the gate in a way that double-counts the carve path, which calls GenerateTileResult synchronously from the game thread.
• Site B: confirm the increment sits after the bCanSolid == bCanAir bail-out, and that the two counters follow bCanSolid the same way the returned enum does — a swapped pair reads as a plausible result and proves the wrong thing.
• The automation tests call ClassifyTile directly; they will move the site-B counters. Harmless, but do not let a test-only path become the only thing that moves them.