acdream/docs/research/2026-05-28-a8-cellar-flap-option2-handoff.md

A8 cellar-flap — option-2 handoff + brainstorming kickoff (2026-05-28 PM)

Purpose

The cellar flap is the last A8 indoor-rendering defect. Its root cause is fully understood (offline-confirmed). The targeted fix (option 1) was tried, failed, and the failure revealed a deeper architectural coupling. The decision is to fix it the retail-faithful way (option 2: WB-style recursive portal visibility) via a fresh superpowers:brainstorming session. This doc is the single pickup point for that session.

Current tree state (do NOT reset)

• Worktree: .claude/worktrees/strange-albattani-3fc83c/, branch claude/strange-albattani-3fc83c, tip e415bb3 — all A8 work is uncommitted in a dirty tree.
• Build green. App tests pass (90 baseline; the 3 option-1 tests were removed).
• The option-1 code (PortalMeshBuilder.CollectSameLevelPortalCells + IsVerticalPortal + 3 tests + the GameWindow call-site change) has been reverted/removed — tree is back to the working-with-cellar-flap baseline.
• tools/A8CellAudit gained a portals mode this session (offline cell/portal dumper) — kept, it's the investigation workhorse.

What WORKS in the dirty tree (the valuable A8 batch — keep)

• EnvCellRenderer SSBO stride fix (mat4 upload, not 80-byte InstanceData).
• WB-style global FrontFace(CW) + per-batch CullMode through MDI.
• EntitySet partitioning (IndoorPass / OutdoorScenery / LiveDynamic) + BuildingShellAnchorCellId scoping.
• RenderOutsideInAcdream (look into buildings from outside).
• CollectVisiblePortalBuildings frustum cull of portal bounds.
• Streaming near/far priority queues + PromoteToNear + the LandblockEntriesWithoutAnimatedIndex hot-path fix (fixed bridge/wall/collision regressions after travel).
• Temporary ACDREAM_A8_DIAG_* flags (strip before any commit).

What DOESN'T work

• Cellar flap + the broader inside-out fragility (see the coupling below).

Decision point for the human: the working A8 batch is large and uncommitted. Consider committing it (after stripping the ACDREAM_A8_DIAG_* flags) so the option-2 work starts from a clean baseline. Deferred per "don't commit yet," but flagged.

The cellar flap — root cause (confirmed)

Full evidence: docs/research/2026-05-28-a8-cellar-flap-root-cause.md.

Short version: the inside-out stencil mask flat-marks the exit portals (windows/doors) of every visibility-BFS-reached cell. From the cellar (0xA9B40171, zero exit portals), the BFS reaches the ground-floor cells (0x16F, 0x170) up the stairwell and marks their windows. Step 4 then paints the whole outdoor world through those silhouettes wherever the cellar's stairwell hole leaves them un-occluded. There is no constraint tying a deeper cell's exit portal to the portal chain (the narrow stairwell) it was reached through.

⭐ THE KEY FINDING — didInsideStencil double-duty coupling

This is the expensive lesson; do not re-pay it.

RenderInsideOutAcdream Step 4 (GameWindow.cs ~11167) wraps both the terrain draw and the entire OutdoorScenery dispatcher draw (which includes neighbor building shells, scenery, and the depth-repair pass) in:

if (didInsideStencil) { ... terrain + OutdoorScenery ... }

where didInsideStencil == (camera-side-filtered exit-portal mask is non-empty).

So the portal mask is doing two jobs at once:

• Job A (intended): gate "paint terrain/sky through the portal openings."
• Job B (accidental): decide "draw exterior geometry (shells/scenery/depth-repair) at all."

Why option 1 failed: option 1 correctly shrank the mask (same-level cells only) so the cellar's mask went empty → didInsideStencil=false → Step 4 skipped entirely → exterior shells + terrain vanished → "walls transparent, sky behind, terrain gone." The old flat mask (all visN cells) papered over this by almost always keeping the mask non-empty.

Consequence for ANY fix: correctly scoping/clipping the portal mask is not enough on its own — it will empty the mask in legitimate cases (looking at an interior wall, sealed cellar) and kill exterior rendering. Job A and Job B must be decoupled so exterior geometry draws regardless of whether any portal is currently visible. This is true for option 2 as much as option 1.

Decision: option 2 (WB-faithful recursive portal visibility)

Chosen over option 1 (decouple-only) because:

• The project mandate is faithful WB/retail porting; option 1 is a structural deviation from WB's RenderInsideOut, and prior "cleaner redesign" deviations were reverted.
• Option 2 handles every case (cellar, stacked floors, deep dungeons) without per-case special-casing.
• It is large enough to deserve design-first (brainstorm), not a mid-session patch.

