Save

Summary: Save data by name, either synchronously or with a completion callback.

Description

Save data by name, either synchronously or with a completion callback. The synchronous overload waits for the write. The callback overload runs asynchronously and invokes the callback on Unity’s main thread.

Call either overload from Unity’s main thread. The callback overload still serializes the data on the main thread before queuing the write. Storage that requires the main thread, such as PlayerPrefs, also writes there.

Declaration

C#
public static SaveResult Save<T>(T data, string name, SaveOptions options = null);

public static void Save<T>(T data, string name, Action<SaveResult> callback, SaveOptions options = null);

Parameters

ParameterTypeDescription
T—Type of the data to save.
dataTThe data to save.
namestringName of the save.
optionsSaveOptionsOptional. Slot, protection and compression settings. Null uses the defaults.
callbackAction<SaveResult>Callback overload only. Called on the main thread with the result when the save is finished.

Returns

The synchronous overload returns a SaveResult. The callback overload passes the result to callback. Check IsSuccess on the result.

Exceptions

ExceptionThrown when
ArgumentNullExceptionThe callback overload receives a null callback.
InvalidOperationExceptionThe method is called from a thread other than Unity’s main thread.

Example

Create either SavePositionSynchronous.cs or SavePositionWithCallback.cs using the matching block. Attach the script to an active GameObject and enter Play mode. It saves that GameObject’s position once and reports the result in the Console.

Synchronous · C#
using Gley.SaveSystem;
using UnityEngine;

public class SavePositionSynchronous : MonoBehaviour
{
    private void Start()
    {
        SaveResult result = API.Save(transform.position, "position-sync-example");

        if (result.IsSuccess)
        {
            Debug.Log("Saved the GameObject's position.", this);
        }
        else
        {
            Debug.LogWarning($"Save failed ({result.Status}): {result.Message}", this);
        }
    }
}
With callback · C#
using Gley.SaveSystem;
using UnityEngine;

public class SavePositionWithCallback : MonoBehaviour
{
    private void Start()
    {
        API.Save(transform.position, "position-callback-example", OnSaved);
    }

    private void OnSaved(SaveResult result)
    {
        if (result.IsSuccess)
        {
            Debug.Log("Saved the GameObject's position.", this);
        }
        else
        {
            Debug.LogWarning($"Save failed ({result.Status}): {result.Message}", this);
        }
    }
}

To load the saved position, use API.Load<Vector3>("position-sync-example") for the synchronous example or API.Load<Vector3>("position-callback-example") for the callback example. See the Load reference.

Player progress in a file

Group the level, coins and checkpoint in one serializable PlayerProgress object. One API.Save call writes the whole object, and API.Load<PlayerProgress> restores it.

Use the File backend for your active platform. Check the Backend column under Tools › Gley › Save System › General. Default (File) also works.

The Save and Load pages share this example. Create PlayerProgressFileExample.cs once and attach it to a GameObject. Enter Play mode and choose Save Progress from the component’s Inspector menu. Change the values under Progress, then choose Load Progress to restore the saved values.

Player progress · C#
using System;
using Gley.SaveSystem;
using UnityEngine;

public class PlayerProgressFileExample : MonoBehaviour
{
    private const string SaveName = "player-progress-example";

    [SerializeField] private PlayerProgress _progress = new PlayerProgress();

    // Use these two Inspector commands to test saving and loading in Play mode.
    // In your game, call the Save System API from your own save and load code.
    [ContextMenu("Save Progress")]
    private void SaveProgress()
    {
        if (!Application.isPlaying)
        {
            return;
        }

        SaveResult result = API.Save(_progress, SaveName);
        Debug.Log($"Save result: {result.Status}", this);
    }

    [ContextMenu("Load Progress")]
    private void LoadProgress()
    {
        if (!Application.isPlaying)
        {
            return;
        }

        LoadResult<PlayerProgress> result = API.Load<PlayerProgress>(SaveName);
        if (!result.IsSuccess)
        {
            Debug.LogWarning($"Load failed ({result.Status}): {result.Message}", this);
            return;
        }

        _progress = result.Data;
        Debug.Log($"Loaded level {_progress.Level}, {_progress.Coins} coins, checkpoint {_progress.Checkpoint}.", this);
    }

    [Serializable]
    private sealed class PlayerProgress
    {
        [SerializeField] private string _checkpoint = "camp";
        [SerializeField] private int _level = 1;
        [SerializeField] private int _coins = 25;

        public string Checkpoint => _checkpoint;
        public int Level => _level;
        public int Coins => _coins;
    }
}

With the default folder settings, the file is Saves/default/player-progress-example.sav under Application.persistentDataPath. To find it in Unity, go to Tools › Gley › Save System › Save Viewer and choose Open save folder.

On This Page