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);
}

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¶

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 bool Success { get; }
public override string ToString();

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;         // diagnostic only, round-trip "o" format
    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 and payload formats 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 or 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
• Ordering CraftingSaveParticipant before Inventory or Currency
• Reflecting into participant internals
• Calling the coordinator off the Unity main thread

Related¶

• Guarantees Matrix — the same surface expressed as guarantees and non-guarantees
• Integration Surfaces — implementing IRevSaveParticipant for your own state
• System Boundaries — what the system refuses to do, and why