acdream/docs/research/2026-05-09-phase-n5b-handoff.md

# Phase N.5b — Terrain on the Modern Rendering Path — Cold-Start Handoff

**Created:** 2026-05-09, immediately after N.5 ship + roadmap A.5 addition.
**Audience:** the next agent picking up terrain rendering work.
**Purpose:** give you everything you need to start N.5b cold, without
spelunking through the N.5 session's history.

---

## TL;DR

N.5 just shipped: `WbDrawDispatcher` lifts entity rendering onto bindless
textures + `glMultiDrawElementsIndirect`. CPU dispatcher 1.23 ms / frame
median at Holtburg courtyard, ~810 fps sustained. **Entities only —
terrain is still on a separate legacy renderer.**

**N.5b's job: port terrain rendering onto the same modern primitives that
N.5 just delivered.** Concretely:

1. Replace `TerrainRenderer` + `TerrainChunkRenderer` (per-landblock VAO,
   `glDrawElements`, `sampler2D` atlases) with a multi-draw-indirect
   dispatcher analogous to `WbDrawDispatcher`, sharing the modern path's
   bindless texture infrastructure where it makes sense.
2. Keep terrain visually identical to today. The legacy `TerrainAtlas` +
   `terrain.vert/.frag` already render correctly; don't introduce visual
   regressions.
3. Resolve issue #51 (WB's terrain split formula diverges from retail's
   `FSplitNESW`) — see "Load-bearing constraint" below.

The roadmap estimate is **~1 week** because the modern-path primitives
are already built. The actual work is porting + bridging + a real
correctness decision on the split formula.

---

## Load-bearing constraint: Issue #51 (terrain split formula)

This is the design decision that will dominate the brainstorm. **Read
`docs/ISSUES.md` issue #51 in full before brainstorming.**

The short version:

- **acdream's terrain split formula** is the retail-decomp `FSplitNESW`
  (constants `0x0CCAC033` / `0x421BE3BD` / `0x6C1AC587` / `0x519B8F25`).
  Documented in `CLAUDE.md` as **the** real AC formula. Ours is degree-2
  polynomial in (x,y). Used by:
  - `src/AcDream.Core/Physics/TerrainSurface.cs:113-120` (physics —
    `IsSplitSWtoNE`)
  - `src/AcDream.Core/World/TerrainBlending.cs` (visual mesh)
- **WB's terrain split formula** in `references/WorldBuilder/WorldBuilder.Shared/Modules/Landscape/Lib/TerrainUtils.cs:44`
  is LINEAR in (x,y). Different math; they cannot be algebraically
  equivalent. They disagree on a meaningful fraction of cells — up to
  ~2m height delta on sloped cells.
- **WB's `TerrainGeometryGenerator`** (the obvious adoption target for
  N.5b's mesh path) uses WB's formula. If we adopt it wholesale, our
  visual terrain disagrees with our physics (which uses retail's
  formula). Player floats / sinks. Already-fixed bug class returns.

**Three viable design paths** (the brainstorm has to pick one):

- **Path A — Adopt WB's formula everywhere.** Switch both physics AND
  visual mesh to WB's `CalculateSplitDirection`. Use WB's
  `TerrainGeometryGenerator` directly. Visual + physics stay synced.
  Risk: physics now disagrees with retail server-authoritative Z by up
  to ~2m on sloped cells. Server-side validation (if any) might reject
  movements; the player might "snap" to server's Z when packets land.
  Need to confirm whether ACE actually validates Z or trusts the
  client. Lowest implementation effort.

- **Path B — Keep retail's formula; fork-patch WB.** Patch
  `references/WorldBuilder/.../TerrainUtils.cs` to use retail's formula
  in our fork. Push the patch to the `acdream` branch of the fork (per
  the WB submodule plumbing fixed in the previous session). Submit
  upstream PR if Chorizite wants it. Most retail-faithful. Implementation
  effort: medium. Coordination overhead with upstream.

- **Path C — Use WB's mesh layout but our formula.** Don't use WB's
  `TerrainGeometryGenerator` directly. Instead port WB's *mesh layout*
  (vertex buffer shape, index buffer per landblock, atlas integration)
  into a new acdream-side `TerrainGeometryGenerator` that uses retail's
  formula. Highest effort but cleanest separation — no fork patches.

Recommendation in the brainstorm: probably **Path A** if quantification
shows ACE doesn't validate Z aggressively (retail's network protocol
is "client tells server position; server trusts within sanity bounds"),
otherwise **Path B**. Path C is overengineered for the level of
divergence.

