Public API

This document covers the public API for Crystal Save, a comprehensive save system for Unity with support for local storage, cloud backends (Supabase, Firebase, Unity Cloud Save, MySQL), encryption, compression, and screenshot capture.

---

Common Use Cases (FAQ)

Loading Without a Scene Reload

Q: Can I load a saved slot without reloading the scene?

Yes! Set restoreLastActiveScene to false. This loads and restores all saved component data, prefabs, and GameObject states without triggering a scene change:

// Load slot 1 without changing scenes - restores all data in-place
SaveManager.Instance.Load(1, restoreLastActiveScene: false);

// Or with async version
LoadResult result = await SaveManager.Instance.LoadSaveSlotAsync(
    slotNumber: 1,
    restoreLastActiveScene: false  // Key parameter!
);

This is useful when:

• Your game uses a persistent scene architecture

• You want to restore player progress without a loading screen

• You're implementing a "revert to checkpoint" feature within the same scene

---

Hooking Into Load Completion Events

Q: How can I run my own code after a save slot is successfully loaded?

Subscribe to the OnLoadCompleted event. This fires after all data has been restored, making it the perfect place to re-wire references in your GameManager:

using Arawn.CrystalSave.Runtime;
using UnityEngine;

public class GameManager : MonoBehaviour
{
    public static GameManager Instance { get; private set; }
    
    private Player currentPlayer;

    void Awake()
    {
        Instance = this;
    }

    void Start()
    {
        // Subscribe to load completion
        SaveManager.Instance.OnLoadCompleted += OnSaveSlotLoaded;
        
        // Also handle failures
        SaveManager.Instance.OnLoadFailed += OnSaveSlotLoadFailed;
    }

    void OnDestroy()
    {
        // Always unsubscribe to prevent memory leaks
        if (SaveManager.Instance != null)
        {
            SaveManager.Instance.OnLoadCompleted -= OnSaveSlotLoaded;
            SaveManager.Instance.OnLoadFailed -= OnSaveSlotLoadFailed;
        }
    }

    private void OnSaveSlotLoaded(object sender, SaveLoadEventArgs args)
    {
        Debug.Log($"Slot {args.Slot.SlotNumber} loaded successfully!");
        
        // Re-wire your restored character to the GameManager
        currentPlayer = FindObjectOfType<Player>();
        
        if (currentPlayer != null)
        {
            // Hook up references, register with systems, etc.
            currentPlayer.Initialize();
            RegisterPlayerWithSystems(currentPlayer);
        }
        
        // Update UI
        UIManager.Instance?.RefreshPlayerStats();
        
        // Resume gameplay
        Time.timeScale = 1f;
    }

    private void OnSaveSlotLoadFailed(object sender, OperationFailedEventArgs args)
    {
        Debug.LogError($"Failed to load: {args.ErrorMessage}");
        // Show error UI to player
    }

    private void RegisterPlayerWithSystems(Player player)
    {
        // Your custom logic here
        CameraController.Instance?.SetTarget(player.transform);
        AudioManager.Instance?.SetListener(player.transform);
    }
}

Available Event Args Properties

Event	Args Type	Properties
OnLoadCompleted	SaveLoadEventArgs	Slot (SaveSlot), Success (bool), Message (string)
OnLoadFailed	OperationFailedEventArgs	Slot (SaveSlot), Operation (string), ErrorMessage (string)
OnSaveCompleted	SaveLoadEventArgs	Slot (SaveSlot), Success (bool), Message (string)
OnSaveFailed	OperationFailedEventArgs	Slot (SaveSlot), Operation (string), ErrorMessage (string)

---

Getting Started

Crystal Save uses a singleton pattern. Access the save manager via:

using Arawn.CrystalSave.Runtime;

SaveManager manager = SaveManager.Instance;

Initialization

The SaveManager initializes automatically on Awake(). You can check if it's ready:

if (SaveManager.Instance.IsInitialized)
{
    // Safe to perform save/load operations
}

Or subscribe to the initialization event:

SaveManager.Initialized += (manager) =>
{
    Debug.Log("SaveManager is ready!");
};

---

SaveManager Singleton

Properties

Property	Type	Description
Instance	SaveManager	Static singleton instance
IsInitialized	bool	Returns true when the manager is fully initialized
CurrentSaveSlot	SaveSlot	The currently active save slot
CurrentSaveData	SaveData	The current in-memory save data
SaveSettings	SaveSettings	The active save settings configuration
AreSaveSlotsReady	bool (static)	True once save slots have been initialized
AreQuickSlotsReady	bool (static)	True once quick save slots have been initialized

