improve type checking

.cdb.json

@@ -0,0 +1,19 @@
+{
+    "type": "MOD",
+    "title": "X Bows",
+    "name": "x_bows",
+    "short_description": "Adds bow and arrows to Minetest.",
+    "dev_state": "MAINTENANCE_ONLY",
+    "tags": [
+        "pvp",
+        "shooter",
+        "survival",
+        "tools"
+    ],
+    "license": "GPLv2",
+    "media_license": "CC BY-SA 4.0",
+    "repo": "https://bitbucket.org/minetest_gamers/x_bows/src/master/",
+    "issue_tracker": "https://bitbucket.org/minetest_gamers/x_bows/issues",
+    "forums": 26466,
+    "video_url": "https://youtu.be/pItpltmUoa8"
+}

.editorconfig

@@ -0,0 +1,12 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

init.lua

@@ -1,3 +1,6 @@
+-- X Bows
+-- by SaKeL
+
 minetest = minetest--[[@as Minetest]]
 ItemStack = ItemStack--[[@as ItemStack]]
 vector = vector--[[@as Vector]]
@@ -6,6 +9,7 @@ default = default--[[@as MtgDefault]]
 local mod_start_time = minetest.get_us_time()
 local bow_charged_timer = 0
 
+-- main class
 x_bows = {
 	pvp = minetest.settings:get_bool('enable_pvp') or false,
 	creative = minetest.settings:get_bool('creative_mode') or false,

mod.conf

@@ -2,4 +2,5 @@ name = x_bows
 description = Adds bow and arrows to Minetest.
 depends =
 optional_depends = default, farming, 3d_armor, hbhunger, mesecons, playerphysics, player_monoids
-min_minetest_version = 5.0
+supported_games = minetest_game
+min_minetest_version = 5.4

types/colors.type.lua

@@ -0,0 +1,11 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---@alias ColorSpec string|ColorSpecTable A ColorSpec specifies a 32-bit color. It can be written in any of the following forms: `colorspec = {a=255, r=0, g=255, b=0}`, numerical form: The raw integer value of an ARGB8 quad: `colorspec = 0xFF00FF00`, string form: A ColorString (defined above): `colorspec = "green"`
+---@alias ColorString string `#RGB` defines a color in hexadecimal format. `#RGBA` defines a color in hexadecimal format and alpha channel. `#RRGGBB` defines a color in hexadecimal format. `#RRGGBBAA` defines a color in hexadecimal format and alpha channel. Named colors are also supported and are equivalent to [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#named-color). To specify the value of the alpha channel, append `#A` or `#AA` to the end of the color name (e.g. `colorname#08`).
+
+---A ColorSpec table form: Each element ranging from 0..255 (a, if absent, defaults to 255):
+---@class ColorSpecTable
+---@field a number
+---@field r number
+---@field g number
+---@field b number

types/craft-recipe.type.lua

@@ -0,0 +1,11 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Crafting recipes
+---@class CraftRecipeDef
+---@field type string (optional) specifies recipe type as shaped, e.g. "shaped", "shapeless", "toolrepair", "cooking", "fuel", default: "shaped"
+---@field output string Itemstring of output itemstack (item counts >= 1 are allowed)
+---@field recipe table<integer|number, string>[]|string A 2-dimensional matrix of items, with a width *w* and height *h*. *w* and *h* are chosen by you, they don't have to be equal but must be at least 1. The matrix is specified as a table containing tables containing itemnames. The inner tables are the rows. There must be *h* tables, specified from the top to the bottom row. Values inside of the inner table are the columns. Each inner table must contain a list of *w* items, specified from left to right. Empty slots *must* be filled with the empty string.
+---@field replacements string[] (optional) Allows you to replace input items with some other items when something is crafted. Provided as a list of item pairs of the form `{ old_item, new_item }` where `old_item` is the input item to replace (same syntax as for a regular input slot; groups are allowed) and `new_item` is an itemstring for the item stack it will become. When the output is crafted, Minetest iterates through the list of input items if the crafting grid. For each input item stack, it checks if it matches with an `old_item` in the item pair list. If it matches, the item will be replaced. Also, this item pair will *not* be applied again for the remaining items. If it does not match, the item is consumed (reduced by 1) normally. The `new_item` will appear in one of 3 places:  Crafting grid, if the input stack size was exactly 1, Player inventory, if input stack size was larger, Drops as item entity, if it fits neither in craft grid or inventory.
+---@field additional_wear number|integer For `{type = "toolrepair"}` only. Adds a shapeless recipe for *every* tool that doesn't have the `disable_repair=1` group. If this recipe is used, repairing is possible with any crafting grid with at least 2 slots. The player can put 2 equal tools in the craft grid to get one "repaired" tool back. The wear of the output is determined by the wear of both tools, plus a 'repair bonus' given by `additional_wear`. To reduce the wear (i.e. 'repair'), you want `additional_wear` to be negative. The formula used to calculate the resulting wear is: 65536 * (1 - ( (1 - tool_1_wear) + (1 - tool_2_wear) + additional_wear )) The result is rounded and can't be lower than 0. If the result is 65536 or higher, no crafting is possible.
+---@field cooktime number|integer For `{type = "cooking"}` only. (optional) Time it takes to cook this item, in seconds. A floating-point number. (default: 3.0)
+---@field burntime number|integer For `{type = "fuel"}` only. (optional) Burning time this item provides, in seconds. A floating-point number. (default: 1.0)

types/decoration.type.lua

@@ -0,0 +1,8 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---The varying types of decorations that can be placed.
+---@class DecorationDef
+---@field deco_type 'simple'|'schematic' `simple`: Creates a 1 times `H` times 1 column of a specified node (or a random node from a list, if a decoration list is specified). Can specify a certain node it must spawn next to, such as water or lava, for example. Can also generate a decoration of random height between a specified lower and upper bound. This type of decoration is intended for placement of grass, flowers, cacti, papyri, waterlilies and so on. `schematic`: Copies a box of `MapNodes` from a specified schematic file (or raw description). Can specify a probability of a node randomly appearing when placed. This decoration type is intended to be used for multi-node sized discrete structures, such as trees, cave spikes, rocks, and so on.
+---@field biomes any List of biomes in which this decoration occurs. Occurs in all biomes if this is omitted, and ignored if the Mapgen being used does not support biomes. Can be a list of (or a single) biome names, IDs, or definitions.
+---@field decoration string| string[] The node name used as the decoration. If instead a list of strings, a randomly selected node from the list is placed as the decoration.
+---@field place_on string| string[] Node (or list of nodes) that the decoration can be placed on

types/entity.type.lua

@@ -0,0 +1,18 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Entity definition
+---@class EntityDef
+---@field initial_properties ObjectProperties A table of object properties. The properties in this table are applied to the object once when it is spawned. `dtime_s` is the time passed since the object was unloaded, which can be used for updating the entity state.
+---@field on_activate fun(self: table, staticdata: string, dtime_s: integer|number) Function receive a "luaentity" table as `self`. Called when the object is instantiated.
+---@field on_deactivate fun(self: table, removal: boolean): nil Function receive a "luaentity" table as `self`. Called when the object is about to get removed or unloaded. `removal`: boolean indicating whether the object is about to get removed. Calling `object:remove()` on an active object will call this with `removal=true`. The mapblock the entity resides in being unloaded will call this with `removal=false`. Note that this won't be called if the object hasn't been activated in the first place. In particular, `minetest.clear_objects({mode = "full"})` won't call this, whereas `minetest.clear_objects({mode = "quick"})` might call this.
+---@field on_step fun(self: table, dtime: integer|number, moveresult?: table) Function receive a "luaentity" table as `self`. Called on every server tick, after movement and collision processing. `dtime`: elapsed time since last call. `moveresult`: table with collision info (only available if physical=true).
+---@field on_punch fun(self: table, puncher: ObjectRef|nil, time_from_last_punch: number|integer|nil, tool_capabilities: ToolCapabilitiesDef|nil, dir: Vector, damage: number|integer): boolean|nil Function receive a "luaentity" table as `self`. Called when somebody punches the object. Note that you probably want to handle most punches using the automatic armor group system. Can return `true` to prevent the default damage mechanism.
+---@field on_death fun(self: table, killer: ObjectRef|nil): nil Function receive a "luaentity" table as `self`. Called when the object dies.
+---@field on_rightclick fun(self: table, clicker: ObjectRef): nil Function receive a "luaentity" table as `self`. Called when `clicker` pressed the 'place/use' key while pointing to the object (not neccessarily an actual rightclick). `clicker`: an `ObjectRef` (may or may not be a player)
+---@field on_attach_child fun(self: table, child: ObjectRef): nil Function receive a "luaentity" table as `self`. `child`: an `ObjectRef` of the child that attaches
+---@field on_detach_child fun(self: table, child: ObjectRef): nil Function receive a "luaentity" table as `self`. `child`: an `ObjectRef` of the child that detaches
+---@field on_detach fun(self: table, parent: ObjectRef|nil) Function receive a "luaentity" table as `self`. `parent`: an `ObjectRef` (can be `nil`) from where it got detached. This happens before the parent object is removed from the world.
+---@field get_staticdata fun(self: table) Function receive a "luaentity" table as `self`. Should return a string that will be passed to `on_activate` when the object is instantiated the next time.
+
+---Entity definition
+---@class ObjectProperties

types/generic.type.lua

@@ -0,0 +1,7 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Undefined location
+---@class LocationUndefined
+---@field type string|'undefined'
+
+---@alias Dump fun(obj: any, dumped?: any): string returns a string which makes `obj` human-readable, `obj`: arbitrary variable, `dumped`: table, default: `{}`

types/inventory.type.lua

@@ -0,0 +1,20 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+--An `InvRef` is a reference to an inventory.
+---@class InvRef
+---@field add_item fun(self: InvRef, listname: string, stack: string|ItemStack): ItemStack Add item somewhere in list, returns leftover `ItemStack`.
+---@field contains_item fun(self: InvRef, listname: string, stack: string|ItemStack, match_meta?: boolean): boolean Returns `true` if the stack of items can be fully taken from the list. If `match_meta` is false, only the items' names are compared, default: `false`
+---@field get_list fun(self: InvRef, listname: string): ItemStack[] Return full list, list of `ItemStack`s
+---@field room_for_item fun(self: InvRef, listname: string, stack: string|ItemStack): boolean Returns `true` if the stack of items can be fully added to the list
+---@field set_stack fun(self: InvRef, listname: string, i: integer, stack: string|ItemStack): nil Copy `stack` to index `i` in list
+---@field is_empty fun(self: InvRef, listname: string): boolean Return `true` if list is empty
+---@field get_size fun(self: InvRef, listname: string): integer Get size of a list
+---@field set_size fun(self: InvRef, listname: string, size: integer): boolean Set size of a list, returns `false` on error, e.g. invalid `listname` or `size`
+---@field get_width fun(self: InvRef, listname: string): boolean Get width of a list
+---@field set_width fun(self: InvRef, listname: string, width: integer): nil Set width of list; currently used for crafting
+---@field get_stack fun(self: InvRef, listname: string, i: integer): ItemStack Get a copy of stack index `i` in list
+---@field set_list fun(self: InvRef, listname: string, list: ItemStack[]): nil Set full list, size will not change
+---@field get_lists fun(): table Returns table that maps listnames to inventory lists
+---@field set_lists fun(self: InvRef, lists: table): nil Sets inventory lists, size will not change
+---@field remove_item fun(self: InvRef, listname: string, stack: string|ItemStack): nil Take as many items as specified from the list, returns the items that were actually removed, as an `ItemStack`, note that any item metadata is ignored, so attempting to remove a specific unique item this way will likely remove the wrong one, to do that use `set_stack` with an empty `ItemStack`.
+---@field get_location fun(): InvRef|LocationUndefined returns a location compatible to `minetest.get_inventory(location)`. returns `{type="undefined"}` in case location is not known

types/item.type.lua

@@ -0,0 +1,53 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Minetest item definition. Used by `minetest.register_node`, `minetest.register_craftitem`, and `minetest.register_tool`.
+---Add your own custom fields. By convention, all custom field names. Should start with `_` to avoid naming collisions with future engine usage.
+---@class ItemDef
+---@field description string Can contain new lines. "\n" has to be used as new line character.
+---@field short_description string|nil Must not contain new lines. Defaults to nil.
+---@field groups table<string, string|number|integer|boolean> key = name, value = rating; rating = <number>. If rating not applicable, use 1. e.g. `{wool = 1, fluffy = 3}` `{soil = 2, outerspace = 1, crumbly = 1}` `{bendy = 2, snappy = 1}` {hard = 1, metal = 1, spikes = 1}
+---@field inventory_image string Texture shown in the inventory GUI. Defaults to a 3D rendering of the node if left empty.
+---@field inventory_overlay string An overlay texture which is not affected by colorization
+---@field wield_image string Texture shown when item is held in hand. Defaults to a 3D rendering of the node if left empty.
+---@field wield_overlay string Like inventory_overlay but only used in the same situation as wield_image
+---@field wield_scale table<string, number|integer> Scale for the item when held in hand
+---@field palette string An image file containing the palette of a node. You can set the currently used color as the "palette_index" field of the item stack metadata. The palette is always stretched to fit indices between 0 and 255, to ensure compatibility with "colorfacedir" (and similar) nodes.
+---@field color string Color the item is colorized with. The palette overrides this.
+---@field stack_max integer|number Maximum amount of items that can be in a single stack.
+---@field range integer|number Range of node and object pointing that is possible with this item held.
+---@field liquids_pointable boolean If true, item can point to all liquid nodes (`liquidtype ~= "none"`), even those for which `pointable = false`
+---@field light_source integer|number When used for nodes: Defines amount of light emitted by node. Otherwise: Defines texture glow when viewed as a dropped item. To set the maximum (14), use the value 'minetest.LIGHT_MAX'. A value outside the range 0 to minetest.LIGHT_MAX causes undefined behavior.
+---@field tool_capabilities ToolCapabilitiesDef
+---@field node_placement_prediction string|nil If nil and item is node, prediction is made automatically. If nil and item is not a node, no prediction is made. If "" and item is anything, no prediction is made. Otherwise should be name of node which the client immediately places on ground when the player places the item. Server will always update with actual result shortly.
+---@field node_dig_prediction string if "", no prediction is made. if "air", node is removed. Otherwise should be name of node which the client immediately places upon digging. Server will always update with actual result shortly.
+---@field sound ItemSoundDef
+---@field on_place fun(itemstack: ItemStack, placer: ObjectRef|nil, pointed_thing: PointedThingDef): ItemStack|nil When the 'place' key was pressed with the item in hand and a node was pointed at. Shall place item and return the leftover itemstack or nil to not modify the inventory. The placer may be any ObjectRef or nil. default: minetest.item_place
+---@field on_secondary_use fun(itemstack: ItemStack, user: ObjectRef|nil, pointed_thing: PointedThingDef): ItemStack|nil Same as on_place but called when not pointing at a node. Function must return either nil if inventory shall not be modified, or an itemstack to replace the original itemstack. The user may be any ObjectRef or nil. default: nil
+---@field on_drop fun(itemstack: ItemStack, dropper: ObjectRef|nil, pos: Vector): ItemStack Shall drop item and return the leftover itemstack. The dropper may be any ObjectRef or nil. default: minetest.item_drop
+---@field on_pickup fun(itemstack: ItemStack, picker: ObjectRef|nil, pointed_thing?: PointedThingDef, time_from_last_punch?: number|integer, rest?: any): ItemStack|nil Called when a dropped item is punched by a player. Shall pick-up the item and return the leftover itemstack or nil to not modify the dropped item. `rest` are other parameters from `luaentity:on_punch`. default: `minetest.item_pickup`
+---@field on_use fun(itemstack: ItemStack, user: ObjectRef|nil, pointed_thing: PointedThingDef): ItemStack|nil default: nil. When user pressed the 'punch/mine' key with the item in hand. Function must return either nil if inventory shall not be modified, or an itemstack to replace the original itemstack. e.g. itemstack:take_item(); return itemstack. Otherwise, the function is free to do what it wants. The user may be any ObjectRef or nil. The default functions handle regular use cases.
+---@field after_use fun(itemstack: ItemStack, user: ObjectRef|nil, node: NodeDef, digparams: DigParamsDef): ItemStack|nil default: nil. If defined, should return an itemstack and will be called instead of wearing out the item (if tool). If returns nil, does nothing.
+
+---Tool capabilities definition
+---@class ToolCapabilitiesDef
+---@field full_punch_interval number|integer
+---@field max_drop_level number|integer
+---@field groupcaps GroupCapsDef
+---@field damage_groups table<string, number|integer> Damage values must be between -32768 and 32767 (2^15)
+---@field punch_attack_uses number|integer|nil Amount of uses this tool has for attacking players and entities by punching them (0 = infinite uses). For compatibility, this is automatically set from the first suitable groupcap using the forumla "uses * 3^(maxlevel - 1)". It is recommend to set this explicitly instead of relying on the fallback behavior.
+
+---Known damage and digging time defining groups
+---@class GroupCapsDef
+---@field crumbly number|GroupCapsItemDef dirt, sand
+---@field cracky number|GroupCapsItemDef tough but crackable stuff like stone.
+---@field snappy number|GroupCapsItemDef something that can be cut using things like scissors, shears, bolt cutters and the like, e.g. leaves, small plants, wire, sheets of metal
+---@field choppy number|GroupCapsItemDef something that can be cut using force; e.g. trees, wooden planks
+---@field fleshy number|GroupCapsItemDef Living things like animals and the player. This could imply some blood effects when hitting.
+---@field explody number|GroupCapsItemDef Especially prone to explosions
+---@field oddly_breakable_by_hand number|GroupCapsItemDef Can be added to nodes that shouldn't logically be breakable by the hand but are. Somewhat similar to `dig_immediate`, but times are more like `{[1]=3.50,[2]=2.00,[3]=0.70}` and this does not override the digging speed of an item if it can dig at a faster speed than this suggests for the hand.
+
+---Known damage and digging time defining groups
+---@class GroupCapsItemDef
+---@field maxlevel number|integer Tells what is the maximum level of a node of this group that the item will be able to dig.
+---@field uses number|integer Tools only. Determines how many uses the tool has when it is used for digging a node, of this group, of the maximum level. The maximum supported number of uses is 65535. The special number 0 is used for infinite uses. For lower leveled nodes, the use count is multiplied by `3^leveldiff`. `leveldiff` is the difference of the tool's `maxlevel` `groupcaps` and the node's `level` group. The node cannot be dug if `leveldiff` is less than zero.
+---@field times table<number|integer, number|integer> List of digging times for different ratings of the group, for nodes of the maximum level. For example, as a Lua table, `times={[2]=2.00, [3]=0.70}`. This would result in the item to be able to dig nodes that have a rating of `2` or `3` for this group, and unable to dig the rating `1`, which is the toughest. Unless there is a matching group that enables digging otherwise. If the result digging time is 0, a delay of 0.15 seconds is added between digging nodes; If the player releases LMB after digging, this delay is set to 0, i.e. players can more quickly click the nodes away instead of holding LMB.

types/itemstack.type.lua

@@ -0,0 +1,35 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---A native C++ format with many helper methods. Useful for converting between formats.
+---An `ItemStack` is a stack of items.
+---It can be created via `ItemStack(x)`, where x is an `ItemStack`, an itemstring, a table or `nil`.
+---@class ItemStack
+---@field is_empty fun(): boolean Returns `true` if stack is empty.
+---@field get_name fun(): string returns item name (e.g. `"default:stone"`).
+---@field set_name fun(self: ItemStack, item_name: string): boolean Returns a boolean indicating whether the item was cleared.
+---@field get_count fun(): integer Returns number of items on the stack.
+---@field set_count fun(self: ItemStack, count: integer): boolean Returns a boolean indicating whether the item was cleared
+---@field get_wear fun(): integer Returns tool wear (`0`-`65535`), `0` for non-tools.
+---@field set_wear fun(self: ItemStack, wear: integer): boolean Returns boolean indicating whether item was cleared
+---@field get_meta fun(): ItemStackMetaRef Returns `ItemStackMetaRef`.
+---@field get_description fun(): string Returns the description shown in inventory list tooltips. The engine uses this when showing item descriptions in tooltips. Fields for finding the description, in order: `description` in item metadata.
+---@field get_short_description fun(): string|nil Returns the short description or nil. Unlike the description, this does not include new lines. Fields for finding the short description, in order: `short_description` in item metadata. Returns nil if none of the above are set.
+---@field clear fun(): nil Removes all items from the stack, making it empty.
+---@field replace fun(self: ItemStack, item: string|table)`: replace the contents of this stack. `item` can also be an itemstring or table.
+---@field to_string fun(): string Returns the stack in itemstring form.
+---@field to_table fun(): table Returns the stack in Lua table form.
+---@field get_stack_max fun(): integer Returns the maximum size of the stack (depends on the item).
+---@field get_free_space fun(): integer Returns `get_stack_max() - get_count()`.
+---@field is_known fun(): boolean Returns `true` if the item name refers to a defined item type.
+---@field get_definition fun(): table Returns the item definition table.
+---@field get_tool_capabilities fun(): table Returns the digging properties of the item, or those of the hand if none are defined for this item type
+---@field add_wear fun(self: ItemStack, amount: integer|number): nil Increases wear by `amount` if the item is a tool, otherwise does nothing. Valid `amount` range is [0,65536] `amount`: number, integer
+---@field add_wear_by_uses fun(self: ItemStack, max_uses: integer|number): nil Increases wear in such a way that, if only this function is called, the item breaks after `max_uses` times. Valid `max_uses` range is [0,65536] Does nothing if item is not a tool or if `max_uses` is 0
+---@field add_item fun(self: ItemStack, item: string|table): ItemStack Returns leftover `ItemStack` Put some item or stack onto this stack
+---@field item_fits fun(self: ItemStack, item: string|table): boolean Returns `true` if item or stack can be fully added to this one.
+---@field take_item fun(self: ItemStack, n: integer|number): ItemStack Returns taken `ItemStack` Take (and remove) up to `n` items from this stack `n`: number, default: `1`
+---@field peek_item fun(self: ItemStack, n: integer|number): ItemStack Returns taken `ItemStack` Copy (don't remove) up to `n` items from this stack `n`: number, default: `1`
+---@field name string
+---@field count integer
+---@field wear string
+---@field metadata string

types/mapgen-aliases.type.lua

@@ -0,0 +1,38 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+--- In a game, a certain number of these must be set to tell core mapgens which of the game's nodes are to be used for core mapgen generation.
+---@alias MapgenAliasesNonV6
+---| '"mapgen_stone"'
+---| '"mapgen_water_source"'
+---| '"mapgen_river_water_source"'
+---| '"mapgen_river_water_source"' # is required for mapgens with sloping rivers where it is necessary to have a river liquid node with a short `liquid_range` and `liquid_renewable = false` to avoid flooding.
+---| '"mapgen_lava_source"' # Optional, Fallback lava node used if cave liquids are not defined in biome definitions. Deprecated, define cave liquids in biome definitions instead.
+---| '"mapgen_cobble"' # Optional, Fallback node used if dungeon nodes are not defined in biome definitions. Deprecated, define dungeon nodes in biome definitions instead.
+
+--- In a game, a certain number of these must be set to tell core mapgens which of the game's nodes are to be used for core mapgen generation.
+---@alias MapgenAliasesV6
+---| '"mapgen_stone"'
+---| '"mapgen_water_source"'
+---| '"mapgen_lava_source"'
+---| '"mapgen_dirt"'
+---| '"mapgen_dirt_with_grass"'
+---| '"mapgen_sand"'
+---| '"mapgen_tree"'
+---| '"mapgen_leaves"'
+---| '"mapgen_apple"'
+---| '"mapgen_cobble"'
+---| '"mapgen_gravel"' # Optional, (falls back to stone)
+---| '"mapgen_desert_stone"' # Optional, (falls back to stone)
+---| '"mapgen_desert_sand"' # Optional, (falls back to sand)
+---| '"mapgen_dirt_with_snow"' # Optional, (falls back to dirt_with_grass)
+---| '"mapgen_snowblock"' # Optional, (falls back to dirt_with_grass)
+---| '"mapgen_snow"' # Optional, (not placed if missing)
+---| '"mapgen_ice"' # Optional, (falls back to water_source)
+---| '"mapgen_jungletree"' # Optional, (falls back to tree)
+---| '"mapgen_jungleleaves"' # Optional, (falls back to leaves)
+---| '"mapgen_junglegrass"' # Optional, (not placed if missing)
+---| '"mapgen_pine_tree"' # Optional, (falls back to tree)
+---| '"mapgen_pine_needles"' # Optional, (falls back to leaves)
+---| '"mapgen_stair_cobble"' # Optional, (falls back to cobble)
+---| '"mapgen_mossycobble"' # Optional, (falls back to cobble)
+---| '"mapgen_stair_desert_stone"' # Optional, (falls backto desert_stone)

types/meta.type.lua

@@ -0,0 +1,35 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---@alias ItemStackMetaRef MetaDataRef|ItemStackMetaRefAbstract
+---@alias NodeMetaRef MetaDataRef|NodeMetaRefAbstract
+---@alias PlayerMetaRef MetaDataRef|PlayerMetaRefAbstract
+---@alias StorageRef MetaDataRef|StorageRefAbstract
+
+---Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], and [`PlayerMetaRef`].
+---@class MetaDataRef
+---@field contains fun(self: MetaDataRef, key: string): boolean|nil Returns true if key present, otherwise false. Returns `nil` when the MetaData is inexistent.
+---@field get fun(self: MetaDataRef, key: string): string|nil Returns `nil` if key not present, else the stored string.
+---@field set_string fun(self: MetaDataRef, key: string, value: string): string Value of `""` will delete the key.
+---@field get_string fun(self: MetaDataRef, key: string): string Returns `""` if key not present.
+---@field set_int fun(self: MetaDataRef, key: string, value: integer): nil
+---@field get_int fun(self: MetaDataRef, key: string): string|integer Returns `0` if key not present.
+---@field set_float fun(self: MetaDataRef, key: string, value: number): nil
+---@field get_float fun(self: MetaDataRef, key): integer|number Returns `0` if key not present.
+---@field to_table fun(): nil Returns `nil` or a table with keys: `fields`: key-value storage `inventory`: `{list1 = {}, ...}}` (NodeMetaRef only)
+---@field from_table fun(self: MetaDataRef, t: nil|table): boolean Any non-table value will clear the metadata. Returns `true` on success
+---@field equals fun(self: MetaDataRef, other: any): boolean Returns `true` if this metadata has the same key-value pairs as `other`
+
+---ItemStack metadata: reference extra data and functionality stored in a stack. Can be obtained via `item:get_meta()`.
+---@class ItemStackMetaRefAbstract
+---@field set_tool_capabilities fun(self: ItemStackMetaRef, tool_capabilities?: table): nil Overrides the item's tool capabilities. A nil value will clear the override data and restore the original behavior.
+
+---Node metadata: reference extra data and functionality stored in a node. Can be obtained via `minetest.get_meta(pos)`.
+---@class NodeMetaRefAbstract
+---@field get_inventory fun(self: NodeMetaRef): InvRef
+---@field mark_as_private fun(self: NodeMetaRef, name: string | table<string[]>) Mark specific vars as private This will prevent them from being sent to the client. Note that the "private" status will only be remembered if an associated key-value pair exists, meaning it's best to call this when initializing all other meta (e.g. `on_construct`).
+
+---Player metadata. Uses the same method of storage as the deprecated player attribute API, so data there will also be in player meta. Can be obtained using `player:get_meta()`.
+---@class PlayerMetaRefAbstract
+
+---Mod metadata: per mod metadata, saved automatically. Can be obtained via `minetest.get_mod_storage()` during load time. WARNING: This storage backend is incapable of saving raw binary data due to restrictions of JSON.
+---@class StorageRefAbstract

types/minetest.type.lua

@@ -0,0 +1,115 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Minetest globals
+---@class Minetest
+---@field item_drop fun(itemstack: string|ItemStack, dropper: ObjectRef, pos: Vector): ItemStack Drop the item, returns the leftover itemstack
+---@field get_us_time fun(): integer|number Returns time with microsecond precision. May not return wall time.
+---@field get_modpath fun(modname: string): string|nil Returns the directory path for a mod, e.g. `"/home/user/.minetest/usermods/modname"`. Returns nil if the mod is not enabled or does not exist (not installed). Works regardless of whether the mod has been loaded yet. Useful for loading additional `.lua` modules or static data from a mod, or checking if a mod is enabled.
+---@field check_player_privs fun(player_or_name: ObjectRef|string, privs: table|string[]): boolean Returns `bool, missing_privs`. A quickhand for checking privileges.  `player_or_name`: Either a Player object or the name of a player. `privs` is either a list of strings, e.g. `"priva", "privb"` or a table, e.g. `{ priva = true, privb = true }`.
+---@field register_on_joinplayer fun(f: fun(player: ObjectRef, last_login: number|integer|nil)): nil Called when a player joins the game. `last_login`: The timestamp of the previous login, or nil if player is new
+---@field register_tool fun(name: string, item_definition: ItemDef): nil Registers the item in the engine
+---@field colorize fun(color: string, message: string): nil
+---@field register_craft fun(recipe: CraftRecipeDef): nil
+---@field register_craftitem fun(name: string, item_definition: ItemDef): nil
+---@field add_entity fun(pos: Vector, name: string, staticdata?: string): ObjectRef|nil  Spawn Lua-defined entity at position. Returns `ObjectRef`, or `nil` if failed.
+---@field get_node fun(pod: Vector): NodeDef Returns the node at the given position as table in the format `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}` for unloaded areas.
+---@field registered_nodes table<string, NodeDef|ItemDef> Map of registered node definitions, indexed by name
+---@field after fun(time: number|integer, func: fun(...), ...): JobTable Call the function `func` after `time` seconds, may be fractional. Optional: Variable number of arguments that are passed to `func`.
+---@field sound_play fun(spec: SimpleSoundSpec|string, parameters: SoundParamDef, ephemeral?: boolean): any Returns a `handle`. 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).
+---@field add_particlespawner fun(particlespawner_definition: ParticlespawnerDef): number|integer Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds. Returns an `id`, and -1 if adding didn't succeed.
+---@field register_globalstep fun(func: fun(dtime: number|integer)): nil Called every server step, usually interval of 0.1s
+---@field get_connected_players fun(): ObjectRef[] Returns list of `ObjectRefs`
+---@field serialize fun(t: table): string Convert a table containing tables, strings, numbers, booleans and `nil`s into string form readable by `minetest.deserialize`. Example: `serialize({foo="bar"})`, returns `'return { ["foo"] = "bar" }'`.
+---@field dir_to_yaw fun(dir: Vector): number|integer Convert a vector into a yaw (angle)
+---@field settings MinetestSettings Settings object containing all of the settings from the main config file (`minetest.conf`).
+---@field register_entity fun(name: string, entity_definition: EntityDef): nil
+---@field deserialize fun(s: string, safe?: boolean): table Returns a table. Convert a string returned by `minetest.serialize` into a table `string` is loaded in an empty sandbox environment. Will load functions if safe is false or omitted. Although these functions cannot directly access the global environment, they could bypass this restriction with maliciously crafted Lua bytecode if mod security is disabled. This function should not be used on untrusted data, regardless of the value of `safe`. It is fine to serialize then deserialize user-provided data, but directly providing user input to deserialize is always unsafe.
+---@field raycast fun(pos1: Vector, pos2: Vector, objects: boolean, liquids: boolean): Raycast `pos1`: start of the ray, `pos2`: end of the ray, `objects`: if false, only nodes will be returned. Default is true. `liquids`: if false, liquid nodes (`liquidtype ~= "none"`) won't be returned. Default is false.
+---@field calculate_knockback fun(player: ObjectRef, hitter: ObjectRef, time_from_last_punch: number|integer, tool_capabilities: ToolCapabilitiesDef, dir: Vector, distance: number|integer, damage: number|integer): integer|number Returns the amount of knockback applied on the punched player. Arguments are equivalent to `register_on_punchplayer`, except the following: `distance`: distance between puncher and punched player. This function can be overriden by mods that wish to modify this behaviour. You may want to cache and call the old function to allow multiple mods to change knockback behaviour.
+---@field get_player_by_name fun(name: string): ObjectRef Get an `ObjectRef` to a player
+---@field get_node_timer fun(pos: Vector): NodeTimerRef Get `NodeTimerRef`
+---@field get_objects_inside_radius fun(pos: Vector, radius: number|integer): ObjectRef[] Returns a list of ObjectRefs. `radius`: using an euclidean metric.
+---@field register_node fun(name: string, node_definition: NodeDef): nil
+---@field get_meta fun(pos: Vector): NodeMetaRef Get a `NodeMetaRef` at that position
+---@field pos_to_string fun(pos: Vector, decimal_places?: number|integer): string returns string `"(X,Y,Z)"`, `pos`: table {x=X, y=Y, z=Z}. Converts the position `pos` to a human-readable, printable string. `decimal_places`: number, if specified, the x, y and z values of the position are rounded to the given decimal place.
+---@field get_node_light fun(pos: Vector, timeofday: number|integer|nil): number|integer|nil Gets the light value at the given position. Note that the light value "inside" the node at the given position is returned, so you usually want to get the light value of a neighbor. `pos`: The position where to measure the light. `timeofday`: `nil` for current time, `0` for night, `0.5` for day. Returns a number between `0` and `15` or `nil`. `nil` is returned e.g. when the map isn't loaded at `pos`.
+---@field set_node fun(pos: Vector, node: SetNodeTable): nil Set node at position `pos`, `node`: table `{name=string, param1=number, param2=number}`, If param1 or param2 is omitted, it's set to `0`. e.g. `minetest.set_node({x=0, y=10, z=0}, {name="default:wood"})`
+---@field place_schematic fun(pos: Vector, schematic, rotation?: '0'|'90'|'180'|'270'|'random', replacements?: table<string, string>, force_placement?: boolean, flags?: string): nil Place the schematic specified by schematic at `pos`. `rotation` can equal `"0"`, `"90"`, `"180"`, `"270"`, or `"random"`. If the `rotation` parameter is omitted, the schematic is not rotated. `replacements` = `{["old_name"] = "convert_to", ...}`. `force_placement` is a boolean indicating whether nodes other than `air` and `ignore` are replaced by the schematic. Returns nil if the schematic could not be loaded. **Warning**: Once you have loaded a schematic from a file, it will be cached. Future calls will always use the cached version and the replacement list defined for it, regardless of whether the file or the replacement list parameter have changed. The only way to load the file anew is to restart the server. `flags` is a flag field with the available flags: place_center_x, place_center_y, place_center_z
+---@field log fun(level?: 'none'|'error'|'warning'|'action'|'info'|'verbose', text: string): nil
+---@field get_item_group fun(name: string, group): any returns a rating. Get rating of a group of an item. (`0` means: not in group)
+---@field get_biome_data fun(pos: Vector): BiomeData|nil
+---@field get_biome_name fun(biome_id: string|number|integer): string|nil Returns the biome name string for the provided biome id, or `nil` on failure. If no biomes have been registered, such as in mgv6, returns `default`.
+---@field find_nodes_in_area fun(pos1: Vector, pos2: Vector, nodenames: string|string[], grouped?: boolean): table `pos1` and `pos2` are the min and max positions of the area to search. `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` If `grouped` is true the return value is a table indexed by node name which contains lists of positions. If `grouped` is false or absent the return values are as follows: first value: Table with all node positions, second value: Table with the count of each node with the node name as index, Area volume is limited to 4,096,000 nodes
+---@field find_nodes_in_area_under_air fun(pos1: Vector, pos2: Vector, nodenames: string|string[]): table returns a list of positions. `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`. Return value: Table with all node positions with a node air above. Area volume is limited to 4,096,000 nodes.
+---@field registered_decorations table<any, DecorationDef> Map of registered decoration definitions, indexed by the `name` field. If `name` is nil, the key is the object handle returned by `minetest.register_schematic`.
+---@field swap_node fun(pos: Vector, node: NodeDef): nil Set node at position, but don't remove metadata
+---@field item_eat fun(hp_change: number, replace_with_item?: string): fun(itemstack: ItemStack, user: ObjectRef, pointed_thing: PointedThingDef) Returns `function(itemstack, user, pointed_thing)` as a function wrapper for `minetest.do_item_eat`. `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.
+---@field override_item fun(name: string, redefinition: ItemDef|NodeDef): nil Overrides fields of an item registered with register_node/tool/craftitem. Note: Item must already be defined, (opt)depend on the mod defining it. Example: `minetest.override_item("default:mese", {light_source=minetest.LIGHT_MAX})`
+---@field register_decoration fun(decoration_definition: DecorationDef): number|integer Returns an integer object handle uniquely identifying the registered decoration on success. To get the decoration ID, use `minetest.get_decoration_id`. The order of decoration registrations determines the order of decoration generation.
+---@field find_node_near fun(pos: Vector, radius: number, nodenames: string[], search_center?: boolean): Vector|nil returns pos or `nil`. `radius`: using a maximum metric, `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`, `search_center` is an optional boolean (default: `false`) If true `pos` is also checked for the nodes
+---@field remove_node fun(pos: Vector): nil By default it does the same as `minetest.set_node(pos, {name="air"})`
+---@field get_node_or_nil fun(pos: Vector): NodeDef|nil Same as `get_node` but returns `nil` for unloaded areas.
+---@field facedir_to_dir fun(facedir: number): Vector Convert a facedir back into a vector aimed directly out the "back" of a node.
+---@field record_protection_violation fun(pos: Vector, name: string): nil This function calls functions registered with `minetest.register_on_protection_violation`.
+---@field dir_to_facedir fun(dir: Vector, is6d?: any): number Convert a vector to a facedir value, used in `param2` for `paramtype2="facedir"`. passing something non-`nil`/`false` for the optional second parameter causes it to take the y component into account.
+---@field register_lbm fun(lbm_definition: LbmDef): nil
+---@field rotate_node fun(itemstack: ItemStack, placer: ObjectRef, pointed_thing: PointedThingDef): nil calls `rotate_and_place()` with `infinitestacks` set according to the state of the creative mode setting, checks for "sneak" to set the `invert_wall` parameter and `prevent_after_place` set to `true`.
+---@field global_exists fun(name: string): nil Checks if a global variable has been set, without triggering a warning.
+---@field register_alias fun(alias: string|MapgenAliasesV6|MapgenAliasesNonV6, original_name: string): nil Also use this to set the 'mapgen aliases' needed in a game for the core mapgens. See [Mapgen aliases] section above.
+---@field register_alias_force fun(alias: string|MapgenAliasesV6|MapgenAliasesNonV6, original_name: string): nil
+---@field add_item fun(pos: Vector, item: ItemStack): ObjectRef|nil Spawn item. Returns `ObjectRef`, or `nil` if failed.
+---@field registered_items table<string, ItemDef> Map of registered items, indexed by name
+---@field add_node fun(pos: Vector, node: SetNodeTable): nil alias to `minetest.set_node`, Set node at position `pos`, `node`: table `{name=string, param1=number, param2=number}`, If param1 or param2 is omitted, it's set to `0`. e.g. `minetest.set_node({x=0, y=10, z=0}, {name="default:wood"})`
+---@field string_to_pos fun(string: string): Vector|nil If the string can't be parsed to a position, nothing is returned.
+---@field chat_send_player fun(name: string, text: string): nil
+
+---Minetest settings
+---@class MinetestSettings
+---@field get fun(self: MinetestSettings, key: string): string|number|integer Returns a value
+---@field get_bool fun(self: MinetestSettings, key: string, default?: boolean): boolean|nil Returns a boolean. `default` is the value returned if `key` is not found. Returns `nil` if `key` is not found and `default` not specified.
+---@field get_np_group fun(self: MinetestSettings, key: string): table Returns a NoiseParams table
+---@field get_flags fun(self: MinetestSettings, key: string): table Returns `{flag = true/false, ...}` according to the set flags. Is currently limited to mapgen flags `mg_flags` and mapgen-specific flags like `mgv5_spflags`.
+---@field set fun(self: MinetestSettings, key: string, value: string|integer|number): nil 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`).
+---@field set_bool fun(self: MinetestSettings, key: string, value: boolean): nil 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`).
+---@field set_np_group fun(self: MinetestSettings, key: string, value: table): nil `value` is a NoiseParams table.
+---@field remove fun(self: MinetestSettings, key: string): boolean Returns a boolean (`true` for success)
+---@field get_names fun(): table Returns `{key1,...}`
+---@field write fun(): boolean Returns a boolean (`true` for success). Writes changes to file.
+---@field to_table fun(): table Returns `{[key1]=value1,...}`
+
+--- Set node table
+---@class SetNodeTable
+---@field name string
+---@field param1 number
+---@field param2 number
+
+--- Job table
+---@class JobTable
+---@field cancel fun(self: JobTable) Cancels the job function from being called
+
+--- Biome data
+---@class BiomeData
+---@field biome string|number|integer the biome id of the biome at that position
+---@field heat string|number|integer the heat at the position
+---@field humidity string|number|integer the humidity at the position
+
+--- LBM (LoadingBlockModifier) definition. A loading block modifier (LBM) is used to define a function that is called for specific nodes (defined by `nodenames`) when a mapblock which contains such nodes gets activated (not loaded!)
+---@class LbmDef
+---@field label string Descriptive label for profiling purposes (optional). Definitions with identical labels will be listed as one.
+---@field name string Identifier of the LBM, should follow the modname:<whatever> convention
+---@field nodenames string[] List of node names to trigger the LBM on. Names of non-registered nodes and groups (as group:groupname) will work as well.
+---@field run_at_every_load boolean Whether to run the LBM's action every time a block gets activated, and not only the first time the block gets activated after the LBM was introduced.
+---@field action fun(pos: Vector, node: NodeDef): nil Function triggered for each qualifying node.
+
+--- Sound parameters.
+--- Looped sounds must either be connected to an object or played locationless to one player using `to_player = name`. A positional sound will only be heard by players that are within `max_hear_distance` of the sound position, at the start of the sound. `exclude_player = name` can be applied to locationless, positional and object-bound sounds to exclude a single player from hearing them.
+---@class SoundParamDef
+---@field to_player string Name
+---@field gain number|integer
+---@field fade number|integer Change to a value > 0 to fade the sound in
+---@field pitch number|integer
+---@field loop boolean
+---@field pos Vector
+---@field max_hear_distance number|integer
+---@field object ObjectRef
+---@field exclude_player string Name

