// OPENBOX DOCS
Importing
Bring storefronts, executables, ROMs, and arcade sets into one catalog.
OpenBoxGL imports from installed storefront manifests, local ROM folders, standalone executables, and arcade DAT catalogs. Every importer reports how many games were found and added; entries that already exist are skipped, so re-running an import never creates duplicates. Imported games keep a stable identity (Steam App ID, Heroic App ID, Lutris ID, Gameyfin ID, GOG/EA/Ubisoft provider ID, or path) so later imports merge into the existing entry instead of adding a second copy.
Library Setup Center (Recommended)
Click Add games → Guided setup… in the top bar to launch the guided Library Setup Center. Its quick path is six steps — Where are your games?, Check what we found, Review matches, Choose emulators, Import games, You're done — with Welcome and Artwork & details available behind Show advanced options:
- Preview Before Commit: Setup Center performs a read-only scan of folders and storefronts (
POST /api/v2/setup/preview). No changes are written tolibrary.jsonuntil you approve them. - Storytelling Progress: Scans report discovered games, platforms, and actionable decision counts.
- Paginated Review & Candidate Resolution: Review discovered titles in batches (
GET /api/v2/setup/preview/items). Resolve shared extensions (e.g..isomatching PS2 or GameCube) with your chosen platform/emulator. - Idempotent Commit: Confirm your choices (
POST /api/v2/setup/commit). Imported games receive a uniqueimport_batch_idfor instant post-import filtering and batch metadata review.
Direct Folder Import
Click Add games → Scan a folder… (or Add one game… for a single entry) and select an absolute path. OpenBoxGL scans recursively by extension and assigns a platform from the extension table:
.nesNES,.sfc/.smcSNES,.gbaGame Boy Advance,.gbGame Boy,.gbcGame Boy Color,.n64/.z64/.v64Nintendo 64,.ndsNintendo DS,.3ds/.ciaNintendo 3DS,.wbfs/.wia/.wadWii / WiiWare,.rvz/.gcm/.gczGameCube,.xci/.nspNintendo Switch,.pbpPSP,.vpkPlayStation Vita,.xexXbox 360,.cue/.chd/.ciso/.m3uDisc image.sh,.appimage,.exe,.rom,.zip,.7z,.raralso import as-is.
Ambiguous Extension Resolution
Per ADR 0012, shared disc extensions (such as .iso) no longer guess platforms silently. OpenBox flags ambiguous multi-platform extensions (AMBIGUOUS_PLATFORM) and presents explicit platform candidates for user resolution in Setup Center and the launch check. Since 1.16.1, .bin, .cue, and .iso files that several systems share wait for you to choose in the import wizard, and a file cannot import until it has a platform — a guess is never made on your behalf.
When several files share a base name with a (Disc 1), (Disc 2), (CD 1), (Side A) style marker, they are grouped into one entry with a generated .m3u and the game name without the disc marker. Since 1.16.0 OpenBox never overwrites a playlist it did not create: if you had made your own .m3u next to the disc images, an import leaves it alone and imports the game exactly once, rather than replacing your playlist and losing the game it pointed to. When several files map to the same platform and name, only the best-ranked ROM is imported; the runner-up candidates are kept on the entry as version_candidates. Ranking prefers clean regional names (World and USA above Europe, then Japan), penalizes (Beta), (Proto), (Demo), (Sample), (Unl), (Pirate), (Hack), and (Translation) tags, favors .chd, .cue, and .m3u, and treats a missing or unreadable file as the worst score.
After a folder scan OpenBoxGL recommends an emulator per detected platform. If exactly one emulator is suggested it is used; if several are, you pick one interactively. Picking one installs it from Flathub and adds its platform profile.
You can also drag a folder onto the drop zone ("Drop ROM folders or game files here to import") and confirm the path.
Steam
Click Import Steam. OpenBoxGL reads installed libraries from standard Steam roots: ~/.local/share/Steam, ~/.steam/steam, and ~/.var/app/com.valvesoftware.Steam/.local/share/Steam on Linux; ~/Library/Application Support/Steam on macOS; and the Steam install found through the registry and Program Files on Windows. It also reads every library folder listed in steamapps/libraryfolders.vdf. It parses appmanifest_*.acf files for the App ID, name, and install directory, and launches through steam -applaunch {app_id} (or the Flatpak equivalent, falling back to xdg-open steam://rungameid/{app_id}).
Each imported Steam game records whether its install folder still exists. A game whose folder has gone missing shows a red Missing badge and turns its Play button into INSTALL, while an installed game offers Verify Steam files (steam://validate/<id>). See Storefront Manager for both states and how a rescan refreshes them.
Heroic
Click Import Heroic. OpenBoxGL reads Epic, GOG, and Amazon manifests from ~/.config/heroic (or the Flatpak path), plus standalone Legendary installs at ~/.config/legendary. Entries launch through xdg-open heroic://launch/{runner}/{heroic_app_id}. DLC records are skipped.
Lutris
Click Import Lutris. OpenBoxGL runs lutris --list-games --installed --json (or the Flatpak variant) and imports installed entries. Entries tagged Xbox or Game Pass become source Xbox; Origin or EA App entries become EA; Ubisoft or Uplay entries become Ubisoft. Each entry keeps its Lutris numeric ID and launches through lutris:rungameid/{lutris_id}. Cover art is picked up from Lutris coverart folders when present.
GOG Galaxy, EA app, and Ubisoft Connect (Windows)
On Windows, click Import GOG, Import EA app, or Import Ubisoft Connect. OpenBoxGL reads installed games from each launcher's registry entries and manifests, merges by the stable gog_id/ea_id/ubisoft_id, and never duplicates a game on a second import.
- GOG runs the game executable directly, with the executable required to stay inside the install folder. Galaxy overlay and Galaxy cloud saves do not start.
- EA launches through
origin2://game/launch; Ubisoft launches throughuplay://launch/<id>/0. If the launcher is uninstalled, the game stays in the library but will not launch until the handler returns. - A malformed entry or missing install directory is reported in the import's
errorsand skipped. The discovery is read-only and offline. - These catalog imports cover installed games only, and Xbox PC packages are not imported. Each source does have an opt-in Auto-import on startup checkbox (off by default), which re-runs the same installed-only scan every launch.
Faugus Launcher
OpenBox integrates with Faugus Launcher (/api/faugus/*), scanning manifests and prefix directories under ~/.config/faugus-launcher, ~/.local/share/faugus-launcher, and ~/Faugus (plus the matching XDG_CONFIG_HOME/XDG_DATA_HOME locations). It reads installed Wine/Proton games, detects UMU prefix identifiers, and launches via umu-run. Faugus is also available as a source in the Library Setup Center.
Arcade sets
Click Import Arcade, then enter the ROM folder, the source (MAME or FinalBurn Neo), and optionally a DAT/XML path. Without a DAT file OpenBoxGL runs mame -listxml to build the catalog. Imported games are classified as parent, merged, split, or non-merged based on whether the parent archive exists and whether the clone's merged ROMs are present in its own archive, and each entry stores its MAME name as rom_name. The launch command defaults to mame -rompath <folder> {rom_name} for MAME and the detected binary for FinalBurn Neo; you can override it with {rom_name} and {path} tokens. BIOS and non-runnable machines are skipped.
ScummVM, RPCS3, Vita3K
From the Storefront Manager dialog: Import ScummVM reads scummvm.ini and imports each configured game with its section ID as the launch target. Import RPCS3 reads dev_hdd0/game folders and titles from PARAM.SFO. It also reads RPCS3's games.yml — and the games: list of config.yml, in both the native and Flatpak config directories — so external game folders and .iso files installed outside the virtual HDD are imported too; an inaccessible entry is reported and skipped without aborting the scan. Import Vita3K reads ux0/app folders and titles, preferring the Title value from param.sfo when it differs from the folder ID.
PICO-8, MSU-1, and WHDLoad
Three small-format importers live in the same Tools > Imports & extras group:
- Import PICO-8 scans a folder recursively for
.p8carts and exported.p8.pngbuilds, importing each as a PICO-8 title on thepico8-pico8emulator adapter. - Import MSU-1 pairs a SNES ROM with its sibling
*.msuaudio-pack folder. The.msufolder is what makes the ROM an MSU-1 title; a pack with no matching.sfc/.smcROM is reported instead of imported. Each entry recordsmsu1: trueand itsmsu_path. - Import WHDLoad scans an Amiga folder for
.lha,.slave, and.hdfinstalls, skipping the WHDLoad system drawers.
Each is also a POST /api/v2/import/pico8, /msu1, and /whdload route taking the folder to scan.
Gameyfin
The Storefront Manager dialog configures a Gameyfin server URL, optional username and password, and a local install folder (empty by default; the field shows a ~/Games/Gameyfin placeholder). Test Gameyfin connection lists the server's games and download providers. The catalog marks each title owned or installed; Import owned / uninstalled adds owned entries as placeholders with a note, and the Play button on such an entry becomes INSTALL, downloading through the configured provider into the install folder. Install staging protects existing files: a failed download keeps the previous copy, and uninstall refuses paths outside the install directory.
Gameyfin honors the same exclusion rules as every other storefront: a per-title import exclusion keeps a game out of future imports and rescans, and the shared excluded platforms list and include owned-but-uninstalled option apply to its startup auto-import.
Storefront Manager
The Storefront Manager dialog also browses owned versus installed catalogs for Steam, Heroic, Lutris, and Gameyfin, plus installed GOG, EA app, and Ubisoft Connect games on Windows, with Import installed and Import owned / uninstalled buttons for either set. Per-source import exclusions keep specific titles out of future rescans. The dialog, its per-source auto-import options, and storefront scanning are covered in Storefront Manager.
Failure recovery
Missing tools and malformed manifests are reported as import errors rather than silently creating unusable entries. A missing Steam binary, missing xdg-open for Heroic, or a Lutris list that is not valid JSON all raise a visible error and import nothing. Configure an emulator profile before launching ROMs; see Emulators and launching.
See Import sources for source-specific paths and Emulators and launching for profiles.
LaunchBox XML migration (v1.10.0)
Moving from LaunchBox? Export your LaunchBox library XML, then preview the migration with POST /api/v2/import/launchbox/preview — it reports how games dedupe against your current library and which emulator mappings apply (mappings are reported, never silently applied). The preview returns a preview_token and source_digest; apply with POST /api/v2/import/launchbox/apply sending the reviewed plan back. If the XML (source_digest) or the library changed since the preview, or the token mismatches, the apply stops with StaleImportPlan (crates/openbox-http/src/handlers/imports.rs, crates/openbox-imports and crates/openbox-http/src/handlers/imports.rs) — preview again instead of forcing it.
Applying a LaunchBox or ES-DE migration rewrites your library from the source file, so it confirms with exact numbers first (v1.16.0): how many games will be added, how many will be merged into games you already have, and how many entries are in the plan. The review list also says plainly when it is only showing the first 50 entries, so a short list is never mistaken for the whole import.
ES-DE gamelist migration (v1.11.0)
ES-DE gamelist.xml imports follow the same review-first pattern with stale-plan guards (StaleESDEPlan in crates/openbox-imports): POST /api/v2/import/esde/preview parses the gamelist into normalized rows, POST /api/v2/import/esde/apply applies the reviewed plan after a source-digest check. See API 1.11 additions and Handheld migration for the exact bodies.
Eden (Nintendo Switch) is emulator-only: emulator_defs/eden-switch.yaml declares state: none and a {path} startup template, so it provides a launch profile — not an import source. Switch ROMs (.xci/.nsp) import through folder import above.
Manual shelf entries (v1.10.0)
POST /api/v2/library/manual-entry adds games with no local file path — physical discs, cartridges, board games, console-only titles. Entries are marked manual_entry: true and live alongside your library without launch validation. Use POST /api/v2/library/manual-entry/update to edit one while retaining its stable identity, and POST /api/v2/library/manual-entry/convert to attach a verified local file when it becomes playable.