Public API
Persistent Asset v1.0.0 · namespaces
PersistentAsset(.BuiltIns/.NoCode) and the editor mirrors PersistentAsset.Editor(.BuiltIns/.NoCode)Reference for every public type and member in the Built-Ins area. Red text flags the exceptions a member can throw. See the API overview for the other areas.
Built-InsReady-made managers, storage backends, security and helpers.
UnityJsonSerializer
class"Unity JSON", the default serializer: serializes fields by Unity's own rules into readable JSON, and supports save versioning. Its inspector Format option is PrettyPrint, OneLine, or Obfuscated (compact base64 so players cannot casually read or edit it, obfuscation, not encryption).
| enum Format | PrettyPrint, OneLine, Obfuscated. |
PrototypePersistenceManager
PM"Prototype". Zero-config local save, desktop/mobile/WebGL. No settings.
FilePersistenceManager
PM"Local File". Configurable file save.
| string FileName / string HeaderText | File name (and subfolders), and an optional '#' comment line at the top of the file (players can edit or delete it; empty writes none). |
| Compression Compression / Encryption Encryption / SaveLock LockSaveTo | Storage protection. |
| bool DoBackup | Keep a second copy against crashes mid-save. |
| static string RuntimeSecret { get; set; } | Secret supplied at runtime for the RuntimeSecret lock. The setter throws ArgumentException when set to null/empty, and InvalidOperationException when set a second time with a different value. |
| static event Action<Object> OnTamperedLoaded | Raised after a load completed with tampered data now on the target (passed to the handler): the file failed its AppendHash integrity check, or carried the sticky mark of a previous detection. |
| static bool IsTampered(Object target) | Whether the data currently loaded on the target descends from a tampered save. The mark is sticky: it is rewritten into every save of the lineage (slot copies and Slots.SaveTo snapshots included), so it survives sessions; it resets on a clear, or when a load finds pristine data again. Throws ArgumentNullException for a null target. |
| static void MarkTampered(Object target) | Brand the current save lineage as tampered from your own cheat detection: same sticky, authenticated mark as an automatic detection, and the only flag a player cannot edit back out of a readable save. Deliberately no unmark (nothing in the API can launder the mark); OnTamperedLoaded is not raised. Throws ArgumentNullException for a null target, InvalidOperationException when no active file manager is in charge of it or its Encryption is not AppendHash. |
PlayerPrefsPersistenceManager
PM"Player Prefs". Saves through PlayerPrefs; synchronous; good for small data.
SessionPersistenceManager
PM"Session (Memory)". In-memory only; never written to disk; wiped each session. Declares StorageKind.Transient.
TestPersistenceManager
PM"Test". A fake in-memory manager to test how the game behaves when persistence misbehaves: every operation can be forced to any outcome, and async delays can be injected, to exercise timing, cancellation and error handling (ReadExecutionMode/WriteExecutionMode default to PreferAsync). Declares StorageKind.Test: assigning it always keeps an import copy of the setup it replaces, restored in one click from its inspector, and it never ships (a non-development build fails while one exists in the project; a development build logs a warning).
| enum ForcedLoadOutcome | Default (run for real), Success, Invalid, Failure, Exception, Cancelled. |
| enum ForcedOutcome | Default, Success, Failure, Exception, Cancelled (save/clear; no Invalid). |
PersistentSlotRegistry<TTarget, TInfo>
SOabstractAlways-global object that records one entry per save slot with a summary you define, without loading the saves. Build a save-select menu on it.
| IReadOnlyList<SlotEntry<TInfo>> Entries { get; } | Every recorded slot, each with its summary, save time and optional screenshot, most recently saved first (the natural order for a load-game menu). A fresh snapshot each call: cache it if you iterate a lot. |
| bool TryGet(string slot, out SlotEntry<TInfo>) / TryGetLatest(...) | Look up one slot, or the most recently saved. |
| string LatestSlot { get; } | Slot of the newest save (for a "Continue" button). |
| TInfo CaptureInfo(TTarget target) (protected abstract) | Return the per-slot summary to record on each save. |
| Awaitable<SaveScreenshot> CaptureScreenshotAsync(TTarget) / SaveScreenshot CaptureScreenshot(TTarget) (protected) | Optional per-slot preview image (override one; async is recommended). See SaveScreenshot. |
| PersistencePolicy Policy { get; } | Forces auto-load on and auto-save off: the registry must mirror the real save state, and it saves itself on every change. |
SlotEntry<TInfo>
structRead-only record of one slot in a PersistentSlotRegistry.
| string Slot { get; } | The slot this entry describes. |
| TInfo Info { get; } | The summary your CaptureInfo returned. |
| DateTime SavedUtc { get; } / long SavedUtcTicks { get; } | When the slot was last saved (UTC). Out-of-range ticks in a tampered or corrupt registry save are clamped into the valid DateTime range rather than throwing. |
| SaveScreenshot Screenshot { get; } | The slot's preview image, empty when none was recorded. |
SaveScreenshot
structA save-slot preview image that serializes as a string, so it rides inside a slot summary. Capture it with the static methods, then decode it on demand for a save-select menu. Its ScreenshotFormat is Jpg (smaller, lossy, no alpha) or Png (lossless).
| static SaveScreenshot Capture(Camera camera, int maxSize = 256, ScreenshotFormat format = Jpg, int jpgQuality = 75) | Capture a camera's view at the wanted size (also a Texture overload). |
| static Awaitable<SaveScreenshot> CaptureAsync(...) | The recommended capture: no main-thread stall on the GPU read back. Camera and Texture overloads. |
| static SaveScreenshot CaptureScreen(int maxSize = 256, ScreenshotFormat format = Jpg, int jpgQuality = 75) / static Awaitable<SaveScreenshot> CaptureScreenAsync(...) | Capture the whole screen, sync or async (async recommended). |
| Texture2D CreateTexture() / Sprite CreateSprite() | Decode into a new texture or sprite the caller owns and must Object.Destroy when done. CreateSprite owns both the sprite and its texture: destroy sprite.texture first, then the sprite. |
| bool HasValue { get; } / int Width { get; } / Height { get; } / float Aspect { get; } | Whether it holds an image, and its size, without decoding. |
ScreenshotFormat
enum| Jpg / Png | Encoding of a SaveScreenshot: JPEG (smaller, lossy, no alpha) or PNG (lossless). |
PersistentSingleton
SOabstractA persistent object that exists once per project, with its asset auto-created and reachable from anywhere via GlobalPersistedData.Find<T>(). Inherit it for a settings or profile singleton.
Encryption
enum| None | No encryption. |
| AppendHash | Readable, with a secured hash: a modified save still loads but is permanently marked as tampered (see FilePersistenceManager.IsTampered). |
| Encrypt | Fully encrypted; a modified save cannot be loaded at all. |
Compression
enum| None / Fast / Optimal | No compression, fast, or best (slower) gzip. |
SaveLock
enum [Flags]| None | Readable by any copy of the project. |
| TargetMachine | Unreadable on another machine. |
| FileLocation | Unreadable if moved, renamed or swapped. |
| RuntimeSecret | Unreadable without the runtime secret. |
| Everything | All locks. |
RemotePersistenceManager
PMabstractextendingBase for remote managers. Implement the async FetchRemote / StoreRemote / DeleteRemote primitives (each reports an Answer); inherit async, cache and push.
| Task<(Answer answer, string body, string message)> FetchRemote(string slot, CancellationToken) (protected abstract) | Read the slot's payload from the server (the body is null unless the answer is Success). |
| Task<(Answer answer, string message)> StoreRemote(string slot, string body, CancellationToken) (protected abstract) | Write the slot's payload to the server. |
| Task<(Answer answer, string message)> DeleteRemote(string slot, CancellationToken) (protected abstract) | Delete the slot's payload on the server. |
| RemoteCacheMode CacheMode { get; protected set; } / OfflineColdStart OfflineColdStart { get; protected set; } (virtual) | Offline-cache behavior; override to opt in (e.g. with [field: SerializeField]). |
| RemoteStatus Status { get; } / StatusChanged | Up-to-date vs pending changes, and its event. |
| Task<RemoteStatus> PushPendingChanges(CancellationToken) | Flush the cache to the server now. |
| enum Answer | Success, NoSave, Corrupt, Error, Unreachable. |
| string SetupError (protected virtual) / string LocalCacheFolder (protected virtual) | Override points: a permanent fault message (null = none); the cache subfolder name (the type name by default). |
| static void ClearLocalCache(string managerName, string folder) | Delete one manager type's offline cache (backs a [ClearLocalData] editor cleaner). |
HttpPersistenceManager
PM"Server (HTTP)". GET/PUT/DELETE at url/slot/id.
| string ReleaseUrl / DevelopmentUrl / Id | Endpoint, dev override, and save id. |
| bool UsePostRequests / Compression Compression | POST fallback; gzip. |
| static string Authorization / static Action<UnityWebRequest> ConfigureRequest | Runtime auth and per-request hook. |
| string GenerateAddress(string slot) (protected) / static Task Send(UnityWebRequest, CancellationToken) (protected) / static string ErrorText(UnityWebRequest) (protected) | Subclassing helpers to adapt the server contract. Send throws OperationCanceledException when the token is cancelled. |
CloudSavePersistenceManager
PM"Cloud Save (UGS)". Per signed-in player. Requires UGS init + sign-in.
| string Key / Compression Compression | Cloud Save key (accepts the <slot> placeholder; only letters, digits, - and _ are valid, any other character is reported as invalid); gzip. |
Remote enums
enum| RemoteCacheMode | None, ServerWithCache, LocalCacheServerBackup. |
| OfflineColdStart | WaitForServer, StartFresh. |
| RemoteStatus | UpToDate, PendingChanges. |
RemoteManagerSettings
classProject-wide settings of the remote managers (Project Settings > Persistent Asset > Remote). Read via Settings.Get<RemoteManagerSettings>().
| float PushRetryDelay { get; } | Seconds between attempts to push pending offline-cache data to the server (clamped to ≥ 5). |
| int RequestTimeout { get; } | Seconds before a single remote request is forced to time out: an absolute ceiling that always applies, capping a request even when a manager's own Load / Save / Clear Timeout is higher or unbounded (whichever bound is reached first ends it). 0 disables it. |
| const float MinimumPushRetryDelay = 5 | Lower bound for PushRetryDelay. |
SaveFileUtility
staticextendingLow-level file IO shared by the file-backed managers and the offline cache. You only need it to build your own file-based manager.
| const string FileExtension = "save" | Extension (no dot) of every save file it reads and writes. |
| string GetRootFolderPath() / EnsureRootFolderExists() | Root folder under which every save location lives (the second creates it). |
| string GetSaveFolderPath(SaveLocation location) / GetSaveFilePath(SaveLocation, string relativeFilePath) | Resolve a location's folder, or a file path within it (GetSaveFilePath appends the .save extension, so pass relativeFilePath without one). Throws ArgumentOutOfRangeException for an undefined location. |
| byte[] Read(SaveLocation, string relativeFilePath) / byte[] ReadHeader(SaveLocation, string, int maxBytes) | Read a save file, or just its first bytes. |
| void Write(SaveLocation, string relativeFilePath, string uniqueId, byte[] data) / WriteAtomic(string path, string tempPath, byte[] data) | Write a save file atomically (stage then swap, crash-safe). |
| void Delete(SaveLocation, string relativeFilePath) | Delete a save file (silent if absent). |
CheatProtectionUtility
staticextendingEncrypt or hash save data with a key derived from the project secret (Project Settings > Persistent Asset > Security). Backs the FilePersistenceManager protection options.
| static string RuntimeSecret { get; set; } | Runtime secret mixed into the key for a SaveLock.RuntimeSecret lock. The setter throws ArgumentException when set to null/empty, and InvalidOperationException when set a second time with a different value. |
| bool UsesRuntimeSecret(SaveLock lockTo) | Whether the lock effectively requires the runtime secret (the editor can opt out). |
| byte[] Encrypt(byte[] data, SaveLock lockTo, string location) / byte[] Decrypt(byte[], SaveLock, string) | Encrypt/decrypt with an embedded integrity hash. Decrypt returns null when the integrity check fails (data modified, moved, or from another machine or project). Throws ArgumentNullException for null data, InvalidOperationException when the lock needs an unset RuntimeSecret. |
| byte[] AppendSecuredHash(byte[], SaveLock, string, bool tampered = false) / bool CheckSecuredHash(byte[] dataWithHash, SaveLock, string, out byte[] originalData, out bool tampered) | Append/verify a tamper-evident hash (data stays readable). tampered writes/reads the tampered-lineage mark, covered by the hash itself so editing it in or out reads as freshly tampered; originalData is extracted even when the check fails, so a caller can carry a tampered payload onward. A CheckSecuredHash overload without the out tampered also exists. Same throws as Encrypt / Decrypt. |
GzipUtility
staticextendingGzip compress and decompress byte data.
| byte[] Compress(byte[] data, Compression compression) / Decompress(byte[] data, Compression compression) | Compress/decompress per a Compression level (None passes through). Throws ArgumentNullException for null data; Decompress throws InvalidDataException on invalid gzip input or past the size ceiling. |
| byte[] Compress(byte[] data, CompressionLevel compressionLevel = Optimal) / Decompress(byte[] data) | Compress/decompress with a raw System.IO.Compression level. Throws ArgumentNullException for null data; Decompress throws InvalidDataException on invalid gzip input or past the size ceiling. |
TaskUtility
staticextendingHelpers for asynchronous manager code: thread hopping and cancellation.
| ThreadType CurrentThreadType { get; } | Whether the caller is on the main or a background thread. |
| Task SwitchToMainThread() | Await to continue on the main thread. |
| Task StartNew(ThreadType, Action, CancellationToken = default, Action<AggregateException> = null) / Task<TResult> StartNew<TResult>(ThreadType, Func<TResult>, ...) | Run work on the chosen thread as a task. |
| Task<T> WithCancellation<T>(Task<T>, CancellationToken) / Task WithCancellation(Task, CancellationToken) | Make any task cancellable even when it ignores the token. Surfaces OperationCanceledException on cancel. |
| void Observe(Task task) | Observe an abandoned task's eventual fault (avoids UnobservedTaskException). |
SlotFormatUtility
staticextendingThe "<slot>" placeholder handling and the reversible file-path slot codec the file-backed managers share.
| const string Placeholder = "<slot>" | The token a manager replaces with the current slot in a user path, key or address. |
| string GenerateName(string customValue, string slot, string defaultName, params char[] separators) | Resolve a storage name: default under the slot, or the custom value with the slot placed/prepended. |
| bool Replace(ref string value, string replacement, params char[] separators) | Replace every placeholder, returning whether any was found. |
| string EncodeForFilePath(string slot) / DecodeForFilePath(string encoded) | Encode a slot into one safe, injective, reversible path segment (and back). |
| bool IsValidFilePath(string value, out string reason) | Whether a relative file path is valid on every platform. |
WebGLFileSync
staticextendingFlush the in-memory file system to IndexedDB on WebGL; call after writing or deleting save files. A no-op off WebGL.
| void RequestSync() | Flush pending file writes to persistent browser storage. |
ThreadType / SaveLocation
enumThreadType
| Main / Background | The main thread (full Unity API) or a background thread (faster, most Unity API unavailable). |
SaveLocation
| Default / Backup / LocalCache | Subfolders of Application.persistentDataPath: the save folder, the backup copy, and the remote managers' offline cache. |