acdream/docs/research/2026-06-02-render-cell-membership-evidence.md

Render Cell-Membership — evidence model (2026-06-02)

Canonical "why" for the Unified Cell Graph (CObjCell) pivot. This is the pixel-grounded investigation that ended the week-long indoor-render saga. Companion design spec: docs/superpowers/specs/2026-06-02-unified-cell-graph-stage1-design.md. Predecessors: docs/research/2026-05-31-render-architecture-reset-handoff.md, docs/research/2026-06-01-render-reset-session2-handoff.md.

0. One-line conclusion

The render pipeline maintains its own indoor-cell system (CellVisibility + PortalVisibilityBuilder + 3 gates) that is separate from, and out of sync with, physics cell tracking. When the render side's answer is "outdoor/null" — which happens on spawn-in, on within-building flicker, and on building entry — terrain draws ungated and you see the world from below. Point-fixing any one gate cannot win because the visibility input is unreliable and disagrees with physics. The fix is to unify onto one cell membership all systems share (the retail CObjCell model), executed as a staged migration (see spec).

1. Symptom

Standing inside the Holtburg cottage (room or cellar) the interior does not seal: the full outdoor world (terrain hills, water, scenery) renders and the player appears to float in it ("world from below"). The exterior renders correctly.

2. Method

Live client against local ACE, four launches, character +Acdream. Existing baseline probes only — no code added (investigation was report-only): ACDREAM_PROBE_SHELL ([shell]), ACDREAM_PROBE_VIS ([vis]), ACDREAM_PROBE_FLAP ([flap]/[flap-cam]), ACDREAM_PROBE_ENVCELL, ACDREAM_PROBE_CELL ([cell-transit]). Screenshots via PowerShell CopyFromScreen on the AcDream.App window → PNG → read.

Gotcha (recorded so it isn't re-hit): Tee-Object writes the log as UTF-16LE. GNU grep (Bash) silently matches nothing on it; the ripgrep-based Grep tool and PowerShell Get-Content decode it correctly. Early "0 probes" Bash reads were false negatives — always read these logs with ripgrep/PowerShell.

3. Findings (per waypoint)

1. Exterior — correct. Opaque textured cottage walls, building sitting on dirt, no holes. No indoor probes fire (outdoor root). The outdoor case is sound and the migration must preserve it.
2. Room, entered from outside (run 1) — indoor path NEVER engaged. [vis]=[shell]=[envcells]=0. The "interior" we saw was the building-shell GfxObj + interior statics drawn by the outdoor entity pass; dark void where nothing covered. ⇒ outdoor→indoor building entry did not transit the player into the cell.
3. Cellar, walked in (run 1) — indoor path engaged but leaks. [vis] root=0xA9B40174 cells=3 ids=[0174,0175,0171] outside(polys=0,planes=0) — visibility computed correctly (windowless ⇒ empty OutsideView). [shell] shows all three shells render fine (gfx=1 tr=0 zh=0). [flap-cam] terrain=Skip outVisible=False — terrain decision is correct. Yet the screenshot is the full outdoor world.
4. First-person test (user-confirmed) — terrain shows even with the eye inside the cell. ⇒ the leak is not the 3rd-person camera; it's the gate/root.
5. Spawn directly into the cellar (run 3) — the cleanest proof. Only one [cell-transit] 0x0 → 0xA9B40174 reason=teleport. Physics knew the indoor cell instantly. Render fired zero [vis]/[shell] while standing still ⇒ world from below. ⇒ render and physics disagree: physics indoor, render outdoor.
6. Move from the cellar (run 3) — render re-engages on motion. [cell-transit] flickers 0174↔0175↔0171 (reason=resolver); [vis]/[shell] start firing. [vis] root=0xA9B40174 cells=1 vs root=0xA9B40175 cells=3 — the portal walk from 0174 reaches only itself (incomplete traversal); the root flickers, so the sealed set flickers 1↔3 and gaps show.
7. Room from the cellar side (run 3). The cottage interior is one connected EnvCell group: 0171(room/Z94) ↔ 0175(stairs/Z93) ↔ 0174(cellar/Z90); the cell flickers among the three while standing still. Render engaged (came up through the graph) yet still showed terrain at room level.

4. Causal model

• Terrain has exactly one draw path (_terrain.Draw, GameWindow.cs:7415/7420), both call sites behind the TerrainClipMode gate; no second terrain/water/skybox source exists (code-confirmed). So terrain can only appear when terrainClipMode != Skip, which happens when the render root resolves outdoor (clipRoot==null → the else branch at GameWindow.cs:7352 → default Planes → ungated terrain).
• Two independent cell resolvers. Render root = CellVisibility.ComputeVisibility (visRootPos) → FindCameraCell (AABB PointInCell, render-side registry). Physics = PhysicsEngine.ResolveCellId → PlayerMovementController.CellId (BSP-based, separate registry). They disagree.
• Render registration lags/misses. Render cells enter CellVisibility via _pendingCells → render-thread AddCell (GameWindow.cs:5749), a different lifecycle from physics' worker-thread CacheCellStruct. On spawn-in the render side has nothing registered yet ⇒ clipRoot==null ⇒ terrain.
• The [flap-cam] probe can't see the failure frames — it only logs inside if (clipRoot is not null). The null-root frames (where terrain draws) are invisible to it, which is why prior log-archaeology missed this.
• Two failure variants, one disease: building entry (outdoor→indoor) leaves you outdoor (finding 2); within-building the membership flickers and the portal walk is incomplete (findings 6–7). Both are "cell membership recomputed from geometry, unreliable, and disagreeing across systems."

5. Verdict → the pivot

Unify onto one cell membership every system shares — the retail CObjCell model (one curr_cell, GetVisible magnitude dispatch, portal graph). Scope decided with the user (2026-06-02): full migration across physics + collision + render + streaming, freeze lifted as needed, executed as a 5-stage chain that keeps the client runnable + visually verified at each step. Design: the companion Stage 1 spec.

6. Disproven / do-not-repeat (this session + predecessors)

• Camera/eye as the root cause (FP test: terrain shows with eye inside the cell).
• A second terrain renderer (code-confirmed there is none).
• "Render-gate consolidation only" as sufficient (the broken input is the membership, upstream of the gate).
• Earlier disproven: H1 PVS grounding, H2 PortalSide, cull mode, shell geometry/texture missing, zoom-confound, the screen-space stencil-mask rule (breaks outdoors), flag-based per-entity gate routing (= patchwork).

7. Grounding research (full reports archived in session transcript)

Two research agents produced the retail structure + acdream inventory that ground the design; their key facts are folded into the spec's "Retail grounding" and "acdream current state" sections with citations. Decomp anchors: CObjCell (acclient.h:30915), CEnvCell (:32072), CLandCell (:31886), CSortCell (:31880), CCellPortal (:32300), CBldPortal (:32094), CellStruct (:32275); GetVisible (pseudo_c:308209), change_cell (:281192), find_cell_list (:308742), ConstructView (:433750/:433827), InitCell (:432896), find_visible_child_cell (:311397).