types/mt.types.lua

@@ -1,361 +0,0 @@
----https://github.com/sumneko/lua-language-server/wiki
-
-------All `vector.*` functions allow vectors `{x = X, y = Y, z = Z}` without metatables. Returned vectors always have a metatable set.
----@class Vector
----@field x integer|number Pitch
----@field y integer|number Yaw
----@field z integer|number Roll
----@field multiply fun(v: Vector, s: number|integer): Vector Returns a scaled vector. Deprecated: If `s` is a vector: Returns the Schur product.
----@field subtract fun(v: Vector, x: number|integer|Vector): Vector Returns a vector. If `x` is a vector: Returns the difference of `v` subtracted by `x`. If `x` is a number: Subtracts `x` from each component of `v`.
----@field add fun(v: Vector, x: number|integer|Vector): Vector Returns a vector. If `x` is a vector: Returns the sum of `v` and `x`. If `x` is a number: Adds `x` to each component of `v`.
----@field normalize fun(v: Vector): Vector Returns a vector of length 1 with direction of vector `v`. If `v` has zero length, returns `(0, 0, 0)`.
----@field distance fun(p1: Vector, p2: Vector): number|integer Returns zero or a positive number, the distance between `p1` and `p2`.
----@field round fun(v: Vector): Vector Returns a vector, each dimension rounded to nearest integer. At a multiple of 0.5, rounds away from zero.
-
----Moving things in the game are generally these.
----This is basically a reference to a C++ `ServerActiveObject`.
----@class ObjectRef
----@field get_pos fun(): Vector Position of player
----@field get_inventory fun(): InvRef|nil Returns an `InvRef` for players, otherwise returns `nil`
----@field get_wield_index fun(): integer Returns the index of the wielded item
----@field get_wielded_item fun(): ItemStack Returns an `ItemStack`
----@field set_velocity fun(self: ObjectRef, vel: Vector): nil
----@field set_acceleration fun(self: ObjectRef, acc: Vector): nil
----@field set_yaw fun(self: ObjectRef, yaw: integer|number): nil Sets the yaw in radians (heading).
----@field get_player_name fun(self: ObjectRef): string Returns `""` if is not a player.
----@field set_fov fun(self: ObjectRef, fov: number|integer, is_multiplier: boolean, transition_time: number|integer): nil Sets player's FOV. `fov`: FOV value. `is_multiplier`: Set to `true` if the FOV value is a multiplier. Defaults to `false`. `transition_time`: If defined, enables smooth FOV transition. Interpreted as the time (in seconds) to reach target FOV. If set to 0, FOV change is instantaneous. Defaults to 0. Set `fov` to 0 to clear FOV override.
----@field get_hp fun(self: ObjectRef): number|integer Returns number of health points
----@field is_player fun(self: ObjectRef): boolean returns true for players, false otherwise
----@field get_luaentity fun(self: ObjectRef): table
----@field get_armor_groups fun(self: ObjectRef): ObjectRefArmorGroups returns a table with the armor group ratings
----@field punch fun(self: ObjectRef, puncher: ObjectRef, time_from_last_punch: integer|number, tool_capabilities: ToolCapabilitiesDef, direction: Vector|nil): nil
----@field add_velocity fun(self: ObjectRef, vel: Vector): nil `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`. 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: 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 (see: physics overrides) will cause existing X/Z velocity to be reduced. Example: `add_velocity({x=0, y=6.5, z=0})` is equivalent to pressing the jump key (assuming default settings)
----@field get_properties fun(self: ObjectRef): table Returns object property table
----@field get_children fun(self: ObjectRef): ObjectRef[] Returns a list of ObjectRefs that are attached to the object.
-
----`ObjectRef` armor groups
----@class ObjectRefArmorGroups
----@field immortal number|integer Skips all damage and breath handling for an object. This group will also hide the integrated HUD status bars for players. It is automatically set to all players when damage is disabled on the server and cannot be reset (subject to change).
----@field fall_damage_add_percent number|integer Modifies the fall damage suffered by players when they hit the ground. It is analog to the node group with the same name. See the node group above for the exact calculation.
----@field punch_operable number|integer For entities; disables the regular damage mechanism for players punching it by hand or a non-tool item, so that it can do something else than take damage.
-
----A native C++ format with many helper methods. Useful for converting between formats.
----An `ItemStack` is a stack of items.
----It can be created via `ItemStack(x)`, where x is an `ItemStack`, an itemstring, a table or `nil`.
----@class ItemStack
----@field is_empty fun(): boolean Returns `true` if stack is empty.
----@field get_name fun(): string returns item name (e.g. `"default:stone"`).
----@field set_name fun(self: ItemStack, item_name: string): boolean Returns a boolean indicating whether the item was cleared.
----@field get_count fun(): integer Returns number of items on the stack.
----@field set_count fun(self: ItemStack, count: integer): boolean Returns a boolean indicating whether the item was cleared
----@field get_wear fun(): integer Returns tool wear (`0`-`65535`), `0` for non-tools.
----@field set_wear fun(self: ItemStack, wear: integer): boolean Returns boolean indicating whether item was cleared
----@field get_meta fun(): ItemStackMetaRef Returns `ItemStackMetaRef`.
----@field get_description fun(): string Returns the description shown in inventory list tooltips. The engine uses this when showing item descriptions in tooltips. Fields for finding the description, in order: `description` in item metadata.
----@field get_short_description fun(): string|nil Returns the short description or nil. Unlike the description, this does not include new lines. Fields for finding the short description, in order: `short_description` in item metadata. Returns nil if none of the above are set.
----@field clear fun(): nil Removes all items from the stack, making it empty.
----@field replace fun(self: ItemStack, item: string|table)`: replace the contents of this stack. `item` can also be an itemstring or table.
----@field to_string fun(): string Returns the stack in itemstring form.
----@field to_table fun(): table Returns the stack in Lua table form.
----@field get_stack_max fun(): integer Returns the maximum size of the stack (depends on the item).
----@field get_free_space fun(): integer Returns `get_stack_max() - get_count()`.
----@field is_known fun(): boolean Returns `true` if the item name refers to a defined item type.
----@field get_definition fun(): table Returns the item definition table.
----@field get_tool_capabilities fun(): table Returns the digging properties of the item, or those of the hand if none are defined for this item type
----@field add_wear fun(self: ItemStack, amount: integer|number): nil Increases wear by `amount` if the item is a tool, otherwise does nothing. Valid `amount` range is [0,65536] `amount`: number, integer
----@field add_wear_by_uses fun(self: ItemStack, max_uses: integer|number): nil Increases wear in such a way that, if only this function is called, the item breaks after `max_uses` times. Valid `max_uses` range is [0,65536] Does nothing if item is not a tool or if `max_uses` is 0
----@field add_item fun(self: ItemStack, item: string|table): ItemStack Returns leftover `ItemStack` Put some item or stack onto this stack
----@field item_fits fun(self: ItemStack, item: string|table): boolean Returns `true` if item or stack can be fully added to this one.
----@field take_item fun(self: ItemStack, n: integer|number): ItemStack Returns taken `ItemStack` Take (and remove) up to `n` items from this stack `n`: number, default: `1`
----@field peek_item fun(self: ItemStack, n: integer|number): ItemStack Returns taken `ItemStack` Copy (don't remove) up to `n` items from this stack `n`: number, default: `1`
----@field name string
----@field count integer
----@field wear string
----@field metadata string
-
----ItemStack metadata: reference extra data and functionality stored in a stack. Can be obtained via `item:get_meta()`.
----@class ItemStackMetaRef
----@field set_tool_capabilities fun(self: ItemStackMetaRef, tool_capabilities?: table): nil Overrides the item's tool capabilities. A nil value will clear the override data and restore the original behavior.
----@field contains fun(self: MetaDataRef, key: string): boolean|nil Returns true if key present, otherwise false. Returns `nil` when the MetaData is inexistent.
----@field get fun(self: MetaDataRef, key: string): string|nil Returns `nil` if key not present, else the stored string.
----@field set_string fun(self: MetaDataRef, key: string, value: string): string Value of `""` will delete the key.
----@field get_string fun(self: MetaDataRef, key: string): string Returns `""` if key not present.
----@field set_int fun(self: MetaDataRef, key: string, value: integer): nil
----@field get_int fun(self: MetaDataRef, key: string): string|integer Returns `0` if key not present.
----@field set_float fun(self: MetaDataRef, key: string, value: number): nil
----@field get_float fun(self: MetaDataRef, key): integer|number Returns `0` if key not present.
----@field to_table fun(): nil Returns `nil` or a table with keys: `fields`: key-value storage `inventory`: `{list1 = {}, ...}}` (NodeMetaRef only)
----@field from_table fun(self: MetaDataRef, t: nil|table): boolean Any non-table value will clear the metadata. Returns `true` on success
----@field equals fun(self: MetaDataRef, other: any): boolean Returns `true` if this metadata has the same key-value pairs as `other`
-
----Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], and [`PlayerMetaRef`].
----@class MetaDataRef
----@field contains fun(self: MetaDataRef, key: string): boolean|nil Returns true if key present, otherwise false. Returns `nil` when the MetaData is inexistent.
----@field get fun(self: MetaDataRef, key: string): string|nil Returns `nil` if key not present, else the stored string.
----@field set_string fun(self: MetaDataRef, key: string, value: string): string Value of `""` will delete the key.
----@field get_string fun(self: MetaDataRef, key: string): string Returns `""` if key not present.
----@field set_int fun(self: MetaDataRef, key: string, value: integer): nil
----@field get_int fun(self: MetaDataRef, key: string): string|integer Returns `0` if key not present.
----@field set_float fun(self: MetaDataRef, key: string, value: number): nil
----@field get_float fun(self: MetaDataRef, key): integer|number Returns `0` if key not present.
----@field to_table fun(): nil Returns `nil` or a table with keys: `fields`: key-value storage `inventory`: `{list1 = {}, ...}}` (NodeMetaRef only)
----@field from_table fun(self: MetaDataRef, t: nil|table): boolean Any non-table value will clear the metadata. Returns `true` on success
----@field equals fun(self: MetaDataRef, other: any): boolean Returns `true` if this metadata has the same key-value pairs as `other`
-
----An `InvRef` is a reference to an inventory.
----@class InvRef
----@field add_item fun(self: InvRef, listname: string, stack: string|ItemStack): ItemStack Add item somewhere in list, returns leftover `ItemStack`.
----@field contains_item fun(self: InvRef, listname: string, stack: string|ItemStack, match_meta?: boolean): boolean Returns `true` if the stack of items can be fully taken from the list. If `match_meta` is false, only the items' names are compared, default: `false`
----@field get_list fun(self: InvRef, listname: string): ItemStack[] Return full list, list of `ItemStack`s
----@field room_for_item fun(self: InvRef, listname: string, stack: string|ItemStack): boolean Returns `true` if the stack of items can be fully added to the list
----@field set_stack fun(self: InvRef, listname: string, i: integer, stack: string|ItemStack): nil Copy `stack` to index `i` in list
----@field is_empty fun(self: InvRef, listname: string): boolean Return `true` if list is empty
----@field get_size fun(self: InvRef, listname: string): integer Get size of a list
----@field set_size fun(self: InvRef, listname: string, size: integer): boolean Set size of a list, returns `false` on error, e.g. invalid `listname` or `size`
----@field get_width fun(self: InvRef, listname: string): boolean Get width of a list
----@field set_width fun(self: InvRef, listname: string, width: integer): nil Set width of list; currently used for crafting
----@field get_stack fun(self: InvRef, listname: string, i: integer): ItemStack Get a copy of stack index `i` in list
----@field set_list fun(self: InvRef, listname: string, list: ItemStack[]): nil Set full list, size will not change
----@field get_lists fun(): table Returns table that maps listnames to inventory lists
----@field set_lists fun(self: InvRef, lists: table): nil Sets inventory lists, size will not change
----@field remove_item fun(self: InvRef, listname: string, stack: string|ItemStack): nil Take as many items as specified from the list, returns the items that were actually removed, as an `ItemStack`, note that any item metadata is ignored, so attempting to remove a specific unique item this way will likely remove the wrong one, to do that use `set_stack` with an empty `ItemStack`.
----@field get_location fun(): InvRef|LocationUndefined returns a location compatible to `minetest.get_inventory(location)`. returns `{type="undefined"}` in case location is not known
-
----Undefined location
----@class LocationUndefined
----@field type string|'undefined'
-
----Minetest globals
----@class Minetest
----@field item_drop fun(itemstack: string|ItemStack, dropper: ObjectRef, pos: Vector): ItemStack Drop the item, returns the leftover itemstack
----@field get_us_time fun(): integer|number Returns time with microsecond precision. May not return wall time.
----@field get_modpath fun(modname: string): string|nil Returns the directory path for a mod, e.g. `"/home/user/.minetest/usermods/modname"`. Returns nil if the mod is not enabled or does not exist (not installed). Works regardless of whether the mod has been loaded yet. Useful for loading additional `.lua` modules or static data from a mod, or checking if a mod is enabled.
----@field check_player_privs fun(player_or_name: ObjectRef|string, privs: table|string[]): boolean Returns `bool, missing_privs`. A quickhand for checking privileges.  `player_or_name`: Either a Player object or the name of a player. `privs` is either a list of strings, e.g. `"priva", "privb"` or a table, e.g. `{ priva = true, privb = true }`.
----@field register_on_joinplayer fun(f: fun(player: ObjectRef, last_login: number|integer|nil)): nil Called when a player joins the game. `last_login`: The timestamp of the previous login, or nil if player is new
----@field register_tool fun(name: string, item_definition: ItemDef): nil Registers the item in the engine
----@field colorize fun(color: string, message: string): nil
----@field register_craft fun(recipe: CraftRecipeDef): nil
----@field register_craftitem fun(name: string, item_definition: ItemDef): nil
----@field add_entity fun(pos: Vector, name: string, staticdata?: string): ObjectRef|nil  Spawn Lua-defined entity at position. Returns `ObjectRef`, or `nil` if failed.
----@field get_node fun(pod: Vector): table<string, string|number|integer|boolean> Returns the node at the given position as table in the format `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}` for unloaded areas.
----@field registered_nodes table<string, NodeDef> Map of registered node definitions, indexed by name
----@field after fun(time: number|integer, func: fun(...), ...): JobTable Call the function `func` after `time` seconds, may be fractional. Optional: Variable number of arguments that are passed to `func`.
----@field sound_play fun(spec: SimpleSoundSpec|string, parameters: SoundParamDef, ephemeral?: boolean): any Returns a `handle`. 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).
----@field add_particlespawner fun(particlespawner_definition: ParticlespawnerDef): number|integer Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds. Returns an `id`, and -1 if adding didn't succeed.
----@field register_globalstep fun(func: fun(dtime: number|integer)): nil Called every server step, usually interval of 0.1s
----@field get_connected_players fun(): ObjectRef[] Returns list of `ObjectRefs`
----@field serialize fun(t: table): string Convert a table containing tables, strings, numbers, booleans and `nil`s into string form readable by `minetest.deserialize`. Example: `serialize({foo="bar"})`, returns `'return { ["foo"] = "bar" }'`.
----@field dir_to_yaw fun(dir: Vector): number|integer Convert a vector into a yaw (angle)
----@field settings MinetestSettings Settings object containing all of the settings from the main config file (`minetest.conf`).
----@field register_entity fun(name: string, entity_definition: EntityDef): nil
----@field deserialize fun(s: string, safe?: boolean): table Returns a table. Convert a string returned by `minetest.serialize` into a table `string` is loaded in an empty sandbox environment. Will load functions if safe is false or omitted. Although these functions cannot directly access the global environment, they could bypass this restriction with maliciously crafted Lua bytecode if mod security is disabled. This function should not be used on untrusted data, regardless of the value of `safe`. It is fine to serialize then deserialize user-provided data, but directly providing user input to deserialize is always unsafe.
----@field raycast fun(pos1: Vector, pos2: Vector, objects: boolean, liquids: boolean): Raycast `pos1`: start of the ray, `pos2`: end of the ray, `objects`: if false, only nodes will be returned. Default is true. `liquids`: if false, liquid nodes (`liquidtype ~= "none"`) won't be returned. Default is false.
----@field calculate_knockback fun(player: ObjectRef, hitter: ObjectRef, time_from_last_punch: number|integer, tool_capabilities: ToolCapabilitiesDef, dir: Vector, distance: number|integer, damage: number|integer): integer|number Returns the amount of knockback applied on the punched player. Arguments are equivalent to `register_on_punchplayer`, except the following: `distance`: distance between puncher and punched player. This function can be overriden by mods that wish to modify this behaviour. You may want to cache and call the old function to allow multiple mods to change knockback behaviour.
----@field get_player_by_name fun(name: string): ObjectRef Get an `ObjectRef` to a player
----@field get_node_timer fun(pos: Vector): NodeTimerRef Get `NodeTimerRef`
----@field get_objects_inside_radius fun(pos: Vector, radius: number|integer): ObjectRef[] Returns a list of ObjectRefs. `radius`: using an euclidean metric.
----@field register_node fun(name: string, node_definition: NodeDef): nil
-
----Node Timers: a high resolution persistent per-node timer. Can be gotten via `minetest.get_node_timer(pos)`.
----@class NodeTimerRef
----@field set fun(self: NodeTimerRef, timeout: integer|number, elapsed: integer|number): nil Set a timer's state. `timeout` is in seconds, and supports fractional values (0.1 etc). `elapsed` is in seconds, and supports fractional values (0.1 etc). Will trigger the node's `on_timer` function after `(timeout - elapsed)` seconds.
----@field start fun(self: NodeTimerRef, timeout: integer|number): nil Start a timer. Equivalent to `set(timeout,0)`.
----@field stop fun(): nil Stops the timer
----@field get_timeout fun(): number|integer Returns current timeout in seconds.
----@field get_elapsed fun(): number|integer Returns current elapsed time in seconds.
----@field is_started fun(): boolean Returns boolean state of timer. Returns `true` if timer is started, otherwise `false`.
-
----A raycast on the map. It works with selection boxes. The map is loaded as the ray advances. If the map is modified after the `Raycast` is created, the changes may or may not have an effect on the object.
----@class Raycast
----@field next fun(): PointedThingDef Returns a `pointed_thing` with exact pointing location. Returns the next thing pointed by the ray or nil.
-
----Entity definition
----@class EntityDef
----@field initial_properties ObjectProperties A table of object properties. The properties in this table are applied to the object once when it is spawned. `dtime_s` is the time passed since the object was unloaded, which can be used for updating the entity state.
----@field on_activate fun(self: table, staticdata: string, dtime_s: integer|number) Function receive a "luaentity" table as `self`. Called when the object is instantiated.
----@field on_deactivate fun(self: table, removal: boolean): nil Function receive a "luaentity" table as `self`. Called when the object is about to get removed or unloaded. `removal`: boolean indicating whether the object is about to get removed. Calling `object:remove()` on an active object will call this with `removal=true`. The mapblock the entity resides in being unloaded will call this with `removal=false`. Note that this won't be called if the object hasn't been activated in the first place. In particular, `minetest.clear_objects({mode = "full"})` won't call this, whereas `minetest.clear_objects({mode = "quick"})` might call this.
----@field on_step fun(self: table, dtime: integer|number, moveresult?: table) Function receive a "luaentity" table as `self`. Called on every server tick, after movement and collision processing. `dtime`: elapsed time since last call. `moveresult`: table with collision info (only available if physical=true).
----@field on_punch fun(self: table, puncher: ObjectRef|nil, time_from_last_punch: number|integer|nil, tool_capabilities: ToolCapabilitiesDef|nil, dir: Vector, damage: number|integer): boolean|nil Function receive a "luaentity" table as `self`. Called when somebody punches the object. Note that you probably want to handle most punches using the automatic armor group system. Can return `true` to prevent the default damage mechanism.
----@field on_death fun(self: table, killer: ObjectRef|nil): nil Function receive a "luaentity" table as `self`. Called when the object dies.
----@field on_rightclick fun(self: table, clicker: ObjectRef): nil Function receive a "luaentity" table as `self`. Called when `clicker` pressed the 'place/use' key while pointing to the object (not neccessarily an actual rightclick). `clicker`: an `ObjectRef` (may or may not be a player)
----@field on_attach_child fun(self: table, child: ObjectRef): nil Function receive a "luaentity" table as `self`. `child`: an `ObjectRef` of the child that attaches
----@field on_detach_child fun(self: table, child: ObjectRef): nil Function receive a "luaentity" table as `self`. `child`: an `ObjectRef` of the child that detaches
----@field on_detach fun(self: table, parent: ObjectRef|nil) Function receive a "luaentity" table as `self`. `parent`: an `ObjectRef` (can be `nil`) from where it got detached. This happens before the parent object is removed from the world.
----@field get_staticdata fun(self: table) Function receive a "luaentity" table as `self`. Should return a string that will be passed to `on_activate` when the object is instantiated the next time.
-
----Entity definition
----@class ObjectProperties
-
----Minetest settings
----@class MinetestSettings
----@field get fun(self: MinetestSettings, key: string): string|number|integer Returns a value
----@field get_bool fun(self: MinetestSettings, key: string, default?: boolean): boolean|nil Returns a boolean. `default` is the value returned if `key` is not found. Returns `nil` if `key` is not found and `default` not specified.
----@field get_np_group fun(self: MinetestSettings, key: string): table Returns a NoiseParams table
----@field get_flags fun(self: MinetestSettings, key: string): table Returns `{flag = true/false, ...}` according to the set flags. Is currently limited to mapgen flags `mg_flags` and mapgen-specific flags like `mgv5_spflags`.
----@field set fun(self: MinetestSettings, key: string, value: string|integer|number): nil 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`).
----@field set_bool fun(self: MinetestSettings, key: string, value: boolean): nil 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`).
----@field set_np_group fun(self: MinetestSettings, key: string, value: table): nil `value` is a NoiseParams table.
----@field remove fun(self: MinetestSettings, key: string): boolean Returns a boolean (`true` for success)
----@field get_names fun(): table Returns `{key1,...}`
----@field write fun(): boolean Returns a boolean (`true` for success). Writes changes to file.
----@field to_table fun(): table Returns `{[key1]=value1,...}`
-
---- Sound parameters.
---- Looped sounds must either be connected to an object or played locationless to one player using `to_player = name`. A positional sound will only be heard by players that are within `max_hear_distance` of the sound position, at the start of the sound. `exclude_player = name` can be applied to locationless, positional and object-bound sounds to exclude a single player from hearing them.
----@class SoundParamDef
----@field to_player string Name
----@field gain number|integer
----@field fade number|integer Change to a value > 0 to fade the sound in
----@field pitch number|integer
----@field loop boolean
----@field pos Vector
----@field max_hear_distance number|integer
----@field object ObjectRef
----@field exclude_player string Name
-
---- ParticleSpawner definition
----@class ParticlespawnerDef
----@field amount number|integer Number of particles spawned over the time period `time`.
----@field time number|integer Lifespan of spawner in seconds. If time is 0 spawner has infinite lifespan and spawns the `amount` on a per-second basis.
----@field collisiondetection boolean If true collide with `walkable` nodes and, depending on the `object_collision` field, objects too.
----@field collision_removal boolean If true particles are removed when they collide. Requires collisiondetection = true to have any effect.
----@field object_collision boolean If true particles collide with objects that are defined as `physical = true,` and `collide_with_objects = true,`. Requires collisiondetection = true to have any effect.
----@field attached ObjectRef If defined, particle positions, velocities and accelerations are relative to this object's position and yaw
----@field vertical boolean If true face player using y axis only
----@field texture string The texture of the particle. e,g, `"image.png"`
----@field playername string Optional, if specified spawns particles only on the player's client
----@field animation TileAnimationDef Optional, specifies how to animate the particles' texture. v5.6.0 and later: set length to -1 to sychronize the length of the animation with the expiration time of individual particles. (-2 causes the animation to be played twice, and so on)
----@field glow number|integer Optional, specify particle self-luminescence in darkness. Values 0-14.
----@field node table<string, string|number|integer> e.g. `{name = "ignore", param2 = 0}`. Optional, if specified the particles will have the same appearance as node dig particles for the given node. Texture` and `animation` will be ignored if this is set.
----@field node_tile number|integer Optional, only valid in combination with `node`. If set to a valid number 1-6, specifies the tile from which the particle texture is picked. Otherwise, the default behavior is used. (currently: any random tile)
----@field minpos Vector Legacy definition field
----@field maxpos Vector Legacy definition field
----@field minvel Vector Legacy definition field
----@field maxvel Vector Legacy definition field
----@field minacc Vector Legacy definition field
----@field maxacc Vector Legacy definition field
----@field minexptime number|integer Legacy definition field
----@field maxexptime number|integer Legacy definition field
----@field minsize number|integer Legacy definition field
----@field maxsize number|integer Legacy definition field
----@field pos number|integer|Vector|ParticlespawnerPosDef As `number`: absolute value - all components of every particle's position vector will be set to this. As `Vector`: vec3 - all particles will appear at this exact position throughout the lifetime of the particlespawner. As `ParticlespawnerPosDef`: vec3 range - the particle will appear at a position that is picked at random from within a cubic range.
-
---- ParticleSpawner pos definition
----@class ParticlespawnerPosDef
----@field min Vector The minimum value this property will be set to in particles spawned by the generator.
----@field max Vector The maximum value this property will be set to in particles spawned by the generator.
----@field bias number|integer When `bias` is 0, all random values are exactly as likely as any other. When it is positive, the higher it is, the more likely values will appear towards the minimum end of the allowed spectrum. When it is negative, the lower it is, the more likely values will appear towards the maximum end of the allowed spectrum. The curve is exponential and there is no particular maximum or minimum value.
----@field pos_tween ParticlespawnerPosTweenDef A tween table should consist of a list of frames in the same form as the untweened pos property above, which the engine will interpolate between, and optionally a number of properties that control how the interpolation takes place. Currently **only two frames**, the first and the last, are used, but extra frames are accepted for the sake of forward compatibility. Any of the above definition styles can be used here as well in any combination supported by the property type.
-
---- ParticleSpawner pos_tween definition
----@class ParticlespawnerPosTweenDef
----@field style string e.g. "fwd":  linear animation from first to last frame (default), "rev": linear animation from last to first frame, "pulse": linear animation from first to last then back to first again, "flicker": like "pulse", but slightly randomized to add a bit of stutter
----@field reps number|integer Number of times the animation is played over the particle's lifespan
----@field start number|integer  Point in the spawner's lifespan at which the animation begins. 0 is the very beginning, 1 is the very end.
----@field frames number|integer|Vector|ParticlespawnerPosDef Frames can be defined in a number of different ways, depending on the underlying type of the property. For now, all but the first and last frame are ignored.
-
---- Tile animation definition
----@class TileAnimationDef
----@field type string e.g. "vertical_frames",  "sheet_2d"
----@field aspect_w number|integer Width of a frame in pixels
----@field aspect_h number|integer Height of a frame in pixels
----@field length number|integer e.g. 3.0 Full loop length, 0.5 Length of a single frame
-
---- Job table
----@class JobTable
----@field cancel fun(self: JobTable) Cancels the job function from being called
-
----Minetest item definition. Used by `minetest.register_node`, `minetest.register_craftitem`, and `minetest.register_tool`.
----Add your own custom fields. By convention, all custom field names. Should start with `_` to avoid naming collisions with future engine usage.
----@class ItemDef
----@field description string Can contain new lines. "\n" has to be used as new line character.
----@field short_description string|nil Must not contain new lines. Defaults to nil.
----@field groups table<string, string|number|integer|boolean> key = name, value = rating; rating = <number>. If rating not applicable, use 1. e.g. `{wool = 1, fluffy = 3}` `{soil = 2, outerspace = 1, crumbly = 1}` `{bendy = 2, snappy = 1}` {hard = 1, metal = 1, spikes = 1}
----@field inventory_image string Texture shown in the inventory GUI. Defaults to a 3D rendering of the node if left empty.
----@field inventory_overlay string An overlay texture which is not affected by colorization
----@field wield_image string Texture shown when item is held in hand. Defaults to a 3D rendering of the node if left empty.
----@field wield_overlay string Like inventory_overlay but only used in the same situation as wield_image
----@field wield_scale table<string, number|integer> Scale for the item when held in hand
----@field palette string An image file containing the palette of a node. You can set the currently used color as the "palette_index" field of the item stack metadata. The palette is always stretched to fit indices between 0 and 255, to ensure compatibility with "colorfacedir" (and similar) nodes.
----@field color string Color the item is colorized with. The palette overrides this.
----@field stack_max integer|number Maximum amount of items that can be in a single stack.
----@field range integer|number Range of node and object pointing that is possible with this item held.
----@field liquids_pointable boolean If true, item can point to all liquid nodes (`liquidtype ~= "none"`), even those for which `pointable = false`
----@field light_source integer|number When used for nodes: Defines amount of light emitted by node. Otherwise: Defines texture glow when viewed as a dropped item. To set the maximum (14), use the value 'minetest.LIGHT_MAX'. A value outside the range 0 to minetest.LIGHT_MAX causes undefined behavior.
----@field tool_capabilities ToolCapabilitiesDef
----@field node_placement_prediction string|nil If nil and item is node, prediction is made automatically. If nil and item is not a node, no prediction is made. If "" and item is anything, no prediction is made. Otherwise should be name of node which the client immediately places on ground when the player places the item. Server will always update with actual result shortly.
----@field node_dig_prediction string if "", no prediction is made. if "air", node is removed. Otherwise should be name of node which the client immediately places upon digging. Server will always update with actual result shortly.
----@field sound SoundDef
----@field on_place fun(itemstack: ItemStack, placer: ObjectRef|nil, pointed_thing: PointedThingDef): ItemStack|nil When the 'place' key was pressed with the item in hand and a node was pointed at. Shall place item and return the leftover itemstack or nil to not modify the inventory. The placer may be any ObjectRef or nil. default: minetest.item_place
----@field on_secondary_use fun(itemstack: ItemStack, user: ObjectRef|nil, pointed_thing: PointedThingDef): ItemStack|nil Same as on_place but called when not pointing at a node. Function must return either nil if inventory shall not be modified, or an itemstack to replace the original itemstack. The user may be any ObjectRef or nil. default: nil
----@field on_drop fun(itemstack: ItemStack, dropper: ObjectRef|nil, pos: Vector): ItemStack Shall drop item and return the leftover itemstack. The dropper may be any ObjectRef or nil. default: minetest.item_drop
----@field on_pickup fun(itemstack: ItemStack, picker: ObjectRef|nil, pointed_thing?: PointedThingDef, time_from_last_punch?: number|integer, rest?: any): ItemStack|nil Called when a dropped item is punched by a player. Shall pick-up the item and return the leftover itemstack or nil to not modify the dropped item. `rest` are other parameters from `luaentity:on_punch`. default: `minetest.item_pickup`
----@field on_use fun(itemstack: ItemStack, user: ObjectRef|nil, pointed_thing: PointedThingDef): ItemStack|nil default: nil. When user pressed the 'punch/mine' key with the item in hand. Function must return either nil if inventory shall not be modified, or an itemstack to replace the original itemstack. e.g. itemstack:take_item(); return itemstack. Otherwise, the function is free to do what it wants. The user may be any ObjectRef or nil. The default functions handle regular use cases.
----@field after_use fun(itemstack: ItemStack, user: ObjectRef|nil, node: NodeDef, digparams: DigParamsDef): ItemStack|nil default: nil. If defined, should return an itemstack and will be called instead of wearing out the item (if tool). If returns nil, does nothing.
-
----Tool capabilities definition
----@class ToolCapabilitiesDef
----@field full_punch_interval number|integer
----@field max_drop_level number|integer
----@field groupcaps GroupCapsDef
----@field damage_groups table<string, number|integer> Damage values must be between -32768 and 32767 (2^15)
----@field punch_attack_uses number|integer|nil Amount of uses this tool has for attacking players and entities by punching them (0 = infinite uses). For compatibility, this is automatically set from the first suitable groupcap using the forumla "uses * 3^(maxlevel - 1)". It is recommend to set this explicitly instead of relying on the fallback behavior.
-
----Known damage and digging time defining groups
----@class GroupCapsDef
----@field crumbly GroupCapsItemDef dirt, sand
----@field cracky GroupCapsItemDef tough but crackable stuff like stone.
----@field snappy GroupCapsItemDef something that can be cut using things like scissors, shears, bolt cutters and the like, e.g. leaves, small plants, wire, sheets of metal
----@field choppy GroupCapsItemDef something that can be cut using force; e.g. trees, wooden planks
----@field fleshy GroupCapsItemDef Living things like animals and the player. This could imply some blood effects when hitting.
----@field explody GroupCapsItemDef Especially prone to explosions
----@field oddly_breakable_by_hand GroupCapsItemDef Can be added to nodes that shouldn't logically be breakable by the hand but are. Somewhat similar to `dig_immediate`, but times are more like `{[1]=3.50,[2]=2.00,[3]=0.70}` and this does not override the digging speed of an item if it can dig at a faster speed than this suggests for the hand.
-
----Known damage and digging time defining groups
----@class GroupCapsItemDef
----@field maxlevel number|integer Tells what is the maximum level of a node of this group that the item will be able to dig.
----@field uses number|integer Tools only. Determines how many uses the tool has when it is used for digging a node, of this group, of the maximum level. The maximum supported number of uses is 65535. The special number 0 is used for infinite uses. For lower leveled nodes, the use count is multiplied by `3^leveldiff`. `leveldiff` is the difference of the tool's `maxlevel` `groupcaps` and the node's `level` group. The node cannot be dug if `leveldiff` is less than zero.
----@field times table<number|integer, number|integer> List of digging times for different ratings of the group, for nodes of the maximum level. For example, as a Lua table, `times={[2]=2.00, [3]=0.70}`. This would result in the item to be able to dig nodes that have a rating of `2` or `3` for this group, and unable to dig the rating `1`, which is the toughest. Unless there is a matching group that enables digging otherwise. If the result digging time is 0, a delay of 0.15 seconds is added between digging nodes; If the player releases LMB after digging, this delay is set to 0, i.e. players can more quickly click the nodes away instead of holding LMB.
-
----Definition of item sounds to be played at various events.  All fields in this table are optional.
----@class SoundDef
----@field breaks SimpleSoundSpec|string When tool breaks due to wear. Ignored for non-tools
----@field eat SimpleSoundSpec|string When item is eaten with `minetest.do_item_eat`
----@field punch_use SimpleSoundSpec|string  When item is used with the 'punch/mine' key pointing at a node or entity
----@field punch_use_air SimpleSoundSpec|string When item is used with the 'punch/mine' key pointing at nothing (air)
-
----Specifies a sound name, gain (=volume) and pitch. This is either a string or a table. In string form, you just specify the sound name or the empty string for no sound.
----@class SimpleSoundSpec
----@field name string  Sound name.
----@field gain number|integer Volume (`1.0` = 100%). Optional and default to `1.0`.
----@field pitch number|integer Pitch (`1.0` = 100%). Optional and default to `1.0`.
-
----Pointed thing definition
----@class PointedThingDef
----@field type string e.g. `{type="nothing"}` `{type="node"}` `{type="object"}`
----@field under Vector Refers to the node position behind the pointed face.
----@field above Vector Refers to the node position in front of the pointed face.
----@field ref ObjectRef e.g. `{type="object", ref=ObjectRef}`
----@field intersection_point Vector Exact pointing location (currently only `Raycast` supports these field). The absolute world coordinates of the point on the selection box which is pointed at. May be in the selection box if the pointer is in the box too.
----@field box_id number|integer Exact pointing location (currently only `Raycast` supports these field). The ID of the pointed selection box (counting starts from 1).
----@field intersection_normal Vector Exact pointing location (currently only `Raycast` supports these field). Unit vector, points outwards of the selected selection box. This specifies which face is pointed at. Is a null vector `vector.zero()` when the pointer is inside the selection box.
-
----Dig params definition.
----@class DigParamsDef
-
----Node definition. Used by `minetest.register_node`.
----@class NodeDef
-
----Crafting recipes
----@class CraftRecipeDef
----@field type string (optional) specifies recipe type as shaped, e.g. "shaped", "shapeless", "toolrepair", "cooking", "fuel", default: "shaped"
----@field output string Itemstring of output itemstack (item counts >= 1 are allowed)
----@field recipe table<integer|number, string>[]|string A 2-dimensional matrix of items, with a width *w* and height *h*. *w* and *h* are chosen by you, they don't have to be equal but must be at least 1. The matrix is specified as a table containing tables containing itemnames. The inner tables are the rows. There must be *h* tables, specified from the top to the bottom row. Values inside of the inner table are the columns. Each inner table must contain a list of *w* items, specified from left to right. Empty slots *must* be filled with the empty string.
----@field replacements string[] (optional) Allows you to replace input items with some other items when something is crafted. Provided as a list of item pairs of the form `{ old_item, new_item }` where `old_item` is the input item to replace (same syntax as for a regular input slot; groups are allowed) and `new_item` is an itemstring for the item stack it will become. When the output is crafted, Minetest iterates through the list of input items if the crafting grid. For each input item stack, it checks if it matches with an `old_item` in the item pair list. If it matches, the item will be replaced. Also, this item pair will *not* be applied again for the remaining items. If it does not match, the item is consumed (reduced by 1) normally. The `new_item` will appear in one of 3 places:  Crafting grid, if the input stack size was exactly 1, Player inventory, if input stack size was larger, Drops as item entity, if it fits neither in craft grid or inventory.
----@field additional_wear number|integer For `{type = "toolrepair"}` only. Adds a shapeless recipe for *every* tool that doesn't have the `disable_repair=1` group. If this recipe is used, repairing is possible with any crafting grid with at least 2 slots. The player can put 2 equal tools in the craft grid to get one "repaired" tool back. The wear of the output is determined by the wear of both tools, plus a 'repair bonus' given by `additional_wear`. To reduce the wear (i.e. 'repair'), you want `additional_wear` to be negative. The formula used to calculate the resulting wear is: 65536 * (1 - ( (1 - tool_1_wear) + (1 - tool_2_wear) + additional_wear )) The result is rounded and can't be lower than 0. If the result is 65536 or higher, no crafting is possible.
----@field cooktime number|integer For `{type = "cooking"}` only. (optional) Time it takes to cook this item, in seconds. A floating-point number. (default: 3.0)
----@field burntime number|integer For `{type = "fuel"}` only. (optional) Burning time this item provides, in seconds. A floating-point number. (default: 1.0)
-
----Minetest game default mod
----@class MtgDefault
----@field node_sound_leaves_defaults fun(): SoundDef

