📦 Lesson 5.4: A JSON Save/Load System (Mini-Project)

The Save/Load Round-Trip

Every save system is the same four-step loop: gather live game state into a plain data object, turn that object into text, write the text to a file — and reverse the whole chain to load. Hold this picture in your head; the rest of the lesson just fills in each arrow.

Figure 1: The round-trip. Saving flows object → JSON → disk; loading flows disk → JSON → object, then applies it back to the running game.

The SaveData Class

The heart of the system is a plain data class — no MonoBehaviour, no logic — that holds exactly what you want to persist. It must be marked [System.Serializable] so Unity will serialize it, and its fields must be serializable too.

using System;
using System.Collections.Generic;
using UnityEngine;

[Serializable]
public class SaveData
{
    public int saveVersion = 1;      // for migrations later

    // Player transform (Vector3 IS serializable)
    public Vector3 playerPosition;
    public float   playerRotationY;

    // Stats
    public int   level;
    public float health;
    public int   gold;

    // Inventory — a List of a serializable item struct
    public List<InventoryEntry> inventory = new List<InventoryEntry>();
}

[Serializable]
public struct InventoryEntry
{
    public string itemId;   // e.g. "sword_iron"
    public int    quantity;
}

Three things make this work:

• Every type used is serializable — int, float, string, Vector3 (Unity built-in), and a List<T> of another [Serializable] type.
• They're public fields, not properties. JsonUtility serializes fields, and only serializes auto-properties if you add [SerializeField] to their backing field — so fields are simplest here.
• The nested InventoryEntry struct is itself [Serializable], so a whole list of items round-trips cleanly.

JsonUtility: To & From JSON

With a serializable class, converting to and from JSON is two calls:

// Object -> JSON string. Pass true for pretty (indented) output.
string json = JsonUtility.ToJson(saveData, prettyPrint: true);

// JSON string -> new object.
SaveData loaded = JsonUtility.FromJson<SaveData>(json);

// Or fill an EXISTING object in place (handy for config reloads):
JsonUtility.FromJsonOverwrite(json, existingSaveData);

The SaveData above serializes to text like this:

{
    "saveVersion": 1,
    "playerPosition": { "x": 12.5, "y": 0.0, "z": -8.25 },
    "playerRotationY": 90.0,
    "level": 3,
    "health": 74.5,
    "gold": 250,
    "inventory": [
        { "itemId": "sword_iron", "quantity": 1 },
        { "itemId": "potion_health", "quantity": 5 }
    ]
}

Readable, diff-able, and hand-editable during development. That legibility is a big reason to prefer a JSON file over cramming a blob into PlayerPrefs.

Writing to persistentDataPath

Where does the file go? Never hard-code a path like C:\Saves — it won't exist on other machines or platforms, and some folders are read-only in a build. Unity gives you a guaranteed-writable, per-user, per-app folder: Application.persistentDataPath.

using System.IO;
using UnityEngine;

string path = Path.Combine(Application.persistentDataPath, "save.json");
Debug.Log(path);
// Windows:  C:/Users/<you>/AppData/LocalLow/<Company>/<Product>/save.json
// macOS:    ~/Library/Application Support/<Company>/<Product>/save.json
// Android:  /storage/emulated/0/Android/data/<package>/files/save.json

Building the path with Path.Combine (not string concatenation) keeps the slashes correct on every OS. Then reading and writing is the standard .NET file API:

File.WriteAllText(path, json);        // save
string json = File.ReadAllText(path); // load
bool exists = File.Exists(path);      // is there a save?
File.Delete(path);                    // delete the save

The Full SaveSystem

Here's the reusable piece: a static SaveSystem that saves, loads, checks, and deletes. Notice the try/catch around file I/O — disks fail, files get corrupted, and a save system that throws an unhandled exception can soft-lock a game.

using System.IO;
using UnityEngine;

public static class SaveSystem
{
    static string Path =>
        System.IO.Path.Combine(Application.persistentDataPath, "save.json");

    public static void Save(SaveData data)
    {
        try
        {
            string json = JsonUtility.ToJson(data, true);
            File.WriteAllText(Path, json);
            Debug.Log($"Saved to {Path}");
        }
        catch (System.Exception e)
        {
            Debug.LogError($"Save failed: {e.Message}");
        }
    }

