// OPENBOX DOCS

Statistics sync

Merge play statistics across machines through a mounted cloud folder.

OpenBoxGL merges play statistics between machines through any mounted folder, Syncthing, Dropbox, Nextcloud, Drive, or a plain local path. The folder must be mounted and writable on every machine that should participate.

Set it up

  1. In Settings → Integrations, set Mounted cloud folder to the absolute path of the mounted folder (for example /mnt/cloud/openbox).
  2. Click Sync statistics now to run a merge immediately. The Python fallback also runs a merge after each session; the 3.0 Rust server does not currently call that hook, so use the button until it is wired.
  3. Configure the same folder on another machine to merge stats there.

What syncs and how conflicts resolve

Sync reads and writes openbox-statistics.json (format 1) in the folder under a file lock. Per game:

FieldMerge rule
play_count, playtime_secondsBy maximum
last_playedNewer timestamp wins
progress, rating, favoriteWhoever played last is authoritative; if neither side has played, the newer file wins
generated_atPreserved when the remote was newer, bumped when local state is newer

Deleted local games are never resurrected: games present only in the cloud file are dropped from the merged output, and only games that exist locally are written back. This keeps a removal on one machine from reappearing on another.

Troubleshooting

ProblemCause / fix
"Configure a mounted cloud sync folder first."No cloud_folder set in Settings; point it at a mounted, writable path.
Sync does nothing after a sessionCheck the folder is mounted and the file is writable; look for sync errors in the diagnostic log.
Stats reappear after deleting a gameDeletion does not remove the cloud file's entry for that game. Run a sync after deletion so the merged output drops it.

Catalog sync

Statistics sync above covers play stats only. Catalog metadata travels through a separate opt-in transport: turn on Enable opt-in library catalog sync under Settings → Integrations after setting the mounted folder, then use Preview catalog changes (POST /api/v2/library/sync/preview), Apply reviewed changes (POST /api/v2/library/sync/apply), and Publish local changes (POST /api/v2/library/sync/publish). Launch paths, commands, credentials, play statistics, installed files, saves, and media stay on each device; the legacy whole-library publish/pull routes return 503 LIBRARY_SYNC_UNAVAILABLE.

See Library catalog sync for the workflow, conflict review, and the exact field allowlist.

See also