types/mtg-creative.type.lua

@@ -0,0 +1,5 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Minetest game creative mod
+---@class MtgCreative
+---@field is_enabled_for fun(name: string): boolean Returning `true` means that Creative Mode is enabled for player `name`. `name` will be `""` for non-players or if the player is unknown. By default, this function returns `true` if the setting `creative_mode` is `true` and `false` otherwise.

types/mtg-default.type.lua

@@ -0,0 +1,37 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Minetest game default mod
+---@class MtgDefault
+---@field LIGHT_MAX number|integer The maximum light level. Maximum light to grow.
+---@field can_grow fun(pos: Vector): boolean Grow trees from saplings
+---@field grow_new_apple_tree fun(pos: Vector): nil
+---@field grow_new_jungle_tree fun(pos: Vector): nil
+---@field grow_new_emergent_jungle_tree fun(pos: Vector): nil
+---@field grow_new_acacia_tree fun(pos: Vector): nil
+---@field grow_new_aspen_tree fun(pos: Vector): nil
+---@field grow_new_snowy_pine_tree fun(pos: Vector): nil
+---@field grow_new_pine_tree fun(pos: Vector): nil
+---@field grow_bush fun(pos: Vector): nil
+---@field grow_acacia_bush fun(pos: Vector): nil
+---@field grow_pine_bush fun(pos: Vector): nil
+---@field grow_blueberry_bush fun(pos: Vector): nil
+---@field grow_papyrus fun(pos: Vector, node: NodeDef): nil
+---@field grow_large_cactus fun(pos: Vector, node: NodeDef): nil
+---@field sapling_on_place fun(itemstack: ItemStack, placer: ObjectRef, pointed_thing: PointedThingDef, sapling_name: string, minp_relative: Vector, maxp_relative: Vector, interval: number): nil Sapling 'on place' function to check protection of node and resulting tree volume
+---@field register_leafdecay fun(def: RegisterLeafdecayDef): nil
+---@field after_place_leaves fun(pos: Vector, placer: ObjectRef, itemstack?: ItemStack, pointed_thing?: PointedThingDef): nil Prevent decay of placed leaves
+---@field node_sound_defaults fun(table?: NodeSoundDef): NodeSoundDef
+---@field node_sound_stone_defaults fun(table?: NodeSoundDef): NodeSoundDef
+---@field node_sound_dirt_defaults fun(table?: NodeSoundDef): NodeSoundDef
+---@field node_sound_sand_defaults fun(table?: NodeSoundDef): NodeSoundDef
+---@field node_sound_wood_defaults fun(table?: NodeSoundDef): NodeSoundDef
+---@field node_sound_leaves_defaults fun(table?: NodeSoundDef): NodeSoundDef
+---@field node_sound_glass_defaults fun(table?: NodeSoundDef): NodeSoundDef
+---@field node_sound_metal_defaults fun(table?: NodeSoundDef): NodeSoundDef
+---@field node_sound_ice_defaults fun(table?: NodeSoundDef): NodeSoundDef
+
+--- Leaf decay definition
+---@class RegisterLeafdecayDef
+---@field trunks string[]
+---@field leaves string[]
+---@field radius number

