Changing your save data after release

Summary: Keep older player saves working with SaveVersion, OnUpgrade and JSON upgrade steps.

When your save class changes, players still have data written by older builds. Give the data a version and describe how to bring older saves up to date. This is separate from upgrading the Save System plugin from v2 to v3; that process is in the Upgrade Guide.

1. Version the top-level data type

Add [SaveVersion(1)] to the class you pass to API.Save. A type without the attribute is already treated as version 1. Increase this number when a change needs migration or makes an older build unable to understand the new data. Keep the version increasing; it is your data format version, not your game’s marketing version.

Version the outer save class, including changes to nested objects. A top-level list, array or primitive is always version 1; wrap it in your own serializable class if it needs versioning.

2. Initialize added or computed fields with OnUpgrade

Suppose version 1 saved music volume, and version 2 adds a separate SFX volume. An existing player’s SFX volume should start at their saved music volume.

Version 1: already shipped

The released game used this AudioSettingsData.cs file, which stores only music volume:

C#
using System;
using UnityEngine;
using Gley.SaveSystem;
 
namespace MyGame
{
    [Serializable]
    [SaveVersion(1)]
    public class AudioSettingsData
    {
        private const float DefaultVolume = 0.8f;
 
        [SerializeField] private float _musicVolume;
 
        public float MusicVolume { get => _musicVolume; set => _musicVolume = value; }
 
        public AudioSettingsData()
        {
            _musicVolume = DefaultVolume;
        }
    }
}

Version 2: adds SFX volume

Replace the contents of AudioSettingsData.cs with the version below. These are two versions of the same class; do not add both to your project.

C#
using System;
using UnityEngine;
using Gley.SaveSystem;
 
namespace MyGame
{
    [Serializable]
    [SaveVersion(2)]
    public class AudioSettingsData : ISaveUpgradable
    {
        private const float DefaultVolume = 0.8f;
 
        [SerializeField] private float _musicVolume;
        [SerializeField] private float _sfxVolume;
 
        public float MusicVolume { get => _musicVolume; set => _musicVolume = value; }
        public float SfxVolume { get => _sfxVolume; set => _sfxVolume = value; }
 
        public AudioSettingsData()
        {
            _musicVolume = DefaultVolume;
            _sfxVolume = DefaultVolume;
        }
 
        public void OnUpgrade(int fromVersion)
        {
            if (fromVersion < 2)
            {
                _sfxVolume = _musicVolume;
            }
        }
    }
}

The constructor defines a fresh game’s defaults. OnUpgrade defines what an older save should become; do not rely on a constructor or field initializer to initialize a newly added field during deserialization. Initialize added lists and nested objects explicitly when upgrading too.

No registration is needed for ISaveUpgradable. Save System calls OnUpgrade on the main thread after loading an older data version, passing the original saved version once. A version-1 save loaded by version 3 still receives fromVersion == 1. Keep earlier conditions as you add later upgrades.

The hook does not run for current-version saves or when a load returns default data. If it throws, the load returns SerializationError with defaults and the exception. Keep it focused on updating the data.

3. Rename fields before deserialization

After a field is renamed, the old value may no longer be available on the loaded object. Use a JSON upgrade step to move it before deserialization. JsonUpgradeStep<T> requires com.unity.nuget.newtonsoft-json to be installed; JsonUtility can remain selected in settings. The helper works on JSON saves written by either serializer.

For this separate example, version 1 of a JsonUtility save stored coins in a private serialized field named _coins. Version 2 renames it to _gold.

Version 1: stores coins

The released game used this WalletData.cs file:

C#
using System;
using UnityEngine;
using Gley.SaveSystem;
 
namespace MyGame
{
    [Serializable]
    [SaveVersion(1)]
    public class WalletData
    {
        [SerializeField] private int _coins;
 
        public int Coins { get => _coins; set => _coins = value; }
    }
}

Version 2: renames coins to gold

Replace the contents of WalletData.cs with the version below. These are two versions of the same class; do not add both to your project. The JSON upgrade step that follows preserves the coins saved by version 1.

