toast::settings::Settings Class Reference

The engine-wide settings registry. More...

#include <settings.hpp>

Public Member Functions
auto	declareBool (std::string_view key, bool default_value, Meta meta={}) -> Entry *
auto	declareInt (std::string_view key, int64_t default_value, Meta meta={}) -> Entry *
auto	declareFloat (std::string_view key, double default_value, Meta meta={}) -> Entry *
auto	declareString (std::string_view key, std::string default_value, Meta meta={}) -> Entry *
auto	find (std::string_view key) -> Entry *
auto	entries () -> std::vector< Entry * >
	Every declared setting, in declaration order.
auto	value (std::string_view key) -> std::optional< Value >
auto	resolved (const Entry *entry) -> Value
auto	setValue (std::string_view key, const Value &value) -> bool
	Writes value into the active layer and fires the setting's change callbacks.
auto	reset (std::string_view key) -> bool
	Drops key's override in the active layer, exposing whatever is underneath.
void	resetAll ()
	reset() for every declared setting
void	setPaths (std::filesystem::path project_file, std::filesystem::path user_file)
	Points the two writable layers at their files; neither has to exist yet.
void	setActiveLayer (Layer layer)
	Which layer setValue() writes to.
auto	activeLayer () const -> Layer
auto	activeFilePath () const -> const std::filesystem::path &
void	load ()
	Reads both writable layers from disk, replacing whatever they currently hold.
auto	save () -> bool
	Writes the active layer, creating parent directories as needed.
auto	dirty () const -> bool
auto	saveIfDirty () -> bool
	save(), but only when something changed since the last one

Static Public Member Functions
static auto	get () -> Settings &

Detailed Description

The engine-wide settings registry.

Systems declare their own settings next to the code that consumes them and keep the returned handle; nothing central has to know the list. Values arriving from disk before their declaration are held and applied when it happens, so load order does not matter - the renderer declares its settings when it is constructed, long after the files were read

Note

Every accessor is mutex-guarded, because the editor sets values from its UI thread while the engine reads them on the main thread. Systems that need a value per frame should cache it through onChange() rather than calling get() in a loop

Member Function Documentation

activeFilePath()

auto toast::settings::Settings::activeFilePath ( ) const -> const std::filesystem::path &

inlinenodiscard

Returns

the file the active layer writes to

entries()

auto toast::settings::Settings::entries ( ) -> std::vector< Entry * >

nodiscard

Every declared setting, in declaration order.

Stable across further declarations - entries live in a deque, so the editor may hold these across a frame in which another system registers

find()

auto toast::settings::Settings::find ( std::string_view key ) -> Entry *

nodiscard

Returns

the entry for key, or nullptr when nothing declared it

load()

void toast::settings::Settings::load

(

)

Reads both writable layers from disk, replacing whatever they currently hold.

Values whose key has not been declared yet are kept aside rather than dropped, and applied by the declare() that eventually names them

resolved()

auto toast::settings::Settings::resolved ( const Entry * entry ) -> Value

nodiscard

Returns

entry's resolved value; the lookup-free path Setting<T>::value() takes

save()

auto toast::settings::Settings::save

(

)

-> bool

Writes the active layer, creating parent directories as needed.

Only keys that actually differ from the layer below are written, which is what keeps a user file to the handful of things that were changed - and lets a later patch move a default the player never touched

Here is the caller graph for this function:

setActiveLayer()

void toast::settings::Settings::setActiveLayer

(

Layer

layer

)

Which layer setValue() writes to.

The editor sets project, so what it authors ships as the game's defaults. A packaged game leaves it at user, so a player's tweaks land in their own file and survive a patch

setValue()

auto toast::settings::Settings::setValue	(	std::string_view	key,
		const Value &	value ) -> bool

Writes value into the active layer and fires the setting's change callbacks.

A value of the wrong alternative is converted when the conversion is lossless-ish (int to double, bool to int) and rejected otherwise, so a caller cannot silently turn a float setting into a string

value()

auto toast::settings::Settings::value ( std::string_view key ) -> std::optional< Value >

nodiscard

Returns

the resolved value of key, or nullopt when it was never declared

Here is the caller graph for this function:

---

The documentation for this class was generated from the following files:

• engine/src/toast/settings/settings.hpp
• engine/src/toast/settings/settings.cpp