KernelAPI reference
Class SaveStore
Namespace: MicroEngine.Core
Assembly: MicroEngine.Saves.dll
Guide: Saving data
Small JSON persistence for settings and progress. Without a directory or a storage of its own, a store keeps its slots
in the platform’s default medium (DefaultStorage): files under the user’s data folder
(DefaultDirectory), and the page’s localStorage in browsers. A composition can hand a game another medium
(HostBuilder.Storage); tests pass a temporary directory.
Corrupt or missing data yields null instead of crashing the game; corrupt data is set aside
(“<slot>.corrupt.json” for files) so the next save cannot destroy it. A slot that exists but could not be
read (locked file, blocked browser storage) is never written by this store, because the game is then
running with fresh progress that would replace the real one. Failed writes return false instead of
throwing, so a full disk or browser storage quota leaves the game running with its progress in memory.
public sealed class SaveStoreInheritance
Examples
public sealed class Progress { public int Level { get; set; } = 1; }
var store = new SaveStore("com.example.mygame");var progress = store.Load<Progress>("progress") ?? new Progress();progress.Level++;store.Save("progress", progress);Remarks
A slot is a name such as “settings” or “progress”; with file storage it becomes <slot>.json in
Directory. Values are serialized with JsonSerializer (public properties).
Constructors
SaveStore(string, string?)
Creates a store for a game.
public SaveStore(string gameId, string? directory = null)Parameters
gameId string
The game’s id, which names its save folder; must not be empty.
directory string?
The folder for the slot files; null uses the platform’s default medium (DefaultStorage).
Exceptions
gameId is null, empty or white space.
SaveStore(ISaveStorage)
Creates a store over a custom storage medium.
public SaveStore(ISaveStorage storage)Parameters
storage ISaveStorage
Exceptions
storage is null.
SaveStore(IStorage)
Creates a store over any storage of the platform contract (IStorage).
public SaveStore(IStorage storage)Parameters
storage IStorage
Exceptions
storage is null.
Properties
Directory
The save folder for file storage; otherwise a description of where saves live.
public string Directory { get; }Property Value
Methods
DefaultDirectory(string)
The save folder used when no directory is given (outside browsers):
%LOCALAPPDATA%\MicroEngine<gameId> on Windows, /Library/Application Support/MicroEngine/<gameId>files/MicroEngine/<gameId>)
on Android, and $XDG_DATA_HOME/MicroEngine/<gameId> (by default /.local/share) on Linux and
other Unix systems. Always absolute, also when the folder does not exist yet: the first save creates it.
public static string DefaultDirectory(string gameId)Parameters
gameId string
Returns
DefaultStorage(string)
The platform’s default save medium for a game: the page’s localStorage in browsers
(BrowserStorage, keys microengine/<gameId>/<slot>), files in
DefaultDirectory everywhere else. A rule of the platform, not a setting: a host that wants another
medium composes it (HostBuilder.Storage) and the game passes it to
#ctor.
public static IStorage DefaultStorage(string gameId)Parameters
gameId string
Returns
Exceptions
gameId is null, empty or white space.
Delete(string)
Removes the slot’s data; does nothing when it does not exist. A slot that could not be read can be saved again after it is deleted: deleting is the game’s explicit choice to start over.
public void Delete(string slot)Parameters
slot string
Exists(string)
Whether the slot has saved data.
public bool Exists(string slot)Parameters
slot string
Returns
Load<T>(string)
Reads and deserializes a slot.
public T? Load<T>(string slot) where T : classParameters
slot string
The slot name.
Returns
T?
The saved value, or null when the slot does not exist, holds invalid JSON (the data is set aside) or could not be read (the slot is then protected from Save``1 for the life of this store).
Type Parameters
T
The saved type.
Save<T>(string, T)
Writes the whole slot at once, so a crash never leaves a half-written save. Returns false when the medium refused the write, or when the slot could not be read earlier (see the class remarks).
public bool Save<T>(string slot, T data)Parameters
slot string
data T
Returns
Type Parameters
T