C#
using System;
using UnityEngine;
using Gley.SaveSystem;
 
namespace MyGame
{
    [Serializable]
    [SaveVersion(2)]
    public class WalletData
    {
        [SerializeField] private int _gold;
 
        public int Gold { get => _gold; set => _gold = value; }
    }
}

Create SaveUpgradeRegistration.cs, add it to a GameObject in your startup scene, and call Register once before any code loads WalletData. Do this on each app run, through the same save service that will load the data. If you use assembly definitions, reference Gley.SaveSystem.Newtonsoft and the Newtonsoft JSON assembly as well as the core Save System assembly.

C#
using Newtonsoft.Json.Linq;
using UnityEngine;
using Gley.SaveSystem;
using Gley.SaveSystem.Newtonsoft;
 
namespace MyGame
{
    public class SaveUpgradeRegistration : MonoBehaviour
    {
        private bool _isRegistered;
 
        // Call this from your startup flow before loading WalletData.
        public void Register()
        {
            // The same type and version cannot be registered twice.
            if (_isRegistered)
            {
                return;
            }
 
            // Register the version 1 to 2 change. Save System calls this
            // callback before deserializing an older save into WalletData.
            API.AddUpgradeStep(new JsonUpgradeStep<WalletData>(1, RenameCoinsToGold));
            _isRegistered = true;
        }
 
        // value contains the saved WalletData fields, using their JSON names.
        private void RenameCoinsToGold(JObject value)
        {
            if (value.TryGetValue("_coins", out JToken coins))
            {
                // Preserve the player's balance under the new name, then remove
                // the old field so the JSON matches version 2.
                value["_gold"] = coins;
                value.Remove("_coins");
            }
        }
    }
}

Register before the first load

  • Call Register explicitly from your startup flow before loading WalletData.
  • Do not rely on the order of two unrelated Awake methods.
  • Add SaveUpgradeRegistration to only one GameObject. If two copies call Register, they both try to add the same WalletData upgrade, causing an error.

Match the names in the saved JSON

Inspect a real old save in Save Viewer before writing the step. Use the exact names stored in that JSON:

  • This JsonUtility example: rename _coins to _gold.
  • Newtonsoft with default public properties: the names may instead be Coins and Gold.

Keep steps for older versions

If version 3 introduces another rename:

  • Keep the step from version 1 for the 1 → 2 transition.
  • Add a step from version 2 for the 2 → 3 transition.

Applicable steps run in version order. Then OnUpgrade runs once with the original saved version.

Versions without a registered step are skipped. Register every transformation needed to preserve the old data.

Choose the right upgrade method

UseWhen
JSON upgrade stepsRename fields or convert types before deserialization.
OnUpgradeInitialize or compute values from the deserialized object.

A failing JSON step returns SerializationError.

4. Load, verify, then save normally

Loading upgrades the object in memory. It does not automatically rewrite the stored save. After a successful load, apply the data to your game; the next successful normal save writes the current data version.

If an upgrade fails with SerializationError, do not continue with the returned defaults or let autosave overwrite the existing save. Keep the original save and resolve the upgrade failure before saving to it again.

  1. Keep copies of real saves from each shipped data version before changing the class.
  2. Run the current build with those copies. Register upgrade steps first, then load the same save name and slot into the current type.
  3. Check IsSuccess and verify important values: currency, inventory, progress and any newly computed defaults.
  4. Save the upgraded data, restart the game, and load it again. Confirm that the values remain correct.
  5. Repeat in a player build, including your IL2CPP and stripping settings where applicable.

The Save Example includes an embedded version-1 save and an OnUpgrade hook you can run without preparing an old build.

5. Handle newer saves in older builds

NewerVersion means the save’s format version or data version is newer than this build understands. Show a message such as “This save needs a newer version of the game. Please update to continue.”

Save System does not load an older backup or quarantine that save, and it refuses writes to the same save while the newer data is present. Keep the player on the menu or offer an explicit new profile. Do not delete their save or treat the returned defaults as loaded progress. See Handling load results.

On This Page