WIP: feat(perf): trace local frame-state intervals #1625

Draft
futondestroyer wants to merge 2 commits from futondestroyer/Longshot:codex/issue1518-frame-state into main
Member

Type: feat · Risk: low · Tested on: Windows 11, RTX 4070, NVIDIA 621.01 · Needs: overhead measurements, Linux smoke, current-main rebase

TL;DR

Add an opt-in CSV that separates gameplay frame intervals from menu and decoded-movie activity. An interval with changing or missing state stays outside the gameplay sample.

Breakdown

  • Players diagnosing stutter can compare stable gameplay and non-gameplay intervals in one local run.
  • A per-map summary currently includes menu or movie activity that occurs without a map change.
  • Classify at host present entry using fresh evidence from menu updates, decoded output, and the player update.
  • Preserve the existing field reports, timing streams, and pacing.
  • The Windows source-backed fixture covers 33 samples, including a reversed clock, a late loading hint, and a pre-existing output file. Paired windowed runs verified the opt-in and the legacy CSV formats.
  • Linux runtime coverage, capture overhead and a current-main rebase remain open.
  • Low risk. The optional trace adds timestamp reads and file writes when enabled.

Why

The existing per-map performance reports cannot distinguish a menu opening and closing within one map. This diagnostic makes the classification available for local testing before considering a field series. Shared frame record · Related dashboard work

What changed

The optional frame-state CSV records whether the game is being played, showing a menu or playing a decoded movie. It also records when the available signals leave an interval uncertain.

  • frame_state_present() in host/rx_backend.c records state before renderer dispatch and keeps the clock-bracket time outside stable-state totals.
  • hos_frame_state_interval() in host/frame_state.h excludes mixed boundaries and decoder changes from gameplay. The trace includes the evidence mask and active decoder count.
  • The sampler creates its file exclusively. host/hos_main.c accepts the path from a dedicated diagnostic environment.
  • tests/test_frame_state.py compiles and exercises the sampler and classifiers with synthetic inputs.

Measurements

Verdict: The Windows smoke separated stable gameplay, the Insert menu, guest menus, and the decoded title movie. The paired launches used the same build to check diagnostic behavior. Capture overhead remains unmeasured.

Hardware: Windows 11 build 26300, RTX 4070, NVIDIA driver 621.01, Intel Core i7-13700F, 32 GB RAM.

Scene: Title movie, repository Kokiri Forest checkpoint and a teleport to Hyrule Field. 1720 × 720 SDR swapchain, Vulkan mailbox, upscaler off, frame generation off, cap 60, threaded rendering Auto (on).

Method: One windowed capture-off launch and one capture-on launch of 49089983, plus one warmed capture-on launch for Insert. Compared the headers and frame order of the legacy streams and counted classified boundaries and intervals in the sidecar. No speed or overhead statistics were collected.

How to reproduce: Start at the title with the kokiri-start repository checkpoint and HOS_SKIP_OPENING=0; set HOS_FPS_MAX=60, HOS_PRESENT_TRACE, HOS_PROFILE_DIR, RX_VK_FRAME_TRACE=1 and RX_VK_FRAME_LOG. Run with HOS_FRAME_STATE_TRACE unset, then run with it pointing to a fresh CSV. Enter Kokiri Forest, open and close Pause, Items and Insert, then teleport to Hyrule Field. Compare the legacy CSV headers and the sidecar's states.

Before: main @ 876dc360 After: this PR @ 49089983
Source-backed frame-state acceptance Fails at the missing opt-in sampler 33 synthetic boundaries and pre-existing-file guard pass
Windowed check on 49089983 Capture off Capture on
Exits cleanly after reaching Hyrule Field Pass Pass
Sidecar Absent 4,132 sampled boundaries and 15 transition intervals
Legacy CSVs All three produced with increasing frame IDs Same columns in all three and increasing frame IDs
Guest menus within Kokiri Forest Route completed 116 Pause and 121 Items observations in the respective action windows
Map change Route completed 233 unknown observations during the load window and gameplay recovered after arrival

