Big Box and handhelds

Big Box is the fullscreen controller-oriented view of the app. Click Big Box in the top bar (or launch with ?deeplink=bigbox; OpenBoxGL also opens Big Box automatically when it detects a gamescope guest session).

Starting in Big Box

Settings → Big Box has a Start in Big Box mode checkbox (bigbox_start_at_launch), and the --bigbox CLI flag (see CLI reference) opens the UI with ?deeplink=bigbox — so a Deck or HTPC can boot straight into Big Box like Steam Big Picture.

Layouts

Settings, Big Box layout, chooses among three modes:

• Stage: one large cover and description with a big Play button.
• Hybrid: a platform rail on the left plus the current platform's games and a scoped Search this platform field.
• CoverFlow: a horizontal cover strip with jewel-case styling; the active cover straightens and scales.

The footer shows the control legend: ← → Browse, Enter / A Play, P Pause, M Filters, F / X Favorite, Esc / B Back.

Navigation and menus

Keyboard arrows (and gamepad left stick / d-pad, or a gamepad's mapped buttons) move through the list. The gamepad mapping is configurable in Settings (buttons 0-31 per action):

Filter and sort menu

Pressing M (or Start on gamepad) opens the Filter and Sort menu with 4 interactive select dropdowns navigateable via controller:

1. Show: All games, Installed, Owned, Favorites, In progress, Completed.
2. Sort: Title, Rating, Recently played, Recent activity, Play time, Shuffle.
3. Quick preset: Filter presets pinned in the desktop UI.
4. Achievements: All, RetroAchievements matched, Not matched.

Controller prompt packs

Activating a controller media pack (controller-xbox or controller-playstation) via Settings or POST /api/premium/media-packs/apply automatically updates the on-screen button legend and prompts to match your physical gamepad layout (controller_prompt_pack). Toggle on-screen button hints with controller_prompt_hint.

The screensaver / attract mode shows a rotating random game after a delay. Settings has two related fields: Big Box screensaver delay (screensaver_seconds, default 90) and Attract mode delay (attract_mode_seconds). The screensaver reads attract_mode_seconds, which falls back to screensaver_seconds when unset, and the Settings dialog keeps both in sync with the same fallback. Both are 0-3600 seconds (0 disables; values 1-29 are rejected). Any control returns; Play launches the displayed game. The screensaver uses the game's background or cover and plays its video when present. An optional Big Box startup video plays on entry, and Library background music with an optional Mix video audio with background music toggle (lower music volume when mixing) plays in Big Box. Battery level and the controller prompt hint display in the Big Box status bar.

Big Box shutdown commands run when switching into Big Box; they are not run when leaving it.

On-screen keyboard

When the hybrid search takes focus, a d-pad-navigable QWERTY + symbols grid opens and types into the search via input events, reusing the existing filter. It sits on the gamepad loop just below the pause overlay, so the pad keeps driving the grid everywhere else.

Health tile

Big Box shows a library health tile with a re-scan action, so you can check the 0–100 health score and re-run the audit without leaving the couch.

Themes and media packs

Big Box uses the same CSS themes as the desktop UI (see Themes), including per-platform themes. Bundled media packs add platform clear logos, Xbox or PlayStation controller prompt packs (which also change the on-screen hint), and core status badges.

Steam Game Mode (handhelds)

On Steam Deck, Bazzite, and other gamescope sessions, OpenBoxGL runs as a guest inside Steam's gamescope session so Steam Input, the Quick Access Menu (TDP/FPS), and MangoHud stay with Steam.

1. Install the AppImage (preferred on SteamOS, Bazzite, and other immutable images).
2. In Desktop Mode, add a non-Steam game pointing at the AppImage with launch options or target args including --game-mode.
3. Enable Steam Input for that shortcut if you want controller profiles in Big Box.
4. Return to Game Mode and launch OpenBox. It opens Big Box fullscreen.

After shortcuts are applied, Steam Bridge copies cached SteamGridDB artwork (cover → capsule, background → hero, clear logo → logo) into the account's Steam grid directory, so bridged games are no longer grey tiles in Game Mode. Original bytes are copied as-is (no resize); skips are logged and reported, and nothing is ever written outside a detected Steam account directory.

Under gamescope, OpenBoxGL detects the guest via environment (GAMESCOPE_WAYLAND_DISPLAY, STEAM_GAMESCOPE_RESTRICTED, or a gamescope desktop name) and opens Big Box fullscreen in the native window. In the web fallback (--web, or when the native host is missing), the UI opens in a kiosk browser (Chromium, Chrome, Brave, or Edge, native or Flatpak), and OpenBoxGL marks that window with a dedicated STEAM_GAME id (413091001) so it is visible under gamescope. Steam titles launched from OpenBox still go through Steam (steam -applaunch / steam://), so Steam Input and overlays keep working. Non-Steam games get a stable synthetic STEAM_GAME id derived from their identity, in the range 700,000,000 to 899,999,999.

Do not wrap OpenBox in another gamescope while already in Game Mode. On a normal desktop, behavior is unchanged unless you pass --game-mode. The Flatpak build relies on host tools for the kiosk-browser window tagging, so prefer the AppImage for Game Mode.

Steam Input profiles stay scoped to your shortcut; the STEAM_GAME tagging is only a window property. OpenBoxGL does not control TDP; use Steam's QAM or your image's handheld tools. Developers can approximate Deck/Bazzite Game Mode on a desktop with ./scripts/emulate_deck_gamemode.sh (requires gamescope; runs a nested session with SteamDeck=1 advertising).

See Handheld performance for the TDP profile behavior supported by the current release.

Gamescope presets (v1.7.2)

Settings → Controller includes a gamescope preset selector with 8 display profiles for handheld and desktop use:

When a preset is selected, OpenBoxGL applies the corresponding gamescope command-line arguments on game launch. The preset does not affect the OpenBoxGL window itself — only the games it launches.

Custom gamescope presets (v1.8.0)

Settings → Controller also supports user-defined presets: up to 16 custom presets with unique names and bounded integer arguments. A custom preset whose name matches a stock preset shadows it. A per-game gamescope_preset override (set in the game editor's Launch tab) wins over the global preset at launch.

MangoHud performance overlay (v1.7.2)

Settings → Controller includes a MangoHud toggle. When enabled, MANGOHUD=1 and MANGOHUD_CONFIG=font_size=24,no_display are set in the environment when launching games (pkg/parity/parity_gamescope.py:580-581), causing the MangoHud on-screen performance overlay (FPS, CPU/GPU usage, frame pacing) to appear. MangoHud must be installed on your system separately.

Controller bench (v1.7.2)

Settings → Controller includes a controller bench tab with a live SVG gamepad visualization. The bench reads navigator.getGamepads() and renders button presses, stick positions, and trigger values in real time, so you can verify controller connectivity and mapping without launching a game.

Game Night party mode (v1.9.0)

Game Night (Big Box → Game Night) turns Big Box into a couch-multiplayer party screen: set players (2–8) and session length, build a queue of party-friendly games, spin the wheel to pick, launch, and advance rounds. The queue and round index persist across restarts. Control it with a gamepad or keyboard (arrows/Enter/N/Escape). Backed by POST /api/v2/party/queue, GET /api/v2/party/queue, and POST /api/v2/party/next.

Video snaps in stage mode (v1.9.0)

Big Box stage mode plays looping gameplay videos behind the selected cover when a video is available, with a 600ms debounce so fast scrolling stays smooth, background-music ducking while video audio plays, and prefers-reduced-motion support. Without a video it falls back to the static cover.