FAQ

Summary: Find answers to common questions and solutions to save errors.

Questions

What data can I save?

You can save numbers, booleans (true/false values), strings (text), supported lists and arrays, and your own classes and structs. Add [Serializable] to your own classes and structs. The default serializer, JsonUtility, converts your data to text. It saves public fields and private fields marked [SerializeField]. See Choosing a serializer for details on which types, fields and properties each serializer can save.

Where are my saves stored?

On desktop and mobile, the default File storage saves to Application.persistentDataPath/Saves. WebGL saves in the browser’s storage. Consoles and other platforms use PlayerPrefs by default. You can choose a different storage option for each platform. Change the save folder in the Setup Guide, or view saves created by the Unity Editor in the Save Viewer.

What happens the first time I load, before anything is saved?

Load returns NotFound because no save exists yet. It does not create a save.

Pass a defaultValue method to choose the starting data returned in Data. Without one, Save System tries to create a new data object. If it cannot, it uses the type’s default value, such as null for a class. Check the status before using the data. See Handling load results.

How do I make Continue and New game buttons, or several profiles?

Use save slots to keep progress separate and decide whether to continue an existing game or create a new one. See Save slots.

Why is my Dictionary or DateTime not saved?

JsonUtility does not save dictionaries, DateTime, properties or nullable fields (fields that can hold null). The Editor warns about known unsupported field types. Choose Newtonsoft under Tools › Gley › Save System › General › Serializer, or store a DateTime as ticks in a long. See Choosing a serializer.

How do I keep a field out of the save?

With JsonUtility, add [NonSerialized] to the field. With Newtonsoft, use [JsonIgnore] to exclude a field or property. See Choosing a serializer.

Why are nested classes in my data null after loading?

A newly created data object can contain null fields unless you initialize them. Create nested objects in your constructor or field initializers, or in the method you pass as defaultValue; see Handling load results. If an existing save already contains null or needs a newly added object, repair it during a data upgrade as described in Changing your save data after release.

I added a field to my save class after release. Will old saves still load?

Yes, if the existing fields remain compatible. The values of new fields depend on your serializer; do not assume a constructor or field initializer gives them the values you want. To set specific starting values, rename fields or change their types, use SaveVersion and upgrade code. See Changing your save data after release.

Can players cheat by editing the save file?

Encryption makes saves harder to edit, but its key is included in the game and a determined player can extract it. Do not rely on it as anti-cheat for online leaderboards or purchases. See Setup Guide for protection settings and Managing encryption keys for key management.

Does it work on WebGL?

Yes. The default File storage keeps saves in the browser between visits. This storage is separate for each website domain, so moving the game to a different domain starts with empty saves. Avoid closing the page immediately after saving. See the Setup Guide for platform settings and browser storage limits.

Can I add cloud saves?

Cloud saves are not built in. Use SaveToString to produce text for your cloud service and LoadFromString to read it back. Alternatively, implement ISaveStorage and register it with SetStorage.

Can I use it from another thread?

Call the API from Unity’s main thread, including your first Save System call. Use SaveAsync and LoadAsync for asynchronous operations. Serialization and storage that requires the main thread, such as PlayerPrefs, still run there.

Will my v2 players lose their saves?

Existing v2 API calls remain available and can read v2 saves. When moving to the new API, register each old save location with API.MapV2 before loading. Follow v2 to v3 to carry over settings and enable the legacy reader when needed. The v2 binary reader is not available in WebGL builds.

What Save System doesn’t include

  • Anti-cheat: encryption makes saves harder to edit, but it does not prevent cheating
  • Built-in cloud saves: use SaveToString with your cloud service, or connect your own storage system through ISaveStorage
  • Official console support: consoles use PlayerPrefs by default. You can connect the console’s save system through ISaveStorage
  • Unity object references: sprites, prefabs and ScriptableObjects aren’t saved. Save a unique ID that stays the same between game sessions instead

Troubleshooting

<Class>.<field> holds a Unity object reference — save an ID, not the reference

Cause: Your data contains a sprite, prefab, ScriptableObject or another Unity object reference. Save System refuses to save these references.

Fix: Save a unique ID that stays the same between game sessions, along with values such as its position or health. Use that ID to find or recreate the object after loading. See Choosing a serializer.

<Class>.<field> is a DateTime, which JsonUtility skips — store .Ticks as a long, or switch to Newtonsoft

Cause: JsonUtility cannot save this field type, so the field is not saved even if the rest of the save succeeds.

Fix: Store DateTime.Ticks in a long, or select Newtonsoft. Similar warnings name other unsupported field types and their alternatives. See Choosing a serializer.

Newtonsoft is selected but not installed — install com.unity.nuget.newtonsoft-json

Cause: Your settings select Newtonsoft, but its Unity package is not installed.

Fix: Click Install Newtonsoft under Tools › Gley › Save System › General › Serializer, then wait for Unity to finish compiling. See Setup Guide.

Save System API must be called from the main thread

Cause: An API call was made from a background thread or task.

Fix: Move the call to Unity’s main thread. Use SaveAsync and LoadAsync for asynchronous operations, and make the first Save System call on the main thread too.

This project shipped with key … — restore it from version control or paste it in Tools > Gley > Save System > Advanced > Manage keys.

Cause: The build check found that an encryption key used in a previous build is missing. Saves protected with that key would not load.

Fix: Restore the settings asset from version control or paste the original key in Tools › Gley › Save System › Advanced › Manage keys. The message shows the missing key’s ID; you need the original full key. See Managing encryption keys.

Load returns UnknownEncryptionKey

Cause: The save was protected with a key this build does not have, often because another machine uses a different settings asset.

Fix: Restore the original key as described in Managing encryption keys. The save is preserved; retry loading after the correct key is available.

Load returns NewerVersion

Cause: The save’s format or data version is newer than this build supports.

Fix: Ask the player to update the game. Keep the existing save; writes to that name are refused to protect newer progress. See Handling load results.

Saves load in the Editor but not in an Android or iOS build (Newtonsoft)

Cause: When building with IL2CPP, Unity may remove code it thinks is unused. This can include constructors, setters or other members Newtonsoft needs to load your data.

Fix: Preserve the required types and members with [Preserve] or link.xml, then test saving and loading in a build on the target device. See Choosing a serializer.

On This Page