acdream/docs/plans/2026-06-11-building-render-port-plan.md

# The holistic building-render port plan (Phase B) — one drawing discipline

**Status: AWAITING USER APPROVAL — no implementation until approved.**
Companion to the Phase A comparison:
[`docs/research/2026-06-11-building-render-acdream-vs-retail-comparison.md`](../research/2026-06-11-building-render-acdream-vs-retail-comparison.md)
(evidence appendices in
[`docs/research/2026-06-11-holistic-map/`](../research/2026-06-11-holistic-map/)).
Mandate: *"one solution that works every time I walk to a new landblock and
walk into a dungeon"* (2026-06-11).

---

## 0. The invariant (what "one drawing discipline" means, retail-cited)

Every phase below moves us toward — and no phase may move us away from — this
frame shape, which is retail's (Ghidra-cited in the comparison doc §2):

1. **Geometry is flattened at load** into surface-batched meshes (we already
   do this). World geometry is **never geometrically clipped at draw time**.
2. **Untextured (solid) surface batches never draw** on building shells and
   cell meshes (`skipNoTexture`); they do draw on plain objects.
3. **Portal polygons are not wall geometry.** They exist per frame only as
   (a) flood admission tests (`ConstructView`: eye-side ε=0.0002 → clip vs
   current view → cell loaded) and (b) **invisible depth writes** — far-Z
   *punch* before an interior draws through an aperture; true-depth *seal*
   on portals to the outside after the landscape draws.
4. **Cells draw whole, far→near, once** (frame stamp); the z-buffer plus the
   punches/seals produce pixel-exact apertures.
5. **Objects and particles are culled per portal view** (sphere vs the view's
   edge planes — `viewconeCheck`), never clipped, never scissored.
6. **One visibility computation feeds everything** — the PView flood. No
   second BFS, no parallel gate, no distance constants in admission.

## 1. Keep-list (the code worth saving — explicitly not touched/rewritten)

- **Mesh pipeline**: `ObjectMeshManager` flatten + global VAO + bindless MDI
  (`WbDrawDispatcher`) — retail-faithful architecture, confirmed by the
  `ConstructMesh`/`RemoveNonPortalNodes` finding.
- **The flood port**: `PortalVisibilityBuilder` (homogeneous clipper, side
  tests, reciprocal clip, exact-match skip) + conformance gates
  (`CornerFloodReplayTests`, `Issue113MeetingHallFloodTests`) — BR-4 adjusts
  constants/heuristics, it does not rewrite the clipper.
- **Membership** (P1 9/9 golden) + **straddle gate** (`414c3de`) +
  **camera collision sweep** (verbatim `update_viewer`) + **znear=0.1** +
  **#105 texture flush** + **two-tier streaming** + spawn/snap validation
  (#107/#111/#112).
- Diagnostics/probes and the dat dump harness.

The M0 freeze list is superseded *for rendering only* by the 2026-06-11
mandate; nothing outside building/interior render + interior collision is in
scope.

## 2. Phases

Ordering rule: each phase lands green (build + full suites + named visual
gate) and the client stays playable after every phase. Conformance pins come
from the dat harness + the flood replay harnesses; retail constants are cited
inline when ported.

### BR-1 — The draw-time surface gate (kills the phantom class)

**What:** classify every mesh batch at decode by surface texturedness
(`Surface.Type & (Base1Image|Base1ClipMap)`); at draw, skip untextured
batches for **building-shell entities and cell meshes only** (plain objects
keep drawing them — retail's bypass). Align the cell-side build-time
`NoPos`/`NoNeg` drop with this rule: run a dat-wide sweep (all CellStructs +
all building models in the populated landblocks) proving
`portal-fill ⇔ untextured`; keep the cheaper build-time drop only where the
sweep proves equivalence, otherwise move to the draw-time gate. GfxObj-side:
fills stay in the mesh but never draw (matches retail exactly).

- **Closes:** #113 phantom staircase class (hall ramp, cottage "flying
  stairs", every building's baked fills) — without touching doors (entities).
- **Acceptance:** `DumpPortalFillSurfaceTypes`-derived conformance sweep
  green; hall + hill-cottage phantom gone and doors/windows intact at
  Holtburg (user gate); all suites green.
- **Risk note:** apertures whose flood fails become true holes
  (retail-identical); per-building floods + DrawPortal look-in already cover
  the visible cases. If a hole shows at an unflooded aperture, that is BR-2/
  BR-4 evidence, not a BR-1 regression.
- **Size:** ~2 commits (batch metadata plumb + draw gate; sweep test).

### BR-2 — Aperture depth machinery (punch / seal / clear)

**What:** port the invisible depth writes:
(a) wire `DrawExitPortalMasks` (today an unwired no-op) as a depth-only draw
of each outside-leading portal polygon, software-clipped to its view slice
(the `ClipToRegion` math already exists), at the portal's **true projected
depth** (retail `maxZ2`) — after the landscape slices, indoor roots;
(b) add the **far-Z punch** (retail `maxZ1`) on building-aperture flood
success on the outdoor + look-in paths, before the interior cells draw;
(c) replace the per-slice scissored `ClearDepthSlice` AABB clear with
retail's discipline: one full depth clear between the outside stage and the
interior stage, gated on whether any seal was drawn (`portalsDrawnCount`);
(d) on the look-in path, draw interior-through-aperture **before** the shell
mesh (retail `DrawBuilding` order) so the shell's depth closes everything
outside the punch.

- **Closes:** #108 (outdoor terrain sweeping across the upstairs door — the
  missing true-depth seal is the confirmed `missing-portal-depth-fence`
  divergence); the outdoor-root depth-discipline gap; part of #109.
- **Acceptance:** cellar↔main-floor walk shows no grass sweep (user gate);
  new harness fact: seal depth = portal plane depth inside the clipped
  aperture polygon (GL readback test or probe assertion); suites green.
- **Size:** ~3 commits (~80 lines of GL + clipper reuse per the area
  estimate, plus the clear re-shape and order swap).

### BR-3 — Retire the geometric shell chop; whole-shell far→near draws

**What:** remove `gl_ClipDistance` as the *enforcement* mechanism for cell
shells (both the outdoor-scoped enable from `927fd8f`/`9ce335e` and the
never-enabled indoor half — i.e. #114 closes by *deleting* the chop, not
perfecting it). Shells draw whole, far→near per `OrderedVisibleCells`
(already the order), drawn-once. Clip regions remain for admission, punch
shapes, and (BR-5) object culling. The landscape-through-aperture pass keeps
its per-slice plane clip for now (open Q: `LScape::draw` internals) — revisit
after BR-2 proves the seal protects terrain.

- **Closes:** #114 (chopped stairs / vanished candle area / barrel-through-
  wall were artifacts of clipping geometry retail never clips) — jointly
  with BR-2. Removes the 8-plane budget + slot-0 PASS-ALL as load-bearing
  for shells.
