// OPENBOX DOCS
SteamGridDB artwork and launcher trophies
Configure optional SteamGridDB artwork and understand OpenBox's separate deterministic trophy case.
OpenBox includes an optional SteamGridDB artwork provider and a separate local OpenBox launcher trophy case. SteamGridDB improves art coverage; launcher trophies summarize what your local library and play history already prove. Neither feature requires an OpenBox account.
SteamGridDB artwork
- Put
STEAMGRIDDB_API_KEY(aliasOPENBOX_STEAMGRIDDB_API_KEY) in an owner-only~/.envfile or another supported environment file. - Leave Enable SteamGridDB artwork provider on in Settings → Integrations, or turn it off when the provider should not be contacted.
- In the metadata dialog, use Search SteamGridDB for one game or Fill missing art via SteamGridDB for a bulk job.
- Review the selected result and media kinds before applying it.
The provider can supply covers, backgrounds, clear logos, icons, and banners. SteamGridDB results carry the steamgriddb source label, participate in the configured metadata provider priority, and are a valid source for the durable media queue (pause, resume, cancel, retry, per-item errors). OpenBox sends HTTPS requests to SteamGridDB, keeps a local disk cache, rejects unsafe media URLs, and reports provider/rate-limit failures as integration errors. The API key is never returned in settings or diagnostics. An optional per-provider SteamGridDB integration token can also be stored from Settings under Integration tokens; it is kept out of the public settings view and shown masked (see Accounts and media). Without a key, or after the provider is disabled/rejected for the session, the rest of the library and other providers continue to work.
Useful routes are:
GET /api/v2/steamgrid/status— enabled/configured/provider and cache status;GET /api/v2/steamgrid/search?q=TITLE&limit=12— bounded autocomplete results;POST /api/v2/steamgrid/test— test the configured key;POST /api/v2/steamgrid/infowith{"steamgrid_id":"ID"}— normalized metadata/media for review;POST /api/v2/steamgrid/apply— queue selected metadata/media for one stable game id; andPOST /api/v2/steamgrid/match— queue a bulk fill for explicit ids or games missing covers.
Apply and bulk match return 202 with a job_id; inspect it through Background jobs. The provider is optional, external, and subject to its own account terms and rate limits.
OpenBox launcher trophies
The local Trophy Case opens from the View Trophy Case button in the success toast that appears when a new launcher trophy is awarded. The toast expires after a few seconds, and there is no persistent Trophy Case item in the 1.18 Tools menu. Tools → RetroAchievements account opens the separate RetroAchievements account dialog, not this local case. The evaluator reads only the current library and recorded history. It stores earn timestamps so an award toast is shown once, but awards are never revoked when metadata or history later changes.
| Trophy | Rule |
|---|---|
| Century Club | 100 hours of total playtime |
| Collector | 100 games in the library |
| Completionist | Beat or complete 5 games |
| Curator | 25 games with cover art |
| Decade Tourist | Play games from 4 different decades |
| Deep Diver | Spend 20 hours in one game |
| First Launch | Finish the first session |
| Marathon Runner | Play a 4-hour session |
| Night Owl | Start a session after midnight (local time) |
| Old School | Play a game released before 1990 |
| Platform Hopper | Play games on 4 different platforms |
| Every Second Counts | Play 7 days in a row |
GET /api/v2/insights/trophies returns each trophy's id, awarded, awarded_at, and live progress. POST /api/v2/insights/trophies/evaluate persists newly met awards and returns newly_awarded, earned, and total. This is a launcher-level local feature, not a replacement for the optional RetroAchievements account, sets, or emulator injection.
See Media providers, RetroAchievements, and API 1.11 additions for provider credentials and route details.