acdream/docs/research/2026-05-30-unified-render-pipeline-decision-and-handoff.md

# Unified retail-faithful render pipeline — decision, scope, and handoff (2026-05-30)

## TL;DR (the decision)

We are **abandoning the two-pipe (inside / outside) rendering approach** and
committing to a **single, unified, retail-faithful render pipeline** built around
retail's portal-visibility view (`PView`). Modern code, retail behavior. This is a
new roadmap phase — **Phase U (Unified Render Pipeline)** — and it is milestone-scale
work, not a patch.

**Why:** acdream inherited a *two-pipe* render structure from WorldBuilder (WB) — a
normal outdoor draw plus a separate flat `RenderInsideOut` stencil pass toggled on
`cameraInsideBuilding` (`GameWindow.cs` ~7345). That split is the root cause of every
indoor/outdoor seam bug (the "flap", missing/transparent walls, terrain bleeding into
interiors). **Retail has no such split.** Retail renders through one portal-visibility
traversal: starting from whatever cell the camera is in, it walks recursively through
portals (doors, windows, cell openings), builds a screen-space clip region per opening,
and draws every visible cell — indoor *and* outdoor — in one pass. There is no
"am I inside a building?" branch, so transitions are seamless **by construction**.

The A8.F effort tried to graft retail's recursive clip *on top of* WB's two-pipe
stencil (a CPU-built NDC mask bridging the two pipes). That hybrid is inherently
fragile and failed its visual gate (**issue #103**). You cannot make two pipes hand
off seamlessly at a doorway; retail avoids the entire bug class by never splitting.

This was confirmed in collaboration with the user, who correctly identified that the
whole direction was wrong: *"in retail there is totally seamless transitions between
out and in… it's like we are on the wrong path here."* Correct.

---

## What this session actually shipped (the salvage)

This session was originally a "camera collision" effort (a reframing of the #103
failure onto the camera eye — itself a detour). The camera work is **real,
retail-faithful, and kept**, but it is **not** the fix for seamless transitions:

- **Swept-sphere camera collision** (retail `SmartBox::update_viewer`, `0x00453ce0`):
  `CameraDiagnostics.CollideCamera` (default on), `ICameraCollisionProbe` +
  `PhysicsCameraCollisionProbe` (reuses `PhysicsEngine.ResolveWithTransition`,
  retail `viewer_sphere` 0.3 m, `init_object(player, 0x5c)` =
  `IsViewer|PathClipped|FreeRotate|PerfectClip`), wired into `RetailChaseCamera`
  (collide into a *separate* published eye — never the damped sought eye — to avoid
  the wall-press oscillation), `GameWindow` wiring + a Camera-menu toggle.
- **Physics fix (retail-faithful):** viewer/sight sweeps bypass acdream's 30-step
  safety cap in `Transition.FindTransitionalPosition` (retail `find_transitional_position`
  has no cap; `calc_num_steps` has a `state & 4` viewer branch). Gate: `&& !ObjectInfo.IsViewer`.
- Commits `69c7f8d` → `aae5300` (plus the design spec/plan docs).

**Camera-collision residual nits (minor, deferred — NOT blockers):**
- Eye can clip ~0.3 m into a wall and reveal outside (near-clip plane 1 m vs collision
  radius 0.3 m — tuning).
- Residual non-retail-smooth feel at walls (the gross oscillation is fixed; tuning remains).

These are polish; revisit after the pipeline lands (or never — they're cosmetic).

---

## Git state at handoff

- Branch `claude/strange-albattani-3fc83c` was **239 commits ahead of `main`**
  (both forked at Phase O, `2256006`, 2026-05-21). The branch carries ~9 days of good
  work since Phase O: A6 physics, issues #98/#100/#101, A7 lighting, the A8/A8.F
  rendering arc, and the camera work — all of it.
- Per user decision (2026-05-30): **the whole branch was merged into `main`** so none
  of that work is lost. The dormant, gated-off A8 two-pipe rendering rides along and is
  **deleted as Task 1 of Phase U** (see below). The user pushes `main` to remotes.
- The `#98`/`#101` physics WIP from a prior session is preserved in `git stash` on this
  branch (a subagent had `git stash apply`-ed it mid-session; it was re-stashed). Do not
  lose it.

---

## Phase U — Unified Render Pipeline (scope / design sketch)

> This is a scope sketch to start a proper brainstorm + spec from — **not** a finalized
> design. The next session brainstorms it.

### Goal

One render path. The camera's current cell is the root of a per-frame portal-visibility
traversal that yields *(visible cells, per-cell screen-space clip region)*; the renderer
draws all visible geometry (indoor cells, outdoor cells, entities, terrain) in a single
pass gated by that visibility. **No `cameraInsideBuilding` branch. No `RenderInsideOut`
stencil pass. No outdoor-vs-indoor toggle.** Seamless in/out by construction.

### Retail oracle (the thing to port)

- `PView::ConstructView` (decomp ~`433750`), `PView::ClipPortals` (~`433572`),
  `PView::GetClip` (~`432344`) — the recursive per-portal screen-space clip-region BFS.
- `CEnvCell::find_visible_child_cell` (`acclient_2013_pseudo_c.txt:311397`,
  `0x0052dc50`) — per-cell portal-visible-child resolution; call site `:280028`.
- `RenderDeviceD3D::DrawBlock` (~`430027`) — the render loop the visibility chain feeds.
- See the project memory note **indoor-portal-visibility-wb-vs-retail** for why WB
  cannot express per-portal clipping and the oracle is retail `PView`.

### What to KEEP (do not re-port)

- The WB-derived **mesh/dat pipeline** is fine and stays: `ObjectMeshManager`,
  `WbMeshAdapter`, `WbDrawDispatcher`, terrain (`TerrainModernRenderer`,
  `LandblockMesh`), `DatCollection`, texture decode. Phase U is about **visibility +
  draw orchestration**, not mesh extraction.
- The **camera collision** and **physics** work from this session.
- Cell data: `CellVisibility` (`FindCameraCell`, `PointInCell`, portal data),
  `PhysicsDataCache` cell structures.

### What is likely SALVAGEABLE from the failed A8.F (verify, don't assume)

The A8.F CPU clip-builder pieces are **unit-test-correct** (the integration is what
failed). They may feed a unified draw directly:
- `PortalProjection` (GL near-plane clip), `ScreenPolygonClip` (2D convex intersection),
  `ViewPolygon`/`CellView` (clip-region model), `PortalVisibilityBuilder` (recursive
  portal-clip BFS producing per-cell `OutsideView`).
The failure was the *two-pipe stencil graft* around them (the CPU NDC mask gating a
*separate* outdoor pipe), not the clip math. A unified pipeline can likely reuse the
builder to produce per-cell clip frames and gate **one** pass.

### What to DELETE (Task 1 — clear the deck)

The dead two-pipe rendering, so the unified path is built clean, not bolted on:
- `RenderInsideOutAcdream` and the `cameraInsideBuilding` branch in `GameWindow.cs`
  (~`7345`+), the `IndoorCellStencilPipeline` / `MarkAndPunchNdc` stencil graft, the
  Job-A/B decouple, the `ACDREAM_A8_INDOOR_BRANCH` kill-switch, the
  `EnvCellRenderer` WB `RenderInsideOut` port (`f9a644a` lineage).
- Keep `EnvCellRenderManager`'s *mesh* path if the unified draw needs it; delete only
  the inside-out *visibility/stencil* machinery.
- Audit before deleting: some A8 commits also fixed real bugs (e.g. `BuildingId`
  stamping, pool aliasing `9559726`) — keep those.

### Approach sketch (for the brainstorm to refine)

1. **Visibility pass** (CPU, GL-free, testable): from the camera cell, recursive portal
   BFS → ordered set of visible cells, each with a screen-space clip polygon (intersection
   of the portal openings along its chain). This is retail `PView::ConstructView`.
   Likely reuses the salvaged A8.F `PortalVisibilityBuilder` family.
2. **Draw pass** (single, unified): for each visible cell (front-to-back), draw its
   geometry + entities clipped to its clip region (scissor or stencil-per-cell, retail
   uses a clip rect/region). Outdoor cells are just cells in this set — no special path.
   Terrain is drawn per visible outdoor cell, gated the same way.
3. **No branch:** the camera being indoors vs outdoors changes only *which cell is the
   root*, not the algorithm.

### Key risks / lessons (do not repeat)

- **Do not graft retail recursion onto WB's flat two-pipe stencil** — that's what
  #103 was. Build the unified pass; don't bridge two pipes.
- **Unit tests on synthetic visibility data did not catch #103 — only the visual gate
  did.** Visual verification at the cottage/cellar/inn/dungeon is the real acceptance.
  Build a runtime visibility probe early (`ACDREAM_PROBE_VIS`) and validate against live
  frames, not just synthetic fixtures.
- **A CPU-built mask gating ALL outdoor geometry is fragile.** The unified pass should
  gate per-cell at draw time (scissor/stencil per visible cell), close to how retail
  clips, rather than one global mask.
- **The camera is not the fix.** That reframing cost this session; the fix is the
  visibility architecture.

### Success criteria (visual)

- Walk Holtburg cottage → cellar → out the door: no flap, walls solid, no terrain
  bleed, seamless threshold crossing from any camera angle/zoom.
- Holtburg Inn: no outdoor stabs/terrain visible through the floor/walls (closes #78).
- Dungeon via Town Network portal: `visibleCells` stays sane (~4–15), no other-dungeon
  geometry (closes/relates #95).
- No regression to outdoor rendering (the default game today).

---

## Next-session pickup prompt

```
We are building Phase U — a single unified retail-faithful render pipeline (retail
PView portal-visibility), abandoning the WB-inherited two-pipe (inside/outside) split
that caused the indoor seam bugs (the flap, missing/transparent walls, terrain bleed).
The decision + full scope is in
docs/research/2026-05-30-unified-render-pipeline-decision-and-handoff.md — READ IT FIRST,
then the project memory note "indoor-portal-visibility-wb-vs-retail" and the #103
failure handoff (docs/research/2026-05-29-a8f-visual-gate-failure-handoff.md).

State both altitudes:
  Currently working toward: M1.5 — Indoor world feels right.
  Current phase: U (Unified Render Pipeline). This supersedes the abandoned A8/A8.F
  two-pipe approach (#103).

Start with superpowers:brainstorming to design the unified pipeline (do NOT jump to
code). The scope sketch in the handoff doc is the input. Key decisions to settle in the
brainstorm: (a) reuse the salvaged A8.F clip-builder (PortalProjection/ScreenPolygonClip/
ViewPolygon/PortalVisibilityBuilder — unit-test-correct) vs fresh port; (b) per-cell
clip mechanism (scissor rect vs stencil-per-cell) matching retail's GetClip; (c) how
terrain + outdoor entities become "just cells" in the visible set.

Task 1 of implementation is to DELETE the dead two-pipe code (RenderInsideOutAcdream,
the cameraInsideBuilding branch, IndoorCellStencilPipeline/MarkAndPunchNdc, the
ACDREAM_A8_INDOOR_BRANCH kill-switch) to clear the deck — but audit first; some A8
commits fixed real bugs (BuildingId stamping, pool aliasing) that must be kept.

Retail anchors: PView::ConstructView ~433750, ClipPortals ~433572, GetClip ~432344,
CEnvCell::find_visible_child_cell :311397, RenderDeviceD3D::DrawBlock ~430027.

Keep: the WB mesh/dat pipeline (ObjectMeshManager/WbDrawDispatcher/terrain), the camera
collision + physics from the 2026-05-30 session. Visual verification at Holtburg
cottage/cellar/inn + a portal dungeon is the acceptance gate — unit tests did not catch
#103.

Preserve the git stash on the branch (#98/#101 physics WIP).
```

---

## Reference index

- Decision context / why WB can't do it: project memory **indoor-portal-visibility-wb-vs-retail**.
- #103 failure detail: `docs/research/2026-05-29-a8f-visual-gate-failure-handoff.md`.
- Camera-collision work this session: `docs/superpowers/specs/2026-05-29-a8f-camera-collision-design.md`,
  `docs/superpowers/plans/2026-05-29-a8f-camera-collision.md`.
- A8.F portal-frame port (the failed two-pipe graft):
  `docs/superpowers/specs/2026-05-29-phase-a8f-portal-frame-visibility-design.md`.
- Retail decomp: `docs/research/named-retail/acclient_2013_pseudo_c.txt`.
- WB visibility reference: `references/WorldBuilder/Chorizite.OpenGLSDLBackend/Lib/VisibilityManager.cs`.