Update to Minetest 5.8.0 Lua API

README.md

@@ -1,4 +1,4 @@
-# Minetest 5.7 LSP API
+# Minetest 5.8 LSP API
 
 These API-headers are made for [lua-language-server].
 

api/classes/invref.lua

@@ -48,9 +48,9 @@ function InvRef:get_stack(listname, index) end
 ---@param stack mt.Item
 function InvRef:set_stack(listname, index, stack) end
 
----Return full list (list of `ItemStack`s).
+---Return full list (list of `ItemStack`s) or `nil` if list doesn't exist (size 0).
 ---@param listname string
----@return mt.ItemStack[]
+---@return mt.ItemStack[]?
 function InvRef:get_list(listname) end
 
 ---Set full list (size will not change).

api/classes/metaref.lua

@@ -30,6 +30,8 @@ function MetaDataRef:set_string(key, value) end
 ---@return string
 function MetaDataRef:get_string(key) end
 
+--- The range for the value is system-dependent (usually 32 bits).
+--- The value will be converted into a string when stored
 ---@param key string
 ---@param value integer
 function MetaDataRef:set_int(key, value) end
@@ -39,6 +41,8 @@ function MetaDataRef:set_int(key, value) end
 ---@return integer
 function MetaDataRef:get_int(key) end
 
+--- The range for the value is system-dependent (usually 32 bits).
+--- The value will be converted into a string when stored.
 ---@param key string
 ---@param value number
 function MetaDataRef:set_float(key, value) end
@@ -48,14 +52,16 @@ function MetaDataRef:set_float(key, value) end
 ---@return number
 function MetaDataRef:get_float(key) end
 
----Returns `nil` or a table with keys: `fields`: key-value storage.
+---Returns a metadata table or `nil` on failure.
 ---@return {fields: {[string]: any}}?
 function MetaDataRef:to_table() end
 
----Any non-table value will clear the metadata.
----
---- * Returns `true` on success.
---- * `fields`: key-value storage
+---* Imports metadata from a metadata table
+---* If `data` is a metadata table (see below), the metadata it represents
+--- will replace all metadata of this MetaDataRef object
+---* Any non-table value for `data` will clear all metadata
+---* Item table values the `inventory` field may also be itemstrings
+---* Returns `true` on success
 ---@param table {fields: {[string]: any}}?
 ---@return boolean
 function MetaDataRef:from_table(table) end
@@ -155,6 +161,11 @@ Some of the values in the key-value store are handled specially:
   in [`ItemStack`]
 - `short_description`: Set the item stack's short description. See also:
   `get_short_description` in [`ItemStack`]
+- `inventory_image`: Override inventory_image
+- `inventory_overlay`: Override inventory_overlay
+- `wield_image`: Override wield_image
+- `wield_overlay`: Override wield_overlay
+- `wield_scale`: Override wield_scale, use vector.to_string
 - `color`: A `ColorString`, which sets the stack's color.
 - `palette_index`: If the item has a palette, this is used to get the current
   color from the palette.

api/classes/settings.lua

@@ -64,6 +64,14 @@ function SettingsClass:remove(key) end
 ---@return string[]
 function SettingsClass:get_names() end
 
+--- * 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.
+---@param key string
+---@return boolean # Is `key` exists.
+function SettingsClass:has(key) end
+
 -- Writes changes to file.
 --
 -- Returns a boolean (`true` for success).

api/classes/sounds.lua

@@ -38,8 +38,23 @@
 ---
 ---@class mt.SimpleSoundSpecTable
 ---@field name string|mt.SpecialSoundFile
----@field gain number
----@field pitch number
+--- * Volume (`1.0` = 100%), must be non-negative.
+--- * At the end, OpenAL clamps sound gain to a maximum of `1.0`. By setting gain for
+--- a positional sound higher than `1.0`, one can increase the radius inside which
+--- maximal gain is reached.
+--- * Furthermore, gain of positional sounds doesn't increase inside a 1 node radius.
+--- * The gain given here describes the gain at a distance of 3 nodes.
+--- * Default: `1.0`
+---@field gain? number
+--- * Applies a pitch-shift to the sound.
+--- * Each factor of `2.0` results in a pitch-shift of +12 semitones.
+--- * Must be positive.
+--- * Default: `1.0`
+---@field pitch? number
+--- If > `0.0`, the sound is faded in, with this value in gain per second, until
+--- `gain` is reached.
+--- * Default: `0.0`
+---@field fade? number
 local sound_spec = {}
 
 ---@alias mt.SimpleSoundSpec mt.SimpleSoundSpecTable|string|mt.SpecialSoundFile
