SaveData

namespace Griff.Runtime;

public sealed class SaveData

Small values that outlive the game: high scores, unlocked levels, settings. Every change is written to disk at once, off the game’s thread so a frame never waits for the disk, and changes made while one is being written go together in the next, so a value set every frame costs a write only as often as the disk keeps up. Stopping the game waits for the last write (Flush). A write that fails (a full disk, a file another program holds) is said once among the game’s problems (Problems) rather than stopping the game, and the next change tries again. A value whose name starts “run.” lasts only while the game runs (see LastsOneRun), and one whose name starts “settings.” is the player’s setting, which a New Game keeps (see IsSetting).

Properties

FilePath

public string? FilePath { get; }

Where values are written, or null when they’re only kept in memory.

Keys

public IEnumerable<string> Keys { get; }

The names of every saved value.

Version

public long Version { get; }

Changes whenever a value is set, deleted or cleared: cheap to poll for changes.

Methods

Clear

public void Clear()

Forgets every value, the player’s settings and controls too (ClearProgress keeps those).

ClearProgress

public void ClearProgress()

Forgets the game’s progress, for a “New Game” button: every value but the player’s settings (IsSetting): those Griff keeps under names starting “griff.” (volumes, fullscreen, rebound keys, network name, saved games and lines read) and the game’s own under names starting “settings.”.

Delete

public bool Delete(string key)

Returns false if there was no value called key.

EditorPath

public static string EditorPath(string projectRoot)

Where the editor keeps a project’s save file while playing: inside its (git-ignored) .griff folder.

Flush

public void Flush()

Waits until every change so far is written (or has failed to be): the game does when it stops, and a host or tool that reads the file straight after (or makes another SaveData of it) does first.

GetBool

public bool GetBool(string key, bool fallback = false)

GetFloat

public float GetFloat(string key, float fallback = 0f)

GetInt

public int GetInt(string key, int fallback = 0)

GetString

public string? GetString(string key, string? fallback = null)

GetText

public string? GetText(string key)

The text kept under key as it’s kept, without going through its JSON (as GetString does): for big text read often, such as a saved game or the lines a player has read. Null if there’s none.

Has

public bool Has(string key)

IsSetting

public static bool IsSetting(string key)

True for the player’s setting, which a New Game keeps (ClearProgress): one Griff keeps for the player, named “griff.” something, or the game’s own named “settings.” something (capitals don’t matter), such as a Toggle’s Save As “settings.fire.Rain” or a Slider’s “settings.difficulty”.

LastsOneRun

public static bool LastsOneRun(string key)

True for a value that lasts one run of the game: one whose name starts “run.” (capitals don’t matter), such as the flag “run.Contracts”. While the game runs it’s kept like any other (a saved game keeps it, and a New Game forgets it), but it isn’t written down, so the next time the game starts it isn’t there: an unlock that doesn’t carry over.

PlayerPath

public static string PlayerPath(string gameName)

Where an exported game called gameName keeps its save file on this computer.

Set

public void Set(string key, int value)

Set

public void Set(string key, float value)

Set

public void Set(string key, bool value)

Set

public void Set(string key, string? value)