FAQ

Does this package save my game for me?#

No. It stores what you give it and returns it intact; what your data means stays yours. You implement one method (ISaveStateSource.SaveToAsync), or assign objects in the Inspector, and the framework owns when, where and how safely the write happens.

Which cloud services are supported?#

None out of the box, deliberately. ICloudTransport is a four-method seam over opaque bytes: you implement it for your service, and the framework supplies keys, metadata, precondition discipline, conflict policies, retry with backoff and an offline queue. No vendor SDK, account or credential is in the package — which is what stops it locking you to one. See Adapter roadmap.

Is my save protected from cheating?#

Partly, and the difference matters. Integrity detects accidental damage. Authentication detects edits by someone without the key. Encryption keeps the contents private. None of that is authority: a determined player with the file and the key in memory can still change it. For ranked or competitive data, validate on your server. See Security best practices.

Where are the files?#

Application.persistentDataPath/<RootFolderName>/<product namespace>/<environment>/slots/<slot>/. The environment segment is what stops a development build writing to production data. NexusForge → Persistence → Open Save Folder takes you there.

Why do I have to reference the assemblies explicitly?#

The assemblies set autoReferenced: false on purpose, so a project opts into a save system visibly rather than inheriting one. It also keeps Assembly-CSharp compiling quickly in projects that only use the Editor tooling.

How many saves can I keep?#

Slots are directories: as many as your disk allows. BackupRetentionCount controls how many previous versions of each slot survive a write, and CheckpointOptions.MaxCount how many rotating checkpoints are kept.

Can two scenes or two players write at once?#

Within one process, writes are coordinated so only one happens at a time. Across two processes on one save root, the later writer wins: atomic promotion keeps either version intact, but nothing coordinates the two processes. Use separate roots, or a cloud conflict policy. This is stated in Limitations rather than discovered.

What happens if a save is corrupted?#

The integrity value is checked before anything is parsed, and recovery quarantines the damaged file and restores the newest valid backup. The framework never deletes data it cannot explain: a damaged file is moved aside with a reason, not removed.

Does it work on WebGL, mobile or consoles?#

Not verified See Platform support. WebGL additionally needs an ISaveStorage adapter, because browser storage is not a file system with atomic renames. The Editor's Platform page shows exactly what was run, where, and what to do about the rest.

Will it work under IL2CPP?#

Yes on Windows x64 with Unity's default stripping: the pipeline was run inside a built player and passed 12/12 checks. Higher stripping levels are Not verified; the risk is types reached only through reflection, and a link.xml is the remedy.

Can I move manual saves off the main thread?#

Partly, and only where it is safe. The projection — reading your model — must stay on the caller's thread, because reading a game's objects off their own thread is a data race. Everything after it is pure byte-level work, and Storage.OffloadWritesToThreadPool moves it. Measure before enabling: see Performance.

Why is autosave off by default?#

Because a framework that writes to a player's disk without being asked is not one you can trust. One line switches it on, and the setup presets already do.

Are migrations configuration?#

No — they are code, registered at startup, because each one is a data transformation that should be reviewed and tested. What is configuration is declaring which schema versions your builds can load, so the Editor can warn you about a gap in the chain.

Does the package phone home?#

Never. There is no endpoint, no telemetry and no account. Cloud synchronisation is off until you enable it and supply a transport.

Can I use it in a server or a headless test process?#

Yes. NexusForge.Persistence.Core has noEngineReferences: true and is tested on its own; the Unity adapters are a separate assembly you simply do not reference.

How do I report a bug or a security issue?#

See Support. Run Validate Everything first — its output is what a maintainer needs, and it is safe to paste.

Next#

• Troubleshooting — symptoms with causes and fixes.
• Limitations — the boundaries, in full.
• What's new — release history and compatibility promises.