6.6 Data-Driven Design, Save/Load

You already know how to write a C# class and put values in its fields. This chapter asks a different question: where should those values live? In every example so far, numbers went straight into a script — an enemy's health was typed as a number inside the Enemy script itself. That is fine for a five-minute prototype. It stops working the moment a real game has fifty enemy types, or the moment a game designer (someone who is not writing C#) needs to change a health value and cannot wait for a programmer to do it. This chapter covers data-driven design (keeping content in data instead of hard-coding it into scripts), Unity's ScriptableObject tool for that, and then the other half of the topic: saving a player's progress to disk and making sure that save still works after you patch the game.

1. What data-driven design means

Data-driven design means the specific numbers and content of your game (an enemy's health, a weapon's damage, the text of a line of dialogue, how much gold a chest drops) live in data — separate files or assets — instead of being typed as literal numbers inside your C# scripts. The script becomes generic: it reads whatever data it is given and acts on it. It does not know or care whether it is running for a goblin or a dragon; it just reads maxHealth from whatever data object was handed to it.

The opposite is hard-coding: writing the actual number straight into the code, like int maxHealth = 20; sitting inside a script called Goblin. If you want an orc too, the usual beginner move is to copy that script and change the numbers, giving you Goblin.cs, Orc.cs, Dragon.cs — three scripts that are 90% identical, differing only in the numbers.

Why this matters for designers and balancing

Balancing a game (tuning numbers like damage, health, and cost until the game feels fair and fun) is not a one-time job. You playtest, a fight feels too easy, you lower the enemy's health by 10%, you playtest again, you repeat this dozens of times per enemy. If every tweak means opening a C# file, changing a number, and waiting for Unity to recompile the script, that loop is slow — and it means only programmers can do it.

With data-driven design, the numbers live in an asset a designer can open and edit directly inside the Unity Editor, with no code and no recompiling. This has two big effects: programmers and designers can work at the same time without stepping on each other's files, and balancing becomes fast enough to do dozens of times in an afternoon. It also makes adding content cheap — a new enemy type is a new data asset with new numbers, not a new script.

2. Unity's tool for this: ScriptableObject

A MonoBehaviour (the base class you already use for scripts on GameObjects) lives attached to a specific object in a specific scene. A ScriptableObject is different: it is a class that holds data as an asset — a file that lives in your Project folder, not attached to any GameObject or scene. You create it once, and any number of GameObjects across any number of scenes can point at that same asset and read its values.

Two things make ScriptableObjects convenient for data-driven design. First, the [CreateAssetMenu] attribute lets a designer right-click in the Project window and choose Create to make a new instance of that data — no code required. Second, because it is a real asset, it shows up in the Inspector like any other Unity object, with a friendly field-by-field editing view designers already know how to use.

A ScriptableObject is not attached to anything and never gets an Update() call — it just sits there holding values until something asks it for them. That makes it a good fit for content that does not change while the game runs: an enemy's base stats, an item's description, a weapon's damage. It is a bad fit for anything that changes every frame, like a live health bar (that belongs in a normal script, as you will see in the next section).

3. Worked example: turning a hard-coded enemy into a data asset

Here is a typical beginner setup: one script per enemy type, numbers hard-coded directly into each one.

using UnityEngine;

public class Goblin : MonoBehaviour
{
    public int maxHealth = 20;
    public int damage = 5;
    public float moveSpeed = 2f;
    public int goldReward = 10;
}

public class Orc : MonoBehaviour
{
    public int maxHealth = 60;
    public int damage = 12;
    public float moveSpeed = 1.2f;
    public int goldReward = 30;
}

Every new enemy type means a new script that looks almost exactly like the last one. Changing the goblin's health means opening Goblin.cs, editing a number, and recompiling. Let us fix this with a ScriptableObject that holds the data, so we only need one enemy script ever.

using UnityEngine;

[CreateAssetMenu(fileName = "NewEnemyData", menuName = "Data/Enemy")]
public class EnemyData : ScriptableObject
{
    public string enemyName;
    public int maxHealth;
    public int damage;
    public float moveSpeed;
    public int goldReward;
}

