acdream/docs/research/2026-07-06-176-seam-floor-zfight-handoff.md

Pickup handoff — #176 seam-floor lighting flicker = a RUNTIME draw z-fight (RenderDoc next)

Paste the companion prompt below into a fresh session. Read this file, then claude-memory/project_render_pipeline_digest.md (top banner), then ISSUES #176.

TL;DR — what #176 actually is now

The Facility Hub corridor floor shows hard-edged purple triangular facets that flicker as the camera turns, at cell seams. After a long investigation (11 hypotheses), the domain is pinned by evidence:

#176's residual is a RUNTIME draw-level depth-fight (z-fight) in the seam FLOOR geometry — two draws the renderer emits at ~the same depth, one carrying the purple portal light and one not, whose winner flips as the camera moves. It is NOT lighting, NOT membership, NOT dat geometry.

The wedge SHAPE itself is retail-faithful (retail shows the same faceted purple — cdb-proven, below). The only defect is the flicker, and it is a render/draw problem. The next step is a RenderDoc pixel-history capture — do NOT throw more lighting fixes at it (two already did nothing).

The elimination table (evidence — this is the DO-NOT-RETRY list)

Ruled OUT	How (hard evidence)
Lighting brightness	per-light cap on the dynamic branch (mesh_modern.vert) → no visual change, reverted
Lighting selection	SelectForCell (all dynamic lights per cell, retail-exact) → no visual change
Light-set camera-cap churn (the OLD "confirmed" #176 theory)	visible-cell scoping shipped (c500912b); probe-proven ~285 through-floor lights dropped/frame — symptom unchanged. REFUTED.
Membership / the "flap"	ACDREAM_PROBE_FLAP: render cell = 0x8A020164 on 100% of 188,732 frames across 526 distinct camera angles, res=None always; ACDREAM_PROBE_PVINPUT flood is stable-per-angle (17/10/8…), never oscillates at a fixed view; 1 [cell-transit] (the spawn teleport) total
Dat-geometry z-fight	Issue176177DungeonSeamInspectionTests.CorridorNeighborhood_CoplanarOverlappingDrawnPolyPairs seeded on the ACTUAL cell 0x8A020164 + neighbors → zero coplanar drawn pairs at the z=−6 corridor floor (only the benign same-cell z=−12 under-hall floor tiling in 0x011E)
A2C / alpha-hole see-through	corridor floor surface 0x08000377 is fully opaque (alpha0Texels=0, transl=0.00)
Translucent under-surface blend	the one translucent colored surface 0x08000034 is NoPos (not drawn)
Flat (per-face) normals	corridor floor uses smooth per-vertex dat normals (center (0,0,1), corners tilted ~27° — retail-style edge smoothing), NOT flat (CellVertexNormals_SmoothOrFaceted_Dump)

What retail actually does (cdb-proven — the wedge is faithful)

tools/cdb/issue176-floor-light.cdb traced live retail's config_hardware_light standing in the Hub (binary↔PDB MATCH, GUID 9e847e2f…):

• Retail applies 4 intensity-100 magenta portal lights (d3dIdx 3–6, color=(0.784,0,0.784), falloff=6) + the viewer fill (d3dIdx 1, intensity=2.25 falloff=10) as D3D hardware lights to EVERY Hub cell (0102,0103,0109,0111,0112,0115,0118,0119,011a,011e,011f,0121,0122,0123…), every frame, stable.
• So retail's cell floors ARE lit by the portals via per-vertex hardware T&L over the same smoothed fan-corner normals → the same faceted purple wedges. → the wedge SHAPE is retail-faithful; only the flicker is ours.

The intensity-100 magenta light is the portal (2 portal weenies 0x000F4247/0x000F4248 in cells 0x8A020118/0x8A020119, dyn=1). Confirmed via the [light-detail] owner=/cell=/dyn= probe fields.

The residual bug — a runtime double-draw of the seam floor

Since it's not dat geometry, the renderer is emitting the corridor floor (or a coincident surface) twice at ~the same depth. Prime suspects to check in RenderDoc (do NOT assume — capture and read):

1. The +0.02 m shell render lift (PortalVisibilityBuilder.ShellDrawLiftZ, register AP-32, the #130 saga). If the shell floor draws lifted while some other pass draws the same floor unlifted, 0.02 m z-fights at grazing angles.
2. The A8 double-sided cell-shell stopgap (#178, LIVE): EnvCellRenderer.RenderModernMDIInternal if (cullMode == CullMode.Landblock) cullMode = CullMode.None; — every cell shell draws two-sided. Retiring this is already an open issue; test whether it's implicated.
3. Portal depth-writes — RetailPViewRenderer.DrawExitPortalMasks / the interior-root depth-clear+seal path. Seals are supposed to fire only for OtherCellId==0xFFFF (a sealed dungeon draws zero), but VERIFY in the capture that no depth-mask lands on the floor-portal plane (the corridor floor IS a floor-portal poly to the under-room, surf 0x08000377, z=−6).

RenderDoc plan (the definitive next step)

1. Launch acdream under RenderDoc (renderdoc → capture AcDream.App, or inject). Standard ACDREAM_LIVE env from CLAUDE.md.
2. Stand in cell 0x8A020164 corridor, at an angle where the floor flickers. Capture a frame (F12).
3. In RenderDoc: right-click a flickering floor pixel → "History" (pixel history). It lists every draw that touched that pixel + its depth + pass/fail.
4. Two draws at ~equal depth writing that pixel = the z-fight. Identify which two passes they are (shell vs shell-lift vs portal-mask). Report the draw names + depths back — that names the fix.
5. Fix at the source (make the two draws not coincide: drop the redundant draw, or reconcile the lift), then re-gate. No band-aid depth-bias (that's a workaround — see CLAUDE.md).

What's committed / the state

• c500912b (in main): visible-cell light scoping — LightSource.CellId
  • BuildPointLightSnapshot(camPos, visibleCells) (retail add_*_lights over visible_cell_table) + the [indoor-light] probe. Retail-faithful; fixed the camera-eviction latent bug. Register AP-85 corrected. Corrected the old handoff's imprecise "insert_light = per-cell" framing — the real model is visible-cell-scoped collection into a small player-nearest pool; see docs/research/2026-07-06-a7-per-cell-lighting-pseudocode.md.
• This commit: LightManager.SelectForCell (all dynamic lights per EnvCell, retail minimize_envcell_lighting) wired into EnvCellRenderer.GetCellLightSet; the [light-detail] owner/cell/dyn probe; CellVertexNormals_* dump; tools/cdb/issue176-floor-light.cdb. Retail-faithful, NOT the flicker fix.
• Suites green: Core 2599 + 2 skip. All on main.

Apparatus (reuse, don't rebuild)

• ACDREAM_PROBE_FLAP=1 — per-frame [flap-cam] render cell + [flap] portal decisions (proved membership stable).
• ACDREAM_PROBE_PVINPUT=1 — per-frame [pv-input] flood=N eye= yaw=.
• ACDREAM_PROBE_LIGHT=1 — [light] + [light-detail] (now with owner/cell/dyn).
• ACDREAM_PROBE_INDOOR_LIGHT=1 — [indoor-light] scoped-pool SET composition.
• tools/cdb/issue176-floor-light.cdb — retail light-setup trace.
• Issue176177DungeonSeamInspectionTests — dat truth (coplanar sweep, floor surfaces, vertex normals); CorridorNeighborhood_CoplanarOverlappingDrawnPolyPairs seed = {0164,0165,016E,017A}+neighbors.

Repro + launch protocol

dotnet build green FIRST (close any running client — a client may still be up; the user manages lifecycle, do NOT kill it, ASK). Standard ACDREAM_LIVE PowerShell launch. Test char spawns in the Facility Hub; the flickering corridor is cell 0x8A020164 (player z≈−5.9). Turn back-and-forth across a seam to reproduce. Strip \000 before grep (PowerShell Tee = UTF-16).

Process lesson (paid for in full this session)

Get a screenshot AND a retail cdb trace EARLY for a render bug — before theorizing. This session chased 11 inference-based hypotheses over many launches; the screenshot (faceted triangles) + the cdb trace (retail applies the same lights → faithful shape) would each have redirected the whole thing in one step. The project's own rules already say this; follow them.

Also open

• #177 — dungeon stairs pop in/out (0178/0182/0183) — a SEPARATE portal-visibility miss, not lighting. Untouched this arc.