Organizing

OpenBoxGL organizes a large catalog through favorites, collections, saved filters, ordered manual playlists, custom fields, ESRB filters, platform categories, and bulk edits.

Filters and views

The sidebar View selector covers All games, Favorites, Recently played, Never played, In progress, Completed, Installed only, Owned / not installed, Has saves, Hidden, and Missing files. The ESRB filter narrows to E, E10+, T, M, AO, RP, or Unrated. Categories group platforms into Nintendo, Sony, Microsoft, Computer, Arcade, Adventure, and Other by default, overridable in Settings. Explorer facets count and filter by genre, developer, publisher, platform, progress, and ESRB with up to 40 values per field; clicking a facet applies it, and an "Unset"/"Unrated" label covers empty values.

Save Filter stores the current platform, category, view, search query, ESRB, and progress as a playlist-style rule set. Save Preset does the same but keeps the rules as a filter preset, optionally pinned as a Big Box quick preset (marked with a star in the sidebar, selectable from the Big Box Filter and Sort menu). Both appear in the sidebar; presets restore their rules when clicked and can be deleted with the × button.

Visual chip builder (v1.7.2+)

Filter presets render as visual chips — compact badges showing the field, operator, and value for each rule (e.g. platform = SNES, genre contains RPG, favorite = true). Chips are generated from the underlying JSON rules via rules_to_chips() and convert back via chips_to_rules() with round-trip fidelity, so editing a chip and saving produces the same rule structure as before. This makes complex collections with many rules easier to scan and edit at a glance.

Playlists

Open the Playlists dialog for New manual playlist and New filter playlist. Manual playlists keep an exact ordered set of games; the manager shows each member with up and down buttons to reorder, plus notes and an optional parent playlist for grouping. Filter playlists store the same rule set as a saved filter and update membership automatically from their rules. Add games to a manual playlist from the context menu or the queue dialog. Deleting a playlist only removes the playlist, never the games.

Smart collections (v1.12.0)

The query bar's Save as collection chip pins a Backlog Radio query as a named sidebar shelf. Unlike a manual playlist — a fixed member list — a smart collection stores only the query and re-evaluates it at read time, so membership stays correct as games are added, played, or re-tagged. Collections live in the sidebar Collections section (at most 50 names), are backed by GET/POST /api/v2/collections and POST /api/v2/collections/delete, and an unparsable saved query evaluates to zero matches rather than an error. See Backlog Radio for the grammar they store.

Game Story timelines (v1.12.0)

The detail pane Story tab narrates one game's deterministic timeline via GET /api/v2/story — a pure read projection over the game record, the session journal, and captured Moments, so it can never go stale. Event kinds are added, first_played, session (longest only), milestone, progress, and moment (parity_story.py:17). Playtime milestones fire at 1h, 5h, 10h, 25h, 50h, and 100h (MILESTONE_SECONDS). See Library overview for where the tab lives.

Large libraries and automatic backups (v1.12.0)

Collections and search run through the same read path documented in API 1.12 additions: the SQLite FTS read model self-enables at 5,000+ games (SQLITE_AUTO_THRESHOLD in pkg/state/sqlite_readmodel.py:30-34); set OPENBOX_ENABLE_SQLITE_READ=0 to opt out — the opt-out is never overridden. JSON remains the source of truth either way. Whole-library protection is the opt-in weekly automatic backup (AUTO_BACKUP_DAYS = 7, AUTO_BACKUP_KEEP = 4 in pkg/parity/parity_backup.py:27-28, last_auto_backup stamp; missing or unparsable counts as due). See Library backups for the manual engine the schedule reuses.

Fields, badges, and bulk edits

The Edit metadata dialog covers name, platform, genre, year, developer, publisher, series, region, play mode, sort title, progress, ESRB, rating (0 to 5, step 0.5), max players, Wikipedia and video URLs, alternate names, video snap/theme/trailer/recording paths, game path, cover/background/video/music paths, controller support, disc count, extended artwork (clear logo, fanart, banner, icon, box back, box spine, 3D box, title screen), screenshots, RetroAchievements Game ID, launch command override, launch profile override, gamescope preset override, per-game launch_env environment overrides (KEY=value lines) and the launch_confirm confirm-before-launch flag (v1.12.0), archive extraction, Big Box hide, hidden, broken, portable, archive member, applications, alternate versions, documents, save paths, description, and private notes.

