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

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

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¶

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-agnostic — it performs no file I/O at all
• 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

Related resources¶

• Participants — Integrations/Save/ contains one participant per system, plus the guide to writing your own
• Teaching panel — SaveCoordinatorPanel captures, restores and shows the per-section report live in a scene
• Sample — Samples/Systems/Save/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¶

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.