acdream/docs/research/2026-06-11-building-render-holistic-port-handoff.md

HANDOFF — Holistic building/interior render port (the end of whack-a-mole)

Date: 2026-06-11. Branch: claude/thirsty-goldberg-51bb9b (worktree), HEAD 124c6cb. Nothing is on main. All session work is branch-only, per the user's explicit instruction.

0. The mandate (user, 2026-06-11, verbatim intent)

"We can't go on like this. We need to solve this holistic once and for all. Not cottage by cottage or bug by bug. Check our code vs how retail draws buildings, interior, collision interior, dynamic objects, clipping and culling. I want one solution that works every time I walk to a new landblock and walk into a dungeon. […] map acdream's way vs retail, then make a plan how to port retail's way of doing it once and for all. We have come a long way and our code is worth saving."

This supersedes the per-issue grind (#105→#113 and the §4 residual family). The next session is an investigation + plan session: NO production code until the plan is approved. The deliverables are (1) an acdream-vs-retail architecture comparison document and (2) a phased port plan. Code is worth saving: this is a port-the-missing-architecture plan, not a rewrite.

1. Branch state (what's in, what's off, how to verify)

Commit	What	State
927fd8f	#113 fix 1: GL clip distances enabled for the PView shell pass	IN (scoped by 9ce335e)
414c3de	#112 rider: retail straddle gate for outdoor-cell admission (membership pick)	IN — solid, live-binary verified, conformance-pinned
8259598	docs: ISSUES updates	IN
9ce335e	#114 scope: shell clip outdoor-eye roots only (indoor regions not draw-quality)	IN
6c9bbce	docs: #114 + #115 filed	IN
e46d3d9	#113 fix 2: DrawingBSP poly filter in GfxObj mesh extraction	UN-APPLIED by 124c6cb (door regression); helper + tests remain
124c6cb	revert of the filter application; keeps CollectDrawingBspPolygonIds + dat pins	IN

Visible state when launched: doors work; the phantom staircase on the Holtburg meeting hall is VISIBLE again (known, documented — it is the un-filtered no-draw geometry, see §2.3); indoor rendering is the pre-#113 state (unclipped); outdoor interior-cell rendering is clipped to door apertures (the only part of the clip work that was validated).

Test baseline: Core 1392 green + 4 pre-existing #99-era failures (DoorBugTrajectoryReplay ×2, DoorCollisionApparatus, BSPStepUp) + 1 skip; App 226; UI 420; Net 294. Gates: P1 membership goldens, CornerFloodReplayTests, Issue107SpawnDiagnosticTests, Issue112MembershipTests (one renamed: ...DemotesRetailFaithfully; two new straddle-gate pins), Issue113 dump + filter pins.

2. What this session PROVED (evidence inventory — all reusable)

2.1 The retail draw-side portal clip exists and we half-have it

• Retail clips drawn cell geometry to the accumulated portal view: Render::set_view (pc:343750) installs the view polygon's edge planes; DrawEnvCell submits every cell polygon with planeMask=0xffffffff (pc:427922) through ACRender::polyClipFinish. Characters/meshes are NOT poly-clipped (viewcone-check path, Render::viewconeCheck + BoundingType handling in DrawMeshInternal).
• Our equivalent (UseShellClipRouting → mesh_modern.vert gl_ClipDistance, region SSBO binding=2 + per-instance slot binding=3) was routed but inert since birth (1405dd8) — GL_CLIP_DISTANCEi was never enabled for the shell pass. 927fd8f enabled it; the outdoor case is validated (Issue113MeetingHallFloodTests: per-cell regions are tight 4–6-plane door-aperture boxes across a 21-step eye sweep, 0 unclipped fallbacks).
• Indoor clip regions are admission-quality, NOT draw-quality (#114): enabling the clip indoors chopped real geometry (hall interior stairs, candle-holder area, walls vanishing at exits; user screenshots in the session transcript 2026-06-11). Suspects: knife-edge regions when the eye nears a portal plane; MergeBuildingFrame first-view-wins dropping additional apertures for multi-portal cells; the >8-plane slot-0 fallback drawing pass-all (the assembler's scissor fallback contract was never implemented — ClipFrameAssembler.cs:13-15).

2.2 The membership outdoor-admission gate is now retail-exact

414c3de (KEEP THIS — it is correct and orthogonal to the render mess): CEnvCell::find_transit_cells (live binary 0052c820, x87 decoded at 0052c8e5-0052c92d; Ghidra decompile confirms char-for-char) admits outdoor cells IFF a path sphere STRADDLES an exterior portal plane (|dist| < radius + F_EPSILON(0.0002)). The membership PICK now gates on it; the collision cell SET keeps the A6.P5 topology widening until A6.P4. Conformance-pinned on real dat geometry.

2.3 The REAL phantom staircase: no-draw (drawing-BSP-orphaned) polygons

Dat-proven (Issue113PhantomStairsDumpTests.DumpHallModel_PolyFlagHistogram):

• Retail renders a GfxObj by traversing its DrawingBSP; polygons present in the Polygons dictionary but referenced by no DrawingBSP node are never drawn.
• Holtburg meeting hall 0x010014C3: dictionary polys {0,1} are a ~5×11 m stair-ramp spanning local z 0→8.5 — in the PhysicsBSP (ACE walks The Sentry on it at z 117–118; invisible-but-walkable in retail) but orphaned from the draw tree — at every degrade level (LOD theory dead: Degrades[0] IS the base model).
• Hill cottage 0x01000827: orphans {0..7}.
• Our ObjectMeshManager.PrepareGfxObjMeshData iterates the dictionary → draws the collision skeleton: the wall staircase up close, the "flying stairs" over the cottage roofline from afar (orphan ramp spans world (221–232, −104..−109, z 116–124.5)).
• The naive filter broke doors (e46d3d9 → un-applied 124c6cb): filtering the dictionary to the PosNode/NegNode-walked id set made doors vanish across Holtburg. OPEN MYSTERY #1 (first diagnostic of the new session): run the histogram fact on a door GfxObj — either DatReaderWriter's DrawingBSPNode exposes polys some other way for those trees (portal-type nodes? Portals list? leaf indexing?), or the parse is incomplete, or doors' visible polys genuinely live outside node.Polygons. The correct retail shape is BSP-traversal-order drawing, not dictionary-with-filter — the filter was a minimal approximation.

2.4 Earlier session facts that still stand

• A9B3 has ONE building (the hill cottage); the #112 gap is a real 20 cm doorway micro-gap; all 17 cottage cells share one identical Position — "misplaced interior cell" is refuted. The phantom-stairs building is the AAB3 meeting hall.
• Door alignment between independently-placed interior cells and the rotated shell is exact (rotation conventions are right); the inn's server-placed door aligning with our shell is the world-anchored confirmation.
• ACE patrol z-values are DB-authored, not physics-grounded — weak as a geometry oracle.
• [resolve] lines in our logs show our client grounding the elevated Sentry at terrain z=116 vs the server's 117.2 — remote-entity grounding vs invisible-walkable geometry (#41-family data point).

3. The architecture gap map (what the investigation must complete)

What we believe we know, per area — every row needs decomp-verified confirmation and a "theirs vs ours" write-up. 🟢 = we have a verified port, 🟡 = partial/approximation, 🔴 = missing/unmapped.

Area	Retail mechanism (anchors)	acdream today	Status
Object draw (GfxObj)	DrawingBSP traversal (D3DPolyRender::ConstructMesh 0x0059dfa0 noted in code; CPhysicsPart::Draw); per-poly planeMask clip; degrade table per part (GfxObjDegradeResolver doc)	Flattened dictionary mesh into global VAO + MDI; degrades only for humanoid setups (#47); no-draw orphans rendered	🔴 core divergence
Building shells	CBuildingObj with leaf_cells (CPartCell) + portals; drawn via LScape → DrawSortCell → DrawBuilding; shell parts drawn per portal-view slot with set_view clip + viewconeCheck (pc:429282-429295)	One WorldEntity per BuildInfo, whole-model mesh, frustum cull only	🔴
Interior cells (render)	PView::DrawInside flood (ConstructView/ClipPortals/InitCell, pc:432896-433895) + per-cell portal_view slices + per-poly clip to the view	Flood ported (R-A1/A2/A2b + dac8f6a, conformance-gated); draw-side clip outdoor-only; indoor regions not draw-quality (#114)	🟡
Statics in cells	Drawn with their cell, per portal-view slot, viewcone-checked (CEnvCell::draw → object lists)	Per-cell buckets via flood (DrawCellObjectLists), unclipped, separate particle gating (particles not flood-gated the same way → flames through walls)	🟡
Dynamic objects (doors, NPCs, items)	CPhysicsObj part arrays; portal-view visibility checks; never hard poly-clipped	WbDrawDispatcher MDI, frustum + visibleCellIds routing	🟡 (audit needed)
Culling	viewer-cell rooted; portal-clipped BFS is THE cull indoors; outdoor = LScape draw + building portal floods; viewconeCheck per mesh	Option A DrawInside is in; outdoor per-building floods (48 m seed); cell-particle scissor partial	🟡
Interior collision	Per-cell shadow_object_list, portal-aware registration (add_shadows_to_cells)	Landblock-wide ShadowObjectRegistry + b3ce505 gate (workaround) → #99	🔴 (= A6.P4, already designed)
Degrade/LOD selection	Per-part current GfxObj chosen from degrade table by distance/quality	Base model everywhere except humanoid setups	🔴
Cell-struct no-draw polys	Same drawing-BSP rule presumably applies to CellStruct (cells have their own DrawingBSP)	Dictionary iteration (site 2, ObjectMeshManager ~:1343)	🔴 unverified

The unifying theme: retail has ONE drawing discipline — BSP/portal-driven traversal decides what is drawn, and the portal view clips what survives — applied uniformly to terrain peeks, shells, cells, statics, and meshes. We replaced traversal with flattened-mesh iteration + a separately-bolted visibility filter, and every bug in the #105→#113 family is a place where the two disagree.

4. Open mysteries (carry into the investigation)

1. Door vanish under the BSP filter (§2.3) — first diagnostic, 15 min with the existing dump harness. Identify a door GfxObj id via ACE weenie data or by clicking a door and reading [B.7] pick-info ... setup= from the log.
2. Indoor clip-region draw-quality (#114) — knife-edge/multi-view/8-plane-fallback.
3. Entry transparency at the hilltop cottage (user: still intermittent) — may be render (flood at entry) or membership at the threshold; needs a probe capture.
4. Particles visible through walls — particle pass is not gated/clipped like meshes.
5. Camera drag/jitter in cramped interiors (#115) — retail boom smoothing (SmartBox::update_viewer region) unread.

5. Tooling inventory (everything the investigation needs is live)

• Ghidra MCP, port 8081, CORRECT program (patchmem 2013 v11.4186 + full PDB — verified: find_transit_cells @ 0052c820 matches). Endpoints: /decompile_function?address=0x..., /searchFunctions?query=..., /function_xrefs?name=..., /list_functions. This is the best decomp source — Ghidra renders x87 correctly where BN pseudo-C invents branches (proven twice).
• Named pseudo-C: docs/research/named-retail/acclient_2013_pseudo_c.txt + acclient.h (verbatim structs) + symbols.json.
• Live cdb attach (read-only disassembly protocol proven this session; static cdb -z uf mis-decodes at OMAP boundaries — use live attach): see CLAUDE.md "Retail debugger toolchain"; the user will launch the 2013 client on request.
• Dat dump harness: tests/AcDream.Core.Tests/Conformance/Issue113PhantomStairsDumpTests.cs — buildings, cells, statics, portal planes, poly-flag histograms, DrawingBSP orphan diff, degrade chains, top-down ASCII maps. Extend freely.
• Flood replay harnesses: CornerFloodReplayTests (indoor), Issue113MeetingHallFloodTests (outdoor per-building flood + assembler).
• Key decomp anchors already mined: PView::InitCell :432896 / ClipPortals :433572 / AddViewToPortals :433446 / ConstructView :433750+:433827 / DrawInside :433793 / DrawPortal :433895; Render::set_view :343750; DrawEnvCell poly submit :427922; DrawBuilding :429282; CEnvCell::find_transit_cells 0052c820; CBuildingObj/CBldPortal/CCellPortal/portal_view_type structs in acclient.h :31908/:32094/:32300/:32346.

6. Investigation charter (for the new session)

Phase A — Map (workflows, parallel subagents). One mapping agent per area in §3's table, each producing "RETAIL: call-chain + data structures + exact gates (verbatim decomp lines)" vs "ACDREAM: call-chain + data structures (file:line)" vs "DIVERGENCES: ranked by user-visible blast radius". Adversarially verify each claimed divergence (the BN-invents-branches lesson; the A6.P5 caller/callee conflation lesson). Areas:

1. GfxObj draw path (BSP traversal, no-draw, degrades, planeMask clip)
2. Building shells (CBuildingObj, leaf_cells, per-portal-view drawing)
3. Interior cells (PView slices → draw-side clip; what makes regions pixel-exact)
4. Statics + dynamics in cells (object lists, viewconeCheck, particles)
5. Culling end-to-end (LScape outdoor walk → building floods → indoor BFS)
6. Interior collision (per-cell shadow lists — fold in the existing A6.P4 design)

Phase B — Plan. One phased port plan with: an invariant ("one drawing discipline"), per-phase acceptance criteria (conformance tests + which user-visible bugs each phase closes: phantom geometry class, #114, #108, #109, doors, #99, particles-through-walls), explicit keep-list (the flood port, the straddle gate, membership, streaming, bindless MDI — the code worth saving), and a migration order that keeps the client playable between phases. The plan goes to the user for approval BEFORE any production code.

Ground rules: investigation-first (no production edits); every retail claim needs a decomp citation or live-binary proof; every acdream claim needs file:line; tests can codify bugs — verify what call sites actually pass.

7. Paste-ready prompt for the new session

Pick up acdream as a SENIOR 3D ENGINE DEVELOPER for the HOLISTIC BUILDING-RENDER
INVESTIGATION (mandated by the user 2026-06-11: "solve this holistic once and for
all... map acdream's way vs retail, then make a plan how to port retail's way" —
no more cottage-by-cottage fixes). Worktree branch claude/thirsty-goldberg-51bb9b,
HEAD 124c6cb. NOTHING goes to main; no production code this session — the
deliverables are (1) an acdream-vs-retail architecture comparison and (2) a phased
port plan for user approval.

READ FIRST (in order):
1. docs/research/2026-06-11-building-render-holistic-port-handoff.md  ← THE charter:
   branch state, the full evidence inventory (orphan no-draw polys, the door-vanish
   mystery, draw-side clip status, straddle gate), the gap map (§3), the open
   mysteries (§4), tooling (§5), and the investigation phases (§6).
2. Memory digests: project_render_pipeline_digest + project_physics_collision_digest
   (DO-NOT-RETRY tables apply).
3. docs/architecture/worldbuilder-inventory.md + docs/ISSUES.md (#113/#114/#115/#99).

DO:
- Phase A: ultracode Workflow fan-out — one mapping agent per area (GfxObj draw,
  building shells, interior cells, statics/dynamics, culling, interior collision),
  each delivering RETAIL (verbatim decomp, Ghidra MCP port 8081 is live with the
  correct PDB; live cdb attach available on request — static cdb -z misdecodes)
  vs ACDREAM (file:line) vs RANKED DIVERGENCES; adversarially verify divergences
  (BN pseudo-C invents branches — proven twice; prefer Ghidra/live-binary).
- First 15-min diagnostic: why the DrawingBSP filter (e46d3d9, un-applied in
  124c6cb) made DOORS vanish — run Issue113PhantomStairsDumpTests' histogram on a
  door GfxObj (get the id from ACE weenie data or a [B.7] pick line).
- Phase B: write the phased port plan (one drawing discipline: BSP/portal-driven
  traversal + portal-view clip), per-phase acceptance criteria naming which bugs
  close (phantom-geometry class, #114 indoor crop, #108, #109, doors, #99,
  particles-through-walls), an explicit keep-list (flood port, straddle gate,
  membership, streaming, bindless MDI), and a migration order that keeps the
  client playable. STOP for user approval before any implementation.

Baseline: Core 1392 + 4 pre-existing #99-era failures + 1 skip / App 226 / UI 420 /
Net 294. The branch state is honest: doors work, the phantom staircase is visible
again (documented), outdoor shell clip on, indoor clip off (#114).

8. Session artifacts (untracked, worktree root)

issue113-user-screenshot-{1,2}.png (the original gate pair, extracted from the transcript), issue113-fix-screenshot{1,2}.png (post-clip pre-gate), issue113-bisect-*.png/log (pre-session build bisect), issue112-ftc-live-disasm.log (the live-binary disassembly of find_transit_cells — keep, it is the straddle-gate proof), issue113-user-gate{,2,3}.log (the three gate launches).