acdream/docs/research/2026-06-01-render-reset-session2-handoff.md

Render Reset — Session 2 handoff (2026-06-01)

Net code change this session: ZERO. A stencil-occlusion approach was designed, implemented (T1–T4), regressed, and fully reverted to the session-start baseline 9bff2b0. The indoor render is still broken exactly as it was at session start. This handoff exists so the NEXT session does not repeat the mistakes that wasted this one. Read this together with the original analysis: docs/research/2026-05-31-render-architecture-reset-handoff.md.

1. Honest state

• Branch claude/thirsty-goldberg-51bb9b, HEAD = 9bff2b0 (baseline). UNPUSHED.
• Two git stashes preserved (stash@{0} #98/#101/A8-culling WIP, stash@{1} issue98 backup). Do NOT drop.
• The reverted stencil work is recoverable from the reflog (commits 1f9cb1b spec, 7adb3da plan, 9e988e7 T1–T3, 003dda4 T4). Do not resurrect it without a reason that comes from evidence.
• The indoor world is still broken: walls/floor don't seal, outdoor terrain visible from inside the cellar ("world from below"), enclosure reads grey/transparent. The doorway flap is still fixed (0ee328a, in baseline). Camera-collision commits (e099b4c, 3066460) are in baseline — parked, out of scope.

2. What was tried, and WHY it failed (the load-bearing part)

Approach tried: a "unified stencil-occlusion gate" — interior geometry writes stencil=1, exterior (terrain + outdoor stabs) draws only where stencil==0, dynamics ungated. The idea was: no cameraInsideBuilding path-toggle (so no flap), per-pixel mask (so no convex-clip leak), the interior floor masks the terrain below it (so no "world from below").

Why it failed — three distinct failures, in order of importance:

1. It was patchwork wearing a new hat. It was bolted onto the existing three separate renderers (terrain / cell-shells / entities) and sorted entities into different gates by flags (IsBuildingShell / ParentCellId / ServerGuid). That per-flag special-casing is the patchwork the reset was supposed to delete. Rule for next time: if the design routes geometry into different gates by entity flags, it is not "one gate" — stop.

2. The rule is wrong outdoors. "Interior writes a screen-space mask, exterior tests it" breaks the outdoor case: a building sits on terrain, but making it write the mask makes the terrain not draw in the building's silhouette → buildings punch holes in the ground, inside AND outside (the regression the user saw). Any unified gate must be correct indoors AND outdoors AND at the threshold — the outdoor case is not an afterthought.

3. It was driven by theory, not pixels. ~5 relaunches, zero screenshots, until the very end. Hypotheses were reasoned from code structure + the user's verbal reports, then code was changed and relaunched. That is the exact anti-pattern the memory render-one-gate warns about ("log-archaeology misled for days; one screenshot cracked it"). A screenshot at the cottage on attempt #1 would have shown the geometry reality immediately.

Meta-cause: the session treated "pick one and execute" as license to start typing rather than license to commit to an architecture, and it pivoted from the handoff's prescribed approach (consolidate the PView clip machinery) to a brand-new mechanism (stencil) under pressure — i.e. it thrashed mechanisms mid-stream instead of grounding a choice in evidence.

3. Evidence gathered that IS still useful (don't re-derive)

• Two redundant portal traversals run per frame (both player-rooted): CellVisibility.GetVisibleCells produces a binary VisibleCellIds set (consumed by WbDrawDispatcher.EntityPassesVisibleCellGate); PortalVisibilityBuilder.Build produces screen-space clip regions + OutsideView (consumed by ClipFrameAssembler → the clip slots). They can disagree. Interior statics are gated by the intersection; shells by only the second; outdoor stabs bypass the first (ParentCellId==null → EntityPassesVisibleCellGate returns true). This is the "3-gate patchwork" in detail.
• CONFIRMED — the cottage structure is IsBuildingShell GfxObj entities, NOT (only) EnvCell shells. src/AcDream.Core/World/LandblockLoader.cs:75-91: each info.Buildings entry becomes a WorldEntity { IsBuildingShell = true, ParentCellId == null }, rendered by WbDrawDispatcher. So the cottage walls/floor/roof are landblock-level building entities that also exist when you are outdoors (where they must not mask terrain). This is the single most important geometry fact for the next design. ⚠️ Still unconfirmed by pixels: whether the cottage also has EnvCell interior shells, and which renderer owns the walls vs. the floor vs. the stairs. The user's report ("correct on the stairs, broken in the rooms") strongly implies a mix — confirm it.
• Retail PView::DrawCells (acclient_2013_pseudo_c.txt:432709) installs the active "view" (clip region) before each draw; the landscape is drawn once, clipped to outside_view, and only when outside_view.view_count > 0 (empty → no landscape — the retail bleed fix). The outside-view is a list of convex view polygons clipped to the union, NOT a single convex set.
• WB's RenderInsideOut is a flat per-pixel STENCIL pass selected by an isInside toggle — acdream ported it byte-for-byte once (IndoorCellStencilPipeline, 792 LOC + portal_stencil shaders + tests) and deleted it in U.1 (3fc77be) precisely because the cameraInsideBuilding toggle caused the flap. The stencil mechanism is sound; the two-pipe toggle structure is what was bad. (Recoverable from 3fc77be^ if ever wanted.)
• Screenshot tooling WORKS and must be used: PowerShell Add-Type user32 GetWindowRect + System.Drawing Graphics.CopyFromScreen on the AcDream.App MainWindowHandle → PNG → Read the PNG. Proven this session (captured shot1.png of the live client at 1296×759). No excuse to theorize blind.

4. Open questions to answer with EVIDENCE (screenshots) BEFORE any design

1. In the cottage room, stairs, and cellar: what geometry actually draws, and what is the renderer for the walls / floor / ceiling / stairs (EnvCell shell vs IsBuildingShell GfxObj)? (Use ACDREAM_PROBE_SHELL [shell] + an entity-inventory probe, paired with a screenshot.)
2. Is cameraInsideCell + the visible-cell set stable standing still in the rooms/cellar, or does it flicker? (Add a one-line per-frame probe of visibility.CameraCell + VisibleCellIds.Count.)
3. Where exactly does terrain leak from in the cellar — below the floor (floor not occluding), through walls (walls not rendering / back-face culled), or terrain drawn ungated (root resolved outdoor)? A screenshot + the resolve probe answers this; do not guess.

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

RENDER PIPELINE — acdream indoor+outdoor. Continue on branch claude/thirsty-goldberg-51bb9b
(do NOT branch/worktree). Preserve the 2 git stashes — do not drop. Branch UNPUSHED — ask
before pushing. Baseline 9bff2b0. A stencil attempt was made and REVERTED last session (reflog
has it; do NOT resurrect without an evidence-based reason).

READ FIRST, in full: docs/research/2026-06-01-render-reset-session2-handoff.md, then the original
analysis docs/research/2026-05-31-render-architecture-reset-handoff.md, then the "Render Pipeline
(SSOT)" section of docs/architecture/acdream-architecture.md, then memory feedbacks
render-one-gate + render-self-contained-gl-state.

GOAL (what we intend): a pipeline where moving outside<->inside is SEAMLESS and looks like
reality — interiors seal (walls/floor/ceiling), you see outside ONLY through real openings
(doors/windows), and OUTDOORS the world renders normally with buildings sitting ON the ground
(never punching holes in terrain). Acceptance test: Holtburg cottage — walk in, stand in the
room, go to the cellar, come back out: no flap, no terrain through floors/walls, no grey void,
no holes in the ground. M1.5 "indoor world feels right."

THIS IS AN ARCHITECTURE TASK, NOT A PATCH JOB. The pipeline is 3 separate renderers (terrain /
cell-shells / entities) each deciding visibility inconsistently. Goal: ONE visibility decision
all geometry obeys the same way. If a fix routes geometry into different gates by flags
(IsBuildingShell / ParentCellId / ServerGuid), that's the patchwork reappearing — stop.

HARD GATE — EVIDENCE BEFORE CODE (this is where last session failed):
- For ANY render/visual question, LOOK AT PIXELS first. Window capture works (PowerShell
  System.Drawing CopyFromScreen on the AcDream.App MainWindowHandle -> PNG -> Read it). No
  theorizing from code alone.
- BEFORE designing: capture+read screenshots of every broken state (cottage room, stairs,
  cellar, outside) and answer §4's three questions with EVIDENCE, not theory.
- AFTER every change: screenshot the cellar and compare yourself. Do NOT "relaunch and ask the
  user" as the loop — the user's eyes are the FINAL gate, not the debugger.

PROCESS (in order): (1) INVESTIGATE report-only (use the /investigate skill) — screenshots +
[shell]/[flap]/cell-resolution probes -> a written evidence model of WHAT is broken and WHY;
get the user's nod before any code. (2) DESIGN (superpowers:brainstorming, grounded in #1) —
one visibility decision, one enforcement, correct indoors AND outdoors AND at the threshold
(the seamless transition IS the hard problem). Pick ONE mechanism and COMMIT; candidates are
the retail-PView clip machinery we already own (PortalVisibilityBuilder + ClipFrame) vs a
stencil mask vs another approach — let evidence choose, then don't thrash. Honestly assess
whether the existing machinery is salvageable into the one gate or a deeper restructure is
warranted; don't ASSUME "consolidation." (3) IMPLEMENT the one gate, delete the ad-hoc gates,
small sequential commits, build green each. (4) VERIFY at the cottage cellar with screenshots,
then the user's final sign-off.

DO NOT REPEAT (evidence-disproven): camera/eye as root, cull mode, shell geometry/texture
missing, H1 PVS grounding, H2 PortalSide, zoom-confound, AND the session-2 failures: a
screen-space "interior writes mask" rule that breaks outdoors (buildings hole the ground);
flag-based per-entity gate routing (= patchwork); jumping to code before understanding the
failure from pixels. Only stop for visual verification once you have a build + screenshots.

6. Confirmed facts ledger (one-liners)

• Cottage walls/floor/roof = IsBuildingShell GfxObj entities, ParentCellId==null (LandblockLoader.cs:75-91).
• Two redundant traversals: CellVisibility.GetVisibleCells (VisibleCellIds) + PortalVisibilityBuilder.Build (screen regions).
• Retail draws the landscape once, clipped to outside_view, only if view_count>0 (DrawCells :432709).
• Stencil mechanism is fine; the cameraInsideBuilding two-pipe toggle is what caused the flap (deleted U.1 3fc77be).
• Window screenshot via PowerShell CopyFromScreen works — use it.