- **Acceptance:** meeting-hall interior + multi-room cottages render
  unchopped from indoor and outdoor eyes (user gate vs the #114 screenshot
  set); phantom stays gone (BR-1 unaffected); flood replay gates green.
- **Order constraint:** must not land before BR-2 (the depth fence replaces
  the chop's job at apertures).
- **Size:** ~2 commits (mostly deletions + the draw-order assertion).

### BR-4 — Shell-draw-driven floods + flood fidelity

**What:** make the building's own draw the flood trigger, retail-shaped:
pair the shell GfxObj's `PortalRef.PortalIndex` with its `BuildInfo.Portals`
entry (the `outdoor_portal_list` correspondence) and, when a shell survives
the cull for a view slice, run each aperture through the ported
`ConstructView(CBldPortal)` chain under that slice. Then remove the
non-retail machinery the trigger replaces: the 48 m seed constant, the
Chebyshev≤1 candidate gather, the `EyeInsidePortalOpening` full-view rescue;
adopt retail constants (ε=0.0002; in-plane rejects for building portals);
add the 1-px screen-space vertex dedup to `ClipToRegion` output (retail's
fixpoint floor) and switch late view growth to in-place propagation
(`AddToCell`/`FixCellList`/`AdjustCellView` shape), removing the
`MaxReprocessPerCell=16` cap; make `MergeBuildingFrame` union views instead
of first-wins and retire single-slot consumers (`CellIdToSlot[0]`); bind
nested floods to their originating slot (the `building_view` latch).

- **Closes:** #109 (binary 48 m pop + first-wins view loss + missing punch
  are its named mechanisms); the flood-stability family (edge-on doorway
  residuals); enables interior-visible-through-window parity.
- **Acceptance:** flood replay harnesses extended: (a) building flood
  triggers with no distance constant — admission matches the
  clip-survival rule across an eye sweep; (b) two-aperture cell holds two
  views; (c) growth propagates without the cap on a portal-dense fixture;
  #109 spot user gate; suites green.
- **Size:** ~4–5 commits (trigger + pairing; constants/dedup; growth
  in-place; merge union; deletions).

### BR-5 — Per-view object + particle culling (viewconeCheck)

**What:** port `Render::viewconeCheck`: per view slice, lift the per-edge
eye planes (each NDC edge + the eye defines a plane — the `view_vertex.plane`
analog) and sphere-test every entity and emitter against the slice before
draw; route particles through the same gate and the same clip/punch
discipline (delete the `BeginDoorwayScissor` AABB path); fix the
outdoor-root unattached-emitter drop; gate the weather pass on
`is_player_outside` (player cell, not viewer root).

- **Closes:** particles-through-walls (candle flames in other buildings);
  rain-indoors-through-doorways; the neighbour-room object over-inclusion
  half of the old #114 report.
- **Acceptance:** flame-through-wall spot at Holtburg (user gate); a
  conformance fact pinning sphere-vs-slice culling on a fixture; no
  regression in entity draw counts outdoors (perf probe within noise).
- **Size:** ~3 commits.

### BR-6 — One gate: consolidate visibility + delete legacy paths

