Settings¶
Extends EngineObject.
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 (SettingDef), 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.
Create one with Settings.new().
Properties¶
needs_restart: booleanTrue when a setting that takes effect at the next start (SettingDef.Restart) holds another value than this run started with. Read-only.
Signals¶
changed: Signal<string>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.
Methods¶
define¶
function define(self, key: string, spec: { [any]: any }): ()
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.
get¶
function get(self, key: string): any
The value of a setting.
set¶
function set(self, key: string, value: any): ()
Changes a setting. A number outside its range is clamped. Changed is raised when the value really is different. A mod can change only its own settings (mod.
reset¶
function reset(self, key: string): ()
Puts a setting back to its default.
reset_all¶
function reset_all(self, prefix: 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.
keys¶
function keys(self, prefix: string?): { string }
The defined keys that start with prefix (all when it is nil), sorted.
info¶
function info(self, key: string): { [any]: any }?
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.
save¶
function save(self): boolean
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.