acdream/docs/research/2026-06-02-acdream-render-pipeline-inventory-and-failures.md

acdream Render Pipeline — Inventory and Failure Map (2026-06-02)

Produced as a full redesign handoff after the Phase W session (Stage 3 + Stage 4 shipped, membership fix landed). Incorporates live probe evidence from the Holtburg cottage run captured the same session.

---

1. Per-frame draw order

All code lives in GameWindow.OnRender. Line numbers are from src/AcDream.App/Rendering/GameWindow.cs.

~7140  [visibility root]
        physicsRoot  = DataCache.CellGraph.CurrCell → TryGetCell → physicsRoot
        visibility   = _cellVisibility.ComputeVisibilityFromRoot(physicsRoot, visRootPos=PLAYER)
          → VisibilityResult { CameraCell, VisibleCellIds (old BFS set), HasExitPortalVisible }
        cameraInsideCell = visibility?.CameraCell != null
        rootSeenOutside  = physicsRoot?.SeenOutside ?? true

~7167  [compute render booleans]
        renderSky        = !cameraInsideCell || rootSeenOutside
        playerInsideCell = cameraInsideCell && !rootSeenOutside  (sealed dungeon)

~7250  [PrepareRenderBatches] — EnvCellRenderer
        _envCellRenderer.PrepareRenderBatches(envCellViewProj, camPos, filter:null, …)
        (CPU snapshot; builds per-cell batches. Always called. Cheap.)

~7290  [ClipFrame / PortalVisibilityBuilder]   ← THE AUTHORITATIVE VISIBILITY FRAME
        if clipRoot (indoor root):
            pvFrame  = PortalVisibilityBuilder.Build(clipRoot, visRootPos=PLAYER, envCellViewProj=EYE)
              → PortalVisibilityFrame { OutsideView, CellViews, OrderedVisibleCells }
            clipAssembly = ClipFrameAssembler.Assemble(_clipFrame, pvFrame)
              → TerrainClipMode { Skip | Scissor | Planes }
              → CellIdToSlot (per-visible-cell clip region)
              → OutdoorVisible / OutdoorSlot
              → HasOutsideView / OutsideViewNdcAabb
            _wbDrawDispatcher.SetClipRouting(CellIdToSlot, OutdoorSlot, OutdoorVisible)
            _envCellRenderer.SetClipRouting(CellIdToSlot)
            envCellShellFilter = HashSet<uint>(CellIdToSlot.Keys)
        else (outdoor root):
            _clipFrame.Reset() — no-clip, slot 0 for everything
            _wbDrawDispatcher.ClearClipRouting()

~7373  _clipFrame.UploadShared(_gl)  ← pushes TerrainUBO + RegionSsbo to GPU
       _wbDrawDispatcher.SetClipRegionSsbo(...)
       _envCellRenderer.SetClipRegionSsbo(...)
       _terrain.SetClipUbo(...)

~7378  [Stage 4] sky pre-scene (LScape — drawn FIRST through the doorway)
        drawSkyThisFrame = renderSky && (clipAssembly==null || clipAssembly.HasOutsideView)
        skyDoorwayClip   = clipAssembly!=null && clipAssembly.HasOutsideView
        if drawSkyThisFrame:
            BeginDoorwayScissor(skyDoorwayClip, OutsideViewNdcAabb)   ← clips to portal opening
            re-bind TerrainClipUBO at binding=2
            Enable ClipDistance0..7
            _skyRenderer.RenderSky(...)          ← sky mesh (gl_ClipDistance gated)
            Disable ClipDistance0..7
            _particleRenderer.Draw(SkyPreScene)  ← particles ONLY inside scissor; NO cell gate
            EndScissor

~7431  [pre-login guard] if IsLiveModeWaitingForLogin → goto SkipWorldGeometry

~7444  Enable ClipDistance0..7  ← world-geometry bracket opens

~7464  [terrain]
        if terrainClipMode == Skip    → nothing drawn
        elif terrainClipMode == Scissor → glScissor to OutsideView AABB → _terrain.Draw → disable
        else (Planes)                  → _terrain.Draw (UBO gated per-vertex)

~7523  [Stage 4] conditional doorway Z-clear
        if skyDoorwayClip:
            glScissor to OutsideViewNdcAabb
            glClear(DepthBufferBit)   ← depth only; color preserved
            EndScissor

~7538  [cell shells — opaque pass]
        if clipAssembly!=null && envCellShellFilter!=null:
            _envCellRenderer.Render(Opaque, envCellShellFilter)
              (per-cell geometry from PrepareRenderBatches; clip-gated via binding=3 slot map)

