acdream/docs/plans/2026-07-22-gamewindow-slice-7-render-frame-orchestration.md

# GameWindow Slice 7 — render-frame orchestration

**Status:** Active 2026-07-22.
**Parent program:** [`docs/architecture/code-structure.md`](../architecture/code-structure.md), Slice 7.
**Baseline:** `9512404e`; `GameWindow.cs` is 7,026 raw lines, 241 fields, and
108 methods. The Release suite passes 7,182 tests / 5 fixture or environment
skips. The 314-second lifecycle/reconnect gate and 394-second synchronized
nine-stop resource soak pass.
**Behavior rule:** This is an ownership extraction. Preserve every accepted
world/PView/alpha/private-viewport/UI draw edge, render-thread publication
edge, GL-state boundary, and GPU-flight failure contract. Do not combine the
extraction with a render-quality change, visibility correction, frame-order
port, or resource-lifetime redesign.

## Progress ledger

- [ ] A — freeze the complete render graph, correct the architecture SSOT, and
  introduce data-only frame contracts plus deterministic order/failure tests.
- [ ] B — extract paperdoll, panel-layout/devtools, and render-diagnostics leaf
  owners while `GameWindow` still orders the frame.
- [ ] C — extract frame-resource begin/upload/publication and live display,
  and weather/display foundations that do not depend on camera/root
  classification.
- [ ] D — extract frame-data classification and reusable world scratch without
  duplicating live identity, spatial, visibility, or resource ownership; then
  run the dependent audio, sky, lighting, and listener preparation.
- [ ] E — replace `RetailPViewDrawContext`'s callback bag with a typed
  `RetailPViewPassExecutor` and data-only inputs.
- [ ] F — extract `WorldSceneRenderer`, including both shared-alpha scopes,
  PView/fallback world branches, particles, debug world draw, and completion.
- [ ] G — compose `RenderFrameOrchestrator`, cut `GameWindow.OnRender` to one
  handoff, and delete obsolete frame bodies, fields, helpers, and callbacks.
- [ ] H — corrected-diff reviews, full Release suite, connected lifecycle and
  soak gates, framebuffer comparison, documentation, memory, and metrics.

Every checked checkpoint is one bisectable architectural commit. A checkpoint
does not complete while a new owner merely delegates a substantial body back to
`GameWindow`.

## 1. Outcome and non-goals

At slice exit, `GameWindow.OnRender` supplies one immutable delta/viewport input
to `RenderFrameOrchestrator`. The orchestrator owns the GPU-flight transaction
and composes focused frame-resource, world-scene, private-presentation, and
diagnostic phases. `GameWindow` remains the construction and shutdown shell; it
does not keep the draw graph, PView pass callbacks, frame scratch, paperdoll
assembly, or performance-title body.

The target ownership graph is:

```text
RenderFrameOrchestrator
  ├── RenderFrameResourceController      GPU slot + resource BeginFrame/upload
  ├── WorldRenderFrameBuilder            camera/root/light/classification facts
  ├── WorldSceneRenderer                 accepted world draw graph
  │     ├── RetailPViewRenderer           visibility/order owner
  │     ├── RetailPViewPassExecutor       concrete GL pass implementation
  │     └── WorldRenderDiagnostics        probes/debug counters/signatures
  ├── PrivatePresentationRenderer        portal + paperdoll + retained UI + ImGui
  │     ├── PaperdollFramePresenter
  │     └── DevToolsFramePresenter
  └── RenderFrameDiagnosticsController   title/resource/frame snapshots
```

Names may narrow as code lands, but the ownership boundaries do not collapse
into one replacement god object. No new owner may receive `GameWindow`, a broad
service locator, or an anonymous list of callbacks into the window.

This slice does **not** change:

- the viewer-cell render root or player-cell lighting root;
- synthetic outdoor-cell behavior or the null-root safety path;
- portal flood, building pre-gates, clip-plane/scissor limits, punch/seal
  depth behavior, shell lift, viewcone culling, or draw distances;
