fix(fps): Link's cap and other cloth keep the game's clock below 60 fps #1384

Open
dukenheimer wants to merge 3 commits from dukenheimer/Longshot:fix/hat-cloth-low-fps into main
Contributor

Type: fix · Risk: low · Tested on: Windows 11, RTX 5090; Steam Deck OLED (SteamOS, RADV) · Needs: none

Why

When the game runs below 60 fps, Link's cap floats: after he stops, it swings far out to the side and takes about a second to
settle. On the Steam Deck (17 to 24 fps) players see it all the time. At 60 fps it settles in about 0.2 s.

The cap is Havok cloth, and the game steps it a fixed 1/60 of a second each frame, whatever the game's own frame step for that
frame. With an engine frame step of 3.3 (about 18 fps), the cloth advances 1/60 s while the rest of the game advances 3.3/60 s,
about 0.3 of it. So the cloth lags behind Link: each cloth step sees his head move about 3.3 times as far, the cap swings wide,
and its settling takes about 3.3 times as long in real time. On a fast PC held to 18 fps it looks the same, so the frame step
alone causes it. The console would step the cloth the same way whenever its frame-rate controller drops to 30, 20 or 15 fps,
so this improves on the original's behaviour at low frame rates.

How to reproduce

Seen on: Windows 11, RTX 5090 (NVIDIA 621.14); the Steam Deck (reported)
Settings and switches: defaults at the game's 60 cap; HOS_FRAME_SLEEP_MS=53 (about 18 fps) on a fast PC, or any PC or
Deck that runs under 30 fps
Steps: in Kokiri Forest, run Link forward for 2 s and let go of the stick.
Expected: the cap follows his head and settles within about 0.2 s after he stops, as at 60 fps.
Actual: on main, the cap's tail flares out sideways 0.2 to 0.45 s after the stop and takes about a second to settle.

What changed

While the engine's frame step is over 1, the cloth's simulate setup steps by the game's 1/60 times that step, so the cloth
advances as far as the rest of the game that frame. The solve count stays the same. With a step of 1 or less nothing changes
(at 60 fps and above; a 60-capped game can still have steps over 1 on slow frames, and those are scaled). The cloth above
60 fps, which still steps 1/60 a frame, is left for a separate change.

  • nx2/oot_patches.py patch_cloth_time:
    • In f_81b3aa48, the Havok simulate operator's per-frame setup, the load of the step context's time (+8) goes through
      hos_oot_cloth_seconds with the engine's frame step: the float f_83b6ea90 writes at 0x84d61fc8, 60 / its frame rate.
    • The setup stores that time and its substep length in the frame data that the solve (f_81b47080) reads.
    • The instance's fixed-1/60 mode (f_81b3a964) is not touched.
    • report warns when the site isn't found once.
  • host/oot_high_fps.{h,c}:
    • oot_cloth_seconds multiplies the time by the step only for 1 < step ≤ 8. A step of 1 or less, 0, a negative step, NaN
      or Inf keeps the game's time.
    • hos_oot_cloth_seconds reads HOS_FPS_CLOTH by the repository's rule (env_value_off: unset, or anything but 0, off,
      false or no, is on). With HOS_FPS_LOG it logs an oot: cloth time line every 600 setups.
    • The header explains why.
  • docs/development.md: a row for HOS_FPS_CLOTH=0.
  • tests/test_oot_cloth_time.py (new): it fails on main.
    • f_81b3aa48's frame-data lines as lifted go through patch_file and are compiled with the host function cut from the
      real source and with gpu/vk/compat/longshot_env.h.
    • It runs frame steps 0.06 to 4.0 and the bad ones (0, −1, NaN, Inf, 8.5), instance scales 1 and 2, each setup twice from
      the same context, and HOS_FPS_CLOTH unset, 1, yes, 0 and off.
    • It checks: with a step over 1 the cloth time is the step's 60ths (else the game's 60th), over the scale; the substeps add
      up to it; the counts are the game's; the context is untouched and a second setup is the same.
  • tests/test_high_fps_fixes.py: its stand-ins include <stdlib.h> and an env_value_off, for the host file it compiles.

Measurements

Verdict: fixed at an 18 fps engine step on Windows and on the Steam Deck. The cloth's time a frame follows the engine's
step (55.6 to 66.7 ms on the PC, smoothed steps 3.33 to 4.0) instead of 16.7 ms, and in the stills the cap settles faster and
flares less, qualitatively like the 60 fps reference. The solve count is unchanged. On the Deck (handheld, about 18 fps) the
stills show the same; fps, median frame time, process CPU and GPU time show no detectable cost in these two runs per arm, and
the tail differences (p99, 1% low) are inconclusive at n=2. The PC's CPU sample of the cloth solve was inconclusive: medians
6.79% (off) and 6.88% (on) of a core, with interference on the PC.

