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 (evidence appendices in docs/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. 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)          — 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.

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.