- shared-alpha sort keys, scope boundaries, blend/cull behavior, or immediate
  EnvCell/private alpha;
- weather, fog, point-light selection, particle visibility/range, terrain
  quality, FOV, frame pacing, or audio-listener formulas;
- portal-space, paperdoll, retained gameplay UI, ImGui, or screenshot visuals;
- resource ownership, shutdown/disposal order, or three-frame GPU retirement;
- TS-53's retained-UI time placement on the render seam.

Issue #225's translucent lifestone/particle comparison remains a separate user
visual gate. Passing this structural slice must not mark it resolved.

## 2. Retail oracle and accepted adaptations

This extraction reuses the existing named-retail research rather than
reinterpreting the draw algorithms:

- `SceneTool::BeginScene @ 0x0043DAD0` establishes the black scene-clear
  baseline used by portal CreatureMode replacement;
- `SmartBox::DrawNoBlit @ 0x00454C20` updates the viewer and invokes the normal
  world render before post-world selection work;
- `SmartBox::RenderNormalMode @ 0x00453AA0` owns landscape/inside dispatch and
  the final retail alpha flush;
- `RenderDeviceD3D::DrawInside @ 0x0059F0D0`,
  `PView::DrawInside @ 0x005A5860`, and
  `PView::ConstructView @ 0x005A57B0` own the portal traversal;
- `PView::DrawCells @ 0x005A4840` fixes the outside-landscape → alpha flush →
  conditional depth clear → exit masks → shells → object-list order;
- `LScape::draw @ 0x00506330`, `GameSky::Draw @ 0x00506FF0`,
  `DrawBuilding @ 0x0059F2A0`, `DrawBlock @ 0x005A17C0`, and
  `DrawObjCellForDummies @ 0x005A0760` constrain the landscape/building/cell
  phases;
- `AddMeshToAlphaList @ 0x0059C230` and
  `FlushAlphaList @ 0x0059D2E0` constrain alpha submission/flush boundaries;
- `CPhysicsPart::UpdateViewerDistance @ 0x0050E030` and
  `CShadowPart::insertion_sort @ 0x006B5130` constrain transformed DAT
  SortCenter/CYpt and stable far-to-near ordering;
- `CreatureMode::Render @ 0x004529D0` constrains portal and paperdoll private
  viewports;
- `SceneTool::EndFrame @ 0x0043FB30` proves retail gameplay UI precedes retail
  profiler/debug overlays; placing ImGui above gameplay UI is acdream's IA-12
  modern coexistence adaptation, not literal Keystone parity.

The readable pseudocode oracle is
[`docs/research/2026-06-05-retail-pview-indoor-render-pseudocode.md`](../research/2026-06-05-retail-pview-indoor-render-pseudocode.md),
with the current full reference in
[`docs/research/2026-06-02-retail-render-pipeline-full-reference.md`](../research/2026-06-02-retail-render-pipeline-full-reference.md).
Shared-alpha ordering is pinned separately by
[`docs/research/2026-07-18-retail-shared-alpha-list-pseudocode.md`](../research/2026-07-18-retail-shared-alpha-list-pseudocode.md).

This slice preserves, rather than retires, the registered modern adaptations:
IA-8/9/10/12/14/15; AD-16/17/19/24;
AP-21/32/33/34/35/85/92/115/116/117;
TS-6/7; and TS-53. Source pointers move with ownership in the same commit, but
mechanism/risk language changes only if behavior actually changes.

## 3. Frozen production render order

The complete accepted order is:

1. call `GpuFrameFlightController.BeginFrame` outside the render `try`;
2. begin the composite-texture frame and cache tick;
3. begin, in order, dispatcher, EnvCell, portal depth, world text, retained-UI
   text, clip, terrain, lighting UBO, then profiler frame state for the current
   GPU slot;
4. select the portal replacement viewport; reset particle visibility when it
   is active;
5. choose portal black or normal fog clear color, force depth writes, clear
   color/depth/stencil, and establish CW/back-face frame-global state;
