Save format
The versioned container: what sits around the payload, what is authenticated, and the compatibility promise it carries.
The container, in one picture#
header format version, algorithm ids, sizes, key id, schema version
metadata save id, framework/game/build/platform, timestamps, playtime, revision, custom members
payload the serialized document (optionally compressed, optionally encrypted)
integrity the value that is verified before anything is parsedWhat is readable without a key#
The header and the metadata block. That is what lets a "Continue" menu list slots — labels, timestamps, playtime, backup counts, schema versions — without decrypting a single byte, and without a key present.
The format version is not your schema version#
Three numbers exist and they mean different things:
| Number | Belongs to | Changes when |
|---|---|---|
| Container format version | The framework | The physical layout changes — rare, and the reader accepts every version it has ever written |
| Schema version | Your game | You change your model — see Schema versions |
| Framework version | The package | The package is upgraded |
A framework upgrade never forces a migration, because the saved framework version is recorded for diagnostics rather than as a trigger.
Compatibility promise#
An older file is always readable. The container records its format version, and the reader accepts every version it has ever written. That is why upgrading the package is not a data migration event for your players.
Next#
- Serialization — the payload and the serializer seam.
- Schema versions — the number that is yours.
- Integrity — what is verified before parsing.
Something wrong on this page? Every page here describes behaviour that is checked in the repository. If a page and the package disagree, the package wins.
Report a documentation problem · Frequently asked questions · Troubleshooting