diff --git a/README.md b/README.md
index 3e1f588..5424000 100644
--- a/README.md
+++ b/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].
 
diff --git a/api/classes/invref.lua b/api/classes/invref.lua
index 35bd89b..1f1a9fe 100644
--- a/api/classes/invref.lua
+++ b/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).
diff --git a/api/classes/metaref.lua b/api/classes/metaref.lua
index daecf1f..7c2336d 100644
--- a/api/classes/metaref.lua
+++ b/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.
diff --git a/api/classes/objectref.lua b/api/classes/objectref.lua
index 0121914..f84ec24 100644
--- a/api/classes/objectref.lua
+++ b/api/classes/objectref.lua
@@ -27,6 +27,8 @@ local ObjectRef = {}
 ---@return mt.Vector|nil
 function ObjectRef:get_pos() end
 
+---* Sets the position of the object.
+---* No-op if object is attached.
 ---@param pos mt.Vector
 function ObjectRef:set_pos(pos) end
 
@@ -36,7 +38,7 @@ function ObjectRef:get_velocity() end
 ---* In comparison to using get_velocity, adding the velocity and then using
 ---  set_velocity, add_velocity is supposed to avoid synchronization problems.
 ---  Additionally, players also do not support set_velocity.
----* If a player:
+---* If object is a player:
 ---  * Does not apply during free_move.
 ---  * Note that since the player speed is normalized at each move step,
 ---    increasing e.g. Y velocity beyond what would usually be achieved
@@ -50,27 +52,30 @@ function ObjectRef:add_velocity(vel) end
 ---* If `continuous` is true, the Lua entity will not be moved to the current
 ---      position before starting the interpolated move.
 ---* For players this does the same as `set_pos`,`continuous` is ignored.
+---* No-op if object is attached.
 ---@param pos mt.Vector
 ---@param continuous boolean|nil Default: `false`.
 function ObjectRef:move_to(pos, continuous) end
 
---[[
-If `direction` equals `nil` and `puncher` does not equal `nil`, `direction`
-will be automatically filled in based on the location of `puncher`.
-]]
+
+---* Punches the object, triggering all consequences a normal punch would have.
+---* If `direction` equals `nil` and `puncher` does not equal `nil`, `direction`
+--- will be automatically filled in based on the location of `puncher`.
 ---@param puncher mt.ObjectRef
 ---@param time_from_last_punch number|nil Time since last punch action.
 ---@param tool_capabilities mt.ToolCaps|nil
----@param direction mt.Vector|nil
+---@param dir mt.Vector|nil Direction vector of punch
 ---@return number tool_wear
 function ObjectRef:punch(
   puncher,
   time_from_last_punch,
   tool_capabilities,
-  direction
+  dir
 )
 end
 
+---* Simulates using the 'place/use' key on the object
+---* Triggers all consequences as if a real player had done this
 ---@param clicker mt.ObjectRef
 function ObjectRef:right_click(clicker) end
 
@@ -93,11 +98,10 @@ function ObjectRef:get_inventory() end
 ---@return string|nil
 function ObjectRef:get_wield_list() end
 
----Returns the index of the wielded item.
----@return number|nil
+---@return number|nil # The wield list index of the wielded item (starting with 1).
 function ObjectRef:get_wield_index() end
 
----@return mt.ItemStack|nil
+---@return mt.ItemStack|nil # A copy of the wielded item.
 function ObjectRef:get_wielded_item() end
 
 ---Replaces the wielded item, returns `true` if successful.
@@ -105,17 +109,22 @@ function ObjectRef:get_wielded_item() end
 ---@return boolean true If successful.
 function ObjectRef:set_wielded_item(item) end
 
----@param group_table table {group1=rating, group2=rating, ...}
-function ObjectRef:set_armor_groups(group_table) end
-
----Returns a table with the armor group ratings.
----@return table {group1=rating, group2=rating, ...}|nil
+---Returns a table with all of the object's armor group ratings.
+---@return table|nil `{group1_name = rating, group2_name = rating, ...}` or `nil`.
 function ObjectRef:get_armor_groups() end
 