6. run GL-state/surface diagnostics;
7. advance render-thread publication in order: `WbMeshAdapter.Tick`, destination
   reveal preparation/evaluation, then `ParticleRenderer.BeginFrame`;
8. begin ImGui, tick weather, and begin retail selection-scene accumulation;
9. when a normal camera/world viewport is active:
   - begin the one frame-scoped `RetailAlphaQueue` collection; its landscape
     `Flush` drains the first sub-scope and `EndFrame` later drains the final
     world sub-scope without a second begin;
   - resolve camera/projection/frustum and begin particle/terrain visibility;
   - publish world-reveal visibility/completion;
   - preview audio/display settings and publish the listener;
   - resolve player lighting cell and collided viewer render cell;
   - build prior-visible-cell point-light candidacy, sun/fog/lighting UBO, and
     animated/equipped classification;
   - construct the synthetic outdoor root/building candidates when required;
   - run the null-root safety world or the one `RetailPViewRenderer.DrawInside`
     graph;
   - draw the post-world Scene particles/weather fallback and debug geometry;
   - sample current-frame DebugVM visible-landblock and nearest-collision facts
     before the developer UI can consume them;
   - close the final shared-alpha scope and publish terrain/cell particle
     visibility;
10. complete retail selection-scene accumulation;
11. draw the portal CreatureMode replacement viewport;
12. render the private paperdoll FBO before its 2-D widget blit;
13. tick/update-cursor/draw retained gameplay UI;
14. render ImGui menus and developer panels above gameplay UI;
15. capture a requested default-framebuffer screenshot;
16. publish window-title, resource-dump, and frame-profile diagnostics;
17. close the exact GPU frame once in `finally`.

Within `RetailPViewRenderer.DrawInside`:

1. construct the main PView; merge per-building exterior floods only for the
   synthetic outdoor root and build separate look-in frames for interior roots;
2. assemble/upload the one clip arena, prepare EnvCell batches, partition
   statics/dynamics, and classify outside-stage dynamics;
3. draw each outside slice early: sky, terrain, and outdoor statics;
4. draw building look-ins: all far-Z punches, opaque shells, then transparent
   shells plus statics/dynamics/emitters;
5. draw outside-stage dynamic meshes, Scene particles, and weather late;
6. draw one interior-root unattached Scene-particle pass;
7. flush the **landscape** shared-alpha scope;
8. for an interior root, perform the full depth clear, then write true-depth
   exit seals; for an outdoor root, retain world depth and use far-Z entry
   punches;
9. draw opaque EnvCell shells once, then transparent shell cells immediate
   far-to-near;
10. draw cell statics as one cross-cell batch, then their particles;
11. draw the surviving main-flood dynamics last, then their particles; look-in
    and outside-stage dynamics remain in their earlier landscape phases.

The landscape alpha flush must never move across the depth clear. The final
world alpha close must never move after portal/paperdoll private viewports.

## 4. Architecture and interfaces

### 4.1 Frame transaction

Use immutable values equivalent to:

```csharp
internal readonly record struct RenderFrameInput(
    double DeltaSeconds,
    int ViewportWidth,
    int ViewportHeight);

internal readonly record struct WorldRenderFrameOutcome(
    int VisibleLandblocks,
    int TotalLandblocks,
    bool NormalWorldDrawn);
```

Portal-viewport selection and drawing belong to `PrivatePresentationRenderer`,
which runs after the world phase. If a combined public outcome becomes useful,
the top-level orchestrator composes it only after private presentation; the
world owner never claims that a later viewport was drawn.

`RenderFrameOrchestrator` receives a small fixed set of typed phase owners. It
does not receive every renderer separately, a mutable frame-services bag, or
`GameWindow`.

`BeginFrame` remains outside the `try`: if it fails, no `EndFrame` is attempted.
After begin succeeds, every failure closes exactly once. Render failure plus
close failure becomes the current explicit `AggregateException`; close-only
failure propagates directly. Alpha, particle-visibility, and selection-scene
completion retain their current non-finally behavior; changing that recovery
contract requires separate approval and evidence.