With this script saved in the project, a designer right-clicks in the Project window, picks Create > Data > Enemy, and gets a new asset file. They do this twice, name the assets Goblin and Orc, and fill in the fields in the Inspector — no code touched at all.

Using the data asset at runtime

Now write one Enemy script that any enemy GameObject can use. It holds a reference to an EnemyData asset and reads from it.

using UnityEngine;

public class Enemy : MonoBehaviour
{
    public EnemyData data;          // shared asset reference, read-only
    private int currentHealth;      // per-instance state, lives HERE, not in the asset

    private void Awake()
    {
        currentHealth = data.maxHealth;
    }

    public void TakeDamage(int amount)
    {
        currentHealth -= amount;
        if (currentHealth <= 0)
        {
            Die();
        }
    }

    private void Die()
    {
        Debug.Log(data.enemyName + " died. Reward: " + data.goldReward + " gold.");
        Destroy(gameObject);
    }
}

Drop the Enemy script onto a GameObject, drag the Goblin asset into its data slot, and you have a goblin. Drag Orc into a different GameObject's data slot instead, and that one is an orc — same script, different data. Trace what happens if this goblin's data has enemyName = "Goblin", maxHealth = 20, goldReward = 10, and something calls TakeDamage(25) once: currentHealth starts at 20, drops to -5, which is zero or less, so Die() runs and prints:

Goblin died. Reward: 10 gold.

4. External data files: JSON and CSV

ScriptableObjects are great, but they are still Unity assets, edited inside the Unity Editor. Sometimes your data needs to live outside Unity entirely: a huge spreadsheet of item stats a designer maintains in Google Sheets, or a list your live-service backend sends down after launch. For that, games commonly use two plain text formats: JSON and CSV.

JSON (JavaScript Object Notation) is a text format for structured data, written as key-value pairs inside curly braces, with square brackets for lists. CSV (Comma-Separated Values) is a plain text table: one row per line, values separated by commas — exactly what you get exporting a spreadsheet. In Unity, a JSON or CSV file gets imported as a TextAsset (an asset type that just holds raw text), which you can read in a script.

Here is a small item database as a JSON file, with a C# script that loads it. Note that the whole file is one JSON object with an items field holding the list — Unity's JSON reader cannot parse a bare list at the top level, so we wrap it.

{
  "items": [
    { "itemId": "potion_small", "displayName": "Small Potion", "baseValue": 10 },
    { "itemId": "sword_iron", "displayName": "Iron Sword", "baseValue": 120 }
  ]
}

using System.Collections.Generic;
using UnityEngine;

[System.Serializable]
public class ItemDefinitionData
{
    public string itemId;
    public string displayName;
    public int baseValue;
}

[System.Serializable]
public class ItemDatabase
{
    public List<ItemDefinitionData> items;
}

public class ItemDatabaseLoader : MonoBehaviour
{
    public TextAsset itemsJsonFile;   // drag the .json file onto this slot in the Inspector

    private void Start()
    {
        ItemDatabase db = JsonUtility.FromJson<ItemDatabase>(itemsJsonFile.text);
        Debug.Log("Loaded " + db.items.Count + " items.");
    }
}

Loaded 2 items.

CSV needs a little manual parsing since Unity has no built-in CSV reader, but it is short: split each line on commas.

string line = "sword_iron,Iron Sword,120";
string[] fields = line.Split(',');

string itemId = fields[0];
string displayName = fields[1];
int baseValue = int.Parse(fields[2]);

Debug.Log(itemId + " costs " + baseValue);

sword_iron costs 120

5. ScriptableObject vs JSON/CSV: when to use each

Both are data-driven. The choice is about workflow, not which one is "better".