---

Save Operations

Save (Fire-and-Forget)

// Basic save to slot 1
SaveManager.Instance.Save(1, "MainMenu");

// Save with custom slot name
SaveManager.Instance.Save(1, "Level1", "My First Save");

Parameters

Parameter	Type	Description
slotNumber	int	The slot number to save to (1-based)
lastActiveScene	string	The scene name to restore on load
slotName	string	(Optional) Custom name for the save slot

SaveAsync (Awaitable)

await SaveManager.Instance.SaveAsync(1, "Level1");

// With cancellation support
var cts = new CancellationTokenSource();
await SaveManager.Instance.SaveAsync(1, "Level1", cts.Token);

SaveSync (Synchronous)

// Blocks until save completes - use sparingly!
SaveManager.Instance.SaveSync(1, "Level1", captureScreenshot: true);

SaveImmediateAsync (No Delay)

Performs an immediate save without any batching or delay:

await SaveManager.Instance.SaveImmediateAsync(1, "Level1");

---

Load Operations

Load (Fire-and-Forget)

// Load slot 1 and restore the saved scene
SaveManager.Instance.Load(1, restoreLastActiveScene: true);

// Load slot 1 without changing scenes
SaveManager.Instance.Load(1, restoreLastActiveScene: false);

// Load with async scene loading
SaveManager.Instance.Load(1, restoreLastActiveScene: true, loadAsync: true, allowSceneActivation: true);

Parameters

Parameter	Type	Default	Description
slotNumber	int	-	The slot number to load
restoreLastActiveScene	bool	false	Whether to load the saved scene
loadAsync	bool	false	Use async scene loading
allowSceneActivation	bool	true	Allow scene activation when loaded

LoadSaveSlotAsync (Awaitable with Result)

LoadResult result = await SaveManager.Instance.LoadSaveSlotAsync(
    slotNumber: 1,
    restoreLastActiveScene: true,
    loadAsync: true,
    allowSceneActivation: true,
    timeout: TimeSpan.FromSeconds(30),
    cancellationToken: default
);

if (result.Success)
{
    Debug.Log("Load completed successfully!");
}
else
{
    Debug.LogError($"Load failed: {result.ErrorMessage}");
}

LoadSaveDataForSlotAsync (Data Only, No Scene Change)

Load save data without triggering a scene change:

SaveData data = await SaveManager.Instance.LoadSaveDataForSlotAsync(1);

if (data != null)
{
    // Access the loaded data
    Debug.Log($"Loaded {data.Components.Count} components");
}

---

Quick Save & Auto Save

Quick Save

// Fire-and-forget quick save
SaveManager.Instance.QuickSave();

// Async quick save with rotating slots
await SaveManager.Instance.QuickSaveAsync();

Quick Load

// Fire-and-forget quick load
SaveManager.Instance.QuickLoad();

// Async quick load
await SaveManager.Instance.QuickLoadAsync(
    loadAsync: true,
    allowSceneActivation: true,
    timeout: TimeSpan.FromSeconds(30)
);

Auto Save

// Fire-and-forget auto save
SaveManager.Instance.AutoSave();

// Async auto save
await SaveManager.Instance.AutoSaveAsync();

Auto Load

// Fire-and-forget auto load
SaveManager.Instance.AutoLoad(restoreScene: true);
// or
SaveManager.Instance.LoadAutoSave(restoreScene: true);

// Async auto load
await SaveManager.Instance.LoadAutoSaveAsync(
    restoreScene: true,
    loadAsync: true,
    allowSceneActivation: true
);

---

Slot Management

Get Save Slots

// Get all save slots
List<SaveSlot> slots = SaveManager.Instance.GetSaveSlots();

// Get a specific slot by number
SaveSlot slot = SaveManager.Instance.GetSaveSlotByNumber(1);

// Get a specific slot by name
SaveSlot slotByName = SaveManager.Instance.GetSaveSlotByName("My Save");

// Get the most recent save
SaveSlot latestSlot = SaveManager.Instance.GetLatestSaveSlot();

Check for Saves

// Check if any save exists (async - recommended for cloud save)
bool hasSave = await SaveManager.Instance.HasSaveAsync();

