Handling load results

Summary: Decide what to show after a load, understand default data, and handle automatic recovery without overwriting progress.

A load returns a LoadResult<T>. Check its Status or IsSuccess before applying Data to your game. A non-null data object can be a fallback value rather than the player’s saved progress.

1. Handle the load result

For a successful load, apply the loaded data. For NotFound, start a new game using defaults. For another failure, keep the player on the menu and explain the problem before allowing a reset or a different profile.

This example uses GuideProgressData from Save slots. Save the script as SafeProgressLoader.cs, attach it to a GameObject, and connect your Load button to LoadGame.

Display Message in your UI. Apply Data and enter gameplay only when CanEnterGame is true.

C#
using UnityEngine;
using Gley.SaveSystem;
 
namespace MyGame
{
    public class SafeProgressLoader : MonoBehaviour
    {
        public GuideProgressData Data { get; private set; }
        public string Message { get; private set; } = "";
        public bool CanEnterGame { get; private set; }
 
        public void LoadGame()
        {
            // Block gameplay and autosaving until a safe starting state is available.
            CanEnterGame = false;
            var options = new SaveOptions { Slot = "slot-1" };
            LoadResult<GuideProgressData> result =
                API.Load<GuideProgressData>("progress", options, CreateDefaultData);
 
            if (result.IsSuccess)
            {
                Data = result.Data;
                CanEnterGame = true;
                Message = "Progress loaded.";
                // Recovery may restore an older copy with less recent progress.
                if (result.RecoveredFromBackup)
                {
                    Message = "A recovered save was loaded. Some recent progress may be missing.";
                }
                return;
            }
 
            // No save yet: use the starting data created by CreateDefaultData.
            if (result.Status == SaveStatus.NotFound)
            {
                Data = result.Data;
                CanEnterGame = true;
                Message = "No saved game yet. Starting a new game.";
                return;
            }
 
            if (result.Status == SaveStatus.NewerVersion)
            {
                Message = "This save needs a newer version of the game. Please update to continue.";
                return;
            }
 
            if (result.Status == SaveStatus.UnknownEncryptionKey)
            {
                Message = "This build cannot unlock the save. Please contact support.";
                return;
            }
 
            Message = "Could not load this profile: " + result.Status + ". Please retry or contact support.";
        }
 
        private GuideProgressData CreateDefaultData()
        {
            return new GuideProgressData();
        }
    }
}

Use CanEnterGame to guard both the transition into gameplay and its normal saving flow. After a failed load it stays false, even if Data still holds values from an earlier attempt. Do not apply or save those values.

2. Respond to each status

StatusMeaningRecommended action
SuccessThe save loaded. RecoveredFromBackup tells you whether a recovery copy was used.Player: Enter the game. If recovered, explain that some recent progress may be missing.
NotFoundNo save was found for that name and slot.Player: Start a new game using defaults. This is normal on a first run; loading does not create a save.
CorruptThe stored data is damaged or could not be decoded, and automatic recovery did not produce a successful load.Player: Show “We couldn’t read this save.” Offer support or a different profile; confirm any reset.
Developer: Collect the result details and available save files before resetting.
TamperedThe protected save failed its authenticity check. The status alone does not establish why the bytes changed.Player: Show “We couldn’t verify this save.” Offer support.
Developer: Preserve the result details and available save files for diagnosis.
UnknownEncryptionKeyThis service does not have the encryption key needed by the save.Player: Explain that the game cannot unlock this save yet.
Developer: Restore or fetch the correct key and retry. If keys come from a server, complete that startup step before loading.
NewerVersionThe save’s format or data version is newer than this build supports.Player: Ask them to update the game to continue.
Developer: Keep the existing save.
StorageErrorStorage could not be read, for example because of permissions or a temporary lock.Player: Explain that the save could not be accessed and offer Retry.
Developer: Check storage access and resolve any permissions or device problems.
SerializationErrorA serializer is missing, deserialization failed, or an upgrade step or hook failed.Player: Explain that the save could not be loaded and offer support.
Developer: Check the saved type, member changes, serializer installation and upgrade code.
InvalidNameThe save or slot name is invalid.Player: Show a general load error.
Developer: Fix the name in your game code. Do not ask the player to repair an internal save name.