Flags and settings

One local diagnostic switch.

Flag What it is Before this PR After this PR Effect Helps or untested Recommendation
HOS_FRAME_STATE_TRACE=<csv> New local output path Unavailable Unset Writes state and duration samples for native game presents Windows fixture and windowed capture passed. Overhead checks pending. Off unless diagnosing

Testing

Tested: The paired windowed launches ran exact head 49089983, with separate repository saves cloned for each launch. The capture-on trace recorded 763 stable gameplay intervals, 256 stable guest-menu intervals and 2,309 stable movie intervals. A warmed, windowed run at the same head recorded 360 Insert-menu observations within Kokiri Forest. The first and last crossings were transitions, and gameplay resumed on close. In both captures, each sampled duration plus its uncertain remainder matched the elapsed host time. The linked Windows pack built successfully. The Windows classifier, environment filter, guest-menu, opening, and video producer fixtures passed. All five modified host translation units passed a paired Windows syntax check with no new warnings. The full Windows suite reported 616 passes, 44 failures and 121 skips. All 44 failures also occur on pinned main.

44 failures reproduced on pinned main

tests/test_auto_handheld.py, tests/test_bake_ds.py, tests/test_bug_report_defaults.py, tests/test_build_long_paths.py, tests/test_cpu_report.py, tests/test_crash_dialog.py, tests/test_crt_options.py, tests/test_damage_debug_menu.py, tests/test_dev_packs.py, tests/test_discover.py, tests/test_display_startup_failure.py, tests/test_dlss_feature_size.py, tests/test_failed_compile_keeps_objects.py, tests/test_fastfp_fma.py, tests/test_fpx_sticky.py, tests/test_game_menu_mouse_buttons.py, tests/test_guest_imported.py, tests/test_hud_layout_row.py, tests/test_invalidate_quick.py, tests/test_invalidate_vcore.py, tests/test_job_queue.py, tests/test_libc_hooks.py, tests/test_lift_lookups.py, tests/test_linux_preflight.py, tests/test_linux_pressure.py, tests/test_mirror_budget.py, tests/test_missing_nup.py, tests/test_pads_after_menu.py, tests/test_pending_guest_import.py, tests/test_pipeline_play_cache.py, tests/test_present_thread.py, tests/test_profiling_mode.py, tests/test_psychov35_fsr3_fg.py, tests/test_readback_timeout_source.py, tests/test_release.py, tests/test_run_all_changed.py, tests/test_sdiv_overflow.py, tests/test_slow_frames.py, tests/test_spawn_emit.py, tests/test_switch_table.py, tests/test_tested_configurations.py, tests/test_upscaler_rows.py, tests/test_walk_key.py, tests/test_walk.py

Not tested: Linux runtime, decoded mid-map movies, affirmative live loading hints, and capture overhead. The scripted Windows map change had no qualifying player-update load hint. The Windows synthetic fixture covers that positive hint.

Must be tested:

  • Linux, Vulkan GPU: Using a new local output path, open and close Insert and Pause or Items in Kokiri Forest, then play a decoded movie and load another map, expecting stable gameplay, menu and movie observations (by hand, inspect the sidecar around each boundary).
  • Windows and Linux, Vulkan GPU: Load a scene that retains Link updates and play a decoded mid-map movie, expecting live loading and movie samples while their evidence is fresh (by hand, verify the state and hint bit in the CSV).
  • Windows timing run: Measure disabled and enabled overhead against current main on the same PC in a controlled timing slot, expecting a near-baseline disabled path and a measured enabled cost (by hand, compare interleaved frame-time and CPU medians).

Risks

What could break: A title, load, or cutscene can lack a qualifying player observation. The CSV records those samples as unknown. An enabled capture performs extra clock reads and buffered file writes.

Turning it off: Leave HOS_FRAME_STATE_TRACE unset.