@@ -53,13 +68,26 @@ local sound_spec = {}
 ---`exclude_player = name` can be applied to locationless, positional and object-
 ---bound sounds to exclude a single player from hearing them.
 ---@class mt.SoundParameters
----@field gain number Default: `1.0`.
----@field pitch number Default: `1.0`.
----@field fade number Default: `0.0`. Change to a value > 0 to fade the sound in.
----@field to_player string Name.
----@field exclude_player string Name.
----@field loop boolean
----@field pos mt.Vector
----@field max_hear_distance number Default: `32`.
----@field object mt.ObjectRef
+---@field gain? number Scales the gain specified in `SimpleSoundSpec`. Default: `1.0`.
+---@field pitch? number Overwrites the pitch specified in `SimpleSoundSpec`. Default: `1.0`.
+---@field fade? number Overwrites the fade specified in `SimpleSoundSpec`. Default: `0.0`. Change to a value > 0 to fade the sound in.
+--
+-- * Start with a time-offset into the sound.
+-- * The behavior is as if the sound was already playing for this many seconds.
+-- * Negative values are relative to the sound's length, so the sound reaches
+-- its end in `-start_time` seconds.
+-- * It is unspecified what happens if `loop` is false and `start_time` is
+-- smaller than minus the sound's length.
+-- * Available since feature `sound_params_start_time`.
+-- * Default: `1.0`.
+---@field start_time? string
+---@field loop? boolean Default: `false`.
+---@field pos? mt.Vector Play sound at a position. <br> Can't be used together with `object`.
+---@field object? mt.ObjectRef Attach the sound to an object. <br> Can't be used together with `pos`.
+---@field to_player? string A player name. Only play for this player. <br> Can't be used together with `exclude_player`.
+---@field exclude_player? string A player name. Don't play sound for this player. <br> Can't be used together with `to_player`.
+--- * Only play for players that are at most this far away when the sound starts playing.
+--- * Needs `pos` or `object` to be set.
+--- * Default: `32`.
+---@field max_hear_distance? number
 local sound_parameters = {}

api/classes/vector.lua

@@ -236,6 +236,15 @@ function vector.offset(v, x, y, z) end
 ---@nodiscard
 function vector.check(v) end
 
+--- * Returns a boolean value indicating if `pos` is inside area formed by `min` and `max`.
+--- * `min` and `max` are inclusive.
+--- * If `min` is bigger than `max` on some axis, function always returns false.
+--- * You can use `vector.sort` if you have two vectors and don't know which are the minimum and the maximum.
+---@param pos mt.Vector
+---@param min mt.Vector
+---@param max mt.Vector
+function vector.in_area(pos, min, max) end
+
 ---If `x` is a vector: Returns the sum of `v` and `x`.
 ---
 ---If `x` is a number: Adds `x` to each component of `v`.

api/definitions/decor.lua

@@ -51,10 +51,15 @@
 -- Upper limits for decoration.
 -- These parameters refer to the Y co-ordinate of the `place_on` node.
 ---@field y_max number
--- Node (or list of nodes) that the decoration only spawns next to.
--- Checks the 8 neighbor nodes on the same Y, and also the ones
--- at Y+1, excluding both center nodes.
+-- * Node (or list of nodes) that the decoration only spawns next to.
+-- * Checks the 8 neighboring nodes on the same height,
+-- and also the ones at the height plus the check_offset, excluding both center nodes.
 ---@field spawn_by string|string[]
+-- * Specifies the offset that spawn_by should also check
+-- * The default value of -1 is useful to e.g check for water next to the base node.
+-- * 0 disables additional checks, valid values: {-1, 0, 1}.
+-- Default: `-1`.
+---@field check_offset number
 -- Number of spawn_by nodes that must be surrounding the decoration
 -- position to occur.
 -- If absent or -1, decorations occur next to any nodes.

api/definitions/lbm.lua

@@ -20,4 +20,7 @@
 -- and not only the first time the block gets activated after the LBM
 -- was introduced.
 ---@field run_at_every_load boolean
----@field action fun(pos:mt.Vector, node:mt.Node)
+-- Function triggered for each qualifying node.
+-- `dtime_s` is the in-game time (in seconds) elapsed since the block
+-- was last active
+---@field action fun(pos:mt.Vector, node:mt.Node, dtime_s: number)

api/definitions/node.lua

@@ -49,8 +49,11 @@
 -- * Tiles can override this behavior.
 -- * Only when `paramtype2` supports palettes.
 ---@field palette string|nil