Note: option 2 still has to solve the Job-A/Job-B decoupling above — it's not optional.

Open design questions for the brainstorm (resolve BEFORE coding)

1. Does WB even render a sealed sub-cell (cellar) via inside-out? Check how WB derives _buildingsWithCurrentCell (VisibilityManager.PrepareVisibility + PortalRenderManager.GetBuildingPortalsByCellId). If WB excludes a cell with no exit portals from the inside-out path, the "fix" may be a classification change, not recursion. Verify against WB source — don't assume recursion exists.
2. How does WB ACTUALLY constrain per-portal visibility? Re-read VisibilityManager.cs (RenderInsideOut/RenderOutsideIn) + PortalRenderManager.cs end-to-end. Is the clipping (a) recursive portal traversal, (b) the 3-bit stencil Step-5 pipeline, (c) pure Step-3 depth occlusion, or (d) the BSP portal-graph in PrepareVisibility? Our port copied the flat Steps 1-4; the constraint mechanism may live in code we didn't port.
3. Job-A/Job-B decoupling. Design how exterior geometry (shells + scenery + depth-repair) draws independent of the portal mask, while terrain-through-portal stays stencil-gated. This must land regardless of the recursion design.
4. Stencil-bit budget + occlusion-query lifecycle if the full WB Step-5 cross-building path is adopted (currently gated off via ACDREAM_A8_STEP5).

Key source references for the brainstorm

WB (the algorithm being ported):

• references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs — PrepareVisibility (47-71), RenderInsideOut (73-239), RenderOutsideIn (241+).
• references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/PortalRenderManager.cs — RenderBuildingStencilMask, GetVisibleBuildingPortals, GetBuildingPortalsByCellId.
• references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/EnvCellRenderManager.cs.

acdream (the current port):

• src/AcDream.App/Rendering/GameWindow.cs — RenderInsideOutAcdream (~11012), RenderOutsideInAcdream (~196), the Step-4 didInsideStencil gate (~11167). This is where the Job-A/Job-B coupling lives.
• src/AcDream.App/Rendering/IndoorCellStencilPipeline.cs — PortalMeshBuilder (camera-side filter), RenderBuildingStencilMask, DrawUploadedPortalMesh.
• src/AcDream.App/Rendering/Wb/BuildingLoader.cs — building cell-set BFS (mirrors WB PortalService; cellar IS expanded into building 0xA).

Retail oracle (if WB is ambiguous):

• docs/research/named-retail/acclient_2013_pseudo_c.txt — CObjCell::find_visible_child_cell (≈311397), PView::DrawCells (≈432709). Retail uses screen-space polygon-clip scissor recursion — the conceptual ancestor of "clip each portal to the chain."

Offline tooling:

• tools/A8CellAudit — dotnet run -- portals <cellId...> dumps a cell's CellPortals (exit vs interior); -- buildings <lb> <radius> dumps building→cell grouping. Reproduces the whole investigation in seconds, no launch.

Brainstorming kickoff prompt (copy-paste into a fresh session)

Use the superpowers:brainstorming skill. We're designing the retail-faithful fix for the A8 "cellar flap" — the last A8 indoor-rendering defect.

Read first, in order:

1. docs/research/2026-05-28-a8-cellar-flap-option2-handoff.md (this doc) — current state, the confirmed root cause, the didInsideStencil double-duty finding, the decision, and the open design questions.
2. docs/research/2026-05-28-a8-cellar-flap-root-cause.md — the offline evidence.
3. The WB + acdream source references listed in the handoff.

The goal: design how acdream's indoor visibility should render outside-through- portals correctly clipped to the portal chain (so a sealed cellar shows no terrain, a windowed room shows its own windows, deep rooms show only the sliver visible through the doorway chain) AND decouple "draw exterior geometry at all" from "is the portal mask non-empty" (the coupling that made the targeted fix regress).

Brainstorm MUST resolve the 4 open design questions in the handoff before any code — especially Q1 (does WB even render a sealed cellar inside-out?) and Q2 (what is WB's ACTUAL per-portal clipping mechanism — verify against source, don't assume recursion). Output a written design/plan; do not start coding until the design is agreed.

Process rules still in force: no workarounds/band-aids; faithful WB/retail port; one visual gate only when a complete fix is ready; the broken indoor branch is behind ACDREAM_A8_INDOOR_BRANCH=1 (default off = pre-A8 visual). The dirty tree has valuable uncommitted A8 work — decide whether to commit it (strip ACDREAM_A8_DIAG_* first) before starting.