acdream/docs/research/2026-05-29-a8f-visual-gate-failure-handoff.md

Phase A8.F — visual-gate failure + pickup handoff (2026-05-29)

TL;DR

The retail portal-frame visibility port (Phase A8.F) shipped as code (Tasks 0–8, committed) but FAILED its visual gate. With ACDREAM_A8_INDOOR_BRANCH=1, indoor and outside-in rendering is broadly broken: cottage/cellar interiors are "covered in outdoor terrain / transparent walls," and walls are invisible in other houses from both inside and outside.

The default game is UNAFFECTED. cameraInsideBuilding = a8IndoorBranchEnabled && (inside a building) (GameWindow.cs:7343), so RenderInsideOutAcdream only runs with the opt-in env var. Without it, rendering is the pre-A8 path (walls render; only the old cellar flap remains). Do not panic — normal play is fine; the A8.F branch is the broken opt-in.

The work is committed (not reverted): the GL-free CPU layer is solid and unit-tested; the integration (CPU-built clipped NDC mask → stencil-gate all outdoor terrain/ scenery) is what fails at runtime. This doc has the root-cause analysis, the apparatus, and a pickup prompt.

What was built (the A8.F port)

Spec: docs/superpowers/specs/2026-05-29-phase-a8f-portal-frame-visibility-design.md Plan: docs/superpowers/plans/2026-05-29-phase-a8f-portal-frame-visibility.md

Idea: port retail's PView recursive portal-clip (ConstructView/ClipPortals/ GetClip) — WB has NO such recursion, so the flat WB stencil can't fix the cellar flap; retail clips each portal to its portal chain. We built a GL-free CPU builder that walks the portal graph and produces OutsideView (a screen-space NDC region = exit portals recursively clipped), then stencil-gate outdoor terrain/scenery to it.

Commits (on claude/strange-albattani-3fc83c, after baseline 5dc4140):

• bb903bc Task 0 — strip ACDREAM_A8_DIAG_* flags.
• 406307e Task 1 — ViewPolygon + CellView (GL-free data model). Unit-tested.
• 7f46c27 Task 2 — ScreenPolygonClip (Sutherland-Hodgman convex intersection). Unit-tested.
• a28a176 + 9ec8330 Task 3 — PortalProjection (NDC + near-plane clip). Unit-tested. (A near-plane bug was caught + fixed during impl: w>=WEps → w+z>=0.)
• 0ed462c + 270c21f Task 4 — PortalVisibilityBuilder (the BFS). Unit-tested. (Known dungeon-scaling fast-follow filed as issue #102.)
• d12892b + 08f6a0c + d581f4c Task 5 — IndoorCellStencilPipeline.MarkAndPunchNdc.
• 9e2eb90 Task 6 — RenderInsideOut rewrite: builder-driven mask + Job-A/B decouple.
• 1c02a01 + 5a012c0 Task 7 — wire-in #2 per-cell translucent clip on stencil bit 2. (A DepthFunc-leak bug was caught + fixed by code review.)
• e0051e0 + 452ee5b Task 8 — wire-in #3 cross-building (ungated Step 5, clipped bit-1).
• 7c3ee43 — triage apparatus (this debugging session; see below).

All dotnet build + dotnet test green throughout (App baseline 108).

The visual-gate failure — symptoms

With ACDREAM_A8_INDOOR_BRANCH=1 at Holtburg cottages (camera = +Acdream):

1. Outside→in (looking into a cottage from outside): cellar entrance looked correct.
2. Inside the cellar: covered in outdoor terrain; walls transparent (see-through). Passable (render-only).
3. Looking out from inside (toward a window): looked roughly normal.
4. Passing inside→out: buildings + ground disappear; only server-spawned things (doors/NPCs/particles) remain.
5. Invisible walls in OTHER houses, both from inside and outside.

Root-cause analysis (evidence-based; see apparatus below)

Finding 1 — the cell walls DO render. [opaque] probe (opaque cell-render stats, captured BEFORE the per-cell transparent loop overwrites them): cells=7 tris=50/60, cells=25 tris=108 in occupied cottage cells. tris=0 only in transient frustum-culled frames. So "transparent walls" is NOT walls failing to render — it's terrain drawn over them. (NOTE: the older [envcells] probe reads stats AFTER the transparent loop, so its cells=1 tris=0 is a misleading artifact — ignore it.)

Finding 2 — OutsideView is frequently EMPTY, and when non-empty it doesn't narrow. [pv-dump] OUTSIDEVIEW polys=N: polys=0 in the majority of frames; polys=1 sometimes. When non-empty, the clipped region ≈ the full source window (e.g. from the cellar, the 0xA9B40170 window passes through ~unclipped, not narrowed to the stairwell sliver). So the recursive-clip — the entire point of A8.F — is not constraining at runtime.

Finding 3 — projection/clip MATH is correct; the builder under-produces. When a [pv-dump] EXIT line fires, the local quad → NDC → clipped chain is sane (window quad local=[(5.55,-8.61,0)(7.45,-8.61,0)(7.45,-8.35,2.5)(5.55,-8.35,2.5)] → reasonable NDC → clipped region). The viewProj is a valid System.Numerics row-vector view*proj (M33≈M34 because far≫near makes proj.M33≈-1; M44 varies with camera, expected). ProjectToNdc matches the GPU convention (verified algebraically: Vector4.Transform(v,M) == GPU M*v for transpose=false upload). Projection is not the bug. The bug is the builder yielding empty/too-wide regions for most real camera positions — the exit-portal clip produces empty (needs deeper trace: portal-side cull? FullScreen-clip producing empty? BFS not reaching exit portals from most positions?).

Finding 4 — the Job-A/B decoupling floods terrain when OutsideView is empty (the proximate cause of "transparent walls"). Task 6 made Step-4 terrain/scenery draw UNCONDITIONALLY, with only the stencil state gated. When OutsideView is empty (didInsideStencil=false), the else branch disables the stencil and draws terrain ungated (GameWindow.cs ~11142). Combined with Finding 2 (empty most frames), terrain floods over the (rendered) cell interior → "covered in terrain / transparent walls." This is exactly the Opus Task-6 code-review Minor #2 risk, realized at scale.

Why WB doesn't hit this but we do: in WB, didInsideStencil = "inside a building" (always true indoors, because it marks the whole building's exit-portal set, which is non-empty). WB never has the "inside + empty mask" case. Our builder produces empty masks frequently, so the else branch (which WB effectively never exercises with an empty mask) floods. The CPU-NDC-recursive-clip mask is far more fragile at runtime than WB's flat building mask.

