From 70549427d41d1890c395d576a422ccb8ff43509b Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Wed, 7 Oct 2026 13:16:53 -0400 Subject: [PATCH 1/4] docs: RetroArch Cloud Sync saves go through save slots Covers rommapp/romm#5170: the newest slotted save per game, core and extension is offered under RetroArch's name, uploads add slot versions pruned per core and extension, and a delete removes every version the path covers. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/ecosystem/retroarch-cloud-sync.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/ecosystem/retroarch-cloud-sync.md b/docs/ecosystem/retroarch-cloud-sync.md index 62728d7b..f4bb6591 100644 --- a/docs/ecosystem/retroarch-cloud-sync.md +++ b/docs/ecosystem/retroarch-cloud-sync.md @@ -57,7 +57,11 @@ The `config`, `thumbnails` and `system` folders belong to no game, so RomM keeps ### Saves -RetroArch sees the saves stored without a slot, which covers everything it uploaded itself and saves you uploaded by hand. Saves written into a [slot](../using/saves-and-states.md#save-slots), such as the browser player's `autosave` history or the ones other device-sync apps upload, are left out of the manifest because they're RomM's versioned history and not files a core would load. +RetroArch saves go through the same [save slots](../using/saves-and-states.md#save-slots) as the web player and other device-sync apps. For each game, core and file extension, RomM offers the newest save from any slot under the name RetroArch expects (`.srm`, for example), so progress made in the browser or on another device reaches RetroArch, and the other way around. + +Each upload adds a new version to the slot of the save RetroArch was offered, or to `autosave` when there was none. An upload with the same bytes as the newest version adds nothing. The slot keeps up to `MAX_SAVES_PER_SLOT` versions for that core and extension, so a `.rtc` file or another core's save in the same slot keeps its own history. + +A save stored without a slot, such as one you uploaded by hand, is offered until the first upload for that game and core files a slotted version. ### States @@ -67,7 +71,7 @@ A state made in RomM's web player has a label and a timestamp in its name instea ### Deletes -Deleting a save or state in RetroArch deletes it in RomM too. In non-destructive mode RetroArch moves a deleted file into a `deleted/` folder instead, and RomM treats that move as a delete as well, since keeping the row would push the file straight back on the next sync. +Deleting a save or state in RetroArch deletes it in RomM too. For a save, that's every version RomM could offer in its place (the game's slotted saves for that core and extension in every slot, plus the unslotted save at that path), so no older version comes back on the next sync. In non-destructive mode RetroArch moves a deleted file into a `deleted/` folder instead, and RomM treats that move as a delete as well, since keeping the row would push the file straight back on the next sync. ## How files match games @@ -128,7 +132,7 @@ Most proxies forward any method, but some web application firewalls and CDN rule - **RetroArch says the sync failed right away**: check the URL ends in `/api/sync/retroarch/`, with the trailing slash, and that the username and password sign in to the RomM web UI. - **A save never shows up in RomM**: its file name matches no ROM you can see. Look for a `matches no ROM in the library` warning in the logs, then rename the ROM or the save so they agree. - **A web player state doesn't show up in RetroArch**: only the newest state per slot is offered, so a newer state in the same slot hides it. RetroArch also has to be sorting states by core for the state to land in the folder the core reads from. -- **A browser save doesn't show up in RetroArch**: saves in a slot aren't offered to RetroArch (see [Saves](#saves)). +- **A browser save doesn't show up in RetroArch**: only the newest save for the game, core and extension is offered (see [Saves](#saves)), and it lands in the folder of the core that wrote it. Check that RetroArch sorts saves by core and runs the same core as the browser player. - **A PSP save doesn't sync**: the folder's title didn't match a ROM. Add the serial from the log message to `SYNC_RETROARCH_PSP_SERIAL_MAP` and restart RomM. - **Errors only on `PROPFIND`, `MOVE` or `MKCOL` requests**: something in front of RomM blocks WebDAV methods (see [Reverse proxy](#reverse-proxy)). - **Large states fail to upload**: raise your proxy's body size limit. From cd3ffff503639ad6178ef3a4809b19ac3573d2fa Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Wed, 7 Oct 2026 14:44:23 -0400 Subject: [PATCH 2/4] docs: RetroArch .srm saves map to autosave, other files stay unslotted Follows rommapp/romm#5170: named slots are never read or changed, other save files are overwritten in place, and a delete clears that game and core's autosave versions. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/ecosystem/retroarch-cloud-sync.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/ecosystem/retroarch-cloud-sync.md b/docs/ecosystem/retroarch-cloud-sync.md index f4bb6591..078d1c65 100644 --- a/docs/ecosystem/retroarch-cloud-sync.md +++ b/docs/ecosystem/retroarch-cloud-sync.md @@ -57,11 +57,11 @@ The `config`, `thumbnails` and `system` folders belong to no game, so RomM keeps ### Saves -RetroArch saves go through the same [save slots](../using/saves-and-states.md#save-slots) as the web player and other device-sync apps. For each game, core and file extension, RomM offers the newest save from any slot under the name RetroArch expects (`.srm`, for example), so progress made in the browser or on another device reaches RetroArch, and the other way around. +A game's `.srm` save shares the `autosave` [slot](../using/saves-and-states.md#save-slots) with the web player and other device-sync apps, so progress made in the browser or on another device reaches RetroArch, and the other way around. For each game and core, the newest `autosave` version is offered under the name RetroArch uses for the game. -Each upload adds a new version to the slot of the save RetroArch was offered, or to `autosave` when there was none. An upload with the same bytes as the newest version adds nothing. The slot keeps up to `MAX_SAVES_PER_SLOT` versions for that core and extension, so a `.rtc` file or another core's save in the same slot keeps its own history. +Each upload adds a new version to `autosave`, unless it has the same bytes as the newest one. Up to `MAX_SAVES_PER_SLOT` versions are kept for each core, so another core's save in the slot keeps its own history. Saves in named slots aren't offered to RetroArch and are never changed by it. -A save stored without a slot, such as one you uploaded by hand, is offered until the first upload for that game and core files a slotted version. +Other files RetroArch puts in `saves/`, such as a `.rtc` clock file, are stored without a slot and overwritten on each upload. A `.srm` stored without a slot, such as one you uploaded by hand, is offered until the first upload for that game and core. ### States @@ -71,7 +71,7 @@ A state made in RomM's web player has a label and a timestamp in its name instea ### Deletes -Deleting a save or state in RetroArch deletes it in RomM too. For a save, that's every version RomM could offer in its place (the game's slotted saves for that core and extension in every slot, plus the unslotted save at that path), so no older version comes back on the next sync. In non-destructive mode RetroArch moves a deleted file into a `deleted/` folder instead, and RomM treats that move as a delete as well, since keeping the row would push the file straight back on the next sync. +Deleting a save or state in RetroArch deletes it in RomM too. For a `.srm`, that's every `autosave` version for that game and core, plus the one stored without a slot, so no older version comes back on the next sync. Named slots are left alone. In non-destructive mode RetroArch moves a deleted file into a `deleted/` folder instead, and RomM treats that move as a delete as well, since keeping the row would push the file straight back on the next sync. ## How files match games @@ -132,7 +132,7 @@ Most proxies forward any method, but some web application firewalls and CDN rule - **RetroArch says the sync failed right away**: check the URL ends in `/api/sync/retroarch/`, with the trailing slash, and that the username and password sign in to the RomM web UI. - **A save never shows up in RomM**: its file name matches no ROM you can see. Look for a `matches no ROM in the library` warning in the logs, then rename the ROM or the save so they agree. - **A web player state doesn't show up in RetroArch**: only the newest state per slot is offered, so a newer state in the same slot hides it. RetroArch also has to be sorting states by core for the state to land in the folder the core reads from. -- **A browser save doesn't show up in RetroArch**: only the newest save for the game, core and extension is offered (see [Saves](#saves)), and it lands in the folder of the core that wrote it. Check that RetroArch sorts saves by core and runs the same core as the browser player. +- **A browser save doesn't show up in RetroArch**: only the newest `autosave` save for the game and core is offered (see [Saves](#saves)), and it lands in the folder of the core that wrote it. Check that RetroArch sorts saves by core and runs the same core as the browser player, and that the save isn't in a named slot. - **A PSP save doesn't sync**: the folder's title didn't match a ROM. Add the serial from the log message to `SYNC_RETROARCH_PSP_SERIAL_MAP` and restart RomM. - **Errors only on `PROPFIND`, `MOVE` or `MKCOL` requests**: something in front of RomM blocks WebDAV methods (see [Reverse proxy](#reverse-proxy)). - **Large states fail to upload**: raise your proxy's body size limit. From 478143a8616e13d71677d4893c6c701198f4af1a Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Thu, 8 Oct 2026 13:35:00 -0400 Subject: [PATCH 3/4] docs: humanize RetroArch save slot changes Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/ecosystem/retroarch-cloud-sync.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ecosystem/retroarch-cloud-sync.md b/docs/ecosystem/retroarch-cloud-sync.md index 9a3091cd..94305eac 100644 --- a/docs/ecosystem/retroarch-cloud-sync.md +++ b/docs/ecosystem/retroarch-cloud-sync.md @@ -77,7 +77,7 @@ A state made in RomM's web player has a label and a timestamp in its name instea ### Deletes -Deleting a save or state in RetroArch deletes it in RomM too. For a `.srm`, that's every `autosave` version for that game and core, plus the one stored without a slot, so no older version comes back on the next sync. Named slots are left alone. In non-destructive mode RetroArch moves a deleted file into a `deleted/` folder instead, and RomM treats that move as a delete as well, since keeping the row would push the file straight back on the next sync. +Deleting a save or state in RetroArch deletes it in RomM too. For a `.srm`, that's every `autosave` version for that game and core plus the one stored without a slot (named slots are left alone), so no older version comes back on the next sync. In non-destructive mode RetroArch moves a deleted file into a `deleted/` folder instead, and RomM treats that move as a delete as well, since keeping the row would push the file straight back on the next sync. ## How files match games From 55c22113f2c558a2de5f1d31335541cedcf69e94 Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Thu, 8 Oct 2026 13:36:51 -0400 Subject: [PATCH 4/4] docs: humanize prose from #172 and #175 Also fix the first-sync FAQ, which still described unslotted saves. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/ecosystem/retroarch-cloud-sync.md | 4 ++-- docs/using/devices.md | 2 +- docs/using/saves-and-states.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ecosystem/retroarch-cloud-sync.md b/docs/ecosystem/retroarch-cloud-sync.md index 94305eac..3952fd6e 100644 --- a/docs/ecosystem/retroarch-cloud-sync.md +++ b/docs/ecosystem/retroarch-cloud-sync.md @@ -11,7 +11,7 @@ Each save and state is attached to the ROM it belongs to, next to the ones from ## Requirements -- A RetroArch build with Cloud Sync and the WebDAV driver. Use RetroArch 1.22 or newer: the 1.19.x builds for Windows and Android have no Cloud Sync menu. +- RetroArch 1.22 or newer, built with Cloud Sync and the WebDAV driver (the 1.19.x builds for Windows and Android have no Cloud Sync menu) - A RomM account with a password, since RetroArch signs in with HTTP Basic auth and an account that only signs in through [OIDC](../administration/oidc/index.md) has none to send - Your ROM files named the same on both sides, because that's how RomM tells which game a save belongs to (see [How files match games](#how-files-match-games)) @@ -175,7 +175,7 @@ RetroArch's requests don't identify the install, so every install signed in as t ### Why does a new device's first sync take so long? -It downloads every save without a slot, for every game you have, plus the newest state in each slot. Saves with no emulator recorded land in the device's `saves/` root. +It downloads the newest save for every game and core you have, plus the newest state in each slot. Saves with no emulator recorded land in the device's `saves/` root. ### Why does the same state have a different size on each device? diff --git a/docs/using/devices.md b/docs/using/devices.md index 7ff84697..3cdc516b 100644 --- a/docs/using/devices.md +++ b/docs/using/devices.md @@ -29,7 +29,7 @@ An account without the `devices.write` permission can't register devices, so its A game you send to one of your devices is added to its download queue and fetched the next time the device is online. -Only devices whose app reports that it accepts installs are offered, which leaves out browsers and RetroArch. Devices also show their online status: a device is online while its app holds an open connection to the `/devices` socket, or when it checked for installs in the last 90 seconds. An app that only checks every few minutes shows as offline between checks, but still picks up the request. +Only devices whose app reports that it accepts installs are offered, which leaves out browsers and RetroArch. Devices also show their online status: a device is online while its app holds an open connection to the `/devices` socket, or has checked for installs in the last 90 seconds. An app that only checks every few minutes shows as offline between checks, but still picks up the request. A request waits in the device's queue until the device takes it and reports back. You get a [notification](notifications.md) when it finishes or fails, and you can cancel a request any time before it finishes. A request nothing picks up expires after `DEVICE_INSTALL_REQUEST_TTL_DAYS` days without a change (2 by default). diff --git a/docs/using/saves-and-states.md b/docs/using/saves-and-states.md index b5e1ee77..3d34009d 100644 --- a/docs/using/saves-and-states.md +++ b/docs/using/saves-and-states.md @@ -78,7 +78,7 @@ A save or state can be renamed, and its screenshot follows it. The new name has Saves and states written in the browser are named after the game and the local time they were captured, so the timestamp in the name matches your clock. -A new version of a save uploaded by a device or RetroArch is tagged with the server's time instead. That follows the container's time zone, which is UTC unless you set `TZ` (for example `TZ=America/New_York`) in RomM's environment. +A new version of a save uploaded by a device or RetroArch is tagged with the server's time instead, which follows the container's time zone: UTC unless you set `TZ` (for example `TZ=America/New_York`) in RomM's environment. When you share a save or state with other users, they see its author but not its favorite flag or labels, which stay yours.