feat(fps): add a 30 FPS cap that keeps real time

docs/development.md

@@ -157,7 +157,7 @@ case-sensitive, and an unknown one is ignored.
 | `HOS_CHAIN=<file>` | While `<file>.go` exists, every wait of a game thread that blocks, every signal that can end one, every sleep and every present, with the time, the thread, the object and the caller; written to `<file>` when `<file>.go` goes away (about 2 million records at most). `python -I scripts/chain.py <file> [<HOS_SAMPLE_ALL file>]` walks each frame back from its present (the thread that ran, the wait that stopped it, the thread whose signal ended it) and prints the frame's critical path by thread: running, wake-ups, sleeps, and, with a sample file of the same run, the functions on it |
 | `HOS_THREAD_TIMES=<seconds>` | Every interval, the threads that used over 5% of a core |
 | `HOS_FPS_LOG` (set), `HOS_PRESENT_TRACE=<csv>` | The game's frame limiter, VRR flags and nominal rate every 300 presents, and the game clock's speed (1.000: real time); a CSV line per game present with host-clock times before queue flushing, around the renderer call, after virtual-core reacquisition, and at the return counter. These are CPU wall times, not GPU completion or scanout; async rendering measures the enqueue call. Unset/empty trace adds no clock reads |
-| `HOS_FPS_MAX=<61-1000>` | A frame rate cap for one run, over the Game frame rate cap row (1000 is Uncapped's) |
+| `HOS_FPS_MAX=30` or `<61-1000>` | A frame rate cap for one run, over the Game frame rate cap row (1000 is Uncapped's) |
 | `RX_VK_FRAME_LOG=<csv>` | A CSV line per present: frame, seconds, frame time in ms. Also works with `HOS_HEADLESS`: CPU intervals after submitting the offscreen copy, without swapchain/display waits. Not `RX_VK_FRAMELOG` (no underscore: pictures, above) |
 | `RX_VK_PRESENTS_AHEAD=<1-8>` | How many presents the game may hand over ahead of the replay (2). Not `RX_VK_PRESENT_AHEAD` |
 | `RX_VK_PRESENT_AHEAD=0` | Frame generation's copies into the window submitted each at its own time, as before #1702 (default on: a set's copies go to the GPU together). Not `RX_VK_PRESENTS_AHEAD` |

docs/tested-configurations.md

@@ -43,6 +43,7 @@ otherwise.
 | 2026-11-11 | as above | as above | as above | as above | as above, `RX_VK_SHADOW_STAGE=0` | as above | Fresh 63.2 fps at about 2,431 draws (memory sync 3.0 ms); after exploring 33.1 fps at 2,431-2,669 draws (memory sync 15.9 ms). No device lost |
 | 2026-11-11 | v2.1.0-rc.3-46-gddafc1f (source d13bde75), nightly | as above | as above | as above | as above, without #2314 | Kokiri Forest, the stream by the village, about 2 minutes after launch | 59.2 fps (56.6-60.0 over 29 windows of 120 presents) at about 2,262 draws; replay submit 12.1 ms, memory sync 4.6 ms. No device lost |
 | 2026-11-11 | as above | as above | as above | as above | 2560x1440 output, DLSS DLAA (model K), frame generation 3x, texture budget 6144 MB, Reflex on, `RX_VK_PARALLEL=4` | Kokiri Forest, the stream by the village, shortly after launch; then free play | Standing 60.9 fps (59.1-61.4 over 24 windows of 120 presents) at about 2,455 draws. About 8 minutes after launch, in Hyrule Field just north of Lake Hylia by the scarecrows, the device was lost after a 5.4 s GPU memory import: `VK_ERROR_DEVICE_LOST`, kernel Xid 109 then Xid 31, VRAM 10.4 of 10.8 GB allowed. Log on #1000 |
+| 2026-11-11 | private-2570 (source bda7ee48), main ef81aee7 + #2582 at b555f82a, API18 | Windows 11 Pro 26300, 1280x720 window | RTX 5090 32 GB, 617.42 | Ryzen 7 9800X3D, 96 GB | 2048x1152 output, Docked, game upscaler, Auto render resolution, FG Off; cap 30 (`frame_rate_cap=7`), Per frame (`game_speed=0`); BelowNormal process; present trace and FPS log on | Kokiri Forest, copied 11/6 12:58 a.m. autosave, Link facing NPC, three hearts; stationary with menu closed and no input/capture during sample | Menu saved 30 and normal restart retained it. 2,175 native present-call returns over 72.5003 s: 30.000 FPS, median 33.28 ms, p95 35.05 ms, longest 57.54 ms, two intervals over 40 ms. Eight game-clock samples: 59.99-60.01 units/s, speed 1.000. These are host return times, not GPU/display completion times. Normal exit; canonical saves/settings and installed players unchanged. Audio, cutscenes, movement/controller, moving platforms, FG and handheld battery/performance untested |
 | 2026-11-11 | host v2.1.0-main-local (source fc2ed0d0); renderer main 49f75dc8 + this branch (FSR 3.1 on the temporal chain) | Gentoo Linux, kernel 7.3.3, KDE Plasma Wayland, windowed | RX 9070 XT 16 GB, Mesa RADV 26.2.6 | Ryzen 9 9950X3D, 32 GB | 2560x1440 output, AMD FSR 3.1 at 100% and Quality (67%), 60 fps cap; `RX_VK_FSR3_CHAIN=0` for the comparison runs | Kokiri Forest (the lost-woods path, a 28 s camera turn), Castle Town market at noon | FSR 3.1 drew every frame on the chain (600 of 600 per status line), no evaluation failures. Kokiri, 4 runs each: 59.3 fps on the chain, 59.2 with its own inputs (1% low 48.1 and 46.4). Market, 3 runs each: 52.5 and 53.1 fps (runs vary by about 0.9). Standing still at 67%: edge flicker 1.67 against 3.01, 1-pixel outlines 2 against 12 per megapixel; at 100% the same within noise |
 | 2026-11-11 | v2.0.14 (source f2796384) + the `value_rec` last-part fix (renderer only) | Anatase 20261005.5 (Fedora-based), Steam Gaming Mode (gamescope, Flatpak Steam), 1280x720 window | ROG Ally X: Ryzen Z1 Extreme iGPU, RADV PHOENIX, Mesa 26.2.3 | Ryzen Z1 Extreme, 24 GB (15.6 GB visible) | 1920x1080 output, game's upscaler 67%, FG 2x, pacing on; `HOS_GUEST_MEMFD=1`, `RX_VK_VRAM_MB=3072` | Death Mountain Trail, walking and a fight | 57 s recording: 0 one-frame luminance spikes; 31.3 fps median (the game's own frames, over 300 draws) |
 | 2026-11-11 | host v2.1.0-main-local (source fc2ed0d0); renderer main 49f75dc8 + #1941 + #1942 + #2243 + this change, built with FSR 4 | Gentoo Linux, kernel 7.3.3, KDE Plasma Wayland, windowed | RX 9070 XT 16 GB, Mesa RADV 26.2.6 | Ryzen 9 9950X3D, 32 GB | 2560x1440 HDR10 (HDR Native, paper white 110 nits, peak 400), AMD FSR 4 Native AA through fsr4-vk (FSR 4.1.1, FP8) | Kokiri Forest (the lost-woods path) | The game presented PQ and FSR 4 was made HDR (log: `HDR colour, linear`); 600 of 600 frames drawn, no device lost. Brightest pixel PQ code 132 (the paper white) with `RX_VK_FSR4_HDR=0`, 135-145 with the change (two runs); the rest of the scene within one code value, brightness steady frame to frame. SDR unchanged |

