acdream/docs/research/2026-05-10-phase-a5-handoff.md

Phase A.5 — Two-tier Streaming + Horizon LOD — Cold-Start Handoff

Created: 2026-05-10, immediately after N.5b ship. Audience: the next agent picking up streaming + horizon-LOD work. Purpose: brief you on where N.5b left things, what A.5 actually has to do to make the world look and feel great, and the load-bearing facts the brainstorm should be informed by.

---

TL;DR

N.5b just shipped: outdoor terrain rendering is on bindless + multi-draw indirect via TerrainModernRenderer. Constant-cost dispatch as the visible landblock count grows — radius=5 vs radius=15 are the same number of GL calls for terrain.

A.5's actual goal — verbatim from the user, 2026-05-09:

"I just want great smooth HIGH fps visuals. Should look great. As long as it scales and we get very high FPS"

That reframes priorities. We are NOT optimizing the inner loop at radius=5 (it's solved). We're scaling visual reach + scene density without the client falling off a perf cliff.

Concretely, A.5 ships three things:

1. Two-tier streaming. Near tier (≤ N₁ landblocks) loads everything as today (terrain + scenery + EnvCells + collision). Far tier (N₁ < r ≤ N₂) loads terrain mesh ONLY. No scenery generation, no collision, no entity registration for the far tier.
2. Per-LB entity bucketing for the WB dispatcher. Today the entity dispatcher walks every loaded entity each frame for AABB cull — ~16K entities @ ~1µs/test = 4.3ms/frame, dominating the frame budget. Bucket entities by landblock so the cull is hierarchical: cull the LB first, then only walk entities inside surviving LBs.
3. Off-thread mesh build. LandblockMesh.Build currently runs on the render thread when a new LB streams in. At today's radius=5 this is invisible; at A.5's higher N₂ it becomes a visible frame-time spike when 4-5 LBs stream simultaneously. Move the build to a worker pool; hand finished LandblockMeshData back via a queue.

The headline win you're shooting for: radius=15 sustains the user's target FPS in Holtburg with no streaming hitches.

---

Where N.5b left things

Branch state (relative to main)

After N.5b ships:

• N.5b SHIP at 08b7362 (final commit; appended SHIP record to plan)
• Roadmap entry, issue #51 closure, perf baseline doc all in place at 083c10c
• Legacy TerrainChunkRenderer + TerrainRenderer + terrain.vert/.frag deleted at 7dfa2af. The modern path is the only path.

Captured perf baseline (load-bearing for A.5's "what's actually hot")

From docs/plans/2026-05-09-phase-n5b-perf-baseline.md, measured 2026-05-09 at Holtburg town dueling field, radius=5, ~30s standstill:

Subsystem	cpu_us median per frame	Notes
Entity dispatcher (WbDrawDispatcher)	~4,300	86% of frame budget. ~16K entities walked for AABB cull. THIS is the bottleneck.
Terrain dispatcher (TerrainModernRenderer)	~6.4	<1% of frame. Constant-cost regardless of radius (proved in N.5b).
Everything else (sky, particles, ImGui, swap, audio)	~700	Small.

Actual FPS at radius=5 in Holtburg: ~200 fps (frame time ≈ 5ms). NOT the "810 fps" inferred from the N.5 ship doc (that was 1/dispatcher_ms, which is only the WB dispatcher CPU cost in isolation, not real frame time).

What naive radius increase does

If you simply raised ACDREAM_STREAM_RADIUS to 15 today without A.5:

• Loaded landblocks: 121 → ~961 (8× more). Acceptable.
• Loaded entities: ~16K → ~125K (linear scaling with LB count). NOT acceptable. At ~1µs per AABB cull, the entity dispatcher would take ~125ms/frame = 8 FPS. Slideshow.
• Memory footprint: similar 8× explosion in scenery instance buffers.

So the perf cliff is real and immediate. A.5 has to address it BEFORE the radius can be safely raised.

What N.5b set up that A.5 inherits

• Modern terrain dispatcher. TerrainModernRenderer is O(1) GL calls in radius. As you add far-tier LBs (terrain only), the terrain dispatcher cost stays flat (~6µs/frame). This is the one subsystem that doesn't need any A.5 work — it just scales.
• Slot allocator for terrain GPU buffers. Already grows by power-of-two doubling. Will absorb radius=15 (~961 slots × ~15 KB each = ~14 MB) without manual tuning.
• [TERRAIN-DIAG] instrumentation. Reports per-frame median + p95 in microseconds. Use this to confirm A.5 doesn't regress terrain perf.
• Conformance sentinel. TerrainModernConformanceTests proves visual mesh Z agrees with TerrainSurface.SampleZFromHeightmap to 0.015 mm. Don't break this — physics ↔ visual agreement must hold across both tiers.
• Bindless atlas. TerrainAtlas.GetBindlessHandles(). The far tier shares the atlas (it's region-wide). Zero atlas-related per-LB cost.

---

The brainstorm questions (the hard calls A.5 has to make)

These are the questions to resolve in the brainstorm step. Bring them to the user with options + recommendation; don't prejudge.

1. Tier radii: what are N₁ and N₂?

• N₁ = near-tier radius (everything loads). Today's default STREAM_RADIUS. Probably stays at 5 (or maybe 4; maybe 3).
• N₂ = far-tier radius (terrain mesh only). Could be 8, 12, 15, 20.

Tradeoffs: bigger N₂ = more world visible = looks better. But each far-tier LB still costs ~16 KB GPU memory + a frustum cull AABB + a slot allocation. At N₂=15, that's ~961 LBs × 16 KB = ~15 MB GPU mem (cheap) + ~961 cull tests (cheap, ~1ms total at 1µs each — and we'll do this per-LB cull anyway as part of #2 below).

Verify against retail: cdb attach + check how many landblocks retail keeps loaded at a given vantage point. Probably around 10-12 per the AC2D references and the holtburger client's behavior.

2. Far tier: terrain only? Or also impostor scenery?

Two options:

• Terrain only (cleanest). Beyond N₁, no trees, no rocks. Skyline is the terrain mesh against the sky.
• Impostor scenery (more retail-like). Beyond N₁, generate flat billboards or low-poly trees instead of full meshes. Adds substantial complexity (billboard pipeline, mesh-LOD generation, per-camera-angle rotation).

Recommendation: start with terrain-only. Add impostors only if the horizon looks wrong (too bare). Retail definitely has SOME distant scenery but the cutoff is gradual; we can match it later if needed.

3. Entity bucketing structure

Today: WbDrawDispatcher keeps a flat dictionary of all entities and walks all of them per frame. To bucket by LB, we need:

• A Dictionary<uint, List<EntityHandle>> keyed by landblock ID
• On AddEntity(...), also stash it in the LB bucket (the spawn flow already knows the LB context)
• On RemoveEntity(...), remove from the LB bucket too
• Per frame: cull at LB granularity first; then cull entities only inside surviving LBs

LB-level AABBs are already computed (per the existing _visibleSlots logic in TerrainModernRenderer — the same AABB applies to entities, modulo a Z-range bump for trees/buildings).

Open question: do entities outside a known LB exist? (Items dropped on the ground? Ephemeral effects? Player projectiles?) If yes, they need a fallback "unknown LB" bucket that's still walked every frame. Probably small.

4. Where does the off-thread mesh build land?

Today LandblockMesh.Build runs synchronously inside OnLandblockLoaded on the render thread. To move it off:

• StreamingLoader worker thread (already async for dat reads) signals "LB X is ready"
• A new worker pool consumes that signal, builds the mesh on a worker thread, posts the finished LandblockMeshData to a ConcurrentQueue
• Render thread drains the queue at the start of each frame, calling _terrain.AddLandblock(...) for each ready mesh

Gotcha: the TerrainBlendingContext is shared. Need to confirm it's read-only (it is — built once at startup). Also _surfaceCache — currently a plain Dictionary populated lazily by TerrainBlending.BuildSurface. Either lock it, replace with ConcurrentDictionary, or pre-populate with all known palCodes at startup.

5. Streaming hysteresis at the tier boundary

When the player crosses N₁ → near-tier shrinks, far-tier grows. LBs that were near-tier need to:

• Drop their scenery (unregister entities)
• Drop their EnvCells
• Keep the terrain mesh (still in far tier)

When the player crosses back: the LB needs scenery + EnvCells re-loaded. Hysteresis (don't churn at the exact boundary) is needed.

The streaming loader already has hysteresis for full LB load/unload. A.5 extends that: a separate hysteresis radius for the scenery/entity layer.

6. Visual quality wins to ride along

A.5 is the natural place to land 2-3 nearly-free quality wins:

• Mipmapped terrain atlas + anisotropic 16x. Today the atlas is GL_LINEAR no mipmaps; distant terrain shimmers. ~half-day fix. Big visible improvement at far tier.
• Tree alpha-test → alpha-to-coverage with MSAA. Today tree edges are binary cutoff and pixel-edged. A2C with MSAA fixes them. ~one day.
• Correct depth-write for transparent foliage. Some scenery passes may be writing depth incorrectly; confirm + fix.

These are not strictly required for A.5 to ship, but they amplify the "looks great" payoff.

7. Acceptance metrics

The user's goal is "smooth + high FPS + great-looking + scales." Pin this concretely:

• Target FPS at radius (whatever final N₁ + N₂): ≥ user's monitor refresh (probably 144 or 240 Hz). Capture before/after numbers in a perf baseline doc parallel to N.5b's.
• No frame-time spikes > 5ms during streaming (record a 60-second trace running through Holtburg → North Yanshi).
• Visual horizon visible at the new N₂. Capture screenshots from the same vantage point at the start of A.5 (before) and at ship (after) for the SHIP record.

8. What's NOT in A.5

A.5 does not need to ship:

• GPU-side culling (compute-shader cull). Bigger lift; N.6 territory.
• Persistent-mapped indirect buffer. N.6 territory.
• Sky / particles / EnvCells migration. Separate N.7+ phases.
• Shadow mapping. Separate visual phase.

Don't let scope creep pull these in.

---

Files to read before brainstorming

In rough order of relevance:

1. docs/research/2026-05-09-phase-n5b-handoff.md — N.5b's handoff (read for context on what was just shipped + the structure of these handoff docs).
2. docs/plans/2026-05-09-phase-n5b-perf-baseline.md — captured perf numbers + the architectural reasoning for what A.5 inherits.
3. memory/project_phase_n5b_state.md — three high-value gotchas captured during N.5b (especially #1: bindless uniform-sampler driver quirk; A.5 won't directly need this, but it's the prior art for any new shader code in the phase).
4. docs/plans/2026-04-11-roadmap.md A.5 entry — the original A.5 description.
5. The streaming loader — src/AcDream.Core/World/StreamingLoader.cs (or wherever it lives; grep for OnLandblockLoaded). Understand the existing ring + hysteresis logic before extending it.
6. WB dispatcher entity flow — src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs lines covering Draw (the per-entity walk) and EntitySpawnAdapter (where entities get registered). The bucketing change lands here.
7. LandblockMesh.Build — src/AcDream.Core/Terrain/LandblockMesh.cs. Its inputs (heightmap, ctx, surfaceCache) determine what the worker thread needs. ~150 lines.
8. WB's SceneryRenderManager — references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/SceneryRenderManager.cs. Has a render-distance cap; informs N₁ vs N₂ defaults.
9. TerrainModernRenderer — src/AcDream.App/Rendering/TerrainModernRenderer.cs. Don't modify; confirm the slot allocator handles radius=15 cleanly.

---

Acceptance criteria for the whole phase

1. Build green; existing tests stay green; N.5b's conformance sentinel still passes (visual mesh Z = TerrainSurface Z within 1mm).
2. Far-tier LBs render terrain visibly past N₁ in user-driven visual verification.
3. Per-frame entity-dispatcher cpu_us at radius=N₁ drops vs today (the bucketing should help even at the current radius).
4. Per-frame entity-dispatcher cpu_us at radius (N₁+N₂) is bounded — does NOT scale linearly with total loaded LBs. Specifically: bucketed cull should be < 1.5× today's cost despite far-tier LBs loading.
5. No streaming hitch > 5ms when running at run-speed across N₁/N₂ tier boundaries simultaneously (capture a 60s trace).
6. [TERRAIN-DIAG] cpu_us stays flat as N₂ grows — the terrain dispatcher proven O(1) (regression check).
7. Visual identity at near-tier (no scenery missing inside N₁; no z-fighting; no cell-boundary wobble — N.5b sentinel still applies).
8. SHIP record + perf baseline + memory entry written, mirroring N.5b's pattern.

---

What you'll be doing in the first 30 minutes

1. Read this handoff in full.
2. Read docs/research/2026-05-09-phase-n5b-handoff.md for the structural pattern.
3. Read docs/plans/2026-05-09-phase-n5b-perf-baseline.md for the captured numbers A.5 inherits.
4. Read memory/project_phase_n5b_state.md for gotchas.
5. Verify build is green: dotnet build.
6. Verify N.5b ship is intact: dotnet test --filter "FullyQualifiedName~TerrainSlot|FullyQualifiedName~TerrainModernConformance|FullyQualifiedName~Wb|FullyQualifiedName~MatrixComposition|FullyQualifiedName~TextureCacheBindless" (target ≥114 passing, 0 failures).
7. Capture a baseline radius=5 frame trace yourself (one launch, 30s standstill at Holtburg dueling field) so you have a "before" number in your own measurement environment, not just trusting N.5b's number.
8. Invoke superpowers:brainstorming with the user. Walk through the 8 brainstorm questions above. Present each with options + my recommendation; don't prejudge.
9. After agreement, write the spec; then the plan; then execute task-by-task using superpowers:subagent-driven-development.

Don't skip the brainstorm. The N₁/N₂ values, the bucketing structure trade-offs, and the worker-thread design are real decisions with downstream consequences that need user input — not "the agent makes a call and goes."

---

Things to NOT do

• Don't raise ACDREAM_STREAM_RADIUS without A.5's tiered loading in place. The entity-cull cliff is immediate and severe (8 FPS at naive radius=15).
• Don't put scenery in the far tier just to "look more retail" without a billboard/impostor pipeline. Full-detail scenery in the far tier is what causes the cull cliff.
• Don't move LandblockMesh.Build to a worker thread without first auditing TerrainBlendingContext + _surfaceCache for thread safety. Concurrent writes to the surfaceCache will produce silently-wrong terrain blending.
• Don't break the N.5b conformance sentinel. If A.5 changes how meshes are built (e.g., for the worker thread), the conformance test must still pass — it's the load-bearing physics ↔ visual Z agreement guard.
• Don't bundle GPU-side culling, persistent-mapped buffers, or shadow mapping into A.5. Those are N.6+ territory; A.5 is "make the world look big and not stutter."
• Don't ship without honest perf numbers. If A.5 doesn't actually hit its FPS target, document why and ship N.6 next instead of papering over it. The N.5b precedent is honest reporting.
• Don't skip the visual verification gate. Same lesson from N.5b's black-terrain regression: "go" doesn't mean "verified." User must actually launch the client at radius=N₂ and confirm the horizon looks great + FPS hits target.

---

Reference: where the FPS budget actually goes today

For brainstorming purposes, the per-frame breakdown at radius=5 / Holtburg (real measurement, 2026-05-09):

~5,000 µs total frame time (= 200 fps)
├── 4,300 µs  WbDrawDispatcher entity cull + dispatch  ← THE BOTTLENECK
│             ~16K entity AABB tests / frame
│             A.5's entity bucketing attacks this directly
├──     6 µs  TerrainModernRenderer
│             O(1) in radius. Won't grow with A.5. Already solved.
├──   ~700 µs Sky, particles, ImGui, audio, swap-buffers, misc
│             Mostly fixed cost; some VSync-related
└──    rest   GPU side (we don't measure this — query plumbing
              deferred to N.6). Could be substantial.

The first action of A.5 is to recognize that the perf claim "810 fps" from N.5 was misleading. Don't repeat the mistake — measure the actual frame time, not just one subsystem.

---

Good luck. The phase is meaty (~2 weeks) but the structural work is well-shaped: tiered streaming has clear boundaries, entity bucketing is an isolated dispatcher change, off-thread mesh build is a well-understood worker pattern. The hard call is the N₁/N₂ values, and that's a brainstorm question — bring it to the user with data.