Check LoadResult.Status for storage and data errors. A null save name or a call from a background thread can still throw an exception.

3. Default data after a failed load

You can pass a method such as CreateDefaultData to provide starting values when no saved data can be loaded.

Receiving default data does not mean the load succeeded. Check Status: for NotFound, you can start a new game; for other failures, show an error.

Loading does not save these defaults. Keep autosaving disabled after a failed load so it cannot overwrite the player’s progress.

4. Automatic recovery

With the File backend, Save System normally keeps the previous successful save as progress.sav.bak. An interrupted write can leave progress.sav.tmp. Loading checks these copies in order:

  1. The main save: progress.sav.
  2. The temporary copy: progress.sav.tmp.
  3. The previous save: progress.sav.bak.

Save System uses the first usable copy. It moves on to the next copy only when a copy is missing or damaged. You do not need to load the backup yourself.

A recovered load returns Success and RecoveredFromBackup == true. This flag also covers recovery from a temporary copy. Apply the recovered data and tell the player that some recent progress may be missing.

When recovery stops

Save System keeps the existing save instead of trying an older backup when:

  • The save needs a newer version of your game.
  • The required encryption key or serializer is missing.
  • The game cannot access the save file.
  • The file is intact, but converting its contents into game data fails.
  • Your save-upgrade code fails.

Fix the problem, then try loading again.

Which backends support recovery?

  • File: supports automatic recovery and keeps damaged saves as .broken files.
  • PlayerPrefs: has no automatic recovery or .broken files.
  • Custom storage: supports recovery only if the backend provides backup support.

SaveToString and LoadFromString work with strings instead of stored files, so they do not use backups or create .broken files.

5. Keep files for support

With the File backend, Save System may keep a damaged save as a .broken file, such as progress.sav.broken. This file helps diagnose loading problems.

Only one .broken file is kept for each save in each slot. A later failure can replace it.

Files to collect for support

Before resetting a profile, collect:

  • The affected .sav file and any .tmp, .bak and .broken files from the same slot.
  • The load result’s Status, Message, Exception, RecoveredFrom and QuarantinedTo.

QuarantinedTo gives the damaged file’s location when available.

Collect these details before calling DeleteSlot or DeleteAll, because both remove .broken files. Show the player a short error message and keep the technical details for support.

6. Test recovery in a build

Run a desktop build using the File backend. The Editor can handle edited saves differently, so test recovery in a build.

Use a disposable test slot. This example uses a save named progress.

Find the save files

On Windows, open %USERPROFILE%\AppData\LocalLow in File Explorer. Open your game’s company folder, product folder, then Saves and the test slot folder.

If you changed the save location, check Save folder name and Save folder override. For other desktop platforms, see Unity’s save locations.

Test backup recovery

  1. Save a state with 10 coins, then save again with 20 coins. Check that both saves succeed.
  2. Close the build. Confirm that the test slot contains progress.sav and progress.sav.bak. Keep a separate copy of the test files.
  3. If the test slot contains progress.sav.tmp, remove it so this test uses the backup.
  4. Open progress.sav in a plain-text editor. Replace its contents with GSS3 damaged and save. Keep the .sav filename and leave the .bak file unchanged.
  5. Reopen the build and load the test slot before saving again.

Check that:

  • IsSuccess is true.
  • RecoveredFromBackup is true.
  • The game restores 10 coins from the backup.

Test missing and damaged saves

Missing save: load an unused slot. Check that the result is NotFound and your game starts with defaults.

Damaged save without a backup:

  1. Save once in another disposable test slot, then close the build.
  2. Open that slot’s folder. Remove any progress.sav.tmp and progress.sav.bak files so recovery cannot use them.
  3. Open progress.sav in a plain-text editor. Replace its entire contents with GSS3 damaged and save. Keep the .sav filename without adding .txt.
  4. Reopen the build and load that slot before saving again. Check that IsSuccess is false, your menu shows an error, and autosaving stays disabled.

Use the Save Example to see a complete scene with an operation log.

On This Page