### 4.2 Borrowed resources and shutdown

Slice 7 collaborators borrow the already-created GL/render owners. They do not
dispose them. The existing retryable shutdown transaction keeps its proven
dependency order: wait for submitted work; withdraw UI/render publications;
release textures and mesh owners; then dispose GL backing stores, with
`GpuFrameFlightController` last among render resources. Slice 8 may group
construction/disposal after the render cutover is stable.

`DisplayFramePacingController` is the focused shared owner for requested VSync,
live display preview, monitor/window callbacks, and the separate
`OnFrameRendered` pacing event. Render preparation and window lifecycle wiring
invoke that typed owner directly; neither calls back into a substantial
`GameWindow` method. Its existing disposal remains in the Slice 7 shutdown
transaction.

### 4.3 World frame data

`WorldRenderFrameBuilder` owns reusable classification scratch:

- animated/equipped entity IDs;
- synthetic outdoor node and candidate building cells;
- previous-frame drawable cells used by point-light candidacy;
- camera/root/classification facts with one-frame borrowed lifetime.

The builder owns only facts available before PView execution. Slice-local
visible/outdoor/unattached particle-owner IDs belong to
`RetailPViewPassExecutor`. The current interior partition is produced by
`RetailPViewRenderer.DrawInside` and remains in its borrowed result/diagnostic
snapshot; it is never stored as stale pre-draw builder state.

It queries canonical `LiveEntityRuntime`, `GpuWorldState`, player-mode/camera,
physics cell graph, cell visibility, and landblock presentation sources. It
does not copy their dictionaries or create a second visibility computation.
Returned collections are borrowed until the next build; tests pin this
lifetime and consumers cannot retain them.

### 4.4 PView pass execution

Replace the current `RetailPViewDrawContext` callback bag with a data-only
`RetailPViewFrameInput`, a typed cell-visibility source, and one explicit
`IRetailPViewPassExecutor`/`RetailPViewPassExecutor`. The executor owns the GL
resources needed for these named operations:

```text
SetTerrainClip
DrawLandscapeSlice
DrawLandscapeSliceLate
ClearInteriorDepth
DrawExitPortalMask
DrawLookInPortalPunch
DrawUnattachedSceneParticles
FlushLandscapeAlpha
DrawCellParticles
DrawDynamicsParticles
EmitDiagnostics
```

`RetailPViewRenderer` remains the retail ordering owner and calls these typed
operations. The executor may not call `GameWindow` or make independent
visibility/order decisions. Existing borrowed `RetailPViewFrameResult` scratch
semantics remain explicit.

### 4.5 Presentation and diagnostics

`PaperdollFramePresenter` owns dirty state, DAT-backed clone/re-dress, pose
selection/application, and FBO rendering. Inventory/session paths call
`MarkDirty`; they do not mutate its internals.

`PrivatePresentationRenderer` owns portal viewport, paperdoll, retained UI,
ImGui, and screenshot order. A focused panel-layout/devtools owner handles menu
actions and is also reused by framebuffer resize; it cannot call a substantial
window method.

`WorldRenderDiagnostics` owns pass-local PView/GL/scissor state, render
signatures, and world-pass timings. `RenderFrameDiagnosticsController` owns
FPS/frame-time accumulation, final visible-landblock counters, performance
title/resource publication, and the public render-frame snapshot. Only
render-derived DebugVM providers move in Slice 7. Update/session/streaming
providers and the cross-domain world-lifecycle resource sampler stay at the
composition boundary until Slice 8 rather than turning either diagnostics
owner into a replacement service locator. Diagnostics observe the frame; they
never choose a draw branch or mutate canonical world ownership.

## 5. Implementation checkpoints

### A — contracts, architecture, and oracles

