First batch of planned PRs

[Ernold11]

First batch of planned PRs — overview before I open them

Four branches are ready or nearly ready. They touch completely disjoint file
sets, so they can be reviewed and merged in any order, independently — I
checked, there is not a single shared file between them.

Sizes below are against current main (553c8ab). All four branches are
already rebased on it; none is stale.

#	Branch	Area	Size	Status
1	agent/latency-without-overlay	docs	+44 / −2, 4 files	ready
2	agent/boot-apply-single-source	GUI / profiles	+142 / −14, 2 files	ready
3	agent/externally-capped-frames	burnerd adaptive	+866 / −31, 7 files	ready

Happy to split, reorder, or drop any of these.

---

1. agent/latency-without-overlay — document keeping latency markers with the overlay off

Problem. In-game latency defaults to the overlay's state, so --pb-overlay=0
switches off NVAPI marker capture along with the HUD. That is a reasonable
default, but it silently removes the pacing signal that adaptive tier switching
reads, and nothing told the user how to get it back.

Change. Documents the explicit opt-in in the latency guide and the shim
reference. Also spells out that the leading env is required: Lutris execs the
command prefix directly rather than through a shell, so a bare
PB_INGAME_LATENCY=1 would be taken as the program to run.

Risk: none — documentation plus the tests that keep the docs honest.

Suggested first. It is the smallest, and it documents behaviour that 3
depends on users being able to enable.

---

2. agent/boot-apply-single-source — read the boot checkbox from the daemon

Problem. "Apply on startup" mixed two sources of truth. The daemon's per-GPU
boot set is the only thing that decides what applies at startup, but the
[ui] persist_on_startup preference was read back to answer "what will boot
do". Nothing rewrites that key when the entry goes away, so it could only go
stale — a config holding true against an empty boot set showed "applies at
startup" for a boot with nothing to apply.

The per-GPU session cache had the same problem in the other direction, and that
is the damaging one: seeded once from the daemon, then authoritative for the
rest of the session, even though the daemon is re-read on every sync. Every
apply sends --boot or --clear-boot from that state. Reachable without
touching the GUI's boot controls at all:

1. open the GUI with no boot entry for the selected GPU — cache seeded off;
2. run penguin-burner-cli --restore-stock, which writes a boot entry through
   its own persist_on_startup path;
3. back in the GUI the box still reads off, because the cache decided once;
4. apply any profile — --clear-boot silently wipes what step 2 wrote.

Change. The no-UUID branch asks the daemon, which already answers for its
selected GPU. The cache now carries only intent the daemon has not been told
about yet — a freshly ticked box — dropped the moment the daemon reports it.
Reading the two with OR keeps one invariant: the box is never shown off while
the daemon holds an entry, so --clear-boot only goes out when there is
genuinely nothing to clear. The preference key keeps being written, and is
documented as what it is — a record of the user's choice, not a statement
about boot.

Also closes a test-isolation gap found on the way: the win fixture patched
the window module's autostart reader but not the mixin's own binding, so
building the window in tests reached the real daemon socket and the checkbox
started ticked or not depending on what that machine had saved.

Risk: low, contained to the GUI profile path. Each new test was confirmed to
fail against the previous behaviour, not merely to pass now.

---

3. agent/externally-capped-frames — stop adaptive fighting an external frame cap

Four commits, and the largest behavioural change of the set. Mostly
burnerd/src/profile/adaptive.rs, with the matching runtime spec fields and
user docs.

Problem. With a target above an external frame cap — a menu locked at 60
while aiming for 100 — every branch of the slow ladder read the miss as "short
of clock". At that target 16.67 ms is well past badly_slow, so the tier jumped
straight to the top and sat there for the whole menu, burning power for frames
the cap would never let through.

What the four commits do

1. Judge whether the GPU is actually the limiter first. When it is loafing
   and the CPU is not saturated either, nothing about the frame rate is a clock
   problem, so the tier eases down instead of climbing. Easing reuses the
   existing comfort-demotion path rather than introducing a second set of
   timings. A saturated CPU is deliberately left to the existing cpu-bound
   guard, keeping the two rules disjoint.

2. Latch the recognition against pacing, not utilisation. The first cut
   oscillated on hardware — performance → balanced → efficiency, then straight
   back — because utilisation was both the entry signal and the thing keeping it
   alive, and utilisation is not independent of the tier: each step down makes
   the card work harder for the same capped rate, climbing back over the entry
   threshold and cancelling the recognition that caused the step. A cap holds
   the frame rate steady whichever tier runs, so frametime is the one signal the
   policy's own decisions cannot invalidate. Two ways out, both meaning "the
   tier is the limit again": pacing degrades past the reference by more than
   15%, or the card is flat out at 90%+.

3. Re-test the cap on the tick its latch is released. Observed live: a latch
   dropped because pacing regressed past it, and the same tick promoted to the
   top tier — with the card at 58% and the CPU at 10%, where nothing was short
   of clock. "This reference stopped explaining the pacing" is a different claim
   from "the tier is the limit now", and only the second justifies climbing. The
   asymmetry is what makes it matter: a promotion takes one window, every step
   back down pays its dwell.

4. Ease the tier down when nothing is being played, and make all three
   utilisation bars configurable. Adaptive paces on frames, so with nothing
   presenting it held whichever tier the last game left behind — a tuned card
   sat on Performance for as long as the desktop stayed idle. An idle desktop
   and a game we cannot measure look identical from the policy's seat;
   utilisation separates them, and the margin is not close (idle desktop with a
   compositor and a browser reads 3–4%, a game runs 50–90% even under an
   external cap; the default bar sits at 20%). Entry is slow, exit immediate,
   and with no utilisation reading at all the tier is held rather than lowered —
   absence of a measurement is not evidence of an idle machine.

