beasty-save-system / beasty-save-system.md
Beasty Save System
Beasty Save System saves and loads your game’s data as JSON files on disk, with no external dependencies and no exceptions thrown at you. It works two ways: drop two components in a scene and wire a button, or call a five-line C# API from your own code.
What makes it different
Zero dependencies. The package ships its own JSON engine. No Newtonsoft, no JsonUtility limits, no
package-manager entries to reconcile with the rest of your project.
Every call returns a typed result. BeastySave.Save returns a SaveResult. BeastySave.Load<T>
returns a LoadResult<T>. Nothing throws at you. You check Success, read the Error code, and decide
what the player sees — including offering the automatic backup when a file turns out to be corrupt.
Safe by default. Saves are written atomically: to a temp file, then swapped over the slot. A crash
mid-write cannot leave you with half a save. The previous file is rotated to a .bak, and a file that
fails its checksum is never allowed to overwrite the last good copy.
Features
- Save any plain C# object, or the state of the components in your scene.
- A zero-code path:
BeastySaveManager+BeastySaveable+ a uGUI button. - Atomic writes, automatic
.bakbackups, SHA-256 checksums, and one-call backup restore. - Optional AES-256 encryption. Read encryption.md for its honest limits.
- Plain-text metadata (level, playtime, chapter) readable without decrypting the file, so a save-slot screen can list slots cheaply.
- Strict (all-or-nothing, with rollback) or tolerant (skip and warn) loading.
- Data versioning with registered migrations, so an update can read the saves your players already have.
- Pluggable storage backends: local files by default, or Firebase Firestore / Realtime Database in the cloud — plus an interface to write your own.
- JSON without files: produce and load the full save envelope as a string, for your own server or endpoint.
- Async variants for file IO, and full async coverage for cloud backends.
- Seven optional converter modules (Animation, Audio, Particles, Physics2D, Physics3D, TMPro, UGUI), each of which compiles only when the matching Unity module is in the project.
- An editor window that lists the saveables in your scene and the save files on disk.
- Unity 6000.2+, Mono and IL2CPP. WebGL is not supported.
Where to start
If you do not write C#, go to save-without-code.md. It walks you from an empty scene to a working save and load, clicking only.
If you do write C#, go to save-with-code.md. Five minutes, a data class, and a save file on disk.
Either way, install first: installation.md.
The one page everybody should read
what-gets-saved.md. It tells you which types round-trip, and — more importantly — that references to Unity objects (a sprite, a prefab, another component) are not saved. That is deliberate, and there is a right way to work with it. Reading that page before you build a save screen is worth the ten minutes.
Guides
Written for anyone, code or no code.
| Page | What it covers |
|---|---|
| what-gets-saved.md | Supported types, what is not saved, the errors that fail a save |
| settings.md | Every BeastySaveSettings field and when to change it |
| scene-state.md | BeastySaveable, BeastySaveManager, ids, spawned objects |
| slots-and-metadata.md | Slots, listing them, and building a save-slot screen |
| backups-and-corruption.md | Atomic writes, .bak files, restoring one |
| encryption.md | AES, and what encryption does and does not protect |
| strict-vs-tolerant.md | The two loading modes |
| versioning-and-migrations.md | Shipping an update that reads old saves |
| async-saving.md | What the async methods really do |
| storage-backends.md | Where saves go: local files, the cloud, and per-user saves |
| firebase.md | Cloud saves with Firebase: Firestore and Realtime Database |
| save-manager-window.md | The editor window, section by section |
| logging.md | The Logging toggle, what each mode prints, and sending logs elsewhere |
Reference
Exact signatures, exact behaviour.
| Page | What it covers |
|---|---|
| api-beastysave.md | Every method on the BeastySave facade |
| results-and-errors.md | SaveResult, LoadResult<T>, the error codes |
| components.md | BeastySaveable and BeastySaveManager, field by field |
| converter-modules.md | The seven modules and exactly what each stores |
| save-file-format.md | The envelope, the group format, the pipelines |
| json-engine.md | JsonNode, JsonMapper, JsonParser, JsonWriter |
Advanced
| Page | What it covers |
|---|---|
| custom-converters.md | Teaching the system to save your own types |
| custom-backends.md | Writing a storage backend of your own |
| platforms-and-limits.md | Unity versions, IL2CPP, WebGL, performance |
When something goes wrong
troubleshooting.md maps a symptom to a cause to a fix. faq.md answers the questions that come up most.