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.