Skip to content

Save — Documentation Guide

Where should I start?

New to the save system?

Start with Overview, then Mental Model.

Between them they explain:

  • What the coordinator does, and what it deliberately does not do
  • Why participants exist, and why none of the five systems changed to gain one
  • How one save file holds state from systems that share no common shape
  • What StableId is for, and why nothing saves without it

Just want to save to a slot and get on with it?

Add RevSaveManager (RevFramework ▸ Core ▸ Save Manager), register your participants, and call Save("slot1").

It holds the participant list, writes through a replaceable IRevSaveStore — defaulting to one file per slot under Application.persistentDataPath — and carries forward the sections a load could not place, which is the part almost nobody wires by hand.

Public API documents it in full, including what a failed write does and does not promise.

Want to know what you can safely depend on?

Read Public API.

That page defines:

  • The supported runtime surface
  • What each type guarantees
  • What is diagnostic only and must not be branched on
  • Explicitly unsupported usage

This is the contract

If something is not listed there, it is not supported — even if it appears public in code.

Saving your own game state?

Read Integration Surfaces.

Framework systems are not privileged here. Quest flags, unlocked levels and settings join the same save file through the same interface, and that page shows exactly how — including the parts that are easy to get wrong, like key stability and what a version number is actually for.

Deciding how to use it?

Read the FAQ. It covers questions like:

  • Where should the save file live?
  • What happens when a player loads a save from an older build?
  • What happens on a SKU that does not have every system?
  • Should a participant throw, or return null?
  • Why did my object not save?

It focuses on decision-making, not API reference.

How these documents work together

Document Purpose
Overview Explains the system
Mental Model Explains how to think about it
Public API Defines what is supported
Integration Surfaces Shows where your own logic plugs in
System Boundaries States what the system is not, and what it refuses to do
Guarantees Matrix Defines behavioural contracts, including non-guarantees
Testing Philosophy Explains what the tests prove, and what they deliberately do not
FAQ Guides correct usage choices

You do not need to read everything — start with what matches your task.

Important support note

The save system is:

  • Coordinator-driven — participants never talk to each other
  • Format-agnostic — the coordinator never parses a payload
  • Storage-replaceable — the coordinator never touches the filesystem; RevSaveManager supplies a default IRevSaveStore you can swap
  • Failure-isolating — one bad section never costs the rest
  • SKU-aware — loading a save on a build without every system is supported, not an error

Support is provided for

  • Behaviour defined in Public API
  • Usage patterns described in Overview, FAQ and Integration Surfaces
  • Guarantees listed in the Guarantees Matrix

Support is not provided for

  • Parsing or rewriting another participant's payload
  • Branching on frameworkVersion, which is diagnostic only
  • Reading the envelope's savedAtUtc field by parsing the save string yourself — the supported route is RevSaveReport.SavedAtUtc, which is handed to you already parsed
  • Relying on participant enumeration order to resolve a duplicate key
  • Assuming an object without a StableId will be saved
  • Reflecting into participant internals
  • Participants — Integrations/Save/ contains one participant per system, plus the guide to writing your own
  • Storage — RevSaveManager and FileSaveStore in Runtime/Core/Save/, for slots and the bytes
  • Teaching panel — SaveCoordinatorPanel captures, restores and shows the per-section report live in a scene. It teaches the coordinator contract only; it writes no file
  • Sample — Samples/Systems/Save/Scenes/00_Save_Quickstart/00_Save_Quickstart.unity

System philosophy

The save system is:

  • A router, not a serialiser — it moves payloads without understanding them
  • A reporter, not a thrower — a broken section is described, not raised
  • A composition point, not an owner — no system's state lives here

The design question it answers is not "how do I serialise this?" Every system already knew that. It is "how do five systems that share no common shape end up in one file, without any of them changing?"

TL;DR

TL;DR

  • Want to understand it → Overview
  • Want to build safely → Public API
  • Want to save your own state → Integration Surfaces
  • Want to choose correctly → FAQ
  • Want to know what it will not do → System Boundaries

One rule matters more than the rest: every object whose state you want saved needs a StableId. Without one it is invisible to every participant — not saved, not restored, and not reported as missing.