acdream/docs/research/2026-08-30-cathedral-review-prompt.md

Cathedral rendering review — independent troubleshooting prompt

You are an independent reviewer investigating a persistent rendering defect in acdream (a modern C# .NET 10 Asheron's Call client; the code is modern, the behavior must be retail). This is a report-only investigation: read anything, run read-only commands (git log/diff/show, grep, dat inspection), but do NOT edit code, do NOT build, do NOT launch clients, and do NOT commit. Your single deliverable is a written report (the path is given at the end).

Where the code is

• Git worktree (the active campaign branch, work here): C:\Users\erikn\source\repos\acdream\.claude\worktrees\peaceful-blackburn-5333f0
• Branch: claude/campaign-w-retail-frame-walk
• HEAD at review time: bb9212c7 (FW4 slice 6)
• Baseline before ANY cathedral-specific fix: 37febd1f — the owner first reported this defect on a build of that commit. Six fix commits followed (see below). The owner's verdict: nothing has fixed anything.
• Main repository (for main-branch history): C:\Users\erikn\source\repos\acdream

The defect (owner-observed, on a live ACE server at 127.0.0.1:9000)

At the cathedral terrace, landblock 0xF418, standing in interior EnvCells 0xF4180104 / 0xF4180106 (owner teleloc: 0xF4180104 [31.9 57.3 169.8]):

1. Waterfall particles (the blue falls over the lake outside) render on top of terrain, water, and other content that should occlude them. Intermittent — toggles with which side of "the seam" (the terrace's interior/outdoor boundary) the CAMERA is on. Standing outdoors near the falls (0xF418000B, 0xF4180015) they look correct.
2. "Stalks" (dark monster-marker shapes near the lake-edge trees, server-spawned weenies, e.g. entities parented at 0xF418010D) leak over trees and scenery. This predates the current campaign.
3. NEW (after the sixth fix): the owner reports particles WITHIN the cathedral are also wrong (uncharacterized — treat as a regression candidate of the fix stack).
4. A previous session's analysis (owner-supplied) adds: the visible cathedral shell is assembled from multiple authored GfxObjs (0x01001FB2, 0x01001FB0, 0x01001FB3) + EnvCells + a portal graph; cell 0xF4180104 has exterior portals 0/1/2/4 and interior portal 3 → 0xF4180105; "if an incorrect depth or portal route prevents one wall's colour pass from drawing, the wall appears transparent even though its geometry and opaque texture are present."

The oracle fact that anchors everything: the RETAIL client connected to the SAME ACE server renders this scene perfectly. So a correct client-side mechanism exists; the task is to find what retail actually does for this scene and where our port diverges.

What you must do

1. Reconstruct retail's actual frame for this scene from the named decomp: docs/research/named-retail/acclient_2013_pseudo_c.txt (18,366 PDB-named functions; grep by class::method) and docs/research/named-retail/acclient.h. Key functions: SmartBox::RenderNormalMode @0x00453aa0, PView::DrawInside @0x005a5860, PView::DrawCells @0x005a4840 (landscape draw pc:432719, gated depth clear pc:432731-2, exit seals pc:432785-6), LScape::draw @0x00506330, RenderDeviceD3D::DrawBlock @0x005a17c0 (per-shadow-cell object draw pc:430056-430064), RenderDeviceD3D::DrawSortCell @0x0059f140, RenderDeviceD3D::DrawBuilding @0x0059f2a0, CPhysicsObj::ShouldDrawParticles @0x0050FE60, D3DPolyRender::FlushAlphaList @0x0059d2e0, PView::GetClip @0x005a4320, PView::InitCell @0x005a4b70. A Ghidra MCP HTTP server may be live at http://127.0.0.1:8081 (/decompile_function?address=0x...) serving the same 2013 build with PDB names — use it when grep is too noisy. Answer specifically: for an interior root whose cell has exit portals, (a) what exactly gets view-clipped vs view-culled vs drawn whole; (b) when does each content class (terrain, sky, building shells, EnvCell shells, cell-static objects + their emitters, dynamic objects + their emitters, unattached emitters, water) draw relative to the gated depth clear and the exit seals; (c) how does the ONE alpha list drain (which flush sites, what depth is in place at each); (d) what depth does the frame hold at the aperture and at the vista at final-drain time.

2. Read the cathedral's actual geometry from the installed DATs (%USERPROFILE%\Documents\Asheron's Call\, DatCollection is the in-tree reader; references/ACViewer is a rendering oracle): landblock 0xF418 — the LandblockInfo object list, the EnvCells 0x0100-0x0115-ish (esp. 0x0104/0x0105/0x0106), their portal polygons (which are exits, flag 0x4 → other_cell 0xFFFF), their stab lists (the falls objects: local static ids 0x4F418012-15 were observed as the falls' particle owners; setup/gfx ids of waterfall objects), and where the water surface geometry lives. Establish: are the falls objects EnvCell stabs, landblock objects, or both? What shape/extent are the exit portal polygons vs the real visible opening (the prior campaign claims they are thin "seam bands")?

3. Audit our implementation against that reconstruction, at BOTH 37febd1f (baseline) and bb9212c7 (HEAD). The relevant code: src/AcDream.App/Rendering/Walk/ (RetailFrameWalk, WalkPView, WalkFrameDriver, WalkViews, WalkScreenClip, WalkProductionWorldData), src/AcDream.App/Rendering/RetailPViewRenderer.cs, RetailPViewPassExecutor*.cs, ClipFrameAssembler.cs, ClipPlaneSet.cs, ParticleRenderer.cs, RetailAlphaQueue.cs, PortalVisibilityBuilder.cs (the legacy visibility layer FW4 is deleting), Scene/RenderScenePViewFrameProduct.cs.

4. Judge the six fix commits individually — each claims a retail citation; decide keep / revert / wrong-mechanism for each:

   • 37febd1f FW4 slice 1 — interior outside-view slices from the walk (was: old PortalVisibilityBuilder slices; also fixed punch-fan index aliasing).
   • c40aecfc slice 2 — exit seals stamp the walk's own flood.
   • 5f7ccdea slice 3 — outside-stage predicate reads the walk flood.
   • f3a03efc slice 4 — exit-plane straddler DYNAMICS' particles emit pre-clear once (was: deliberately last-pass).
   • 0d6cd5c0 slice 5 — straddling CELL-STATIC particles emit pre-clear (retail shadow-cell rule claim).
   • bb9212c7 slice 6 — interior roots draw terrain+sky UNCLIPPED (view-culled only), one terrain turn (was: per-exit-view scissor+clip slices). Evidence from the live probes is in %LOCALAPPDATA%\Temp\fw3-*.log and %LOCALAPPDATA%\Temp\fw4-*.log ([walk-root], [walk-part], [walk-alpha], [walk-dyn], [walk-portal], [walk-emit] lines; the probe is ACDREAM_PROBE_WALK_ROOT, documented in docs/launch-options.md).

5. Explain why the symptom survived all six fixes, and produce a concrete, mechanism-first fix plan (what to change, where, what retail evidence pins it, and what a falsifiable test/probe for it looks like BEFORE any code is written).

Required background reading (in this order)

1. claude-memory/project_pview_visibility_campaign.md (the #456 campaign memory — the proven mechanism model, the do-not-retry list; note: claude-memory/ is a junction in the MAIN repo root at C:\Users\erikn\source\repos\acdream\claude-memory\; the same files are at C:\Users\erikn\.claude\projects\C--Users-erikn-source-repos-acdream\memory\)
2. docs/plans/2026-08-30-campaign-fw-frame-walk.md (the active campaign plan — stages FW0-FW6, the FW1 conformance status, the FW4 slice log)
3. claude-memory/project_render_pipeline_digest.md (render SSOT + DO-NOT-RETRY table)
4. docs/research/2026-08-30-fw-walk-oracle/ (the ten retail cdb traces the walk is conformance-tested against)
5. docs/plans/2026-08-30-pview-visibility-campaign.md (the abandoned PView campaign — what was tried and refuted)

Hard rules

• The decomp is ground truth; ACE/ACViewer/WorldBuilder are interpretation aids. Where sources disagree, the decomp wins.
• Do not propose workarounds (suppression flags, grace periods, symptom-site early-outs). Root mechanisms only.
• Respect the do-not-retry lists in the memory docs (e.g., depth stamps as "retail's mechanism" is decomp-refuted; the panels are portal polys, not inert decoration).
• Every claim in your report needs a citation: a decomp address, a DAT field, a file:line in our tree, a probe-log line, or a commit SHA.
• If you cannot verify a claim, say so explicitly — an honest "unverified" beats a plausible guess. This investigation has already burned six fix rounds on plausible guesses.

Deliverable

Write your full report to: docs/research/2026-08-30-cathedral-review-<YOURNAME>.md (replace <YOURNAME> with your model name, e.g. fable, opus, external). Structure: Executive verdict (≤10 lines) → Retail frame reconstruction → DAT geometry findings → Divergence table (ranked) → Per-commit verdicts → Why the symptom survived → Recommended fix plan → Open questions. Length: as long as it needs to be; completeness beats brevity.