Compatibility: The existing saves, caches, renderer ABI, pacing controls, and exported metrics retain their current paths.

Issues

See #1518
See #1530 for the field producer boundary.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (feat(perf): trace local frame-state intervals) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says.
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Nothing gets worse that I know of. Capture overhead pending.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main. The reviewed and built head is based on 876dc360. Current main is 9dff58e6.
  • python -I -B tests/run_all.py passes apart from the pinned-main failures named in Testing.
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Linux full build pending.
  • Docs updated.
**Type:** feat · **Risk:** low · **Tested on:** Windows 11, RTX 4070, NVIDIA 621.01 · **Needs:** overhead measurements, Linux smoke, current-main rebase ## TL;DR Add an opt-in CSV that separates gameplay frame intervals from menu and decoded-movie activity. An interval with changing or missing state stays outside the gameplay sample. ## Breakdown - Players diagnosing stutter can compare stable gameplay and non-gameplay intervals in one local run. - A per-map summary currently includes menu or movie activity that occurs without a map change. - Classify at host present entry using fresh evidence from menu updates, decoded output, and the player update. - Preserve the existing field reports, timing streams, and pacing. - The Windows source-backed fixture covers 33 samples, including a reversed clock, a late loading hint, and a pre-existing output file. Paired windowed runs verified the opt-in and the legacy CSV formats. - Linux runtime coverage, capture overhead and a current-main rebase remain open. - Low risk. The optional trace adds timestamp reads and file writes when enabled. ## Why The existing per-map performance reports cannot distinguish a menu opening and closing within one map. This diagnostic makes the classification available for local testing before considering a field series. [Shared frame record](https://git.magicbean.dev/MagicBeanDev/Longshot/issues/1518) · [Related dashboard work](https://git.magicbean.dev/MagicBeanDev/Longshot/issues/1520) ## What changed The optional frame-state CSV records whether the game is being played, showing a menu or playing a decoded movie. It also records when the available signals leave an interval uncertain. - `frame_state_present()` in `host/rx_backend.c` records state before renderer dispatch and keeps the clock-bracket time outside stable-state totals. - `hos_frame_state_interval()` in `host/frame_state.h` excludes mixed boundaries and decoder changes from gameplay. The trace includes the evidence mask and active decoder count. - The sampler creates its file exclusively. `host/hos_main.c` accepts the path from a dedicated diagnostic environment. - `tests/test_frame_state.py` compiles and exercises the sampler and classifiers with synthetic inputs. ## Measurements **Verdict:** The Windows smoke separated stable gameplay, the Insert menu, guest menus, and the decoded title movie. The paired launches used the same build to check diagnostic behavior. Capture overhead remains unmeasured. Hardware: Windows 11 build 26300, RTX 4070, NVIDIA driver 621.01, Intel Core i7-13700F, 32 GB RAM. Scene: Title movie, repository Kokiri Forest checkpoint and a teleport to Hyrule Field. 1720 × 720 SDR swapchain, Vulkan mailbox, upscaler off, frame generation off, cap 60, threaded rendering Auto (on). Method: One windowed capture-off launch and one capture-on launch of `49089983`, plus one warmed capture-on launch for Insert. Compared the headers and frame order of the legacy streams and counted classified boundaries and intervals in the sidecar. No speed or overhead statistics were collected. How to reproduce: Start at the title with the `kokiri-start` repository checkpoint and `HOS_SKIP_OPENING=0`; set `HOS_FPS_MAX=60`, `HOS_PRESENT_TRACE`, `HOS_PROFILE_DIR`, `RX_VK_FRAME_TRACE=1` and `RX_VK_FRAME_LOG`. Run with `HOS_FRAME_STATE_TRACE` unset, then run with it pointing to a fresh CSV. Enter Kokiri Forest, open and close Pause, Items and Insert, then teleport to Hyrule Field. Compare the legacy CSV headers and the sidecar's states. | | Before: main @ 876dc360 | After: this PR @ 49089983 | |---|---|---| | Source-backed frame-state acceptance | Fails at the missing opt-in sampler | 33 synthetic boundaries and pre-existing-file guard pass | | Windowed check on `49089983` | Capture off | Capture on | |---|---|---| | Exits cleanly after reaching Hyrule Field | Pass | Pass | | Sidecar | Absent | 4,132 sampled boundaries and 15 transition intervals | | Legacy CSVs | All three produced with increasing frame IDs | Same columns in all three and increasing frame IDs | | Guest menus within Kokiri Forest | Route completed | 116 Pause and 121 Items observations in the respective action windows | | Map change | Route completed | 233 unknown observations during the load window and gameplay recovered after arrival | ### Flags and settings One local diagnostic switch. | Flag | What it is | Before this PR | After this PR | Effect | Helps or untested | Recommendation | |---|---|---|---|---|---|---| | `HOS_FRAME_STATE_TRACE=<csv>` | New local output path | Unavailable | Unset | Writes state and duration samples for native game presents | Windows fixture and windowed capture passed. Overhead checks pending. | Off unless diagnosing | ## Testing **Tested:** The paired windowed launches ran exact head `49089983`, with separate repository saves cloned for each launch. The capture-on trace recorded 763 stable gameplay intervals, 256 stable guest-menu intervals and 2,309 stable movie intervals. A warmed, windowed run at the same head recorded 360 Insert-menu observations within Kokiri Forest. The first and last crossings were transitions, and gameplay resumed on close. In both captures, each sampled duration plus its uncertain remainder matched the elapsed host time. The linked Windows pack built successfully. The Windows classifier, environment filter, guest-menu, opening, and video producer fixtures passed. All five modified host translation units passed a paired Windows syntax check with no new warnings. The full Windows suite reported 616 passes, 44 failures and 121 skips. All 44 failures also occur on pinned main. <details> <summary>44 failures reproduced on pinned main</summary> `tests/test_auto_handheld.py`, `tests/test_bake_ds.py`, `tests/test_bug_report_defaults.py`, `tests/test_build_long_paths.py`, `tests/test_cpu_report.py`, `tests/test_crash_dialog.py`, `tests/test_crt_options.py`, `tests/test_damage_debug_menu.py`, `tests/test_dev_packs.py`, `tests/test_discover.py`, `tests/test_display_startup_failure.py`, `tests/test_dlss_feature_size.py`, `tests/test_failed_compile_keeps_objects.py`, `tests/test_fastfp_fma.py`, `tests/test_fpx_sticky.py`, `tests/test_game_menu_mouse_buttons.py`, `tests/test_guest_imported.py`, `tests/test_hud_layout_row.py`, `tests/test_invalidate_quick.py`, `tests/test_invalidate_vcore.py`, `tests/test_job_queue.py`, `tests/test_libc_hooks.py`, `tests/test_lift_lookups.py`, `tests/test_linux_preflight.py`, `tests/test_linux_pressure.py`, `tests/test_mirror_budget.py`, `tests/test_missing_nup.py`, `tests/test_pads_after_menu.py`, `tests/test_pending_guest_import.py`, `tests/test_pipeline_play_cache.py`, `tests/test_present_thread.py`, `tests/test_profiling_mode.py`, `tests/test_psychov35_fsr3_fg.py`, `tests/test_readback_timeout_source.py`, `tests/test_release.py`, `tests/test_run_all_changed.py`, `tests/test_sdiv_overflow.py`, `tests/test_slow_frames.py`, `tests/test_spawn_emit.py`, `tests/test_switch_table.py`, `tests/test_tested_configurations.py`, `tests/test_upscaler_rows.py`, `tests/test_walk_key.py`, `tests/test_walk.py` </details> **Not tested:** Linux runtime, decoded mid-map movies, affirmative live `loading` hints, and capture overhead. The scripted Windows map change had no qualifying player-update load hint. The Windows synthetic fixture covers that positive hint. **Must be tested:** - Linux, Vulkan GPU: Using a new local output path, open and close Insert and Pause or Items in Kokiri Forest, then play a decoded movie and load another map, expecting stable gameplay, menu and movie observations (by hand, inspect the sidecar around each boundary). - Windows and Linux, Vulkan GPU: Load a scene that retains Link updates and play a decoded mid-map movie, expecting live `loading` and `movie` samples while their evidence is fresh (by hand, verify the state and hint bit in the CSV). - Windows timing run: Measure disabled and enabled overhead against current main on the same PC in a controlled timing slot, expecting a near-baseline disabled path and a measured enabled cost (by hand, compare interleaved frame-time and CPU medians). ## Risks **What could break:** A title, load, or cutscene can lack a qualifying player observation. The CSV records those samples as unknown. An enabled capture performs extra clock reads and buffered file writes. **Turning it off:** Leave `HOS_FRAME_STATE_TRACE` unset. **Compatibility:** The existing saves, caches, renderer ABI, pacing controls, and exported metrics retain their current paths. ## Issues See https://git.magicbean.dev/MagicBeanDev/Longshot/issues/1518 See https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1530 for the field producer boundary. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`feat(perf): trace local frame-state intervals`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says. - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [ ] Nothing gets worse that I know of. Capture overhead pending. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [ ] Rebased on current `main`. The reviewed and built head is based on `876dc360`. Current main is `9dff58e6`. - [x] `python -I -B tests/run_all.py` passes apart from the pinned-main failures named in Testing. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Linux full build pending. - [x] Docs updated.
feat(perf): trace local frame-state intervals
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 15s
Third-party parts / As their notes say (pull_request) Successful in 17s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
4908998398
Assisted-by: OpenAI Codex
Author
Member

