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 (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¶
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¶
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¶
Class¶
What the registry knows about this object's class.
public override ClassInfo Class { get; }
Property Value¶
Clock¶
The clock that the debounce of
public TimeProvider Clock { get; set; }
Property Value¶
IsDirty¶
True when there are changes that are not in the file yet.
public bool IsDirty { get; }
Property Value¶
NeedsRestart¶
True when a setting that takes effect at the next start (
public bool NeedsRestart { get; }
Property Value¶
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¶
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¶
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¶
Exceptions¶
There is no such setting.
GetBool(string)¶
A boolean setting's value.
public bool GetBool(string key)
Parameters¶
key string
Returns¶
GetInt(string)¶
An integer setting's value.
public int GetInt(string key)
Parameters¶
key string
Returns¶
GetNumber(string)¶
A number setting's value.
public double GetNumber(string key)
Parameters¶
key string
Returns¶
GetString(string)¶
A string or choice setting's value.
public string GetString(string key)
Parameters¶
key string
Returns¶
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¶
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¶
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¶
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. 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¶
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¶
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