types/mtg-dungeon-loot.type.lua

@@ -0,0 +1,14 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Minetest game dungeon loot mod API
+---@class MtgDungeonLoot
+---@field register fun(loot_definition: MtgDungeonLootDef): nil Registers one or more loot items, `def` Can be a single loot_definition or a list of them.
+---@field registered_loot table Table of all registered loot, not to be modified manually
+
+---Loot definition
+---@class MtgDungeonLootDef
+---@field name string
+---@field chance number chance value from 0.0 to 1.0 that the item will appear in the chest when chosen, Due to an extra step in the selection process, 0.5 does not(!) mean that on average every second chest will have this item
+---@field count number[]|nil table with minimum and maximum amounts of this item, optional, defaults to always single item
+---@field y number[]|nil table with minimum and maximum heights this item can be found at, optional, defaults to no height restrictions
+---@field types string[]|nil table with types of dungeons this item can be found in supported types: "normal" (the cobble/mossycobble one), "sandstone", "desert" and "ice", optional, defaults to no type restrictions

types/mtg-farming.type.lua

@@ -0,0 +1,10 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Minetest game farming mod
+
+----Node definition. Used by `minetest.register_node`.
+---@class NodeDefMtgFarming
+---@field fertility string[]|nil Used in default farming mod, defines biome name list where plants can grow
+---@field steps number How many steps the plant has to grow, until it can be harvested
+---@field minlight number Minimum light to grow
+---@field maxlight number Maximum light to grow

