BetterSaves

Description
BetterSaves keeps Slay the Spire 2 vanilla and modded saves interoperable. It provides selectable sync scopes, a protected first-sync flow, and verified in-game backup and restore tools.

Installation instructions
If you have previously used versions of bettrersaves below v0.3.0 and wish to switch to v0.3.0 or later, please go to the "%AppData%/SlayTheSpire2/mods/BetterSaves" directory and delete the config file before starting the game to back up all current saves.

## Highlights

- Bidirectional vanilla/modded save synchronization
- Four sync modes, including a complete opt-out
- Vanilla compatibility mode when BetterSaves is the only enabled mod
- Protected first sync with an automatic local safety snapshot
- One-click backups, SHA-256 validation, exact two-sided restore, and backup deletion
- Profile-screen indicator for the save side currently in use

## Install Or Update

1. Download `BetterSaves` 
2. Extract the archive into the game's `mods` directory.
3. Confirm the resulting layout:

   ```text
   Slay the Spire 2/
   └─ mods/
      └─ BetterSaves/
         ├─ BetterSaves.dll
         ├─ BetterSaves.json
         └─ BetterSaves.pck
   ```

4. Start the game normally.

When updating, replace the existing game-side `BetterSaves` folder. Configuration and backups are stored outside the game directory and are not removed by replacing the mod files.

## Sync Modes

Change the mode from the BetterSaves row in the mod settings screen.

| Mode | What it synchronizes |
| --- | --- |
| `Sync Off` | Disables BetterSaves copying, deletion, watchers, startup reconciliation, and first-sync prompts. New saves remain only on the side currently used by the game. |
| `Save Only` | Synchronizes supported in-progress single-player run files. |
| `Data Only` | Synchronizes progression, timeline, discoveries, and run history, but not in-progress run files. |
| `Full Sync` | Synchronizes both supported run files and profile data. |

Mode changes take effect immediately. To keep both sides aligned before choosing `Sync Off`, save at the main menu and allow the current synchronization to finish first.

When only BetterSaves is enabled, the game uses the vanilla save path. When gameplay mods are enabled, it uses the modded save path.

## First Sync

The first time BetterSaves manages an existing profile, it creates a local safety backup before asking which save to keep:

- `Keep Vanilla (Overwrite Modded)` preserves vanilla and copies it to the modded side.
- `Keep Modded (Overwrite Vanilla)` preserves modded and copies it to the vanilla side.
- `Decide Later` changes nothing for the current session and asks again next launch.

The selected source is not considered complete until the files are copied and the game successfully reloads that profile. Steam Cloud mirror writes are deferred until this reload succeeds.

If the selected source contains clearly less data than the other side, the first click displays a warning. Click the same choice again only when that overwrite is intentional.

If the safety backup cannot be created, BetterSaves blocks the import instead of modifying either save side. If profile reload or automatic rollback fails, the protection state persists across restarts and displays the recovery backup path.

## Backup And Restore

The `BetterSaves Save Backups` row appears directly below the sync-mode setting.

- `Back Up Now` snapshots both vanilla and modded directories for the current Steam account and profile.
- `Restore Backup` is available from the main menu and lists manual backups, pre-restore safety backups, and compatible first-sync backups.
- Every normal restore creates a pre-restore safety backup, exactly replaces both profile directories, validates the result, and reloads the profile before synchronization resumes.
- The latest three pre-restore safety backups are retained per account/profile. Manual and first-sync backups are not pruned automatically.
- Backups protecting first sync or failed-restore recovery cannot be deleted.
- If restore or rollback is interrupted, BetterSaves pauses automatic synchronization and locks recovery to the recorded safety backup.
- If the active Steam account cannot be matched safely while several local account folders exist, BetterSaves refuses the operation instead of guessing.

Manual profile backups intentionally exclude account-wide `profile.save` and `settings.save`. Restoring one profile therefore does not replace another profile, the selected slot, global settings, or another Steam account.

Restore works while `Sync Off` is selected and never changes the selected sync mode.

## Data Locations

BetterSaves stores its configuration and backups under the operating system's application-data directory:

| System | BetterSaves data directory |
| --- | --- |
| Windows | `%AppData%/SlayTheSpire2/mods/BetterSaves/` |
| Linux | `${XDG_CONFIG_HOME:-~/.config}/SlayTheSpire2/mods/BetterSaves/` |
| macOS | `~/Library/Application Support/SlayTheSpire2/mods/BetterSaves/` |

Windows and Linux are the current release targets. The macOS path documents the application-data layout used by the code, but macOS runtime compatibility is not currently verified.

Important paths:

```text
config.json
backups/manual/
backups/first-sync-<timestamp>/
```

Completed first-sync backups contain `backup-complete.json`; manual and pre-restore backups contain `manual-backup.json`.

## Steam Cloud And Compatibility

- BetterSaves may upload mirrored files after a successful local sync or restore, according to the selected sync mode.
- BetterSaves deliberately does not delete Steam Cloud files. This protects other devices but means a remote file absent from a restored local backup can reappear later.
- Steam Cloud startup timing can delay when changes appear on another device. Use the same BetterSaves version on every installation sharing the same saves.
- Multiplayer current-run interop is less predictable than single-player interop because vanilla and modded sessions may use different local player identifiers.
- Slay the Spire 2 updates can change internal game methods used by mods. Install the latest BetterSaves release after a game update.

### Linux Runtime Error

If startup fails with a Harmony or `mm-exhelper.so` error mentioning `_Unwind_RaiseException`, ensure `libgcc-s1`, `libstdc++6`, and `libunwind8` are visible to the game process.

Sandboxed Steam installations such as NixOS or Flatpak may require the library in Steam launch options:

```text
LD_PRELOAD+=":/path/to/libgcc_s.so.1" %command%
```

NixOS with nix-ld commonly uses:

```text
LD_PRELOAD+=":/run/current-system/sw/share/nix-ld/lib/libgcc_s.so.1" %command%
```

## Recovery Checklist

If BetterSaves reports a blocked first sync or restore:

1. Do not delete or overwrite the displayed backup directory.
2. Return to the main menu and open `Restore Backup`.
3. Restore the backup selected by the recovery warning.
4. Keep the game open until profile reload completes.
5. If in-game recovery is unavailable, copy the data directory before attempting manual repair and attach the latest game log when reporting the issue.

Requirements

If you encounter any problems while using this mod, you are welcome to give me feedback immediately!
If you still encounter the problem of lost saves, please submit the current log file to help me fix this issue.

Shout outs