Baseline: HOS_FPS_CLOTH=0 on this PR's build (the log and CPU rows: 5ddc9a7b). It switches off the one hook and runs the
game's own cloth path, on the same build, save and caches; there was no separate main base. The stills' before row comes from
an earlier build of this branch, 05bbcfd5, with HOS_FPS_CLOTH=0: the same unscaled path (=0 returns the game's time
unchanged in both), since the 5ddc9a7b =0 runs took no shots.

Hardware: Windows 11, RTX 5090 (NVIDIA 621.14), i7-13700K, 96 GB
Scene: Kokiri Forest beside Link's house, a child save; 2560x1440, quality preset 6 (Auto's), DLSS, frame generation off,
the game's 60 cap; headless (longshot_ctl.py launch --profile test); about 18 fps from HOS_FRAME_SLEEP_MS=53
Method: the cloth's time from the log, the cloth solve's CPU share in 2 interleaved runs a side (the median), and stills:

  • A scripted route through the control bridge: 3 s idle, 2.5 s run, 3 s stop, 2.5 s run back, 3 s stop.
  • The cloth's time from the oot: cloth time lines (HOS_FPS_LOG).
  • CPU from HOS_SAMPLE_ALL and scripts/cpu_report.py (inclusive share of f_81b47080), 2 interleaved pairs, the median.
  • Stills: every present shot while the route runs (1280x720; the 60 fps reference 640x360), cropped around Link at the same
    times after the stop.
    How to reproduce: as How to reproduce; HOS_FPS_LOG=1; HOS_FPS_CLOTH=0 for the before column.