Compatibility. Both new spec fields are serde-defaulted, so a client
predating them still resolves against a strict deny_unknown_fields spec. The
daemon enforces the ordering of the three bars rather than clamping quietly.

Verification. cargo test, cargo fmt --check, cargo clippy clean; full
pytest suite green. The oscillation test replays the measured utilisation climb
(30% → 85%) and asserts the tier only ever moves down; it was reproduced from
the live log before the fix.

This is the one I would most like your @jpietek opinion on before it becomes a PR,
since it changes tier-switching policy rather than fixing a bug in it.

[jpietek]

I think I could take this framerate cap for the weekend/monday testing on my GPU along with this one: #61.

Will verify accross my Steam lib on 5080, thanks. BTW what GPU do you have for testing? I'm particularly looking for somebody with 5090 for extensive testing, but with current pricing - well can't afford that...

[Ernold11]

I test on an RTX 5070 Ti at UWQHD (3440×1440), with the FPS target set to 100 across all my testing.

That combination is what made the frame-cap behaviour easy to hit and reproduce — plenty of game menus and cinematics sit at a hard 60 or 30, well below that target, so the mismatch shows up constantly rather than as a one-off.

[jpietek]

OK, not a lot of time for gaming, but I'm pushing on the game frame rate cap, there might be multiple ways to cap it right? So probably we need to test these scenarios:

1. No tool at all: open a game whose menu locks at 60/30 — the author's actual repro - this was your case right - which game exactly, what display/graphic options?

2. DXVK_FRAME_RATE=60 %command% in Steam launch options — built into DXVK, nothing to install, works for any D3D9/10/11 title under Proton (VKD3D_FRAME_RATE for D3D12 titles).

3. MangoHud: mangohud %command% with MANGOHUD_CONFIG=fps_limit=60.

4. gamescope: gamescope -W 3440 -H 1440 -r 60 --framerate-limit 60 -- %command% — the feature you were thinking of.

5. libstrangle: strangle 60 %command%.

[Ernold11]

Good question — the policy doesn't care how the cap is imposed, only what it
looks like in telemetry: frame rate held steady while the GPU is loafing. Entry
is GPU util at or below the cap bar (40% default) with the CPU not saturated;
after that it latches onto the pacing measured at that moment and stops
consulting utilisation entirely, until pacing degrades past 1.15x or the card
goes flat out at 90%.

So for the in-process limiters — DXVK_FRAME_RATE / VKD3D_FRAME_RATE, MangoHud
fps_limit, libstrangle — I'd expect behaviour identical to the in-game menu
lock. They all throttle present inside the game process, the render loop blocks,
and the GPU genuinely idles. Same signature, same recognition. Worth testing all
three anyway, but I'd be surprised if they diverged.

gamescope is the one we should treat separately — it needs a deeper look,
since it sits outside the game process and may pace presentation without
the GPU ever going idle.

One caveat on the measurement side: we read pacing from the NVAPI latency
markers, i.e. the game's own frametime. For in-process limiters that's the same
number the player sees. Under gamescope it may not be — the game could be pacing
at 100 internally while the display gets 60.

Useful side effect of your list: DXVK_FRAME_RATE gives a deterministic repro
that doesn't depend on finding the right menu or cutscene. Probably the best one
to test against first.

My repro: RTX 5070 Ti, UWQHD (3440x1440), FPS target 100 across all testing, in
AC Shadows. Menus sit at a hard 60, well under the target, so the mismatch
shows up constantly rather than as a one-off.

[Ernold11]

Lutris tab proposal with extra daemon information at the top of the window.

[Ernold11]

Yup, call it Game Library and support Lutris and Steam for now. Hopefuly Lutris also has some simple api to retrieve all the games and apply the cmdline to selected/all of them. That was my main motivation, copy pasting the cmdline string for 100+ games was super annoying.

Remember to prompt always to keep exisiting functionality intact. So keep steam in separate dir, have specific api, interface, abstraction for a "launcher". Then have 2 impl steam - as is, lutris in separate Lutris directory in the src tree.

BTW I will setup Lutris on my box and import my GOG game library for testing too.

On the Lutris API — yes, it has one. Games live in a SQLite db (~/.local/share/lutris/pga.db), per-game config is YAML in ~/.config/lutris/games/*.yml, and there's a CLI to list the library. So bulk-setting the command line is doable without clicking through 100 games one by one ;)

I'll try to come back with a working implementation - Game Library with Steam and Lutris combined.

[jpietek]

Cool, we can schedule this for 0.8.0 and focus 100% on this + some smaller features you've pushed like capped frame rates.

[Ernold11]

Sounds good. I'll go through what smaller bits I still have locally and share what in my opinion is worth pushing.

#60 can go in whenever — it's docs only, no code paths touched.

[jpietek]

Okay try to keep it as simple as possible for the user. Some scan now, or even autoscan on first entry to Game Library. So we detect on our own what launchers are available on the system and auto import what's possible. And then just some little icon steam (we can reuse the one I have for tab) and icon for Lutris to indicate which game belongs where. We sort by alphabetical order and play time right now.

[Ernold11]

I’ve already burned through quite a few tokens on the Game Library, trying to stick to your suggestions and the project’s overall direction. If I have some time, I’ll try to push something today. For now, it’s only Steam and Lutris, but I’ll also be working on the Heroic integration. In my opinion, it’s looking pretty promising so far.