**What:** make the PView flood the only visibility computation:
remove the per-frame ACME BFS (`CellVisibility.ComputeVisibilityFromRoot`)
by folding its remaining consumers (lighting indoor flag etc.) onto PView/
membership outputs; delete or quarantine the confirmed legacy remnants
(`InteriorRenderer`, `IndoorDrawPlan` consumers of the old path, the
`clipRoot==null` second render branch, the dormant exit-mask wiring once
BR-2 rewires it, duplicate frustum implementation); one frustum, one
center/radius window.

- **Closes:** the `dual-live-visibility-computations` inconsistency class
  (the one-gate rule, `feedback_render_one_gate`); removes the surface area
  where two gates disagree (future flap-class bugs).
- **Acceptance:** gate-audit re-run shows ONE visibility computation per
  frame; every deletion verified by a launch + the visual gate set; suites
  green.
- **Size:** ~3 commits, mostly deletions (each independently revertable).

### BR-7 — Interior collision: per-cell shadow lists (A6.P4, verified)

**What:** ship the A6.P4 architecture with the investigation's corrections:
registration builds the cell set by sphere-overlap portal flood (not an XY
grid; crosses landblocks), per-cell `shadow_object_list` iteration on the
query side (`CheckOtherCells` runs env AND shadow objects per other cell),
buildings dispatch through a per-LandCell building channel
(`CSortCell.building` shape), `OtherPortalId` widened to signed with the
`>= 0` gate (sign-extension Ghidra-proven). Then remove the `b3ce505`
stopgap, the A6.P5 `hasExitPortal` widening, and the #90 stickiness
workaround.

- **Closes:** #99 (doors block from both sides), very likely #97; retires
  three flagged workarounds.
- **Acceptance:** A6.P4 spec acceptance (doors block both ways at Holtburg
  inn + cottages; #98 cellar ascent stays fixed — `CellarUp` harness green);
  capture/replay comparison on the door apparatus; suites green.
- **Size:** the A6.P4 spec's estimate stands (~5 commits); independent of
  BR-2..BR-5 — may run in parallel with them.

### BR-8 — Feel tier: camera, lighting, LOD (post-discipline polish)

- **BR-8a Camera (#115, verified root cause; can land any time):** damp the
  sought eye FROM the published collided viewer each frame (retail
  `PlayerPhysicsUpdatedCallback` shape) and apply the computed player fade
  over the 0.45→0.20 m band. Acceptance: cramped-interior turn feel (user
  gate). ~1–2 commits.
- **BR-8b Lighting (pending verifier confirmation):** interior sun mask
  (never sun-light interiors), static cell-light burn-in (all lights, not
  8-nearest), viewer light, per-object light selection, surface
  luminosity/diffuse. Acceptance: side-by-side interior look vs retail
  screenshots. Phase-sized; spec before code.
- **BR-8c LOD + dedup (low):** per-part degrade selection beyond humanoids;
  frame-stamp draw dedup. Optional per-cell interleave for draw-order parity
  is explicitly NOT planned (z-buffer makes it unnecessary; revisit only on
  evidence).
- **Picking refinements** (all-low area): defer; file as issues when the
  port changes what is clickable.

## 3. What this plan deliberately does NOT do

- No per-frame BSP traversal of ordinary geometry (retail doesn't either).
- No rewrite of the mesh/MDI pipeline, the flood clipper, membership, or
  streaming (keep-list).
- No `leaf_cells`/`CPartCell` port (path dormant in the 2013 binary — needs
  runtime proof first).
- No transparency-sorting work yet — that area's map is still re-running;
  fold its findings in as a BR-9 candidate after review (the AlphaList
  deferral machinery is already decompiled in the Area 1 file).

## 4. Sequencing summary

```
BR-1 (surface gate)          — first; standalone visual win, lowest risk
BR-2 (depth punch/seal)      — second; enables BR-3
BR-3 (delete shell chop)     — closes #114 with BR-2
BR-4 (draw-driven floods)    — closes #109; flood fidelity
BR-5 (viewconeCheck)         — particles/objects through the same gate
BR-6 (one gate + deletions)  — consolidation after the discipline is in
BR-7 (collision A6.P4)       — independent track; may interleave with BR-2..5
BR-8 (camera/lighting/LOD)   — feel tier; BR-8a may land early
```

Every phase: `dotnet build` + full suites green, conformance pins added with
retail citations, named user visual gate, roadmap/ISSUES updated in the same
session, and the render digest updated when a phase closes one of the named
bugs.

## 5. Approval asks

1. Approve the plan shape + ordering (BR-1 → BR-8, BR-7 parallel-capable).
2. Approve the deletions implied by BR-3/BR-6 (shell-chop enforcement,
   ACME BFS visibility, legacy render branches) — all on the strength of the
   cited evidence that retail has no counterpart.
3. Note the verification caveat: ~36/76 divergences still carry UNVERIFIED
   (resume in flight); BR-1..BR-3's load-bearing claims are either verified
   or dat-confirmed locally, so approval need not wait on the rest.