Async Save & Load System for Unity

Asynchronous and production-ready save/load system designed for Unity. This package provides a component based framework for data persistence that is extensible, secure, and performant.

Core Features

• Asynchronous File Operations

• Safe-Saving Protocol

• Multiple Serialization Formats

• Component-Based Architecture

• Dynamic Object Persistence

• Performant UI Loading

• Advanced Editor Tooling

Dependencies

This package requires the following Unity packages to be installed in the project:

• Newtonsoft Json: com.unity.newtonsoft-json

• TextMeshPro: com.unity.textmeshpro

These dependencies are declared in the package.json and will be installed automatically by the Unity Package Manager.

Installation

This system is distributed as a Unity Package Manager (UPM) package via Git.

• In the Unity Editor, navigate to Window > Package Manager.

• Click the + icon in the top left corner and select Add package from git URL....

• Enter the repository URL and click Add.

Implementation Guide

Step 1: SaveManager Setup

The SaveManager is a singleton component for all save/load operations.

• Create an empty GameObject in a persistent scene (e.g., a startup or manager scene).

• Add the SaveManager.cs component to the GameObject.

• Configure the component in the Inspector:

• Save System Type: Select the desired serialization format (Json or Binary).

• Save File Base Name: Define the base name for save files (e.g., "gamedata").

Step 2: PrefabDatabase Configuration

The PrefabDatabase is a ScriptableObject that maps prefab assets to a unique ID for runtime instantiation.

• In the Project window, create a new database via right mous button inside project window > Create > Saving > Prefab Database.

• Assign the created PrefabDatabase asset to the corresponding field on the SaveManager.

• To automatically find and register all saveable prefabs in the project, click the "Scan Project for Saveable Prefabs" button in the PrefabDatabase inspector.

Step 3: Creating a Saveable Component

To make a component's data persistent, it must inherit from SaveableBehaviour and implement the serialization logic.

• Create a new C# script for your component (e.g. PlayerState.cs).

• Change the base class from MonoBehaviour to SaveableBehaviour.

• Override the SaveData and LoadData methods to define what data is saved and how it is restored.

Example (from Samples folder): PlayerSaveableExample.cs

using UnityEngine;
using System;
using Newtonsoft.Json;
using Zajceq.Utils.SaveSystem;

/// <summary>
/// Example ISaveable component for the Player GameObject
/// </summary>

public class PlayerSaveableExample : SaveableBehaviour
{
    [SerializeField] private float currentHealth = 100f;
    [SerializeField] private float mana = 100f;

    [Serializable]
    private struct PlayerData 
    {
        public float CurrentHealth;
        public float Mana;
    }

    public override void SaveData(ObjectSaveData objectSaveData)
    {
        var data = new PlayerData {CurrentHealth = currentHealth, Mana = mana};
        string json = JsonConvert.SerializeObject(data);
        objectSaveData.ComponentData[GetType().Name] = json;
    }

    public override void LoadData(ObjectSaveData objectSaveData)
    {
        if (objectSaveData != null && objectSaveData.ComponentData.TryGetValue(GetType().Name, out string json))
        {
            var data = JsonConvert.DeserializeObject<PlayerData>(json);
            currentHealth = data.CurrentHealth;
            mana = data.Mana;
        }
    }

    public override string MigrateData(string oldJsonData, int oldVersion)
    {
        //If migration is needed, add logic for it here
        return oldJsonData;
    }
}

Note: Every GameObject with a SaveableBehaviour must also have a GuidComponent attached to ensure a persistent, unique identity.

Step 4: Using the Samples

The package includes sample scene and scripts to demonstrate functionality.

• In the Package Manager, select the Save System package.

• Navigate to the Samples tab and import the desired examples.

• The imported samples include a pre-configured UI menu and example saveable objects.

System Architecture

The system is divided into several logical layers, each with a distinct responsibility.

Core Engine

• SaveManager.cs: The central singleton managing the entire save/load pipeline, object registration, and data migration.

• GuidComponent.cs: Provides persistent, unique identification for GameObjects across save/load cycles.

• SaveableBehaviour.cs: The abstract base class that provides common functionality for all saveable components, including automatic registration with the SaveManager.

• ISaveable.cs: The public interface defining the contract for a saveable component.

Serialization Systems

• ISaveSystem.cs: The interface defining the contract for a serialization strategy.

• JsonSaveSystem.cs: An ISaveSystem implementation for serializing data to human-readable JSON files.

• BinarySaveSystem.cs: An ISaveSystem implementation for serializing data to AES-encrypted binary files.

Data Structures

• GameData.cs: The root serializable class representing the entire state of a save file.

• ObjectSaveData.cs: A container for the serialized data of a single GameObject, mapping component type names to their JSON data.

• GameDataMeta.cs: A lightweight data structure containing only metadata about a save file (e.g., timestamp), used for fast UI population.

Editor Tools

• SaveSystemDebugger.cs: An editor window (Tools > Save System Debugger) that displays all currently registered ISaveable components and provides a real-time preview of their data with save/load buttons.

• SaveFileRepairUtility.cs: An editor window (Tools > Save File Repair Utility) for inspecting, decrypting, and manually editing save files.