--- Screen tint if player is inside node.
+-- Screen tint if a player is inside this node, see `ColorSpec`.
+-- Color is alpha-blended over the screen.
 ---@field post_effect_color mt.ColorSpec|nil
+-- Determines whether `post_effect_color` is affected by lighting.
+---@field post_effect_color_shaded boolean|nil
 ---@field paramtype mt.ParamType|nil
 ---@field paramtype2 mt.ParamType2|nil
 -- Force value for param2 when player places node.
@@ -205,33 +208,33 @@ function node.after_destruct(pos, oldnode) end
 ---@param newnode mt.Node
 function node.on_flood(pos, oldnode, newnode) end
 
--- * Called when oldnode is about be converted to an item, but before the
+-- * Called when `oldnode` is about be converted to an item, but before the
 --   node is deleted from the world or the drops are added.
 -- * This is generally the result of either the node being dug or an attached
 --   node becoming detached.
 -- * Default: `nil`.
 ---@param pos mt.Vector
----@param oldnode mt.Node
----@param oldmeta mt.NodeMetaRef Old node before deletion.
+---@param oldnode mt.Node Node table of node before it was deleted.
+---@param oldmeta mt.NodeMetaRef Metadata of node before it was deleted, as a metadata table.
 ---@param drops table<unknown, mt.Item>
 function node.preserve_metadata(pos, oldnode, oldmeta, drops) end
 
 -- * Called after constructing node when node was placed using
 --   `minetest.item_place_node` / `minetest.place_node`.
 -- * If return true no item is taken from itemstack.
 -- * Default: `nil`.
----@param pos mt.Vector
----@param placer mt.ObjectRef|nil
+---@param pos mt.Vector Node position.
+---@param placer mt.ObjectRef|nil 
 ---@param itemstack mt.Item
 ---@param pointed_thing mt.PointedThing
 function node.after_place_node(pos, placer, itemstack, pointed_thing) end
 
--- * Called after destructing node when node was dug using
+-- * Called after destructing the node when node was dug using
 --   `minetest.node_dig` / `minetest.dig_node`.
 -- * Default: `nil`.
 ---@param pos mt.Vector
----@param oldnode mt.Node
----@param oldmetadata table
+---@param oldnode mt.Node Node table of node before it was dug.
+---@param oldmetadata table Metadata of node before it was dug, as a metadata table.
 ---@param digger mt.ObjectRef
 function node.after_dig_node(pos, oldnode, oldmetadata, digger) end
 
@@ -390,6 +393,9 @@ function node.on_metadata_inventory_take(pos, listname, index, stack, player) en
 ---@class mt.NodeSoundsDef
 -- * If walkable, played when object walks on it.
 -- * If node is climbable or a liquid, played when object moves through it.
+-- * Sound is played at the base of the object's collision-box.
+-- * Gain is multiplied by `0.6`.
+-- * For local player, it's played position-less, with normal gain.
 ---@field footstep mt.SimpleSoundSpec
 -- * While digging node.
 -- * If `"__group"`, then the sound will be `default_dig_<groupname>`,

api/definitions/object.lua

@@ -51,6 +51,8 @@
 --   'inventory_image'.
 --   If 'itemname' contains a ColorString or palette index (e.g. from
 --   `minetest.itemstring_with_palette()`), the entity will inherit the color.
+--   Wielditems are scaled a bit. If you want a wielditem to appear
+--   to be as large as a node, use `0.667` in `visual_size`.
 ---@field visual "cube"|"sprite"|"upright_sprite"|"mesh"|"item"|"wielditem"
 -- Multipliers for the visual size. If `z` is not specified, `x` will be used
 -- to scale the entity along both horizontal axes.

api/minetest/environment.lua

@@ -149,7 +149,7 @@ function minetest.set_timeofday(val) end
 ---@return number timeofday between `0` and `1`; `0` for midnight, `0.5` for midday
 function minetest.get_timeofday() end
 
----@return number time the time, in seconds, since the world was created.
+---@return number | nil time the time, in seconds, since the world was created. The time is not available (`nil`) before the first server step.
 function minetest.get_gametime() end
 
 ---@return number days number of days elapsed since world was created.

api/minetest/global.lua

@@ -158,7 +158,8 @@ function minetest.register_on_player_hpchange(func, modifier) end
 ---|"drown"
 ---|"respawn"
 ---@field object mt.ObjectRef|nil
----@field node string|nil node name
+---@field node string|nil Node name (when `type` is `"node"`).
+---@field node_pos mt.Vector|nil Node position (when `type` is `"node"`).
 ---@field from
 ---|"mod"
 ---|"engine"
