Choosing a serializer

Summary: Choose JsonUtility or Newtonsoft, avoid skipped fields, and save object IDs instead of Unity references.

A serializer turns your save data into JSON and reads it back. Start with JsonUtility for simple data. Choose Newtonsoft when your data needs types that JsonUtility cannot preserve.

1. Match the serializer to your data

Your dataChoose
Numbers, booleans, strings, enums, Unity values such as Vector3, and serializable classes containing supported fields, lists or arraysJsonUtility. It is built into Unity and is the default.
Dictionaries, DateTime, nullable values, or other .NET collections such as HashSetNewtonsoft.
Different derived classes stored through a base typeJsonUtility needs [SerializeReference] on the relevant field. Newtonsoft supports polymorphism through its configured type handling.
GameObjects, components, prefabs, sprites or ScriptableObjectsSave an ID and plain values. Neither serializer saves Unity object references.

Save System wraps the top-level value internally, so you can also save a primitive, list or array directly. Use a class as the top-level value when you need to version your data later.

2. Check which members will be saved

JsonUtility saves fields, including private fields marked [SerializeField]. Mark your own data classes and structs [Serializable]. Properties, static fields, readonly fields and fields marked [NonSerialized] are not saved. A public property can expose a private serialized field to your gameplay code; the field is what JsonUtility stores.

JsonUtility skipsKeep JsonUtility by storing…
Dictionary<TKey, TValue>A list of serializable entries, each holding a key and value.
DateTime or TimeSpanTicks as a long. For dates, choose and consistently use UTC.
Nullable fields such as int?A normal value and a separate boolean indicating whether it is present.
HashSet, nested collections such as List<List<int>>, or multidimensional arraysA list, or a serializable wrapper around each inner collection.
Guid or decimalA string, or a scaled integer for decimal values when appropriate.

JsonUtility can skip unsupported fields without failing the save. For example, the save may succeed while a dictionary inside your data class is left out. The Editor and Save Viewer warn about known unsupported field types, but these warnings are not shown in builds. Test with recognizable values, save them, then load them and check that every value is restored.

Newtonsoft uses different rules from Unity. It saves public fields and public properties with getters by default. To include a private field, mark it with [JsonProperty]; Unity’s [SerializeField] alone is not enough. Use [JsonIgnore] to exclude a field or property.

A property also needs a way to receive its value when loading. The simplest options are a public getter and setter, or a private backing field marked [JsonProperty]. A getter-only property can appear in the saved JSON without its value being restored when you load.

3. Select the serializer

  1. Stop Play mode and open Tools › Gley › Save System.
  2. On the General tab, choose JsonUtility or Newtonsoft under Serializer.
  3. If Newtonsoft is missing, accept the installation of com.unity.nuget.newtonsoft-json and wait for Unity to finish compiling. Installing it through the install link alone does not change your selection; confirm the dropdown afterwards.
  4. Enter Play mode again. Save recognizable values, restart Play mode, and load them. Check every collection and optional value.
  5. Repeat in a build on your target platform. With Newtonsoft and IL2CPP stripping, preserve your save types and constructors with [Preserve] or link.xml as needed. An Editor test alone does not check stripping.

4. Save IDs instead of Unity objects

A Transform or prefab reference belongs to a Unity scene or asset. It is not a stable identifier for a later game session. If a serialized member contains a Unity object reference, Save System refuses the save with UnsupportedData and names the offending path.

An item ID is a name or number you assign to an item type in your game. For example, you could choose potion for a health potion and iron_sword for an iron sword. Save System does not generate these IDs; you define them in your own game code or item definitions. If your inventory system already gives each item type an ID, use that existing ID.

For example, to save an inventory containing three health potions:

  1. Assign the ID potion to the health potion in your game’s item definitions. Each item type needs its own ID; all health potions of this type share the same ID.
  2. When the player collects a health potion, read its ID from that definition. Store potion and the current count, 3, in your save data, instead of a reference to the potion prefab or ScriptableObject.
  3. After loading, your inventory code finds the item definition with the ID potion and restores a stack of three health potions. That definition can supply the display name, icon or prefab. Save System restores the ID and count; your game handles the lookup.

Choose each ID once and keep it unchanged between releases, even if you rename the item’s display name. Older saves still contain the original ID.

For an object you recreate in the scene, save the prefab’s ID together with its position and rotation. After loading, find the matching prefab in your game’s definitions, create it and apply those values. If you need to find a particular object that already exists in the scene, give that object its own stable ID so your code can distinguish it from other objects using the same prefab.

The included Save Example shows the inventory part: SaveExampleUI.cs defines the IDs gem and potion, PlayerProfile.cs uses them when items are collected, and InventoryItem.cs stores each ID and count. It also saves a movable token’s position as a Vector2.

5. Changing serializers after release

Each v3 save records the serializer that wrote it. Loading follows that record, so changing the dropdown affects future writes and does not require you to convert every existing save first. Older JsonUtility saves still load with JsonUtility after you select Newtonsoft.

Keep Newtonsoft installed while any existing saves need it, even if you switch new writes back to JsonUtility. A missing serializer returns SerializationError; Save System preserves the save and refuses to overwrite it. It does not fall back to another serializer.

The new serializer must support your current data, and your current class must still understand older saved members. Serializer selection does not repair earlier skipped fields or migrate renamed fields. Before shipping a switch, load copies of real saves from the previous build, save again, restart, and verify the new saves. For data changes, follow Changing your save data after release.

On This Page