From 95b6874c1241877c0530d2fda76aac468c52830f Mon Sep 17 00:00:00 2001 From: Erik Date: Sun, 31 May 2026 17:01:23 +0200 Subject: [PATCH] =?UTF-8?q?docs(render):=20Phase=20U.4c=20=E2=80=94=20flap?= =?UTF-8?q?=20fixed=20+=20residuals=20handoff=20(checkpoint)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Canonical handoff (research note) for the U.4c flap fix + the three residuals the visual gate revealed (#78 terrain-not-gated-inside, camera-collision need, U.5). Records the full hypothesis journey (H1/H2 both evidence-disproven) so the next session doesn't re-walk them. ISSUES.md: flap recorded in Recently-closed; #78 annotated (more visible post-fix). CLAUDE.md: U-phase orientation updated with the flap-fixed status + the canonical handoff pointer + camera-collision-next. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 19 +++ docs/ISSUES.md | 32 +++++ ...31-u4c-flap-fixed-and-residuals-handoff.md | 123 ++++++++++++++++++ 3 files changed, 174 insertions(+) create mode 100644 docs/research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md diff --git a/CLAUDE.md b/CLAUDE.md index 319dbbd..965948f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -741,6 +741,25 @@ pickup prompt: [`docs/research/2026-05-30-unified-render-pipeline-decision-and-handoff.md`](docs/research/2026-05-30-unified-render-pipeline-decision-and-handoff.md). The M1.5 narrative below is history retained for context. +**2026-05-31 — U.4c doorway FLAP FIXED** (`0ee328a`, visual-verified "flap gone"). +Root cause (converged on a live `ACDREAM_PROBE_FLAP` capture, after disproving an +H2 `PortalSide` side-test fix and an H1 PVS-grounding hypothesis): indoor visibility +was rooted at the 3rd-person camera **eye**, which drifts out of the player's cell → +`FindCameraCell` returns a STALE cell for its grace frames → the doorway portal is +culled as behind-the-eye → exit cell + terrain + shells drop. Fix: root indoor +visibility (cell resolution + portal-side test) at the **player's cell** +(retail `CellManager::ChangePosition`; matches the existing lighting decision). Eye +still drives projection. **The flap is done; the indoor pipeline is NOT yet seamless** — +the visual gate revealed three SEPARATE residuals: (1) **#78** outdoor terrain not gated +inside (now more visible since terrain draws again); (2) **camera collision** needed (the +chase eye is outside the player's cell ~79% of frames → the eye-projected clip +over-includes → transparent outer walls); (3) **U.5** outside-looking-in (deferred). +Camera collision (retail `SmartBox::update_viewer` keeping the eye in the cell) is the +highest-leverage next step. CANONICAL handoff (read first next session): +[`docs/research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md`](docs/research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md). +Apparatus `ACDREAM_PROBE_FLAP` + `tools/A8CellAudit` are committed + ready. Do NOT retry +H1 (PVS grounding) or H2 (`PortalSide` side-test) — both evidence-disproven. + **Currently working toward: M1.5 — Indoor world feels right** (resumed from 2026-05-20 baseline after Phase O ship). **A6.P1 + A6.P2 + A6.P3 slice 1 SHIPPED 2026-05-21.** **A6.P3 slice 2 v2 SHIPPED 2026-05-22** diff --git a/docs/ISSUES.md b/docs/ISSUES.md index 58b6485..b567624 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -348,6 +348,16 @@ terrain mesh visible over the stair geometry. references, do-not-retry list, and pickup prompt for the investigation session. +**2026-05-31 update (post-U.4c-flap-fix):** the U.4c flap fix (`0ee328a`, root +indoor visibility at the player's cell) made this MORE visible — terrain now +draws inside again (it was Skipped during the flap), so the "floor shows outdoor +ground / cellar floor transparent / see the world from below" symptom is now +prominent. Confirmed at visual gate. Fix direction unchanged: gate outdoor +terrain by indoor-cell visibility (port retail `CEnvCell::find_visible_child_cell` +`acclient_2013_pseudo_c.txt:311397` + `seen_outside` landscape-keep). See +[`docs/research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md`](research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md) +(residual 1). + --- ## #79 — Indoor lighting: spurious spot lights on walls @@ -3612,6 +3622,28 @@ Unverified. The likely culprits, ranked by suspected probability: # Recently closed +## Phase U.4c doorway "flap" — [DONE 2026-05-31 · 0ee328a] indoor visibility rooted at the camera eye + +**Status:** DONE (Phase U.4c flap sub-step) +**Closed:** 2026-05-31 +**Commits:** `0ee328a` (fix) + `13d58ca`/`b5f2bf2`/`8941d1e` (characterization) +**Component:** rendering, visibility + +**Resolution:** Crossing a doorway, terrain + building shells + cell shells flapped off +(grey void + floating entities). Root cause (converged on a live `ACDREAM_PROBE_FLAP` +capture, after disproving a side-test/`PortalSide` hypothesis and a PVS-grounding +hypothesis): indoor portal visibility was rooted at the 3rd-person camera **eye**, which +drifts out of the player's cell; `FindCameraCell` then returned a **stale cell for its 3 +grace frames**, and from that stale root the doorway portal was culled as "behind" the eye +→ the exit cell + terrain dropped. Fix: root indoor visibility (cell resolution + portal- +side test) at the **player's cell** (retail `CellManager::ChangePosition` tracks `curr_cell` +by the player; acdream already roots lighting at the player). Eye still drives projection. +Visual-verified "flap gone." **Residuals are NOT the flap** — see #78 (terrain not gated +inside, now more visible) + a new camera-collision need (the chase eye is outside the +player's cell ~79% of frames → eye-projected clip over-includes → transparent outer walls) ++ U.5 (outside-looking-in). Full record: +[`docs/research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md`](research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md). + ## #100 — [DONE 2026-05-25 · f48c74aa + a64e6f2] Transparent rectangular patches around every house (terrain rendering) **Status:** DONE diff --git a/docs/research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md b/docs/research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md new file mode 100644 index 0000000..90c9150 --- /dev/null +++ b/docs/research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md @@ -0,0 +1,123 @@ +# Phase U.4c — flap FIXED (root visibility at the player's cell) + residuals handoff (2026-05-31) + +## TL;DR + +The **U.4c doorway "flap" is fixed.** Root cause (converged on live evidence, after two wrong +turns): indoor portal visibility was rooted at the **3rd-person camera EYE**, which drifts out of +the player's cell (through interior walls into AABB gaps); `FindCameraCell` then returned a **stale +cell for 3 grace frames**, and from that stale root the doorway portal was culled as "behind" the +eye → the exit cell + terrain + building shells all dropped → grey-void collapse. **Fix +(`0ee328a`):** root indoor visibility (cell resolution + portal-side test) at the **PLAYER's cell** +(retail `CellManager::ChangePosition` tracks `curr_cell` by the player; acdream already roots +lighting at the player for the same chase-cam reason). The eye still drives the per-frame projection. + +Visual gate (2026-05-31): the user confirmed **"flap seems gone."** But the gate also revealed the +indoor pipeline is **not yet seamless** — three **separate, largely-known** residuals remain (terrain +not gated inside #78, camera-displacement / camera-collision, U.5). Those are a **broader new scope** +than the flap; user chose to **checkpoint + hand off**. M1.5 "indoor world feels right" needs them. + +## The fix that shipped (`0ee328a`) + +`GameWindow.OnRender`: introduce `visRootPos = (_playerMode && _playerController is not null) ? +_playerController.Position : camPos`, and feed it to BOTH `_cellVisibility.ComputeVisibility(...)` +and `PortalVisibilityBuilder.Build(clipRoot, visRootPos, …)`. The camera eye (`camPos` / +`envCellViewProj`) still drives the per-frame projection and `_envCellRenderer.PrepareRenderBatches` +frustum/render cull. Removed the earlier synthetic builder flap test (it modeled the disproven +side-test hypothesis; the fix is integration-level). App tests 151/151. Two-stage Opus review: clean +(no Critical/Important; downstream-consumer audit — sky/weather/fog/sun/entity-cull/cache — all +internally consistent under player-rooting; `cameraInsideCell` is now a harmless misnomer → +cosmetic rename suggested as a follow-up). + +## The hypothesis journey (DO NOT re-walk these — all evidence-disproven) + +- **H1 (PVS / stab_list grounding)** — the spec's leading hypothesis. The live evidence showed the + flap is a *root* problem, not a *set-membership* problem; force-keeping cells would diverge from + retail's walk-reached `cell_draw_list`. The Layer-1 data (`LoadedCell.VisibleCells` + `SeenOutside`, + `639f20f`) was plumbed and is harmless/available but is NOT what fixed the flap. +- **H2 (port the dat `PortalSide` into the side test)** — I pivoted here on a raw 0/1 anti-correlation + in `A8CellAudit`. **DISPROVEN** (`b5f2bf2`): under the `(Flags&2)==0` boolean convention + our normal + winding, the dat `PortalSide` sense is **byte-identical** to our centroid `InsideSide` at every pose + — the swap is a literal no-op. The implementer subagent caught this via the real-data validation + loop and refused to ship the no-op. +- **"eye crosses the plane while inside the cell"** — **REFUTED** (`8941d1e`): `0171`'s local AABB is + y∈[-7.65,1.15]; the `0171→0170` portal plane is at y=-7.65 (the cell's *min* boundary), so an eye + genuinely inside `0171` always has side-test D≤0 → always traverses. The eye must be *outside* the + cell for the cull — i.e. a ROOT problem (grace-stale), confirmed by the moving capture. + +The decisive apparatus was `ACDREAM_PROBE_FLAP` (per-frame `[flap]`/`[flap-cam]` lines): flap frames +were uniformly `res=Grace eyeInRoot=n terrain=Skip`; good frames `eyeInRoot=Y`. See +`docs/research/2026-05-31-u4c-flap-characterization.md` (top banner = the converged reading). + +## Residuals revealed at the visual gate (the NEXT work — NOT the flap) + +User observations (inside a Holtburg cottage, this session's cells `0xA9B40162/0174/0175`) mapped to cause: + +1. **"Floor shows outdoor ground / cellar floor transparent / I see the world from below."** + → **Issue #78 family** (already known; CLAUDE.md flags it: *"outdoor terrain mesh visible inside + cottage cellars … indoor-cell visibility culling not gating outdoor terrain"*). Terrain isn't + occluded by the interior. The flap fix made it MORE visible because terrain now draws again (it + was Skipped during the flap). **Fix direction:** gate outdoor terrain by indoor-cell visibility + when the camera/player is in a cell — port retail `CEnvCell::find_visible_child_cell` + (`acclient_2013_pseudo_c.txt:311397`) / the `seen_outside` landscape-keep logic; relate #78, #100 + secondary finding. + +2. **"Outer walls transparent when looking out."** → the per-frame clip is projected from the + **displaced eye** (outside the player's cell **79%** of frames: 3049 `eyeInRoot=n` vs 795 `=Y`). + The OutsideView over-includes (scissor AABB fallback fired 320×; portals project far off-screen + e.g. `ndc=(-9.8,0.7)(-9.4,-10.5)`) → terrain bleeds past the window opening. **Fix direction:** + camera collision — retail `SmartBox::update_viewer` keeps the viewer inside the cell so the clip + stays consistent (`eyeInRoot` ≈ always Y). Reopens the parked camera scope. + +3. **"On the stairs: everything grey, I see doors/NPCs/particles from all around (other houses')."** + → transition-zone cell resolution on the stairwell (player straddling cells) + the displaced eye + seeing un-occluded entities. Same camera-displacement + terrain-gating family. (Stairs/cellar is + the #98-saga area — complex geometry.) + +4. **"Outside looking in: no interior walls."** → **U.5** (outdoor-camera → building-interior + peering), already deferred. + +**Net:** M1.5 "indoor world feels right" needs THREE more pieces beyond the flap — **#78 terrain +gating inside**, **camera collision (keep the eye in the player's cell)**, and **U.5**. The +camera-displacement root (residuals 2+3) is the highest-leverage: with the eye constrained to the +player's cell, the eye-projected clips become consistent and both 2 and much of 3 resolve. + +## Apparatus (kept — gated/inert when off; available for the residual work) + +- **`ACDREAM_PROBE_FLAP=1`** (`RenderingDiagnostics.ProbeFlapEnabled`) — per-frame `[flap]` (root, + eye, localEye, per-portal D/side/proj/clip/NDC, outPolys, vis) + `[flap-cam]` (res, eyeInRoot, + eye, player, terrain mode, outdoorVisible). `CellVisibility.LastCameraCellResolution` + + `CameraCellResolution` enum added. Per-frame (not cell-change-throttled) so it catches flicker at a + stable root. Throwaway — strip when the residual indoor work is done. +- **`tools/A8CellAudit/Program.cs` `portals` subcommand** — per-portal plane / centroid-`InsideSide` + / dat `PortalSide` / local AABB / swept-pose O-vs-A-vs-B sense comparison. The tool that disproved + H2. `PortalFlags.PortalSide = 0x2`, `ExactMatch = 0x1`. + +## Commit list (all on `claude/thirsty-goldberg-51bb9b`, UNPUSHED) + +``` +0ee328a fix(render): U.4c — root indoor visibility at the player's cell (THE FLAP FIX) +8941d1e research: refute eye-crosses-plane; correct stale H2 note (+ AABB dump) +b5f2bf2 research: DISPROVE the side-test fix (PortalSide port is a no-op) +13d58ca research: characterize the flap on real dat evidence ++ probe commits (ProbeFlapEnabled, NDC/clip probe), the spec (31f265d) + plan (211350b), + Layer-1 data plumbing (639f20f), the RED-apparatus (cd3ffe3, removed in 0ee328a). +``` +(Plus the converged-note update + this handoff.) + +## Git state +- Branch `claude/thirsty-goldberg-51bb9b`, **UNPUSHED** (push decision pending with the user). +- Two `git stash` entries preserved (#98/#101 WIP) — do NOT drop. + +## Next-session pickup prompt +``` +U.4c doorway flap is FIXED (commit 0ee328a — root indoor visibility at the player's cell, not the +camera eye; reviewed clean). READ docs/research/2026-05-31-u4c-flap-fixed-and-residuals-handoff.md +FIRST. The visual gate revealed three SEPARATE residuals (NOT the flap): (1) #78-family — outdoor +terrain not gated inside (floor shows ground / see world from below); (2) camera displacement — +the chase eye is outside the player's cell 79% of frames so the eye-projected clip over-includes +(transparent outer walls), fixed by camera collision (retail SmartBox::update_viewer keeping the +eye in the cell); (3) U.5 outside-looking-in (deferred). Highest leverage = camera collision (fixes +2 and much of 3). Apparatus ACDREAM_PROBE_FLAP + A8CellAudit are committed + ready. Brainstorm the +camera-collision-vs-terrain-gating ordering before coding. Do NOT re-try H1 (PVS grounding) or H2 +(PortalSide side-test) — both evidence-disproven (see the handoff). NO workarounds. +```