The two compounding root causes (summary)

1. OutsideView builder under-produces at runtime — empty most frames; never narrows recursively. (Builder/clip integration with real geometry; not the projection math.)
2. Empty-OutsideView → ungated terrain flood — the Job-A/B decoupling's else branch draws terrain everywhere when the mask is empty, painting over the cell interior.

Concrete first-fix hypothesis (try this first next session)

The else branch is wrong: an empty OutsideView means "no outdoors visible from here," not "all outdoors visible." When inside a building with an empty mask, draw NO outdoor terrain/scenery (or fall back to the pre-A8 "depth-clear-when-inside" behavior), rather than ungated terrain. That alone should stop the flooding (walls become solid; you temporarily lose terrain-through-portal until the builder is fixed, but the interior renders correctly). This decouples the two bugs so each can be fixed independently.

Then separately debug Finding 2 (why the builder yields empty/too-wide regions) — the [pv-dump] apparatus already traces local→NDC→clipped; extend it to log the side-test result and the per-stage vert counts for ALL exit portals (the current dump's EXIT-CULLED/ EXIT-PROJ/EXIT-CLIP lines do this — read them across many frames to see which gate kills the portals when polys=0).

The architectural question (escalate to the human before a big rewrite)

Is "CPU-build a recursively-clipped NDC region + stencil-gate ALL outdoor terrain/scenery to it" viable in acdream's pipeline, or is it too fragile (Finding 2)? Options:

• (a) Fix the builder + the else-branch (incremental; the first-fix hypothesis above).
• (b) Reconsider enforcement — e.g., port retail's per-cell screen-space scissor more literally, or keep WB's flat building mask (accept the cellar flap) and special-case only the cellar. The user explicitly chose the faithful retail port (option A) at brainstorm; revisit only if (a) proves intractable.

Safety / current state

• Default game safe: indoor branch gated behind ACDREAM_A8_INDOOR_BRANCH=1 (cameraInsideBuilding = a8IndoorBranchEnabled && inside, GameWindow.cs:7343).
• Work is committed, not reverted (CPU layer is good; integration needs fixing).
• The old cellar flap (the original M1.5 blocker) is still present in the default (pre-A8) path — A8.F did not fix it.
• Tree clean as of 7c3ee43.

Apparatus (all env-gated; require ACDREAM_A8_INDOOR_BRANCH=1 to reach the code)

• ACDREAM_A8_DUMP_PV=1 — [pv-dump] lines: per camera cell, the exit-portal local→NDC→clipped geometry (EXIT-CULLED / EXIT-PROJ / EXIT-CLIP / EXIT) + OUTSIDEVIEW polys=N. First 2 Build calls per distinct camera cell. (PortalVisibilityBuilder.cs.)
• ACDREAM_PROBE_ENVCELL=1 — [opaque] line: opaque cell-render stats (cells/tris) BEFORE the transparent loop overwrites _envCellRenderer.Stats. One-shot per camera cell. (GameWindow.cs, after the Step-3 opaque render.)
• ACDREAM_PROBE_VIS=1 — [buildings]/[draworder]/[stencil]/[envcells] (existing). NOTE [envcells] is post-transparent-loop (misleading); [stencil] verts reflects the OutsideView triangle count.
• tools/A8CellAudit — offline cell/portal dumper (portals <cellId> / buildings <lb> <radius>).

Launch (PowerShell), then walk +Acdream into a Holtburg cottage ground floor + cellar:

$env:ACDREAM_DAT_DIR="$env:USERPROFILE\Documents\Asheron's Call"; $env:ACDREAM_LIVE="1"
$env:ACDREAM_TEST_HOST="127.0.0.1"; $env:ACDREAM_TEST_PORT="9000"
$env:ACDREAM_TEST_USER="testaccount"; $env:ACDREAM_TEST_PASS="testpassword"
$env:ACDREAM_A8_INDOOR_BRANCH="1"; $env:ACDREAM_A8_DUMP_PV="1"; $env:ACDREAM_PROBE_ENVCELL="1"
dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | Tee-Object -FilePath "a8f.log"

Cottage cells: 0xA9B40170 (ground floor, has window exit portal), 0xA9B40171 (cellar), 0xA9B40174/175 (cellar rooms), building 0xA. Inn vestibule: 0xA9B40164/162.

Code anchors

• src/AcDream.App/Rendering/PortalVisibilityBuilder.cs — the builder (Finding 2 lives here).
• src/AcDream.App/Rendering/GameWindow.cs — RenderInsideOutAcdream (~11012); Step-4 else ungated-terrain branch (~11142, Finding 4); call-site gate (~7343, 7636).
• src/AcDream.App/Rendering/IndoorCellStencilPipeline.cs — MarkAndPunchNdc + bit-2 helpers.
• src/AcDream.App/Rendering/PortalProjection.cs / ScreenPolygonClip.cs / PortalView.cs — CPU layer (correct).
• references/WorldBuilder/.../VisibilityManager.cs:73-239 — the WB reference (flat, no recursion).
• Retail oracle: docs/research/named-retail/acclient_2013_pseudo_c.txt — PView::ConstructView 433750, ClipPortals 433572, GetClip 432344.

Pickup prompt

Read docs/research/2026-05-29-a8f-visual-gate-failure-handoff.md and pick up the A8.F debugging. The default game is SAFE (indoor branch gated behind ACDREAM_A8_INDOOR_BRANCH). Use superpowers:systematic-debugging. Two compounding root causes are documented: (1) the OutsideView builder under-produces (empty most frames, never narrows); (2) the Job-A/B decoupling floods ungated terrain when OutsideView is empty. Start with the first-fix hypothesis: make the empty-OutsideView case draw NO outdoor terrain/scenery when inside (an empty mask = "no outdoors visible," not "all outdoors"), to stop the terrain-over-walls flood and isolate the two bugs. Verify via the apparatus (ACDREAM_A8_DUMP_PV / ACDREAM_PROBE_ENVCELL) — read the EXIT-CULLED/PROJ/CLIP lines across frames to learn which gate kills the exit portals when polys=0. Then fix the builder. If the builder proves intractable, escalate the architectural question (handoff §"The architectural question") to the user before any big rewrite — do NOT thrash. No speculative fixes without root cause (the Iron Law). The visual gate (user looking at a Holtburg cottage cellar) is the acceptance test.