~7546  [entities]
        _wbDrawDispatcher.Draw(camera, LandblockEntries, frustum,
            visibleCellIds: visibility?.VisibleCellIds,   ← OLD BFS set, NOT pvFrame
            animatedEntityIds: animatedIds)
        Per-entity slot routing (SetClipRouting active = indoor root):
            serverGuid != 0 (live-dynamic) → slot 0 (unclipped)
            ParentCellId in CellIdToSlot   → cell's clip slot
            ParentCellId null              → OutdoorSlot or CULL (OutdoorVisible)
            ParentCellId not in CellIdToSlot → CULL
        IsShellScopedSet always returns false (U.1 deleted shell sets); so outdoor
        scenery (ParentCellId==null) routes to OutdoorSlot/CULL — BUT clip routing
        only fires for indoor root (SetClipRouting active). Outdoor root: ALL slot 0,
        nothing culled → outdoor scenery ALWAYS draws when outdoors.

~7553  [cell shells — transparent pass]
        if clipAssembly!=null && envCellShellFilter!=null:
            _envCellRenderer.Render(Transparent, envCellShellFilter)

~7561  Disable ClipDistance0..7  ← world-geometry bracket closes

~7568  [Scene particles]
        _particleRenderer.Draw(Scene)
        NO cell filter; no clip planes. All particles draw regardless of camera location.

~7583  [Stage 4] sky post-scene (weather / rain)
        if drawSkyThisFrame:
            BeginDoorwayScissor(skyDoorwayClip, OutsideViewNdcAabb)
            re-bind TerrainClipUBO
            Enable ClipDistance0..7
            _skyRenderer.RenderWeather(...)      ← rain cylinder clipped to doorway
            Disable ClipDistance0..7
            _particleRenderer.Draw(SkyPostScene) ← NO cell gate; scissor only
            EndScissor

~7739  SkipWorldGeometry: (pre-login goto target)

---

2. The gate table — the headline inconsistency

What is gated	Gate source	Computed by	Consistency verdict
Terrain	terrainClipMode + UBO planes	ClipFrameAssembler ← PortalVisibilityBuilder (pvFrame OutsideView)	CORRECT — skips when no exit portal visible. Planes-mode clips to portal opening per-vertex. Scissor-mode over-includes.
Cell shells	envCellShellFilter (CellIdToSlot.Keys) + per-instance clip slot (binding=3)	Same pvFrame / ClipFrameAssembler	CORRECT — only draws cells whose clip region is non-empty.
Indoor static entities (ParentCellId set)	CellIdToSlot lookup via ResolveSlotForFrame	Same pvFrame / ClipFrameAssembler	CORRECT for indoor statics. CULL when cell not visible.
Outdoor scenery / building shells (ParentCellId == null)	OutdoorVisible → OutdoorSlot or CULL	Same pvFrame / ClipFrameAssembler	GATED when _clipRoutingActive (indoor root only). Clips to OutsideView slot. BUT: IsShellScopedSet always returns false (shell sets deleted in U.1), so the IsBuildingShell anchor-cell branch in EntityPassesVisibleCellGate is dead code — the live path at line 1756 returns true unconditionally for null-ParentCellId when NOT clip-routing. See §3.
Live-dynamic entities (serverGuid != 0)	None — slot 0, always unclipped	N/A	INTENTIONAL — matches retail.
Particles (Scene / SkyPost / SkyPre)	Sky pre/post: doorway scissor only. Scene: NONE	N/A	BROKEN: no cell gate. Issue #104 (deferred).
Sky mesh	drawSkyThisFrame (seen_outside + HasOutsideView) + gl_ClipDistance against TerrainClipUBO	Same pvFrame	CORRECT — gated to portal opening or full-screen outdoors.

The core inconsistency (three gates, not one)

GATE #1 — Terrain:
    Computed from pvFrame.OutsideView (PortalVisibilityBuilder) → TerrainClipMode
    Skip ⇒ 0 terrain. Planes ⇒ clipped to portal. Scissor ⇒ AABB over-include.
    SOURCE: ClipFrameAssembler (~GameWindow.cs:7322)

GATE #2 — Cell shells:
    Computed from pvFrame.CellIdToSlot (same PortalVisibilityBuilder) → envCellShellFilter
    Only draws cells whose clip region is non-empty (correct, but incomplete seal).
    SOURCE: ClipFrameAssembler (~GameWindow.cs:7333)