----@param frame_range { x: number, y: number }|nil `{x=1, y=1}`
----@param frame_speed number|nil Default: `15.0`.
+---* Sets the object's full list of armor groups.
+---* Note: all armor groups not in the table will be removed.
+---@param group_table table `{group1_name = rating, group2_name = rating, ...}`
+function ObjectRef:set_armor_groups(group_table) end
+
+---* Sets the object animation parameters and (re)starts the animation.
+---* Animations only work with a `"mesh"` visual.
+---
+---@param frame_range { x: number, y: number }|nil Default `{x=1, y=1}`. Beginning and end frame (as specified in the mesh file). <br> * Animation interpolates towards the end frame but stops when it is reached. <br> * If looped, there is no interpolation back to the start frame. <br> * If looped, the model should look identical at start and end. <br> * Only integer numbers are supported.
+---@param frame_speed number|nil Default: `15.0`. How fast the animation plays, in frames per second.
 ---@param frame_blend number|nil Default: `0.0`.
----@param frame_loop boolean|nil Default: `true`.
+---@param frame_loop boolean|nil Default: `true`. If `true`, animation will loop. If false, it will play once.
 function ObjectRef:set_animation(
   frame_range,
   frame_speed,
@@ -124,17 +133,22 @@ function ObjectRef:set_animation(
 )
 end
 
----@return { x: number, y: number}|nil range
+---@return { x: number, y: number}|nil frame_range
 ---@return number|nil frame_speed
 ---@return number|nil frame_blend
 ---@return boolean|nil frame_loop
 function ObjectRef:get_animation() end
 
+--- * Sets the frame speed of the object's animation.
+--- * Unlike `set_animation`, this will not restart the animation.
+--- * `frame_speed`: See `set_animation`.
 ---@param frame_speed number|nil Default: `15.0`.
 function ObjectRef:set_animation_frame_speed(frame_speed) end
 
+--- * Attaches object to `parent`.
+--- * See 'Attachments' section for details.
 ---@param parent mt.ObjectRef
----@param bone string|nil Default: `""`. The root bone.
+---@param bone string|nil Default: `""`(the root bone). Bone to attach to.
 ---@param position mt.Vector|nil Default: `{x=0, y=0, z=0}`. Relative position.
 ---@param rotation mt.Vector|nil Default: `{x=0, y=0, z=0}`. Relative rotation in degrees.
 ---@param forced_visible boolean|nil Default: `false`. Should appear in first person?
@@ -149,8 +163,8 @@ end
 
 ---* This command may fail silently (do nothing) when it would result
 ---  in circular attachments.
----* Returns parent, bone, position, rotation, forced_visible,
----  or nil if it isn't attached.
+---* Returns current attachment parameters or nil if it isn't attached.
+---* If attached, returns `parent`, `bone`, `position`, `rotation`, `forced_visible`.
 ---@return mt.ObjectRef|nil parent
 ---@return string|nil bone The root bone.
 ---@return mt.Vector|nil position Relative position.
@@ -161,7 +175,7 @@ function ObjectRef:get_attach() end
 ---Returns a list of ObjectRefs that are attached to the object.
 ---@return mt.ObjectRef[]|nil
 function ObjectRef:get_children() end
-
+--- Detaches object. No-op if object was not attached.
 function ObjectRef:set_detach() end
 
 ---@param bone string|nil Default: `""`. The root bone.
@@ -169,11 +183,15 @@ function ObjectRef:set_detach() end
 ---@param rotation mt.Vector|nil Default: `{x=0, y=0, z=0}`.
 function ObjectRef:set_bone_position(bone, position, rotation) end
 
----Returns position and rotation of the bone.
+--- * Returns `position, rotation` of the specified bone (as vectors).
+--- * note: position is relative to the object.
 ---@param bone string
 ---@return mt.Vector|nil position, mt.Vector|nil rotation
 function ObjectRef:get_bone_position(bone) end
 
+--- * set a number of object properties in the given table
+--- * only properties listed in the table will be changed
+--- * see the [Object properties](https://github.com/minetest/minetest/blob/master/doc/lua_api.md#object-properties) section for details
 ---@param property_table table
 function ObjectRef:set_properties(property_table) end
 
@@ -188,7 +206,8 @@ function ObjectRef:is_player() end
 ---@field color mt.ColorSpec|nil
 ---@field bgcolor mt.ColorSpec|nil
 
----Returns a table with the attributes of the nametag of an object.
+--- * Returns a table with the attributes of the nametag of an object.
+--- * A nametag is a HUD text rendered above the object.
 ---@return mt.NameTagAttributes|nil
 function ObjectRef:get_nametag_attributes() end
 
@@ -242,6 +261,7 @@ function LuaObjectRef:set_texture_mod(mod) end
 function LuaObjectRef:get_texture_mod() end
 
 ---* Specifies and starts a sprite animation.
+---* Only used by `sprite` and `upright_sprite` visuals
 ---* Animations iterate along the frame `y` position.
 ---  * First column:  subject facing the camera
 ---  * Second column: subject looking to the left
@@ -265,7 +285,7 @@ end
 ---@deprecated
 function LuaObjectRef:get_entity_name() end
 
----@return any
+---@return any # The object's associated luaentity table.
 function LuaObjectRef:get_luaentity() end
 
 ---Player only (no-op for other objects).
@@ -346,7 +366,7 @@ function PlayerObjectRef:set_breath(value) end
 
 ---* Sets player's FOV.
 ---* Set `fov` to 0 to clear FOV override.
----@param fov number FOV value
+---@param fov number Field of View (FOV) value.
 ---@param is_multiplier boolean|nil Default: `false`. Set to `true` if the FOV value is a multiplier.
 ---@param transition_time number|nil Default: `0`. If defined, enables smooth FOV transition. Interpreted as the time (in seconds) to reach target FOV. If set to 0, FOV change is instantaneous.
 function PlayerObjectRef:set_fov(fov, is_multiplier, transition_time) end
@@ -419,14 +439,55 @@ function PlayerObjectRef:get_player_control() end
 ---@return number|nil
 function PlayerObjectRef:get_player_control_bits() end
 
+--- * Note: All numeric fields modify a corresponding `movement_*` setting in the game's `minetest.conf`.
+--- * Note: Some of the fields don't exist in old API versions, see feature
+--- `physics_overrides_v2`.
 ---@class mt.PhysicsOverride
----@field speed number|nil Default: `1`. Multiplier to default walking speed value.
+---@field speed number|nil Default: `1`. Multiplier to default movement speed and acceleration values.
 ---@field jump number|nil Default: `1`. Multiplier to default jump value.
 ---@field gravity number|nil Default: `1`. Multiplier to default gravity value.
+--- * Default: `1`.
+--- * Multiplier to default climb speed value.
+--- * Note: The actual climb speed is the product of `speed` and `speed_climb`.
+---@field speed_climb number|nil
+--- * Default: `1`.
+--- * Multiplier to default sneak speed value.
+--- * Note: The actual sneak speed is the product of `speed` and `speed_crouch`.
+---@field speed_crouch number|nil Default: `1`. Whether player can sneak.
+--- * Default: `1`.
+--- * Multiplier to liquid movement resistance value
+--- (for nodes with `liquid_move_physics`); the higher this value, the lower the
+--- resistance to movement. At `math.huge`, the resistance is zero and you can
+--- move through any liquid like air. (default: `1`)
+---   * Warning: Values below 1 are currently unsupported.
+---@field liquid_fluidity number|nil
+--- * Default: `1`.
+--- * Multiplier to default maximum liquid resistance value
+--- (for nodes with `liquid_move_physics`); controls deceleration when entering
+--- node at high speed. At higher values you come to a halt more quickly.
+---@field liquid_fluidity_smooth number|nil
+--- * Default: `1`.
+--- * Multiplier to default liquid sinking speed value;
+--- (for nodes with `liquid_move_physics`).
+---@field liquid_sink number|nil
+--- * Default: `1`.
+--- * Multiplier to horizontal and vertical acceleration
+--- on ground or when climbing.
+---   * Note: The actual acceleration is the product of `speed` and `acceleration_default`.
+---@field acceleration_default number|nil Default: `1`. Whether player can sneak.
+--- * Default: `1`.
+--- Multiplier to acceleration
+--- when jumping or falling.
+---   * Note: The actual acceleration is the product of `speed` and `acceleration_air`
+---@field acceleration_air number|nil Default: `1`. Whether player can sneak.
 ---@field sneak boolean|nil Default: `true`. Whether player can sneak.
 ---@field sneak_glitch boolean|nil Default: `false`. Whether player can use the new move code replications of the old sneak side-effects: sneak ladders and 2 node sneak jump.
 ---@field new_move boolean|nil Default: `true`. Use new move/sneak code. When false the exact old code is used for the specific old sneak behavior.
 
+--- * For games, we recommend for simpler code to first modify the `movement_*`
+--- settings (e.g. via the game's `minetest.conf`) to set a global base value
+--- for all players and only use `set_physics_override` when you need to change
+--- from the base value on a per-player basis.
 --- @param override_table mt.PhysicsOverride
 function PlayerObjectRef:set_physics_override(override_table) end
 
@@ -464,10 +525,13 @@ function PlayerObjectRef:hud_get(id) end
 ---@field breathbar boolean|nil
 ---@field minimap boolean|nil The client may locally elect to not view the minimap.
 ---@field minimap_radar boolean|nil Is only usable when `minimap` is true.
----Allow showing basic debug info that might give a gameplay advantage.
----This includes map seed, player position, look direction, the pointed node
----and block bounds. Does not affect players with the `debug` privilege.
+--- * Allow showing basic debug info that might give a gameplay advantage.
+--- * This includes map seed, player position, look direction, the pointed node
+--- * and block bounds. Does not affect players with the `debug` privilege.
 ---@field basic_debug boolean|nil
+--- * Modifies the client's permission to view chat on the HUD.
+--- * The client may locally elect to not view chat. Does not affect the console.
+---@field chat boolean|nil
 
 ---Sets specified HUD flags of player.
 ---@param flags mt.HUDFlags If a flag equals `nil`, the flag is not modified.
@@ -521,40 +585,65 @@ function PlayerObjectRef:set_minimap_modes(modes, selected_mode) end
 ---@overload fun(base_color: mt.ColorSpec|nil, type:string|nil, textures:table|nil, clouds:boolean|nil) **Deprecated**.
 function PlayerObjectRef:set_sky(sky_parameters) end
 
----A table used in regular sky_parameters type only (alpha is ignored)
----@class mt.SkyColor
----Default: `#61b5f5`. For the top half of the sky during the day.
----@field day_sky mt.ColorSpec|nil
----Default: `#90d3f6`. For the bottom half of the sky during the day.
----@field day_horizon mt.ColorSpec|nil
----Default: `#b4bafa`. For the top half of the sky during dawn/sunset.
----@field dawn_sky mt.ColorSpec|nil
----Default: `#bac1f0`. For the bottom half of the sky during dawn/sunset.
----@field dawn_horizon mt.ColorSpec|nil
----Default: `#006bff`. For the top half of the sky during the night.
----@field night_sky mt.ColorSpec|nil
----Default: `#4090ff`. For the bottom half of the sky during the night.
----@field night_horizon mt.ColorSpec|nil
----Default: `#646464`. For when you're either indoors or underground.
----@field indoors mt.ColorSpec|nil
----Default: `#f47d1d`. Changes the fog tinting for the sun at sunrise and sunset.
----@field fog_sun_tint mt.ColorSpec|nil
----Default: `#7f99cc`. Changes the fog tinting for the moon at sunrise and sunset.
----@field fog_moon_tint mt.ColorSpec|nil
----Default: `"default"`. Changes which mode the directional fog.
----@field fog_tint_type `"custom"`|`"default"`|nil
-
 ---@class mt.SkyParameters
----Changes fog in "skybox" and "plain".
----@field base_color mt.ColorSpec|nil Default: `#ffffff`.
----`"regular"` Uses `0 | 6 | 0` textures, `base_color`
----`ignored | used as fog | used as both fog and sky`.
----@field type `"regular"`|`"skybox"`|`"plain"`|nil
+--- Default: `#ffffff`.
+--- Changes fog in "skybox" and "plain".
+---@field base_color mt.ColorSpec|nil
+--- * Float, rotation angle of sun/moon orbit in degrees.
+--- * By default, orbit is controlled by a client-side setting, and this field is not set.
+--- * After a value is assigned, it can only be changed to another float value.
+--- * Valid range [-60.0,60.0] (default: not set).
+---@field body_orbit_tilt? number
+--- * `"regular"`: Uses 0 textures, `base_color` ignored
+--- * `"skybox"`: Uses 6 textures, `base_color` used as fog.
+--- * `"plain"`: Uses 0 textures, `base_color` used as both fog and sky.
+--- (default: `"regular"`).
+---@field type "regular"|"skybox"|"plain"|nil
 ---A table containing up to six textures in the following order: Y+ (top),
 ---Y- (bottom), X- (west), X+ (east), Z+ (north), Z- (south).
 ---@field textures table|nil
 ---@field clouds boolean|nil `true` Boolean for whether clouds appear.
----@field sky_color mt.SkyColor
+---@field sky_color? mt.SkyColor
+---@field fog? mt.Fog
+
+  ---A table used in regular sky_parameters type only (alpha is ignored)
+  ---@class mt.SkyColor
+  ---Default: `#61b5f5`. For the top half of the sky during the day.
+  ---@field day_sky mt.ColorSpec|nil
+  ---Default: `#90d3f6`. For the bottom half of the sky during the day.
+  ---@field day_horizon mt.ColorSpec|nil
+  ---Default: `#b4bafa`. For the top half of the sky during dawn/sunset.
+  ---@field dawn_sky mt.ColorSpec|nil
+  ---Default: `#bac1f0`. For the bottom half of the sky during dawn/sunset.
+  ---@field dawn_horizon mt.ColorSpec|nil
+  ---Default: `#006bff`. For the top half of the sky during the night.
+  ---@field night_sky mt.ColorSpec|nil
+  ---Default: `#4090ff`. For the bottom half of the sky during the night.
+  ---@field night_horizon mt.ColorSpec|nil
+  ---Default: `#646464`. For when you're either indoors or underground.
+  ---@field indoors mt.ColorSpec|nil
+  ---Default: `#f47d1d`. Changes the fog tinting for the sun at sunrise and sunset.
+  ---@field fog_sun_tint mt.ColorSpec|nil
+  ---Default: `#7f99cc`. Changes the fog tinting for the moon at sunrise and sunset.
+  ---@field fog_moon_tint mt.ColorSpec|nil
+  ---Default: `"default"`. Changes which mode the directional fog.
+  ---@field fog_tint_type `"custom"`|`"default"`|nil
+
+  --- A table with optional fields.
+  ---@class mt.Fog
+  --- Integer, set an upper bound the client's viewing_range (inluding range_all).
+  --- By default, fog_distance is controlled by the client's viewing_range, and this field is not set.
+  --- Any value >= 0 sets the desired upper bound for the client's viewing_range and disables range_all.
+  --- Any value < 0, resets the behavior to being client-controlled.
+  --- Ddefault: `-1`.
+  ---@field fog_distance? number
+  --- Float, override the client's fog_start.
+  --- Fraction of the visible distance at which fog starts to be rendered.
+  --- By default, fog_start is controlled by the client's `fog_start` setting, and this field is not set.
+  --- Any value between [0.0, 0.99] set the fog_start as a fraction of the viewing_range.
+  --- Any value < 0, resets the behavior to being client-controlled.
+  --- Default: `-1`.
+  ---@field fog_start? number
 
 ---* `as_table`: boolean that determines whether the deprecated version of this
 ---  function is being used.
@@ -633,8 +722,8 @@ function PlayerObjectRef:set_clouds(cloud_parameters) end
 function PlayerObjectRef:get_clouds() end
 
 ---* Overrides day-night ratio, controlling sunlight to a specific amount.
----* `nil`: Disables override, defaulting to sunlight based on day-night cycle.
----@param ratio number|nil Ratio from 0 to 1.
+---* Passing no arguments disables override, defaulting to sunlight based on day-night cycle.
+---@param ratio? number Ratio from 0 to 1.
 function PlayerObjectRef:override_day_night_ratio(ratio) end
 
 ---@return number|nil ratio Ratio from 0 to 1, or `nil` if not overridden.
@@ -666,12 +755,13 @@ function PlayerObjectRef:get_local_animation() end
 
 ---* Defines offset vectors for camera per player.
 ---* in third person view max values are `{x=-10/10, y=-10,15, z=-5/5}`
----@param firstperson? mt.Vector|nil Default: `{x=0, y=0, z=0}`.
----@param thirdperson? mt.Vector|nil Default: `{x=0, y=0, z=0}`.
-function PlayerObjectRef:set_eye_offset(firstperson, thirdperson) end
+---@param firstperson? mt.Vector|nil * Offset in first person view. <br> * Defaults to `vector.zero()` if unspecified.
+---@param thirdperson_back? mt.Vector|nil * Offset in third person back view. <br> * Clamped between `vector.new(-10, -10, -5)` and `vector.new(10, 15, 5)`. <br> * Defaults to `vector.zero()` if unspecified.
+---@param thirdperson_front? mt.Vector|nil * Offset in third person front view. <br> * Same limits as for `thirdperson_back` apply. <br> * Defaults to `thirdperson_back` if unspecified.
+function PlayerObjectRef:set_eye_offset(firstperson, thirdperson_back, thirdperson_front) end
 
 ---Returns first and third person offsets.
----@return mt.Vector|nil, mt.Vector|nil
+---@return mt.Vector|nil, mt.Vector|nil, mt.Vector|nil
 function get_eye_offset() end
 
 ---* Sends an already loaded mapblock to the player.
@@ -683,11 +773,21 @@ function get_eye_offset() end
 function PlayerObjectRef:send_mapblock(blockpos) end
 
 ---@class mt.Light
----@field saturation number|nil This value has no effect on clients who have the "Tone Mapping" shader disabled.
+---@field saturation number|nil This value has no effect on clients who have the "Tone Mapping" shader disabled. Default: `1.0`.
 ---@field shadows {intensity: number|nil}|nil This value has no effect on clients who have the "Dynamic Shadows" shader disabled.
+--- A table that controls automatic exposure.
+--- The basic exposure factor equation is `e = 2^exposure_correction / clamp(luminance, 2^luminance_min, 2^luminance_max)`.
+--- * `luminance_min` set the lower luminance boundary to use in the calculation (default: `-3.0`).
+--- * `luminance_max` set the upper luminance boundary to use in the calculation (default: `-3.0`).
+--- * `exposure_correction` correct observed exposure by the given EV value (default: `0.0`).
+--- * `speed_dark_bright` set the speed of adapting to bright light (default: `1000.0`).
+--- * `speed_bright_dark` set the speed of adapting to dark scene (default: `1000.0`).
+--- * `center_weight_power` set the power factor for center-weighted luminance measurement (default: `1.0`).
+---@field exposure {luminance_min: number, luminance_max: number, exposure_correction: number, speed_dark_bright: number, speed_bright_dark: number, center_weight_power: number}
 
 ---Sets lighting for the player.
----@param light_definition mt.Light
+--- * Passing no arguments resets lighting to its default values.
+---@param light_definition? mt.Light
 function PlayerObjectRef:set_lighting(light_definition) end
 
 ---Returns the current state of lighting for the player.
diff --git a/api/classes/settings.lua b/api/classes/settings.lua
index 9f6ec1f..b545da0 100644
--- a/api/classes/settings.lua
+++ b/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).
diff --git a/api/classes/sounds.lua b/api/classes/sounds.lua
index 9016df1..6b15336 100644
--- a/api/classes/sounds.lua
+++ b/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 = {}
diff --git a/api/classes/vector.lua b/api/classes/vector.lua
index cd0639b..45040cc 100644
--- a/api/classes/vector.lua
+++ b/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`.
diff --git a/api/definitions/decor.lua b/api/definitions/decor.lua
index c7f7073..f9a3607 100644
--- a/api/definitions/decor.lua
+++ b/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.
diff --git a/api/definitions/lbm.lua b/api/definitions/lbm.lua
index 9768212..5d3763c 100644
--- a/api/definitions/lbm.lua
+++ b/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)
diff --git a/api/definitions/node.lua b/api/definitions/node.lua
index 69dbd46..68684ff 100644
--- a/api/definitions/node.lua
+++ b/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,14 +208,14 @@ 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
 
@@ -220,18 +223,18 @@ function node.preserve_metadata(pos, oldnode, oldmeta, drops) end
 --   `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>`,
diff --git a/api/definitions/object.lua b/api/definitions/object.lua
index 45a0c12..a79d4a6 100644
--- a/api/definitions/object.lua
+++ b/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.
diff --git a/api/minetest/environment.lua b/api/minetest/environment.lua
index 0d93427..d027b95 100644
--- a/api/minetest/environment.lua
+++ b/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.
diff --git a/api/minetest/global.lua b/api/minetest/global.lua
index fc718df..a1fa4c8 100644
--- a/api/minetest/global.lua
+++ b/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`).
 ---
diff --git a/api/minetest/helpers.lua b/api/minetest/helpers.lua
index ea3c466..b6c8b30 100644
--- a/api/minetest/helpers.lua
+++ b/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`.
diff --git a/api/minetest/items.lua b/api/minetest/items.lua
index 430da29..ad97207 100644
--- a/api/minetest/items.lua
+++ b/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
diff --git a/api/minetest/jobs.lua b/api/minetest/jobs.lua
index 6a130d2..4c553d4 100644
--- a/api/minetest/jobs.lua
+++ b/api/minetest/jobs.lua
@@ -33,6 +33,7 @@ function minetest.after(time, func, ...) end
 --
 -- Classes:
 --
+-- - `AreaStore`
 -- - `ItemStack`
 -- - `PerlinNoise`
 -- - `PerlinNoiseMap`
diff --git a/api/minetest/misc.lua b/api/minetest/misc.lua
index 610011c..b7e2553 100644
--- a/api/minetest/misc.lua
+++ b/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`.
 ---
diff --git a/api/minetest/sounds.lua b/api/minetest/sounds.lua
index e97ebcc..ed7f2c7 100644
--- a/api/minetest/sounds.lua
+++ b/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
 
diff --git a/api/minetest/translations.lua b/api/minetest/translations.lua
index e3a514f..a2a8b22 100644
--- a/api/minetest/translations.lua
+++ b/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)`.
diff --git a/api/minetest/utilities.lua b/api/minetest/utilities.lua
index 9b3775e..8116f64 100644
--- a/api/minetest/utilities.lua
+++ b/api/minetest/utilities.lua
@@ -94,6 +94,12 @@ function minetest.is_singleplayer() end
 ---@field mod_storage_on_disk boolean
 -- "zstd" method for compress/decompress (5.7.0).
 ---@field compress_zstd boolean
+-- Sound parameter tables support start_time (5.8.0)
+---@field sound_params_start_time boolean
+-- New fields for set_physics_override: speed_climb, speed_crouch,
+-- liquid_fluidity, liquid_fluidity_smooth, liquid_sink,
+-- acceleration_default, acceleration_air (5.8.0)
+---@field physics_overrides_v2 boolean
 minetest.features = {}
 
 ---@param arg string | table<mt.Feature, boolean>
@@ -125,6 +131,40 @@ function minetest.has_feature(arg) end
 ---@return mt.PlayerInfo
 function minetest.get_player_information(player_name) end
 
+--- Will only be present if the client sent this information (requires v5.7+)
+---
+--- Note that none of these things are constant, they are likely to change during a client
+--- connection as the player resizes the window and moves it between monitors
+---
+--- real_gui_scaling and real_hud_scaling can be used instead of DPI.
+--- OSes don't necessarily give the physical DPI, as they may allow user configuration.
+--- real_*_scaling is just OS DPI / 96 but with another level of user configuration.
+---@class mt.PlayerWindowInfo
+--- Current size of the in-game render target (pixels).
+---
+--- This is usually the window size, but may be smaller in certain situations,
+--- such as side-by-side mode.
+---@field size {x: number, y: number}
+--- Estimated maximum formspec size before Minetest will start shrinking the
+--- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than
+--- this and `padding[-0.01,-0.01]`.
+---@field max_formspec_size {x: number, y: number}
+--- GUI Scaling multiplier
+---
+--- Equal to the setting `gui_scaling` multiplied by `dpi / 96`
+---@field real_gui_scaling number
+--- HUD Scaling multiplier
+---
+--- Equal to the setting `hud_scaling` multiplied by `dpi / 96`
+---@field real_hud_scaling number
+
+--- Will only be present if the client sent this information (requires v5.7+)
+---
+--- Note that none of these things are constant, they are likely to change during a client
+--- connection as the player resizes the window and moves it between monitors
+---@return mt.PlayerWindowInfo
+function minetest.get_player_window_information(player_name) end
+
 -- Creates a directory specified by `path`, creating parent directories
 -- if they don't exist.
 ---@param path string
@@ -177,6 +217,8 @@ function minetest.get_version() end
 ---@class mt.EngineVersion
 ---@field project string Name of the project, eg, "Minetest".
 ---@field string string Simple version, eg, "1.2.3-dev".
+---@field proto_min string The minimum supported protocol version.
+---@field proto_max string The maximum supported protocol version.
 -- Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty".
 ---@field hash string
 -- Boolean value indicating whether it's a development build.
@@ -221,3 +263,9 @@ function minetest.colorspec_to_bytes(colorspec) end
 ---@param data mt.ColorSpec[]|string
 ---@param compression integer|nil Optional zlib compression level from 0 to 9.
 function minetest.encode_png(width, height, data, compression) end
+
+--- Encodes non-unreserved URI characters by a
+--- percent sign followed by two hex digits. See
+--- [RFC 3986, section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
+---@param str string
+function minetest.urlencode(str) end