types/mtg-screwdriver.type.lua

@@ -0,0 +1,5 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Minetest game screwdriver mod
+---@class MtgScrewdriver
+---@field disallow fun(): boolean Returns `false`

types/mtg-stairs.type.lua

@@ -0,0 +1,5 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Minetest game stairs mod
+---@class MtgStairs
+---@field register_stair_and_slab fun(subname: string, recipeitem?: string, groups: GroupCapsDef, images: NodeTilesDef, desc_stair: string, desc_slab: string, sounds: NodeSoundDef, worldaligntex?: boolean, desc_stair_inner?: string, desc_stair_outer?: string): nil `subname`: Basically the material name (e.g. cobble) used for the stair name. Nodename pattern: "stairs:stair_subname", `recipeitem`: Item used in the craft recipe, e.g. "default:cobble", may be `nil`, `groups`: damage and digging time defining groups, `worldaligntex`: A bool to set all textures world-aligned. Default false.

types/node.type.lua

@@ -0,0 +1,24 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---@alias NodeDef NodeDefAbstract | NodeDefMtgFarming
+
+---Node definition. Used by `minetest.register_node`.
+---@class NodeDefAbstract
+---@field name string
+---@field next_plant string|nil
+---@field liquidtype 'none'|'source'|'flowing' specifies liquid flowing physics, "none": no liquid flowing physics, "source": spawns flowing liquid nodes at all 4 sides and below; recommended drawtype: "liquid". "flowing": spawned from source, spawns more flowing liquid nodes around it until `liquid_range` is reached; will drain out without a source; recommended drawtype: "flowingliquid". If it's "source" or "flowing" and `liquid_range > 0`, then both `liquid_alternative_*` fields must be specified
+---@field on_rightclick fun(pos: Vector, node: NodeDef, clicker: ObjectRef, itemstack: ItemStack, pointed_thing?: PointedThingDef): ItemStack default: nil, Called when clicker (an ObjectRef) used the 'place/build' key not neccessarily an actual rightclick) while pointing at the node at pos with 'node' being the node table. itemstack will hold clicker's wielded item. Shall return the leftover itemstack. Note: pointed_thing can be nil, if a mod calls this function. This function does not get triggered by clients <=0.4.16 if the "formspec" node metadata field is set.
+---@field place_param2 number Value for param2 that is set when player places node
+---@field param2 number Value for param2 that is set when player places node
+---@field buildable_to boolean If true, placed nodes can replace this node. default: `false`
+---@field tiles string|NodeTilesDef Textures of node; +Y, -Y, +X, -X, +Z, -Z. List can be shortened to needed length.
+---@field sound NodeSoundDef Definition of node sounds to be played at various events.
+
+---Textures of node; +Y, -Y, +X, -X, +Z, -Z. List can be shortened to needed length.
+---@class NodeTilesDef
+---@field name string
+---@field animation TileAnimationDef
+---@field backface_culling boolean backface culling enabled by default for most nodes
+---@field align_style 'node'|'world'|'user' align style determines whether the texture will be rotated with the node or kept aligned with its surroundings. "user" means that client setting will be used, similar to `glasslike_framed_optional`. Note: supported by solid nodes and nodeboxes only.
+---@field scale number|integer scale is used to make texture span several (exactly `scale`) nodes, instead of just one, in each direction. Works for world-aligned textures only. Note that as the effect is applied on per-mapblock basis, `16` should be equally divisible by `scale` or you may get wrong results.
+---@field color ColorSpec the texture's color will be multiplied with this color. the tile's color overrides the owning node's color in all cases.

