// 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
- In Settings, set Mounted cloud folder to the absolute path of the mounted folder (for example
/mnt/cloud/openbox). - Click Sync statistics now to run a merge immediately, or let it run automatically, sync runs automatically after each session ends, so play time propagates without manual action.
- 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:
| Field | Merge rule |
|---|---|
play_count, playtime_seconds | By maximum |
last_played | Newer timestamp wins |
progress, rating, favorite | Whoever played last is authoritative; if neither side has played, the newer file wins |
generated_at | Preserved 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
| Problem | Cause / 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 session | Check the folder is mounted and the file is writable; look for sync errors in the diagnostic log. |
| Stats reappear after deleting a game | Deletion does not remove the cloud file's entry for that game. Run a sync after deletion so the merged output drops it. |
See also
- Library catalog sync, opt-in catalog metadata sync (v1.10.0)
- Sessions, saves, and backups, session recording and history
- API saves and operations,
POST /api/cloud/sync - Data and recovery, where local state lives
Catalog sync (v1.10.0)
Statistics sync above covers play stats only. OpenBox 1.10.0 also includes an explicit, opt-in catalog transport for games and shared metadata. Enable Library synchronization, then use POST /api/v2/library/sync/preview to inspect incoming events and POST /api/v2/library/sync/apply to apply a reviewed plan. Publish local events with POST /api/v2/library/sync/publish and the JSON body {"protocol":"v3"}.
The v3 transport stores immutable, content-addressed events under openbox-library-v3, tracks device identity and ancestry, propagates tombstones, preserves a recovery snapshot before apply, and lets you choose conflicts explicitly. Launch paths, commands, credentials, play statistics, installed files, saves, and media remain local to each device. The former whole-library publish payload and POST /api/v2/library/sync/pull return 503 LIBRARY_SYNC_UNAVAILABLE before mutation; they do not perform last-writer-wins replacement.