Limitations
Every package has edges. These are PersistKit's, stated plainly and before you find them in a bug report.
What it deliberately does not do#
| Not done | Why, and what to do instead |
|---|---|
| A scene object inside a component's field | Give that object a PersistKit Identity and save it under its own key. An identity is what makes it findable again; a field holding an object has nothing stable to write down |
| A list of references in one component field | The field path writes one value per field, because it goes through Unity's serializer. A list of references is a saved value in its own right: Persist.SaveReferences("party", theList) and Persist.LoadReferences("party", into) |
| A list that mixes scene objects and assets | One list holds one kind. A mixed list is refused with the sentence saying so rather than stored in a way that could half-resolve |
| C# properties | Unity's serializer does not save them. Use a field |
| Collections nested more than two deep | Flatten, or save two keys |
Collection types other than arrays, List<T> and Dictionary<K,V> | Convert to one of those before saving |
| Asynchronous local save and load | A local save is a small file write. The cloud operations are the asynchronous ones |
| Addressables | The registry is the table, and PersistKitAssetRegistry.Instance lets you point it at your own resolver. No Addressables dependency |
| A Dictionary field inside your own class | A documented limitation of Unity's serializer. A top-level dictionary is fully supported — save it as its own key beside the class |
| Cloud SDK providers (UGS, Steam, Firebase, Supabase, PlayFab) | Each needs an account, a plan or a platform SDK, and none could be run here. The folder and REST providers are complete, working examples of the same five-operation contract |
What it cannot protect#
- A save file is on the player's machine. Encryption stops a player from reading it in a text editor and from changing a value in it. It is a strong lock, not a safe: the passphrase lives in your build. Do not put anything in a save that must stay secret from the player.
- A checksum is not authentication. Integrity detects accidental damage. Proving who wrote a file needs the keyed signature, which is a different mechanism, and PersistKit keeps the two apart on purpose.
- A restored older save cannot be detected without a server-side sequence number. That is out of scope, and saying so is more useful than implying otherwise.
Where the platform decides#
OnApplicationQuitis not guaranteed everywhere. A mobile app can be killed; a console can suspend the game. Save at your own moments as well — a checkpoint, a scene change — rather than only on the way out.- A damaged file is never deleted. It is left where it is, because it may hold data the backups do not.
- Two devices writing the same cloud file at the same instant are settled by the service, not by PersistKit. A provider with conditional writes closes that window properly. The folder provider cannot lock a file, and says so in its own documentation rather than pretending.
- No run has been made on Android, iOS, macOS, Linux, WebGL or consoles. The runtime is platform-neutral C# with no native code and no reflection, but no claim is made beyond what was actually run: see Platforms.
What it will not do, even when asked nicely#
- Save nothing quietly. A value it cannot store is refused with a code, not written as nothing.
- Overwrite a save it cannot read. A newer file is refused and left alone.
- Guess during a migration. A version with no migration covering it is refused.
- Resolve a cloud conflict on its own. It reports the conflict, with both timestamps and both sizes, and asks.
Next#
- Platforms — what was run, and what was not
- Error codes — the full catalogue
- Support — what a useful report contains