Remote Storage

Installation

  • Complete the steps in Getting Started if LionSDK is not installed.

  • If LionSDK is already installed,

    • Install the package Lion - Remote Storage .

Make sure the “Hide Package” button is disabled to see the relevant package folders.

Quick Start

  1. Setup Firebase.

  2. Setup Firestore.

    1. If integrated, users will be able to retrieve game data even after reinstall.

  3. Setup Facebook Authentication (Optional, but recommended, if you want Facebook login data sync)

    1. If integrated, users will be able to retrieve game data from their other devices after a Facebook login.

Implementation

Reading & Writing Data

All reads and writes are instant and local:

RemoteStorage.SetInt("coins", 100);
int coins = RemoteStorage.GetInt("coins", 0);
RemoteStorage.SetValue("profile", playerProfile);

Saving to the Cloud

Cloud saving is manual — call the awaitable Save() Whenever you want to push data to the cloud:

bool synced = await RemoteStorage.Save();
if (!synced)
{
    // Cloud unreachable
}

  • Returns true once the data has reached the cloud.

  • Returns false If the cloud cannot be reached, local data is safe.

  • If authentication or the first sync failed (for example, the game started offline), the next Save() sync recovers by itself — it authenticates, pulls and merges the cloud save, then pushes. OnRemoteDataUpdated fires if the cloud save wins that merge.

Call Save() at meaningful moments — after level completion, after a purchase, or on app pause. Data also syncs once automatically during module initialization (pull → merge → push).

Using the OnRemoteDataUpdated Event

When data is synced from the cloud, a merge conflict may occur between local and remote data. If the remote data wins (because it has a more recent purchase, higher XP, or newer save time), the local data is replaced.

When this happens, RemoteStorage.OnRemoteDataUpdated fires so your game can reload its in-memory state. This is also the right moment to tell the player their progress was restored — for example, show a popup saying the save was loaded from the cloud.

RemoteStorage.OnRemoteDataUpdated += () =>
{
    // Cloud data replaced local data — reload your in-memory state
    coins = RemoteStorage.GetInt("coins", 0);
    volume = RemoteStorage.GetFloat("volume", 1f);
    playerProfile = RemoteStorage.GetValue<PlayerProfile>("profile", new PlayerProfile());
};

If you cache storage values in memory (e.g. at game start), those cached values will be stale after a cloud merge. Always listen to OnRemoteDataUpdated and re-read your data to keep your game state in sync.

Advanced

Initialization Flow

  1. Initialize() loads data from PlayerPrefs immediately and returns without waiting for the cloud.

  2. Background sync starts: Firebase Email/Password auth → pull remote data → merge → push.

  3. Remote Storage does NOT block LionSDK initialization.

IsDataReady Behaviour differs by session type:

  • Returning user (local data exists): IsDataReady = true Local data is playable immediately.

  • First session (no local data): IsDataReady = true only after the background cloud sync completes (or fails). Show a loading indicator until ready.

Architecture Overview

Remote Storage uses a local‑first architecture. All reads and writes are instantly saved to local storage (PlayerPrefs). Cloud synchronization with Firestore happens in the background, so it never blocks your game.

Game Code → RemoteStorage API → LocalStorage (PlayerPrefs) → instant reads/writes
                                         ↕
                               CloudSyncManager (background)
                                         ↕
                                  Firestore (cloud)
API

RemoteStorage Static API

Member
Type
Description

IsInitialized

bool

true once the module has completed initialization (local data loaded).

OnInitialized

event Action

Fires when initialization completes.

CurrentSyncState

SyncState

Current cloud sync state.

OnSyncStateChanged

event Action<SyncState>

Fires when sync state changes.

CurrentMergeConflictData

MergeConflictData

The current merge conflict data from the active storage, or null.

OnRemoteDataUpdated

event Action

Fires when cloud data replaces local data after a merge — reload cached values and optionally show a save-restored popup.

IsDataReady

bool

true when save data is ready to read. On a first session it becomes true only after the initial cloud sync attempt.

Save()

Task<bool>

Saves locally and pushes data to the cloud. Returns false if the cloud could not be reached — local data is safe.

Save(MergeConflictData)

Task<bool>

Same as Save(), but updates the merge conflict data first. Call it after progression or purchase updates.

DeleteAll()

void

Clears local data, deletes the cloud save, and removes the account — the next session starts fresh. Used by the LionSDK delete-progress flow.

SyncState API

Use the SyncState API to monitor the current status of the cloud synchronization.

SyncState Enum

State
Description

LocalOnly

Cloud sync has not started yet (initial state).

Authenticating

Firebase email auth is in progress.

Syncing

Pulling or pushing data to Firestore.

Synced

Cloud and local data are in sync.

Failed

Auth or sync failed. Local data is safe and playable.

Checking Current State

if (RemoteStorage.CurrentSyncState == SyncState.Synced)
{
    Debug.Log("Cloud data is in sync!");
}

Subscribing to State Changes

RemoteStorage.OnSyncStateChanged += (state) =>
{
    Debug.Log($"Sync state changed: {state}");
    
    if (state == SyncState.Failed)
    {
        // Show offline indicator to the player
    }
};

PreviousAppChargeNextFirestore

Last updated

Was this helpful?