Before, HOS_FPS_CLOTH=0: this PR @ 5ddc9a7b After: this PR @ 5ddc9a7b
cloth time a frame at an 18 fps engine step (steps 3.16–4.0) 16.67 ms 55.56–66.67 ms (the step's 60ths)
cloth solve count the game's the same
cloth solve f_81b47080, % of a core (run 1 / run 2, median) 7.27 / 6.31, 6.79 5.99 / 7.78, 6.88: inconclusive
game clock speed (first / second window) 0.994–0.998 / 0.929–0.943 0.996–0.998 / 0.947–0.962
Stills (cap after a stop) 60 fps reference: 05bbcfd5, HOS_FPS_CLOTH=0, 60 cap Before, HOS_FPS_CLOTH=0: 05bbcfd5, 18 fps After: this PR @ 5ddc9a7b, 18 fps
hangs down, settled by about +0.2 s tail flares out sideways at +0.2 to +0.45 s hangs down, settled by about +0.2 s

Times are the shots' present times after the stop (estimates from sampled frames, not measured settling times).

PC stills, from behind: rows 60 fps reference, Before HOS_FPS_CLOTH=0 (05bbcfd5), After this PR @ 5ddc9a7b
PC stills, toward the camera: the same rows

(5ddc9a7b, HOS_FPS_CLOTH=0, 18 fps)
oot: cloth time 16.67 ms (the game's 16.67 ms: frame step 3.333, HOS_FPS_CLOTH=0; 601 setups)
oot: cloth time 16.67 ms (the game's 16.67 ms: frame step 3.529, HOS_FPS_CLOTH=0; 1201 setups)
(5ddc9a7b, unset, 18 fps)
oot: cloth time 66.67 ms (the game's 16.67 ms: frame step 4.000; 1 setups)
oot: cloth time 58.82 ms (the game's 16.67 ms: frame step 3.529; 601 setups)
oot: cloth time 55.56 ms (the game's 16.67 ms: frame step 3.333; 1201 setups)

Steam Deck

Hardware: Steam Deck OLED, 16 GB (AMD Custom GPU 0932, RADV VANGOGH, Mesa 26.2.0-devel git 5c65d4fc31), SteamOS 3.9.5
(build 20261023.100), Game Mode, handheld on AC, 15 W power cap, GPU profile_peak
Build: this PR @ 5ddc9a7b, built natively for Linux (Longshot's Linux build image, tools.lock's tools, RX_MARCH=x86-64-v3;
longshot sha256 fee0f163…, longshot_vk.so c0b77984…)
Scene: Kokiri Forest, the owner's own settings (render at 100%, frame generation off), 1280x800 at 90 Hz, about 18 fps
Method: standing, 45 s windows; a warm-up of each arm, then =0, unset, unset, =0 (4 measured windows and 2 warm-ups,
all valid); frame times from the frame log, the process's CPU time per game frame (the bridge's frame counter) and GPU time a
frame from the renderer; then a scripted 30-frame run and stop with every present shot. Power-limit (FPPT) throttle flags
were set in 2-7% of the samples of the measured windows.

Before, HOS_FPS_CLOTH=0: this PR @ 5ddc9a7b After: this PR @ 5ddc9a7b
fps (run 1 / run 2, median) 18.31 / 18.17, 18.24 18.28 / 18.30, 18.29
median frame time 53.50 / 54.00, 53.75 ms 53.60 / 53.70, 53.65 ms
p99 frame time 66.4 / 91.3, 78.9 ms 64.6 / 64.9, 64.8 ms (inconclusive at n=2)
1% low 7.31 / 6.99, 7.15 fps 7.06 / 7.52, 7.29 fps
process CPU ms per bridge game frame (median) 152.6 ms 152.6 ms: no measurable CPU difference
GPU time a frame 44.06 ms 44.04 ms
cloth time a frame 16.67 ms at every step (2.14–4.00) 16.67 × the step (37.04 ms at 2.222, 52.63 at 3.158, 66.67 at 4.000)
Stills (cap after a stop, Deck) Before, HOS_FPS_CLOTH=0: this PR @ 5ddc9a7b After: this PR @ 5ddc9a7b
sticks out sideways at the stop, whips to the right by +0.2 s, still swinging at +0.45 and +0.67 s hangs behind his head from the stop, settled by +0.2 s, a slight sway after +0.45 s

No obvious stretching or clipping in the inspected frames (up to +0.67 s); these sequences are not a general stability test.
The times (+0.2 s, +0.45 s, +0.67 s) are estimates from the sampled presents' game times, not measured settling times.
Steam Deck stills: Before, HOS_FPS_CLOTH=0: this PR @ 5ddc9a7b, then After: this PR @ 5ddc9a7b

(Deck, HOS_FPS_CLOTH=0)  oot: cloth time 16.67 ms (the game's 16.67 ms: frame step 2.727, HOS_FPS_CLOTH=0; 1 setups)
(Deck, unset)            oot: cloth time 37.04 ms (the game's 16.67 ms: frame step 2.222; 1 setups)

About the PC's CPU sample: a WSL session not part of the test started at 23:14:28 during it, and the second =1 run shows higher
worker-thread totals (69.7% against 46–51% of a core), so it shows neither a cost nor its absence. Also tried and rejected:
multiplying the substeps by the step as well (4× at 18 fps) looked the same and took the solve from about 6% to about 26% of
a core (about +11.5 ms of CPU a frame).

Flags and settings

One new switch, to compare against the game's behaviour.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
HOS_FPS_CLOTH while the engine's frame step is over 1, the cloth steps by it not there (the game's 60th) unset: on; 0, off, false, no: the game's with a step over 1 the cloth advances as far as the game; a step of 1 or less unchanged helps at an 18 fps step on Windows and on the Steam Deck; no cost seen on the Deck at n=2 leave unset; 0 only to compare

Testing

Tested:

  • Game-free: python -I -B tests/run_all.py on 5ddc9a7b: 624 pass, 46 fail, 52 skipped. The same 46 fail on main @ 544229a2
    (623 pass), so this PR adds no failure; they are listed below. tests/test_oot_cloth_time.py fails on main and passes
    here. Six mutants fail it: no scaling, scaling at steps of 1 or less, no upper bound, NaN let through, atoi parsing, and
    the default off.
  • In the game, on Windows 11 with an RTX 5090: a full build of 5ddc9a7b, headless, the route above at an 18 fps engine step,
    =0 and =1 (log and CPU samples, 2 pairs) and =1 with shots. The lift applied the site once
    (oot_patches: the cloth's time below 60 fps in code_024.c, no warning).
  • Linux: a native build of 5ddc9a7b (Longshot's Linux build image, tools.lock's tools, RX_MARCH=x86-64-v3) finished with the
    site applied and no warnings (longshot sha256 fee0f163…, longshot_vk.so c0b77984…).
  • Steam Deck OLED, handheld on AC: that Linux build in Kokiri Forest at about 18 fps, =0 against unset, 2 interleaved 45 s
    windows each after a warm-up, the log lines, and every present around a stop (Measurements).

Not tested:

  • Pauses, menus, loading and area changes with the fix on.
  • Other cloth than Link's cap in close view.
  • The instance's fixed-1/60 mode, which this doesn't touch; whether the game uses it wasn't checked.
  • The fix's CPU cost beyond 2 runs a side: within the spread on the Deck, inconclusive on the PC.

Must be tested: None.

Risks

What could break: while the engine's step is over 1, every character's cloth (Link's cap, NPC clothes) steps by it, with
substeps up to 4 times as long as at 60 fps (the host caps the step at 4). At 18 fps nothing unstable was seen in Kokiri
Forest, but no other area was played, and the same solve count doesn't prove the cloth is stable everywhere.

Turning it off: HOS_FPS_CLOTH=0, or revert.

Compatibility: nothing changes for saves, options, caches or the vk ABI. The lifted code changes, so the game is translated
again on update, as with any oot_patches.py change.

Issues

No issue filed; the tracker was searched (cloth, hat, Link's cap, floaty, low fps, frame step). Seen by dukenheimer on his
Steam Deck.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named).
  • 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.
  • Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen.
  • A file in docs/tested/ for each new measured run (format in docs/tested-configurations.md): nine files, one a run
    (the Deck's 4 measured windows, the PC's 5 runs of the final build), in their own commit. Each passes scripts/tested_configurations.py's row reader;
    tests/test_tested_configurations.py fails on main already, on a file from #1256 with six rows and a Windows line-ending case.
  • A game-free test added for the fix, failing on main and passing here.
  • 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.
  • Docs updated.

The 46 checks that fail on main @ 544229a2 and on this branch: test_auto_handheld, test_bug_report_defaults, test_cpu_report,
test_crash_dialog, test_crt_options, test_damage_debug_menu, test_discover, test_display_startup_failure,
test_dlss_feature_size, test_failed_compile_keeps_objects, test_framegen_preset, test_fsr_uniform_ownership,
test_guest_imported, test_hud_layout_row, test_import_reach, test_invalidate_vcore, test_job_queue, test_lift_lookups,
test_linux_preflight, test_linux_pressure, test_mirror_budget, test_missing_nup, test_pads_after_menu,
test_parallel_init_order, test_pending_guest_import, test_perf_report, test_pipeline_play_cache, test_present_thread,
test_profiling_mode, test_readback_timeout_source, test_recorder_sync, test_replay_write_order, test_rumble_menu,
test_run_all_changed, test_slow_frames, test_staging_burst, test_switch_table, test_target_image_pool,
test_tested_configurations, test_upscaler_round_trip, test_upscaler_rows, test_vcore_escape, test_vk_occlusion_queries,
test_vk_swapchain_compat, test_walk_key, test_walk (all under tests/).

**Type:** fix · **Risk:** low · **Tested on:** Windows 11, RTX 5090; Steam Deck OLED (SteamOS, RADV) · **Needs:** none ## Why When the game runs below 60 fps, Link's cap floats: after he stops, it swings far out to the side and takes about a second to settle. On the Steam Deck (17 to 24 fps) players see it all the time. At 60 fps it settles in about 0.2 s. The cap is Havok cloth, and the game steps it a fixed 1/60 of a second each frame, whatever the game's own frame step for that frame. With an engine frame step of 3.3 (about 18 fps), the cloth advances 1/60 s while the rest of the game advances 3.3/60 s, about 0.3 of it. So the cloth lags behind Link: each cloth step sees his head move about 3.3 times as far, the cap swings wide, and its settling takes about 3.3 times as long in real time. On a fast PC held to 18 fps it looks the same, so the frame step alone causes it. The console would step the cloth the same way whenever its frame-rate controller drops to 30, 20 or 15 fps, so this improves on the original's behaviour at low frame rates. ## How to reproduce **Seen on:** Windows 11, RTX 5090 (NVIDIA 621.14); the Steam Deck (reported) **Settings and switches:** defaults at the game's 60 cap; `HOS_FRAME_SLEEP_MS=53` (about 18 fps) on a fast PC, or any PC or Deck that runs under 30 fps **Steps:** in Kokiri Forest, run Link forward for 2 s and let go of the stick. **Expected:** the cap follows his head and settles within about 0.2 s after he stops, as at 60 fps. **Actual:** on main, the cap's tail flares out sideways 0.2 to 0.45 s after the stop and takes about a second to settle. ## What changed While the engine's frame step is over 1, the cloth's simulate setup steps by the game's 1/60 times that step, so the cloth advances as far as the rest of the game that frame. The solve count stays the same. With a step of 1 or less nothing changes (at 60 fps and above; a 60-capped game can still have steps over 1 on slow frames, and those are scaled). The cloth above 60 fps, which still steps 1/60 a frame, is left for a separate change. - `nx2/oot_patches.py` `patch_cloth_time`: - In `f_81b3aa48`, the Havok simulate operator's per-frame setup, the load of the step context's time (+8) goes through `hos_oot_cloth_seconds` with the engine's frame step: the float `f_83b6ea90` writes at 0x84d61fc8, `60 / its frame rate`. - The setup stores that time and its substep length in the frame data that the solve (`f_81b47080`) reads. - The instance's fixed-1/60 mode (`f_81b3a964`) is not touched. - `report` warns when the site isn't found once. - `host/oot_high_fps.{h,c}`: - `oot_cloth_seconds` multiplies the time by the step only for 1 < step ≤ 8. A step of 1 or less, 0, a negative step, NaN or Inf keeps the game's time. - `hos_oot_cloth_seconds` reads `HOS_FPS_CLOTH` by the repository's rule (`env_value_off`: unset, or anything but 0, off, false or no, is on). With `HOS_FPS_LOG` it logs an `oot: cloth time` line every 600 setups. - The header explains why. - `docs/development.md`: a row for `HOS_FPS_CLOTH=0`. - `tests/test_oot_cloth_time.py` (new): it fails on main. - `f_81b3aa48`'s frame-data lines as lifted go through `patch_file` and are compiled with the host function cut from the real source and with `gpu/vk/compat/longshot_env.h`. - It runs frame steps 0.06 to 4.0 and the bad ones (0, −1, NaN, Inf, 8.5), instance scales 1 and 2, each setup twice from the same context, and `HOS_FPS_CLOTH` unset, 1, yes, 0 and off. - It checks: with a step over 1 the cloth time is the step's 60ths (else the game's 60th), over the scale; the substeps add up to it; the counts are the game's; the context is untouched and a second setup is the same. - `tests/test_high_fps_fixes.py`: its stand-ins include `<stdlib.h>` and an `env_value_off`, for the host file it compiles. ## Measurements **Verdict:** fixed at an 18 fps engine step on Windows and on the Steam Deck. The cloth's time a frame follows the engine's step (55.6 to 66.7 ms on the PC, smoothed steps 3.33 to 4.0) instead of 16.7 ms, and in the stills the cap settles faster and flares less, qualitatively like the 60 fps reference. The solve count is unchanged. On the Deck (handheld, about 18 fps) the stills show the same; fps, median frame time, process CPU and GPU time show no detectable cost in these two runs per arm, and the tail differences (p99, 1% low) are inconclusive at n=2. The PC's CPU sample of the cloth solve was inconclusive: medians 6.79% (off) and 6.88% (on) of a core, with interference on the PC. Baseline: `HOS_FPS_CLOTH=0` on this PR's build (the log and CPU rows: 5ddc9a7b). It switches off the one hook and runs the game's own cloth path, on the same build, save and caches; there was no separate main base. The stills' before row comes from an earlier build of this branch, 05bbcfd5, with `HOS_FPS_CLOTH=0`: the same unscaled path (`=0` returns the game's time unchanged in both), since the 5ddc9a7b `=0` runs took no shots. Hardware: Windows 11, RTX 5090 (NVIDIA 621.14), i7-13700K, 96 GB Scene: Kokiri Forest beside Link's house, a child save; 2560x1440, quality preset 6 (Auto's), DLSS, frame generation off, the game's 60 cap; headless (`longshot_ctl.py launch --profile test`); about 18 fps from `HOS_FRAME_SLEEP_MS=53` Method: the cloth's time from the log, the cloth solve's CPU share in 2 interleaved runs a side (the median), and stills: - A scripted route through the control bridge: 3 s idle, 2.5 s run, 3 s stop, 2.5 s run back, 3 s stop. - The cloth's time from the `oot: cloth time` lines (`HOS_FPS_LOG`). - CPU from `HOS_SAMPLE_ALL` and `scripts/cpu_report.py` (inclusive share of `f_81b47080`), 2 interleaved pairs, the median. - Stills: every present shot while the route runs (1280x720; the 60 fps reference 640x360), cropped around Link at the same times after the stop. How to reproduce: as How to reproduce; `HOS_FPS_LOG=1`; `HOS_FPS_CLOTH=0` for the before column. | | Before, `HOS_FPS_CLOTH=0`: this PR @ 5ddc9a7b | After: this PR @ 5ddc9a7b | |---|---|---| | cloth time a frame at an 18 fps engine step (steps 3.16–4.0) | 16.67 ms | 55.56–66.67 ms (the step's 60ths) | | cloth solve count | the game's | the same | | cloth solve `f_81b47080`, % of a core (run 1 / run 2, median) | 7.27 / 6.31, 6.79 | 5.99 / 7.78, 6.88: inconclusive | | game clock speed (first / second window) | 0.994–0.998 / 0.929–0.943 | 0.996–0.998 / 0.947–0.962 | | Stills (cap after a stop) | 60 fps reference: 05bbcfd5, `HOS_FPS_CLOTH=0`, 60 cap | Before, `HOS_FPS_CLOTH=0`: 05bbcfd5, 18 fps | After: this PR @ 5ddc9a7b, 18 fps | |---|---|---|---| | | hangs down, settled by about +0.2 s | tail flares out sideways at +0.2 to +0.45 s | hangs down, settled by about +0.2 s | Times are the shots' present times after the stop (estimates from sampled frames, not measured settling times). ![PC stills, from behind: rows 60 fps reference, Before HOS_FPS_CLOTH=0 (05bbcfd5), After this PR @ 5ddc9a7b](https://git.magicbean.dev/attachments/82916318-6f90-47e6-85b5-1b9b10dc64a9) ![PC stills, toward the camera: the same rows](https://git.magicbean.dev/attachments/d9a78c48-6797-4aae-a7de-cf936feee6e1) ``` (5ddc9a7b, HOS_FPS_CLOTH=0, 18 fps) oot: cloth time 16.67 ms (the game's 16.67 ms: frame step 3.333, HOS_FPS_CLOTH=0; 601 setups) oot: cloth time 16.67 ms (the game's 16.67 ms: frame step 3.529, HOS_FPS_CLOTH=0; 1201 setups) (5ddc9a7b, unset, 18 fps) oot: cloth time 66.67 ms (the game's 16.67 ms: frame step 4.000; 1 setups) oot: cloth time 58.82 ms (the game's 16.67 ms: frame step 3.529; 601 setups) oot: cloth time 55.56 ms (the game's 16.67 ms: frame step 3.333; 1201 setups) ``` #### Steam Deck Hardware: Steam Deck OLED, 16 GB (AMD Custom GPU 0932, RADV VANGOGH, Mesa 26.2.0-devel git 5c65d4fc31), SteamOS 3.9.5 (build 20261023.100), Game Mode, handheld on AC, 15 W power cap, GPU profile_peak Build: this PR @ 5ddc9a7b, built natively for Linux (Longshot's Linux build image, tools.lock's tools, `RX_MARCH=x86-64-v3`; `longshot` sha256 fee0f163…, `longshot_vk.so` c0b77984…) Scene: Kokiri Forest, the owner's own settings (render at 100%, frame generation off), 1280x800 at 90 Hz, about 18 fps Method: standing, 45 s windows; a warm-up of each arm, then `=0`, unset, unset, `=0` (4 measured windows and 2 warm-ups, all valid); frame times from the frame log, the process's CPU time per game frame (the bridge's frame counter) and GPU time a frame from the renderer; then a scripted 30-frame run and stop with every present shot. Power-limit (FPPT) throttle flags were set in 2-7% of the samples of the measured windows. | | Before, `HOS_FPS_CLOTH=0`: this PR @ 5ddc9a7b | After: this PR @ 5ddc9a7b | |---|---|---| | fps (run 1 / run 2, median) | 18.31 / 18.17, 18.24 | 18.28 / 18.30, 18.29 | | median frame time | 53.50 / 54.00, 53.75 ms | 53.60 / 53.70, 53.65 ms | | p99 frame time | 66.4 / 91.3, 78.9 ms | 64.6 / 64.9, 64.8 ms (inconclusive at n=2) | | 1% low | 7.31 / 6.99, 7.15 fps | 7.06 / 7.52, 7.29 fps | | process CPU ms per bridge game frame (median) | 152.6 ms | 152.6 ms: no measurable CPU difference | | GPU time a frame | 44.06 ms | 44.04 ms | | cloth time a frame | 16.67 ms at every step (2.14–4.00) | 16.67 × the step (37.04 ms at 2.222, 52.63 at 3.158, 66.67 at 4.000) | | Stills (cap after a stop, Deck) | Before, `HOS_FPS_CLOTH=0`: this PR @ 5ddc9a7b | After: this PR @ 5ddc9a7b | |---|---|---| | | sticks out sideways at the stop, whips to the right by +0.2 s, still swinging at +0.45 and +0.67 s | hangs behind his head from the stop, settled by +0.2 s, a slight sway after +0.45 s | No obvious stretching or clipping in the inspected frames (up to +0.67 s); these sequences are not a general stability test. The times (+0.2 s, +0.45 s, +0.67 s) are estimates from the sampled presents' game times, not measured settling times. ![Steam Deck stills: Before, HOS_FPS_CLOTH=0: this PR @ 5ddc9a7b, then After: this PR @ 5ddc9a7b](https://git.magicbean.dev/attachments/b21eafba-e56e-4ad0-ad00-9d06a1643e62) ``` (Deck, HOS_FPS_CLOTH=0) oot: cloth time 16.67 ms (the game's 16.67 ms: frame step 2.727, HOS_FPS_CLOTH=0; 1 setups) (Deck, unset) oot: cloth time 37.04 ms (the game's 16.67 ms: frame step 2.222; 1 setups) ``` About the PC's CPU sample: a WSL session not part of the test started at 23:14:28 during it, and the second `=1` run shows higher worker-thread totals (69.7% against 46–51% of a core), so it shows neither a cost nor its absence. Also tried and rejected: multiplying the substeps by the step as well (4× at 18 fps) looked the same and took the solve from about 6% to about 26% of a core (about +11.5 ms of CPU a frame). ### Flags and settings One new switch, to compare against the game's behaviour. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `HOS_FPS_CLOTH` | while the engine's frame step is over 1, the cloth steps by it | not there (the game's 60th) | unset: on; `0`, `off`, `false`, `no`: the game's | with a step over 1 the cloth advances as far as the game; a step of 1 or less unchanged | helps at an 18 fps step on Windows and on the Steam Deck; no cost seen on the Deck at n=2 | leave unset; `0` only to compare | ## Testing **Tested:** - Game-free: `python -I -B tests/run_all.py` on 5ddc9a7b: 624 pass, 46 fail, 52 skipped. The same 46 fail on main @ 544229a2 (623 pass), so this PR adds no failure; they are listed below. `tests/test_oot_cloth_time.py` fails on main and passes here. Six mutants fail it: no scaling, scaling at steps of 1 or less, no upper bound, NaN let through, `atoi` parsing, and the default off. - In the game, on Windows 11 with an RTX 5090: a full build of 5ddc9a7b, headless, the route above at an 18 fps engine step, `=0` and `=1` (log and CPU samples, 2 pairs) and `=1` with shots. The lift applied the site once (`oot_patches: the cloth's time below 60 fps in code_024.c`, no warning). - Linux: a native build of 5ddc9a7b (Longshot's Linux build image, tools.lock's tools, `RX_MARCH=x86-64-v3`) finished with the site applied and no warnings (`longshot` sha256 fee0f163…, `longshot_vk.so` c0b77984…). - Steam Deck OLED, handheld on AC: that Linux build in Kokiri Forest at about 18 fps, `=0` against unset, 2 interleaved 45 s windows each after a warm-up, the log lines, and every present around a stop (Measurements). **Not tested:** - Pauses, menus, loading and area changes with the fix on. - Other cloth than Link's cap in close view. - The instance's fixed-1/60 mode, which this doesn't touch; whether the game uses it wasn't checked. - The fix's CPU cost beyond 2 runs a side: within the spread on the Deck, inconclusive on the PC. **Must be tested:** None. ## Risks **What could break:** while the engine's step is over 1, every character's cloth (Link's cap, NPC clothes) steps by it, with substeps up to 4 times as long as at 60 fps (the host caps the step at 4). At 18 fps nothing unstable was seen in Kokiri Forest, but no other area was played, and the same solve count doesn't prove the cloth is stable everywhere. **Turning it off:** `HOS_FPS_CLOTH=0`, or revert. **Compatibility:** nothing changes for saves, options, caches or the vk ABI. The lifted code changes, so the game is translated again on update, as with any `oot_patches.py` change. ## Issues No issue filed; the tracker was searched (cloth, hat, Link's cap, floaty, low fps, frame step). Seen by dukenheimer on his Steam Deck. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [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] Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen. - [x] A file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`): nine files, one a run (the Deck's 4 measured windows, the PC's 5 runs of the final build), in their own commit. Each passes `scripts/tested_configurations.py`'s row reader; `tests/test_tested_configurations.py` fails on main already, on a file from #1256 with six rows and a Windows line-ending case. - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. - [x] Docs updated. The 46 checks that fail on main @ 544229a2 and on this branch: test_auto_handheld, test_bug_report_defaults, test_cpu_report, test_crash_dialog, test_crt_options, test_damage_debug_menu, test_discover, test_display_startup_failure, test_dlss_feature_size, test_failed_compile_keeps_objects, test_framegen_preset, test_fsr_uniform_ownership, test_guest_imported, test_hud_layout_row, test_import_reach, test_invalidate_vcore, test_job_queue, test_lift_lookups, test_linux_preflight, test_linux_pressure, test_mirror_budget, test_missing_nup, test_pads_after_menu, test_parallel_init_order, test_pending_guest_import, test_perf_report, test_pipeline_play_cache, test_present_thread, test_profiling_mode, test_readback_timeout_source, test_recorder_sync, test_replay_write_order, test_rumble_menu, test_run_all_changed, test_slow_frames, test_staging_burst, test_switch_table, test_target_image_pool, test_tested_configurations, test_upscaler_round_trip, test_upscaler_rows, test_vcore_escape, test_vk_occlusion_queries, test_vk_swapchain_compat, test_walk_key, test_walk (all under tests/).
Assisted-by: GitHub Copilot (Claude Opus 5.5)
Co-authored-by: Copilot App <[email protected]>
f_81b3aa48 takes the cloth's time from its step context, a 60th of a second whatever the frame (16.67 ms measured at 18 fps, ~45 setups a frame at 18 and 60 fps), so below 60 fps the cloth ran at fps/60 of the clock: Link's cap swung out and settled slowly. While the game's frame step (f_83b6ea90's float at 0x84d61fc8) is over 1, hos_oot_cloth_seconds multiplies that time by it: the same solves, the cloth on the clock. 60 fps and above unchanged. HOS_FPS_CLOTH=0 keeps the game's.

Assisted-by: GitHub Copilot (Claude Opus 5.5)
Co-authored-by: Copilot App <[email protected]>
docs(tested): the hat cloth fix's runs on the PC and the Steam Deck, one record a run
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
e8a8137f10
Assisted-by: GitHub Copilot (Claude Opus 5.5)
Co-authored-by: Copilot App <[email protected]>
Author
Contributor

Tested in game: Windows 11, RTX 5090 (NVIDIA 621.14): a full build of 5ddc9a7b, headless, Kokiri Forest at about 18 fps (HOS_FRAME_SLEEP_MS=53), HOS_FPS_CLOTH=0 against unset: the oot: cloth time line follows the engine step (55.6-66.7 ms against 16.67 ms) and Link's cap settles by about +0.2 s after a stop instead of flaring out. Steam Deck OLED (SteamOS 3.9.5, RADV, handheld on AC): a native Linux build of 5ddc9a7b, Kokiri Forest at about 18 fps, the same A/B: the same in the stills and the log, with fps, median frame time, process CPU and GPU time unchanged within 2 runs per arm.

Tested in game: Windows 11, RTX 5090 (NVIDIA 621.14): a full build of 5ddc9a7b, headless, Kokiri Forest at about 18 fps (HOS_FRAME_SLEEP_MS=53), HOS_FPS_CLOTH=0 against unset: the oot: cloth time line follows the engine step (55.6-66.7 ms against 16.67 ms) and Link's cap settles by about +0.2 s after a stop instead of flaring out. Steam Deck OLED (SteamOS 3.9.5, RADV, handheld on AC): a native Linux build of 5ddc9a7b, Kokiri Forest at about 18 fps, the same A/B: the same in the stills and the log, with fps, median frame time, process CPU and GPU time unchanged within 2 runs per arm.
Author
Contributor

The stills (Link's cap around a stop, crops of shots taken every present; times are the shots' present times after the stop, estimates from sampled frames).

PC, Windows 11, RTX 5090. Rows: the 60 fps reference (05bbcfd5, HOS_FPS_CLOTH=0, 60 cap); Before, HOS_FPS_CLOTH=0: 05bbcfd5, 18 fps (the same unscaled path; the 5ddc9a7b =0 runs took no shots); After: this PR @ 5ddc9a7b, 18 fps.

PC, from behind
PC, toward the camera

Steam Deck OLED, handheld on AC, about 18 fps. Rows: Before, HOS_FPS_CLOTH=0: this PR @ 5ddc9a7b; After: this PR @ 5ddc9a7b.

Steam Deck

The stills (Link's cap around a stop, crops of shots taken every present; times are the shots' present times after the stop, estimates from sampled frames). PC, Windows 11, RTX 5090. Rows: the 60 fps reference (05bbcfd5, `HOS_FPS_CLOTH=0`, 60 cap); Before, `HOS_FPS_CLOTH=0`: 05bbcfd5, 18 fps (the same unscaled path; the 5ddc9a7b `=0` runs took no shots); After: this PR @ 5ddc9a7b, 18 fps. ![PC, from behind](https://git.magicbean.dev/attachments/82916318-6f90-47e6-85b5-1b9b10dc64a9) ![PC, toward the camera](https://git.magicbean.dev/attachments/d9a78c48-6797-4aae-a7de-cf936feee6e1) Steam Deck OLED, handheld on AC, about 18 fps. Rows: Before, `HOS_FPS_CLOTH=0`: this PR @ 5ddc9a7b; After: this PR @ 5ddc9a7b. ![Steam Deck](https://git.magicbean.dev/attachments/b21eafba-e56e-4ad0-ad00-9d06a1643e62)
dukenheimer changed title from WIP: fix(fps): Link's cap and other cloth keep the game's clock below 60 fps to fix(fps): Link's cap and other cloth keep the game's clock below 60 fps 2026-11-17 09:28:46 +00:00
TrashPanda approved these changes 2026-11-17 10:11:59 +00:00
TrashPanda left a comment

Below 60 fps the cloth steps as far as the rest of the game that frame, and the number of solves stays the same. I read head e8a8137f. It applies onto current main. This can merge as it is.

f_81b3aa48 loads the step context's time and, while the engine's frame step is over 1 and at most 8, multiplies that time by the step. A step of 1 or less, 0, a negative step, NaN or Inf keeps the game's 60th. HOS_FPS_CLOTH=0 (also off, false or no) does the same. The fixed 1/60 mode is not patched. The site has to be found once, or the lift warns and leaves it. The game-free test runs the patched frame-data lines: the substeps add up to the scaled time, the counts stay the game's, and a second setup from the same context matches. The played code is 5ddc9a7b; the tip only adds the measured rows, one file each. On that build, at about 18 fps, the cloth's time follows the step on Windows and on the Steam Deck, and the cap settles instead of flaring out. Above 60 fps the cloth is unchanged.

Below 60 fps the cloth steps as far as the rest of the game that frame, and the number of solves stays the same. I read head `e8a8137f`. It applies onto current main. This can merge as it is. `f_81b3aa48` loads the step context's time and, while the engine's frame step is over 1 and at most 8, multiplies that time by the step. A step of 1 or less, 0, a negative step, NaN or Inf keeps the game's 60th. `HOS_FPS_CLOTH=0` (also off, false or no) does the same. The fixed 1/60 mode is not patched. The site has to be found once, or the lift warns and leaves it. The game-free test runs the patched frame-data lines: the substeps add up to the scaled time, the counts stay the game's, and a second setup from the same context matches. The played code is `5ddc9a7b`; the tip only adds the measured rows, one file each. On that build, at about 18 fps, the cloth's time follows the step on Windows and on the Steam Deck, and the cap settles instead of flaring out. Above 60 fps the cloth is unchanged.
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
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 doesn't have enough approvals yet. 0 of 1 approvals granted.
Some workflows are waiting to be reviewed.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'fix/hat-cloth-low-fps:dukenheimer-fix/hat-cloth-low-fps'
git switch 'dukenheimer-fix/hat-cloth-low-fps'
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!1384
No description provided.