acdream/docs/research/2026-05-31-render-architecture-reset-handoff.md

Render Architecture Reset — assessment + handoff (2026-05-31)

Read this first, in full, before touching any render code. This is a deliberate reset after a week of point-fixing the indoor render with no shippable progress. The next session's job is NOT another symptom fix — it is to bring acdream's render pipeline up to a single, coherent, retail-faithful design (PView) and close the indoor seams by construction.

1. The honest state

A full week (Phase U.4 → U.4c → this session) has gone into the indoor render. Net result: the doorway "flap" is fixed (real, kept), but the indoor world is still broken — walls/ceiling don't visually seal, you see outdoor terrain from inside the cellar ("the world from below"), and the enclosure reads as a grey/transparent void.

The reason there's been no progress is architectural, not a bug: the render pipeline is a patchwork of three inconsistent visibility gates bolted onto a half-finished port of retail's PView. Seams are structural — fixing one place (the flap, the camera, the shells) pops a seam in another. We have been chasing symptoms across different subsystems (visibility → camera collision → shell rendering) instead of fixing the architecture. That stops now.

Mandate from the user (2026-05-31): "produce me a solid engine that produces a retail-faithful experience… look over what we have done, check our design and if it matches a solid engine design, and solve all our issues." This handoff is the assessment; the next session executes the reset.

2. Evidence ledger — what is RULED OUT and CONFIRMED (do not re-litigate)

This week was not all waste: it eliminated, with direct evidence, every subsystem except the gating architecture. Do not re-investigate these.

CONFIRMED (direct evidence):