types/nodetimer.type.lua

@@ -0,0 +1,11 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Node Timers: a high resolution persistent per-node timer. Can be gotten via `minetest.get_node_timer(pos)`.
+---@class NodeTimerRef
+---@field set fun(self: NodeTimerRef, timeout: integer|number, elapsed: integer|number): nil Set a timer's state. `timeout` is in seconds, and supports fractional values (0.1 etc). `elapsed` is in seconds, and supports fractional values (0.1 etc). Will trigger the node's `on_timer` function after `(timeout - elapsed)` seconds.
+---@field start fun(self: NodeTimerRef, timeout: integer|number): nil Start a timer. Equivalent to `set(timeout,0)`.
+---@field stop fun(): nil Stops the timer
+---@field get_timeout fun(): number|integer Returns current timeout in seconds.
+---@field get_elapsed fun(): number|integer Returns current elapsed time in seconds.
+---@field is_started fun(): boolean Returns boolean state of timer. Returns `true` if timer is started, otherwise `false`.
+---@field get_meta fun(pos: Vector): MetaDataRef Get a `NodeMetaRef` at that position

types/object.type.lua

@@ -0,0 +1,35 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---@alias ObjectRef ObjectRefAbstract|ObjectRefLuaEntityRef
+
+---Moving things in the game are generally these.
+---This is basically a reference to a C++ `ServerActiveObject`.
+---@class ObjectRefAbstract
+---@field get_pos fun(): Vector Position of player
+---@field get_inventory fun(): InvRef|nil Returns an `InvRef` for players, otherwise returns `nil`
+---@field get_wield_index fun(): integer Returns the index of the wielded item
+---@field get_wielded_item fun(): ItemStack Returns an `ItemStack`
+---@field set_acceleration fun(self: ObjectRef, acc: Vector): nil
+---@field set_yaw fun(self: ObjectRef, yaw: integer|number): nil Sets the yaw in radians (heading).
+---@field get_player_name fun(self: ObjectRef): string Returns `""` if is not a player.
+---@field set_fov fun(self: ObjectRef, fov: number|integer, is_multiplier: boolean, transition_time: number|integer): nil Sets player's FOV. `fov`: FOV value. `is_multiplier`: Set to `true` if the FOV value is a multiplier. Defaults to `false`. `transition_time`: If defined, enables smooth FOV transition. Interpreted as the time (in seconds) to reach target FOV. If set to 0, FOV change is instantaneous. Defaults to 0. Set `fov` to 0 to clear FOV override.
+---@field get_hp fun(self: ObjectRef): number|integer Returns number of health points
+---@field is_player fun(self: ObjectRef): boolean returns true for players, false otherwise
+---@field get_luaentity fun(self: ObjectRef): table
+---@field get_armor_groups fun(self: ObjectRef): ObjectRefArmorGroups returns a table with the armor group ratings
+---@field punch fun(self: ObjectRef, puncher: ObjectRef, time_from_last_punch: integer|number, tool_capabilities: ToolCapabilitiesDef, direction: Vector|nil): nil
+---@field add_velocity fun(self: ObjectRef, vel: Vector): nil `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`. 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: 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 (see: physics overrides) will cause existing X/Z velocity to be reduced. Example: `add_velocity({x=0, y=6.5, z=0})` is equivalent to pressing the jump key (assuming default settings)
+---@field get_properties fun(self: ObjectRef): table Returns object property table
+---@field get_children fun(self: ObjectRef): ObjectRef[] Returns a list of ObjectRefs that are attached to the object.
+
+---Moving things in the game are generally these.
+---This is basically a reference to a C++ `ServerActiveObject`.
+---@class ObjectRefLuaEntityRef
+---@field set_velocity fun(self: ObjectRef, vel: Vector): nil `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
+---@field remove fun(): nil remove object, The object is removed after returning from Lua. However the `ObjectRef` itself instantly becomes unusable with all further method calls having no effect and returning `nil`.
+
+---`ObjectRef` armor groups
+---@class ObjectRefArmorGroups
+---@field immortal number|integer Skips all damage and breath handling for an object. This group will also hide the integrated HUD status bars for players. It is automatically set to all players when damage is disabled on the server and cannot be reset (subject to change).
+---@field fall_damage_add_percent number|integer Modifies the fall damage suffered by players when they hit the ground. It is analog to the node group with the same name. See the node group above for the exact calculation.
+---@field punch_operable number|integer For entities; disables the regular damage mechanism for players punching it by hand or a non-tool item, so that it can do something else than take damage.

types/particlespawner.type.lua

@@ -0,0 +1,49 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+--- ParticleSpawner definition
+---@class ParticlespawnerDef
+---@field amount number|integer Number of particles spawned over the time period `time`.
+---@field time number|integer Lifespan of spawner in seconds. If time is 0 spawner has infinite lifespan and spawns the `amount` on a per-second basis.
+---@field collisiondetection boolean If true collide with `walkable` nodes and, depending on the `object_collision` field, objects too.
+---@field collision_removal boolean If true particles are removed when they collide. Requires collisiondetection = true to have any effect.
+---@field object_collision boolean If true particles collide with objects that are defined as `physical = true,` and `collide_with_objects = true,`. Requires collisiondetection = true to have any effect.
+---@field attached ObjectRef If defined, particle positions, velocities and accelerations are relative to this object's position and yaw
+---@field vertical boolean If true face player using y axis only
+---@field texture string The texture of the particle. e,g, `"image.png"`
+---@field playername string Optional, if specified spawns particles only on the player's client
+---@field animation TileAnimationDef Optional, specifies how to animate the particles' texture. v5.6.0 and later: set length to -1 to sychronize the length of the animation with the expiration time of individual particles. (-2 causes the animation to be played twice, and so on)
+---@field glow number|integer Optional, specify particle self-luminescence in darkness. Values 0-14.
+---@field node table<string, string|number|integer> e.g. `{name = "ignore", param2 = 0}`. Optional, if specified the particles will have the same appearance as node dig particles for the given node. Texture` and `animation` will be ignored if this is set.
+---@field node_tile number|integer Optional, only valid in combination with `node`. If set to a valid number 1-6, specifies the tile from which the particle texture is picked. Otherwise, the default behavior is used. (currently: any random tile)
+---@field minpos Vector Legacy definition field
+---@field maxpos Vector Legacy definition field
+---@field minvel Vector Legacy definition field
+---@field maxvel Vector Legacy definition field
+---@field minacc Vector Legacy definition field
+---@field maxacc Vector Legacy definition field
+---@field minexptime number|integer Legacy definition field
+---@field maxexptime number|integer Legacy definition field
+---@field minsize number|integer Legacy definition field
+---@field maxsize number|integer Legacy definition field
+---@field pos number|integer|Vector|ParticlespawnerPosDef As `number`: absolute value - all components of every particle's position vector will be set to this. As `Vector`: vec3 - all particles will appear at this exact position throughout the lifetime of the particlespawner. As `ParticlespawnerPosDef`: vec3 range - the particle will appear at a position that is picked at random from within a cubic range.
+
+--- ParticleSpawner pos definition
+---@class ParticlespawnerPosDef
+---@field min Vector The minimum value this property will be set to in particles spawned by the generator.
+---@field max Vector The maximum value this property will be set to in particles spawned by the generator.
+---@field bias number|integer When `bias` is 0, all random values are exactly as likely as any other. When it is positive, the higher it is, the more likely values will appear towards the minimum end of the allowed spectrum. When it is negative, the lower it is, the more likely values will appear towards the maximum end of the allowed spectrum. The curve is exponential and there is no particular maximum or minimum value.
+---@field pos_tween ParticlespawnerPosTweenDef A tween table should consist of a list of frames in the same form as the untweened pos property above, which the engine will interpolate between, and optionally a number of properties that control how the interpolation takes place. Currently **only two frames**, the first and the last, are used, but extra frames are accepted for the sake of forward compatibility. Any of the above definition styles can be used here as well in any combination supported by the property type.
+
+--- ParticleSpawner pos_tween definition
+---@class ParticlespawnerPosTweenDef
+---@field style string e.g. "fwd":  linear animation from first to last frame (default), "rev": linear animation from last to first frame, "pulse": linear animation from first to last then back to first again, "flicker": like "pulse", but slightly randomized to add a bit of stutter
+---@field reps number|integer Number of times the animation is played over the particle's lifespan
+---@field start number|integer  Point in the spawner's lifespan at which the animation begins. 0 is the very beginning, 1 is the very end.
+---@field frames number|integer|Vector|ParticlespawnerPosDef Frames can be defined in a number of different ways, depending on the underlying type of the property. For now, all but the first and last frame are ignored.
+
+--- Tile animation definition
+---@class TileAnimationDef
+---@field type string e.g. "vertical_frames",  "sheet_2d"
+---@field aspect_w number|integer Width of a frame in pixels
+---@field aspect_h number|integer Height of a frame in pixels
+---@field length number|integer e.g. 3.0 Full loop length, 0.5 Length of a single frame