• Use a ScriptableObject when the data needs to directly reference other Unity assets (a Sprite icon, an audio clip, a prefab), when a designer will edit it inside the Unity Editor with a nice Inspector view, or when the content ships baked into the game and does not need to change after release.
• Use JSON or CSV when the data is authored outside Unity (a spreadsheet a designer maintains, or an export from another tool), when non-programmers need to edit huge tables (hundreds of rows are easier as a spreadsheet than as hundreds of separate asset files), or when the content needs to be updated after the game has shipped without submitting a new build — for example a live-service balance patch downloaded from a server.

6. What "save game" actually means

Everything so far — EnemyData, ItemDatabase — is content: it is the same for every player and does not change while the game runs (it ships as part of the game). Save data is different: it is the specific state of one player's current playthrough — their level, their gold, their inventory, where they are standing, which quests they finished. Content ships with the game; save data is created and changed while someone plays.

Saving means writing a snapshot of the current game state to a file so it can be restored later. There is one rule that matters more than any other: save plain values, never references to live objects. A GameObject, a MonoBehaviour, a Transform, a Sprite — all of these only exist while the game is running, inside memory Unity is currently managing. The moment the game closes, they are gone. A reference to one of them is meaningless the next time the game starts, because that exact object was never created yet. Instead, save the numbers and strings that describe the state: a position as three floats (x, y, z), an inventory item as a string ID and a count, not the item's GameObject or its script instance.

Converting a live, in-memory object into a storable form (like text) is called serialization. Turning it back into a usable object is deserialization. That is exactly what the next two sections build.

7. Serializing to JSON with JsonUtility

