Skip to content

Class SettingsStore

Namespace: Apogee.Host
Assembly: Apogee.Host.dll

The player's settings, as the settings global: typed values under dotted keys (audio.volume, mod.coolmod.show_hints) that the engine and the game define (), kept in user://settings.xml as the ones that differ from their defaults. Keys the game does not define (a mod that is switched off) are kept as they are. The store belongs to the main thread.

public sealed class SettingsStore : EngineObject

Inheritance

object ← EngineObject ← SettingsStore

Inherited Members

EngineObject.IsAdopted, EngineObject.Handle, EngineObject.IsDestroyed, EngineObject.Class, EngineObject.Adopt(), EngineObject.TryGet(SlotHandle, out EngineObject), EngineObject.Destroy(), object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()

Constructors

SettingsStore()

A store in memory that is never written: for a script run on its own, and for tests.

public SettingsStore()

Fields

DefaultPath

Where the settings of a game are.

public const string DefaultPath = "user://settings.xml"

Field Value

string

Properties

Bindings

The input map whose rebindings are kept: the bindings in the file are applied to it when it is set (those of actions it does not have yet wait until they are added), and every rebinding marks the settings to be saved.

public InputActionMap? Bindings { set; }

Property Value

InputActionMap?

Changed

A setting changed, with its key. It is raised at once, after the store holds the new value, and only when the value is really different.

public Signal<string> Changed { get; }

Property Value

Signal<string>

Class

What the registry knows about this object's class.

public override ClassInfo Class { get; }

Property Value

ClassInfo

Clock

The clock that the debounce of counts on; tests set a fake one.

public TimeProvider Clock { get; set; }

Property Value

TimeProvider

IsDirty

True when there are changes that are not in the file yet.

public bool IsDirty { get; }

Property Value

bool

NeedsRestart

True when a setting that takes effect at the next start () holds another value than this run started with.

public bool NeedsRestart { get; }

Property Value

bool

Methods

Define(SettingDef)

Defines a setting. A value the file has for the key is read now; one that does not read as the type is logged and the default is used. Defining a key again with the same type and owner (a script that reloaded) replaces its definition and keeps its value.

public void Define(SettingDef definition)

Parameters

definition SettingDef

Exceptions

ValueException

The definition is wrong, or the key is defined as another type or by another owner.

Define(string, ScriptTable)

Defines a setting from a script. spec is { type = "bool" | "int" | "number" | "string" | "choice", default = …, min = …, max = …, choices = { … }, restart = …, help = "…" }. The script that defines it owns it; a mod can define only mod.<its id>.… keys and audio buses (audio.bus.<name>, a number).

public void Define(string key, ScriptTable spec)

Parameters

key string

Two or more words of a-z, 0-9 and _ joined by dots.

spec ScriptTable

The type and default, and what else it needs.

Definition(string)

The definition of a key, or null when it is not defined.

public SettingDef? Definition(string key)

Parameters

key string

Returns

SettingDef?

Flush()

Saves what is not saved yet, whatever the debounce says: at the end of the session.

public void Flush()

Get(string)

The value of a setting.

public Value Get(string key)

Parameters

key string

A defined key.

Returns

Value

Exceptions

ValueException

There is no such setting.

GetBool(string)

A boolean setting's value.

public bool GetBool(string key)

Parameters

key string

Returns

bool

GetInt(string)

An integer setting's value.

public int GetInt(string key)

Parameters

key string

Returns

int

GetNumber(string)

A number setting's value.

public double GetNumber(string key)

Parameters

key string

Returns

double

GetString(string)

A string or choice setting's value.

public string GetString(string key)

Parameters

key string

Returns

string

Info(string)

What a setting is: { type, default, min, max, choices, restart, help } (the fields that do not apply are left out), or nil when the key is not defined. What an options menu builds its controls from.

public ScriptTable? Info(string key)

Parameters

key string

A key.

Returns

ScriptTable?

Keys(string?)

The defined keys that start with prefix (all when it is nil), sorted.

public string[] Keys(string? prefix = null)

Parameters

prefix string?

The start of the keys, or nil.

Returns

string[]

OnDestroyed()

protected override void OnDestroyed()

Open(VirtualFileSystem, string)

The settings in path, or the defaults when there is no such file. A file that cannot be read is logged and set aside as settings.bad.xml beside it; the defaults are used and the next save replaces it.

public static SettingsStore Open(VirtualFileSystem files, string path = "user://settings.xml")

Parameters

files VirtualFileSystem

The game's files; path must be in a writable source (user://).

path string

The file.

Returns

SettingsStore

Reset(string)

Puts a setting back to its default.

public void Reset(string key)

Parameters

key string

A defined key.

ResetAll(string?)

Puts the settings whose key starts with prefix back to their defaults (all of them when it is nil). A mod gives the prefix of its own settings (mod.<its id>.).

public void ResetAll(string? prefix = null)

Parameters

prefix string?

The start of the keys, or nil for all.

Save()

Writes the settings to the file now, as the values that differ from their defaults. The file is written beside itself and moved over the old one, so a crash leaves one of the two whole. A store made with new() has no file. Returns false (and logs once) when it cannot be written; the changes stay to be saved.

public bool Save()

Returns

bool

SaveIfDirty(TimeSpan)

Saves when there are changes and the last attempt to save was at least minimumInterval ago: called every frame, it writes a slider that is being dragged once in that time, and the last change soon after it.

public void SaveIfDirty(TimeSpan minimumInterval)

Parameters

minimumInterval TimeSpan

The time between two writes.

Set(string, Value)

Changes a setting. A number outside its range is clamped. is raised when the value really is different. A mod can change only its own settings (mod.<its id>.…) and the audio buses it defined.

public void Set(string key, Value value)

Parameters

key string

A defined key.

value Value

A value of the setting's type.

Exceptions

ValueException

There is no such setting, the value is of another type or not one of the choices, or a mod changes a setting that is not its own.

TryGet(string, out Value)

The value of a setting, or false when the key is not defined.

public bool TryGet(string key, out Value value)

Parameters

key string

value Value

Returns

bool

KeyDefined

Raised when a key is defined (also when it is defined again), with the key: what hooks a setting up to the thing it controls.

public event Action<string>? KeyDefined

Event Type

Action<string>?