Skip to content

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: boolean True 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..… keys and audio buses (audio.bus., a number).

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..…) and the audio buses it defined.

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.