// OPENBOX DOCS

Organizing

Use search, filters, collections, playlists, and safe library operations.

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.

Platform and category filters cycle through three states — include, exclude, clear — on repeated clicks. The Source filter is a dropdown with a separate Exclude checkbox, and a smart collection loads its saved query into the search box rather than cycling. Excluded values show as "Not <field>: <value>" chips and are written to the URL hash, so a refresh restores the exclusions along with the rest of the view.

Presets and playlists accept more than the sidebar controls expose: source, achievements-source, and region rules, plus a text operator (contains_any / not_contains_any) for genre, developer, publisher, and region. Every rule key except view and platform_category can also appear in an exclude block, which rejects matching games rather than adding them — up to 20 values per field, and a refresh keeps the block intact.

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 (crates/openbox-discovery). 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 crates/openbox-store/src/sqlite_readmodel.rs); set OPENBOX_ENABLE_SQLITE_READ=0 to opt out — the opt-out is never overridden. In 2.0 the projection rebuilds on a background thread after writes, and a query that lands before the rebuild falls back to the canonical library with source: "json" — 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 crates/openbox-sync/src/backup.rs, 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).

Bulk Edit also offers find and replace across the selection: choose a metadata field (name, notes, genre, developer, publisher, platform, region, or source), type the text to find and its replacement, and review the preview first — it lists up to 100 affected games with their before and after values and reports how many more were truncated. Apply then writes the same literal replacement to every match. There is no regular-expression mode, so a $ or \ in the replacement is just a character. The preview is a dry run by default; nothing is written until you apply, and the API route (POST /api/v2/bulk/find-replace) behaves the same way. The API also accepts progress and esrb as find fields, but the dialog offers neither.

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. Which labels are offered at all is configurable: Settings → Sessions & Saves → Progress values allowed by automation and the game editor takes a comma-separated list (default Unplayed, Playing, Paused, Beaten, Completed, Mastered, Abandoned). Progress automation and the game editor only show enabled labels, and the API rejects an ineligible label instead of storing it, so a stored value always matches the current list.

Controller and keyboard remapping (v1.18.0)

Settings → Controller records the keyboard shortcuts for play, back, menu, pause, paging, search, settings, and the reader, and maps gamepad buttons to the same actions. A mapped button can be cleared by emptying its field, and a duplicate assignment is never applied silently: OpenBox asks Swap controller buttons first and swaps the two assignments only after you confirm.

The same Settings category defines the controller types — Gamepad, Arcade stick, Racing wheel, Light gun, Paddle, Trackball, Spinner, Keyboard, Mouse, and VR. A type shows as a chip in the game editor and as one badge per type on a library card, so a shelf that mixes input devices is visible at a glance (crates/openbox-http/src/handlers/settings.rs, static/settings.js:132-175). See Keyboard & Controller Shortcuts for the full table of defaults and rules.

Health audit and duplicates

Library checkup in the Tools menu runs an 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 issue table carries a Source column and per-source issue counts, and a source filter narrows it to one storefront (plugin sources appear under their display name). The audit's Remove duplicate entries removes only duplicate library entries; game files stay on disk.

Bulk platform edits can also move media: tick the option and selected games' media files follow the platform change. The field update is committed even when a move fails, and the response reports the failures in media_errors so you can retry just those files rather than repeat the whole edit.

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 Library checkup 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:

DimensionWeightWhat it measures
File integrity35Game files present and reachable
Duplicates20Duplicate game records — identity collisions, cross-source included
Artwork20Missing media across the media types, weighted by type priority (cover ≫ banner/icon; screenshots as a group)
Metadata15Missing or sparse descriptive fields
Launch readiness10ROM-suffix games with no emulator profile and no per-game override, plus games flagged broken

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.

Platform administration works the same way. Rename platform (in the platform panel) rewrites the platform across games, launch profiles, filter playlists, presets, and platform settings maps, and optionally moves the platform's media folder; Delete platform requires typing the name and moves its games to the Trash. Both are described in Library overview.

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.