From 6b9250e4ef8173c0eb008e6a7907ec44c61ae578 Mon Sep 17 00:00:00 2001 From: grorp Date: Sat, 13 Jan 2024 20:01:50 +0100 Subject: [PATCH] Document settings API behavior regarding default values (#14247) --- doc/lua_api.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/doc/lua_api.md b/doc/lua_api.md index 06f48aac1..c4e1265c5 100644 --- a/doc/lua_api.md +++ b/doc/lua_api.md @@ -246,15 +246,15 @@ The format is documented in `builtin/settingtypes.txt`. It is parsed by the main menu settings dialogue to list mod-specific settings in the "Mods" category. +`minetest.settings` can be used to read custom or engine settings. +See [`Settings`]. + ### `init.lua` The main Lua script. Running this script should register everything it -wants to register. Subsequent execution depends on minetest calling the +wants to register. Subsequent execution depends on Minetest calling the registered callbacks. -`minetest.settings` can be used to read custom or existing settings at load -time, if necessary. (See [`Settings`]) - ### `textures`, `sounds`, `media`, `models`, `locale` Media files (textures, sounds, whatever) that will be transferred to the @@ -5772,7 +5772,7 @@ Setting-related --------------- * `minetest.settings`: Settings object containing all of the settings from the - main config file (`minetest.conf`). + main config file (`minetest.conf`). See [`Settings`]. * `minetest.setting_get_pos(name)`: Loads a setting from the main settings and parses it as a position (in the format `(1,2,3)`). Returns a position or nil. @@ -8229,37 +8229,47 @@ secure random device cannot be found on the system. An interface to read config files in the format of `minetest.conf`. -It can be created via `Settings(filename)`. +`minetest.settings` is a `Settings` instance that can be used to access the +main config file (`minetest.conf`). Instances for other config files can be +created via `Settings(filename)`. + +Engine settings on the `minetest.settings` object have internal defaults that +will be returned if a setting is unset. +The engine does *not* (yet) read `settingtypes.txt` for this purpose. This +means that no defaults will be returned for mod settings. ### Methods * `get(key)`: returns a value + * Returns `nil` if `key` is not found. * `get_bool(key, [default])`: returns a boolean * `default` is the value returned if `key` is not found. * Returns `nil` if `key` is not found and `default` not specified. * `get_np_group(key)`: returns a NoiseParams table + * Returns `nil` if `key` is not found. * `get_flags(key)`: * Returns `{flag = true/false, ...}` according to the set flags. * Is currently limited to mapgen flags `mg_flags` and mapgen-specific flags like `mgv5_spflags`. + * Returns `nil` if `key` is not found. * `set(key, value)` * Setting names can't contain whitespace or any of `="{}#`. * Setting values can't contain the sequence `\n"""`. * Setting names starting with "secure." can't be set on the main settings object (`minetest.settings`). * `set_bool(key, value)` - * See documentation for set() above. + * See documentation for `set()` above. * `set_np_group(key, value)` * `value` is a NoiseParams table. - * Also, see documentation for set() above. + * Also, see documentation for `set()` above. * `remove(key)`: returns a boolean (`true` for success) * `get_names()`: returns `{key1,...}` * `has(key)`: * Returns a boolean indicating whether `key` exists. - * Note that for the main settings object (`minetest.settings`), `get(key)` - might return a value even if `has(key)` returns `false`. That's because - `get` can fall back to the so-called parent of the `Settings` object, i.e. - the default values. + * In contrast to the various getter functions, `has()` doesn't consider + any default values. + * This means that on the main settings object (`minetest.settings`), + `get(key)` might return a value even if `has(key)` returns `false`. * `write()`: returns a boolean (`true` for success) * Writes changes to file. * `to_table()`: returns `{[key1]=value1,...}`