Document settings API behavior regarding default values (#14247)

This commit is contained in:
grorp 2024-01-13 20:01:50 +01:00 committed by GitHub
parent 5089e8342f
commit 6b9250e4ef
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -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 It is parsed by the main menu settings dialogue to list mod-specific
settings in the "Mods" category. settings in the "Mods" category.
`minetest.settings` can be used to read custom or engine settings.
See [`Settings`].
### `init.lua` ### `init.lua`
The main Lua script. Running this script should register everything it 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. 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` ### `textures`, `sounds`, `media`, `models`, `locale`
Media files (textures, sounds, whatever) that will be transferred to the 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 * `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 * `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. 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`. 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 ### Methods
* `get(key)`: returns a value * `get(key)`: returns a value
* Returns `nil` if `key` is not found.
* `get_bool(key, [default])`: returns a boolean * `get_bool(key, [default])`: returns a boolean
* `default` is the value returned if `key` is not found. * `default` is the value returned if `key` is not found.
* Returns `nil` if `key` is not found and `default` not specified. * Returns `nil` if `key` is not found and `default` not specified.
* `get_np_group(key)`: returns a NoiseParams table * `get_np_group(key)`: returns a NoiseParams table
* Returns `nil` if `key` is not found.
* `get_flags(key)`: * `get_flags(key)`:
* Returns `{flag = true/false, ...}` according to the set flags. * Returns `{flag = true/false, ...}` according to the set flags.
* Is currently limited to mapgen flags `mg_flags` and mapgen-specific * Is currently limited to mapgen flags `mg_flags` and mapgen-specific
flags like `mgv5_spflags`. flags like `mgv5_spflags`.
* Returns `nil` if `key` is not found.
* `set(key, value)` * `set(key, value)`
* Setting names can't contain whitespace or any of `="{}#`. * Setting names can't contain whitespace or any of `="{}#`.
* Setting values can't contain the sequence `\n"""`. * Setting values can't contain the sequence `\n"""`.
* Setting names starting with "secure." can't be set on the main settings * Setting names starting with "secure." can't be set on the main settings
object (`minetest.settings`). object (`minetest.settings`).
* `set_bool(key, value)` * `set_bool(key, value)`
* See documentation for set() above. * See documentation for `set()` above.
* `set_np_group(key, value)` * `set_np_group(key, value)`
* `value` is a NoiseParams table. * `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) * `remove(key)`: returns a boolean (`true` for success)
* `get_names()`: returns `{key1,...}` * `get_names()`: returns `{key1,...}`
* `has(key)`: * `has(key)`:
* Returns a boolean indicating whether `key` exists. * Returns a boolean indicating whether `key` exists.
* Note that for the main settings object (`minetest.settings`), `get(key)` * In contrast to the various getter functions, `has()` doesn't consider
might return a value even if `has(key)` returns `false`. That's because any default values.
`get` can fall back to the so-called parent of the `Settings` object, i.e. * This means that on the main settings object (`minetest.settings`),
the default values. `get(key)` might return a value even if `has(key)` returns `false`.
* `write()`: returns a boolean (`true` for success) * `write()`: returns a boolean (`true` for success)
* Writes changes to file. * Writes changes to file.
* `to_table()`: returns `{[key1]=value1,...}` * `to_table()`: returns `{[key1]=value1,...}`