types/pointed-thing.type.lua

@@ -0,0 +1,11 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Pointed thing definition
+---@class PointedThingDef
+---@field type string e.g. `{type="nothing"}` `{type="node"}` `{type="object"}`
+---@field under Vector Refers to the node position behind the pointed face.
+---@field above Vector Refers to the node position in front of the pointed face.
+---@field ref ObjectRef e.g. `{type="object", ref=ObjectRef}`
+---@field intersection_point Vector Exact pointing location (currently only `Raycast` supports these field). The absolute world coordinates of the point on the selection box which is pointed at. May be in the selection box if the pointer is in the box too.
+---@field box_id number|integer Exact pointing location (currently only `Raycast` supports these field). The ID of the pointed selection box (counting starts from 1).
+---@field intersection_normal Vector Exact pointing location (currently only `Raycast` supports these field). Unit vector, points outwards of the selected selection box. This specifies which face is pointed at. Is a null vector `vector.zero()` when the pointer is inside the selection box.

types/raycast.type.lua

@@ -0,0 +1,5 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---A raycast on the map. It works with selection boxes. The map is loaded as the ray advances. If the map is modified after the `Raycast` is created, the changes may or may not have an effect on the object.
+---@class Raycast
+---@field next fun(): PointedThingDef Returns a `pointed_thing` with exact pointing location. Returns the next thing pointed by the ray or nil.

