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

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

**EXECUTION STATUS (2026-06-11, post-BR-7): BR-2…BR-7 are ALL CODE-COMPLETE
on the branch — the render arc as the fused tasks T1–T4 (T1 `579c8b0` frame
order; T2 `cf8a2c3`/`529dfcf`/`88f3ce1` flood fidelity, two retail constants
refuted by the conformance gate and kept at documented tolerances; T3
`a6aec8c` viewconeCheck; T4 `4a307d3` one-gate deletions), and BR-7 (T6,
collision A6.P4) as `6ec4cde` (signed OtherPortalId gate) + `abf36e2`
(BuildShadowCellSet flood) + `dbfbf85` (per-cell architecture: flood
registration, building channel, per-cell query, b3ce505 DELETED — closes
#99) + `ca4b482` (straddle-only outside-add, A6.P5 widening + #90
stickiness removed). Of the 4 #99-era Core reds, 3 flipped green as
designed (door apparatus + tick-13558 + tick-22760's blocking invariant);
the 4th (BSPStepUp D4) + 22760's lateral-slide delta proved to be a
SEPARATE pre-existing slide-response family — filed #116, D4 skipped with
the reference (probes show the cell-set layer innocent). Suites: Core
1416/0/2skip, App 225, UI 420, Net 294.

**T5 EXECUTED 2026-06-11 (the single comprehensive user gate) — PARTIAL
PASS.** ✅ Confirmed by the user: doors block both ways incl. off-center
(#99 visual), cellar descent/ascent clean + #108 grass-sweep GONE, inn
2nd floor clean (#97 closed), interiors stable through doorways incl.
edge-on, #109 far-door oscillation GONE, formerly-popping stairs now
STABLE at all ranges (the distance-pop class is dead). ❌ Remaining —
four filed render artifacts: **#117** aperture-shaped see-through
(doors/interiors through terrain hills + through nearer buildings — the
punch erases occluder depth), **#118** character clipped+vanishes for a
moment on house exit, **#119** old-tower stairs partially invisible +
extraneous barrel (pre-existing; `[up-null]` permanently-invisible mesh
lead in the T5 log), **#120** `[pv-ERROR]` in-place-propagation
convergence tripwire at depth 128 on the cottage cells (self-detected
T2 invariant break — investigate first). Rain-indoors not verifiable
(clear weather). NEXT: fix #120 → #117 → #118 → #119 at the mechanism
level, then a focused re-gate on just those spots.**

**Status: APPROVED + AMENDED (2026-06-11). EXECUTION DIRECTIVE CHANGED BY THE
USER: "I don't care if it is non-playable… I want everything ported, then we
test."** The per-phase playability constraint and per-phase user visual gates
are DROPPED. BR-2 through BR-6 execute as ONE continuous port (the fused
render discipline), with build + unit/conformance tests green at every commit
(engineering hygiene, not gates), and **ONE comprehensive visual test pass at
the end**. Rationale: the first BR-2 attempt failed precisely because the
phase slicing cut retail's frame order in half (the punch shipped without
entities-drawn-last and erased characters in apertures — reverted `88be519`);
the installment-must-be-a-complete-retail-behavior rule replaces the
playability rule. BR-7 (collision) runs as an independent track; BR-8b
(lighting) still wants the verification resume first.
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 surface gate — ✅ RESOLVED AS ALREADY-EQUIVALENT (2026-06-11, execution day 1)

**Premise falsified before implementation (the BR-1 pre-check,
`ReplicateProductionEmission_OnPortalFills`):** acdream **already suppresses
every portal fill** — all four extraction paths skip `Stippling.NoPos`
positive sides (`ObjectMeshManager.PrepareGfxObjMeshData:1046`,
`PrepareCellStructMeshData:1394`, `CellMesh.Build:44`, `GfxObjMesh.Build:71`),
and the Holtburg fills have no negative surface. The planned "draw-time
surface gate" has nothing to gate.

**What shipped instead — the equivalence pin**
(`StipplingSurfaceEquivalenceTests`): 2,607 polys across 13 building models +
13 environments, **zero violations both directions** — `NoPos ⇔ untextured
surface`. Our build-time skip is therefore *proven equivalent* to retail's
draw-time `skipNoTexture` rule on this content; the
`portal-poly-suppression-criterion` divergence closes as
equivalent-with-proof. The pin fails loudly if future content breaks the
invariant (the cue to implement the draw-time gate then).

**Consequences (the honest part):**
- The **#113 phantom residual is NOT GfxObj fills** — it cannot be, they
  never reach a vertex buffer. The "root cause #2" attribution from the
  e46d3d9 session is corrected; the e46d3d9 user-gate observations (filter
  removed phantom/doors) were confounded — the filter was a provable mesh
  no-op on both shells and door parts.
- The phantom's plausible true sites are cell-side: flood-admitted stair
  CELLS drawn with a pass-all slice when the assembler hands them no slot
  (`RetailPViewRenderer.cs:71` draws ALL visible cells; `NoClipSlice`
  default), and/or stair-cell STATICS drawn unclipped + un-viewcone'd by
  design (`object-lists-skip-portal-view-gate`, confirmed). **BR-2's first
  task is a 10-minute probe at the hall bisect spot pinning which** —
  the closure moves to BR-2/BR-3 (shells) and BR-5 (statics).
- **Closes:** the `portal-poly-suppression-criterion` divergence (as
  proven-equivalent); #113's closure moves to BR-2/BR-3/BR-5.
- **Shipped:** the pre-check + equivalence pin tests; no production code
  (none needed).

### 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.

- **First task (from BR-1's falsification):** the 10-minute probe at the
  hall bisect spot — when the phantom is visible, log per stair cell
  (0x100..0x106) whether it drew with a real clip slot or the pass-all
  `NoClipSlice`, and whether its statics drew — pinning the phantom's true
  draw site (shells → fixed here/BR-3; statics → BR-5).
- **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; the
  #113 phantom residual if the probe pins it on pass-all shell slices.
- **Acceptance:** cellar↔main-floor walk shows no grass sweep (user gate);
  phantom-spot check at the hall (user gate, replaces the old BR-1
  acceptance); 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) — ✅ CODE-COMPLETE 2026-06-11 (`6ec4cde`+`abf36e2`+`dbfbf85`+`ca4b482`; visual confirmation rides T5)

**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. Explicitly out of scope — tracked follow-ups (NOT covered by BR-1…BR-8)

Completing BR-1 through BR-8 lands the building/interior **drawing
discipline** and the collision rearchitecture. It does **not** cover the
items below. They are named here so the boundary of what the campaign
delivers is written down, not assumed — each becomes its own roadmap item or
issue, none blocks BR-1…BR-8.

- **FU-1 — Transparency / draw-sorting (→ BR-9 candidate).** Retail's
  `DrawSortCell` + AlphaList deferral (decompiled in
  `2026-06-11-holistic-map/wf1-gfxobj-draw.md`) governs water surfaces,
  translucent windows, and alpha-blend ordering. The area's *map never
  completed* (agent hit the token limit), so there are no divergences yet —
  scope it before promoting to BR-9. **Severity: medium; user-visible as
  wrong window/water compositing.**
- **FU-2 — Dungeon visibility scaling (#95).** The 8 phases are
  Holtburg-building-shaped. Dungeons share the EnvCell/portal discipline so
  they benefit *automatically*, and BR-4's tighter flood admission
  (no-distance-constant + screen-clip rejection + cell-loaded gate)
  **plausibly** shrinks #95's 135-cells/frame blowup — but #95 is a
  disconnected-landblock *seeding* problem that BR-4 is not guaranteed to
  fix. **Re-measure #95 after BR-4/BR-6 land; if still blown, it needs its
  own phase.** Do not assume the building port closes it.
- **FU-3 — Distance LOD / degrades (= BR-8c, optional).** Per-part degrade
  selection beyond humanoids; far models stay base-detail until picked up.
- **FU-4 — Picking refinements** (4 low-severity divergences,
  `wf2-picking-selection.md`). Defer; file as issues if/when the port
  changes what is clickable (e.g. building shells, baked fills).
- **FU-5 — The ~30 open questions** live in the comparison doc §6
  (`2026-06-11-building-render-acdream-vs-retail-comparison.md`). The
  load-bearing ones are referenced inline in the phases that consume them
  (e.g. `LScape::draw` clip behavior for BR-2/BR-3, the near-W constant,
  `DrawPortal` mode-3 seal-on-failure for unstreamed interiors); the rest
  are pinned during implementation, not before.
- **FU-6 — Verification top-up.** ~36/76 divergences remain UNVERIFIED (the
  overnight resume was stopped to preserve budget; both runs are resumable
  by ID — see comparison §7). Run a cheap resume before **BR-8b lighting**
  scoping (the one phase that leans on unverified rows) and before promoting
  FU-1 to BR-9.

## 5. Sequencing summary

```
BR-1 (surface gate)          — ✅ RESOLVED as already-equivalent (pin shipped,
                               no production code; #113 closure moved to
                               BR-2/3/5 — see BR-1 section)
BR-2 (depth punch/seal)      — FIRST implementation phase; opens with the
                               phantom-site probe; 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;
                               closes the phantom if it is statics-side
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.

## 6. 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.