Need help getting started? Try the player guide. These notes include older work; the game overview explains what’s ready now.

Technical audit follow-up, 2026-10-20

Graphics menu and presentation follow-up, 2026-10-22

Graphics toggles now use one setting-field mapping for both displayed values and activation. Activation, keyboard/pointer availability and disabled styling share the row descriptor's capability policy. Renderer cycling remains separate; localized labels, stable IDs, order, layout and saved settings are unchanged. All51 menu captures remain byte-identical after the refactor.

The frontend only reapplies audio settings when music style, music volume or sound volume changes. Graphics, display and Extras changes no longer acquire the audio apply lock, reset identical mixer volumes or resend MIDI volume state. The existing audio-status snapshot and availability fallback still run. An instrumented Windows frontend fixture verifies zero audio apply calls through display/Graphics/Extras changes, then one for music style and one per volume edit.

New menus receive VSync availability before their first draw, including menus recreated after gameplay. VSync Off/unavailable now avoids the two window-state queries in each presentation; enabled VSync still checks visible/non-minimized windows and keeps its existing error recovery. No presentation timing, renderer quality, gameplay clock or audio balance changes were introduced. These are bounded reductions in redundant work, not a measured gameplay FPS improvement.

Validation: Windows Release rebuilt; all11 focused CTests;40,064 ASan/UBSan menu/audio checks;23,864 Windows settings/input/audio/persistence checks; 31,086 input/VSync checks;8,453,272 Vulkan checks with no validation errors and hidden frontend resize sanity. The Windows Settings pointer fixture was updated to the current display row. No campaign playthrough or physical input test. See frontend-settings-refactor-validation.json for source/capture hashes.

Motion-blur pass scheduling and working storage, 2026-10-22

The Vulkan postprocessor now omits camera blur on stationary frames and camera history resets. Motion-only no-op frames skip the composed RGB upload, compute submission, fence wait and RGB download; AO/AA still run when selected. Camera history advances even on skipped frames, so movement resumes from the latest view rather than accumulating old velocity. Main-scene surface metadata is still retained on the GPU when motion blur is enabled.

AO, AA and blur share a single ordered dispatch loop and at most two working image regions. Blur can overwrite the AO result after AA has consumed it; compute barriers cover both read-after-write and write-after-read dependencies. The three-effect working range drops from12 to8 bytes per pixel (23.7 to15.8MiB at1080p). With the backend's power-of-two allocator, a fresh1080p work buffer needs16MiB instead of32MiB; capacities remain retained across smaller viewports. Push-constant allocation derives from the C structure size instead of a repeated literal. A cumulative post-dispatch counter supports regression checks.

Three alternating before/after pairs on the RTX4060 Laptop GPU,30 stationary frames per each of eight scenes at1920x1080, give median run-average timings:

These are isolated renderer timings with a stationary camera, not gameplay FPS or measurements of moving-camera blur. All112 before/after scene captures have identical pixel/depth/water hashes and actor/wall counts:48 stationary captures plus64 moving captures covering non-motion masks0..7 at odd resolution641x359. Moving blur depends on wall-clock exposure and is covered by GPU regressions rather than cross-process hash comparisons. Details and raw run locations are in vulkan-motion-refactor-validation.json. The benchmark accepts an optional stationary argument after the effect mask.

Validation passes8,453,254 Vulkan checks and30 paired scene draws with no Vulkan validation errors, plus the hidden muted180-frame frontend resize check and all11 focused CTests. New checks assert omitted no-op dispatches, preserved outputs, and resumed blur after cuts for every AA/AF/AO combination. The Windows Release frontend was rebuilt. Settings, effect quality, Software/GBA rendering and game simulation are unchanged. No campaign playthrough was run.

GPU-retained AO metadata, 2026-10-22

The world-texel AO implementation previously copied each main-view UV/depth/ material sample into a CPU array and uploaded it again after reflections. The Vulkan backend now retains those samples directly on the device before reflection passes reuse the render attachments. Only the composed scene RGB is uploaded for postprocessing. The ordinary CPU readback needed for decals, water and statistics remains unchanged.

This removes the scene's16-byte-per-pixel AO array and its per-pixel copy/mask work. At1920x1080, the array occupied31.6MiB; normal AO postprocessing uploads fall from39.6MiB to7.9MiB per frame (80% less). Device-local copying preserves all original float samples. The shader applies the same sky/billboard depth mask that the CPU previously applied. No sample counts, resolution, filtering, world-texel snapping, AO radius or visual quality were reduced.