First, design a plain data class that holds exactly the values you want to save — nothing more. This kind of class, whose only job is holding data with no real behavior, is sometimes called a POCO (Plain Old C# Object).

using System.Collections.Generic;

[System.Serializable]
public class InventoryItemData
{
    public string itemId;
    public int count;
}

[System.Serializable]
public class SaveData
{
    public int saveVersion = 2;
    public string playerName;
    public int level;
    public int gold;
    public float posX;
    public float posY;
    public float posZ;
    public List<InventoryItemData> inventory = new List<InventoryItemData>();
}

Notice saveVersion at the top — section 9 explains exactly why it is there. Now gather live game values into this class. This is the moment you copy numbers out of live objects, never the objects themselves.

using System.Collections.Generic;
using UnityEngine;

public class SaveController : MonoBehaviour
{
    public PlayerStats playerStats;
    public Inventory inventory;

    public SaveData BuildSaveData()
    {
        SaveData data = new SaveData();
        data.playerName = playerStats.playerName;
        data.level = playerStats.level;
        data.gold = playerStats.gold;

        Vector3 pos = playerStats.transform.position;
        data.posX = pos.x;
        data.posY = pos.y;
        data.posZ = pos.z;

        data.inventory = new List<InventoryItemData>();
        foreach (InventorySlot slot in inventory.slots)
        {
            InventoryItemData itemData = new InventoryItemData();
            itemData.itemId = slot.item.itemId;   // save the ID string, not the item asset itself
            itemData.count = slot.count;
            data.inventory.Add(itemData);
        }

        return data;
    }
}

Unity's built-in JsonUtility converts a [System.Serializable] object to and from a JSON string. Here is the smallest possible round trip:

SaveData data = new SaveData();
data.playerName = "Nova";
data.level = 5;
data.gold = 120;

string json = JsonUtility.ToJson(data, true);   // true = pretty-print with indentation
Debug.Log(json);

{
    "saveVersion": 2,
    "playerName": "Nova",
    "level": 5,
    "gold": 120,
    "posX": 0,
    "posY": 0,
    "posZ": 0,
    "inventory": []
}

Trace it: every field we set (playerName, level, gold) shows its value, and every field we never touched (posX, posY, posZ, the empty inventory list) shows its default. That is just an ordinary C# object turned into text.

8. Writing and reading files: persistent storage

A JSON string only helps once it is on disk. Unity gives you Application.persistentDataPath: a folder guaranteed to be writable, whose exact location Unity picks correctly for whatever platform the game is running on (a different folder on Windows, macOS, and mobile — you never need to know or hardcode which one). Combine that with System.IO.File to write and read text.

using System;
using System.IO;
using UnityEngine;

public static class SaveManager
{
    private const int CURRENT_SAVE_VERSION = 2;

    private static string GetSavePath()
    {
        return Path.Combine(Application.persistentDataPath, "save.json");
    }

    public static void Save(SaveData data)
    {
        data.saveVersion = CURRENT_SAVE_VERSION;
        string json = JsonUtility.ToJson(data, true);
        File.WriteAllText(GetSavePath(), json);
        Debug.Log("Saved game to " + GetSavePath());
    }

    public static SaveData Load()
    {
        string path = GetSavePath();

        if (!File.Exists(path))
        {
            Debug.Log("No save file found. Starting a new game.");
            return new SaveData();
        }

        try
        {
            string json = File.ReadAllText(path);
            SaveData data = JsonUtility.FromJson<SaveData>(json);
            data = MigrateIfNeeded(data);
            return data;
        }
        catch (Exception e)
        {
            Debug.LogWarning("Save file was corrupted, starting fresh. " + e.Message);
            return new SaveData();
        }
    }

    private static SaveData MigrateIfNeeded(SaveData data)
    {
        if (data.saveVersion < CURRENT_SAVE_VERSION)
        {
            Debug.Log("Upgrading save from version " + data.saveVersion + " to " + CURRENT_SAVE_VERSION);
            data.saveVersion = CURRENT_SAVE_VERSION;
        }
        return data;
    }
}

Trace a first-ever run, before any save file exists: Load() checks File.Exists(path), finds nothing, and returns a brand-new SaveData:

No save file found. Starting a new game.

Call SaveManager.Save(data) and it writes the file, printing something like:

Saved game to /storage/emulated/0/Android/data/com.yourstudio.yourgame/files/save.json

(The exact path text differs by platform — that is exactly why we asked Application.persistentDataPath instead of typing a path ourselves.)

9. Versioning your save data

Here is the problem versioning solves. You ship version 1.0 of your game. Players save their progress — files sitting on their disks with whatever shape SaveData had at that moment. Three months later you patch the game and, say, split hp (an int from 0 to 100) into a new field healthPercent (a float from 0 to 1) because the new health system needs it that way. Every save file already on a player's disk still has the old shape. If you just delete hp and add healthPercent with nothing connecting them, every returning player's health silently resets, because healthPercent was never in their old file and gets its C# default.

The fix: add an int saveVersion field (you already saw it sitting in SaveData since section 7). Every time you save, stamp the current version number into it. Every time you load, check the version you read against the current version your code expects, and if it is older, run migration code — code whose only job is upgrading an old save's shape into the new one — before anything else touches the data.

[System.Serializable]
public class SaveData
{
    public int saveVersion = 2;

    // Deprecated: kept only so JsonUtility can still read old version-1 save files.
    public int hp;

    // New in version 2: health is stored as a percentage instead of a raw hit-point number.
    public float healthPercent = 1f;
}

private static SaveData MigrateIfNeeded(SaveData data)
{
    if (data.saveVersion == 1)
    {
        data.healthPercent = data.hp / 100f;
        data.saveVersion = 2;
    }
    return data;
}

Trace it for a returning player whose old file has {"saveVersion": 1, "hp": 40}: JsonUtility.FromJson fills in hp = 40 (the field still exists in the class, so it still matches by name), healthPercent stays at its default of 1, then MigrateIfNeeded sees saveVersion == 1, computes healthPercent = 40 / 100f = 0.4, and bumps saveVersion to 2. The player keeps their 40% health instead of it silently resetting to full or empty.

10. Common save/load pitfalls

11. A note on cloud saves for live-service games

A live-service game (a game that keeps running and receiving updates after launch, usually tied to online player accounts) typically cannot rely on a save file sitting on one device — players expect their progress to follow them if they switch phones or play on a different PC. The common approach: upload the same JSON blob you already built for the local file to a backend service tied to the player's account (examples include PlayFab, Steam Cloud, or a studio's own server), and download it again when they sign in elsewhere.

