acdream/docs/plans/2026-07-22-gamewindow-slice-8-checkpoint-g-runtime-settings.md

GameWindow Slice 8 — Checkpoint G Runtime Settings Plan

Objective

Replace GameWindow's duplicated pre-window and OnLoad settings paths with one two-phase RuntimeSettingsController. The controller owns persistence and live settings state; render, window, audio, UI, and streaming objects remain borrowed targets. This is a structural cutover, not a redesign of the settings format or retail option behavior.

Two carried behaviors are now explicit rather than accidental. Saved FOV is applied during startup even when developer tools are disabled; previously it was incorrectly gated on construction of SettingsVM. The named-retail /framerate live toggle and notice remain intact, while acdream's already shipped cross-launch ShowFps persistence is documented as AP-121 rather than being attributed to the retail command body.

Frozen behavior and ordering

1. Construct the controller before Window.Create and load Display, Audio, Gameplay, Chat, and the default Character bag exactly once.
2. Resolve the preset plus environment overrides once for the immutable startup snapshot. WindowOptions.VSync comes from the pacing policy initialized with that snapshot; WindowOptions.Samples comes from the same resolved quality.
3. After window/GL input, camera, DAT effects, and optional audio exist, but before devtools or world/render factories, apply startup settings in this order: monitor-aware pacing, resolution/fullscreen, field of view, then audio.
4. Downstream terrain, dispatcher, render-range, and streaming factories read the same startup quality snapshot. The legacy startup stream-radius override remains at its current composition boundary.
5. Bind one complete RuntimeSettingsTargets only after window, UI (when enabled), terrain atlas, dispatcher, render-range, and streaming exist. Binding performs no display, quality, UI-lock, or audio replay.
6. Settings-panel Save preserves its callback order: keybindings, Display, Audio, Gameplay, Chat, Character. Each section retains its existing persistence/error boundary.
7. Display Save persists first, applies resolution/fullscreen, publishes the new display snapshot, then reapplies quality. A changed MSAA sample count is logged as restart-required and is not applied to the live GL context.
8. Runtime quality reapply preserves the existing order: alpha-to-coverage, terrain anisotropy, render-range publication, streaming reconciliation, completion budget.
9. /framerate, UI lock, loot permits, and combat preferences mutate the controller's canonical state, synchronize the optional Settings draft using the existing draft-preservation rules, and retain their existing save-error behavior.
10. Enter-world changes the active toon key, loads that character bag even when devtools are disabled, and publishes it to the optional Settings view model. Session reset restores the startup/default character context before the later identity-reset operation restores the key to default.
11. Per-frame display/audio preview reads the optional Settings draft through a typed source. Particle range and FPS visibility read the same source so an unsaved draft still previews exactly as it does today.
12. Shutdown first withdraws the Settings view-model and runtime-target loans; the controller never disposes the window, renderer, UI, streaming, audio, or input objects it borrows.

Types and ownership

• IRuntimeSettingsStorage is the test seam for the five settings bags. JsonRuntimeSettingsStorage is the production owner of the one concrete SettingsStore and exposes that store only for retained-window layout persistence.
• RuntimeSettingsSnapshot is the immutable startup value.
• IRuntimeSettingsStartupTarget receives the one startup Display/Audio apply.
• IRuntimeSettingsTargets receives future display-window, quality, and UI-lock changes. BindRuntimeTargets stores it without invoking it.
• IRuntimeSettingsPreviewSource exposes current Display/Audio preview values and whether a live draft exists.
• RuntimeSettingsController owns persistence, current values, active toon, resolved quality, and the optional SettingsVM binding. It also implements the combat settings source; no second gameplay-state mirror remains.
• SilkRuntimeDisplayWindowTarget, RuntimeSettingsStartupTargets, and RuntimeSettingsTargets are App-layer adapters over borrowed runtime objects.

Automated gates

• Construction loads every bag once and populates one immutable snapshot.
• Startup apply is ordered, exactly once, and independent of GL in controller tests.
• Runtime target binding produces zero calls; unbinding prevents future target calls while state and persistence still advance.
• Display Save ordering, quality transition, and restart-required MSAA logging.
• Quality target receives one complete resolved value per reapply.
• Draft preview/cancel, external FPS mutation, UI lock, loot permits, and combat option synchronization.
• Toon activate/load/reset/save behavior with and without a Settings view model.
• Save failures preserve each established state/target boundary.
• Source-boundary test proves GameWindow no longer constructs or loads a SettingsStore, owns persisted settings fields, or contains quality/display feature bodies.
• Focused App tests, full App tests, Release solution build, and full Release suite.

Review and commit gate

After the focused tests pass, the existing retail-conformance, architecture/integration, and adversarial reviewers inspect the complete diff in parallel. Confirmed findings are corrected and the same reviewers repeat until clean. Documentation, roadmap, issues, memory, CLAUDE.md, and AGENTS.md are reconciled in the same bisectable Checkpoint G commit.

Implementation result

• RuntimeSettingsController is constructed before Window.Create; all five bags load once and WindowOptions consumes its immutable startup snapshot.
• Startup substeps commit independently, so an audio failure retries audio without replaying already successful pacing/display/FOV work.
• Late target binding is inert and reversible; expected-instance SettingsVM withdrawal cannot detach a replacement binding.
• The concrete quality adapter preserves all five application steps and the unchanged MSAA restart boundary.
• Combat changes merge their three fields into a live Gameplay draft rather than overwriting unrelated unsaved fields; successful external changes also advance the SettingsVM persisted baseline so Cancel cannot resurrect stale command state.
• UI-lock target, persistence, and baseline publication form one explicit convergence state. A transient failure leaves the same requested value retryable instead of letting the equality fast-path strand unfinished work.
• Enter/reset/toon changes load and publish Character state independently of developer-tool availability.
• GameWindow no longer constructs or loads SettingsStore, owns persisted settings mirrors, or contains display/quality/settings feature bodies.
• Candidate metrics: 3,663 raw lines / 162 fields / 37 methods, down 394 lines / 36 fields / 17 methods from Checkpoint F and 12,060 lines (76.7%) from the campaign baseline.
• Thirty-five focused App settings/boundary tests, all 43 SettingsVMTests, the UI Abstractions Release suite (534 pass), and the App Release suite (3,183 pass / 3 intentional skips) pass. All three independent corrected-diff reviews are clean. The production App Release build has zero warnings/errors; the solution Release build retains the 17 existing #228 test-project warnings; and the complete Release suite passes 7,553 tests / 5 intentional skips.