Metadata ownership follows the main renderer and dimensions. Starting a new pass on that renderer invalidates previous metadata; reflected renderers leave it intact. Successful postprocessing consumes it. The sample block is aligned to16 bytes, including odd frame sizes, and the transfer-to-compute barrier covers retained data and the new color upload. Standalone postprocessing keeps an explicit host override for differential checks. Scene code no longer owns or populates backend AO metadata.

Three alternating paired runs,30 frames per scene over8 scenes at1920x1080 on the RTX4060 Laptop GPU, produced these median-of-run-average render times:

These are isolated renderer timings; simulation, audio and presentation are excluded. All96 before/after scene comparisons retain identical pixel, depth, water-mask hashes and actor/wall counts. Additional odd-resolution checks cover all remaining effect masks. Raw runs, method and source hashes are in vulkan-ao-transfer-validation.json.

New regressions compare retained raw GPU samples against the former masked host-upload route after reflection attachment resize/overwrite, main-target growth/shrink and with/without AA. Real scene draws assert no host AO array is allocated. Vulkan passes8,222,890 checks/30 paired draws with zero validation errors, including hidden muted frontend resize sanity. All11 focused CTests and31,073 Win32 weapon-wheel/input checks pass. The rebuilt Windows frontend has no compiler warnings in the affected rebuild. Existing narrow integer/mask and wide-cursor resource warnings were made explicit without changing behavior. No campaign playthrough was run.

Vulkan postprocessing and policy cleanup, 2026-10-22

The revision removes unnecessary work from the new Vulkan effects while preserving their rendered output:

• FXAA without SSAO reads input colors directly. It no longer clears/uploads unused depth or dispatches a full-screen copy before filtering. Upload size falls from8 to4 bytes per pixel; compute dispatches fall from2 to1.
• Device-local input/work ranges follow the selected effects. AA alone needs two single-image buffers; AO alone needs color+depth input and one output; combined AO+AA retains its intermediate image and explicit compute barrier. Geometric capacities remain retained across toggles to avoid reallocations.
• SSAO reuses its four loaded neighbor depths for normal reconstruction.
• Named buffer-memory and menu-availability policies replace overloaded numeric flags. Upload/readback/device-local ownership and renderer-only row rules are explicit. Three menu shadowing/signedness warnings are fixed.

Validation: warning-free Windows Release build; all11 focused CTests; 8,202,211 Vulkan assertions and30 paired scene draws with zero validation errors, including the hidden muted frontend resize smoke. New post tests cover AA without depth, exact AA versus neutral-AO+AA output, repeated effect toggles, 1-pixel targets and growing odd sizes. ASan/UBSan audio/settings passes40,028 checks; all51 existing menu captures remain byte-identical. No campaign replay.

Three alternating before/after pairs at1920x1080,40 frames per scene across 8 scenes, and additional641x359 runs cover all8 effect masks. All112 compared scene outputs retain identical color, depth, water-mask hashes and actor/wall counts. Raw results and source hashes: vulkan-post-refactor-validation.json.

Median-of-run-averages effects time for AA alone fell7.386->6.763ms (8.4%). This timing includes CPU surface effects, not just postprocessing. Total render time did not improve reliably: AA17.599->18.440ms, AO18.479->19.406ms, all effects17.927->18.041ms. The concrete benefits are reduced transfers, dispatches and requested working memory; these measurements do not establish an overall FPS increase or an AO speedup. The hybrid CPU/GPU scene round trip remains a larger architectural cost. No quality/sample-count reductions or simulation/audio timing changes were made.

Rendering and menu cache follow-up, 2026-10-21

The audit follow-up implements the measured rendering hot spots without changing resolution, texture art, simulation timing or sprite priority:

• Floor/ceiling and water sampling share caller-owned, 512-entry world-texel scratch. Each software view and synchronous hardware row job starts empty. Keys include texel coordinates, plane height, material color and surface kind. Only the unfaded near range is cached; distance fading and the reflection stencil remain per pixel. No mutable cache is shared by worker threads or retained across moving sectors, animation frames or palette changes.
• Sprite wall transforms, near clipping and live portal heights are prepared once per view. Each sprite still applies its own origin/height gates and wall silhouette clipping. Subject/shadow/overlay submission uses one shared helper; original stable painter order and floor-overlapping sprite art are preserved.
• Reflections collect height/row intervals in one stencil scan, in original first-appearance order. They reuse shadow preparation and actor ordering, and avoid redundant geometry-signature work per reflected height and godray pass. Every mirror retains its own camera-dependent clipping preparation.
• Vulkan uses hashed material and texture lookups without sorting submissions. Texture entries own a byte copy and expanded palette indices. First use in each pass compares current bytes, including mip and generated shadow art; stale addresses are integer keys, never dereferenced. Unchanged content stays uploaded, changed ranges and the live palette are uploaded, and buffer growth copies the complete retained content. Retention resets at the next pass after 4 million texels or 4,096 entries; entries cannot be evicted mid-submission.
• Settings and Graphics row descriptors now drive label/slider coordinates, ranges and GBA-disabled styling/hit testing together. Stable action IDs, translations, saved settings and existing positions remain unchanged.

The benchmark now includes eight scenes: start with/without decals, water with/ without reflections, reflected shadows, godrays, and a synthetic 64-sprite scene with/without shadows. The crowd fixture changes render inputs only; it does not advance or bypass gameplay. Measurements exclude simulation, audio and display presentation. Larger GPU scheduling/readback changes remain outside this pass.

Validation and paired timings are recorded in render-refactors-validation.json. Three alternating paired runs, 60 frames per case at1920x1080 on the RTX4060 Laptop GPU, produced these medians:

The 1.3% plain-start difference is small enough to treat as timing noise. These are isolated renderer measurements, not gameplay FPS guarantees. Pixel, depth, water-mask hashes and actor/wall counts match before/after in all eight Vulkan cases across all three pairs, and in eight480x320 Software cases. All39 menu captures are byte-identical across three languages.

Validation: the static-runtime Windows Release build passes; all11 focused CTest checks pass; Vulkan passes6,564,616 assertions,30 paired scenes and the muted frontend resize smoke with zero validation errors. Texture regressions cover same-address byte changes, palette changes, mip-only changes, changed image dimensions, repeated material sharing, buffer growth and cache eviction. ASan/UBSan with leak checks passes surface decals (56,872,820 checks), PC renderer (11,803,544) and sprite shadows (14,408). Settings/core audio and the hidden, muted Windows Settings UI pass. No campaign playthrough was run.

Render-loop optimization, 2026-10-21

The hardware scene finish now gathers depth, actor/wall statistics, decals and water in one parallel row pass instead of a serial full-frame pass followed by a second effects pass. Each job owns its rows and per-row counters; counters are reduced after synchronous completion. Scratch counters grow with the target height, persist across draws and are released with the renderer's geometry cache. No gameplay or audio state enters worker jobs.

Hardware frames skip CPU depth clears that GPU readback completely overwrites, including the consumed reflection rows. Software still initializes depth. The hardware path also skips the redundant zero-pitch color clear: its sky pass fills every consumed row before upload. Sky rendering resolves each distinct texture row once and copies adjacent identical rows. This reuse is only within a draw, preserving live palette fades, yaw and pitch changes.

Three paired 60-frame runs at1920x1080 on the RTX4060 Laptop GPU measured these median isolated render times (simulation, audio and presentation excluded):

All measured final-frame pixel/depth/water hashes and actor/wall counters match the baseline exactly across the Vulkan runs; four separate854x480 Software cases also match. tests/bench_vulkan.c reports these hashes outside its timing interval. Timing variation remains, and these are not end-to-end gameplay FPS. The backend's effects_ms now includes depth/statistics processing too, so compare total render times rather than that component across implementations. Raw paired samples and source hashes: render-optimization-validation.json.

Validation: rebuilt Windows frontend and128 libraries; eight focused CTests; 5,846,303 Vulkan checks,18 sprite-order cases and22 paired GPU/software draws with no validation errors; exact serial/parallel pixels, depth, water masks and counters with and without effects; muted180-frame default-Vulkan launch/resize; 11,598,404 portable renderer assertions under GCC ASan/UBSan with leak checking. No campaign playthrough was run.

The audit fixes are implemented without intentional changes to gameplay, rendered artwork, audio balance, or save formats. The remaining large frontend state-machine redesign is deliberately staged; the original transition order and ownership flags still govern the application.

Changes

