acdream/docs/research/2026-05-30-phase-u4-shipped-and-flap-handoff.md

Phase U.4 — shipped (unified pipeline + indoor rendering) + the threshold "flap" handoff (2026-05-30)

TL;DR

The unified retail-faithful render pipeline (Phase U) is built and shipped through U.4, and indoor rendering is visually verified correct: standing inside a Holtburg cottage / cellar / inn, the cell-shell walls render solid, terrain no longer bleeds into interiors, and the per-cell clip gating works. This replaced the abandoned two-pipe (inside/outside) split (#103). Modern code, retail behavior.

One residual remains: the threshold "flap" — crossing a doorway (inside↔outside), terrain

• building-shells briefly vanish leaving only un-gated geometry (particles + live entities) over the bluish clear color. This is precisely root-caused (not a mystery): our per-frame view-dependent portal BFS is unstable at multi-hop exit paths, so OutsideView flickers empty → terrain gets Skip-ped. The retail-faithful fix is PVS (stab_list) grounding — a focused sub-step, U.4c. It was deliberately NOT attempted at the end of this (very long) session to avoid thrashing a fragile cell-resolution area (the #98 lesson + the "don't push tired design calls late-session" rule).

Visual gate status: PASS for the indoor case; the seamless-threshold criterion is deferred to U.4c.

---

What shipped this session (Phase U, all committed on claude/thirsty-goldberg-51bb9b)

Stage	What	Commit(s)
Spec + plan	Phase U design + implementation plan	8601137, 0f7b395
U.1	Delete the two-pipe machinery (kept all audited fixes)	3fc77be
U.2a	Portal BFS: closest-first ordering + retail fixpoint termination	d880775 (+ 306cdb0 review fixups)
U.2b	Reciprocal OtherPortalClip (+ CRITICAL fix: resolve by other_portal_id, not first-OtherCellId-scan)	3916b2b → 65781f5
U.2c	ClipPlaneSet (NDC convex region → gl_ClipDistance planes, 8-cap + scissor fallback)	a83b430
U.2d	ACDREAM_PROBE_VIS visibility probe (in RenderingDiagnostics, Core)	0b12583
U.3	GPU gate: gl_ClipDistance in mesh+terrain shaders, ClipFrame, scoped clip bracket	bf2e559 → 864fc5f
U.4	Unified gated draw pass (ClipFrameAssembler, per-instance slots, EnvCellRenderer.Render wired, terrain Skip/Scissor/Planes) + ResolveEntitySlot tests	7993e06 → 354ca74
U.4 fix 1	EnvCellRenderer.Render uploads its own uViewProjection (was inheriting WbDrawDispatcher's → stale → seam flicker)	d6d4671
U.4 fix 2	EnvCellRenderer.Render sets its own BLEND + DepthMask per pass (was inheriting → opaque walls blended against clear color → "transparent walls")	9be9547

Build green, App tests 151/151 throughout. Core failures are the documented pre-existing static-leak flakiness (zero Core production files touched by U.4). Branch is UNPUSHED — push decision is the user's.

Two reviews caught real CRITICALs (the process earned its keep)

• U.2b: reciprocal-portal resolved by scanning for the first OtherCellId match → mis-resolved when a cell has two portals to one neighbour (real on Holtburg cellar 0x148↔0x149) → hidden geometry. Fixed by plumbing the dat's OtherPortalId back-link.
• U.3: GL_CLIP_DISTANCE0..7 enabled globally while 6 non-clip-writing shaders ran → undefined behavior (benign on the dev driver, a portability landmine). Fixed by scoping the enable to the world-geometry draws.

The recurring lesson (now 3×): EnvCellRenderer must own its GL state

EnvCellRenderer.Render was dormant pre-U.4 (only the deleted two-pipe path called it). When U.4 wired it into the live loop, it surfaced THREE inherited-GL-state bugs in sequence:

1. (2026-05-28, pre-U.4) cull state → "missing walls".
2. (U.4 fix 1) uViewProjection → stale-matrix seam flicker.
3. (U.4 fix 2) BLEND + DepthMask → opaque walls blending against the clear color. A renderer that runs mid-frame after other consumers MUST establish every GL state it depends on (matrix, blend, depth-mask, cull, front-face, A2C) — never inherit. See the memory note render-self-contained-gl-state.

---

The flap — root cause (evidence-based)

Symptom

Crossing a doorway (the user's screenshot, inside→outside): terrain + building-shells + cell- shells vanish, leaving only particles + live entities (NPCs/doors/items, slot 0 = no-clip) over the bluish clear color (glClearColor(0.05,0.10,0.18)).

Evidence — ACDREAM_PROBE_VIS [vis] lines, SAME cell across frames

root=0xA9B40171  cells=4  ids=[...,0xA9B40170]   outside(polys=1,planes=4)   ← window cell reached → terrain draws
root=0xA9B40171  cells=3  ids=[0xA9B40171,75,74]  outside(polys=0,planes=0)   ← window cell dropped → terrain SKIPPED

Over one cellar traversal: 10 empty-OutsideView frames vs 16 non-empty — for the same cells. The ground-floor cell 0xA9B40170 (which holds the window / 0xFFFF exit portal) flickers in and out of the visible set as the camera moves.

Mechanism

1. Our PortalVisibilityBuilder runs a per-frame, view-dependent portal BFS. The CameraOnInteriorSide portal-side test culls portals based on the camera's exact pose.
2. Near a portal boundary, a tiny camera move flips which portals pass the test → the multi-hop path (cellar → ground floor → window) breaks in some frames.
3. When the exit-portal cell isn't reached, OutsideView is empty.
4. ClipFrameAssembler maps empty OutsideView → TerrainMode.Skip (the bleed fix) AND outdoorVisible=false → building-shells culled.
5. Result: terrain + building-shells flap off whenever the exit path momentarily breaks.

Why retail is seamless (the fix direction)

Retail grounds visibility in a precomputed potentially-visible-set: on cell entry, CEnvCell::grab_visible_cells populates the visible_cell_table from the cell's stab_list (a STABLE per-cell PVS), and seen_outside is a stable per-cell flag ("this cell is adjacent to the exterior"). The per-frame PView clip refines WHERE things draw, but the SET of reachable cells (and thus whether the exit portal is reachable) is stable. Our pure per-frame view-dependent BFS has no such anchor → it flaps. Retail anchors: CEnvCell::grab_visible_cells ~311878, seen_outside set in find_cell_list ~311044, stab_list on CEnvCell.

---

U.4c — proposed scope (stabilize portal visibility)

Goal: make the visible-cell set (and therefore OutsideView / the terrain-draw decision) stable so the threshold is seamless, the retail way — NOT a hysteresis/last-frame band-aid (that's a workaround; forbidden).

Candidate approaches to settle in a brainstorm (do NOT jump to code — fragile area, #98 history):

1. PVS / stab_list grounding (most retail-faithful). Load each cell's stab_list (the dat has it) into a stable per-cell visible set on cell entry; the per-frame BFS operates within / is anchored by it, so the exit-portal cell never drops out. This is what makes retail seamless by construction. Largest change; needs the stab_list dat read + integration.
2. Stable seen_outside terrain-draw decision. Decouple "should terrain draw" (stable: does the camera cell statically reach a 0xFFFF exit portal within its building's portal graph?) from "where to clip it" (OutsideView). Still needs a clip region when OutsideView momentarily empties (else bleed) — likely the raw exit-portal projection as a fallback.
3. Investigate the specific instability first. Why does 0xA9B40170 drop from the cellar's BFS at certain angles — is it CameraOnInteriorSide on the stairwell portal being pose-brittle? A more robust (epsilon / reciprocal-aware) side test might stabilize the common case before a full PVS port. Cheapest; verify it's retail-faithful, not a fudge.

Recommendation: brainstorm U.4c (superpowers:brainstorming) starting from approach 1 vs 3, using the [vis] probe as the apparatus. Build a stable visible-set; the clip stays per-frame.

Also deferred (not the flap, separately tracked)

• U.5 — outdoor-camera → building-interior peering (retail outdoor_pview / DrawBuilding / DrawPortal / ConstructView(CBldPortal)). Standing OUTSIDE looking INTO a house still shows no interior; that's U.5, not the flap. Open data dependency: render-side building-exterior portal geometry (we carry BldPortalInfo physics-side).
• U.6 — dungeon-scale validation; close/relate #95 + the residual #102 diamond-clip note.
• Minor leftovers flagged in the U.4 review: AppendSlot collapses the 3 Count==0 states (U.4c should branch IsNothingVisible/UseScissorFallback before calling it); orphaned LandblockEntriesWithoutAnimatedIndex; dead BuildingShellAnchorPass/Reject counters.

---

Apparatus (use this, evidence-first)

• ACDREAM_PROBE_VIS=1 — [vis] line per cell change: root cell, visible-cell count + ids, outside(polys=N,planes=M), per-cell plane counts, scissor fallbacks. The flap shows as outside(polys=0) frames interleaved with outside(polys=1) for the same cell. Owner: AcDream.Core.Rendering.RenderingDiagnostics.EmitVis.
• Launch block: CLAUDE.md "Running the client" + ACDREAM_PROBE_VIS=1, pipe to a fresh log. Read it with PowerShell Select-String (the Tee log is UTF-16) or tr -d '\0' | grep in bash.

Next-session pickup prompt

Phase U.4c — stabilize portal visibility (fix the threshold "flap"). The unified render
pipeline (Phase U, U.1-U.4) is shipped and indoor rendering is visually verified correct.
The remaining issue is the doorway "flap": terrain + building-shells flicker off when
crossing the threshold. Root cause is in
docs/research/2026-05-30-phase-u4-shipped-and-flap-handoff.md — READ IT FIRST. It is the
per-frame view-dependent portal BFS being unstable at multi-hop exit paths (OutsideView
flickers empty → terrain Skip'd). The retail-faithful fix is PVS / stab_list grounding
(retail grab_visible_cells / seen_outside). This is a FRAGILE cell-resolution area (#98
saga) — start with superpowers:brainstorming on PVS-grounding vs a targeted side-test
stabilization; use ACDREAM_PROBE_VIS as the apparatus; NO workarounds (no hysteresis
band-aid). Do NOT touch the indoor rendering (it works). U.5 (outdoor→building peering)
and U.6 (dungeon scale) remain after U.4c.

Git state

• All Phase U work committed on claude/thirsty-goldberg-51bb9b, unpushed (push is the user's call).
• Two git stash entries on the branch (#98/#101 physics WIP, pre-triage backup) — preserve, do not drop.