**Step 1 of the brainstorm:** quantify the divergence. Run WB's formula
+ retail's formula across all (lbX, lbY, cellX, cellY) tuples for
several representative landblocks (Holtburg, Foundry, open landscape,
some sloped terrain like Direlands). Record disagreement rate. If <5%
of cells disagree, Path A's risk is bounded; if >20%, Path B becomes
more attractive.

---

## Where N.5 left things

### Branch state

After last session:
- `main` is at `a64cd11` ("docs(roadmap): add A.5 — two-tier streaming")
- N.5 SHIP at `27eaf4e` (merge commit)
- N.5 ship-amendment at `e0dbc9c` (legacy renderers retired)
- Legacy `InstancedMeshRenderer` + `StaticMeshRenderer` + `WbFoundationFlag`
  ARE GONE. Bindless is mandatory; missing extensions throws
  `NotSupportedException` at startup.

### What works in N.5

- **Entity rendering:** `WbDrawDispatcher` does ~12-15 GL calls per frame
  for all visible entities regardless of scene complexity. Three SSBO
  uploads (instance matrices @ binding=0, batch data @ binding=1,
  indirect commands) + 2 `glMultiDrawElementsIndirect` calls (opaque +
  transparent passes).
- **Bindless texture infrastructure:** `BindlessSupport` wrapper +
  `TextureCache` parallel `UploadRgba8AsLayer1Array` path + three
  `Bindless*` `GetOrUpload` methods + two-phase `Dispose`. All textures
  on the WB modern path are 1-layer `Texture2DArray` + `sampler2DArray`.
- **mesh_modern.vert/.frag** preserves the full `SceneLighting` UBO
  (8 lights + fog + lightning flash + per-channel clamp) — visual
  identity to N.4 confirmed at user gates.
- **Diagnostic:** CPU stopwatch + GL_TIME_ELAPSED queries logged via
  `[WB-DIAG]` (GPU timing currently shows 0/0 — query polling needs
  double-buffering, deferred to N.6).

### What N.5b inherits

These are levers N.5b will pull on:

- **`BindlessSupport`** at `src/AcDream.App/Rendering/Wb/BindlessSupport.cs`
  — already wraps `ArbBindlessTexture`. Reusable for terrain textures.
- **`DrawElementsIndirectCommand` struct** at `src/AcDream.App/Rendering/Wb/DrawElementsIndirectCommand.cs`
  — 20-byte layout, ready to populate per-landblock terrain commands.
- **`BuildIndirectArrays` helper** at `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs`
  — pure CPU layout helper, currently scoped to entities; could
  generalize for terrain.
- **`TextureCache`** with parallel Texture2DArray bindless cache —
  but terrain has its own `TerrainAtlas` (multi-layer texture array
  for splat blending). N.5b decides whether to integrate or keep
  separate.
- **`SceneLightingUbo`** at binding=1 — terrain.frag already consumes
  it; the new modern terrain shader continues that.
- **Retail's `FSplitNESW`** in `src/AcDream.Core/World/TerrainBlending.cs`
  — the formula to preserve (or replace, per Path A/B/C decision).

### What still uses the legacy path (NOT N.5b's job)

- **Sky rendering** (`SkyRenderer.cs`) — N.8 territory.
- **Particles** (`ParticleRenderer.cs`) — N.8 territory.
- **Debug lines** (`DebugLineRenderer.cs`) — fine as-is.
- **UI / text** (`TextRenderer.cs` + ImGui) — fine as-is; ImGui has its
  own backend.

---

## What N.5b is — technical detail

### Today's terrain stack (1383 lines acdream + ~140 lines shaders)

| File | Lines | Role |
|---|---|---|
| `src/AcDream.App/Rendering/TerrainRenderer.cs` | 247 | Top-level orchestration; per-landblock cull + draw |
| `src/AcDream.App/Rendering/TerrainChunkRenderer.cs` | 454 | Per-landblock VAO + IBO management; `glDrawElements` per visible chunk |
| `src/AcDream.App/Rendering/TerrainAtlas.cs` | 386 | Multi-layer `Texture2DArray` atlas for terrain splat textures |
| `src/AcDream.App/Rendering/Shaders/terrain.vert` | 147 | Per-vertex world position, normal, UV, palCode |
| `src/AcDream.App/Rendering/Shaders/terrain.frag` | 149 | Splat blending across 4 corner textures |