This introduces a new problem local saves do not have: conflicts. If a player plays offline on two devices and both eventually reconnect, whose save wins? The simplest strategy, and a reasonable default for a beginner project, is last-write-wins: keep a timestamp with the save and let whichever upload is newest overwrite the rest. It is not perfect — a player could lose real progress made on the "losing" device — but more sophisticated merging (combining specific fields instead of picking one whole save) is a much bigger design problem saved for later. Whatever strategy you use, keep the same saveVersion field in the cloud copy too; migrations apply the same way whether the JSON came from local disk or from a server.

12. Glossary

• Data-driven design — keeping a game's content and numbers in data (assets or files) instead of hard-coded inside scripts.
• Hard-coding — writing a specific value directly into code instead of reading it from data.
• ScriptableObject — a Unity class for data that lives as its own asset file, shareable by many GameObjects, not attached to any scene.
• CreateAssetMenu — the attribute that adds a "Create new asset" option to Unity's right-click menu for a ScriptableObject.
• JSON — JavaScript Object Notation, a text format for structured data using key-value pairs and lists.
• CSV — Comma-Separated Values, a plain text table format, one row per line.
• TextAsset — Unity's asset type for a plain text file (such as .json or .csv) that a script can read.
• Serialization / deserialization — converting a live in-memory object into a storable form (like text), and converting it back.
• POCO — Plain Old C# Object; a simple class that just holds data with no real behavior.
• JsonUtility — Unity's built-in tool for converting [System.Serializable] objects to and from JSON text.
• Application.persistentDataPath — a writable folder Unity provides whose exact location is correct for whatever platform the game is running on.
• Save version / migration — a number stamped into saved data recording its shape, and the code that upgrades an old save to match the current shape.
• Live-service game — a game that keeps running and receiving updates after launch, usually with online player accounts.
• Cloud save — save data uploaded to a backend service tied to a player's account, so progress follows them across devices.

13. Exercises

using UnityEngine;

public class Sword : MonoBehaviour
{
    public string weaponName = "Sword";
    public int damage = 10;
    public float attackSpeed = 1.0f;
}

public class Bow : MonoBehaviour
{
    public string weaponName = "Bow";
    public int damage = 6;
    public float attackSpeed = 1.8f;
}

using UnityEngine;

[CreateAssetMenu(fileName = "NewWeaponData", menuName = "Data/Weapon")]
public class WeaponData : ScriptableObject
{
    public string weaponName;
    public int damage;
    public float attackSpeed;
}

using UnityEngine;

public class Weapon : MonoBehaviour
{
    public WeaponData data;

    public void Attack()
    {
        Debug.Log(data.weaponName + " hits for " + data.damage + " damage.");
    }
}

[System.Serializable]
public class SaveData
{
    public int saveVersion = 1;
    public string playerName;
    public int level;
    public int gold;
}

private const int CURRENT_SAVE_VERSION = 1;

private static SaveData MigrateIfNeeded(SaveData data)
{
    return data;
}

[System.Serializable]
public class SaveData
{
    public int saveVersion = 2;
    public string playerName;
    public int level;
    public int gold;
    public int highScore;
}

private const int CURRENT_SAVE_VERSION = 2;

private static SaveData MigrateIfNeeded(SaveData data)
{
    if (data.saveVersion == 1)
    {
        data.highScore = data.level * 100;
        data.saveVersion = 2;
    }
    return data;
}

// version 1 shape, already shipped and on players' disks:
[System.Serializable]
public class SaveData
{
    public int saveVersion = 1;
    public int hp;   // 0 to 100
}

[System.Serializable]
public class SaveData
{
    public int saveVersion = 2;

    // Deprecated: kept only so JsonUtility can still read old version-1 save files.
    public int hp;

    public float healthPercent = 1f;
}

private static SaveData MigrateIfNeeded(SaveData data)
{
    if (data.saveVersion == 1)
    {
        data.healthPercent = data.hp / 100f;
        data.saveVersion = 2;
    }
    return data;
}