gpu/vk/fps_stats.h

@@ -130,12 +130,12 @@ void columns(const Ring<N>& r, int64_t now, int64_t window, int count, int* out,
     }
 }
 
-/// The Game frame rate cap row's rate (0 60, then 90, 120, 144, 165, 240; 6 Uncapped: 0, no rate); HOS_FPS_MAX over it
+/// The Game frame rate cap row's rate (0 60, then 90, 120, 144, 165, 240; 6 Uncapped: 0, no rate; 7 30); HOS_FPS_MAX over it
 /// (env_max, 0 when not set: host/nn_vi.c fps_max's rules, 1000 and over is uncapped)
 inline int cap_rate(int fps_cap, int env_max = 0) {
-    static const int rates[] = {60, 90, 120, 144, 165, 240, 0};
-    if (env_max > 0) return env_max >= 1000 ? 0 : std::max(env_max, 60);
-    return fps_cap >= 0 && fps_cap <= 6 ? rates[fps_cap] : 60;   // (a value this build does not know: 60, as the host)
+    static const int rates[] = {60, 90, 120, 144, 165, 240, 0, 30};
+    if (env_max > 0) return env_max == 30 ? 30 : env_max >= 1000 ? 0 : std::max(env_max, 60);
+    return fps_cap >= 0 && fps_cap <= 7 ? rates[fps_cap] : 60;   // (a value this build does not know: 60, as the host)
 }
 /// The frame time the game aims for, in ms: the cap's, or with V-Sync On (FIFO, no frame generation) the display's refresh
 /// when that is slower; 0 when there is none (Uncapped, without V-Sync)