Save — Public API¶

Namespace: RevGaming.RevFramework.Core.Save Assembly: RevFramework.Core — ships in every package, with no define guard.

Supported surface at a glance¶

IRevSaveParticipant¶

The interface your own state implements. Framework systems are not privileged — they implement the same one.

public interface IRevSaveParticipant
{
    string Key { get; }
    int Version { get; }
    string Capture();
    void Restore(string payload, int version);
}

IRevSaveOrdered and RevSaveOrder¶

Optional, and most participants should not implement it. Restoring is normally independent per section — Inventory does not care whether Health has run.

public interface IRevSaveOrdered
{
    int RestoreOrder { get; }
}

public static class RevSaveOrder
{
    public const int Default = 0;      // what a non-implementer is treated as
    public const int Early   = -1000;  // before ordinary participants
    public const int Late    = 1000;   // after them
}

Implement it only when your restore reads or writes another system's state, because that is the only case where order can change the outcome. CraftingSaveParticipant is the framework's one example: its restore reconciles offline progress, delivering craft outputs into the inventory and refunding currency, so it declares RevSaveOrder.Late.

RevSaveCoordinator¶

Static and stateless. Two saves running against different participant sets cannot interfere, and there is no instance to wire up or keep alive.

public static string Capture(IEnumerable<IRevSaveParticipant> participants);

public static string Capture(
    IEnumerable<IRevSaveParticipant> participants,
    out RevSaveReport report,
    IEnumerable<RevSaveSection> carryOver = null);

public static RevSaveReport Restore(
    string json,
    IEnumerable<IRevSaveParticipant> participants);

Capture¶

Restore¶

RevSaveManager¶

Component menu: RevFramework ▸ Core ▸ Save Manager. [DisallowMultipleComponent].

The coordinator's opinions — where the string lives, who contributes to it, and what happens to the sections a load could not place — have to live somewhere, and until 1.2.0 that somewhere was every project separately. This is them.

public IRevSaveStore Store { get; set; }
public IReadOnlyList<IRevSaveParticipant> Participants { get; }
public IReadOnlyList<RevSaveSection> CarriedOver { get; }

public event Action<string, RevSaveReport> SaveCompleted;
public event Action<string, RevSaveReport> LoadCompleted;

public bool Register(IRevSaveParticipant participant);
public bool Unregister(IRevSaveParticipant participant);
public void Clear();

public RevSaveReport Save(string slot);
public RevSaveReport Load(string slot);

public bool HasSave(string slot);
public bool Delete(string slot);
public bool TryListSlots(List<string> results);
public void DiscardCarriedOver();

Registration¶

Save(slot)¶

Load(slot)¶

Slots and carried data¶

IRevSaveStore and FileSaveStore¶

public interface IRevSaveStore
{
    bool TryRead(string slot, out string payload);
    bool TryWrite(string slot, string payload);
    bool Exists(string slot);
    bool TryDelete(string slot);
    bool TryListSlots(List<string> results);
}

The default store¶

RevSaveManager.Store defaults to a FileSaveStore rooted at Application.persistentDataPath/<saveFolderName>, where saveFolderName is a serialized inspector field defaulting to Saves. One file per slot, named <slot>.json.

Write failure — the exact guarantee¶

FileSaveStore.TryWrite writes the payload to a sibling <slot>.json.tmp, deletes the existing <slot>.json if there is one, and moves the temporary into place.

RevSaveReport¶

public IReadOnlyList<RevSaveSectionOutcome> Outcomes { get; }
public IReadOnlyList<RevSaveSection> Unrecognised { get; }
public IReadOnlyList<RevSaveSection> Unapplied { get; }
public IReadOnlyList<RevSaveSection> PartiallyApplied { get; }
public IReadOnlyList<RevSaveSection> Displaced { get; }
public string FatalError { get; }
public DateTime? SavedAtUtc { get; }
public bool Success { get; }
public override string ToString();

How the coordinator decides which list a failure lands in¶

public void Restore(string payload, int version)
{
    if (version > Version) throw new NotSupportedException(...);   // nothing touched: Unapplied

    foreach (var entry in Parse(payload))
    {
        RevSaveRestore.MarkMutated();                              // from here on, any throw
        Apply(entry);                                              // is PartiallyApplied
    }
}