Tested in game: Windows 11 build 26300, RTX 4070, NVIDIA 621.01, windowed Vulkan mailbox at 1720 x 720. On 49089983, the opt-in trace separated Pause, Items and Insert from gameplay in Kokiri Forest and tagged the decoded title movie. Hyrule Field loaded, gameplay resumed, and both paired runs exited cleanly. The three legacy CSV headers matched, and capture off produced no sidecar.

Tested in game: Windows 11 build 26300, RTX 4070, NVIDIA 621.01, windowed Vulkan mailbox at 1720 x 720. On 49089983, the opt-in trace separated Pause, Items and Insert from gameplay in Kokiri Forest and tagged the decoded title movie. Hyrule Field loaded, gameplay resumed, and both paired runs exited cleanly. The three legacy CSV headers matched, and capture off produced no sidecar.
Collaborator

Possibly related, for context:

  • PR #1502 WIP: fix(perf): perf samples follow the camera, land in the relay's own cells, and skip cutscenes and the title — Open gameplay-sample filtering by map, cutscenes, title
  • PR #1530 feat(perf): the game sends its own v2 summaries with replay phases — Open producer work; description says boundary coordinated, but this adds separate local trace
  • issue #1518 A frame is timed at six different moments, and none of them is when it reaches the screen — Frame timing/record measurement motivation this PR implements
Possibly related, for context: - PR #1502 WIP: fix(perf): perf samples follow the camera, land in the relay's own cells, and skip cutscenes and the title — Open gameplay-sample filtering by map, cutscenes, title - PR #1530 feat(perf): the game sends its own v2 summaries with replay phases — Open producer work; description says boundary coordinated, but this adds separate local trace - issue #1518 A frame is timed at six different moments, and none of them is when it reaches the screen — Frame timing/record measurement motivation this PR implements
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 10s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 15s
Third-party parts / As their notes say (pull_request) Successful in 17s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
This pull request is marked as a work in progress.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'codex/issue1518-frame-state:futondestroyer-codex/issue1518-frame-state'
git switch 'futondestroyer-codex/issue1518-frame-state'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1625
No description provided.