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
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,...}`