    public static SaveData Load()
    {
        if (!File.Exists(Path))
        {
            Debug.Log("No save found; starting fresh.");
            return new SaveData();          // defaults
        }

        try
        {
            string json = File.ReadAllText(Path);
            SaveData data = JsonUtility.FromJson<SaveData>(json);
            return SaveMigrator.Migrate(data);   // handle old versions
        }
        catch (System.Exception e)
        {
            Debug.LogError($"Load failed, using defaults: {e.Message}");
            return new SaveData();
        }
    }

    public static bool HasSave() => File.Exists(Path);

    public static void Delete()
    {
        if (File.Exists(Path)) File.Delete(Path);
    }
}

And the glue that reads live state into a SaveData and applies it back — this is where your specific game objects plug in:

public class GameSaveController : MonoBehaviour
{
    [SerializeField] Transform player;
    [SerializeField] PlayerStats stats;      // your own stats component
    [SerializeField] Inventory inventory;    // your own inventory component

    public void SaveGame()
    {
        var data = new SaveData
        {
            playerPosition  = player.position,
            playerRotationY = player.eulerAngles.y,
            level  = stats.Level,
            health = stats.Health,
            gold   = stats.Gold,
            inventory = inventory.ToEntries()   // returns List<InventoryEntry>
        };
        SaveSystem.Save(data);
    }

    public void LoadGame()
    {
        SaveData data = SaveSystem.Load();
        player.position    = data.playerPosition;
        player.eulerAngles = new Vector3(0f, data.playerRotationY, 0f);
        stats.Set(data.level, data.health, data.gold);
        inventory.FromEntries(data.inventory);
    }
}

💡 Keep gathering and applying in one place. The SaveSystem knows nothing about your game — it just moves a SaveData to and from disk. GameSaveController is the only script that touches both the save data and your live objects. That separation is what makes SaveSystem droppable into your next project unchanged.

Versioning Your Saves

Ship your game, players make saves — then in a patch you add a new stat or rename a field. Old save files still exist on their disks. Without a plan, loading one either crashes or silently drops data. The fix is the saveVersion field we added on day one.

public static class SaveMigrator
{
    public const int CurrentVersion = 2;

    public static SaveData Migrate(SaveData data)
    {
        // v1 had no "gold" field -> JsonUtility leaves it at 0.
        if (data.saveVersion < 2)
        {
            data.gold = 100;          // grandfather old players a starter purse
            data.saveVersion = 2;
        }

        // future: if (data.saveVersion < 3) { ... }

        data.saveVersion = CurrentVersion;
        return data;
    }
}

Because JsonUtility simply ignores JSON fields that don't exist on the class and leaves missing fields at their defaults, adding a field is safe — the migrator's job is to fill in sensible values for saves made before that field existed.

JsonUtility's Gotchas

JsonUtility is fast and built-in, but it is deliberately minimal. Design your SaveData around these hard limits:

• No Dictionary<K,V>. Dictionaries don't serialize. Store two parallel Lists, or a List of a small key-value struct (as our InventoryEntry does).
• No polymorphism. If SaveData has a List<Item> and you put a Weapon : Item in it, only the Item fields are saved — the subclass is flattened. Use an enum "type" field + one flat struct, or a different serializer.
• Top level must be an object. JsonUtility.ToJson(myList) won't work — wrap the list in a class (that's why SaveData holds the list rather than being one).
• No null distinction for value types, and it won't serialize static or const fields.

🔒 A word on security. A JSON file is plain text a player can open and edit — same caveat as PlayerPrefs. For a single-player game that's usually fine (let them cheat their own save). For anything competitive or monetized, the authoritative state must live on a server; never trust a local save for values that matter.

Mini-Project: Save & Restore the Player

Time to tie Module 5 together. You'll build a scene where the player can walk around, pick up items, take damage — then save, quit, relaunch, and load back into exactly the state they left.

Summary

🚀 What's Next?

You've closed out Module 5: your game can move between scenes smoothly and remember everything that matters. Next we shift into the Systems Track and give the world a brain. In Lesson 6.1: The NavMesh: Baking & Agents you'll install the AI Navigation package, bake a walkable surface, and send your first agent chasing a destination.