> ## Documentation Index
> Fetch the complete documentation index at: https://docs.susaplay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud Saves

> Persist player progress across devices and sessions

## Overview

Cloud saves store one payload per slot, per player, per game. The payload is an opaque string —
serialize your own state into it. The platform versions each write and applies it inside a
server-side transaction.

## Write a save

```csharp theme={null}
var payload = JsonUtility.ToJson(new SaveState
{
    level = 12,
    coins = 1200
});

var saved = await SusaPlaySDK.CloudSave.Save("main", payload);

if (saved.success)
{
    Debug.Log($"Saved as version {saved.data.version}");
}
```

You do not supply a version. The server assigns the next one and returns it.

## Read a save

```csharp theme={null}
var loaded = await SusaPlaySDK.CloudSave.Load("main");

if (loaded.success)
{
    var state = JsonUtility.FromJson<SaveState>(loaded.data.data);
    ApplyProgress(state);
}
else
{
    StartFreshGame();
}
```

`success` is false both when the read failed and when the slot has never been written, so treat
it as "no save yet".

## Serializing state

Unity's `JsonUtility` only handles serializable fields on concrete classes — no dictionaries, no
polymorphism. For nested or dynamic state, either flatten it into a serializable class or bring
your own JSON library.

```csharp theme={null}
[System.Serializable]
public class SaveState
{
    public int level;
    public int coins;
    public string[] inventory;
}
```

## Multiple slots

Slots are independent. Use them to separate state that changes at different rates, so a settings
write cannot clobber progress.

```csharp theme={null}
await SusaPlaySDK.CloudSave.Save("progress", progressJson);
await SusaPlaySDK.CloudSave.Save("settings", settingsJson);
```

## Concurrency

Two sessions writing the same slot cannot corrupt each other — writes are transactional and the
later one wins with a higher version.

The SDK has no merge callback. If your game can realistically run in two tabs at once and
last-write-wins is not acceptable, read immediately before writing and merge in your own code.

## Rules

* Keep each slot under 500 KB
* Never store payment details or auth tokens in a save
* Save at natural checkpoints, not every frame — each write is a network round trip
* Keep unsaved state in memory when a write fails, and retry rather than dropping progress