1. Profile errors. ssa_win32_profile_store checks the reread under its file lock. A transient read failure retains the pending in-memory change and leaves the disk file intact. Missing/corrupt files can be repaired from known session data; explicit Clear Data still clears, and another writer's valid cleared profile wins over stale session bits. This follows the existing score-table writer's policy.
2. Audio status. The UI obtains device availability, MIDI error and music activity through ssa_win32_audio_status, taking the worker's mutex. Open/close remain UI-thread lifecycle operations. Music modes, gains, delay, voices and sound-effect mixing are unchanged.
3. Shared decal atlas. Immutable masks/thresholds are initialized once per process. Windows uses InitOnce; portable builds use acquire/release C11 atomics. Level instances retain their own palette and layout, and never free the shared atlas. Sampling coordinates, tile generation and texels are unchanged. Tests retain a live instance while another is reinitialized and freed, in addition to checking complete atlas hashes and rendered pixels.
4. Renderer dependency. ssa_pc_scene owns geometry, world/actor drawing, allocation and mirrored-scene rendering. ssa_pc_renderer composes the HUD over that scene. Core depends on the scene backend, which calls no native lifecycle or HUD functions; it no longer links back to the PC compositor. The backend still reads the prepared SsaNativeGame structure. A narrower prepared-view data API can be introduced separately if that coupling becomes a maintenance problem. The missing portable libm dependency is explicit.
5. Frontend organization. game_screens.inc contains screen entry/exit and NETRICSA controller code; game_diagnostics.inc contains scripted audio, menu and story inputs plus the NETRICSA pointer diagnostic. App ownership and presentation-boundary assertions remain in game.c. This is a first separation of responsibilities, not a claim that every diagnostic or screen flag has been removed from the loop.
6. Settings. One field catalogue generates native storage, validation and comparison. The version-12, 16-byte disk encoder stays explicit. Shared runtime application is used for live changes and level setup; it validates before modifying state and does not reconfigure enhanced weapons when the mode is unchanged. Display/audio/input policy remains in the platform layer.
7. Focused test builds. CTest registers eight non-playthrough checks against production libraries. The three portable rendering/HUD Python runners share a content-addressed GCC sanitizer object/archive cache instead of rebuilding every C source independently. Toolchain flags, headers, includes and source content participate in cache keys. Failed builds never publish cache entries; an interprocess lock protects concurrent builders. Other historical ROM differential runners retain their specialized build paths.

Evidence

• Full Windows Release build passed, including the frontend with /W4 /WX.
• Eight CTest checks passed: settings fields, runtime settings, profile I/O, audio status, surface decals, PC renderer, classic HUD, frontend intermission.
• Profile I/O: 21 assertions covering sharing violations, retained progress, retry, concurrent clear, corrupt-file repair and failed replacement.
• Audio snapshot stress: 50,000 reads with a concurrent writer, no audio device.
• GCC ASan/UBSan with leak checking passed surface decals (52,224,732 checks), PC renderer (11,169,540), and classic HUD (382,453). MSVC agrees with the surface suite.
• The 12 pre/post renderer benchmark cases have identical pixel/depth hashes; all 25 saved decal screenshots are byte-identical.
• Windows Settings UI passed 23,656 checks, muted, including all three music modes. The audio/settings codec suite passed 39,044 checks over 26 sequences.
• Muted normal startup/menu/restart, GBA startup/audio/restart, and Egypt story handoff passed. No automated campaign playthrough was run.

Measured x64 sizes: SsaNativeGame decreased from 8,451,768 to 1,767,112 bytes; per-level decals decreased from 6,701,680 to 17,016 bytes. The process still owns one 6,684,672-byte atlas. The first atlas bake measured 45.6 ms during this run; subsequent level initialization measured 0.258 and 0.249 ms, versus approximately 38–40 ms for each initialization before sharing. These are initialization and memory measurements, not a claim of higher rendering FPS.

Reproduce focused Windows checks:

.\scripts\test-focused.ps1
# Reuse an existing build:
.\scripts\test-focused.ps1 -SkipBuild

CTest writes artifacts under build/native-windows/test-output and JUnit output to build/native-windows/focused-tests.xml. It never runs campaign completion or the audible MIDI synchronization diagnostic. WSL sanitizer entry points remain tests/test_surface_decals.py, tests/test_pc_renderer.py and tests/test_classic_hud.py. CMake also exposes SSA_SANITIZERS for GCC/Clang; that CMake configuration was not run here because WSL has no CMake installed.

The machine-readable summary is technical-refactors-validation.json. Existing feature-specific validation files retain their own scope. Manual control feel, audio listening, and full campaign parity were not evaluated by this refactor.