- correct the stale render-pipeline and per-frame architecture sections;
- add `RenderFrameInput`, phase interfaces, and a recording orchestrator;
- pin normal order, portal replacement, login wait, indoor/outdoor/null-root
  branches, and screenshot placement; camera is an initialized runtime
  invariant, so the slice does not invent a new graceful missing-camera path;
- pin the exact GPU begin/end exception matrix;
- add source guards against `GameWindow` back-references, mega contexts, and a
  new PView delegate bag;
- capture the current connected framebuffer/resource baseline.

### B — leaf presentation and diagnostics

- extract paperdoll refresh/pose/dirty/FBO ownership;
- extract panel-layout reuse and devtools menu/panel rendering;
- extract pass-local render signature, PView/GL/scissor probes, and timing state
  into `WorldRenderDiagnostics`; extract FPS, final counts, title/resource
  publication, and the public render snapshot into
  `RenderFrameDiagnosticsController`;
- preserve the pre-presentation render-derived DebugVM sampling site separately
  from the post-screenshot title/resource publication site; leave non-render
  DebugVM providers and cross-domain world-lifecycle sampling at composition;
- keep call sites in their current `GameWindow.OnRender` positions.

### C — frame resources and live preparation

- extract ordered per-resource `BeginFrame` calls, clear/state establishment,
  histogram probe, mesh upload, reveal evaluation, and particle begin;
- extract weather accumulation and display foundations that do not consume the
  camera/root classification, preserving their current render-time positions;
- consolidate requested-VSync/live-preview, monitor callbacks, and
  `OnFrameRendered` pacing through `DisplayFramePacingController`, while
  leaving its disposal in the existing shutdown transaction;
- prove `WbMeshAdapter.Tick` remains before reveal evaluation and drawing;
- prove dispatcher begin occurs once for the whole world/paperdoll frame.

### D — world frame builder

- move animated/equipped classification, camera/root selection, outdoor-node
  building gather, and prior-visible-cell light scratch out of the window;
- after those facts exist, run focused audio/listener, live preview, sky PES,
  sun/fog/point-light, and lighting-UBO preparation; do not build an interim
  `GameWindow` mega-context;
- keep PView-generated particle-owner sets in `RetailPViewPassExecutor` and the
  post-draw partition in the borrowed PView result/diagnostic snapshot;
- pin viewer-cell versus player-cell roles, portal replacement, login wait,
  fallback/null-root, sealed/SeenOutside, and borrowed scratch reset;
- preserve allocation-free warmed frames and hysteretic scratch retention.

### E — typed PView pass executor

- replace `Action`/`Func` draw callbacks in `RetailPViewDrawContext`;
- move landscape early/late, scissor/clip, depth seal/punch, particle passes,
  landscape alpha flush, and PView diagnostics to the executor;
- add a recording executor test for the complete `DrawInside` call sequence;
- verify no executor operation rebuilds portal visibility or retains a borrowed
  frame result across calls.

### F — world scene owner

- extract alpha/selection/particle-visibility begin/end and the normal-world
  conditional;
- extract sky/terrain/null-root fallback and unified PView branches;
- extract post-world particles/weather and debug collision drawing;
- return a small `WorldRenderFrameOutcome` for diagnostics/presentation;
- delete the world draw body and helper closure from `GameWindow`.

### G — final orchestration cutover

- compose concrete resource, world, private-presentation, and diagnostic owners;
- replace `OnRender` with one `RenderFrameOrchestrator.Render` handoff;
- remove obsolete fields/helpers/callbacks and prove the transitive render graph
  has no substantial path back to `GameWindow`;
- preserve the existing shutdown resource list without transferring disposal;
- measure line/field/method counts. Ownership decides completion; the expected
  signal is roughly 5,000–5,500 lines before Slice 8 composition cleanup.

### H — release and connected gates

After three clean corrected-diff reviews:

1. run focused App/Core render, PView, alpha, portal, screenshot, and resource
   tests;