// Check if a specific slot has a save
bool hasSlotSave = await SaveManager.Instance.HasSaveAtAsync(1);

// Check for saves after a specific date
bool hasRecentSave = await SaveManager.Instance.HasSaveAfterDateAsync(DateTime.Now.AddDays(-7));

// Check for saves in a specific scene
bool hasSceneSave = await SaveManager.Instance.HasSaveInSceneAsync("Level1");

// Quick check using slot timestamps (works with cloud save)
bool hasAny = SaveManager.Instance.HasAnySaveInSlots();

Note: When cloud save is enabled, prefer async methods to avoid blocking the main thread.

Rename Save Slot

// Async rename (recommended)
bool success = await SaveManager.Instance.RenameSaveSlotAsync(1, "New Save Name");

// Synchronous rename (blocks on cloud save)
SaveManager.Instance.RenameSlot(1, "New Save Name");

Delete Save Slot

SaveManager.Instance.Delete(1);

Get Slot Metadata

// Async (fetches from remote if needed)
SaveSlot metadata = await SaveManager.Instance.GetSlotMetadataAsync(1);

// Synchronous (local only for cloud backends)
SaveSlot localMeta = SaveManager.Instance.GetSlotMetadata(1);

Refresh Slots

Force a refresh of slot data from both local and remote sources:

await SaveManager.Instance.ForceRefreshSlotsAsync();

---

Screenshot Management

Get Screenshot

SaveSlot slot = SaveManager.Instance.GetSaveSlotByNumber(1);
Texture2D screenshot = SaveManager.Instance.GetScreenshot(slot);

if (screenshot != null)
{
    // Use the screenshot texture
    rawImage.texture = screenshot;
}

Capture Screenshot Manually

string screenshotFileName = SaveManager.Instance.CaptureScreenshotSync(1);

Cleanup Unused Screenshots

SaveManager.Instance.CleanupScreenshots();

---

Scene Transitions & Prefabs

Load Scene with Snapshot (In-Memory)

Load a scene while preserving prefab state in memory (no disk write):

// By scene name
await SaveManager.Instance.LoadSceneWithSnapshotAsync("Level2", loadAdditive: false, loadAsync: true);

// By build index
await SaveManager.Instance.LoadSceneWithSnapshotAsync(2, loadAdditive: false, loadAsync: true);

Load Scene After Save and Populate

Save to a slot, populate pending prefabs, then load a scene:

await SaveManager.Instance.LoadSceneAfterSaveAndPopulatePendingPrefabsAsync(
    slotNumber: 1,
    lastActiveScene: "Level1",
    targetSceneName: "Level2",
    loadAdditive: false,
    loadAsync: true
);

Snapshot-Based Scene Transition (No Disk Write)

Create an in-memory snapshot and populate pending prefabs, then load a scene:

await SaveManager.Instance.LoadSceneAfterSnapshotAndPopulatePendingPrefabsAsync(
    sceneName: "Level2",
    loadAdditive: false,
    loadAsync: true,
    allowDuplicateLoad: false
);

Snapshot Current Data

Capture the current game state in memory without writing to disk:

bool success = SaveManager.Instance.SnapshotCurrentData("CurrentScene");

Snapshot and Populate

Capture game state and prepare pending prefabs for scene transitions:

bool success = await SaveManager.Instance.SnapshotAndPopulateAsync("CurrentScene");

Populate Pending Prefabs

Populate prefab data from a save slot (useful for custom scene loaders):

// From a specific slot
await SaveManager.Instance.PopulatePendingPrefabsFromSlotAsync(1);

// From in-memory snapshot
await SaveManager.Instance.PopulatePendingPrefabsFromSnapshotAsync();

---

Single GameObject Restoration

Restore individual GameObjects without a full load operation.

From Current Save Data

// Restore by UniqueID
bool success = await SaveManager.Instance.RestoreSingleGameObjectFromCurrentDataAsync("player_001");

// Restore a specific GameObject
GameObject player = GameObject.Find("Player");
await SaveManager.Instance.RestoreSingleGameObjectFromCurrentDataAsync(player);

From a Specific Slot

// Restore by UniqueID from slot
bool success = await SaveManager.Instance.RestoreSingleGameObjectFromSlotAsync("player_001", slotNumber: 1);

// Restore a specific GameObject from slot
await SaveManager.Instance.RestoreSingleGameObjectFromSlotAsync(player, slotNumber: 1);