**Per-frame today:** for each visible landblock, bind its VAO + IBO,
bind the terrain texture atlas, set per-landblock uniforms, issue
`glDrawElements`. With 25 landblocks at default radius=2, that's ~25
draw calls per frame for terrain (cheap, but doesn't scale).

### WB's terrain stack (1937 lines + ~200 lines shaders)

| File | Lines | Role |
|---|---|---|
| `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TerrainRenderManager.cs` | 1023 | Top-level coordinator; uses multi-draw-indirect already |
| `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TerrainGeometryGenerator.cs` | 326 | Mesh generation per landblock (uses WB's split formula — see #51) |
| `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/LandSurfaceManager.cs` | 588 | Texture atlas management + alpha mask generation for splat blending |
| `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Shaders/Landscape.vert/.frag` | ~200 | Modern shader; consumes SSBO instance data + bindless atlas handle |

WB's renderer is structurally close to what N.5b targets. Key differences
from acdream:

- WB uses **uint32 indices** (`DrawElementsType.UnsignedInt`) for
  terrain — landblocks have more vertices than fit in ushort range.
  N.5's `WbDrawDispatcher` uses `UnsignedShort` for entities.
- WB packs all visible terrain into shared mesh buffers + dispatches
  via `glMultiDrawElementsIndirect`. We can mirror that pattern.
- WB's `LandSurfaceManager` builds per-landblock alpha masks for splat
  blending; this is the bulk of its 588 lines. Different model from
  our `TerrainAtlas` which uses palCode-based blending in the fragment
  shader.

### What N.5b actually does

Roughly four sub-pieces:

1. **Terrain mesh on global VBO/IBO.** Following N.5's pattern, all
   visible terrain landblocks pack into a single global vertex buffer
   + index buffer. Per-landblock entries become `DrawElementsIndirectCommand`
   records with `firstIndex` + `baseVertex` offsets. One
   `glMultiDrawElementsIndirect` call per pass.
2. **Bindless terrain atlas.** Either (a) port `TerrainAtlas` to use
   bindless handles + sampler2DArray (small change, keeps current
   blending math), or (b) adopt WB's `LandSurfaceManager` (bigger
   change, switches to alpha-mask blending). Brainstorm decides.
3. **New shader `terrain_modern.vert/.frag`** that:
   - Reads per-landblock data from an SSBO (analogous to
     mesh_modern's `Batches[]`)
   - Samples the terrain atlas via bindless `sampler2DArray` handle
   - Continues to consume `SceneLighting` UBO @ binding=1 (no
     visual identity regression vs N.4 — same lighting math)
4. **Resolve issue #51** per Path A/B/C decision in the brainstorm.

### Per-frame target shape

```
// Once at init:
Build global terrain VAO + VBO + IBO (resizable; grows as landblocks stream in)
Generate bindless handles for terrain atlas

// Per frame:
1. Frustum cull landblocks (existing per-landblock AABB test)
2. Build per-visible-landblock IndirectGroupInput list
3. Upload _terrainBatchSsbo + _terrainIndirectBuffer
4. glBindVertexArray(globalTerrainVao)
5. glBindBufferBase(SHADER_STORAGE_BUFFER, 1, _terrainBatchSsbo)
6. glBindBuffer(DRAW_INDIRECT_BUFFER, _terrainIndirectBuffer)
7. glMultiDrawElementsIndirect(...)  // ONCE per pass — opaque pass
   (terrain has no transparent; one indirect call total)
```

Total ~6-8 GL calls per frame for terrain regardless of scene size.
At radius=5 (121 landblocks) this is the same number of GL calls as
at radius=2 (25 landblocks).

---

## Files to read before brainstorming

In rough order:

1. **`docs/ISSUES.md` issue #51** (49-103). Load-bearing constraint.
2. **`CLAUDE.md`** the "Reference hierarchy by domain" terrain row +
   "Reference repos: check ALL FOUR" — terrain math is one of the
   places where checking multiple references matters most.
3. **acdream terrain stack:**
   - `src/AcDream.App/Rendering/TerrainRenderer.cs` (247 lines, easy
     read)
   - `src/AcDream.App/Rendering/TerrainChunkRenderer.cs` (454 lines —
     this is the per-landblock GL plumbing that goes away in N.5b)
   - `src/AcDream.App/Rendering/TerrainAtlas.cs` (386 lines —
     multi-layer atlas)
   - `src/AcDream.App/Rendering/Shaders/terrain.vert/.frag` (~300
     lines combined)
   - `src/AcDream.Core/World/TerrainBlending.cs` (the FSplitNESW
     side; preserve or replace)
4. **WB terrain stack:**
   - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TerrainRenderManager.cs`
     (1023 lines — the model to mirror; multi-draw indirect already
     in place)
   - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/TerrainGeometryGenerator.cs`
     (326 lines — uses WB's split formula; per #51)
   - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/LandSurfaceManager.cs`
     (588 lines — alpha-mask atlas; alternative to our `TerrainAtlas`)
   - `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Shaders/Landscape.vert/.frag`
   - `references/WorldBuilder/WorldBuilder.Shared/Modules/Landscape/Lib/TerrainUtils.cs:44`
     (CalculateSplitDirection — WB's formula)
5. **N.5 plan + spec** (cribs for the modern-path pattern):
   - `docs/superpowers/plans/2026-05-08-phase-n5-modern-rendering.md`
     (what we did, including amendments)
   - `docs/superpowers/specs/2026-05-08-phase-n5-modern-rendering-design.md`
     (decisions log)
6. **Memory: `project_phase_n5_state.md`** — three high-value gotchas
   from N.5 (texture target lock-in, bindless Dispose order,
   GL_TIME_ELAPSED double-buffering). All apply to N.5b.

---

## Brainstorm questions

These are the questions to resolve in the brainstorm step. Don't
prejudge — bring them to the user with options + recommendation:

1. **Path A vs B vs C** for issue #51 (the terrain split formula). The
   biggest decision; everything else flows from it. Should be
   informed by quantifying the divergence rate first (run both
   formulas across representative landblocks).

2. **Atlas model.** Keep `TerrainAtlas` (palCode-based fragment shader
   blending) and just bindless-ify it, or adopt WB's `LandSurfaceManager`
   (alpha-mask blending)? Tradeoff: minimal change vs alignment with
   WB. Visual outcome should be identical either way.

3. **Mesh ownership.** Use a single global VBO/IBO for all terrain
   (mirror N.5's pattern), or per-landblock VBO/IBO with multi-draw
   indirect over them? Single global is more cache-friendly + more
   like N.5, but requires resizable buffer management. Per-landblock
   is simpler but doesn't share the IBO across draws.

4. **Index format.** N.5 uses `UnsignedShort` (max 64K verts per
   draw). Terrain landblocks have many more verts than that. WB uses
   `UnsignedInt`. Just commit to `UnsignedInt` for terrain?

5. **Shader unification.** Separate `terrain_modern.vert/.frag` or
   merge with `mesh_modern.vert/.frag` via uniforms? Probably separate
   since the vertex layouts differ (terrain has palCode; entities
   have UV).

6. **Streaming integration.** Today's `TerrainChunkRenderer` integrates
   with the streaming loader (landblocks come and go). N.5b's global
   buffer model needs a strategy for adding/removing landblocks from
   the global VBO/IBO without per-add reallocation. Free-list /
   compaction / fixed-slot allocator?

7. **Conformance test.** Per the lessons from N.2, "WB's terrain
   formula differs from retail" — we need a test that proves our
   visual terrain matches our physics terrain (i.e., visual mesh Z
   at any (X,Y) equals `TerrainSurface.GetHeight(X,Y)`). Run a sweep
   across ~1M (X,Y) points; assert |delta| < epsilon.

8. **Visual verification gate.** Holtburg + Foundry + sloped terrain
   (Direlands?) + cell transitions. The split-formula-disagreement
   bug class shows up as terrain "wobble" at cell boundaries — that's
   the specific thing to look for.

---

## Acceptance criteria for the whole phase

- Visual terrain identical to current legacy path (no missing chunks,
  no z-fighting at cell boundaries, no texture seams)
- `[WB-DIAG]` shows terrain accounting for ~6-8 GL calls per frame
  regardless of scene size (currently scales with visible landblock
  count, ~25-121 calls)
- Frame time measurably lower in dense-terrain scenes (specify scenes
  in the spec — probably radius=5 outdoor roaming)
- Conformance test: visual mesh Z agrees with `TerrainSurface.GetHeight`
  within epsilon across a 1M-point sweep
- All existing tests still green
- The split-formula decision (#51) is resolved with a clear writeup
  in the spec

---

## What you'll be doing in the first 30 minutes

1. Read this handoff in full.
2. Read `docs/ISSUES.md` issue #51 in full.
3. Read CLAUDE.md "Reference hierarchy by domain" terrain row.
4. Read `TerrainRenderer.cs` + `TerrainChunkRenderer.cs` end-to-end.
5. Skim `TerrainRenderManager.cs` (WB's) — at least the multi-draw
   indirect dispatch section.
6. Verify build is green: `dotnet build`.
7. Verify N.5 ship is intact: `dotnet test --filter "FullyQualifiedName~Wb|FullyQualifiedName~MatrixComposition|FullyQualifiedName~TextureCacheBindless"` should produce 71 passing tests, 0 failures.
8. Quantify the formula divergence (Path A/B/C decision input):
   write a one-shot test that runs both formulas across all
   (lbX, lbY, cellX, cellY) tuples for ~10 representative landblocks
   and reports disagreement rate.
9. Invoke the `superpowers:brainstorming` skill with the user. Walk
   through the 8 brainstorm questions above. Bring the formula
   divergence number to inform the Path A/B/C decision.
10. Write the spec.
11. Write the plan.
12. Begin Week 1 implementation per the plan.

Don't skip the brainstorm. The terrain split formula decision (Path
A/B/C) has real downstream consequences — physics, server-Z agreement,
fork-patching of WB. Needs explicit user input, not "the agent makes
a call and goes." This phase is structurally the same shape as N.5 —
brainstorm → spec → plan → tasks-with-checkboxes → commits-update-checkboxes
→ final SHIP commit.

---

## Things to NOT do

- **Don't adopt WB's terrain code wholesale without resolving #51
  first.** The split formula decision affects the entire pipeline;
  patching it after-the-fact requires re-doing visual + physics + the
  TerrainGeometryGenerator port.
- **Don't introduce a per-cell wobble at landblock boundaries.** That's
  the visible signature of the formula disagreement. If you see it
  during visual verification, the formula isn't aligned between your
  physics and visual paths.
- **Don't break the existing `[WB-DIAG]` instrumentation.** Add a
  separate counter for terrain (`terrainDrawsIssued`) so the entity
  + terrain perf can be observed independently.
- **Don't bundle A.5 (two-tier streaming + horizon LOD) into this
  phase.** N.5b is "terrain on modern path"; A.5 is "split the radius
  + LOD." Different scopes, different brainstorms. A.5 might become
  natural to pick up next once N.5b lands.
- **Don't try to re-port `FSplitNESW` if you're going Path A.** The
  whole point of Path A is to commit to WB's formula. If you keep
  retail's formula via Path B/C, do it once, definitively.
- **Don't skip the formula-divergence quantification.** Step 8 of
  the first 30 minutes. The Path decision should be data-informed,
  not gut-feel. <5% divergence makes Path A bounded-risk; >20% makes
  Path B/C more attractive.
- **Don't skip visual verification.** The split-formula bug class
  shows up as cell-boundary wobble that's hard to spot in screenshots
  but obvious in motion. Walk a sloped landblock during verification.
- **Don't extend the phase scope.** N.5b is "terrain on modern path."
  Sky, particles, EnvCells — all subsequent phases. If the brainstorm
  tries to expand, push back.

---

## Reference: the N.5 dispatcher flow you're mirroring

```
WbDrawDispatcher.Draw(...) {
  // Phase 1: walk entities, build groups
  // Phase 2: lay matrices contiguously
  // Phase 3: build BatchData + DEIC arrays via BuildIndirectArrays
  // Phase 4: upload 3 SSBOs (instances, batches, indirect)
  // Phase 5: bind global VAO + SSBOs
  // Phase 6: opaque pass — glMultiDrawElementsIndirect
  // Phase 7: transparent pass — glMultiDrawElementsIndirect
}
```

For terrain the shape is similar but simpler:

```
TerrainModernDispatcher.Draw(...) {
  // Phase 1: walk visible landblocks, frustum cull
  // Phase 2: build per-landblock IndirectGroupInput list
  //          (one entry per visible landblock — typically 25-121)
  // Phase 3: upload 2 SSBOs (terrain batch data, indirect commands)
  //          (no per-instance buffer needed — terrain isn't instanced)
  // Phase 4: bind global terrain VAO + SSBOs
  // Phase 5: opaque pass ONLY — glMultiDrawElementsIndirect
}
```

Total ~6-8 GL calls per frame for terrain. That's the destination.

Good luck. The split-formula decision is the only really hard call;
everything else is mechanical port work on top of N.5's substrate.
Holler at the user if anything in #51's three paths feels genuinely
ambiguous after reading the references.