2. run `dotnet build AcDream.slnx -c Release`;
3. run the complete Release suite;
4. run `tools/run-connected-world-lifecycle-gate.ps1 -SkipBuild`;
5. run `tools/run-connected-r6-soak.ps1 -SkipBuild`;
6. require code-zero graceful exits, exact lifecycle checkpoints/PNGs, no
   fatal/invariant/reveal/pending-resource failures, and unchanged same-location
   resource tolerances;
7. compare the six existing lifecycle/reconnect PNGs (`capped_login`,
   `aerlinthe_first`, `facility_hub`, `holtburg_after_dungeon`,
   `aerlinthe_revisit`, and `uncapped_reconnect`) with the Slice 6 baseline;
8. audit architecture, divergence pointers, roadmap, milestones, issues,
   `AGENTS.md`, `CLAUDE.md`, and durable memory.

The accepted baseline at docs-only commit `9512404e` is behavior-equivalent to
production cutover `e91f3102`: 7,182 passed / 5 skipped, 314.195-second
lifecycle/reconnect, and 393.581-second soak. Exact counters are recorded in
`memory/project_gamewindow_decomposition.md` and the Slice 6 closeout ledger.
Building/doorway poses, an open paperdoll, transient portal-exit visuals, and
#225 remain user visual gates; the stable post-materialization PNGs do not
overclaim them.

## 6. Mandatory review gate

After every implementation checkpoint, three read-only reviews run:

1. **Retail conformance:** named anchors, PView/alpha/depth/private-viewport/UI
   order, and registered adaptation boundaries.
2. **Architecture/integration:** focused owner scope, no replacement god object,
   no service locator/back-callback, render-thread mutation, borrowed lifetime,
   GL-state symmetry, and shutdown dependency direction.
3. **Adversarial:** begin/end failures, missing resources, portal/login
   branches, stale borrowed scratch, callback reentrancy, frame spikes,
   mid-frame resource churn, and GUID/session replacement.

The primary agent fixes confirmed findings at their root, then requests
corrected-diff re-review until clean. Each checkpoint then runs focused tests,
Release build/full suite, divergence/doc audit, and lands as one commit.

## 7. Final acceptance matrix

### Automated

- exact orchestrator order for normal, login, portal, indoor, outdoor, and
  fallback frames, plus construction-time rejection of missing required phase
  owners;
- exact GPU begin/end/aggregate failure behavior;
- PView landscape/look-in/flush/clear/seal/shell/static/dynamics ordering;
- screenshot after retained UI/ImGui, before title/resource/frame-profile
  diagnostics, and before GPU `EndFrame`;
- dispatcher frame begin once across world and paperdoll scopes;
- frame scratch reset/reuse after skipped, portal, normal, and failed frames;
- no `GameWindow` reference or anonymous draw delegate bag in extracted owners;
- existing PView replay, shared-alpha, particle visibility, portal, paperdoll,
  GPU-fence, screenshot, resource, and structural suites remain green;
- Release build and all tests green;
- connected lifecycle/reconnect and synchronized soak reports pass.

### In-client campaign gate

- outdoor dense scenes, terrain, sky, weather, particles, and selection match;
- buildings, doorway look-in/out, depth seals/punches, and dynamics stay stable;
- sealed dungeons keep correct visibility and lighting;
- portal replacement and destination reveal preserve the accepted flow;
- paperdoll, retained gameplay UI, cursor, and ImGui layering are unchanged;
- no resource growth, GPU reset, render exception, or shutdown regression.

## 8. Fixed assumptions

- all render/GL mutation remains on the existing render thread;
- `DatCollection` remains the only DAT reader;
- `LiveEntityRuntime`, `GpuWorldState`, cell visibility, session, and resource
  owners remain canonical and are not copied;
- existing render resources are borrowed through Slice 7 and disposed by the
  current shutdown transaction;
- frame-local results and scratch collections are borrowed until the next
  frame/call unless explicitly copied;
- no quality/range/performance tradeoff is introduced to make the extraction
  easier;
- missing optional diagnostic/UI owners skip only their own presentation and
  never suppress world drawing or GPU frame closure.