// OPENBOX DOCS
Import sources
Configure Steam, Heroic, Lutris, Gameyfin, ROM, and arcade imports.
OpenBoxGL imports installed libraries and local files from the sources you already run on Linux, macOS, and Windows, plus native GOG Galaxy, EA app, and Ubisoft Connect installs on Windows. Each source is offered only on the platforms it supports, as noted under its heading. Every importer adds only entries that are not already present, so re-running an import never duplicates. Missing manifests, binaries, or malformed output are reported and skipped according to the source importer.
Steam
- Manifests:
steamapps/appmanifest_*.acfin every Steam library folder (~/.local/share/Steam,~/.steam/steam, the Flatpak~/.var/app/com.valvesoftware.Steam/.local/share/Steam, plus any library listed insteamapps/libraryfolders.vdf). - Records: name, platform
PC, sourceSteam,steam_app_id, install dir,store_installed, and a launch command that preferssteam -applaunch {app_id}, falls back toflatpak run com.valvesoftware.Steam -applaunch {app_id}, thenxdg-open steam://rungameid/{app_id}. - Install state:
store_installedisinstall_dir.is_dir()at import time, so a manifest whose game folder is gone still imports but is marked missing. Those games show a red Missing badge and an INSTALL handoff instead of Play; installed games offer Verify files, which callsPOST /api/v2/game/store-actionwithaction: "repair"and openssteam://validate/<app_id>. A storefront scan refreshes the flag in place. - Prerequisite: one of
steam,flatpak, orxdg-openonPATH, else"Steam, Flatpak, or xdg-open is required to launch imported Steam games." POST /api/v2/import/steamimports installed games; the storefront catalog also reads owned app ids fromuserdata/*/config/localconfig.vdf.
Heroic
Heroic is offered on Linux and Windows. It is not offered on macOS, where the import refuses to run.
- Manifests:
legendaryConfig/legendary/installed.json(Epic),gog_store/installed.json(GOG),nile_config/installed.json(Amazon) under~/.config/heroicor the Flatpak~/.var/app/com.heroicgameslauncher.hgl/config/heroic, plus the standalone~/.config/legendary/installed.json. - Records: source
Epic/GOG/Amazon,heroic_app_id, launchxdg-open heroic://launch/<runner>/{heroic_app_id}. - DLC records (
is_dlc) are skipped. - Prerequisite:
xdg-open, else"xdg-open is required to launch imported Heroic games." - The storefront catalog reads library caches (
store_cache/*.json,GamesConfig/legendary.json) to list owned-but-uninstalled titles.
Lutris
Lutris is offered on Linux only.
- Source:
lutris --list-games --installed --json(orflatpak run net.lutris.Lutris --list-games --installed --json), 30-second timeout. - Records: non-installed entries skipped; numeric
idrequired. Origin tagging from the service/source fields: Xbox/Game Pass ->Xbox, EA app/Origin ->EA, Ubisoft/uPlay ->Ubisoft, elseLutris. Platform defaults to the record platform, orWindowsfor wine/winesteam runners. Cover art is discovered from Lutris coverart folders when present. - Prerequisite:
lutrisorflatpak, else"Lutris or Flatpak is required to import Lutris games."Malformed JSON raises"Lutris returned an invalid game list."
GOG Galaxy, EA app, and Ubisoft Connect on Windows
- Discovery: native and offline. GOG reads
HKCU\Software\GOG.com\Gamesand the twoHKLMvariants plus each game'sgoggame-*.info; the EA app reads its installer manifests (__Installer\installerdata.xml); Ubisoft Connect reads itsInstallsregistry keys. All paths are checked and all provider ids must be digits. - Records: source
GOG/EA/Ubisoft, the matchinggog_id/ea_id/ubisoft_id, install directory, andplatform: "PC". - Launch: GOG runs the executable directly and keeps it inside the install directory, so Galaxy overlay and Galaxy cloud saves do not start. EA launches through the registered
origin2://game/launchhandler; Ubisoft launches throughuplay://launch/<id>/0. - Routes:
POST /api/v2/import/gog,POST /api/v2/import/ea, andPOST /api/v2/import/ubisoft. Re-running an import merges by provider id, so it does not duplicate a game. - Limits: installed games only. Owned-but-uninstalled catalogs and Xbox PC packages are not imported. Each source has a per-source Auto-import on startup option (off by default) stored as
{enabled, platform, include_uninstalled}withinclude_uninstalledfixed at false for these three. On non-Windows hosts the routes refuse with400(see API 1.19 changes). - Failure model: a malformed registry entry or a missing install directory is reported in
errorsand skipped; a GOG executable outside its install directory is refused. Uninstalling the EA app or Ubisoft Connect leaves the game in the library but breaks launches until the handler returns.
Gameyfin
- Source: a self-hosted Gameyfin server configured in Settings (
gameyfin_url, optionalgameyfin_username/gameyfin_password,gameyfin_install_dir,gameyfin_provider). - Behavior: catalog import lists owned games with installed status; install downloads the game from the server into the install directory (staging, rollback, symlink rejection, 4 GiB per file cap) and marks the entry installed; uninstall removes only files under the install directory.
- The install directory is empty by default; the Settings field shows a
~/Games/Gameyfinplaceholder. Provider resolution falls back to the first provider the server offers, or the bundled Direct Download provider. - Connection and request failures surface as
400with the server's message. - Exclusions and auto-import: Gameyfin titles can be excluded per title like any other storefront, and its startup auto-import honors
auto_import_excluded_platformsplus theinclude_uninstalledoption. Its auto-import entry is keyedgameyfininstorefront_auto_import.
ROM folders and executables
- Scan a folder (Add games → Scan a folder…) scans recursively for supported extensions (see API content and imports for the full list) and adds each file, grouping multi-disc sets into an
.m3uand ranking duplicate ROMs (preferring USA/World releases over beta/proto/demo/hack tags, and larger CHD/CUE/M3U over archives). - Watch folders rescanned automatically every 10 seconds while the server runs.
- A
chosen_emulatorsmap can install emulators from Flathub during the wizard flow.
Arcade sets (MAME / FinalBurn Neo)
- Import:
POST /api/v2/import/arcadewith a ROM folder and optionally a DAT/XML file. Without a DAT, MAME's ownmame -listxmloutput is used (mamemust be installed, 300 s timeout, 256 MiB cap). - Classification from the DAT (
cloneofand per-set ROMs compared to ZIP contents):parent,merged(clone runs from the parent archive),split(own archive missing parent ROMs),non-merged(complete own archive). - Launch command defaults to
mame -rompath <folder> {rom_name}orfbneo {path}; an explicitcommandoverrides. - The set type counts are returned so you can verify classification.
Loose arcade, console, and small-format helpers
POST /api/v2/import/loose-arcade:.zip/.7z/.singe/.romfiles, defaulting tohypseus/singecommands.POST /api/v2/import/xbox360: folders withdefault.xex,.xex,.xbe; title from the parent folder fordefault.xex.POST /api/v2/import/scummvm: games fromscummvm.inisections.POST /api/v2/import/rpcs3: titles fromdev_hdd0/game/*/PARAM.SFO(PS3), plus external game folders and ISOs declared ingames.yml(or thegames:list ofconfig.yml) in both the native~/.config/rpcs3and Flatpak config directories. A path that no longer exists, a folder withoutPARAM.SFO, or a non-ISO file is reported and skipped; one bad entry never aborts the scan.POST /api/v2/import/vita3k: titles fromux0/app/*/sce_sys/param.sfo(Vita), resolving title ids to readable names.POST /api/v2/import/pico8:.p8and exported.p8.pngcarts, imported on thepico8-pico8adapter.POST /api/v2/import/msu1: pairs a*.msuaudio-pack folder with its sibling.sfc/.smcROM and recordsmsu1: trueplusmsu_path; a pack with no matching ROM is an error, not a game.POST /api/v2/import/whdload:.lha/.slave/.hdfAmiga installs, skipping WHDLoad system drawers, on theamiga-whdloadadapter.
Faugus Launcher
- Source: Faugus data directories and manifests (
~/.config/faugus-launcher,~/.local/share/faugus-launcher,~/Faugus, and prefix directories withdrive_c). - Records: name, path, source
Faugus,faugus_id,wine_prefix, and launch command defaulting toumu-run {path}. GET /api/v2/faugus/statuschecks if Faugus is installed;GET /api/v2/faugus/scanscans available games;POST /api/v2/faugus/importimports scanned games with canonical identity deduplication.
Proton & Wine prefix manager
- Discovery: discovers active Wine prefixes across standard locations (
~/.wine,~/.local/share/wineprefixes, Heroic, Lutris, Bottles, and Steam Proton prefixes) and detected Proton installations (~/.local/share/Steam/compatibilitytools.d, Steam common Proton runtimes). - Endpoints:
GET /api/v2/wine/prefixeslists known prefixes,GET /api/v2/wine/protonslists detected Proton versions, andGET /api/v2/wine/prefix-for-game?game_id=...resolves or recommends a prefix for a specific title.
Import exclusions
Entries added via /api/v2/import/exclusions block specific storefront titles from future imports and rescans, keyed by source + external id (Heroic entries can carry a three-part heroic key for store-specific exclusions). The sources are Steam, Heroic, Lutris, Gameyfin, GOG, EA, and Ubisoft; Gameyfin exclusions work the same as the other storefronts, including on startup auto-import.
Failure model
- Missing launchers, malformed manifests, and empty results never create partial entries: the importer raises a clear error (surfaced as
400) or skips the unusable record. foundcounts everything the source reported;addedcounts what the library did not already have. Storefront entries without local files are imported as owned-but-uninstalled (store_installed: false).- A storefront scan is incremental and per source: each source runs in its own process with a 30-second budget, an over-budget source is recorded as
timeout, and sources already completed keep their results. See Storefront Manager.
Related
-
API content and imports for every import route
-
Accounts and media for metadata providers
-
Local services for Gameyfin, OBS, and save tools
-
Faugus Launcher — scanning and importing an existing Faugus library
-
Storefront Manager — importing from Steam, Epic, GOG, and Amazon through Heroic and Lutris