types/sound.type.lua

@@ -0,0 +1,26 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---Specifies a sound name, gain (=volume) and pitch. This is either a string or a table. In string form, you just specify the sound name or the empty string for no sound.
+---@class SimpleSoundSpec
+---@field name string  Sound name.
+---@field gain number|integer Volume (`1.0` = 100%). Optional and default to `1.0`.
+---@field pitch number|integer Pitch (`1.0` = 100%). Optional and default to `1.0`.
+
+--- Definition of node sounds to be played at various events.
+---@class NodeSoundDef
+---@field footstep SimpleSoundSpec  If walkable, played when object walks on it. If node is climbable or a liquid, played when object moves through it
+---@field dig SimpleSoundSpec|'__group' While digging node. If `"__group"`, then the sound will be `default_dig_<groupname>`, where `<groupname>` is the name of the item's digging group with the fastest digging time. In case of a tie, one of the sounds will be played (but we cannot predict which one) Default value: `"__group"`
+---@field dug SimpleSoundSpec Node was dug
+---@field place SimpleSoundSpec Node was placed. Also played after falling
+---@field place_failed SimpleSoundSpec When node placement failed. Note: This happens if the _built-in_ node placement failed. This sound will still be played if the node is placed in the `on_place` callback manually.
+---@field fall SimpleSoundSpec  When node starts to fall or is detached
+
+---Definition of item sounds to be played at various events.  All fields in this table are optional.
+---@class ItemSoundDef
+---@field breaks SimpleSoundSpec|string When tool breaks due to wear. Ignored for non-tools
+---@field eat SimpleSoundSpec|string When item is eaten with `minetest.do_item_eat`
+---@field punch_use SimpleSoundSpec|string  When item is used with the 'punch/mine' key pointing at a node or entity
+---@field punch_use_air SimpleSoundSpec|string When item is used with the 'punch/mine' key pointing at nothing (air)
+
+---Dig params definition.
+---@class DigParamsDef

types/string.type.lua

@@ -0,0 +1,7 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+---@alias string string|StringAbstract
+
+---String helpers
+---@class StringAbstract
+---@field split fun(self: string, str: string, separator?: string, include_empty?: boolean, max_splits?: number, sep_is_pattern?: boolean): table `separator`: string, default: `","`, `include_empty`: boolean, default: `false`, `max_splits`: number, if it's negative, splits aren't limited, default: `-1`, `sep_is_pattern`: boolean, it specifies whether separator is a plain string or a pattern (regex), default: `false`. e.g. `"a,b":split","` returns `{"a","b"}`

types/vector.type.lua

@@ -0,0 +1,15 @@
+---https://github.com/sumneko/lua-language-server/wiki
+
+------All `vector.*` functions allow vectors `{x = X, y = Y, z = Z}` without metatables. Returned vectors always have a metatable set.
+---@class Vector
+---@field x integer|number Pitch
+---@field y integer|number Yaw
+---@field z integer|number Roll
+---@field multiply fun(v: Vector, s: number|integer): Vector Returns a scaled vector. Deprecated: If `s` is a vector: Returns the Schur product.
+---@field subtract fun(v: Vector, x: number|integer|Vector): Vector Returns a vector. If `x` is a vector: Returns the difference of `v` subtracted by `x`. If `x` is a number: Subtracts `x` from each component of `v`.
+---@field add fun(v: Vector, x: number|integer|Vector): Vector Returns a vector. If `x` is a vector: Returns the sum of `v` and `x`. If `x` is a number: Adds `x` to each component of `v`.
+---@field normalize fun(v: Vector): Vector Returns a vector of length 1 with direction of vector `v`. If `v` has zero length, returns `(0, 0, 0)`.
+---@field distance fun(p1: Vector, p2: Vector): number|integer Returns zero or a positive number, the distance between `p1` and `p2`.
+---@field round fun(v: Vector): Vector Returns a vector, each dimension rounded to nearest integer. At a multiple of 0.5, rounds away from zero.
+---@field new fun(a, b?, c?): Vector Returns a new vector `(a, b, c)`.
+---@field direction fun(p1: Vector, p2: Vector): Vector Returns a vector of length 1 with direction `p1` to `p2`. If `p1` and `p2` are identical, returns `(0, 0, 0)`.