@@ -338,6 +339,12 @@ minetest.registered_craft_predicts = {}
 ---@alias mt.InvInfo {from_list: string, to_list: string, from_index: integer, to_index: integer, count: integer}|{listname: string, index: integer, stack: mt.Item}
 
 ---Determines how much of a stack may be taken, put or moved to a player inventory.
+---* `minetest.register_on_player_inventory_action(function(player, action, inventory, inventory_info))`
+---* Called after an item take, put or move event from/to/in a player inventory
+---* These inventory actions are recognized:
+---  * move: Item was moved within the player inventory
+---  * put: Item was put into player inventory from another inventory
+---  * take: Item was taken from player inventory and put into another inventory
 ---
 ---`player` (type `ObjectRef`) is the player who modified the inventory `inventory` (type `InvRef`).
 ---

api/minetest/helpers.lua

@@ -38,7 +38,7 @@ function math.factorial(x) end
 
 -- `"a,b":split","` returns `{"a", "b"}`.
 ---@param str string
----@param separator string|nil Default: `","`.
+---@param separator string|nil Cannot be empty. Default: `","`.
 ---@param include_empty boolean|nil Default: `false`.
 ---@param max_splits number|nil If it's negative, splits aren't limited. Default: `-1`.
 ---@param sep_is_pattern boolean|nil Is separator a plain string or a pattern? Default: `false`.

api/minetest/items.lua

@@ -235,8 +235,8 @@ function minetest.item_drop(itemstack, dropper, pos) end
 -- Default `on_eat` callback.
 --
 -- - `replace_with_item` is the itemstring which is added to the inventory. If
---   the player is eating a stack, then replace_with_item goes to a different
---   spot.
+--   the player is eating a stack and `replace_with_item` doesn't fit onto
+--   the eaten stack, then the remainings go to a different spot, or are dropped.
 --
 -- Returns a function wrapper for `minetest.do_item_eat`.
 ---@param hp_change number

api/minetest/jobs.lua

@@ -33,6 +33,7 @@ function minetest.after(time, func, ...) end
 --
 -- Classes:
 --
+-- - `AreaStore`
 -- - `ItemStack`
 -- - `PerlinNoise`
 -- - `PerlinNoiseMap`

api/minetest/misc.lua

@@ -315,9 +315,15 @@ end
 ---
 ---If `transient` is `false` or absent, the forceload will be persistent (saved between server runs).
 ---If `true`, the forceload will be transient (not saved between server runs).
+---
+---`limit` is an optional limit on the number of blocks that can be
+---forceloaded at once. If `limit` is negative, there is no limit. If it is
+---absent, the limit is the value of the setting `"max_forceloaded_blocks"`.
+---If the call would put the number of blocks over the limit, the call fails.
 ---@param pos mt.Vector
 ---@param transient? boolean
-function minetest.forceload_block(pos, transient) end
+---@param limit? number
+function minetest.forceload_block(pos, transient, limit) end
 
 ---Stops forceloading the position `pos`.
 ---

api/minetest/sounds.lua

@@ -5,12 +5,8 @@
 ---@alias mt.SoundHandle unknown
 
 ---@param spec mt.SimpleSoundSpec
----@param parameters table A sound parameter table.
---- `false`
---- Ephemeral sounds will not return a handle and can't be stopped or faded.
---- It is recommend to use this for short sounds that happen in response to
---- player actions (e.g. door closing).
----@param ephemeral boolean|nil
+---@param parameters mt.SoundParameters A sound parameter table.
+---@param ephemeral boolean|nil Ephemeral sounds will not return a handle and can't be stopped or faded. It is recommend to use this for short sounds that happen in response to player actions (e.g. door closing). (default: false)
 ---@return mt.SoundHandle handle
 function minetest.sound_play(spec, parameters, ephemeral) end
 

api/minetest/translations.lua

@@ -121,9 +121,10 @@ On some specific cases, server translation could be useful. For example, filter
 a list on labels and send results to client. A method is supplied to achieve
 that:
 
-`minetest.get_translated_string(lang_code, string)`: Translates `string` using
-translations for `lang_code` language. It gives the same result as if the string
-was translated by the client.
+`minetest.get_translated_string(lang_code, string)`: Resolves translations in
+the given string just like the client would, using the translation files for
+`lang_code`. For this to have any effect, the string needs to contain translation
+markup, e.g. `minetest.get_translated_string("fr", S("Hello"))`.
 
 The `lang_code` to use for a given player can be retrieved from the table
 returned by `minetest.get_player_information(name)`.