RevSavePartialRestoreException is still the better tool when you know you failed partway: it carries a message naming what did and did not land, which a classification alone cannot. MarkMutated is the backstop for the failure you did not anticipate — which is, by definition, the one you did not write a message for.

Calling MarkMutated() outside a restore does nothing, so a participant's own unit tests can call Restore directly without a coordinator around it.

The two supported members are the whole of that surface:

public static class RevSaveRestore
{
    public static void MarkMutated();     // idempotent; a plain field write
}

public sealed class RevSavePartialRestoreException : Exception
{
    public RevSavePartialRestoreException(string message);
    public RevSavePartialRestoreException(string message, Exception inner);
}

Worth naming the owners that did not restore in that message: the ones that did are no longer recoverable from the save.

All four section lists hand back copies. RevSaveSection has public fields for JsonUtility, so IReadOnlyList protects the list and not its contents — editing what you are given cannot reach anything the framework is still holding, and the same instances are safe to pass straight back as carryOver.

RevSaveSectionStatus¶

public enum RevSaveSectionStatus
{
    Ok = 0,
    Skipped = 1,
    Unrecognised = 2,
    Failed = 3,
    DuplicateKey = 4,
    PartiallyApplied = 5,
    Displaced = 6,
}

RevSaveSectionOutcome¶

public string Key { get; }
public RevSaveSectionStatus Status { get; }
public string Message { get; }
public override string ToString();

Message is populated for anything other than Ok.

RevSaveSection and RevSaveEnvelope¶

Both are [Serializable] with public fields so the envelope round-trips through JsonUtility — which keeps a JSON library out of RevFramework.Core, an assembly that ships everywhere and has no dependencies to spend.

[Serializable] public sealed class RevSaveSection
{
    public string key;      // participant key this section belongs to
    public int version;     // participant's payload version at time of writing
    public string payload;  // the participant's own payload; never parsed by the coordinator
}

[Serializable] public sealed class RevSaveEnvelope
{
    public int envelopeVersion;
    public string frameworkVersion;   // diagnostic only
    public string savedAtUtc;         // round-trip "o"; read it on RevSaveReport.SavedAtUtc
    public List<RevSaveSection> sections;

    public const int CurrentEnvelopeVersion = 1;
}

You will normally only touch RevSaveSection as an opaque item in report.Unrecognised.

StableId¶

Namespace: RevGaming.RevFramework.Core.Identity Component menu: RevFramework ▸ Core ▸ Stable Id

public string Id { get; }
public void AssignId(string value);   // throws ArgumentException on null/whitespace

Framework participants¶

Namespace: RevGaming.RevFramework.Integrations.Save.* Each lives in a define-gated assembly and compiles only when its system is present.

Their keys, payload formats and declared restore order are part of this contract. Their internals are not.

CurrencySaveParticipant takes one more optional argument than the table implies:

new CurrencySaveParticipant(
    service, currencies,
    reason: "RevSaveRestore",
    unsavedWallets: UnsavedWalletPolicy.Zero);   // default; or .Leave

UnsavedWalletPolicy decides what a restore does about an owner holding a wallet the save does not mention — Zero (default) zeroes what it holds, Leave keeps it and warns. This is the one participant that clears rather than applying on top, because the alternative is minting money. See System Guarantees Matrix → §8.

Explicitly not supported¶

• Parsing, rewriting or hand-authoring another participant's payload
• Branching on frameworkVersion
• Reading savedAtUtc out of the envelope yourself instead of from RevSaveReport.SavedAtUtc
• Relying on enumeration order to decide which of two duplicate keys wins
• Assuming an object without a StableId is saved, or that its absence is reported
• Assuming report.Success == false means nothing was applied
• Assuming a partial owner miss is reported — only a section that matched none of its owners is
• Assuming an IRevSaveStore write is atomic, or that a failed write left the previous save intact
• Reading a FileSaveStore slot file directly, or relying on the .tmp name it writes through
• Assuming Capture honours IRevSaveOrdered — it does not, and no capture order changes the file
• Reflecting into participant internals
• Calling the coordinator off the Unity main thread

Related¶

• Guarantees Matrix — the same surface expressed as guarantees and non-guarantees; §12 covers the manager and the store
• Integration Surfaces — implementing IRevSaveParticipant, IRevSaveOrdered or IRevSaveStore for your own project
• System Boundaries — what the system refuses to do, and why