collection is a separate grouping field populated by imports (Steam, Heroic, Lutris, Gameyfin, Arcade, Xbox 360) and shown and filtered in the native window. It feeds the Related Games scorer (two games with the same collection score higher). The UI does not currently expose an editable collection control or a collection: search term, so its value is set by imports and surfaced through related-game reasons rather than by hand.

Custom fields are defined in Settings as Name|Option1,Option2 lines (up to 20 fields, 50 options each). They appear as editable values on each game and can be bulk-applied.

Bulk Edit works on any multi-selection: platform, genre, progress, rating, favorite, hidden, and ESRB. Only supplied values change; rating must be 0 to 5, progress must be one of the known statuses, and favorite/hidden must be true or false. Tags can be replaced or adjusted per game (see Queue, tags, and notifications).

Progress automation (Settings) can mark a game Playing after N minutes of play and Paused after N days idle, and a Progress status on first play setting stamps the first launch.

Health audit and duplicates

The Health button runs a Library Audit over the whole library: duplicate identities, missing game files, missing box fronts, missing extras (applications, versions, documents), missing save paths, and ROMs without an emulator profile. Each issue lists the game and the specific problem, and clicking an issue selects that game. The audit's Remove duplicate entries removes only duplicate library entries; game files stay on disk.

Media opens the Media Manager: a per-platform audit (games, database matched, missing box front, missing background, missing screenshots), bulk media downloads, and duplicate-media cleanup with a separate dry-run and apply step. Duplicate detection hashes cover, background, and screenshot files; the apply step deletes only files inside the OpenBox data directory and never symlinks.

Library health score (v1.14.0)

The Health dialog no longer just lists problems — it scores the library out of 100 and tells you where the points went. The score is the weighted sum of five dimensions, and every deduction names the games behind it, so a number is never the whole answer:

The health card sits at the top of the audit, and Breakdown opens a per-dimension dialog listing the exact issues in that dimension. Each dimension has a Fix all in this dimension queue that shows a dry-run preview first and stays undoable — nothing is changed before you approve the plan, and every fix can be reversed. A health tile in Big Box shows the current score with a re-scan action, and a scheduled rescan (daily, weekly, on startup, or off; default weekly) keeps it fresh without getting in the way of a game you are actually playing.

Artwork Doctor (v1.14.0)

The Artwork Doctor is the artwork half of that work, run as one cancelable batch job. It scans the artwork fields — cover, hero, background, clear logo, icon, and banner — for missing covers, artwork files that are missing on disk, low-resolution and wrong-aspect images, and duplicate cover images, then fixes all of them with SteamGridDB. Every replacement is recorded against the provider it came from, and the whole batch is undoable — the same "preview, then apply, then undo if you disagree" contract as the rest of the health fixes. Missing game files are not its business: that is the health score's file_integrity dimension, and the missing-file repair wizard is what relinks them.

Repair missing files and merge duplicates (v1.14.0)

Two wizards turn the health report into fixes:

• Repair missing files scans for missing game and media paths, matches them against a folder you pick, and relinks only the matches that are still missing — anything that changed since the scan is skipped rather than guessed at, so a half-moved folder cannot get a wrong link written.
• Merge duplicates groups identity, path, and title collisions and shows a merge preview. It keeps the record with the most play history, unions media and list fields, and moves the absorbed entries to the Trash so a merge is reversible rather than destructive. The health dialog's dedupe button opens it.

The API equivalents are GET /api/v2/library/health and /health/issues for the snapshot and issue lists, POST /api/v2/library/health/scan and /health/fix to run and apply, GET/POST /api/v2/library/repair with /repair/preview and /repair/apply for the missing-file wizard, and POST /api/v2/library/duplicates/merge for the merge.

Safe deletion

Removing a game asks twice: first to confirm removing the library entry, then whether to also delete the game's listed media files. Game files are never deleted. Settings has Remove all imported Steam games for wiping Steam entries only. The audit and duplicate tools also report before they change anything. Keep a backup when the operation affects files; see Sessions, saves, and backups.

Stable game IDs keep edits, session history, queue entries, and saves attached when library order changes. If two imported entries share an identity (for example the same Steam App ID), the health audit flags them as duplicates.