GATE #3 — Entities (WbDrawDispatcher):
    Indoor statics: ParentCellId ∈ CellIdToSlot → correct.
    Outdoor stabs (ParentCellId == null):
        When _clipRoutingActive (indoor root): gated to OutdoorSlot or culled — looks correct.
        BUT: visibleCellIds passed to EntityPassesVisibleCellGate is from
             CellVisibility.ComputeVisibilityFromRoot → VisibilityResult.VisibleCellIds,
             which is the OLD BFS (GetVisibleCellsFromRoot). This is a SEPARATE computation
             from pvFrame. The two can agree, but they are NOT the same object.
    SOURCE: _cellVisibility.ComputeVisibilityFromRoot (~GameWindow.cs:7166)
            NOT from PortalVisibilityBuilder.

The duplication: CellVisibility.ComputeVisibilityFromRoot (old BFS, produces VisibilityResult.VisibleCellIds) and PortalVisibilityBuilder.Build (new pvFrame BFS) are TWO SEPARATE portal traversals per frame. The entity dispatcher consumes the old one via visibleCellIds; terrain + shells consume the new one via pvFrame. When they disagree, entities draw in cells whose shells are culled, or vice versa.

The structural gap (issue #78 root cause): outdoor scenery (ParentCellId == null: houses, trees, landblock-baked stabs) bypasses the entity gate entirely when NOT clip-routing (outdoor root). When clip-routing is active (indoor root), they route to OutdoorSlot/cull — BUT the IsShellScopedSet branch that would use BuildingShellAnchorCellId for building-shell culling is dead code (always returns false, line 1761). So building shells registered with IsBuildingShell=true but no BuildingShellAnchorCellId still pass. The result: some outdoor geometry leaks through the portal restriction.

Retail's design: one PView traversal (PView::ConstructView → ClipPortals → AddViewToPortals, retail decomp :433750). Every renderer consumes the SAME regions. There is no separate entity-visibility BFS.

---

3. Per-renderer notes

3.1 EnvCellRenderer (src/AcDream.App/Rendering/Wb/EnvCellRenderer.cs)

• What it does: draws indoor cell geometry (walls/floor/ceiling of EnvCells). WB port (WB EnvCellRenderManager.cs). Per-cell batches prepared by PrepareRenderBatches (~line 530), drawn in two passes (Opaque / Transparent) via Render(pass, filter) (~line 790).
• Clip mechanism: per-instance clip-slot buffer (binding=3, _clipSlotBuffer). Each instance stores its CellIdToSlot slot index. The shared clip-region SSBO (binding=2, ClipFrame.RegionSsbo) is handed in via SetClipRegionSsbo.
• Diagnostics:
  • ACDREAM_PROBE_SHELL=1 → [shell] line each opaque pass (~line 943). Reports per-cell: gfx=N (gfxObj count), tf=N (transform count), batch=N, idx=N (index count / 3 = tris), tr=N (translucent batches), zh=N (zero-handle = missing bindless texture). Diagnosis tree: NOSNAP = cell not in snapshot (no batches prepared); zh>0 = geometry present but texture handle zero (invisible); idx>0 + zh=0 + tr=0 = opaque geometry drawn, fault is depth/occlusion not the shell itself.
  • Session evidence: all visited cells (0170–0175) showed idx>0 + zh=0 + tr=0 + tr=0. Shells ARE drawn, textured, opaque. Max filter=3 cells rendered at once (correct for a 3-cell visibility set). ZERO NOSNAP.
• Known issue (U.4 fix): GL state (Blend, DepthMask, uViewProjection, CullMode cache) must be set self-contained at entry to each Render() call. Bugs were hit 3× in Phase U.4 when state bled from prior renderers. Fixed by explicit state setup at ~line 810 + 1010. CullMode.Landblock → CullMode.None override at line 1216 renders cell polys double-sided as a stopgap (architectural cause not yet resolved).

3.2 TerrainModernRenderer (src/AcDream.App/Rendering/TerrainModernRenderer.cs)

• What it does: draws all loaded landblock terrain via glMultiDrawElementsIndirect. Single global VBO/EBO, one slot per landblock (~line 26 onwards).
• Clip mechanism: TerrainClipUBO (binding=2, ClipFrame.TerrainUbo) handed in via SetClipUbo. When the UBO count > 0 (Planes mode), terrain_modern.vert clips per-vertex via gl_ClipDistance. When count==0 (outdoor root / Scissor mode), ungated.
• Gate in GameWindow: terrainClipMode (~line 7464):
  • Skip → no draw at all (correct for sealed cellar: OutsideView is empty).
  • Scissor → glScissor to TerrainScissorNdcAabb; UBO count 0 (no plane gating). This mode OVER-INCLUDES (everything in the scissor box draws, not just through the portal).
  • Planes → draws normally; UBO planes gate per-vertex.
• Known gap: Scissor-mode over-inclusion. When the OutsideView polygon exceeds the convex-plane budget, terrain is scissored to its NDC AABB rather than clipped to the actual portal shape. An unusually large or non-convex doorway can let terrain bleed.

3.3 WbDrawDispatcher (src/AcDream.App/Rendering/Wb/WbDrawDispatcher.cs)

• What it does: draws all world entities (static scenery, NPCs, doors, items) via glMultiDrawElementsIndirect. Per-instance clip slots (binding=3) + shared clip SSBO (binding=2).
• Entity gate: EntityPassesVisibleCellGate (static, line 1739):
  • visibleCellIds == null → pass (outdoor root: nothing culled).
  • ParentCellId set → pass iff cell ∈ visibleCellIds.
  • ParentCellId == null && IsBuildingShell && IsShellScopedSet → anchor-cell check. BUT IsShellScopedSet always returns false (line 1761, U.1 deletion). So this branch is dead.
  • ParentCellId == null && !(the above) → unconditionally returns true (line 1756). This is the outdoor-scenery bypass: houses, trees, landblock-baked stabs all pass when visibleCellIds is non-null but they have no ParentCellId.
• Clip-slot routing (when _clipRoutingActive, i.e. indoor root):
  • serverGuid != 0 → slot 0 (unclipped — retail behavior).
  • ParentCellId in CellIdToSlot → cell's clip slot.
  • ParentCellId == null && OutdoorVisible → OutdoorSlot (gated to OutsideView).
  • ParentCellId == null && !OutdoorVisible → CULL.
  • ParentCellId not in CellIdToSlot → CULL.
  • When NOT _clipRoutingActive (outdoor root): all slot 0, no culling.
• The gap: visibleCellIds passed by GameWindow is visibility?.VisibleCellIds (old CellVisibility BFS), not pvFrame.OrderedVisibleCells (new PortalVisibilityBuilder BFS). These are parallel traversals of the same graph; in practice they should agree for the simple cottage graph, but they can diverge for complex portal topologies.

3.4 CellVisibility (src/AcDream.App/Rendering/CellVisibility.cs)

• What it does: OLD portal visibility system. ComputeVisibilityFromRoot(root, pos) does a simple BFS through LoadedCell.Portals, collecting the full reachable set as VisibleResult.VisibleCellIds (HashSet). Sets CameraCell when inside a cell. Also produces HasExitPortalVisible (a portal with OtherCellId == 0xFFFF was reached).
• Used for: visibility?.VisibleCellIds → entity gate in WbDrawDispatcher.Draw. Also for cameraInsideCell, physicsRoot lookup.
• NOT used for: terrain gating, shell filter, clip-slot assignment. Those come from PortalVisibilityBuilder.
• Note: FindCameraCell AABB grace-frame fallback was DELETED in Stage 3 (2026-06-02). ComputeVisibilityFromRoot(null, …) returns null (outdoor root) — no AABB scan fallback.

3.5 PortalVisibilityBuilder (src/AcDream.App/Rendering/PortalVisibilityBuilder.cs)

• What it does: the NEW portal-clip visibility BFS (port of retail PView::ConstructView :433750). Produces PortalVisibilityFrame: per-cell CellView (screen-space NDC clip region), OutsideView (union of all exit-portal regions), OrderedVisibleCells (closest-first list).
• Used for: terrain clip mode, shell filter, entity clip slots (via ClipFrameAssembler).
• KEEP — this is the correct retail-faithful PView kernel. Output is correct (confirmed by [vis] probe: cellar 0174 shows outPolys=0 / terrain=Skip; room 0171 shows outPolys=1 / terrain=Planes).

3.6 ClipFrame / ClipFrameAssembler / ClipPlaneSet

• What it does: CPU → GPU bridge. ClipFrameAssembler.Assemble translates the PortalVisibilityFrame into a ClipFrameAssembly: per-cell plane arrays packed into a SSBO (RegionSsbo), a UBO for terrain (TerrainUbo), CellIdToSlot map, TerrainClipMode.
• KEEP — pure CPU logic, GL-free, fully unit-tested. The slot/gate policy is correct.

3.7 ParticleRenderer (src/AcDream.App/Rendering/ParticleRenderer.cs)

• What it does: draws particle emitters for all three passes (SkyPreScene, Scene, SkyPostScene). particle.vert has NO gl_ClipDistance support.
• Gating: SkyPreScene and SkyPostScene are bounded by the doorway scissor (BeginDoorwayScissor) when skyDoorwayClip is set. Scene pass: no gate at all — draws every particle regardless of camera location.
• Known gap: issue #104 (deferred). Inside a sealed cellar, Scene particles from the outdoor network-portal (e.g. Holtburg Town portal effect) are still drawn, visible through walls.

3.8 SkyRenderer (src/AcDream.App/Rendering/Sky/SkyRenderer.cs)

• What it does: sky mesh (celestial objects) + weather (rain cylinder). Uses sky.vert which writes gl_ClipDistance from the same binding=2 TerrainClipUBO.
• Gate: drawSkyThisFrame = renderSky && (clipAssembly==null || HasOutsideView). Indoor with no exit portal → no sky (seen_outside=false for dungeon; HasOutsideView=false for a room whose portal is around a corner). Indoor with visible portal → sky/weather clipped to doorway via gl_ClipDistance (Planes mode) or glScissor (Scissor mode).
• KEEP — Stage 4 correctly implements the retail LScape draw split.

---

4. Failure map — 5 user symptoms → root cause → gate

Probe context: [vis] probe confirms PVS is correct. [shell] probe confirms shells ARE drawn (idx>0, zh=0, tr=0). Player moves 0170→0171→0175→0174 correctly via [cell-transit].

Symptom 1: From outside through a door/window, interior walls are transparent

• Root cause: outside-looking-in (U.5) — when the camera is outdoors and the player is outdoors, clipRoot == null → outdoor root → _clipRoutingActive = false → every entity slot 0, terrain ungated, shells not drawn (shell rendering is only active when clipAssembly != null). EnvCell shells are NEVER rendered from the outdoor root. The indoor cells are not in the WbDrawDispatcher entity walk because they have ParentCellId set to cells that may not be in visibleCellIds (which is null outdoors).
• Gate: GATE #2 (shell rendering only active for indoor root). No outdoor → indoor visibility pipeline exists yet.
• Status: planned Phase U.5 / deferred by the render-reset mandate.

Symptom 2: Inside you see only the outdoor world + NPCs/particles/doors (no interior)

• Root cause (indoor root path): shells ARE drawn (probe confirmed). But outdoor terrain renders on top and clips through the shells because: (a) Terrain (Gate #1): in Planes mode, outdoor terrain is clipped to the portal-plane region, but since the cottage room has an exit portal, terrain draws THROUGH the doorway region. In Scissor mode it draws through the portal bounding box. The shells do not depth-occlude the terrain if terrain draws after the shells — but terrain draws BEFORE the shells (line 7464 vs 7538). So: terrain draws first, shells draw on top. This is correct draw order. The issue is that the terrain PLANE region covers the entire portal opening (the door/window), not just the area past the wall, so terrain pixels are written inside the room via the doorway. (b) Outdoor stabs (Gate #3, line 1756): ParentCellId==null entities bypass visibleCellIds, always pass the EntityPassesVisibleCellGate. When _clipRoutingActive, they route to OutdoorSlot (clipped to OutsideView) or are culled when !OutdoorVisible. For a cellar with seen_outside=true but sealed walls (OutsideView present), the stabs are clipped to the OutsideView AABB — but an AABB is a rectangle, not the actual doorway silhouette, so stabs visible in the same NDC box as the doorway still draw.
• Gate: GATE #1 (terrain) leaks through the portal opening; GATE #3 (entity) allows outdoor stabs to render through any pixel in the OutsideView bounding box.

Symptom 3: Looking out from inside, you see houses/trees through the ground

• Root cause: same as Symptom 2 from the other direction — outdoor stabs have ParentCellId==null → unconditionally pass EntityPassesVisibleCellGate (line 1756). When inside, clip routing is active and they route to OutdoorSlot. If OutdoorVisible is true (there IS an exit portal), they clip to the OutsideView AABB — but the AABB over-includes relative to the actual portal polygon. If OutdoorVisible is false (cellar with no direct exit portal in view) they should be culled — and the [vis] probe shows terrain=Skip for the sealed cellar, meaning this is correct for terrain. But stabs still leak through because clip-slot routing uses outdoorSlot (which points to the OutsideView region, computed per frame), not a true exclusion.
• The deeper gap: even when OutdoorVisible=false (terrain Skip), the ClipSlotCull sentinel at line 399 (return outdoorVisible ? outdoorSlot : ClipSlotCull) should cull outdoor stabs. Let's verify this is actually reaching that code: ResolveSlotForFrame (line 414) gates on _clipRoutingActive. When active and OutdoorVisible=false, ResolveEntitySlot returns ClipSlotCull → culled=true → entity dropped. This is CORRECT in theory. But the symptom persists, suggesting either: (a) _clipRoutingActive is not set on frames where the symptom shows (possible race between PrepareRenderBatches and Render), or (b) some outdoor stabs have serverGuid != 0 (live-dynamic) and thus take the slot-0 / always-unclipped branch.
• Gate: GATE #3 (entity). The theory says it should work for dat-hydrated stabs when OutdoorVisible=false; if the symptom still appears from the cellar, (b) is likely.

Symptom 4: On the cellar stairs, walls show but floor is grey and entities show through walls above

• Root cause (grey floor): terrain is rendering. For cell 0175 (stairs), seen_outside=true → terrain draws. The stairs cell has an exit portal chain, so OutsideView is non-empty, terrain=Planes. Terrain at the landblock Z level renders through the portal-plane region. The stair geometry is at a higher Z than the terrain; the terrain wins depth for some pixels → grey floor (terrain texture visible through the stair floor polygon).
• Root cause (entities through walls above): live-dynamic entities (serverGuid != 0) take slot 0 (unclipped) unconditionally (line 391: if (serverGuid != 0) return 0). This matches retail intent, but means NPCs / doors visible through walls above the stairs are working as designed — they are depth-tested only, not portal-clipped.
• Gate: terrain GATE #1 (Planes clip is correct in theory but terrain at ground level is visible through a downward-looking portal); entity unclipped slot for live-dynamics.

Symptom 5: In the cellar you see grey world instead of the floor

• Root cause (confirmed by [vis] probe): cellar 0174 shows outPolys=0 / terrain=Skip. The cellar IS correctly sealed — terrain does NOT draw for the cellar frame (Skip mode). The grey is NOT outdoor terrain. It is the GL clear color (background) showing through because: (a) The cell shell DOES draw ([shell] probe: 0174 idx=42, 14 triangles, opaque, zh=0). But the FLOOR polygon of the cellar GfxObj may not be present in the dat's polygon list (the cellar has no floor polygon — only walls). The floor visual is a separate landblock terrain tile at the cellar depth, normally occluded by the terrain mesh. With terrain SKIPPED (correct!), nothing draws at that Z level — the clear color shows through. (b) Alternatively, the floor is present but the GfxObj has CullMode.Landblock remapped to CullMode.None (EnvCellRenderer line 1216). If the floor polygon's normal points up, it still draws. If the floor is missing from the dat, nothing closes the bottom.
• This is a geometry/dat gap, not a gating bug — the cellar cell may simply not have a floor polygon in the EnvCell dat, expecting the terrain to serve as the floor (retail gets away with this because the terrain is never skipped in retail for a seen_outside=true cell with an exit portal reachable — retail draws terrain for every cell it visits in the PView walk, not just when an OutsideView exists). The Skip mode (correct for a SEALED dungeon with no exit portal) is too aggressive for a seen_outside=true cellar where the exit portal is simply behind you / not in the current frustum.
• Gate: GATE #1 (terrain). Skip fires when OutsideView.IsNothingVisible — this is correct for a dungeon, but for a seen_outside=true building interior it fires whenever the exit portal is behind the camera, which removes the terrain floor.

---

5. REUSABLE vs REDESIGN inventory

KEEP (correct, retail-faithful, well-tested)

Component	What to keep	Why
PortalVisibilityBuilder	Entire file	Correct PView BFS port. Probe-confirmed: OutsideView polygons, ordered cells, exit-portal detection all correct.
ClipFrame / ClipPlaneSet	Entire files	GL-free, unit-tested. The slot/gate policy and SSBO layout are correct.
ClipFrameAssembler	Entire file + tests	Correct translation of pvFrame → GPU slots. TerrainClipMode.Skip = correct for sealed dungeon.
LoadedCell.SeenOutside	Field + hydration	Correct retail anchor (acclient.h seen_outside). Stage 3 uses it correctly for sky/sun gate.
Doorway Z-clear (Stage 4)	GameWindow ~7523	Correct retail port of PView::DrawCells:432731.
Sky clip to OutsideView (Stage 4)	SkyRenderer path	Correct retail LScape split. gl_ClipDistance gating works.
CellVisibility.ComputeVisibilityFromRoot	Root-selection logic only	The physics-membership root selection is correct (Stage 3 fix). The BFS body can be retired once entity dispatch reads from pvFrame directly.
EnvCellRenderer	Geometry/texture/MDI path	[shell] probe confirms correct geometry, textures, depth, state. Keep the renderer; redesign the gating.
TerrainModernRenderer	Renderer itself	Works correctly. Just needs its caller to supply the correct clip mode.
WbDrawDispatcher slot-routing	ResolveEntitySlot logic (lines 381–400)	The policy is retail-faithful for indoor statics + live-dynamics. The gap is the outdoor-stab bypass, fixable without redesigning the dispatcher.
All diagnostic probes	ACDREAM_PROBE_SHELL, PROBE_VIS, PROBE_FLAP, PROBE_CELL, PROBE_SWEPT	Essential apparatus. Keep until the pipeline redesign is visual-verified.

REDESIGN / FIX

Component	Problem	Fix direction
WbDrawDispatcher.EntityPassesVisibleCellGate line 1756	ParentCellId==null returns true unconditionally (outdoor stab bypass).	When _clipRoutingActive AND !OutdoorVisible: return false. The ResolveSlotForFrame path already culls via ClipSlotCull for the clip-slot mechanism — verify that path is actually reached and the IsBuildingShell anchor branch fires for shells.
WbDrawDispatcher.Draw visibleCellIds parameter	Sourced from CellVisibility old BFS, not from pvFrame. Two separate traversals per frame.	Retire VisibilityResult.VisibleCellIds as the entity gate; use pvFrame.OrderedVisibleCells (same data, one traversal).
CellVisibility.GetVisibleCellsFromRoot BFS	Duplicate of PortalVisibilityBuilder's BFS (minus clip regions). Called once per frame alongside pvFrame.	Retain only CameraCell derivation (needed for clipRoot); discard the VisibleCellIds set.
TerrainClipMode.Skip trigger	Fires when OutsideView.IsNothingVisible — correct for dungeon, but fires for a seen_outside=true building interior when the exit portal is behind the camera. Removes the terrain floor for the cellar case.	Gate terrain-skip on !physicsRoot?.SeenOutside (i.e. Skip ONLY for dungeons where seen_outside=false). When seen_outside=true, always draw terrain at least at clip-mode Planes/Scissor.
ParticleRenderer.Draw(Scene)	No cell filter; no clip planes. Particles draw everywhere.	Add an indoor gate: when clipAssembly != null (indoor root), scissor Scene particles to OutsideView AABB. Full clip-slot support for particles is a larger change (particles have no instanceID).
EnvCellRenderer CullMode.Landblock → None override (line 1216)	Architectural stopgap — renders cell polys double-sided. The real winding issue hasn't been resolved.	Investigate whether AC's EnvCell geometry has consistent winding (retail uses backface cull). If winding is consistent, remove override and set CullMode per polygon's winding from the dat.
Outside-looking-in (U.5)	No pipeline for outdoor-camera → indoor-cell visibility. Shell rendering is only active for indoor root.	Phase U.5: add outdoor shell pass when CellVisibility detects a nearby building cell in the frustum.

---

6. The diagnostic apparatus

Probes: env vars and what they emit

Env var	C# property	Emission site	Line format	When to use
ACDREAM_PROBE_CELL=1	PhysicsDiagnostics.ProbeCellEnabled	PlayerMovementController.cs:776	[cell-transit] old=0x... new=0x... pos=(x,y,z) reason=...	Confirm cell membership changes. Low volume (fires only on transitions).
ACDREAM_PROBE_VIS=1	RenderingDiagnostics.ProbeVisibilityEnabled	GameWindow.cs:7338	[vis] root=0x... cells=[...] outPolys=N outPlanes=N per-cell:{0x...:N,...}	Confirm PVS output. Cell-change-throttled to stay readable.
ACDREAM_PROBE_FLAP=1	RenderingDiagnostics.ProbeFlapEnabled	GameWindow.cs:7352, PortalVisibilityBuilder.cs:235	[flap-cam] root=0x... res=None eyeInRoot=Y/n eye=... terrain=... outVisible=...	Check whether terrain/portals flap. High volume; use briefly.
ACDREAM_PROBE_SHELL=1	RenderingDiagnostics.ProbeShellEnabled	EnvCellRenderer.cs:950	[shell] filter=N drawCalls=N inst=N tris=N [0xCELLID:gfx=N tf=N batch=N idx=N tr=N zh=N]	Confirm cell shells are drawn per frame. Opaque pass only.
ACDREAM_PROBE_SWEPT=1	PhysicsDiagnostics.ProbeSweptEnabled	PhysicsEngine.cs:861	[swept-sphere] ...	Physics swept-sphere diagnostics (not render).
ACDREAM_PROBE_PUSH_BACK=1	PhysicsDiagnostics.ProbePushBackEnabled	BSPQuery.cs	[push-back], [push-back-disp], [push-back-cell]	A6 apparatus; heavy under motion.
ACDREAM_PROBE_FLAP=1 (builder)	same	PortalVisibilityBuilder.cs:235	[flap] camCell=0x... portals=N TRV/SKIP entries...	Portal traversal trace per frame. Heavy.

Runtime-toggleable via DebugPanel (F11 → Diagnostics checkboxes) without relaunch for PROBE_CELL and PROBE_VIS.

Reading logs on Windows (launch.log is UTF-16 LE from PowerShell Tee-Object)

Do NOT use GNU grep on launch.log — it interprets UTF-16 as binary.

Correct approach (PowerShell):

# Filter [shell] lines
Select-String -Path launch.log -Pattern '^\[shell\]' | Select-Object -ExpandProperty Line

# Filter [vis] lines
Select-String -Path launch.log -Pattern '^\[vis\]' | Select-Object -ExpandProperty Line

# Filter [cell-transit] lines
Select-String -Path launch.log -Pattern '^\[cell-transit\]' | Select-Object -ExpandProperty Line

Correct approach (ripgrep / Grep tool) — works with UTF-16 LE when -E flag is set:

rg --encoding utf-16-le '\[shell\]' launch.log
rg --encoding utf-16-le '\[vis\]' launch.log

If the log was tee'd with PowerShell's default Tee-Object (UTF-16 LE without -Encoding utf8), every other byte is NUL. Read the file with Get-Content launch.log | Select-String '\[shell\]' or force UTF-8 at launch time:

dotnet run ... 2>&1 | Tee-Object -FilePath launch.log -Encoding utf8

[shell] diagnosis tree

[shell] filter=N drawCalls=N inst=N tris=N [0xCELLID:...]
│
├── NOSNAP → cell not in PrepareRenderBatches snapshot
│     Cause: cell not yet loaded (streaming lag) OR PrepareRenderBatches filter excluded it.
│     Action: check streaming for the cell; verify PrepareRenderBatches is called with filter:null.
│
├── gfx=0 → cell present in snapshot but no GfxObj batches
│     Cause: EnvCell has no renderable geometry (possible for corridor/transition cells).
│     Action: inspect dat with DatReaderWriter dump; verify the cell has a non-empty
│             EnvironmentId → GfxObj polygon list.
│
├── idx=0 → gfxObj present but zero index count
│     Cause: GfxObj loaded but ObjectMeshManager returned 0-index batch.
│     Action: check mesh staging; PrepareMeshDataAsync may not have completed for this GfxObj.
│
├── zh>0 → batch present with zero bindless texture handle
│     Cause: texture not yet uploaded to TextureCache; GfxObj mesh arrived before texture decode.
│     Action: wait for texture upload; check for TextureCache errors in log.
│
└── idx>0 + zh=0 + tr=0 → OPAQUE GEOMETRY DRAWN — fault is elsewhere
      The shell is geometrically correct and textured. The problem is:
      (a) Terrain/outdoor stabs render in front and are not gated to the portal opening,
          or (b) outside-looking-in (U.5, no outdoor root shell pass).
      This is the confirmed state for the current session.

---

7. Summary

The current pipeline has PVS that is computationally correct but enforces visibility through three inconsistent gates:

1. Gate 1 (terrain): PortalVisibilityBuilder → ClipFrameAssembler → TerrainClipMode. Correct for sealed dungeons. Over-aggressive Skip for seen_outside=true buildings when portal is behind the camera.

2. Gate 2 (shells): same PortalVisibilityBuilder output → envCellShellFilter. Correct. Only active for indoor root.

3. Gate 3 (entities): parallel OLD CellVisibility BFS → VisibleCellIds (set membership), combined with PortalVisibilityBuilder-derived clip routing. The outdoor-stab bypass (ParentCellId==null → return true, line 1756) is the primary architectural gap.

Retail has one gate: PView. One traversal, one region per cell, every geometry type clipped to its portal-derived region. The fix is to make PortalVisibilityBuilder the sole source of truth for ALL geometry types and retire CellVisibility.VisibleCellIds as a rendering gate.

The [shell] probe evidence rules out: geometry missing, textures missing, wrong cull mode, blend/depth state errors. The shells ARE drawn correctly. The residual is purely that outdoor geometry is not gated to portal openings.