// OPENBOX DOCS

Handheld performance

Apply optional per-launch handheld performance profiles.

Performance profiles apply a TDP limit through ryzenadj before a game launches, and optionally restore a configured value when the session ends. They are per launch profile: either a platform profile or a per-game launch profile override.

Handheld performance limits are a Linux feature: they use ryzenadj on Linux only. On Windows and macOS the Handheld performance controls are hidden.

Setup

In Tools → Emulators & controllers, after a profile exists (for example GameCube = dolphin-emu -b -e {path}), the Handheld performance section lists each profile with:

  • Enable TDP checkbox
  • Limit (W): the TDP applied at launch (0-60, step 0.5)
  • Restore (W): the TDP applied when the session ends (0-60, step 0.5)

Limits are stored in watts and converted to milliwatts for ryzenadj -stapm-limit=<mW>. A profile with only a limit and no restore value applies the limit at launch and does nothing on close.

When limits apply

The Apply handheld performance limits setting (Settings) has three modes:

  • auto (default): applies only when OpenBoxGL detects a gamescope guest (Steam Deck / Bazzite game mode) or a battery-powered host (/sys/class/power_supply/BAT* present).
  • always: applies on any host.
  • off: never applies.

Because auto gates on battery or gamescope, a desktop session never applies or restores a limit. The same gating decides restore, so a session that never applied a limit does not try to restore one.

Battery reporting (v1.18.0)

Big Box shows a battery indicator in its status bar when a battery is present; Show the battery indicator in Big Box (battery_indicator, default on) controls it. The indicator uses the browser Battery Status API when available and otherwise calls GET /api/v2/native/battery, which reads the first BAT* device under /sys/class/power_supply on Linux, pmset -g batt on macOS, and GetSystemPowerStatus on Windows, and returns present, percent, and charging. A host with no battery returns present: false.

This indicator is display-only. The auto performance gate keeps its own battery check and is unaffected by turning the indicator off, so hiding the badge never changes whether a TDP limit applies. Big Box requests the reading when it opens and reuses the 60-second cache, which keeps it off the launch hot path.

Failure behavior

Missing ryzenadj on PATH, a permission failure, a non-Ryzen CPU, or a malformed TDP value are logged as warnings and do not block the game launch. The apply and restore helpers never raise; the profile resolution falls back from a per-game launch_profile override to the game's platform when the override does not name an existing profile.

Library scale and test gates

Formal support graduates to 50,000 games on the Rust backend (ADR 0116); blocking performance gates cover 10k and 20k libraries (perf-20k in CI; docs/development/PERF.md), and scripts/check_tests.py enforces 85.0% total and 62.0% web_app.py coverage floors for the Python fallback. The optional SQLite FTS read model self-enables at 5,000+ games (OPENBOX_ENABLE_SQLITE_READ=0 opts out) for indexed search and facets on large libraries; in 2.0 it rebuilds on a background thread and falls back to source: "json" while stale, and JSON remains canonical. See API 1.12 additions and Configuration.

Safety

Hardware-specific permissions remain host configuration; OpenBoxGL stores no root credential. ryzenadj runs with a 10-second timeout and only ever receives -stapm-limit=<mW> arguments. If the limit should not persist, configure a restore value so the session end restores it; keep in mind the restore is skipped when the apply was skipped under auto.