Restore Multiple GameObjects

// From current data
List<string> idsToRestore = new List<string> { "player_001", "npc_002", "chest_003" };
await SaveManager.Instance.RestoreSingleGameObjectsFromCurrentDataAsync(idsToRestore);

// From most recent slot
await SaveManager.Instance.RestoreSingleGameObjectsFromMostRecentSlotAsync(idsToRestore);

Restore All Destroyed GameObjects

// From current data
await SaveManager.Instance.RestoreAllDestroyedGameObjectsFromCurrentDataAsync();

// From a specific slot
await SaveManager.Instance.RestoreAllDestroyedGameObjectsFromSlotAsync(1);

---

Events

Initialization Events

// Static event - fires when SaveManager is ready
SaveManager.Initialized += (manager) => { };

// Static event - fires when save slots are initialized
SaveManager.SaveSlotsInitialized += () => { };

// Static event - fires when quick slots are initialized
SaveManager.QuickSlotsInitialized += () => { };

Save/Load Completion Events

SaveManager.Instance.OnSaveCompleted += (sender, args) =>
{
    Debug.Log($"Saved slot {args.Slot.SlotNumber}: {args.Message}");
};

SaveManager.Instance.OnLoadCompleted += (sender, args) =>
{
    Debug.Log($"Loaded slot {args.Slot.SlotNumber}: {args.Message}");
};

SaveManager.Instance.OnDeleteCompleted += (sender, args) =>
{
    Debug.Log($"Deleted slot {args.Slot.SlotNumber}");
};

SaveManager.Instance.OnRenameSlotCompleted += (sender, args) =>
{
    Debug.Log($"Renamed slot from '{args.OldName}' to '{args.NewName}'");
};

Failure Events

SaveManager.Instance.OnSaveFailed += (sender, args) =>
{
    Debug.LogError($"Save failed: {args.ErrorMessage}");
};

SaveManager.Instance.OnLoadFailed += (sender, args) =>
{
    Debug.LogError($"Load failed: {args.ErrorMessage}");
};

SaveManager.Instance.OnDeleteFailed += (sender, args) =>
{
    Debug.LogError($"Delete failed: {args.ErrorMessage}");
};

SaveManager.Instance.OnRenameSlotFailed += (sender, args) =>
{
    Debug.LogError($"Rename failed: {args.ErrorMessage}");
};

SaveManager.Instance.OnBackupFailed += (sender, args) =>
{
    Debug.LogError($"Backup failed: {args.ErrorMessage}");
};

SaveManager.Instance.OnVerificationFailed += (sender, args) =>
{
    Debug.LogError($"Verification failed: {args.ErrorMessage}");
};

Scene Loading Events

SaveManager.Instance.OnSceneLoadStarted += (sceneName) =>
{
    Debug.Log($"Loading scene: {sceneName}");
};

SaveManager.Instance.OnSceneLoadProgress += (progress) =>
{
    Debug.Log($"Load progress: {progress * 100}%");
};

SaveManager.Instance.OnSceneLoadCompleted += (sceneName) =>
{
    Debug.Log($"Scene loaded: {sceneName}");
};

SaveManager.Instance.OnSceneActivationRequested += (sceneName) =>
{
    Debug.Log($"Scene activation requested: {sceneName}");
};

Screenshot Events

SaveManager.Instance.OnScreenshotCaptureStarted += () =>
{
    // Hide UI elements before screenshot
};

SaveManager.Instance.OnScreenshotCaptureFinished += () =>
{
    // Restore UI elements after screenshot
};

Slot Update Events

SaveManager.Instance.OnSaveSlotsUpdated += () =>
{
    // Refresh save slot UI
};

SaveManager.Instance.OnQuickSlotsUpdated += () =>
{
    // Refresh quick save UI
};

GameObject Restoration Events

SaveManager.Instance.OnGameObjectRestored += (uniqueId) =>
{
    Debug.Log($"Restored GameObject: {uniqueId}");
};

SaveManager.Instance.OnAllGameObjectsRestored += () =>
{
    Debug.Log("All GameObjects restored");
};

SaveManager.Instance.OnSingleGameObjectRestored += (gameObject) =>
{
    Debug.Log($"Single GameObject restored: {gameObject.name}");
};

Scene Activation Pipeline

Control when prefabs spawn during scene activation:

// Only spawn prefabs when loading screen is hidden
SaveManager.Instance.SceneActivationPipeline = (sceneName) =>
{
    return !IsLoadingScreenVisible();
};

---

Extension Methods

Extension methods are available in the Arawn.CrystalSave.Runtime namespace.

Reset All Save Slots

await SaveManager.Instance.ResetAllSaveSlots();

Get Active Save Slots

List<SaveSlot> activeSlots = await SaveManager.Instance.GetActiveSaveSlots();

Save to All Slots

await SaveManager.Instance.SaveToAllSlots("CurrentScene");

Load Most Recent Slot

await SaveManager.Instance.LoadMostRecentSlot();

Restore from Most Recent Slot

await SaveManager.Instance.RestoreSingleGameObjectsFromMostRecentSlotAsync(
    new List<string> { "player_001", "inventory_001" }
);

---

Diagnostics & Utilities

Get Load State Diagnostics

string diagnostics = SaveManager.Instance.GetLoadStateDiagnostics();
Debug.Log(diagnostics);

Output example:

=== Crystal Save Load State Diagnostics ===
Current Save Data Loaded: Yes
  - Saved Prefabs: 15
  - Last Active Scene: Level1
Active Scene: Level2
Loaded Scenes: 2
  [0] Level2 (Active: True)
  [1] Persistent (Active: False)
Scenes with Pending Prefabs: 1
  - Level3

Get Pending Prefab Info

// Get count of queued prefabs
int pendingCount = SaveManager.Instance.GetPendingPrefabCount();

// Get scenes with pending prefabs
List<string> scenes = SaveManager.Instance.GetScenesWithPendingPrefabs();

Validate Scene Loading Timing

SaveManager.Instance.ValidateSceneLoadingTiming("MyOperation", "Level2");

Clear Pending Prefabs

⚠️ Warning: This permanently discards queued prefabs!

SaveManager.Instance.ClearPendingPrefabs();

---

Scene Load Orchestrator

For advanced scene loading scenarios (Addressables, asset bundles), register a custom orchestrator:

public class MyCustomLoader : SceneLoadOrchestratorBase
{
    public override async Task OnScenePreLoad(string sceneName)
    {
        // Prime prefab data before scene loads
        await SaveManager.Instance.PopulatePendingPrefabsFromSlotAsync(0);
    }

    public override async Task OnSceneWillActivate(Scene scene)
    {
        // Custom logic before scene activation
    }

    public override void OnSceneActivated(Scene scene)
    {
        // Custom logic after scene activation
    }

    public override void OnSceneUnloaded(Scene scene)
    {
        // Cleanup logic after scene unloads
    }
}

// Register the orchestrator
SaveManager.Instance.RegisterSceneLoadOrchestrator(new MyCustomLoader());

// Unregister when done
SaveManager.Instance.UnregisterSceneLoadOrchestrator(orchestrator);

---

SaveSlot Class

The SaveSlot class represents metadata for a save slot.

Properties

Property	Type	Description
SlotNumber	int	The slot number (1-based)
SlotName	string	The display name of the slot
LastSaved	DateTime	When the slot was last saved
LastActiveScene	string	The scene name at time of save
ScreenshotFileName	string	Path to the screenshot file
CustomMetadata	Dictionary<string, string>	Custom key-value metadata

---

LoadResult Struct

Returned by async load operations.

Properties

Property	Type	Description
Success	bool	Whether the load succeeded
ErrorMessage	string	Error message if failed (null on success)

---

Best Practices

1. Use Async Methods with Cloud Save: When cloud save is enabled, always prefer *Async methods to avoid blocking the main thread.

2. Wait for Initialization: Always check IsInitialized or subscribe to Initialized before performing operations.

3. Handle Failures: Subscribe to failure events to provide user feedback when operations fail.

4. Scene Transitions: Use LoadSceneAfterSnapshotAndPopulatePendingPrefabsAsync for seamless scene transitions with prefab persistence.

5. Screenshots: Use OnScreenshotCaptureStarted and OnScreenshotCaptureFinished to hide/show UI elements.

6. Diagnostics: Use GetLoadStateDiagnostics() when debugging scene loading issues.

---

Version Compatibility

• Unity: 2022.3 LTS and Unity 6+

• Serialization: MemoryPack

• Cloud Backends: Supabase, Firebase, Unity Cloud Save, MySQL