Library overview

OpenBoxGL presents imported games in a searchable grid or list. Select a card to open its detail pane, where metadata, artwork, launch, saves, and history stay together. The top bar is grouped into three zones:

• The Library zone holds Library, Set up library (#setupLibraryButton), Add game, and Import folder.
• The Actions zone holds Big Box, Running, Queue, and Activity (#activityButton with live running operation count).
• The Tools menu (#toolsButton) is organized into four accessible WAI-ARIA semantic groups:
  1. Library: Metadata, Media, Health, Bulk Edit, Tags, Playlists, Backup, History, Achievements, Save Filter, Save Preset.
  2. Sources: Storefronts, Emulators, Import Steam, Import Heroic, Import Lutris, Import Arcade, Discovery.
  3. Personalize: Themes, Plugins, Settings, Fullscreen.
  4. Automation: Webhooks, Notifications.

Browse and search

The sidebar offers, from top to bottom: a Search field, a View selector, an ESRB filter, Categories, Platforms, Playlists, Collections, Filter presets, and Explorer. Collections (v1.12.0) lists named shelves saved from the query bar — a collection stores the query text, not a snapshot, so membership re-evaluates live as the library changes (see Backlog Radio). The View selector includes: All games, Favorites, Recently played, Never played, In progress, Completed, Installed only, Owned / not installed, Has saves, Hidden, and Missing files.

Search supports field-targeted terms, quoted values, and negative terms. Prefix a term with - to exclude it:

• title:hollow matches names, sort titles, and alternate names.
• platform:"PlayStation 2" matches a literal platform value.
• -tag:demo excludes games carrying a demo tag.
• dev:team matches developer, pub: publisher, series:, genre:, region:, notes:, source:, store:, progress:, rating:, favorite:, installed:, hidden:, broken:, portable:, controller:, and tag: all work.
• installed:yes / installed:no and favorite:yes / favorite:no filter booleans.

Bare terms search name, sort title, alternate names, platform, genre, developer, publisher, series, region, notes, source, play mode, status, progress, controller support, and tags. Short bare terms also match title initials and acronyms (e.g. oot matches Ocarina of Time).

Sort options are Title, Rating, Recently played, Recent activity, Play time, Date added, Platform, and Genre. The arrange bar on the right edge jumps through the current sort's groups; it appears once the view has at least four groups. The Surprise me button (or Ctrl+Alt+Q / Ctrl+Alt+R) selects/focuses a random game in the grid (the Surprise Me button / "Just surprise me" opens the picker), which scores the current view by available time, mood, familiarity, and players — with a "Just surprise me" fallback for a purely random pick. See Discovery.

The image group dropdown changes which artwork shows on cards: Box fronts, Backgrounds, Screenshots, Clear logos, Fanart, Banners, Box backs, Box spines, 3D boxes, Title screens, Icons, Cart fronts, Cart backs, Discs, Ads / flyers, and Manuals. The choice can be remembered per platform or per playlist from the dropdown's save action. List view shows Title, Platform, Genre, ESRB, Progress, Plays, and Rating columns.

Select multiple games by holding Ctrl or Shift while clicking cards. This enables Bulk Edit, which can change platform, genre, progress, rating, favorite, hidden, ESRB, and reset play statistics on every selected game at once. Right-click any card for the context menu: Play, Toggle favorite, Edit metadata, Mark progress, Reset play statistics, Add to playlist, New playlist from game, and Remove from library. The Edit Game dialog includes Previous and Next buttons to cycle through the filtered library without closing the modal.

Game details

The detail pane shows a hero with background art, name and platform, a PLAY button (or INSTALL for owned-but-uninstalled Gameyfin entries), favorite toggle, Edit metadata, Find metadata, Use Steam data (for Steam entries), Capture screenshot, Download bezel, Remove game, and Gameyfin Uninstall where applicable. Below are Information facts (release date, developer, publisher, ESRB, source, category, custom fields, max players, controller support, disc count, play time, launches, last played, progress, rating, region, play mode, Wikipedia, video URL), description and notes, extras (applications, alternate versions, documents), video and music players, a screenshot gallery, extended artwork groups, Related Games, RetroAchievements, and Save management with save discovery, backups, Ludusavi and Hoard actions. The pane also carries detail tabs: Overview, Moments, and Story (v1.12.0) — the Story tab narrates the game's deterministic timeline (added, first played, longest session, playtime milestones, progress, captured Moments) served by GET /api/v2/story.

A platform selected in the sidebar shows a platform panel with statistics (games, completed, play time, launches, favorites, missing files), Play random, Last played, Most played, and an Edit platform documents list of manuals and reference files.

Organize safely

Use Importing, Organizing, and Queue, tags, and notifications for focused procedures. The Health button opens the Library Audit, which carries a health score (v1.14.0): a 0–100 number built from five weighted dimensions — file integrity (35), duplicates (20), artwork (20), metadata (15), and launch readiness (10) — where every deduction names its games. The audit still flags duplicate identities, missing game files, missing box fronts, missing extras (applications, versions, documents), missing save paths, and ROMs without an emulator profile; click an issue to jump to that game. The health card's breakdown dialog lists per-dimension issues with a Fix all in this dimension queue that shows a dry-run preview first and is undoable. A scheduled rescan (daily, weekly, on startup, or off; default weekly) skips active game sessions, and Big Box shows a health tile with re-scan.

Artwork Doctor scans for missing covers, missing files, low-resolution and wrong-aspect artwork, and duplicate images, then fixes all with SteamGridDB in one cancelable batch job — every replacement is attributable to its provider and undoable per batch. The missing-file repair wizard scans for missing game and media paths, matches them against a folder you pick, and relinks only the matches that are still missing, skipping anything that changed since the scan. Duplicate detection groups identity, path, and title collisions; the merge preview picks the record with the most play history, unions media and list fields, and moves absorbed entries to the Trash so merges are reversible — the health dialog's dedupe button opens the merge dialog. Remove duplicate entries inside the audit deletes only the duplicate library entries, never game files.

Media opens the Media Manager with a per-platform audit (games, database matched, missing box front, missing background, missing screenshots), bulk downloads for matched games, and Find duplicate media, which separates a dry-run from Delete duplicate media and can be scoped to a single platform or the entire collection. Duplicate detection hashes cover, background, and screenshot files; deletion only touches files inside the OpenBox data directory, never symlinks.

Removing a game asks twice: first to confirm the library entry removal, then whether to also delete the game's listed media files. Game files are never deleted. Settings also offers Remove all imported Steam games, which removes only Steam entries and keeps files and media.

Source and status

Capability status belongs to the parity matrix, maintained from PARITY.md. Library data lives in ~/.local/share/openbox-game-launcher/library.json unless OPENBOX_DATA_DIR points elsewhere. State is schema version 6, written atomically with a .bak last-known-good copy beside it; recovery is covered in Data and recovery.

Large libraries (5,000+ games) self-enable the SQLite FTS read model unless OPENBOX_ENABLE_SQLITE_READ=0 opts out, and an opt-in weekly automatic backup keeps 4 archives on a 7-day schedule — see Organizing, API 1.12 additions, and Library backups.