• The interior cell shells RENDER correctly. [shell] probe (ACDREAM_PROBE_SHELL): every visible cell (0xA9B40170-0175) is prepared and drawn — gfx=1, idx 24–270, tr=0 (not translucent), zh=0 (textures present), opaque pass, depth-on. So the shells are NOT the problem (geometry, textures, cull, depth all fine).
• The visibility traversal computes correct results. [flap] probe: portals traverse (TRV), project, and clip to non-empty screen regions (clip=4/5), vis=3 cells, terrain=Skip/outPolys=0 correct for a windowless cellar.
• The residual is OUTDOOR geometry not being gated to portal openings when indoors (issue #78): screenshots show outdoor terrain + scenery rendered and visible from inside the cellar (from below), and the interior not sealing. The cell mesh renders but does not occlude / the outside is not clipped to the window.

RULED OUT (with evidence) — do NOT chase again:

• The camera / eye position as the root (eye-displacement was reduced by e099b4c but the residuals persisted unchanged — the camera thread was a detour).
• Cull mode (cell shells already render double-sided, EnvCellRenderer.cs:1168).
• Cell-shell geometry missing / textures missing ([shell] proves both present).
• The portal side-test / PortalSide (b5f2bf2, byte-identical no-op).
• PVS / stab_list grounding (H1, 639f20f plumbed, not the fix).
• Camera zoom as the cause (errors persist at minimum zoom).

3. The current render architecture (mapped) — the patchwork

Per-frame, inside GameWindow.OnRender (~:7290-7471):

CellVisibility.ComputeVisibility(visRootPos = PLAYER pos)   → visible-cell SET + VisibleCellIds + CameraCell
        │
PortalVisibilityBuilder.Build(clipRoot, visRootPos=PLAYER, envCellViewProj=EYE)   ← a partial port of retail ConstructView
        │   → PortalVisibilityFrame { OutsideView, per-cell CellViews, OrderedVisibleCells }
        │   (side-test + ordering use the PLAYER; projection uses the EYE — a split)
        │
ClipFrameAssembler.Assemble(...)   → TerrainClipMode {Skip|Scissor|Planes} + CellIdToSlot (per-cell clip regions) + OutdoorVisible
        │
        ├── TerrainModernRenderer.Draw       gated by TerrainClipMode  (GATE #1)
        ├── EnvCellRenderer.Render(shells)   gated by envCellShellFilter + per-cell clip slot  (GATE #2)
        └── WbDrawDispatcher.Draw(entities)  gated by ParentCellId ∈ visibleCellIds … BUT outdoor stabs have ParentCellId==null and ALWAYS PASS  (GATE #3)

Why this is structurally fragile (the root of all the seams):

1. Three separate gates (terrain / shells / entities) must independently agree to produce a seamless interior. They don't. Retail has one gate (PView).
2. Outdoor geometry is not gated to portal openings. Terrain has its own Skip/Scissor/Planes path (and the Scissor fallback over-includes), and outdoor stabs/scenery (ParentCellId==null) bypass the gate entirely → you see the outdoor world from inside (#78). Retail draws the landscape only through exit portals, clipped to the opening.
3. No single source of truth. "What is visible and where on screen" is reassembled from three consumers of one builder, instead of being the builder's authoritative, uniformly-enforced output.
4. Player-rooted set vs eye-projected clip split adds a second axis of fragility (the flap, the residual degeneracies) — secondary, but real.

This is the crux: we compute visibility once but enforce it three different, inconsistent ways.

4. The retail-faithful target — PView: one traversal, one gate

Retail (decomp docs/research/named-retail/acclient_2013_pseudo_c.txt) renders the world through PView, a single portal-clipped traversal:

• Root at the viewer's cell (CellManager::ChangePosition tracks curr_cell).
• PView::ConstructView (:433750) walks the portal graph; InitCell (:432896) computes each cell's screen-space clip region (the portal opening it's seen through, recursively intersected with the parent's region); cells go on cell_draw_list closest-first.
• Exit portals add the outside (landscape) to the view, clipped to the exit-portal opening.
• PView::DrawCells (:432715) renders each cell clipped to its region, and the landscape only where an exit portal reveals it.
• The viewer (eye) is collided (SmartBox::update_viewer :92761) so the projection stays well-conditioned.
• CEnvCell::find_visible_child_cell (:311397) + seen_outside gate the landscape-keep.
• Outdoors, PView is trivial (the LandCell + neighbours, no indoor clipping).

The defining property: ONE visibility structure gates ALL geometry — interior cell shells, interior statics, and the outside (terrain + scenery) — all clipped to their PView-derived regions. That is why retail is seamless by construction.

Reference port to crib (acdream owns it but never invokes it): WorldBuilder's RenderInsideOut / VisibilityManager (references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs).

5. The solid design for acdream (the reset target)

We already have the hard part (the PortalVisibilityBuilder ConstructView port + the ClipFrame clip-plane machinery + per-cell clip slots). The reset is a consolidation, not a rewrite: make the PView output the single gate for every geometry type.

1. One gate. Every draw — cell shells, interior statics, terrain, outdoor scenery — is clipped to its PView region:
   • Interior cell C → its per-cell clip region (already ≈done in EnvCellRenderer).
   • Interior static in cell C → cell C's region (route via the same per-instance clip slot).
   • Outside (terrain + outdoor scenery + ParentCellId==null stabs) → the OutsideView region (union of exit-portal openings). Empty OutsideView (windowless interior) ⇒ draw NO outdoor geometry. No ParentCellId==null bypass.
   • Outdoor root (camera/player in a LandCell, no indoor cell) ⇒ gate = everything (today's normal path).
2. Delete the ad-hoc gates. Collapse GATE #1/#2/#3 into the single clip-to-region. Remove the ParentCellId==null always-pass in WbDrawDispatcher. Remove the terrain Scissor over-include fallback in favour of retail's exact portal clip.
3. Resolve the set/clip split. Decide one rooting story (the flap fix proved the set must be player-rooted; the clip/projection is the eye's — confirm this is retail-faithful under the unified gate, or collide the eye so they coincide).
4. U.5 (eye outside, looking into a building) is the same machinery with the root at the eye's cell and the interior shown through the building's portals — design it in, don't special-case it.

Result, by construction: #78 (outdoor gated to openings), transparent walls (interior uniformly clipped), grey enclosure (no spurious ungated gaps), terrain-through-floor (no outdoor outside the window) all resolve together — because there is one consistent rule instead of three.

6. Next-session mission (the reset — in order)

1. Audit the current render data-flow against §3; confirm the three-gate divergence in the live code.
2. Verify the target against retail: read PView in full (ConstructView/InitCell/ClipPortals/AddViewToPortals/DrawCells/ grab_visible_cells/find_visible_child_cell) and WB RenderInsideOut. Do not trust this doc's summary alone — confirm the one-gate model from the source.
3. Design the unified gate (superpowers:brainstorming → spec). This is architectural; brainstorm it, don't free-solo.
4. Implement the single gate; delete the ad-hoc gates/bypasses.
5. Verify at the visual gate: flap stays fixed; walls/ceiling solid; no terrain-through-floor; no grey; outdoor visible only through windows/doors, clipped.

Operating rules for the reset: evidence-first; no point-fixes; no new gate bolted on to mask a seam (that is exactly what produced this mess). If a fix starts to look like a fourth special-case gate, stop — it belongs in the one gate.

7. What the week produced (status of each artifact)

• KEEP — 0ee328a flap fix: root indoor visibility at the player's cell. A correct, retail-faithful PView piece (the set must be player-rooted). Keep.
• ORTHOGONAL — e099b4c camera-collision viewer-gate-exemption: retail-faithful but not the seam fix (the camera thread was a detour). Open decision: keep (it's a real, faithful improvement) or revert to keep the reset branch focused. Recommendation: park it — keep the commit but treat camera collision as out-of-scope for the reset; revisit only after the unified gate lands. Its sibling diagnosis (3066460) + spec (docs/superpowers/specs/2026-05-31-camera-collision-indoor-engagement-design.md)
  • the CameraCollisionIndoorTests are accurate for what they cover but are about an orthogonal subsystem.
• APPARATUS (throwaway, gated, useful for the reset):
  • ACDREAM_PROBE_FLAP → [flap]/[flap-cam]/[flap-sweep] (visibility + eye + camera sweep).
  • ACDREAM_PROBE_SHELL → [shell] (per-cell shell render: prepared? geometry? flags?). Strip both once the reset lands.
• Disproven hypotheses (do NOT repeat): H1 (PVS grounding), H2 (PortalSide), zoom-confound, back-face-cull, eye-displacement-as-root, shell-geometry/texture-missing.

8. Git / safety

• Branch claude/thirsty-goldberg-51bb9b, UNPUSHED (push pending with the user).
• Two git stash entries preserved (#98/#101 WIP) — do NOT drop.
• Throwaway capture logs u4c-*.log are untracked — ignore/delete, do not commit.

9. Pickup prompt (copy-paste for the next session)

RENDER ARCHITECTURE RESET — acdream indoor pipeline. Continue on branch
claude/thirsty-goldberg-51bb9b (do NOT branch/worktree; preserve the 2 git stashes).

READ FIRST, in full: docs/research/2026-05-31-render-architecture-reset-handoff.md, then
the "Render Pipeline" section of docs/architecture/acdream-architecture.md.

State both altitudes: Working toward M1.5 "indoor world feels right." After a week of
point-fixing with no shippable progress, this is an ARCHITECTURE RESET, not a symptom fix.

THE PROBLEM (root cause, evidence in the handoff): acdream's render pipeline is a
patchwork of THREE inconsistent visibility gates (terrain TerrainClipMode / shell
per-cell clip / entity ParentCellId filter with an outdoor-stab bypass) bolted onto a
half-finished PView port. Seams are structural. The interior cell shells RENDER FINE
(proven); the residual is that OUTDOOR geometry isn't gated to portal openings when
indoors (#78) and the three gates don't agree.

THE TARGET (retail PView, §4-5 of the handoff): ONE portal-visibility traversal whose
output is the SINGLE GATE for ALL geometry — interior shells, interior statics, AND the
outside (terrain + scenery) all clipped to their PView regions; outside drawn ONLY
through exit-portal openings; empty OutsideView ⇒ no outdoor; no ParentCellId==null
bypass; outdoor root ⇒ gate=everything. We already own the builder (PortalVisibilityBuilder
= ConstructView port) + ClipFrame; this is CONSOLIDATION, not a rewrite.

MISSION (in order): (1) audit the current 3-gate data-flow in GameWindow.OnRender
~:7290-7471; (2) VERIFY the one-gate model against retail PView (ConstructView :433750,
InitCell :432896, DrawCells :432715, find_visible_child_cell :311397) + WB RenderInsideOut
(references/WorldBuilder/.../VisibilityManager.cs) — confirm from source, not the handoff
summary; (3) brainstorm + spec the unified gate (superpowers:brainstorming); (4) implement
the single gate, delete the ad-hoc gates/bypasses; (5) visual-verify ALL indoor issues
resolve together.

DO NOT REPEAT (evidence-disproven, handoff §2): camera/eye as root, cull mode, shell
geometry/texture missing, H1 PVS grounding, H2 PortalSide, zoom-confound. DO NOT bolt on
a fourth gate to mask a seam. Evidence-first; no point-fixes; brainstorm the architecture
before coding; only stop for visual verification.

Apparatus ready: ACDREAM_PROBE_FLAP ([flap]/[flap-cam]/[flap-sweep]) + ACDREAM_PROBE_SHELL
([shell]). Open decision: keep or revert e099b4c (camera collision, orthogonal — parked).
Launch per CLAUDE.md "Running the client"; Holtburg cottage cellar/stairs is the test
scenario; visual verification at that threshold is the acceptance gate.