diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..f3eaa86 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,4 @@ +{ + "material-icon-theme.activeIconPack": "none", + "Lua.workspace.ignoreDir": [".vscode", "config.lua"] +} diff --git a/README.md b/README.md index e4ef934..1ca57cf 100644 --- a/README.md +++ b/README.md @@ -2,4 +2,4 @@ ## Target -- Minetest 7ffc0268dfd78647187554d6248015329e9f5d2d +- Minetest 5.6.0 diff --git a/aliases.lua b/aliases.lua deleted file mode 100644 index 230bdee..0000000 --- a/aliases.lua +++ /dev/null @@ -1,15 +0,0 @@ ----@meta - ----This adds an alias `alias` for the item called `original_name` ----@param alias string ----@param original_name string -function minetest.register_alias(alias, original_name) end - ----Same as `minetest.register_alias` but will unregister the alias if it exists ----@param alias string ----@param original_name string -function minetest.register_alias_force(alias, original_name) end - ----Map of registered aliases, indexed by name ----@type table -minetest.registered_aliases = {} diff --git a/api/after.lua b/api/after.lua index a6edb15..daebec3 100644 --- a/api/after.lua +++ b/api/after.lua @@ -1,10 +1,9 @@ ---@meta ---@class job -local job = {} - ---Cancels the job function from being called. -function job:cancel() end +---@field cancel fun(self: job) + ---Call the function `func` after `time` seconds, may be fractional ---@param time number diff --git a/api/bans.lua b/api/bans.lua index 717757e..a9c7b7c 100644 --- a/api/bans.lua +++ b/api/bans.lua @@ -2,11 +2,13 @@ ---Returns a list of all bans formatted as string. ---@return string +---@nodiscard function minetest.get_ban_list() end ---Returns list of bans matching IP address or name formatted as string. ---@param ip_or_name string ---@return string +---@nodiscard function minetest.get_ban_description(ip_or_name) end ---Ban the IP of a currently connected player diff --git a/api/callbacks.lua b/api/callbacks.lua index ccd683f..b6230c0 100644 --- a/api/callbacks.lua +++ b/api/callbacks.lua @@ -89,7 +89,7 @@ minetest.registered_on_newplayers = {} ---Note: This callback is invoked even if the punched player is dead. --- ---Callback should return `true` to prevent the default damage mechanism. ----@param func fun(player: ObjectRef, hitter: ObjectRef, time_from_last_punch: number, tool_capabilities: tool_capabilities, dir: Vector, damage: number): boolean +---@param func fun(player: ObjectRef, hitter: ObjectRef, time_from_last_punch: number, tool_capabilities: tool_capabilities, dir: Vector, damage: number): boolean? function minetest.register_on_punchplayer(func) end ---Map of registered on_punchplayer. @@ -107,7 +107,7 @@ minetest.registered_on_rightclickplayers = {} ---Register a function that will be called when a player is damaged or healed. ---@param func fun(player: ObjectRef, hp_change: integer, reason: PlayerHPChangeReason): integer?, boolean? ----@param modifier boolean When true, the function should return the actual `hp_change`. +---@param modifier? boolean When true, the function should return the actual `hp_change`. ---Note: modifiers only get a temporary `hp_change` that can be modified by later modifiers. --- ---Modifiers can return true as a second argument to stop the execution of further functions. @@ -132,7 +132,7 @@ minetest.registered_on_dieplayers = {} ---Called **before** repositioning of player occurs. --- ---Return `true` in func to disable regular player placement. ----@param func fun(player: ObjectRef): boolean +---@param func fun(player: ObjectRef): boolean? function minetest.register_on_respawnplayer(func) end ---Map of registered on_respawnplayer. @@ -162,7 +162,7 @@ minetest.registered_on_joinplayers = {} ---Register a function that will be called when a player leaves the game. --- ---`timed_out`: True for timeout, false for other reasons. ----@param func fun(player: ObjectRef, timed_out: boolean) +---@param func fun(player: ObjectRef, timed_out?: boolean) function minetest.register_on_leaveplayer(func) end ---Map of registered on_leaveplayer. @@ -247,7 +247,7 @@ minetest.registered_on_chatcommands = {} ---Newest functions are called first. --- ---If function returns `true`, remaining functions are not called. ----@param func fun(player: ObjectRef, formname: string, fields: table): boolean +---@param func fun(player: ObjectRef, formname: string, fields: table): boolean? function minetest.register_on_player_receive_fields(func) end ---Map of registered on_player_receive_fields. @@ -269,11 +269,11 @@ minetest.registered_on_crafts = {} ---Register a function that will be called before a player craft something to make the crafting prediction. --- ---Similar to `minetest.register_on_craft`. ----@param func fun(itemstack: ItemStack, player: ObjectRef, old_craft_grid: table, craft_inv: InvRef) +---@param func fun(itemstack: ItemStack, player: ObjectRef, old_craft_grid: table, craft_inv: InvRef): ItemStack? function minetest.register_craft_predict(func) end ---Map of registered craft_predicts. ----@type fun(itemstack: ItemStack, player: ObjectRef, old_craft_grid: table, craft_inv: InvRef)[] +---@type (fun(itemstack: ItemStack, player: ObjectRef, old_craft_grid: table, craft_inv: InvRef): ItemStack?)[] minetest.registered_craft_predicts = {} ---Determines how much of a stack may be taken, put or moved to a player inventory. @@ -288,11 +288,11 @@ minetest.registered_craft_predicts = {} ---Return a numeric value to limit the amount of items to be taken, put or moved. --- ---A value of `-1` for `take` will make the source stack infinite. ----@param func fun(player: ObjectRef, action: '"move"'|'"put"'|'"take"', inventory: InvRef, inventory_info: {from_list: string, to_list: string, from_index: integer, to_index: integer, count: integer}|{listname: string, index: integer, stack: ItemStack}): integer +---@param func fun(player: ObjectRef, action: '"move"'|'"put"'|'"take"', inventory: InvRef, inventory_info: {from_list: string, to_list: string, from_index: integer, to_index: integer, count: integer}|{listname: string, index: integer, stack: ItemStack}): integer? function minetest.register_allow_player_inventory_action(func) end ---Map of registered allow_player_inventory_action. ----@type (fun(player: ObjectRef, action: '"move"'|'"put"'|'"take"', inventory: InvRef, inventory_info: {from_list: string, to_list: string, from_index: integer, to_index: integer, count: integer}|{listname: string, index: integer, stack: ItemStack}): integer)[] +---@type (fun(player: ObjectRef, action: '"move"'|'"put"'|'"take"', inventory: InvRef, inventory_info: {from_list: string, to_list: string, from_index: integer, to_index: integer, count: integer}|{listname: string, index: integer, stack: ItemStack}): integer?)[] minetest.registered_allow_player_inventory_action = {} ---Called after a take, put or move event from/to/in a player inventory. @@ -380,3 +380,6 @@ function minetest.register_on_liquid_transformed(func) end ---Map of registered on_liquid_transformed. ---@type fun(pos_list: Vector[], node_list: node[])[] minetest.registered_on_liquid_transformed = {} + +---@type table +minetest.callback_origins = {} diff --git a/api/default_item_def.lua b/api/default_item_def.lua new file mode 100644 index 0000000..02c72fa --- /dev/null +++ b/api/default_item_def.lua @@ -0,0 +1,51 @@ +---@meta + +---Place item as a node. +---@param itemstack ItemStack +---@param placer ObjectRef +---@param pointed_thing pointed_thing +---@param param2? integer overrides `facedir` and wallmounted `param2` +---@param prevent_after_place? boolean if `true`, `after_place_node` is not called for the newly placed node to prevent a callback and placement loop +---@return ItemStack itemstack +---@return Vector? position the location the node was placed to. `nil` if nothing was placed. +function minetest.item_place_node(itemstack, placer, pointed_thing, param2, prevent_after_place) end + +---Place item as-is. +--- +---Returns the leftover itemstack +--- +---**Note**: This function is deprecated and will never be called. +---@param itemstack ItemStack +---@param placer ObjectRef +---@param pointed_thing pointed_thing +---@deprecated +function minetest.item_place_object(itemstack, placer, pointed_thing) end + +---Wrapper that calls `minetest.item_place_node` if appropriate. +--- +---Calls `on_rightclick` of `pointed_thing.under` if defined instead. +--- +---**Note**: is not called when wielded item overrides `on_place` +---@param itemstack ItemStack +---@param placer ObjectRef +---@param pointed_thing pointed_thing +---@param param2? integer overrides `facedir` and wallmounted `param2` +---@return ItemStack itemstack +---@return Vector? position the location the node was placed to. `nil` if nothing was placed. +function minetest.item_place(itemstack, placer, pointed_thing, param2) end + +---Drop the item. +--- +---Returns the leftover itemstack. +---@param itemstack ItemStack +---@param dropper ObjectRef +---@param pos Vector +---@return ItemStack +function minetest.item_drop(itemstack, dropper, pos) end + +---Returns `function(itemstack, user, pointed_thing)` as a function wrapper for `minetest.do_item_eat`. +---@param hp_change integer +---@param replace_with_item? string the itemstring which is added to the inventory. if the player is eating a stack, then `replace_with_item` goes to a different spot. +---@return fun(itemstack: ItemStack, user: ObjectRef, pos: Vector) +---@nodiscard +function minetest.item_eat(hp_change, replace_with_item) end diff --git a/api/default_node_def.lua b/api/default_node_def.lua new file mode 100644 index 0000000..2b48ec4 --- /dev/null +++ b/api/default_node_def.lua @@ -0,0 +1,16 @@ +---@meta + +---Calls functions registered by `minetest.register_on_punchnode()`. +---@param pos Vector +---@param node node +---@param puncher ObjectRef +---@param pointed_thing pointed_thing +function minetest.node_punch(pos, node, puncher, pointed_thing) end + +---Checks if node can be dug, puts item into inventory, removes node. +--- +---Calls functions registered by `minetest.registered_on_dignodes()`. +---@param pos Vector +---@param node node +---@param digger ObjectRef +function minetest.node_dig(pos, node, digger) end diff --git a/api/environment.lua b/api/environment.lua index 145d8c9..ef8c5ad 100644 --- a/api/environment.lua +++ b/api/environment.lua @@ -39,17 +39,20 @@ function minetest.remove_node(pos) end ---Returns `{name="ignore", param1=0, param2=0}` for unloaded areas. ---@param pos Vector ---@return node +---@nodiscard function minetest.get_node(pos) end ---Same as `minetest.get_node` but returns `nil` for unloaded areas. ---@param pos Vector ---@return node? +---@nodiscard function minetest.get_node_or_nil(pos) end ---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. ---@param pos Vector ---@param timeofday? number `nil` for current time, `0` for night, `0.5` for day ---@return integer? light Between `0` and `15`, `nil` if the area isn't loaded. +---@nodiscard function minetest.get_node_light(pos, timeofday) end ---Get the sunlight (or moonlight) value at pos at the given time of day. @@ -58,6 +61,7 @@ function minetest.get_node_light(pos, timeofday) end ---@param pos Vector ---@param timeofday? number `nil` for current time, `0` for night, `0.5` for day ---@return integer? light Between `0` and `15`, `nil` if the area isn't loaded. +---@nodiscard function minetest.get_natural_light(pos, timeofday) end ---Calculates the artificial light (light from e.g. torches) value from the `param1` value. @@ -65,6 +69,7 @@ function minetest.get_natural_light(pos, timeofday) end ---Currently it's the same as `math.floor(param1 / 16)`, except that it ensures compatibility. ---@param param1 integer The param1 value of a `paramtype = "light"` node. ---@return integer light Between `0` and `15`. +---@nodiscard function minetest.get_artificial_light(param1) end ---Place node with the same effects that a player would cause. (like calling `on_place` callbacks) @@ -95,16 +100,19 @@ function minetest.spawn_falling_node(pos) end ---@param pos1 Vector ---@param pos2 Vector ---@return Vector[] +---@nodiscard function minetest.find_nodes_with_meta(pos1, pos2) end ---Get a `NodeMetaRef` at that position. ---@param pos Vector ---@return NodeMetaRef +---@nodiscard function minetest.get_meta(pos) end ---Get a `NodeTimerRef` at that position. ---@param pos Vector ---@return NodeTimerRef +---@nodiscard function minetest.get_node_timer(pos) end --FIXME: staticdata @@ -129,12 +137,14 @@ function minetest.add_item(pos, item) end ---Get `ObjectRef` of player with name `name` or `nil` if player is not connected. ---@param name string ---@return ObjectRef? +---@nodiscard function minetest.get_player_by_name(name) end ---Returns a list of ObjectRefs. ---@param pos Vector ---@param radius number using an euclidean metric ---@return ObjectRef[] +---@nodiscard function minetest.get_objects_inside_radius(pos, radius) end ---Returns a list of ObjectRefs. @@ -143,6 +153,7 @@ function minetest.get_objects_inside_radius(pos, radius) end ---@param pos1 Vector ---@param pos2 Vector ---@return ObjectRef[] +---@nodiscard function minetest.get_objects_in_area(pos1, pos2) end ---Set time of day in the minetest world. @@ -151,16 +162,19 @@ function minetest.set_timeofday(val) end ---Get time of day in the minetest world. ---@return number +---@nodiscard function minetest.get_timeofday() end ---Returns the time, in seconds, since the world was created. ---@return integer +---@nodiscard function minetest.get_gametime() end ---Returns number days elapsed since world was created. --- ---Accounts for time changes. ---@return integer +---@nodiscard function minetest.get_day_count() end ---Find a node near specified position. @@ -169,6 +183,7 @@ function minetest.get_day_count() end ---@param nodenames string|string[] e.g. `{"ignore", "group:tree"}` or `"default:dirt"` ---@param search_center? boolean is an optional boolean (default: `false`). if true `pos` is also checked for the nodes ---@return Vector? +---@nodiscard function minetest.find_node_near(pos, radius, nodenames, search_center) end ---Find nodes in specified area. @@ -185,6 +200,7 @@ function minetest.find_node_near(pos, radius, nodenames, search_center) end ---@param grouped? boolean default `false` ---@return Vector[]|table ---@return table? +---@nodiscard function minetest.find_nodes_in_area(pos1, pos2, nodenames, grouped) end ---Find nodes under air in specified area. @@ -194,12 +210,14 @@ function minetest.find_nodes_in_area(pos1, pos2, nodenames, grouped) end ---@param pos2 Vector ---@param nodenames string|string[] e.g. `{"ignore", "group:tree"}` or `"default:dirt"` ---@return Vector[] +---@nodiscard function minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames) end ---Return world-specific perlin noise. --- ---The actual seed used is the noiseparams seed plus the world seed. ---@param noiseparams noise_params +---@nodiscard function minetest.get_perlin(noiseparams) end ---Return voxel manipulator object. @@ -208,6 +226,7 @@ function minetest.get_perlin(noiseparams) end ---@param pos1? Vector ---@param pos2? Vector ---@return VoxelManip +---@nodiscard function minetest.get_voxel_manip(pos1, pos2) end ---Set the types of on-generate notifications that should be collected. @@ -229,11 +248,13 @@ function minetest.set_gen_notify(flags, deco_ids) end ---Returns a flagstring and a table with the `deco_id`s. ---@return string ---@return unknown[] +---@nodiscard function minetest.get_gen_notify() end ---Returns the decoration ID number for the provided decoration name string, or `nil` on failure. ---@param decoration_name string ----@return unknown? +---@return number? +---@nodiscard function minetest.get_decoration_id(decoration_name) end ---@alias mapgen_object_name @@ -252,16 +273,22 @@ function minetest.get_decoration_id(decoration_name) end --- ---If the requested Mapgen object is unavailable, or `get_mapgen_object()` was called outside of an `on_generate()` callback, `nil` is returned. ---@param objectname mapgen_object_name +---@return VoxelManip|integer[] +---@return Vector? +---@return Vector? +---@nodiscard function minetest.get_mapgen_object(objectname) end ---Returns the heat at the position, or `nil` on failure. ---@param pos Vector ---@return number? +---@nodiscard function minetest.get_heat(pos) end ---Returns the humidity at the position, or `nil` on failure. ---@param pos Vector ---@return number? +---@nodiscard function minetest.get_humidity(pos) end ---Returns a table containing: @@ -272,11 +299,13 @@ function minetest.get_humidity(pos) end ---Returns `nil` on failure. ---@param pos Vector ---@return {biome: unknown, heat: number, humidity: number}? +---@nodiscard function minetest.get_biome_data(pos) end ---Returns the biome id, as used in the biomemap Mapgen object and returned by `minetest.get_biome_data(pos)`, for a given biome_name string. ---@param biome_name string ---@return unknown +---@nodiscard function minetest.get_biome_id(biome_name) end ---Returns the biome name string for the provided biome id, or `nil` on failure. @@ -284,6 +313,7 @@ function minetest.get_biome_id(biome_name) end ---If no biomes have been registered, such as in mgv6, returns `default`. ---@param biome_id unknown ---@return string|'"default"'|nil +---@nodiscard function minetest.get_biome_name(biome_id) end ---**DEPRECATED:** use `minetest.get_mapgen_setting(name)` instead. @@ -296,6 +326,7 @@ function minetest.get_biome_name(biome_id) end ---* `flags` ---@deprecated ---@return {mgname: string, seed: integer, chunksize: integer, water_level: integer, flags: string} +---@nodiscard function minetest.get_mapgen_params() end ---**DEPRECATED:** use `minetest.set_mapgen_setting(name, value, override)` instead. @@ -359,10 +390,12 @@ function minetest.set_mapgen_params(mapgen_params) end ---4) Settings set as the user config default ---@param name mapgen_settings|string ---@return string? +---@nodiscard function minetest.get_mapgen_setting(name) end ---Same as `minetest.get_mapgen_setting(name)`, but returns the value as a `NoiseParams` table if the setting `name` exists and is a valid `NoiseParams`. ---@return noise_params? +---@nodiscard function minetest.get_mapgen_setting_noiseparams(name) end ---Sets a mapgen param to `value`, and will take effect if the corresponding mapgen setting is not already present in map_meta.txt. @@ -392,6 +425,7 @@ function minetest.set_noiseparams(name, noiseparams, set_default) end ---Returns a table of the noiseparams for `name`. ---@param name string ---@return noise_params +---@nodiscard function minetest.get_noiseparams(name) end ---Generate all registered ores within the VoxelManip `vm` and in the area from `pos1` to `pos2`. @@ -415,7 +449,7 @@ function minetest.generate_decorations(vm, pos1, pos2) end ---Takes an optional table as an argument with the field `mode`. ---* mode = `"full"` : Load and go through every mapblock, clearing objects (default). ---* mode = `"quick"`: Clear objects immediately in loaded mapblocks, clear objects in unloaded mapblocks only when the mapblocks are next activated. ----@param options {mode: '"full"'|'"quick"'} +---@param options? {mode: '"full"'|'"quick"'} function minetest.clear_objects(options) end ---Load the mapblocks containing the area from `pos1` to `pos2`. @@ -445,7 +479,7 @@ function minetest.load_area(pos1, pos2) end ---* `param` is the user-defined parameter passed to emerge_area (or nil if the parameter was absent). ---@param pos1 Vector ---@param pos2 Vector ----@param callback? fun(blockpos: Vector, action: 0|1|2|3|4, calls_remaining: integer, param?: any) +---@param callback? fun(blockpos: Vector, action: emerge_status, calls_remaining: integer, param?: any) ---@param param? any function minetest.emerge_area(pos1, pos2, callback, param) end @@ -463,6 +497,7 @@ function minetest.delete_area(pos1, pos2) end ---@param pos2 Vector ---@return boolean ---@return Vector? +---@nodiscard function minetest.line_of_sight(pos1, pos2) end ---Returns table containing path that can be walked on @@ -484,8 +519,93 @@ function minetest.line_of_sight(pos1, pos2) end ---@param max_jump number maximum height difference to consider walkable ---@param max_drop number maximum height difference to consider droppable ---@param algorithm '"A*_noprefetch"'|'"A*"'|'"Dijkstra"' difference between `"A*"` and `"A*_noprefetch"` is that `"A*"` will pre-calculate the cost-data, the other will calculate it on-the-fly +---@return Vector[]? +---@nodiscard function minetest.find_path(pos1, pos2, searchdistance, max_jump, max_drop, algorithm) end +---@class tree_definition +---Initial tree axiom +---@field axiom string +---Rules set A +---@field rules_a string +---Rules set B +---@field rules_b string +---Rules set C +---@field rules_c string +---Rules set D +---@field rules_d string +---Trunk node name +---@field trunk string +---Leaves node name +---@field leaves string +---Secondary leaves node name +---@field leaves2 string +---Chance (0-100) to replace leaves with leaves2 +---@field leaves2_chance integer +---Angle in degrees +---@field angle integer +---Max amount of iterations, usually 2-5 +---@field iterations integer +---Factor to lower nr of iterations, usually 0-3 +---@field random_level number +---Type of trunk: 1 node, 2x2 nodes or 3x3 in cross shape +---@field trunk_type "'single'"|"'double'"|"'crossed'" +---true -> use thin (1 node) branches +---@field thin_branches boolean +---Fruit node name +---@field fruit string +---Chance (0-100) to replace leaves with fruit node +---@field fruit_chance integer +---Random seed, if no seed is provided, the engine will create one +---@field seed integer + +---Spawns L-system tree at given `pos` with definition in `treedef` table. +--- +---```lua +---pos = {x = 230, y = 20, z = 4} +---apple_tree = { +--- axiom = "FFFFFAFFBF", +--- rules_a = "[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]", +-- rules_b = "[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]", +--- trunk = "default:tree", +--- leaves = "default:leaves", +--- angle = 30, +--- iterations = 2, +--- random_level = 0, +--- trunk_type = "single", +--- thin_branches = true, +--- fruit_chance = 10, +--- fruit = "default:apple" +---} +---minetest.spawn_tree(pos, apple_tree) +---``` +--- +---**Key for special L-System symbols used in axioms:** +--- +---* `G`: move forward one unit with the pen up +---* `F`: move forward one unit with the pen down drawing trunks and branches +---* `f`: move forward one unit with the pen down drawing leaves (100% chance) +---* `T`: move forward one unit with the pen down drawing trunks only +---* `R`: move forward one unit with the pen down placing fruit +---* `A`: replace with rules set A +---* `B`: replace with rules set B +---* `C`: replace with rules set C +---* `D`: replace with rules set D +---* `a`: replace with rules set A, chance 90% +---* `b`: replace with rules set B, chance 80% +---* `c`: replace with rules set C, chance 70% +---* `d`: replace with rules set D, chance 60% +---* `+`: yaw the turtle right by `angle` parameter +---* `-`: yaw the turtle left by `angle` parameter +---* `&`: pitch the turtle down by `angle` parameter +---* `^`: pitch the turtle up by `angle` parameter +---* `/`: roll the turtle to the right by `angle` parameter +---* `*`: roll the turtle to the left by `angle` parameter +---* `[`: save in stack current state info +---* `]`: recover from stack state info +--- +---@param pos Vector +---@param treedef tree_definition function minetest.spawn_tree(pos, treedef) end ---Add node to liquid flow update queue. @@ -495,11 +615,13 @@ function minetest.transforming_liquid_add(pos) end ---Get max available level for leveled node. ---@param pos Vector ---@return integer +---@nodiscard function minetest.get_node_max_level(pos) end ---Get level of leveled node (water, snow). ---@param pos Vector ---@return integer +---@nodiscard function minetest.get_node_level(pos) end ---Set level of leveled node, default `level` equals `1` @@ -560,5 +682,6 @@ function minetest.check_for_falling(pos) end ---The spawn level is intentionally above terrain level to cope with full-node biome 'dust' nodes. ---@param x integer ---@param z integer ----@return integer +---@return integer? +---@nodiscard function minetest.get_spawn_level(x, z) end diff --git a/api/formspec.lua b/api/formspec.lua index 9dd85b2..1f15620 100644 --- a/api/formspec.lua +++ b/api/formspec.lua @@ -6,7 +6,7 @@ ---@param formspec string Formspec to display function minetest.show_formspec(playername, formname, formspec) end ----Close a formspec. * `playername`: name of player to close formspec +---Close a formspec. --- ---Calling `show_formspec(playername, formname, "")` is equal to this expression. --- diff --git a/api/helpers.lua b/api/helpers.lua index 8b66ac1..3a0ec37 100644 --- a/api/helpers.lua +++ b/api/helpers.lua @@ -174,3 +174,49 @@ function table.key_value_swap(t) end ---@param to? integer Defaults to `#table` ---@param random_func? function This function receives two integers as arguments and should return a random integer inclusively between them. Defaults to `math.random` function table.shuffle(table, from, to, random_func) end + +---Returns a position. +--- +---Returns the exact position on the surface of a pointed node. +---@param placer ObjectRef +---@param pointed_thing pointed_thing +---@return Vector +---@nodiscard +function minetest.pointed_thing_to_face_pos(placer, pointed_thing) end + +---Simulates a tool being used once and returns the added wear, such that, if only this function is used to calculate wear, the tool will break exactly after `uses` times of uses +---@param uses integer Number of times the tool can be used +---@param initial_wear? integer The initial wear the tool starts with (default: 0) +---@return integer +---@nodiscard +function minetest.get_tool_wear_after_use(uses, initial_wear) end + +---Simulates an item that digs a node. +--- +---Returns a table with the following fields: +--- +---* `diggable`: `true` if node can be dug, `false` otherwise. +---* `time`: Time it would take to dig the node. +---* `wear`: How much wear would be added to the tool (ignored for non-tools). +--- +---`time` and `wear` are meaningless if node's not diggable +---@param groups table Table of the node groups of the node that would be dug +---@param tool_capabilities tool_capabilities Tool capabilities table of the item +---@param wear? integer Amount of wear the tool starts with (default: 0) +---@return {diggable: boolean, time: number, wear: integer} +---@nodiscard +function minetest.get_dig_params(groups, tool_capabilities, wear) end + +---Simulates an item that punches an object. +--- +---Returns a table with the following fields: +--- +---* `hp`: How much damage the punch would cause (between `-65535` and `65535`). +---* `wear`: How much wear would be added to the tool (ignored for non-tools). +---@param groups table Damage groups of the object +---@param tool_capabilities tool_capabilities Tool capabilities table of the item +---@param time_from_last_punch? number Time in seconds since last punch action +---@param wear? integer Amount of wear the item starts with (default: 0) +---@return {hp: integer, wear: integer} +---@nodiscard +function minetest.get_hit_params(groups, tool_capabilities, time_from_last_punch, wear) end diff --git a/api/http.lua b/api/http.lua index 1e0093a..0856638 100644 --- a/api/http.lua +++ b/api/http.lua @@ -1,66 +1,41 @@ ---@meta ---@class HTTPRequest -local http_request = {} - ----@type string -http_request.url = nil - +---The URL +---@field url string ---Timeout for request to be completed in seconds. Default depends on engine settings. ----@type number -http_request.timeout = nil - +---@field timeout number ---The http method to use. Defaults to `"GET"`. ----@type '"GET"'|'"POST"'|'"PUT"'|'"DELETE"' -http_request.method = nil - +---@field method '"GET"'|'"POST"'|'"PUT"'|'"DELETE"' ---Data for the POST, PUT or DELETE request. --- ---Accepts both a string and a table. If a table is specified, encodes table as `x-www-form-urlencoded` key-value pairs. ----@type string|table -http_request.data = nil - +---@field data string|table ---Optional, if specified replaces the default minetest user agent with given string. ----@type string -http_request.user_agent = nil - +---@field user_agent string ---Optional, if specified adds additional headers to the HTTP request. --- ---You must make sure that the header strings follow HTTP specification ("Key: Value"). ----@type string[] -http_request.extra_headers = nil - +---@field extra_headers string[] ---Optional, if true performs a multipart HTTP request. --- ---Default is false. --- ---POST only, data must be array. ----@type boolean -http_request.multipart = nil +---@field multipart boolean ---@class HTTPRequestResult -local http_request_result = {} - ---If true, the request has finished (either succeeded, failed or timed out). ----@type boolean -http_request_result.completed = nil - +---@field completed boolean ---If true, the request was successful. ----@type boolean -http_request_result.succeeded = nil - +---@field succeeded boolean ---If true, the request timed out. ----@type boolean -http_request_result.timeout = nil - +---@field timeout boolean ---HTTP status code ----@type integer -http_request_result.code = nil - +---@field code integer ---Responce data. ----@type string -http_request_result.data = nil +---@field data string ---@class HTTPApiTable @@ -76,11 +51,13 @@ function httpapitable.fetch(req, callback) end ---Performs given request asynchronously and returns handle for `HTTPApiTable.fetch_async_get`. ---@param req HTTPRequest ---@return any +---@nodiscard function httpapitable.fetch_async(req) end ---Return response data for given asynchronous HTTP request. ---@param handle any ---@return HTTPRequestResult +---@nodiscard function httpapitable.fetch_async_get(handle) end ---Returns `HTTPApiTable` containing http functions if the calling mod has been granted access by being listed in the `secure.http_mods` or `secure.trusted_mods` setting, otherwise returns `nil`. @@ -91,4 +68,5 @@ function httpapitable.fetch_async_get(handle) end --- ---**DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN A LOCAL VARIABLE!** ---@return HTTPApiTable +---@nodiscard function minetest.request_http_api() end diff --git a/api/inventory.lua b/api/inventory.lua new file mode 100644 index 0000000..22c06c5 --- /dev/null +++ b/api/inventory.lua @@ -0,0 +1,54 @@ +---@meta + +---Get an inventory. +---@param location {type: '"player"'|'"node"'|'"detached"', name: string, node: Vector} +---@return InvRef? +---@nodiscard +function minetest.get_inventory(location) end + +---@class detached_inventory_callbacks +---Called when a player wants to move items inside the inventory. +--- +---Return value: number of items allowed to move. +---@field allow_move fun(inv: InvRef, from_list: string, from_index: integer, to_list: string, to_index: integer, count: integer, player: ObjectRef): integer +---Called when a player wants to put something into the inventory. +--- +---Return value: number of items allowed to put. +--- +---Return value -1: Allow and don't modify item count in inventory. +---@field allow_put fun(inv: InvRef, listname: string, index: integer, stack: ItemStack, player: ObjectRef): integer +---Called when a player wants to take something out of the inventory. +--- +---Return value: number of items allowed to take. +--- +---Return value -1: Allow and don't modify item count in inventory. +---@field allow_take fun(inv: InvRef, listname: string, index: integer, stack: ItemStack, player: ObjectRef): integer +---@field on_move fun(inv: InvRef, from_list: string, from_index: integer, to_list: string, to_index: integer, count: integer, player: ObjectRef) +---@field on_put fun(inv: InvRef, listname: string, index: integer, stack: ItemStack, player: ObjectRef) +---@field on_take fun(inv: InvRef, listname: string, index: integer, stack: ItemStack, player: ObjectRef) + + +---Create a detached inventory. +---@param name string +---@param callbacks detached_inventory_callbacks +---@param player_name? string Make detached inventory available to one player exclusively, by default they will be sent to every player (even if not used). Note that this parameter is mostly just a workaround and will be removed in future releases. +---@return InvRef +function minetest.create_detached_inventory(name, callbacks, player_name) end + +---Remove a detached inventory. +--- +---Returns a boolean indicating whether the removal succeeded. +---@param name string +---@return boolean +function minetest.remove_detached_inventory(name) end + +---Returns leftover `ItemStack` or `nil` to indicate no inventory change. +--- +---See `minetest.item_eat` and `minetest.register_on_item_eat`. +---@param hp_change integer +---@param replace_with_item ItemStack +---@param itemstack ItemStack +---@param user ObjectRef +---@param pointed_thing pointed_thing +---@return ItemStack? +function minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing) end diff --git a/api/item_handling.lua b/api/item_handling.lua new file mode 100644 index 0000000..574bdba --- /dev/null +++ b/api/item_handling.lua @@ -0,0 +1,126 @@ +---@meta + +---Returns a string for making an image of a cube (useful as an item image). +---@param img1 string +---@param img2 string +---@param img3 string +---@return string +---@nodiscard +function minetest.inventorycube(img1, img2, img3) end + +---Returns the position of a `pointed_thing` or `nil` if the `pointed_thing` does not refer to a node or entity. +--- +---If the optional `above` parameter is true and the `pointed_thing` refers to a node, then it will return the `above` position of the `pointed_thing`. +---@param pointed_thing pointed_thing +---@param above boolean +---@return Vector? +---@nodiscard +function minetest.get_pointed_thing_position(pointed_thing, above) end + +---Convert a vector to a facedir value, used in `param2` for `paramtype2="facedir"`. +--- +---Passing `true` for the optional second parameter causes it to take the y component into account. +---@param dir Vector +---@param is6d? boolean +---@return integer +---@nodiscard +function minetest.dir_to_facedir(dir, is6d) end + +---Convert a facedir back into a vector aimed directly out the "back" of a node. +---@param facedir integer +---@return Vector +---@nodiscard +function minetest.facedir_to_dir(facedir) end + +---Convert a vector to a wallmounted value, used for `paramtype2="wallmounted"`. +---@param dir Vector +---@return integer +---@nodiscard +function minetest.dir_to_wallmounted(dir) end + +---Convert a wallmounted value back into a vector aimed directly out the "back" of a node. +---@param wallmounted integer +---@return Vector +---@nodiscard +function minetest.wallmounted_to_dir(wallmounted) end + +---Convert a vector into a yaw (angle). +---@param dir Vector +---@return number +---@nodiscard +function minetest.dir_to_yaw(dir) end + +---Convert yaw (angle) to a vector. +---@param yaw number +---@return Vector +---@nodiscard +function minetest.yaw_to_dir(yaw) end + +---Returns a boolean. +--- +---Returns `true` if the given `paramtype2` contains color information (`color`, `colorwallmounted` or `colorfacedir`). +---@param ptype paramtype2 +---@return boolean +---@nodiscard +function minetest.is_colored_paramtype(ptype) end + +---Removes everything but the color information from the given `param2` value. +--- +---Returns `nil` if the given `paramtype2` does not contain color information. +---@param param2 integer +---@param paramtype2 paramtype2 +---@return integer? +function minetest.strip_param2_color(param2, paramtype2) end + +---Returns list of itemstrings that are dropped by `node` when dug with the item `toolname` (not limited to tools). +---@param node node|string node as table or node name +---@param toolname? string name of the item used to dig (can be `nil`) +---@return string[] +function minetest.get_node_drops(node, toolname) end + +---Get craft result. +---@param input {method: '"normal"'|'"cooking"'|'"fuel"', width: integer, items: ItemStack[]} +---@return {item: ItemStack, time: integer, replacements: ItemStack[]} output +---@return {method: '"normal"'|'"cooking"'|'"fuel"', width: integer, items: ItemStack[]} decremented_input +---@nodiscard +function minetest.get_craft_result(input) end + +---Returns last registered recipe for output item (or node). +---@param output string +---@return craft_recipe +---@nodiscard +function minetest.get_craft_recipe(output) end + +---Returns registered recipes for output item (or node). +---@param output string +---@return craft_recipe[]? +---@nodiscard +function minetest.get_all_craft_recipes(output) end + +---Handles drops from nodes after digging: Default action is to put them into digger's inventory. +--- +---Can be overridden to get different functionality (e.g. dropping items on ground) +---@param pos Vector +---@param drops string[] list of itemstrings +---@param digger ObjectRef +function minetest.handle_node_drops(pos, drops, digger) end + +---Creates an item string which contains palette index information for hardware colorization. +--- +---You can use the returned string as an output in a craft recipe. +---@param item string|ItemStack|table the item stack which becomes colored. can be in string, table and native form. +---@param palette_index integer this index is added to the item stack +---@return string +---@nodiscard +function minetest.itemstring_with_palette(item, palette_index) end + +---Creates an item string which contains static color information for hardware colorization. +--- +---Use this method if you wish to colorize an item that does not own a palette. +--- +---You can use the returned string as an output in a craft recipe. +---@param item string|ItemStack|table the item stack which becomes colored. can be in string, table and native form. +---@param colorstring ColorString +---@return string +---@nodiscard +function minetest.itemstring_with_color(item, colorstring) end diff --git a/api/misc.lua b/api/misc.lua index 57cb371..333ca7a 100644 --- a/api/misc.lua +++ b/api/misc.lua @@ -103,7 +103,7 @@ function minetest.parse_json(string, nullvalue) end ---1. You can only use strings and positive integers of at least one as keys. ---2. You can not mix string and integer keys. This is due to the fact that JSON has two distinct array and object values. ---@param data table ----@param styled boolean Human-readable format, default: false +---@param styled? boolean Human-readable format, default: false ---@return string? output ---@return string? error ---@nodiscard diff --git a/api/mod_channels.lua b/api/mod_channels.lua index 21c34f4..dcdb11e 100644 --- a/api/mod_channels.lua +++ b/api/mod_channels.lua @@ -2,7 +2,7 @@ ---Server joins channel `channel_name`, and creates it if necessary. --- ---You should listen for incoming messages with `minetest.register_on_modchannel_message`. +---You should listen for incoming messages with `minetest.register_on_modchannel_message`. ---@param channel_name string ---@return ModChannel function minetest.mod_channel_join(channel_name) end diff --git a/api/particles.lua b/api/particles.lua new file mode 100644 index 0000000..ce28df5 --- /dev/null +++ b/api/particles.lua @@ -0,0 +1,279 @@ +---@meta + +---@class particle_definition +---@field pos Vector +---@field velocity Vector +---@field acceleration Vector +---Disappears after expirationtime seconds +---@field expirationtime number +---Scales the visual size of the particle texture. +--- +---If `node` is set, size can be set to 0 to spawn a randomly-sized particle (just like actual node dig particles). +---@field size number +---If `true` collides with `walkable` nodes and, depending on the `object_collision` field, objects too. +---@field collisiondetection boolean +---If `true` particle is removed when it collides. +--- +---Requires `collisiondetection = true` to have any effect. +---@field collision_removal boolean +---If `true` particle collides with objects that are defined as `physical = true,` and `collide_with_objects = true,`. +--- +---Requires `collisiondetection = true` to have any effect. +---@field object_collision boolean +---If `true` faces player using y axis only. +---@field vertical boolean +---The texture of the particle. +---@field texture string +---Optional, if specified spawns particle only on the player's client. +---@field playername string +---Optional, specifies how to animate the particle texture. +---@field animation tile_animation_definition +---Optional, specify particle self-luminescence in darkness. +--- +---Values 0-14. +---@field glow integer +---Optional, if specified the particle 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 node +---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 node_tile integer + +---Add a particle with given definition. +--- +---The overloaded definition is deprecated. +---@overload fun(pos: Vector, velocity: Vector, acceleration: Vector, expirationtime: number, size: number, collisiondetection: boolean, texture: string, playername: string) +---@param def particle_definition +function minetest.add_particle(def) end + +---@alias particlespawner_new_pos +---| number # All components of every particle's position vector will be set to this value +---| Vector # All particles will appear at this exact position throughout the lifetime of the particlespawner +---| particlespawner_new_pos_table + +---@class particlespawner_new_pos_table +---`min` is the minimum value this property will be set to in particles spawned by the generator +---@field min Vector +---`max` is the maximum value this property will be set to in particles spawned by the generator +---@field max Vector +---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 bias number + +---@alias particlespawner_new_float +---| number +---| particlespawner_new_pos_float + +---@class particlespawner_new_pos_float +---`min` is the minimum value this property will be set to in particles spawned by the generator +---@field min number +---`max` is the maximum value this property will be set to in particles spawned by the generator +---@field max number +---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 bias number + +---@alias particlespawner_new_tween_style +---|'"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 + +---@class particlespawner_definition +---Number of particles spawned over the time period `time`. +---@field amount integer +---Lifespan of spawner in seconds. +--- +---If time is 0 spawner has infinite lifespan and spawns the `amount` on a per-second basis. +---@field time number +---If `true` collides with `walkable` nodes and, depending on the `object_collision` field, objects too. +---@field collisiondetection boolean +---If `true` particle is removed when it collides. +--- +---Requires `collisiondetection = true` to have any effect. +---@field collision_removal boolean +---If `true` particle collides with objects that are defined as `physical = true,` and `collide_with_objects = true,`. +--- +---Requires `collisiondetection = true` to have any effect. +---@field object_collision boolean +---If defined, particle positions, velocities and accelerations are relative to this object's position and yaw +---@field attached ObjectRef +---If `true` faces player using y axis only. +---@field vertical boolean +---The texture of the particle. +---@field texture string|particle_texture +---A `texpool` consists of a list of possible particle textures. +--- +---Every time a particle is spawned, the engine will pick a texture at random from the `texpool` and assign it as that particle's texture. +--- +---You can also specify a `texture` in addition to a `texpool`; the `texture` value will be ignored on newer clients but will be sent to older (pre-v5.6.0) clients that do not implement texpools. +---@field texpool (string|particle_texture)[] +---Optional, if specified spawns particle only on the player's client. +---@field playername string +---Optional, specifies how to animate the particle texture. +---@field animation tile_animation_definition +---Optional, specify particle self-luminescence in darkness. +--- +---Values 0-14. +---@field glow integer +---Optional, if specified the particle 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 node +---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 node_tile integer +---@field minpos Vector +---@field maxpos Vector +---@field minvel Vector +---@field maxvel Vector +---@field minacc Vector +---@field maxacc Vector +---@field minexptime number +---@field maxexptime number +---@field minsize number +---@field maxsize number +---The position at which particles can appear +---@field pos particlespawner_new_pos +---@field pos_tween {style: particlespawner_new_tween_style, reps: integer, [integer]: particlespawner_new_pos} +---The initial velocity of the particle +---@field vel particlespawner_new_pos +---@field vel_tween {style: particlespawner_new_tween_style, reps: integer, [integer]: particlespawner_new_pos} +---The direction and speed with which the particle accelerates +---@field acc particlespawner_new_pos +---@field acc_tween {style: particlespawner_new_tween_style, reps: integer, [integer]: particlespawner_new_pos} +---Offsets the velocity of each particle by a random amount within the specified range each frame. +--- +---Used to create Brownian motion. +---@field jitter particlespawner_new_pos +---@field jitter_tween {style: particlespawner_new_tween_style, reps: integer, [integer]: particlespawner_new_pos} +---The amount by which absolute particle velocity along each axis is decreased per second. +--- +---A value of 1.0 means that the particle will be slowed to a stop over the space of a second; a value of -1.0 means that the particle speed will be doubled every second. +--- +---To avoid interfering with gravity provided by `acc`, a drag vector like `vector.new(1,0,1)` can be used instead of a uniform value. +---@field drag particlespawner_new_pos +---@field drag_tween {style: particlespawner_new_tween_style, reps: integer, [integer]: particlespawner_new_pos} +---How bouncy the particles are when `collisiondetection` is turned on. +--- +---Values less than or equal to `0` turn off particle bounce; `1` makes the particles bounce without losing any velocity, and `2` makes them double their velocity with every bounce. `bounce` is not bounded but values much larger than `1.0` probably aren't very useful. +---@field bounce particlespawner_new_float +---@field bounce_tween {style: particlespawner_new_tween_style, reps: integer, [integer]: particlespawner_new_float} +---The number of seconds after which the particle disappears. +---@field exptime particlespawner_new_float +---@field exptime_tween {style: particlespawner_new_tween_style, reps: integer, [integer]: particlespawner_new_float} +---Sets the birth orientation of particles relative to various shapes defined in world coordinate space. +--- +---This is an alternative means of setting the velocity which allows particles to emerge from or enter into some entity or node on the map, rather than simply being assigned random velocity values within a range. the velocity calculated by this method will be **added** to that specified by `vel` if `vel` is also set, so in most cases **`vel` should be set to 0**. +---@field attract {kind: particlespawner_new_attract_kind, strength: particlespawner_new_attract_strength, strenght_tween: {style: particlespawner_new_tween_style, reps: integer, [integer]: particlespawner_new_attract_strength}} + +---Selects the kind of shape towards which the particles will be oriented. +---@alias particlespawner_new_attract_kind +---No attractor is set and the `attractor` table is ignored. +---|>'"none"' +---The particles are attracted to a specific point in space. +--- +---Use this also if you want a sphere-like effect, in combination with the `radius` property. +---|'"point"' +---The particles are attracted to an (infinite) line passing through the points `origin` and `angle`. +--- +---Use this for e.g. beacon effects, energy beam effects, etc. +---|'"line"' +---The particles are attracted to an (infinite) plane on whose surface `origin` designates a point in world coordinate space. +--- +---Use this for e.g. particles entering or emerging from a portal. +---|'"plane"' + +---The speed with which particles will move towards `attractor`. +--- +---If negative, the particles will instead move away from that point. +---@alias particlespawner_new_attract_strength number + +---@alias particlespawner_new_texture_blend +---Blends transparent pixels with those they are drawn a top according to the alpha channel of the source texture. +--- +---Useful for e.g. material objects like rocks, dirt, smoke, or node chunks. +---|>'"alpha"' +---Adds the value of pixels to those underneath them, modulo the sources alpha channel. +--- +---Useful for e.g. bright light effects like sparks or fire. +---|'"add"' +---Like "add" but less bright. useful for subtler light effects. +--- +---Note that this is NOT formally equivalent to the "screen" effect used in image editors and compositors, as it does not respect the alpha channel of of the image being blended. +---|'"screen"' +---The inverse of "add"; the value of the source pixel is subtracted from the pixel underneath it. +--- +---A white pixel will turn whatever is underneath it black; a black pixel will be "transparent". +--- +---Useful for creating darkening effects. +---|'"sub"' + + +---In versions before v5.6.0, particlespawner textures could only be specified as a single texture string. +--- +---After v5.6.0, textures can now be specified as a table as well. +--- +---This table contains options that allow simple animations to be applied to the texture. +---@class particle_texture +---@field name string The texture file name +---Controls how visible the particle is. +---* `1.0`: the particle is fully visible +---* `0`: the particle is completely invisible +---@field alpha number +---Can be used instead of `alpha` to animate the alpha value over the particle's lifetime. +--- +---Time references are understood with respect to the particle's lifetime, not the spawner's. +--- +---`{1,0}` fades the particle out over its lifetime. +---@field alpha_tween {style: particlespawner_new_tween_style, reps: integer, [integer]: number} +---Scales the texture onscreen. +---@field scale number|{x: number, y: number} +---Animates the scale over the particle's lifetime. +---@field scale_tween {style: particlespawner_new_tween_style, reps: integer, [integer]: number|{x: number, y: number}} +---@field blend particlespawner_new_texture_blend +---@field animation tile_animation_definition + +---@param def particlespawner_definition +function minetest.add_particlespawner(def) end + +minetest.add_particlespawner({ + pos_tween = { + style = "fwd", + reps = 1, + }, + bounce = {}, + texture = { + blend = "add", + animation = { + + }, + scale_tween = { + { x = 1, y = 1 } + } + }, + texpool = { + { alpha = 1.2, blend = "alpha", name = "test.png" } + }, + attract = { + kind = "none", + strength = 0.1 + }, +}) diff --git a/api/register/environment.lua b/api/register/environment.lua index c736b5e..961d7e7 100644 --- a/api/register/environment.lua +++ b/api/register/environment.lua @@ -1,121 +1,218 @@ ---@meta +---Register a new node. +---@param name string +---@param def node_definition +function minetest.register_node(name, def) end ----**Scatter** ---- ----Randomly chooses a location and generates a cluster of ore. ---- ----If `noise_params` is specified, the ore will be placed if the 3D perlin noise at that point is greater than the `noise_threshold`, giving the ability to create a non-equal distribution of ore. ---- ----**Sheet** ---- ----Creates a sheet of ore in a blob shape according to the 2D perlin noise described by `noise_params` and `noise_threshold`. ---- ----This is essentially an improved version of the so-called "stratus" ore seen in some unofficial mods. ---- ----This sheet consists of vertical columns of uniform randomly distributed height, varying between the inclusive range `column_height_min` and `column_height_max`. ---- ----If `column_height_min` is not specified, this parameter defaults to 1. ---- ----If `column_height_max` is not specified, this parameter defaults to `clust_size` for reverse compatibility. New code should prefer `column_height_max`. ---- ----The `column_midpoint_factor` parameter controls the position of the column at which ore emanates from. ---- ----If 1, columns grow upward. If 0, columns grow downward. If 0.5, columns grow equally starting from each direction. ---- ----`column_midpoint_factor` is a decimal number ranging in value from 0 to 1. If this parameter is not specified, the default is 0.5. ---- ----The ore parameters `clust_scarcity` and `clust_num_ores` are ignored for this ore type. ---- ----**Puff** ---- ----Creates a sheet of ore in a cloud-like puff shape. ---- ----As with the `sheet` ore type, the size and shape of puffs are described by `noise_params` and `noise_threshold` and are placed at random vertical positions within the currently generated chunk. ---- ----The vertical top and bottom displacement of each puff are determined by the noise parameters `np_puff_top` and `np_puff_bottom`, respectively. ---- ----**Blob** ---- ----Creates a deformed sphere of ore according to 3d perlin noise described by `noise_params`. ---- ----The maximum size of the blob is `clust_size`, and `clust_scarcity` has the same meaning as with the `scatter` type. ---- ----**Vein** ---- ----Creates veins of ore varying in density by according to the intersection of two instances of 3d perlin noise with different seeds, both described by `noise_params`. +---Register a new craftitem. +---@param name string +---@param def item_definition +function minetest.register_craftitem(name, def) end + +---Register a new tool. +---@param name string +---@param def item_definition +function minetest.register_tool(name, def) end + +---Overrides fields of an item registered with register_node/tool/craftitem. --- ----`random_factor` varies the influence random chance has on placement of an ore inside the vein, which is `1` by default. +---Note: Item must already be defined, (opt)depend on the mod defining it. --- ----Note that modifying this parameter may require adjusting `noise_threshold`. +---Example: `minetest.override_item("default:mese", {light_source=minetest.LIGHT_MAX})` +---@param name string +---@param redefinition node_definition +function minetest.override_item(name, redefinition) end + +---Unregisters the item from the engine, and deletes the entry with key `name` from `minetest.registered_items` and from the associated item table according to its nature: `minetest.registered_nodes`, etc. +---@param name string +function minetest.unregister_item(name) end + +---Registered nodes, indexed by name. +---@type table +minetest.registered_nodes = {} + +---Registered items, indexed by name. +---@type table +minetest.registered_items = {} + +---Registered tools, indexed by name. +---@type table +minetest.registered_tools = {} + +---Registered craftitems, indexed by name. +---@type table +minetest.registered_craftitems = {} + + +---Register a new entity. +---@param name string +---@param def entity_definition +function minetest.register_entity(name, def) end + +---Registered entities, indexed by name. +---@type table +minetest.registered_entities = {} + + +---@class abm_definition +---Descriptive label for profiling purposes (optional). +--- +---Definitions with identical labels will be listed as one. +---@field label string +---Apply `action` function to these nodes. +--- +---`group:groupname` can also be used here. +---@field nodenames string[] +---Only apply `action` to nodes that have one of, or any combination of, these neighbors. +--- +---If left out or empty, any neighbor will do. +--- +---`group:groupname` can also be used here. +---@field neighbors string[] +---Operation interval in seconds. +---@field interval number +---Chance of triggering `action` per-node per-interval is 1.0 / this value. +---@field chance number +---Min height levels where ABM will be processed. +--- +---Can be used to reduce CPU usage. +---@field min_y integer +---Max height levels where ABM will be processed. +--- +---Can be used to reduce CPU usage. +---@field max_y integer +---If true, catch-up behaviour is enabled. +--- +---The `chance` value is temporarily reduced when returning to an area to simulate time lost by the area being unattended. +--- +---Note that the `chance` value can often be reduced to 1. +---@field catch_up boolean +---Function triggered for each qualifying node. +---* `active_object_count` is number of active objects in the node's mapblock. +---* `active_object_count_wider` is number of active objects in the node's mapblock plus all 26 neighboring mapblocks. If any neighboring mapblocks are unloaded an estimate is calculated for them based on loaded mapblocks. +---@field action fun(pos: Vector, node: node, active_object_count: integer, active_object_count_wider: integer) + +---Register a new Active Block Modifier (ABM) +---@param def abm_definition +function minetest.register_abm(def) end + +---@type abm_definition[] +minetest.registered_abm = {} + + +---@class lbm_definition +---Descriptive label for profiling purposes (optional). --- ----The parameters `clust_scarcity`, `clust_num_ores`, and `clust_size` are ignored by this ore type. +---Definitions with identical labels will be listed as one. +---@field label string +---@field name string +---List of node names to trigger the LBM on. --- ----This ore type is difficult to control since it is sensitive to small changes. +---Also non-registered nodes will work. --- ----The following is a decent set of parameters to work from: +---Groups (as of `group:groupname`) will work as well. +---@field nodenames string[] +---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 run_at_every_load boolean +---@field action fun(pos: Vector, node: node) + +---Register a new Loading Block Modifier (LBM) --- ----```lua ----noise_params = { ---- offset = 0, ---- scale = 3, ---- spread = {x=200, y=200, z=200}, ---- seed = 5390, ---- octaves = 4, ---- persistence = 0.5, ---- lacunarity = 2.0, ---- flags = "eased", ----}, ----noise_threshold = 1.6 ----``` +---A 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!) +---@param def lbm_definition +function minetest.register_lbm(def) end + +---@type lbm_definition[] +minetest.registered_lbm = {} + + +---This adds an alias `alias` for the item called `original_name` +---@param alias string +---@param original_name string +function minetest.register_alias(alias, original_name) end + +---Same as `minetest.register_alias` but will unregister the alias if it exists +---@param alias string +---@param original_name string +function minetest.register_alias_force(alias, original_name) end + +---Map of registered aliases, indexed by name +---@type table +minetest.registered_aliases = {} + + +---Register a new ore. +---@param def ore_definition +function minetest.register_ore(def) end + +---Returns an integer object handle uniquely identifying the registered biome on success. --- ----**WARNING**: Use this ore type *very* sparingly since it is ~200x more computationally expensive than any other ore. +---To get the biome ID, use `minetest.get_biome_id`. --- ----**Stratum** +---The maximum number of biomes that can be used is 65535. --- ----Creates a single undulating ore stratum that is continuous across mapchunk borders and horizontally spans the world. +---However, using an excessive number of biomes will slow down map generation. --- ----The 2D perlin noise described by `noise_params` defines the Y co-ordinate of the stratum midpoint. +---Depending on desired performance and computing power the practical limit is much lower. +---@param def biome_definition +---@return integer +function minetest.register_biome(def) end + +---Map of registered biome definitions, indexed by the `name` field. --- ----The 2D perlin noise described by `np_stratum_thickness` defines the stratum's vertical thickness (in units of nodes). +---If `name` is `nil`, the key is the object handle returned by `minetest.register_biome`. +---@type table +minetest.registered_biomes = {} + +---Unregisters the biome from the engine, and deletes the entry with key `name` from `minetest.registered_biomes`. --- ----Due to being continuous across mapchunk borders the stratum's vertical thickness is unlimited. +---**Warning:** This alters the biome to biome ID correspondences, so any decorations or ores using the 'biomes' field must afterwards be cleared and re-registered. +---@param name string +function minetest.unregister_biome(name) end + +---Returns an integer object handle uniquely identifying the registered decoration on success. --- ----If the noise parameter `noise_params` is omitted the ore will occur from `y_min` to `y_max` in a simple horizontal stratum. +---To get the decoration ID, use `minetest.get_decoration_id`. --- ----A parameter `stratum_thickness` can be provided instead of the noise parameter `np_stratum_thickness`, to create a constant thickness. +---The order of decoration registrations determines the order of decoration generation. +---@param def decoration_definition +---@return integer? +function minetest.register_decoration(def) end + +---Map of registered decoration definitions, indexed by the `name` field. --- ----Leaving out one or both noise parameters makes the ore generation less intensive, useful when adding multiple strata. +---If `name` is nil, the key is the object handle returned by `minetest.register_decoration`. +---@type table +minetest.registered_decorations = {} + +---Returns an integer object handle uniquely identifying the registered schematic on success. --- ----`y_min` and `y_max` define the limits of the ore generation and for performance reasons should be set as close together as possible but without clipping the stratum's Y variation. +---If the schematic is loaded from a file, the `name` field is set to the filename. --- ----Each node in the stratum has a 1-in-`clust_scarcity` chance of being ore, so a solid-ore stratum would require a `clust_scarcity` of 1. +---If the function is called when loading the mod, and `name` is a relative path, then the current mod path will be prepended to the schematic filename. +---@param def schematic_table +---@return integer? +function minetest.register_schematic(def) end + +---Clears all biomes currently registered. --- ----The parameters `clust_num_ores`, `clust_size`, `noise_threshold` and `random_factor` are ignored by this ore type. ----@class ore_definition ----@field ore_type '"scatter"'|'"sheet"'|'"puff"'|'"blob"'|'"vein"'|'"stratum"' ----@field ore string ----@field ore_param2 integer Facedir rotation. Default is `0` (unchanged rotation) ----@field wherein string|string[] ----@field clust_scarcity number Ore has a 1 out of clust_scarcity chance of spawning in a node. If the desired average distance between ores is 'd', set this to d * d * d. ----@field clust_num_ores integer Number of ores in a cluster ----@field clust_size integer Size of the bounding box of the cluster ----@field y_min integer Lower limit for ore ----@field y_max integer Upper limit for ore ----@field flags flag_specifier ----@field noise_threshold number If noise is above this threshold, ore is placed. Not needed for a uniform distribution. ----@field noise_params noise_params Describe one of the perlin noises used for ore distribution. Needed by "sheet", "puff", "blob" and "vein" ores. Omit from "scatter" ore for a uniform ore distribution. Omit from "stratum" ore for a simple horizontal strata from y_min to y_max. ----@field biomes string|string[] List of biomes in which this ore occurs. Occurs in all biomes if this is omitted, and ignored if the Mapgen being used does not support biomes. ----@field column_height_min integer **sheet only** ----@field column_height_max integer **sheet only** ----@field column_midpoint_factor number **sheet only** ----@field np_puff_top noise_params **puff only** ----@field np_puff_bottom noise_params **puff only** ----@field random_factor number **vein only** ----@field np_stratum_thickness noise_params **stratum only** ----@field stratum_thickness integer **stratum only** +---**Warning:** Clearing and re-registering biomes alters the biome to biome ID correspondences, so any decorations or ores using the `biomes` field must afterwards be cleared and re-registered. +function minetest.clear_registered_biomes() end +---Clears all decorations currently registered. +function minetest.clear_registered_decorations() end ---- ----@param def ore_definition -function minetest.register_ore(def) end +---Clears all ores currently registered. +function minetest.clear_registered_ores() end + +---Clears all schematics currently registered. +function minetest.clear_registered_schematics() end + +---Map of object references, indexed by active object id. +---@type table +minetest.object_refs = {} + +---Map of Lua entities, indexed by active object id. +---@type table +minetest.luaentities = {} diff --git a/api/register/gameplay.lua b/api/register/gameplay.lua index e72dc27..8724b32 100644 --- a/api/register/gameplay.lua +++ b/api/register/gameplay.lua @@ -79,3 +79,92 @@ ---Register a craft recipe ---@param recipe craft_recipe function minetest.register_craft(recipe) end + +---Will erase existing craft based either on output item or on input recipe. +--- +---Specify either output or input only. +--- +---If you specify both, input will be ignored. +--- +---For input use the same recipe table syntax as for `minetest.register_craft(recipe)`. For output specify only the item, without a quantity. +--- +---Returns `false` if no erase candidate could be found, otherwise returns `true`. +--- +---**Warning**! The type field ("shaped", "cooking" or any other) will be ignored if the recipe contains output. Erasing is then done independently from the crafting method. +---@param recipe craft_recipe +---@return boolean +function minetest.clear_craft(recipe) end + +---@class chatcommand_definition +---Short parameter description +--- +---Use of symbols is as follows: +---* `<>` signifies a placeholder to be replaced when the command is used. For example, when a player name is needed: `` +---* `[]` signifies param is optional and not required when the command is used. For example, if you require param1 but param2 is optional: ` []` +---* `|` signifies exclusive or. The command requires one param from the options provided. For example: ` | ` +---* `()` signifies grouping. For example, when param1 and param2 are both required, or only param3 is required: `( ) | ` +---@field params string +---Full description +---@field description string +---Require the privileges to run +---@field privs table +---Called when command is run. Returns boolean success and text output. +--- +---Special case: The help message is shown to the player if `func` returns `false` without a text output. +---@field func fun(name: string, param: string): boolean, string? + +---Register a chat command. +---@param name string +---@param def chatcommand_definition +function minetest.register_chatcommand(name, def) end + +---Overrides fields of a chatcommand registered with `minetest.register_chatcommand`. +---@param name string +---@param redef chatcommand_definition +function minetest.override_chatcommand(name, redef) end + +---Unregisters a chatcommands registered with `minetest.register_chatcommand`. +---@param name string +function minetest.unregister_chatcommand(name) end + +---Map of registered chatcommands, indexed by name. +---@type table +minetest.registered_chatcommands = {} + +---@class privilege_definition +---Privilege description. +---@field description string +---Whether to grant the privilege to singleplayer. +---@field give_to_singleplayer boolean +---Whether to grant the privilege to the server admin. +--- +---Uses value of 'give_to_singleplayer' by default. +---@field give_to_admin boolean +---Called when given to player 'name' by 'granter_name'. +--- +---'granter_name' will be nil if the priv was granted by a mod. +--- +---Return true to stop `register_on_priv_grant` from being called. +---@field on_grant fun(name: string, granter_name?: string): boolean +---Called when taken from player `name` by `revoker_name`. +--- +---`revoker_name` will be `nil` if the priv was revoked by a mod. +--- +---Return true to stop `register_on_priv_revoke` from being called. +---@field on_revoke fun(name: string, revoker_name?: string): boolean + + +---Register a new privilege. +--- +---If `definition` is a description, the priv will be granted to singleplayer and admin by default. +--- +---To allow players with `basic_privs` to grant, see the `basic_privs` minetest.conf setting. +---@param name string Name of the privilege +---@param definition privilege_definition|string Privilege definition or description. +function minetest.register_privilege(name, definition) end + +---Map of registered privilege definitions, indexed by name. +--- +---Registered privileges can be modified directly in this table. +---@type table +minetest.registered_privileges = {} diff --git a/api/rollback.lua b/api/rollback.lua new file mode 100644 index 0000000..0be22d0 --- /dev/null +++ b/api/rollback.lua @@ -0,0 +1,21 @@ +---@meta + +---Find who has done something to a node, or near a node. +--- +---Returns `{{actor, pos, time, oldnode, newnode}, ...}` +--- +---* `actor`: `"player:"` or `"liquid"`. +---@param pos Vector +---@param range number +---@param seconds number +---@param limit integer +---@return {[1]: string|'"liquid"', [2]: Vector, [3]: number, [4]: node, [5]: node}[] +---@nodiscard +function minetest.rollback_get_node_actions(pos, range, seconds, limit) end + +---Revert latest actions of someone. +---@param actor string|'"liquid"' `"player:"` or `"liquid"`. +---@param seconds number +---@return boolean success +---@return string[] log_messages +function minetest.rollback_revert_actions_by(actor, seconds) end diff --git a/api/schematic.lua b/api/schematic.lua new file mode 100644 index 0000000..e7d8aac --- /dev/null +++ b/api/schematic.lua @@ -0,0 +1,99 @@ +---@meta + + +---A schematic specifier identifies a schematic by either a filename to a Minetest Schematic file (`.mts`) or through raw data supplied through Lua, in the form of a table. +---@alias schematic_specifier string|integer|schematic_table + +---Probability values: +--- +---* A probability value of `0` or `1` means that node will never appear(0% chance). +---* A probability value of `254` or `255` means the node will always appear (100% chance). +---* If the probability value `p` is greater than `1`, then there is a `(p / 256 * 100)` percent chance that node will appear when the schematic is placed on the map. +---@class schematic_table +---A 3D vector containing the dimensions of the provided schematic. +---@field size Vector +---A slice table sets the probability of a particular horizontal slice of the schematic being placed. +--- +---`ypos` = 0 for the lowest horizontal slice of a schematic. +---@field yslice_prob {ypos: Vector, prob: integer} +---The `data` field is a flat table of MapNode tables making up the schematic, in the order of `[z [y [x]]]`. +--- +---Each MapNode table contains: +---* `name`: the name of the map node to place (required) +---* `prob` (alias `param1`): the probability of this node being placed (default: `255`) +---* `param2`: the raw param2 value of the node being placed onto the map (default: `0`) +---* `force_place`: boolean representing if the node should forcibly overwrite any previous contents (default: `false`) +---@field data {name: string, prob: integer, param2: integer, force_place: boolean}[] + +---Create a schematic from the volume of map specified by the box formed by `p1` and `p2`. +--- +---* `probability_list`: Apply the specified probability and per-node force-place to the specified nodes. An array of tables containing two fields, `pos` and `prob`. +--- * `pos` is the 3D vector specifying the absolute coordinates of the node being modified, +--- * `prob` is an integer value from `0` to `255` that encodes probability and per-node force-place. Probability has levels 0-127, then 128 may be added to encode per-node force-place. For probability stated as 0-255, divide by 2 and round down to get values 0-127, then add 128 to apply per-node force-place. If there are two or more entries with the same pos value, the last entry is used. If `pos` is not inside the box formed by `p1` and `p2`, it is ignored. +---* `slice_prob_list`: Apply the specified probability to the specified horizontal slices. An array of tables containing two fields, `ypos` and `prob`. +--- * `ypos` indicates the y position of the slice with a probability applied, the lowest slice being `ypos = 0`. +---@param p1 Vector +---@param p2 Vector +---@param probability_list? {pos: Vector, prob: integer}[] +---@param filename string # Saves schematic in the Minetest Schematic format to filename. +---@param slice_prob_list? {ypos: Vector, prob: integer}[] +function minetest.create_schematic(p1, p2, probability_list, filename, slice_prob_list) end + +---Place the schematic at `pos`. +--- +---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. +---@param pos Vector +---@param schematic schematic_specifier +---@param rotation? '"0"'|'"90"'|'"180"'|'"270"'|'"random"' +---@param replacements? table +---@param force_placement boolean # Boolean indicating whether nodes other than `air` and `ignore` are replaced by the schematic. +---@param flags flag_specifier # Flag field with the available flags: `place_center_x`, `place_center_y`, `place_center_z` +---@return unknown? +function minetest.place_schematic(pos, schematic, rotation, replacements, force_placement, flags) end + +---This function is analogous to `minetest.place_schematic`, but places a schematic onto the specified VoxelManip object `vmanip` instead of the map. +--- +---Returns `false` if any part of the schematic was cut-off due to the `VoxelManip` not containing the full area required, and true if the whole schematic was able to fit. +--- +---Returns `nil` if the schematic could not be loaded. +--- +---After execution, any external copies of the VoxelManip contents are invalidated. +---@param vmanip VoxelManip +---@param pos Vector +---@param schematic schematic_specifier +---@param rotation? '"0"'|'"90"'|'"180"'|'"270"'|'"random"' +---@param replacements? table +---@param force_placement boolean # Boolean indicating whether nodes other than `air` and `ignore` are replaced by the schematic. +---@param flags flag_specifier # Flag field with the available flags: `place_center_x`, `place_center_y`, `place_center_z` +---@return boolean? +function minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacements, force_placement, flags) end + +---`format`: +---* "mts": a string containing the binary MTS data used in the MTS file format. +---* "lua": a string containing Lua code representing the schematic in table format. +--- +---`options`: +---* If `lua_use_comments` is true and `format` is "lua", the Lua code generated will have (X, Z) position comments for every X row generated in the schematic data for easier reading. +---* If `lua_num_indent_spaces` is a nonzero number and `format` is "lua", the Lua code generated will use that number of spaces as indentation instead of a tab character. +---@param schematic schematic_specifier +---@param format '"lua"'|'"mts"' +---@param options {lua_use_comments: boolean, lua_num_indent_spaces: integer} +---@return string +function minetest.serialize_schematic(schematic, format, options) end + +---Returns a Lua table representing the schematic. +--- +---`write_yslice_prob`: +---* `none`: no `write_yslice_prob` table is inserted +---* `low`: only probabilities that are not 254 or 255 are written in the `write_ylisce_prob` table +---* `all`: write all probabilities to the `write_yslice_prob` table. +--- +---The default for this option is `all`. +--- +---Any invalid value will be interpreted as `all`. +---@param schematic schematic_specifier +---@param options {write_yslice_prob: '"none"'|'"low"'|'"all"'} +---@return schematic_table +function minetest.read_schematic(schematic, options) end diff --git a/api/server.lua b/api/server.lua index 19a6722..e692d4e 100644 --- a/api/server.lua +++ b/api/server.lua @@ -3,7 +3,7 @@ ---Request the server to shutdown. ---@param message? string Will display `message` to clients ---@param reconnect? boolean Displays a reconnect button to players ----@param delay? any Adds an optional delay (in seconds) before shutdown. Negative delay cancels the current active shutdown. Zero delay triggers an immediate shutdown. +---@param delay? number Adds an optional delay (in seconds) before shutdown. Negative delay cancels the current active shutdown. Zero delay triggers an immediate shutdown. function minetest.request_shutdown(message, reconnect, delay) end ---Cancel current delayed shutdown. @@ -15,16 +15,19 @@ function minetest.cancel_shutdown_requests() end --- ---This function may be overwritten by mods to customize the status message. ---@param name string ----@param joined any Indicates whether the function was called when a player joined. +---@param joined boolean Indicates whether the function was called when a player joined. ---@return string +---@nodiscard function minetest.get_server_status(name, joined) end ---Returns the server uptime in seconds. ---@return integer +---@nodiscard function minetest.get_server_uptime() end ---Returns the current maximum lag. ---@return number +---@nodiscard function minetest.get_server_max_lag() end ---Remove player from database if he is not connected. @@ -44,20 +47,12 @@ function minetest.remove_player(name) end function minetest.remove_player_auth(name) end ---@class dynamic_add_media_options -local dynamic_add_media_options = {} - ---Path to a media file on the filesystem. ----@type string -dynamic_add_media_options.filepath = nil - +---@field filepath string ---Name of the player the media should be sent to instead of all players (optional) ----@type string -dynamic_add_media_options.to_player = nil - +---@field to_player string ---Marks the media as ephemeral, it will not be cached on the client (optional, default: false) ----@type boolean -dynamic_add_media_options.ephemeral = nil - +---@field ephemeral boolean ---Pushes the specified media file to client(s). --- diff --git a/auth.lua b/auth.lua index e88e46a..ab190b5 100644 --- a/auth.lua +++ b/auth.lua @@ -1,13 +1,33 @@ ---@meta ---@class authentication_handler_definition +---Get authentication data for existing player `name` (`nil` if player doesn't exist). +--- +---Returns following structure: `{password=, privileges=, last_login=}` ---@field get_auth fun(name: string): {password: string, privileges: table, last_login: integer|nil} +---Create new auth data for player `name`. +--- +---Note that `password` is not plain-text but an arbitrary representation decided by the engine. ---@field create_auth fun(name: string, password: string) +---Delete auth data of player `name`. +--- +---Returns boolean indicating success (`false` if player is nonexistent). ---@field delete_auth fun(name: string): boolean +---Set password of player `name` to `password`. +--- +---Auth data should be created if not present. ---@field set_password fun(name: string, password: string) +---Set privileges of player `name`. +--- +---`privileges` is in table form, auth data should be created if not present. ---@field set_privileges fun(name: string, privileges: table) +---Reload authentication data from the storage location. +--- +---Returns boolean indicating success. ---@field reload fun(): boolean +---Called when player joins, used for keeping track of last_login. ---@field record_login fun(name: string) +---Returns an iterator (use with `for` loops) for all player names currently in the auth database. ---@field iterate fun() ---Registers an auth handler that overrides the builtin one. @@ -20,6 +40,7 @@ function minetest.register_authentication_handler(authentication_handler) end --- ---Use this to e.g. get the authentication data for a player: `local auth_data = minetest.get_auth_handler().get_auth(playername)` ---@return authentication_handler_definition +---@nodiscard function minetest.get_auth_handler() end ---Must be called by the authentication handler for privilege changes. @@ -45,6 +66,7 @@ function minetest.auth_reload() end ---The player needs to be online for this to be successful. ---@param name string ---@return string +---@nodiscard function minetest.get_player_ip(name) end ---Convert a name-password pair to a password hash that Minetest can use. @@ -54,6 +76,7 @@ function minetest.get_player_ip(name) end ---For this purpose, use `minetest.check_password_entry` instead. ---@param name string ---@param raw_password string +---@nodiscard function minetest.get_password_hash(name, raw_password) end ---Returns true if the "password entry" for a player with name matches given password, false otherwise. @@ -64,23 +87,28 @@ function minetest.get_password_hash(name, raw_password) end ---@param name string ---@param entry string ---@param password string +---@return boolean +---@nodiscard function minetest.check_password_entry(name, entry, password) end ---Converts string representation of privs into table form. ---@param str string ---@param delim? string String separating the privs. Defaults to `","`. ---@return table +---@nodiscard function minetest.string_to_privs(str, delim) end ---Returns the string representation of `privs` ---@param privs table ---@param delim? string String separating the privs. Defaults to `","`. ---@return string +---@nodiscard function minetest.privs_to_string(privs, delim) end ---Returns player privs. ---@param name string ---@return table +---@nodiscard function minetest.get_player_privs(name) end ---Check if player have given privileges. @@ -88,4 +116,5 @@ function minetest.get_player_privs(name) end ---@param ... any Is either a list of strings, e.g. `"priva", "privb"` or a table, e.g. `{ priva = true, privb = true }`. ---@return boolean ---@return table missing_privs +---@nodiscard function minetest.check_player_privs(player_or_name, ...) end diff --git a/classes/areastore.lua b/classes/areastore.lua index 79852ce..92e7440 100644 --- a/classes/areastore.lua +++ b/classes/areastore.lua @@ -5,7 +5,7 @@ ---The `data` field (string) may be used to store and retrieve any mod-relevant information to the specified area. --- ---Despite its name, mods must take care of persisting AreaStore data. They may use the provided load and write functions for this. ----@class AreaStore +---@class AreaStore: userdata local area_store = {} ---Returns the area information about the specified ID. @@ -18,6 +18,7 @@ local area_store = {} ---@param include_corners boolean ---@param include_data boolean ---@return nil|true|{min: Vector, max: Vector, data: string} +---@nodiscard function area_store:get_area(id, include_corners, include_data) end ---Returns all areas as table, indexed by the area ID. @@ -27,6 +28,7 @@ function area_store:get_area(id, include_corners, include_data) end ---@param include_corners boolean ---@param include_data boolean ---@return table +---@nodiscard function area_store:get_areas_for_pos(pos, include_corners, include_data) end ---Returns all areas that contain all nodes inside the area specified by`corner1 and `corner2` (inclusive). @@ -40,6 +42,7 @@ function area_store:get_areas_for_pos(pos, include_corners, include_data) end ---@param include_corners boolean ---@param include_data boolean ---@return table +---@nodiscard function area_store:get_areas_in_area(corner1, corner2, accept_overlap, include_corners, include_data) end ---Returns the new area's ID, or nil if the insertion failed. @@ -94,4 +97,5 @@ function area_store:from_file(filename) end --- ---@param type_name? '"LibSpatial"' Forces the internally used API ---@return AreaStore +---@nodiscard function AreaStore(type_name) end diff --git a/classes/invref.lua b/classes/invref.lua index 0e8bad9..02c8655 100644 --- a/classes/invref.lua +++ b/classes/invref.lua @@ -1,17 +1,19 @@ ---@meta ---A reference to an inventory. ----@class InvRef +---@class InvRef: userdata local InvRef = {} ---Return `true` if list is empty. ---@param listname string ---@return boolean +---@nodiscard function InvRef:is_empty(listname) end ---Get the size of a list. ---@param listname string ---@return integer +---@nodiscard function InvRef:get_size(listname) end ---Set the size of a list. @@ -25,6 +27,7 @@ function InvRef:set_size(listname, size) end ---Get the width of a list. ---@param listname string ---@return integer +---@nodiscard function InvRef:get_width(listname) end ---Set width of the list; currently used for crafting. @@ -36,6 +39,7 @@ function InvRef:set_width(listname, width) end ---@param listname string ---@param i integer ---@return ItemStack +---@nodiscard function InvRef:get_stack(listname, i) end ---Copy `stack` to index `i` in the list. @@ -47,6 +51,7 @@ function InvRef:set_stack(listname, i, stack) end ---Returns a full list of `ItemStack`. ---@param listname string ---@return ItemStack[] +---@nodiscard function InvRef:get_list(listname) end ---Set a full list of `ItemStack`. @@ -58,6 +63,7 @@ function InvRef:set_list(listname, list) end ---Returns table mapping listnames to inventory lists. ---@return table +---@nodiscard function InvRef:get_lists() end ---Sets inventory lists (size will not change). @@ -66,7 +72,7 @@ function InvRef:set_lists(lists) end ---Add `stack` somewhere in list, returns leftover `ItemStack`. ---@param listname string ----@param stack ItemStack +---@param stack ItemStack|string ---@return ItemStack function InvRef:add_item(listname, stack) end @@ -74,6 +80,7 @@ function InvRef:add_item(listname, stack) end ---@param listname string ---@param stack ItemStack ---@return boolean +---@nodiscard function InvRef:room_for_item(listname, stack) end ---Returns `true` if the stack of items can be fully taken from the list. @@ -82,6 +89,7 @@ function InvRef:room_for_item(listname, stack) end ---@param listname string ---@param stack ItemStack ---@param match_meta? boolean +---@nodiscard function InvRef:contains_item(listname, stack, match_meta) end ---Take as many items as specified from the list, returns the items that were actually removed (as an `ItemStack`). @@ -96,4 +104,5 @@ function InvRef:remove_item(listname, stack) end ---Returns a location compatible with `minetest.get_inventory(location)`. ---@return inventory_location +---@nodiscard function InvRef:get_location() end diff --git a/classes/itemstack.lua b/classes/itemstack.lua index 2a146c4..9615423 100644 --- a/classes/itemstack.lua +++ b/classes/itemstack.lua @@ -3,18 +3,21 @@ ---Returns an `ItemStack` ---@param x ItemStack|string|table|nil ---@return ItemStack +---@nodiscard function ItemStack(x) end ---An `ItemStack` is a stack of items. ----@class ItemStack +---@class ItemStack: userdata local stack = {} ---Returns `true` if stack is empty. ---@return boolean +---@nodiscard function stack:is_empty() end ---Returns item name (e.g. `"default:stone"`). ---@return string +---@nodiscard function stack:get_name() end ---Returns a boolean indicating whether the item was cleared. @@ -24,6 +27,7 @@ function stack:set_name(item_name) end ---Returns number of items in the stack. ---@return integer +---@nodiscard function stack:get_count() end ---Returns a boolean indicating whether the item was cleared. @@ -33,6 +37,7 @@ function stack:set_count(count) end ---Returns tool wear (`0`-`65535`), `0` for non-tools. ---@return integer +---@nodiscard function stack:get_wear() end ---Returns boolean indicating whether item was cleared. @@ -42,11 +47,13 @@ function stack:set_wear(wear) end ---Returns `ItemStackMetaRef`. ---@return ItemStackMetaRef +---@nodiscard function stack:get_meta() end ---**DEPRECATED:** Returns metadata (a string attached to an itemstack). ---@deprecated ---@return string +---@nodiscard function stack:get_metadata() end ---**DEPRECATED:** Returns true. @@ -64,6 +71,7 @@ function stack:set_metadata(metadata) end --- * `description` in item definition --- * item name ---@return string +---@nodiscard function stack:get_description() end ---Returns the short description or nil. @@ -75,6 +83,7 @@ function stack:get_description() end --- * first line of the description --- * item name ---@return string? +---@nodiscard function stack:get_short_description() end ---Removes all items from the stack, making it empty. @@ -86,30 +95,37 @@ function stack:replace(item) end ---Returns the stack in itemstring form. ---@return string +---@nodiscard function stack:to_string() end ---Returns the stack in Lua table form. ---@return table +---@nodiscard function stack:to_table() end ---Returns the maximum size of the stack (depends on the item). ---@return integer +---@nodiscard function stack:get_stack_max() end ---Returns `get_stack_max() - get_count()`. ---@return integer +---@nodiscard function stack:get_free_space() end ---Returns `true` if the item name refers to a defined item type. ---@return boolean +---@nodiscard function stack:is_known() end ---Returns the item definition table. ---@return table +---@nodiscard function stack:get_definition() end ---Returns the digging properties of the item, or those of the hand if none are defined for this item type. ---@return tool_capabilities +---@nodiscard function stack:get_tool_capabilities() end ---Increases wear by `amount` if the item is a tool, otherwise does nothing. @@ -126,18 +142,19 @@ function stack:add_item(item) end ---Returns `true` if item or stack can be fully added to this one. ---@param item ItemStack|string|table ---@return boolean +---@nodiscard function stack:item_fits(item) end ---Take (and remove) up to `n` items from this stack. --- ---Return taken `ItemStack`. ----@param n integer +---@param n? integer ---@return ItemStack function stack:take_item(n) end ---Copy (don't remove) up to `n` items from this stack. --- ---Returns taken `ItemStack`. ----@param n integer +---@param n? integer ---@return ItemStack function stack:peek_item(n) end diff --git a/classes/luaentity.lua b/classes/luaentity.lua index 75e8a0d..b545e99 100644 --- a/classes/luaentity.lua +++ b/classes/luaentity.lua @@ -3,3 +3,9 @@ ---@class Luaentity ---@field name string ---@field object ObjectRef +---@field on_activate fun(self: Luaentity, staticdata, dtime_s: number) +---@field on_step fun(self: Luaentity, dtime: number, moveresult: moveresult) +---@field on_punch fun(self: Luaentity, puncher: ObjectRef, time_from_last_punch: number, tool_capabilities: tool_capabilities, dir: Vector) +---@field on_rightclick fun(self: Luaentity, clicker: ObjectRef) +---@field get_staticdata fun(self: Luaentity): string +---@field [string] any diff --git a/classes/metadata.lua b/classes/metadata.lua index 063e09b..1ce5d66 100644 --- a/classes/metadata.lua +++ b/classes/metadata.lua @@ -5,7 +5,7 @@ ----------------- ---Base class used by `StorageRef`, `NodeMetaRef`, `ItemStackMetaRef`, and `PlayerMetaRef`. ----@class MetaDataRef +---@class MetaDataRef: userdata local MetaDataRef = {} ---Returns `true` if key present, otherwise `false`. @@ -13,11 +13,13 @@ local MetaDataRef = {} ---Returns `nil` when the MetaData is inexistent. ---@param key string ---@return boolean? +---@nodiscard function MetaDataRef:contains(key) end ---Returns `nil` if key not present, else the stored string. ---@param key string ---@return string? +---@nodiscard function MetaDataRef:get(key) end ---Value of `""` will delete the key. @@ -28,6 +30,7 @@ function MetaDataRef:set_string(key, value) end ---Returns `""` if key not present. ---@param key string ---@return string +---@nodiscard function MetaDataRef:get_string(key) end ---@param key string @@ -37,6 +40,7 @@ function MetaDataRef:set_int(key, value) end ---Returns `0` if key not present. ---@param key string ---@return integer +---@nodiscard function MetaDataRef:get_int(key) end ---@param key string @@ -46,11 +50,13 @@ function MetaDataRef:set_float(key, value) end ---Returns `0` if key not present. ---@param key string ---@return number +---@nodiscard function MetaDataRef:get_float(key) end ---Returns `nil` or a table with keys: --- * `fields`: key-value storage ---@return {fields: {[string]: any}}? +---@nodiscard function MetaDataRef:to_table() end ---Any non-table value will clear the metadata. @@ -64,6 +70,7 @@ function MetaDataRef:from_table(table) end ---Returns `true` if this metadata has the same key-value pairs as `other`. ---@param other MetaDataRef ---@return boolean +---@nodiscard function MetaDataRef:equals(other) end ----------------- @@ -77,6 +84,7 @@ local NodeMetaRef = {} --- * `fields`: key-value storage --- * `inventory`: `{list1 = {}, ...}}` ---@return {fields: {[string]: any}, inventory: {[string]: {[integer]: string}}}? +---@nodiscard function NodeMetaRef:to_table() end ---Any non-table value will clear the metadata. @@ -90,6 +98,7 @@ function NodeMetaRef:from_table(table) end ---Returns `InvRef` ---@return InvRef +---@nodiscard function NodeMetaRef:get_inventory() end ---Mark specific vars as private. @@ -118,12 +127,12 @@ function ItemStackMetaRef:set_tool_capabilities(tool_capabilities) end ---------------- ---@class StorageRef: MetaDataRef -local StorageRef = {} ---Returns reference to mod private `StorageRef`. --- ---Must be called during mod load time. ---@return StorageRef +---@nodiscard function minetest.get_mod_storage() end ------------------- @@ -131,4 +140,3 @@ function minetest.get_mod_storage() end ------------------- ---@class PlayerMetaRef: MetaDataRef -local PlayerMetaRef = {} diff --git a/classes/modchannel.lua b/classes/modchannel.lua index 6d6dd35..ce82993 100644 --- a/classes/modchannel.lua +++ b/classes/modchannel.lua @@ -1,6 +1,6 @@ ---@meta ----@class ModChannel +---@class ModChannel: userdata local ModChannel = {} ---Leave the mod channel. @@ -14,7 +14,8 @@ function ModChannel:leave() end ---Returns true if channel is writeable and mod can send over it. ---@return boolean -function ModChannel:is_writable() end +---@nodiscard +function ModChannel:is_writeable() end ---If mod channel is not writeable or invalid, message will be dropped. --- diff --git a/classes/node.lua b/classes/node.lua index a818a10..8aed18a 100644 --- a/classes/node.lua +++ b/classes/node.lua @@ -1,14 +1,6 @@ ---@meta ---@class node -local node = {} - ----The node name ----@type string -node.name = nil - ----@type integer -node.param1 = nil - ----@type integer -node.param2 = nil +---@field name string +---@field param1 integer +---@field param2 integer diff --git a/classes/nodetimerref.lua b/classes/nodetimerref.lua index 563f1c7..1324c49 100644 --- a/classes/nodetimerref.lua +++ b/classes/nodetimerref.lua @@ -1,7 +1,7 @@ ---@meta ---A high resolution persistent per-node timer. ----@class NodeTimerRef +---@class NodeTimerRef: userdata local node_timer_ref = {} ---Set a timer's state. @@ -24,12 +24,15 @@ function node_timer_ref:stop() end --- ---If `timeout` equals `0`, timer is inactive. ---@return number +---@nodiscard function node_timer_ref:get_timeout() end ---Returns current elapsed time in seconds. ---@return number +---@nodiscard function node_timer_ref:get_elapsed() end ---Returns boolean state of the timer. ---@return boolean +---@nodiscard function node_timer_ref:is_started() end diff --git a/classes/objectref.lua b/classes/objectref.lua index 7b69357..fb99a32 100644 --- a/classes/objectref.lua +++ b/classes/objectref.lua @@ -3,7 +3,7 @@ ---A reference to an entity. --- ---This is basically a reference to a C++ `ServerActiveObject`. ----@class ObjectRef +---@class ObjectRef: userdata local ObjectRef = {} ------------- @@ -12,6 +12,7 @@ local ObjectRef = {} ---Return position of the object ---@return Vector +---@nodiscard function ObjectRef:get_pos() end ---Set position of the object @@ -20,6 +21,7 @@ function ObjectRef:set_pos(pos) end ---Returns the velocity of the object as a vector. ---@return Vector +---@nodiscard function ObjectRef:get_velocity() end ---In comparison to using `get_velocity`, adding the velocity and then using `set_velocity`, `add_velocity` is supposed to avoid synchronization problems. @@ -39,7 +41,7 @@ function ObjectRef:add_velocity(vel) end --- ---For players this does the same as `set_pos`,`continuous` is ignored. ---@param pos Vector ----@param continuous boolean +---@param continuous? boolean function ObjectRef:move_to(pos, continuous) end ---Simulate a punch of the object. @@ -55,28 +57,34 @@ function ObjectRef:right_click(clicker) end ---Returns number of health points of the object. ---@return integer +---@nodiscard function ObjectRef:get_hp() end --FIXME: reason table + ---Set number of health points of the object. ---@param hp integer ----@param reason table +---@param reason? table function ObjectRef:set_hp(hp, reason) end ---Returns an `InvRef` for players, otherwise returns `nil` ---@return InvRef? +---@nodiscard function ObjectRef:get_inventory() end ---Returns the inventory list the wielded item is in. ---@return string +---@nodiscard function ObjectRef:get_wield_list() end ---Returns the index of the wielded item. ---@return integer +---@nodiscard function ObjectRef:get_wield_index() end ---Returns the wielded `ItemStack` ---@return ItemStack +---@nodiscard function ObjectRef:get_wielded_item() end ---Replaces the wielded item, returns `true` if successful. @@ -86,6 +94,7 @@ function ObjectRef:set_wielded_item(item) end ---Returns a table with the armor group ratings. ---@return { [string]: integer } +---@nodiscard function ObjectRef:get_armor_groups() end ---Set armor group ratings. @@ -97,13 +106,14 @@ function ObjectRef:set_armor_groups(groups) end ---@return number frame_speed ---@return number frame_blend ---@return boolean frame_loop +---@nodiscard function ObjectRef:get_animation() end ---Set object animation. ---@param frame_range {x: number, y: number} ----@param frame_speed number ----@param frame_blend number ----@param frame_loop boolean +---@param frame_speed? number Default: `15.0` +---@param frame_blend? number Default: `0.0` +---@param frame_loop? boolean Default: `true` function ObjectRef:set_animation(frame_range, frame_speed, frame_blend, frame_loop) end ---Set object animation frame speed. @@ -126,10 +136,12 @@ function ObjectRef:set_attach(parent, bone, position, rotation, forced_visible) ---@return Vector? position ---@return Vector? rotation ---@return boolean? forced_visible +---@nodiscard function ObjectRef:get_attach() end ---Returns a list of `ObjectRefs` that are attached to the object. ---@return ObjectRef[] +---@nodiscard function ObjectRef:get_children() end ---Detach object. @@ -145,65 +157,178 @@ function ObjectRef:set_bone_position(bone, position, rotation) end ---@param bone string ---@return Vector position ---@return Vector rotation +---@nodiscard function ObjectRef:get_bone_position(bone) end ---FIXME: document object_properties - ---Object Properties ---@class object_properties +---**Player Only** +--- +---Defaults to `minetest.PLAYER_MAX_HP_DEFAULT`. ---@field hp_max integer +---**Player Only** +--- +---Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`. ---@field breath_max integer +---**Player Only** +--- +---Zoom FOV in degrees. +--- +---Note that zoom loads and/or generates world beyond the server's maximum send and generate distances, so acts like a telescope. +--- +---Smaller zoom_fov values increase the distance loaded/generated. +--- +---Defaults to 15 in creative mode, 0 in survival mode. +--- +---`zoom_fov = 0` disables zooming for the player. ---@field zoom_fov number +---**Player Only** +--- +---Camera height above feet position in nodes. +--- +---Defaults to 1.625 ---@field eye_height number +---Collide with `walkable` nodes. ---@field physical boolean +---Collide with other objects if `physical = true` ---@field collide_with_objects boolean +---`{xmin, ymin, zmin, xmax, ymax, zmax}` in nodes from object position. ---@field collisionbox number[] +---Selection box uses collision box dimensions when not set. +--- +---`{xmin, ymin, zmin, xmax, ymax, zmax}` in nodes from object position. ---@field selectionbox number[] +---Overrides selection box when `false`. ---@field pointable boolean +---* `"cube"` is a node-sized cube. +---* `"sprite"` is a flat texture always facing the player. +---* `"upright_sprite"` is a vertical flat texture. +---* `"mesh"` uses the defined mesh model. +---* `"wielditem"` is used for dropped items. (see builtin/game/item_entity.lua). +--- * For this use 'wield_item = itemname' (Deprecated: 'textures = {itemname}'). +--- * If the item has a 'wield_image' the object will be an extrusion of that, otherwise: +--- * If 'itemname' is a cubic node or nodebox the object will appear identical to 'itemname'. +--- * If 'itemname' is a plantlike node the object will be an extrusion of its texture. +--- * Otherwise for non-node items, the object will be an extrusion of 'inventory_image'. +--- * If 'itemname' contains a ColorString or palette index (e.g. from `minetest.itemstring_with_palette()`), the entity will inherit the color. +---* `"item"` is similar to `"wielditem"` but ignores the 'wield_image' parameter. ---@field visual '"cube"'|'"sprite"'|'"upright_sprite"'|'"mesh"'|'"wielditem"'|'"item"' ----@field visual_size Vector +---Multipliers for the visual size. +--- +---If `z` is not specified, `x` will be used to scale the entity along both horizontal axes. +---@field visual_size Vector|{x: number, y: number} +---File name of mesh when using `"mesh"` visual. ---@field mesh string +---Number of required textures depends on visual. +---* `"cube"` uses 6 textures just like a node, but all 6 must be defined. +---* `"sprite"` uses 1 texture. +---* `"upright_sprite"` uses 2 textures: {front, back}. +---* `"wielditem"` expects 'textures = {itemname}' (see 'visual' above). +---* `"mesh"` requires one texture for each mesh buffer/material (in order) ---@field textures string[] +---Number of required colors depends on visual. ---@field colors table +---Use texture's alpha channel. +--- +---Excludes `"upright_sprite"` and `"wielditem"`. +--- +---Note: currently causes visual issues when viewed through other semi-transparent materials such as water. ---@field use_texture_alpha boolean +---Used with spritesheet textures for animation and/or frame selection according to position relative to player. +--- +---Defines the number of columns and rows in the spritesheet: `{x = columns, y = rows}`. ---@field spritediv {x: integer, y: integer} +---Used with spritesheet textures. +--- +---Defines the `{x = column, y = row}` position of the initially used frame in the spritesheet. ---@field initial_sprite_basepos {x: integer, y: integer} +---If `false`, object is invisible and can't be pointed. ---@field is_visible boolean +---If `true`, is able to make footstep sounds of nodes (see node sound definition for details). ---@field makes_footstep_sound boolean +---Set constant rotation in radians per second, positive or negative. +--- +---Object rotates along the local Y-axis, and works with set_rotation. +--- +---Set to 0 to disable constant rotation. ---@field automatic_rotate number +---If positive number, object will climb upwards when it moves horizontally against a `walkable` node, if the height difference is within `stepheight`. ---@field stepheight number +---Automatically set yaw to movement direction, offset in degrees. +--- +---`false` to disable. ---@field automatic_face_movement_dir number +---Limit automatic rotation to this value in degrees per second. +--- +---No limit if value <= 0. ---@field automatic_face_movement_max_rotation_per_sec number +---Set to false to disable backface_culling for model. ---@field backface_culling boolean +---Add this much extra lighting when calculating texture color. +--- +---Value < 0 disables light's effect on texture color. +--- +---For faking self-lighting, UI style entities, or programmatic coloring in mods. ---@field glow integer +---The name to display on the head of the object. By default empty. +--- +---If the object is a player, a nil or empty nametag is replaced by the player's name. +--- +---For all other objects, a nil or empty string removes the nametag. +--- +---To hide a nametag, set its color alpha to zero. That will disable it entirely. ---@field nametag string +---Text color of nametag. ---@field nametag_color ColorSpec ----@field nametag_bgcolor ColorSpec +---Background color of nametag. +--- +---`false` will cause the background to be set automatically based on user settings. +--- +---Default: `false` +---@field nametag_bgcolor ColorSpec|false +---Same as infotext for nodes. +--- +---Empty by default. ---@field infotext string +---If `false`, never save this object statically. +--- +---It will simply be deleted when the block gets unloaded. +--- +---The get_staticdata() callback is never called then. +--- +---Defaults to `true`. ---@field static_save boolean +---Texture modifier to be applied for a short duration when object is hit. ---@field damage_texture_modifier string +---Setting this to `false` disables diffuse lighting of entity. ---@field shaded boolean +---Defaults to `true` for players, `false` for other entities. +--- +---If set to `true` the entity will show as a marker on the minimap. ---@field show_on_minimap boolean ---Returns object properties. ---@return object_properties +---@nodiscard function ObjectRef:get_properties() end ---Set objects properties. ---@param object_properties object_properties function ObjectRef:set_properties(object_properties) end ----Returns true for players, false otherwise. +---Returns `true` for players, `false` otherwise. ---@return boolean +---@nodiscard function ObjectRef:is_player() end ---@class nametag_attributes ---@field text string ---@field color ColorSpec ----@field bgcolor ColorSpec|'false' +---@field bgcolor ColorSpec|'"false"' ---Returns a table with the attributes of the nametag of an object. ---@return nametag_attributes +---@nodiscard function ObjectRef:get_nametag_attributes() end ---Sets the attributes of the nametag of the object. @@ -237,6 +362,7 @@ function ObjectRef:set_acceleration(acc) end --- ---Returns the acceleration of the object. ---@return Vector +---@nodiscard function ObjectRef:get_acceleration() end ---**Luaentity Only** @@ -257,6 +383,7 @@ function ObjectRef:set_rotation(rot) end --- ---`X` is pitch (elevation), `Y` is yaw (heading) and `Z` is roll (bank). ---@return Vector +---@nodiscard function ObjectRef:get_rotation() end ---**Luaentity Only** @@ -269,6 +396,7 @@ function ObjectRef:set_yaw(yaw) end --- ---Returns the yaw (heading) of the object in radians. ---@return number +---@nodiscard function ObjectRef:get_yaw() end ---**Luaentity Only** @@ -283,6 +411,7 @@ function ObjectRef:set_texture_mod(mod) end --- ---Returns the current texture modifier of the object. ---@return string +---@nodiscard function ObjectRef:get_texture_mod() end ---**Luaentity Only** @@ -310,14 +439,14 @@ function ObjectRef:set_sprite(start_frame, num_frames, framelenght, select_x_by_ ---**DEPRECATED**, will be removed in a future version. ---@deprecated ---@return string +---@nodiscard function ObjectRef:get_entity_name() end ---FIXME - ---**Luaentity Only** --- ---Returns object luaentity. ----@return table +---@return Luaentity +---@nodiscard function ObjectRef:get_luaentity() end ----------------- @@ -330,6 +459,7 @@ function ObjectRef:get_luaentity() end --- ---Returns `""` if object isn't a player. ---@return string +---@nodiscard function ObjectRef:get_player_name() end ---**Player Only** @@ -337,6 +467,7 @@ function ObjectRef:get_player_name() end ---**DEPRECATED**, use `get_velocity()` instead. ---@deprecated ---@return Vector +---@nodiscard function ObjectRef:get_player_velocity() end ---**Player Only** @@ -350,6 +481,7 @@ function ObjectRef:add_player_velocity(vel) end --- ---Get camera direction as a unit vector. ---@return Vector +---@nodiscard function ObjectRef:get_look_dir() end ---**Player Only** @@ -358,6 +490,7 @@ function ObjectRef:get_look_dir() end --- ---Angle ranges between `-pi/2` and `pi/2`, which are straight up and down respectively. ---@return number +---@nodiscard function ObjectRef:get_look_vertical() end ---**Player Only** @@ -374,6 +507,7 @@ function ObjectRef:set_look_vertical(radians) end --- ---Angle is counter-clockwise from the +z direction. ---@return number +---@nodiscard function ObjectRef:get_look_horizontal() end ---**Player Only** @@ -393,6 +527,7 @@ function ObjectRef:set_look_horizontal(radians) end ---**DEPRECATED AS BROKEN**, use `get_look_vertical()`. ---@deprecated ---@return number +---@nodiscard function ObjectRef:get_look_pitch() end ---**Player Only** @@ -415,6 +550,7 @@ function ObjectRef:set_look_pitch(rad) end ---**DEPRECATED AS BROKEN**, use `get_look_horizontal()`. ---@deprecated ---@return number +---@nodiscard function ObjectRef:get_look_yaw() end ---**Player Only** @@ -435,6 +571,7 @@ function ObjectRef:set_look_yaw(rad) end --- * max: bubbles bar is not shown --- * see [object_properties] for more information ---@return integer +---@nodiscard function ObjectRef:get_breath() end ---**Player Only** @@ -460,6 +597,7 @@ function ObjectRef:set_fov(fov, is_multiplier, transition_time) end ---@return number fov FOV value. Returns `0` if an FOV override doesn't exist. ---@return boolean is_multiplier Set to `true` if the FOV value is a multiplier. ---@return number transition_time Time (in seconds) to reach target FOV. +---@nodiscard function ObjectRef:get_fov() end ---**Player Only** @@ -486,12 +624,14 @@ function ObjectRef:set_attribute(attribute, value) end ---@deprecated ---@param attribute string ---@return string? +---@nodiscard function ObjectRef:get_attribute(attribute) end ---**Player Only** --- ---Returns a `PlayerMetaRef` ---@return PlayerMetaRef +---@nodiscard function ObjectRef:get_meta() end ---**Player Only** @@ -524,6 +664,7 @@ function ObjectRef:set_formspec_prepend(formspec) end --- ---Returns `{}` if object isn't a player. ---@return {up: boolean, down: boolean, left: boolean, right: boolean, jump: boolean, aux1: boolean, sneak: boolean, dig: boolean, place: boolean, LMB: boolean, RMB: boolean, zoom: boolean} +---@nodiscard function ObjectRef:get_player_control() end ---**Player Only** @@ -544,34 +685,22 @@ function ObjectRef:get_player_control() end --- ---Returns `0` (no bits set) if the object is not a player. ---@return integer +---@nodiscard function ObjectRef:get_player_control_bits() end ---@class physics_override -local physics_override = {} - ---Multiplier to default walking speed value (default: `1`) ----@type number -physics_override.speed = nil - +---@field speed number ---Multiplier to default jump value (default: `1`) ----@type number -physics_override.jump = nil - +---@field jump number ---Multiplier to default gravity value (default: `1`) ----@type number -physics_override.gravity = nil - +---@field gravity number ---Whether player can sneak (default: `true`) ----@type boolean -physics_override.sneak = nil - +---@field sneak boolean ---Whether player can use the new move code replications of the old sneak side-effects: sneak ladders and 2 node sneak jump (default: `false`) ----@type boolean -physics_override.sneak_glitch = nil - +---@field sneak_glitch boolean ---Use new move/sneak code. When `false` the exact old code is used for the specific old sneak behaviour (default: `true`) ----@type boolean -physics_override.new_move = nil +---@field new_move boolean ---**Player Only** --- @@ -583,66 +712,48 @@ function ObjectRef:set_physics_override(override_table) end --- ---Returns the table given to `set_physics_override`. ---@return physics_override +---@nodiscard function ObjectRef:get_physics_override() end --TODO: improve self documentation of hud definition using minetest modding book ----@class hud_definition -local hud_definition = {} +---@class hud_definition ---Type of element. ----@type '"image"'|'"text"'|'"statbar"'|'"inventory"'|'"waypoint"'|'"image_waypoint"'|'"compass"'|'"minimap"' -hud_definition.type = nil - +---@field type '"image"'|'"text"'|'"statbar"'|'"inventory"'|'"waypoint"'|'"image_waypoint"'|'"compass"'|'"minimap"' ---Position of the element, starting from the top left corner of the screen. --- ---`{x=0.5, y=0.5}` would place the element at the center of the screen while `{x=0, y=0}` would keep it in the top left corner. ----@type {x: number, y: number} -hud_definition.position = nil - ----Name of the element ----@type string -hud_definition.name = nil - ----@type {x: number, y: number} -hud_definition.scale = nil - ----@type string -hud_definition.text = nil - ----@type string -hud_definition.text2 = nil - ----@type number -hud_definition.number = nil - +---@field position {x: number, y: number} +---Name of the element. +---@field name string +---@field scale {x: number, y: number} +---@field text string +---@field text2 string +---@field number number ---**TYPE: inventory** --- ---Selected item in inventory. 0 for no item selected. ----@type integer -hud_definition.item = nil - +---@field item integer ---Direction: `0`: left-right, `1`: right-left, `2`: top-bottom, `3`: bottom-top ----@type 0|1|2|3 -hud_definition.direction = nil - ----@type {x: number, y: number} -hud_definition.alignment = nil - ----@type {x: number, y: number} -hud_definition.offset = nil - ----Size of the element in pixels. ----@type {x: number, y: number} -hud_definition.size = nil - +---@field direction 0|1|2|3 +---@field alignment {x: number, y: number} +---@field offset {x: number, y: number} +---@field size {x: number, y: number} ---Lower z-index HUDs are displayed behind higher z-index HUDs. ----@type integer -hud_definition.z_index = nil - +--- +---* `-400`: Graphical effects, such as vignette +---* `-300`: Name tags, waypoints +---* `-200`: Wieldhand +---* `-100`: Things that block the player's view, e.g. masks +---* `0`: Default. For standard in-game HUD elements like crosshair, hotbar, minimap, builtin statbars, etc +---* `100`: Temporary text messages or notification icons +---* `1000`: Full-screen effects such as full-black screen or credits. This includes effects that cover the entire screen +---* `Other`: If your HUD element doesn't fit into any category, pick a number between the suggested values +---@field z_index integer ---Defint font style for "text" elements: bitfield with `1` = bold, `2` = italic, `4` = monospace ----@type integer -hud_definition.style = nil +---@field style integer + ---**Player Only** --- @@ -661,7 +772,7 @@ function ObjectRef:hud_remove(id) end --- ---Change a value of a previously added HUD element. ---@param id integer ----@param stat '"position"'|'"name"'|'"scale"'|'"text"'|'"number"'|'"item"' +---@param stat '"position"'|'"name"'|'"scale"'|'"text"'|'"text2"'|'"number"'|'"item"'|'"direction"'|'"alignment"'|'"offset"'|'"world_pos"'|'"size"'|'"z_index"'|'"style"' ---@param value any function ObjectRef:hud_change(id, stat, value) end @@ -670,6 +781,7 @@ function ObjectRef:hud_change(id, stat, value) end ---Returns the HUD element definition structure of the specified ID ---@param id integer ---@return hud_definition? +---@nodiscard function ObjectRef:hud_get(id) end ---@class hud_flags @@ -692,6 +804,7 @@ function ObjectRef:hud_set_flags(flags) end --- ---Returns player HUD flags. ---@return hud_flags +---@nodiscard function ObjectRef:hud_get_flags() end ---**Player Only** @@ -704,6 +817,7 @@ function ObjectRef:hud_set_hotbar_itemcount(count) end --- ---Returns number of slots shown in builtin hotbar. ---@return integer +---@nodiscard function ObjectRef:hud_get_hotbar_itemcount() end ---**Player Only** @@ -716,6 +830,7 @@ function ObjectRef:hud_set_hotbar_image(texturename) end --- ---Returns hotbar background image. ---@return string +---@nodiscard function ObjectRef:hud_get_hotbar_image() end ---**Player Only** @@ -728,6 +843,7 @@ function ObjectRef:hud_set_hotbar_selected_image(texturename) end --- ---Returns selected hotbar background image. ---@return string +---@nodiscard function ObjectRef:hud_get_hotbar_selected_image() end --FIXME: unclear lua_api doc @@ -740,93 +856,61 @@ function ObjectRef:hud_get_hotbar_selected_image() end function ObjectRef:set_minimap_modes(modes, selected_mode) end ---@class sky_parameters -local sky_parameters = {} - ---Fog color in "skybox" and "plain" modes. ----@type ColorSpec -sky_parameters.base_color = nil - +---@field base_color ColorSpec --- Available types: ---* `"regular"`: Uses 0 textures, `base_color` ignored ---* `"skybox"`: Uses 6 textures, `base_color` used as fog. ---* `"plain"`: Uses 0 textures, `base_color` used as both fog and sky. ----@type '"regular"'|'"skybox"'|'"plain"' -sky_parameters.type = nil - +---@field type '"regular"'|'"skybox"'|'"plain"' ---A table containing up to six textures in the following order: --- ---Y+ (top), Y- (bottom), X- (west), X+ (east), Z+ (north), Z- (south) ----@type string[] -sky_parameters.textures = nil - +---@field textures string[] ---Whether clouds appear. (default: `true`) ----@type boolean -sky_parameters.clouds = nil - +---@field clouds boolean ---A table used in `"regular"` type only, containing sky color values (alpha is ignored): ----@type sky_color -sky_parameters.sky_color = {} +---@field sky_color sky_color ---@class sky_color -local sky_color = {} - ---For the top half of the sky during the day. (default: `#61b5f5`) ----@type ColorSpec -sky_color.day_sky = nil - +---@field day_sky ColorSpec ---For the bottom half of the sky during the day. (default: `#90d3f6`) ----@type ColorSpec -sky_color.day_horizon = nil - +---@field day_horizon ColorSpec ---For the top half of the sky during dawn/sunset. (default: `#b4bafa`) --- ---The resulting sky color will be a dark version of the ColorSpec. --- ---**Warning:** The darkening of the ColorSpec is subject to change. ----@type ColorSpec -sky_color.dawn_sky = nil - +---@field dawn_sky ColorSpec ---For the bottom half of the sky during dawn/sunset. (default: `#bac1f0`) --- ---The resulting sky color will be a dark version of the ColorSpec. --- ---**Warning:** The darkening of the ColorSpec is subject to change. ----@type ColorSpec -sky_color.dawn_horizon = nil - +---@field dawn_horizon ColorSpec ---For the top half of the sky during the night. (default: `#006bff`) --- ---The resulting sky color will be a dark version of the ColorSpec. --- ---**Warning:** The darkening of the ColorSpec is subject to change. ----@type ColorSpec -sky_color.night_sky = nil - +---@field night_sky ColorSpec ---For the bottom half of the sky during the night. (default: `#4090ff`) --- ---The resulting sky color will be a dark version of the ColorSpec. --- ---**Warning:** The darkening of the ColorSpec is subject to change. ----@type ColorSpec -sky_color.night_horizon = nil - +---@field night_horizon ColorSpec ---For when you're either indoors or underground. (default: `#646464`) ----@type ColorSpec -sky_color.indoors = nil - +---@field indoors ColorSpec ---Changes the fog tinting for the sun at sunrise and sunset. (default: `#f47d1d`) ----@type ColorSpec -sky_color.fog_sun_tint = nil - +---@field fog_sun_tint ColorSpec ---Changes the fog tinting for the moon at sunrise and sunset. (default: `#7f99cc`) ----@type ColorSpec -sky_color.fog_moon_tint = nil - +---@field fog_moon_tint ColorSpec ---Changes which mode the directional fog abides by, `"custom"` uses `sun_tint` and `moon_tint`, while `"default"` uses the classic Minetest sun and moon tinting. --- ---Will use tonemaps, if set to `"default"`. (default: `"default"`) ----@type '"default"'|'"custom"' -sky_color.fog_tint_type = nil +---@field fog_tint_type '"default"'|'"custom"' ---**Player Only** --- @@ -841,6 +925,7 @@ function ObjectRef:set_sky(sky_parameters) end ---Returns sky settings. ---@param as_table? boolean Determines whether the deprecated version of this function is being used. (see lua_api.txt for more infos) ---@return sky_parameters +---@nodiscard function ObjectRef:get_sky(as_table) end ---**Player Only** @@ -850,38 +935,26 @@ function ObjectRef:get_sky(as_table) end ---**DEPRECATED:** Use `get_sky(as_table)` instead. ---@deprecated ---@return sky_color +---@nodiscard function ObjectRef:get_sky_color() end ---@class sun_parameters -local sun_parameters = {} - ---Whether the sun is visible. (default: `true`) ----@type boolean -sun_parameters.visible = nil - +---@field visible boolean ---A regular texture for the sun. --- ---Setting to `""` will re-enable the mesh sun. --- ---Default: `"sun.png"`, if it exists. ----@type string -sun_parameters.texture = nil - +---@field texture string ---A 512x1 texture containing the tonemap for the sun (default: `"sun_tonemap.png"`) ----@type string -sun_parameters.tonemap = nil - +---@field tonemap string ---A regular texture for the sunrise texture. (default: `"sunrisebg.png"`) ----@type string -sun_parameters.sunrise = nil - +---@field sunrise string ---Whether the sunrise texture is visible. (default: `true`) ----@type boolean -sun_parameters.sunrise_visible = nil - +---@field sunrise_visible boolean ---Float controlling the overall size of the sun. (default: `1`) ----@type number -sun_parameters.scale = nil +---@field scale number ---**Player Only** --- @@ -895,15 +968,12 @@ function ObjectRef:set_sun(parameters) end --- ---Returns the current sun settings. ---@return sun_parameters +---@nodiscard function ObjectRef:get_sun() end ---@class moon_parameters -local moon_parameters = {} - ---Whether the moon is visible. (default: `true`) ----@type boolean -moon_parameters.visible = nil - +---@field visible boolean ---A regular texture for the moon. --- ---Setting to `""` will re-enable the mesh moon. @@ -911,16 +981,11 @@ moon_parameters.visible = nil ---Default: `"moon.png"`, if it exists. --- ---Note: Relative to the sun, the moon texture is rotated by 180°. You can use the `^[transformR180` texture modifier to achieve the same orientation. ----@type string -moon_parameters.texture = nil - +---@field texture string ---A 512x1 texture containing the tonemap for the moon (default: `"sun_tonemap.png"`) ----@type string -moon_parameters.tonemap = nil - +---@field tonemap string ---Float controlling the overall size of the moon. (default: `1`) ----@type number -moon_parameters.scale = nil +---@field scale number ---**Player Only** --- @@ -934,28 +999,20 @@ function ObjectRef:set_moon(parameters) end --- ---Returns the current moon settings. ---@return moon_parameters +---@nodiscard function ObjectRef:get_moon() end ---@class star_parameters -local star_parameters = {} - ---Whether the stars are visible. (default: `true`) ----@type boolean -star_parameters.visible = nil - +---@field visible boolean ---The number of stars in the skybox. --- ---Only applies to `"skybox"` and `"regular"` sky types. (default: `1000`) ----@type integer -star_parameters.count = nil - +---@field count integer ---The color of the stars, alpha channel is used to set overall star brightness. (default: `#ebebff69`) ----@type ColorSpec -star_parameters.star_color = nil - +---@field star_color ColorSpec ---Float controlling the overall size of the stars. (default: `1`) ----@type number -star_parameters.scale = nil +---@field scale number ---**Player Only** --- @@ -969,36 +1026,24 @@ function ObjectRef:set_stars(parameters) end --- ---Returns the current star settings. ---@return star_parameters +---@nodiscard function ObjectRef:get_stars() end ---@class cloud_parameters -local cloud_parameters = {} - ---Cloud density. --- ---From `0` (no clouds) to `1` (full clouds) (default `0.4`) ----@type number -cloud_parameters.density = nil - +---@field density number ---Cloud color with alpha channel (default `#fff0f0e5`). ----@type ColorSpec -cloud_parameters.color = nil - +---@field color ColorSpec ---Cloud color lower bound, use for a "glow at night" effect (alpha ignored, default `#000000`). ----@type ColorSpec -cloud_parameters.ambient = nil - +---@field ambient ColorSpec ---Cloud height (default per conf, usually `120`). ----@type integer -cloud_parameters.height = nil - +---@field height integer ---Cloud thickness in nodes (default `16`). ----@type integer -cloud_parameters.thickness = nil - +---@field thickness integer ---2D cloud speed + direction in nodes per second (default `{x=0, z=-2}`). ----@type {x: number, y: number} -cloud_parameters.speed = nil +---@field speed {x: number, y: number} ---**Player Only** --- @@ -1012,6 +1057,7 @@ function ObjectRef:set_clouds(parameters) end --- ---Returns the current cloud settings. ---@return cloud_parameters +---@nodiscard function ObjectRef:get_clouds() end ---**Player Only** @@ -1026,6 +1072,7 @@ function ObjectRef:override_day_night_ratio(ratio) end --- ---Returns the current day-night ratio or `nil` if no override is active. ---@return number? +---@nodiscard function ObjectRef:get_day_night_ratio() end ---**Player Only** @@ -1048,6 +1095,7 @@ function ObjectRef:set_local_animation(idle, walk, dig, walk_while_dig, frame_sp ---@return {x: integer, y: integer} dig ---@return {x: integer, y: integer} walk_while_dig ---@return integer frame_speed +---@nodiscard function ObjectRef:get_local_animation() end ---**Player Only** @@ -1064,6 +1112,7 @@ function ObjectRef:set_eye_offset(firstperson, thirdperson) end ---Returns first and third person offsets. ---@return Vector firstperson ---@return Vector thirdperson +---@nodiscard function ObjectRef:get_eye_offset() end ---**Player Only** @@ -1080,12 +1129,9 @@ function ObjectRef:get_eye_offset() end function ObjectRef:send_mapblock(blockpos) end ---@class light_definition -local light_definition = {} - ---Controls ambient shadows. ---* `intensity` sets the intensity of the shadows from 0 (no shadows, default) to 1 (blackness) ----@type {intensity: number} -light_definition.shadows = nil +---@field shadows {intensity: number} ---**Player Only** --- @@ -1097,4 +1143,5 @@ function ObjectRef:set_lighting(definition) end --- ---Returns the current lighting of the player. ---@return light_definition +---@nodiscard function ObjectRef:get_lighting() end diff --git a/classes/pcgrandom.lua b/classes/pcgrandom.lua index 2806f16..a86ba59 100644 --- a/classes/pcgrandom.lua +++ b/classes/pcgrandom.lua @@ -2,7 +2,7 @@ ---A 32-bit pseudorandom number generator. ---Uses PCG32, an algorithm of the permuted congruential generator family, offering very strong randomness. ----@class PcgRandom +---@class PcgRandom: userdata local pcg_random = {} ---Returns next random integer. @@ -11,6 +11,7 @@ local pcg_random = {} ---@param min? integer ---@param max? integer ---@return integer +---@nodiscard function pcg_random:next(min, max) end ---Return normally distributed random number between `min` and `max`. @@ -23,6 +24,7 @@ function pcg_random:next(min, max) end ---@param max integer ---@param num_trials integer Default: 6 ---@return integer +---@nodiscard function pcg_random:rand_normal_dist(min, max, num_trials) end --FIXME: document params @@ -31,4 +33,5 @@ function pcg_random:rand_normal_dist(min, max, num_trials) end ---@param seed number ---@param sequence? any ---@return PcgRandom +---@nodiscard function PcgRandom(seed, sequence) end diff --git a/classes/pseudorandom.lua b/classes/pseudorandom.lua index a11c014..5775edd 100644 --- a/classes/pseudorandom.lua +++ b/classes/pseudorandom.lua @@ -16,9 +16,11 @@ local pseudo_random = {} ---@param min? integer ---@param max? integer ---@return integer +---@nodiscard function pseudo_random:next(min, max) end ---Create a PseudoRandom generator. ---@param seed number ---@return PseudoRandom +---@nodiscard function PseudoRandom(seed) end diff --git a/classes/raycast.lua b/classes/raycast.lua index ba1d001..0552781 100644 --- a/classes/raycast.lua +++ b/classes/raycast.lua @@ -5,39 +5,34 @@ ---Create a Raycast ---@param pos1 Vector Start of the ray ---@param pos2 Vector End of the ray ----@param objects boolean If `false`, only nodes will be returned. Default is `true`. ----@param liquids boolean If `false`, liquid nodes (`liquidtype ~= "none"`) won't be returned. Default is `false`. +---@param objects? boolean If `false`, only nodes will be returned. Default is `true`. +---@param liquids? boolean If `false`, liquid nodes (`liquidtype ~= "none"`) won't be returned. Default is `false`. ---@return Raycast +---@nodiscard function Raycast(pos1, pos2, objects, liquids) end minetest.raycast = Raycast ---@class pointed_thing_raycast: pointed_thing -local pointed_thing_raycast = {} - ---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. ----@type Vector -pointed_thing_raycast.intersection_point = nil - +---@field intersection_point Vector ---The ID of the pointed selection box (counting starts from 1). ----@type integer -pointed_thing_raycast.box_id = nil - +---@field box_id integer ---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. ----@type Vector -pointed_thing_raycast.intersection_normal = nil +---@field intersection_normal Vector ----@class Raycast +---@class Raycast: userdata local raycast = {} ---Returns a `pointed_thing` with exact pointing location. --- ---Returns the next thing pointed by the ray or nil. ---@return pointed_thing_raycast? +---@nodiscard function raycast:next() end diff --git a/classes/securerandom.lua b/classes/securerandom.lua index 282822b..3d794bf 100644 --- a/classes/securerandom.lua +++ b/classes/securerandom.lua @@ -7,8 +7,10 @@ local secure_random = {} ---Return next `count` many random bytes, as a string. ---@param count? integer Default: 1, Max: 2048 ---@return string +---@nodiscard function secure_random:next_bytes(count) end ---Returns nil if a secure random device cannot be found on the system. ---@return SecureRandom? +---@nodiscard function SecureRandom() end diff --git a/classes/settings.lua b/classes/settings.lua index afc2228..b49aa21 100644 --- a/classes/settings.lua +++ b/classes/settings.lua @@ -3,6 +3,7 @@ ---Returns a `Settings` object ---@param filename string ---@return Settings +---@nodiscard function Settings(filename) end ---The settings have the format `key = value`. @@ -12,6 +13,7 @@ local settings = {} ---Returns a value. ---@param key string ---@return string +---@nodiscard function settings:get(key) end ---Returns a boolean. @@ -20,17 +22,20 @@ function settings:get(key) end ---@param key string ---@param default? boolean ---@return boolean? +---@nodiscard function settings:get_bool(key, default) end ---Returns a `NoiseParams` table. ---@param key string ---@return noise_params +---@nodiscard function settings:get_np_group(key) end --- * Returns `{flag = true/false, ...}` according to the set flags. --- * Is currently limited to mapgen flags `mg_flags` and mapgen-specific flags like `mgv5_spflags`. ---@param key string ---@return table +---@nodiscard function settings:get_flags(key) end --- * Setting names can't contain whitespace or any of `="{}#`. @@ -56,7 +61,8 @@ function settings:set_np_group(key, value) end function settings:remove(key) end ---Returns `{key1,...}`. ----@return table +---@return string[] +---@nodiscard function settings:get_names() end ---Writes changes to file. @@ -66,7 +72,7 @@ function settings:get_names() end function settings:write() end ---Returns `{[key1]=value1,...}`. ----@return table +---@return table function settings:to_table() end ---Settings object containing all of the settings from the main config file (`minetest.conf`). @@ -78,4 +84,5 @@ minetest.settings = {} ---Returns a position or `nil`. ---@param name string ---@return Vector? +---@nodiscard function minetest.setting_get_pos(name) end diff --git a/classes/vector.lua b/classes/vector.lua index 3459264..29fdb29 100644 --- a/classes/vector.lua +++ b/classes/vector.lua @@ -20,10 +20,12 @@ vector = {} ---@param y number ---@param z number ---@return Vector +---@nodiscard function vector.new(x, y, z) end ---Create a new vector `(0, 0, 0)`. ---@return Vector +---@nodiscard function vector.zero() end ---Returns a copy of the vector `v`. @@ -37,11 +39,13 @@ function vector.copy(v) end ---@param init? integer If given starts looking for the vector at this string index. ---@return Vector? ---@return integer? +---@nodiscard function vector.from_string(s, init) end ---Returns a string of the form `"(x, y, z)"`. ---@param v Vector ---@return string +---@nodiscard function vector.to_string(v) end ---Returns a vector of length 1 with direction `p1` to `p2`. @@ -50,17 +54,20 @@ function vector.to_string(v) end ---@param p1 Vector ---@param p2 Vector ---@return Vector +---@nodiscard function vector.direction(p1, p2) end ---Returns zero or a positive number, the distance between `p1` and `p2`. ---@param p1 Vector ---@param p2 Vector ---@return number +---@nodiscard function vector.distance(p1, p2) end ---Returns zero or a positive number, the length of vector `v`. ---@param v Vector ---@return number +---@nodiscard function vector.length(v) end ---Returns a vector of length 1 with direction of vector `v`. @@ -68,28 +75,35 @@ function vector.length(v) end ---If `v` has zero length, returns `(0, 0, 0)`. ---@param v Vector ---@return Vector +---@nodiscard function vector.normalize(v) end ---Returns a vector, each dimension rounded down. ---@param v Vector ---@return Vector +---@nodiscard function vector.floor(v) end ---Returns a vector, each dimension rounded to nearest integer. --- ---At a multiple of `0.5`, rounds away from zero. ---@param v Vector +---@return Vector +---@nodiscard function vector.round(v) end ---Returns a vector where the function `func` has been applied to each component. ---@param v Vector ---@param func fun(i: number):number +---@return Vector +---@nodiscard function vector.apply(v, func) end ---Returns a boolean, `true` if the vectors are identical. ---@param a Vector ---@param b Vector ---@return boolean +---@nodiscard function vector.equals(a, b) end ---Returns in order `minp`, `maxp` vectors of the cuboid defined by `v1`, `v2`. @@ -97,12 +111,14 @@ function vector.equals(a, b) end ---@param v2 Vector ---@return Vector minp ---@return Vector maxp +---@nodiscard function vector.sort(v1, v2) end ---Returns the angle between `v1` and `v2` in radians. ---@param v1 Vector ---@param v2 Vector ---@return number +---@nodiscard function vector.angle(v1, v2) end ---Returns the dot product of `v1` and `v2`. @@ -115,6 +131,7 @@ function vector.dot(v1, v2) end ---@param v1 Vector ---@param v2 Vector ---@return Vector +---@nodiscard function vector.cross(v1, v2) end ---Returns the sum of the vectors `v` and `(x, y, z)`. @@ -123,6 +140,7 @@ function vector.cross(v1, v2) end ---@param y number ---@param z number ---@return Vector +---@nodiscard function vector.offset(v, x, y, z) end ---Returns a boolean value indicating whether `v` is a real vector, eg. created by a `vector.*` function. @@ -130,6 +148,7 @@ function vector.offset(v, x, y, z) end ---Returns `false` for anything else, including tables like `{x=3,y=1,z=4}`. ---@param v Vector ---@return boolean +---@nodiscard function vector.check(v) end ---If `x` is a vector: Returns the sum of `v` and `x`. @@ -138,6 +157,7 @@ function vector.check(v) end ---@param v Vector ---@param x Vector | number ---@return Vector +---@nodiscard function vector.add(v, x) end ---If `x` is a vector: Returns the difference of `v` subtracted by `x`. @@ -146,24 +166,28 @@ function vector.add(v, x) end ---@param v Vector ---@param x Vector | number ---@return Vector +---@nodiscard function vector.subtract(v, x) end ---Returns a scaled vector. ---@param v Vector ---@param s number ---@return Vector +---@nodiscard function vector.multiply(v, s) end ---Returns a scaled vector. ---@param v Vector ---@param s number ---@return Vector +---@nodiscard function vector.divide(v, s) end ---Applies the rotation `r` (in radians) to `v` and returns the result. ---@param v Vector ---@param r number ---@return Vector +---@nodiscard function vector.rotate(v, r) end ---Returns `v1` rotated around axis `v2` by `a` radians according to the right hand rule. @@ -171,6 +195,7 @@ function vector.rotate(v, r) end ---@param v2 Vector ---@param a number ---@return Vector +---@nodiscard function vector.rotate_around_axis(v1, v2, a) end ---Returns a rotation vector for `direction` pointing forward using `up` as the up vector. @@ -180,4 +205,6 @@ function vector.rotate_around_axis(v1, v2, a) end ---Otherwise `direction` and `up` need to be vectors in a 90 degree angle to each other. ---@param direction Vector ---@param up? Vector +---@return Vector +---@nodiscard function vector.dir_to_rotation(direction, up) end diff --git a/classes/voxelarea.lua b/classes/voxelarea.lua index 042fb8a..3336aa5 100644 --- a/classes/voxelarea.lua +++ b/classes/voxelarea.lua @@ -1,31 +1,26 @@ ---@meta ---@class VoxelArea +---@field MinEdge Vector +---@field MaxEdge Vector +---@field ystride number +---@field zstride number VoxelArea = {} ----@type Vector -VoxelArea.MinEdge = nil - ----@type Vector -VoxelArea.MaxEdge = nil - ----@type number -VoxelArea.ystride = nil - ----@type number -VoxelArea.zstride = nil - ---Create a new `VoxelArea`. ---@param o {MinEdge: Vector, MaxEdge: Vector} ---@return VoxelArea +---@nodiscard function VoxelArea:new(o) end ---Returns a 3D vector containing the size of the area formed by `MinEdge` and `MaxEdge`. ---@return Vector +---@nodiscard function VoxelArea:getExtent() end ---Returns the volume of the area formed by `MinEdge` and `MaxEdge`. ---@return number +---@nodiscard function VoxelArea:getVolume() end ---Returns the index of an absolute position in a flat array starting at `1`. @@ -36,6 +31,7 @@ function VoxelArea:getVolume() end ---@param y integer ---@param z integer ---@return integer +---@nodiscard function VoxelArea:index(x, y, z) end ---Same functionality as `VoxelArea:index(x, y, z)` but takes a vector as param. @@ -43,11 +39,13 @@ function VoxelArea:index(x, y, z) end ---As with `index(x, y, z)`, the components of `p` must be integers, and `p` is not checked for being inside the area volume. ---@param p Vector ---@return integer +---@nodiscard function VoxelArea:indexp(p) end ---Returns the absolute position vector corresponding to index `i`. ---@param i integer ---@return Vector +---@nodiscard function VoxelArea:position(i) end ---Check if (`x`,`y`,`z`) is inside area formed by `MinEdge` and `MaxEdge`. @@ -55,15 +53,19 @@ function VoxelArea:position(i) end ---@param y number ---@param z number ---@return boolean +---@nodiscard function VoxelArea:contains(x, y, z) end ---Same functionality as `VoxelArea:contains(x, y, z)` but takes a vector as param. ---@param p Vector ---@return boolean +---@nodiscard function VoxelArea:containsp(p) end ---Same functionality as `VoxelArea:contains(x, y, z)` but takes an index as param. ---@param i integer +---@return boolean +---@nodiscard function VoxelArea:containsi(i) end ---Returns an iterator that returns indices. @@ -75,9 +77,11 @@ function VoxelArea:containsi(i) end ---@param maxx integer ---@param maxy integer ---@param maxz integer +---@nodiscard function VoxelArea:iter(minx, miny, minz, maxx, maxy, maxz) end ---Same functionality as `VoxelArea:iter(minx, miny, minz, maxx, maxy, maxz)` but takes vector as params. ---@param minp Vector ---@param maxp Vector +---@nodiscard function VoxelArea:iterp(minp, maxp) end diff --git a/classes/voxelmanip.lua b/classes/voxelmanip.lua index 580d717..8bf13b6 100644 --- a/classes/voxelmanip.lua +++ b/classes/voxelmanip.lua @@ -34,12 +34,13 @@ function VoxelManip:read_from_map(p1, p2) end ---* If `light` is `false`, no light calculations happen, and you should correct all modified blocks with `minetest.fix_light()` as soon as possible. --- ---Keep in mind that modifying the map where light is incorrect can cause more lighting bugs. ----@param light boolean +---@param light? boolean function VoxelManip:write_to_map(light) end ---Returns node table of the node currently loaded in the `VoxelManip` at that position. ---@param pos Vector ---@return node +---@nodiscard function VoxelManip:get_node_at(pos) end ---Sets a specific node in the `VoxelManip` at that position. @@ -54,6 +55,7 @@ function VoxelManip:set_node_at(pos, node) end ---If the param `buffer` is present, this table will be used to store the result instead. ---@param buffer? table ---@return integer[] +---@nodiscard function VoxelManip:get_data(buffer) end ---Sets the data contents of the `VoxelManip` object. @@ -82,6 +84,7 @@ function VoxelManip:set_lighting(light, p1, p2) end --- ---`light = day + (night * 16)` ---@return integer[] +---@nodiscard function VoxelManip:get_light_data() end ---Sets the light data of each node in the `VoxelManip` object. @@ -97,6 +100,7 @@ function VoxelManip:set_light_data(light_data) end ---If the param `buffer` is present, this table will be used to store the result instead. ---@param buffer? table ---@return integer[]? +---@nodiscard function VoxelManip:get_param2_data(buffer) end ---Sets the `param2` contents of each node in the `VoxelManip` object. @@ -122,9 +126,11 @@ function VoxelManip:update_liquids() end ---Returns `true` or `false` if the data in the voxel manipulator had been modified since the last read from map, due to a call to `minetest.set_data()` on the loaded area elsewhere. ---@return boolean +---@nodiscard function VoxelManip:was_modified() end ---Returns actual emerged minimum and maximum positions. ---@return Vector pmin ---@return Vector pmax +---@nodiscard function VoxelManip:get_emerged_area() end diff --git a/colors.lua b/colors.lua index 8b295e0..80f606a 100644 --- a/colors.lua +++ b/colors.lua @@ -11,12 +11,14 @@ ---The escape sequence sets the text color to `color` ---@param color ColorString ---@return string +---@nodiscard function minetest.get_color_escape_sequence(color) end ---Equivalent to: `minetest.get_color_escape_sequence(color)..message..minetest.get_color_escape_sequence("#ffffff")` ---@param color ColorString ---@param message string ---@return string +---@nodiscard function minetest.colorize(color, message) end ---The escape sequence sets the background of the whole text element to `color`. @@ -24,29 +26,35 @@ function minetest.colorize(color, message) end ---Only defined for item descriptions and tooltips. ---@param color ColorString ---@return string +---@nodiscard function minetest.get_background_escape_sequence(color) end ---Removes foreground colors added by `get_color_escape_sequence`. ---@param str string ---@return string +---@nodiscard function minetest.strip_foreground_colors(str) end ---Removes background colors added by `get_background_escape_sequence`. ---@param str string ---@return string +---@nodiscard function minetest.strip_background_colors(str) end ---Removes all color escape sequences. ---@param str string ---@return string +---@nodiscard function minetest.strip_colors(str) end ---Converts a `ColorSpec` to a `ColorString`. If the `ColorSpec` is invalid, returns `nil`. ---@param colorspec ColorSpec ---@return ColorString? +---@nodiscard function minetest.colorspec_to_colorstring(colorspec) end ---Converts a `ColorSpec` to a raw string of four bytes in an RGBA layout, returned as a string. ---@param colorspec ColorSpec ---@return string +---@nodiscard function minetest.colorspec_to_bytes(colorspec) end diff --git a/config.lua b/config.lua index 8346ee0..2384a8b 100644 --- a/config.lua +++ b/config.lua @@ -1,3 +1,5 @@ +---@diagnostic disable:lowercase-global + name = "Minetest" files = { diff --git a/const.lua b/const.lua index b94c0b8..53ba9c2 100644 --- a/const.lua +++ b/const.lua @@ -43,6 +43,14 @@ minetest.EMERGE_FROM_DISK = 3 minetest.EMERGE_GENERATED = 4 +---@alias emerge_status +---| `minetest.EMERGE_CANCELLED` +---| `minetest.EMERGE_ERRORED` +---| `minetest.EMERGE_FROM_MEMORY` +---| `minetest.EMERGE_FROM_DISK` +---| `minetest.EMERGE_GENERATED` + + ---Directory separator in use on the system. ---@type '"/"'|'"\\\\"' DIR_DELIM = nil diff --git a/log.lua b/log.lua index 519aa15..4b43529 100644 --- a/log.lua +++ b/log.lua @@ -9,5 +9,5 @@ function minetest.log(level, message) end ---Equivalent to `minetest.log(table.concat({...}, "\t"))` ----@vararg string +---@param ... string function minetest.debug(...) end diff --git a/lua_api.txt b/lua_api.txt index b2db971..8c9f982 100644 --- a/lua_api.txt +++ b/lua_api.txt @@ -1,12 +1,10 @@ -Minetest Lua Modding API Reference -================================== +# Minetest Lua Modding API Reference -* More information at -* Developer Wiki: -* (Unofficial) Minetest Modding Book by rubenwardy: +- More information at +- Developer Wiki: +- (Unofficial) Minetest Modding Book by rubenwardy: -Introduction ------------- +## Introduction Content and functionality can be added to Minetest using Lua scripting in run-time loaded mods. @@ -20,90 +18,82 @@ files are automatically transferred to the client. If you see a deficiency in the API, feel free to attempt to add the functionality in the engine and API, and to document it here. -Programming in Lua ------------------- +## Programming in Lua If you have any difficulty in understanding this, please read [Programming in Lua](http://www.lua.org/pil/). -Startup -------- +## Startup Mods are loaded during server startup from the mod load paths by running the `init.lua` scripts in a shared environment. -Paths ------ +## Paths -* `RUN_IN_PLACE=1` (Windows release, local build) - * `$path_user`: `` - * `$path_share`: `` -* `RUN_IN_PLACE=0`: (Linux release) - * `$path_share`: - * Linux: `/usr/share/minetest` - * Windows: `/minetest-0.4.x` - * `$path_user`: - * Linux: `$HOME/.minetest` - * Windows: `C:/users//AppData/minetest` (maybe) +Minetest keeps and looks for files mostly in two paths. `path_share` or `path_user`. +`path_share` contains possibly read-only content for the engine (incl. games and mods). +`path_user` contains mods or games installed by the user but also the users +worlds or settings. +With a local build (`RUN_IN_PLACE=1`) `path_share` and `path_user` both point to +the build directory. For system-wide builds on Linux the share path is usually at +`/usr/share/minetest` while the user path resides in `.minetest` in the home directory. +Paths on other operating systems will differ. - -Games -===== +# Games Games are looked up from: -* `$path_share/games//` -* `$path_user/games//` +- `$path_share/games//` +- `$path_user/games//` Where `` is unique to each game. The game directory can contain the following files: -* `game.conf`, with the following keys: - * `title`: Required, a human-readable title to address the game, e.g. `title = Minetest Game`. - * `name`: (Deprecated) same as title. - * `description`: Short description to be shown in the content tab - * `allowed_mapgens = ` - e.g. `allowed_mapgens = v5,v6,flat` - Mapgens not in this list are removed from the list of mapgens for the - game. - If not specified, all mapgens are allowed. - * `disallowed_mapgens = ` - e.g. `disallowed_mapgens = v5,v6,flat` - These mapgens are removed from the list of mapgens for the game. - When both `allowed_mapgens` and `disallowed_mapgens` are - specified, `allowed_mapgens` is applied before - `disallowed_mapgens`. - * `disallowed_mapgen_settings= ` - e.g. `disallowed_mapgen_settings = mgv5_spflags` - These mapgen settings are hidden for this game in the world creation - dialog and game start menu. Add `seed` to hide the seed input field. - * `disabled_settings = ` - e.g. `disabled_settings = enable_damage, creative_mode` - These settings are hidden for this game in the "Start game" tab - and will be initialized as `false` when the game is started. - Prepend a setting name with an exclamation mark to initialize it to `true` - (this does not work for `enable_server`). - Only these settings are supported: - `enable_damage`, `creative_mode`, `enable_server`. - * `author`: The author of the game. It only appears when downloaded from - ContentDB. - * `release`: Ignore this: Should only ever be set by ContentDB, as it is - an internal ID used to track versions. -* `minetest.conf`: +- `game.conf`, with the following keys: + - `title`: Required, a human-readable title to address the game, e.g. `title = Minetest Game`. + - `name`: (Deprecated) same as title. + - `description`: Short description to be shown in the content tab + - `allowed_mapgens = ` + e.g. `allowed_mapgens = v5,v6,flat` + Mapgens not in this list are removed from the list of mapgens for the + game. + If not specified, all mapgens are allowed. + - `disallowed_mapgens = ` + e.g. `disallowed_mapgens = v5,v6,flat` + These mapgens are removed from the list of mapgens for the game. + When both `allowed_mapgens` and `disallowed_mapgens` are + specified, `allowed_mapgens` is applied before + `disallowed_mapgens`. + - `disallowed_mapgen_settings= ` + e.g. `disallowed_mapgen_settings = mgv5_spflags` + These mapgen settings are hidden for this game in the world creation + dialog and game start menu. Add `seed` to hide the seed input field. + - `disabled_settings = ` + e.g. `disabled_settings = enable_damage, creative_mode` + These settings are hidden for this game in the "Start game" tab + and will be initialized as `false` when the game is started. + Prepend a setting name with an exclamation mark to initialize it to `true` + (this does not work for `enable_server`). + Only these settings are supported: + `enable_damage`, `creative_mode`, `enable_server`. + - `author`: The author of the game. It only appears when downloaded from + ContentDB. + - `release`: Ignore this: Should only ever be set by ContentDB, as it is + an internal ID used to track versions. +- `minetest.conf`: Used to set default settings when running this game. -* `settingtypes.txt`: +- `settingtypes.txt`: In the same format as the one in builtin. This settingtypes.txt will be parsed by the menu and the settings will be displayed in the "Games" category in the advanced settings tab. -* If the game contains a folder called `textures` the server will load it as a +- If the game contains a folder called `textures` the server will load it as a texturepack, overriding mod textures. Any server texturepack will override mod textures and the game texturepack. -Menu images ------------ +## Menu images Games can provide custom main menu images. They are put inside a `menu` directory inside the game directory. @@ -114,8 +104,7 @@ If you want to specify multiple images for one identifier, add additional images named like `$identifier.$n.png`, with an ascending number $n starting with 1, and a random image will be chosen from the provided ones. -Menu music ------------ +## Menu music Games can provide custom main menu music. They are put inside a `menu` directory inside the game directory. @@ -125,20 +114,17 @@ If you want to specify multiple music files for one game, add additional images named like `theme.$n.ogg`, with an ascending number $n starting with 1 (max 10), and a random music file will be chosen from the provided ones. -Mods -==== +# Mods -Mod load path -------------- +## Mod load path Paths are relative to the directories listed in the [Paths] section above. -* `games//mods/` -* `mods/` -* `worlds//worldmods/` +- `games//mods/` +- `mods/` +- `worlds//worldmods/` -World-specific games --------------------- +## World-specific games It is possible to include a game in a world; in this case, no mods or games are loaded or checked from anywhere else. @@ -148,27 +134,25 @@ directory exists. Mods should then be placed in `/game/mods/`. -Modpacks --------- +## Modpacks Mods can be put in a subdirectory, if the parent directory, which otherwise should be a mod, contains a file named `modpack.conf`. The file is a key-value store of modpack details. -* `name`: The modpack name. Allows Minetest to determine the modpack name even - if the folder is wrongly named. -* `description`: Description of mod to be shown in the Mods tab of the main - menu. -* `author`: The author of the modpack. It only appears when downloaded from - ContentDB. -* `release`: Ignore this: Should only ever be set by ContentDB, as it is an - internal ID used to track versions. -* `title`: A human-readable title to address the modpack. +- `name`: The modpack name. Allows Minetest to determine the modpack name even + if the folder is wrongly named. +- `description`: Description of mod to be shown in the Mods tab of the main + menu. +- `author`: The author of the modpack. It only appears when downloaded from + ContentDB. +- `release`: Ignore this: Should only ever be set by ContentDB, as it is an + internal ID used to track versions. +- `title`: A human-readable title to address the modpack. Note: to support 0.4.x, please also create an empty modpack.txt file. -Mod directory structure ------------------------ +## Mod directory structure mods ├── modname @@ -200,21 +184,19 @@ The location of this directory can be fetched by using A `Settings` file that provides meta information about the mod. -* `name`: The mod name. Allows Minetest to determine the mod name even if the - folder is wrongly named. -* `description`: Description of mod to be shown in the Mods tab of the main - menu. -* `depends`: A comma separated list of dependencies. These are mods that must be - loaded before this mod. -* `optional_depends`: A comma separated list of optional dependencies. - Like a dependency, but no error if the mod doesn't exist. -* `author`: The author of the mod. It only appears when downloaded from - ContentDB. -* `release`: Ignore this: Should only ever be set by ContentDB, as it is an - internal ID used to track versions. -* `title`: A human-readable title to address the mod. - -Note: to support 0.4.x, please also provide depends.txt. +- `name`: The mod name. Allows Minetest to determine the mod name even if the + folder is wrongly named. +- `description`: Description of mod to be shown in the Mods tab of the main + menu. +- `depends`: A comma separated list of dependencies. These are mods that must be + loaded before this mod. +- `optional_depends`: A comma separated list of optional dependencies. + Like a dependency, but no error if the mod doesn't exist. +- `author`: The author of the mod. It only appears when downloaded from + ContentDB. +- `release`: Ignore this: Should only ever be set by ContentDB, as it is an + internal ID used to track versions. +- `title`: A human-readable title to address the mod. ### `screenshot.png` @@ -276,8 +258,7 @@ in one of its parents, the parent's file is used. Although it is discouraged, a mod can overwrite a media file of any mod that it depends on by supplying a file with an equal name. -Naming conventions ------------------- +## Naming conventions Registered names should generally be in this format: @@ -304,14 +285,10 @@ Any mod can redefine `experimental:tnt` by using the name :experimental:tnt -when registering it. That mod is required to have `experimental` as a -dependency. - - +when registering it. For this to work correctly, that mod must have +`experimental` as a dependency. - -Aliases -======= +# Aliases Aliases of itemnames can be added by using `minetest.register_alias(alias, original_name)` or @@ -334,8 +311,7 @@ you have an item called `epiclylongmodname:stuff`, you could do and be able to use `/giveme stuff`. -Mapgen aliases --------------- +## Mapgen aliases 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. For example: @@ -346,9 +322,9 @@ of the game's nodes are to be used for core mapgen generation. For example: #### Essential aliases -* mapgen_stone -* mapgen_water_source -* mapgen_river_water_source +- `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 @@ -356,58 +332,60 @@ it is necessary to have a river liquid node with a short `liquid_range` and #### Optional aliases -* mapgen_lava_source +- `mapgen_lava_source` Fallback lava node used if cave liquids are not defined in biome definitions. -Deprecated for non-V6 mapgens, define cave liquids in biome definitions instead. +Deprecated, define cave liquids in biome definitions instead. -* mapgen_cobble +- `mapgen_cobble` Fallback node used if dungeon nodes are not defined in biome definitions. -Deprecated for non-V6 mapgens, define dungeon nodes in biome definitions instead. - -### Aliases needed for Mapgen V6 - -* mapgen_stone -* mapgen_water_source -* mapgen_lava_source -* mapgen_dirt -* mapgen_dirt_with_grass -* mapgen_sand -* mapgen_gravel -* mapgen_desert_stone -* mapgen_desert_sand -* mapgen_dirt_with_snow -* mapgen_snowblock -* mapgen_snow -* mapgen_ice - -* mapgen_tree -* mapgen_leaves -* mapgen_apple -* mapgen_jungletree -* mapgen_jungleleaves -* mapgen_junglegrass -* mapgen_pine_tree -* mapgen_pine_needles - -* mapgen_cobble -* mapgen_stair_cobble -* mapgen_mossycobble -* mapgen_stair_desert_stone +Deprecated, define dungeon nodes in biome definitions instead. -### Setting the node used in Mapgen Singlenode +### Aliases for Mapgen V6 -By default the world is filled with air nodes. To set a different node use, for -example: +#### Essential - minetest.register_alias("mapgen_singlenode", "default:stone") +- `mapgen_stone` +- `mapgen_water_source` +- `mapgen_lava_source` +- `mapgen_dirt` +- `mapgen_dirt_with_grass` +- `mapgen_sand` + +- `mapgen_tree` +- `mapgen_leaves` +- `mapgen_apple` + +- `mapgen_cobble` +#### Optional +- `mapgen_gravel` (falls back to stone) +- `mapgen_desert_stone` (falls back to stone) +- `mapgen_desert_sand` (falls back to sand) +- `mapgen_dirt_with_snow` (falls back to dirt_with_grass) +- `mapgen_snowblock` (falls back to dirt_with_grass) +- `mapgen_snow` (not placed if missing) +- `mapgen_ice` (falls back to water_source) +- `mapgen_jungletree` (falls back to tree) +- `mapgen_jungleleaves` (falls back to leaves) +- `mapgen_junglegrass` (not placed if missing) +- `mapgen_pine_tree` (falls back to tree) +- `mapgen_pine_needles` (falls back to leaves) -Textures -======== +- `mapgen_stair_cobble` (falls back to cobble) +- `mapgen_mossycobble` (falls back to cobble) +- `mapgen_stair_desert_stone` (falls backto desert_stone) + +### Setting the node used in Mapgen Singlenode + +By default the world is filled with air nodes. To set a different node use e.g.: + + minetest.register_alias("mapgen_singlenode", "default:stone") + +# Textures Mods should generally prefix their textures with `modname_`, e.g. given the mod name `foomod`, a texture could be called: @@ -417,12 +395,14 @@ the mod name `foomod`, a texture could be called: Textures are referred to by their complete name, or alternatively by stripping out the file extension: -* e.g. `foomod_foothing.png` -* e.g. `foomod_foothing` +- e.g. `foomod_foothing.png` +- e.g. `foomod_foothing` +Supported texture formats are PNG (`.png`), JPEG (`.jpg`), Bitmap (`.bmp`) +and Targa (`.tga`). +Since better alternatives exist, the latter two may be removed in the future. -Texture modifiers ------------------ +## Texture modifiers There are various texture modifiers that can be used to let the client generate textures on-the-fly. @@ -465,16 +445,16 @@ on top of `cobble.png`. #### Crack -* `[crack::

` -* `[cracko::

` -* `[crack:::

` -* `[cracko:::

` +- `[crack::

` +- `[cracko::

` +- `[crack:::

` +- `[cracko:::

` Parameters: -* ``: tile count (in each direction) -* ``: animation frame count -* `

`: current animation frame +- ``: tile count (in each direction) +- ``: animation frame count +- `

`: current animation frame Draw a step of the crack animation on the texture. `crack` draws it normally, while `cracko` lays it over, keeping transparent @@ -486,11 +466,11 @@ Example: #### `[combine:x:,=:,=:...` -* ``: width -* ``: height -* ``: x position -* ``: y position -* ``: texture to combine +- ``: width +- ``: height +- ``: x position +- ``: y position +- ``: texture to combine Creates a texture of size `` times `` and blits the listed files to their specified coordinates. @@ -553,7 +533,7 @@ Example: #### `[transform` -* ``: transformation(s) to apply +- ``: transformation(s) to apply Rotates and/or flips the image. @@ -597,8 +577,8 @@ Example: #### `[verticalframe::` -* ``: animation frame count -* ``: current animation frame +- ``: animation frame count +- ``: current animation frame Crops the texture to a frame of a vertical animation. @@ -621,10 +601,10 @@ which it assumes to be a tilesheet with dimensions w,h. Colorize the textures with the given color. `` is specified as a `ColorString`. -`` is an int ranging from 0 to 255 or the word "`alpha`". If +`` is an int ranging from 0 to 255 or the word "`alpha`". If it is an int, then it specifies how far to interpolate between the colors where 0 is only the texture color and 255 is only ``. If -omitted, the alpha of `` will be used as the ratio. If it is +omitted, the alpha of `` will be used as the ratio. If it is the word "`alpha`", then each texture pixel will contain the RGB of `` and the alpha of `` multiplied by the alpha of the texture pixel. @@ -654,8 +634,7 @@ In particular consider `minetest.dynamic_add_media` and test whether using other texture modifiers could result in a shorter string than embedding a whole image, this may vary by use case. -Hardware coloring ------------------ +## Hardware coloring The goal of hardware coloring is to simplify the creation of colorful nodes. If your textures use the same pattern, and they only @@ -702,16 +681,16 @@ to one line). The indexing starts from 0. Examples: -* 16x16 palette, index = 0: the top left corner -* 16x16 palette, index = 4: the fifth pixel in the first row -* 16x16 palette, index = 16: the pixel below the top left corner -* 16x16 palette, index = 255: the bottom right corner -* 2 (width) x 4 (height) palette, index = 31: the top left corner. +- 16x16 palette, index = 0: the top left corner +- 16x16 palette, index = 4: the fifth pixel in the first row +- 16x16 palette, index = 16: the pixel below the top left corner +- 16x16 palette, index = 255: the bottom right corner +- 2 (width) x 4 (height) palette, index = 31: the top left corner. The palette has 8 pixels, so each pixel is stretched to 32 pixels, to ensure the total 256 pixels. -* 2x4 palette, index = 32: the top right corner -* 2x4 palette, index = 63: the top right corner -* 2x4 palette, index = 64: the pixel below the top left corner +- 2x4 palette, index = 32: the top right corner +- 2x4 palette, index = 63: the top right corner +- 2x4 palette, index = 64: the pixel below the top left corner #### Using palettes with items @@ -729,31 +708,31 @@ a texture. You can also use texture modifiers. The node's color depends on its `param2`, so you also must set an appropriate `paramtype2`: -* `paramtype2 = "color"` for nodes which use their full `param2` for +- `paramtype2 = "color"` for nodes which use their full `param2` for palette indexing. These nodes can have 256 different colors. The palette should contain 256 pixels. -* `paramtype2 = "colorwallmounted"` for nodes which use the first +- `paramtype2 = "colorwallmounted"` for nodes which use the first five bits (most significant) of `param2` for palette indexing. The remaining three bits are describing rotation, as in `wallmounted` paramtype2. Division by 8 yields the palette index (without stretching the palette). These nodes can have 32 different colors, and the palette should contain 32 pixels. Examples: - * `param2 = 17` is 2 * 8 + 1, so the rotation is 1 and the third (= 2 + 1) - pixel will be picked from the palette. - * `param2 = 35` is 4 * 8 + 3, so the rotation is 3 and the fifth (= 4 + 1) - pixel will be picked from the palette. -* `paramtype2 = "colorfacedir"` for nodes which use the first + - `param2 = 17` is 2 \* 8 + 1, so the rotation is 1 and the third (= 2 + 1) + pixel will be picked from the palette. + - `param2 = 35` is 4 \* 8 + 3, so the rotation is 3 and the fifth (= 4 + 1) + pixel will be picked from the palette. +- `paramtype2 = "colorfacedir"` for nodes which use the first three bits of `param2` for palette indexing. The remaining five bits are describing rotation, as in `facedir` paramtype2. Division by 32 yields the palette index (without stretching the palette). These nodes can have 8 different colors, and the palette should contain 8 pixels. Examples: - * `param2 = 17` is 0 * 32 + 17, so the rotation is 17 and the - first (= 0 + 1) pixel will be picked from the palette. - * `param2 = 35` is 1 * 32 + 3, so the rotation is 3 and the - second (= 1 + 1) pixel will be picked from the palette. + - `param2 = 17` is 0 \* 32 + 17, so the rotation is 17 and the + first (= 0 + 1) pixel will be picked from the palette. + - `param2 = 35` is 1 \* 32 + 3, so the rotation is 3 and the + second (= 1 + 1) pixel will be picked from the palette. To colorize a node on the map, set its `param2` value (according to the node's paramtype2). @@ -807,8 +786,7 @@ To set the `color` field, you can use `minetest.itemstring_with_color`. Metadata field filtering in the `recipe` field are not supported yet, so the craft output is independent of the color of the ingredients. -Soft texture overlay --------------------- +## Soft texture overlay Sometimes hardware coloring is not enough, because it affects the whole tile. Soft texture overlays were added to Minetest to allow @@ -850,11 +828,7 @@ Example (colored grass block): palette = "default_foilage.png", }) - - - -Sounds -====== +# Sounds Only Ogg Vorbis files are supported. @@ -873,11 +847,11 @@ is chosen randomly from the matching sounds. When playing the sound `foomod_foosound`, the sound is chosen randomly from the available ones of the following files: -* `foomod_foosound.ogg` -* `foomod_foosound.0.ogg` -* `foomod_foosound.1.ogg` -* (...) -* `foomod_foosound.9.ogg` +- `foomod_foosound.ogg` +- `foomod_foosound.0.ogg` +- `foomod_foosound.1.ogg` +- (...) +- `foomod_foosound.9.ogg` Examples of sound parameter tables: @@ -929,8 +903,7 @@ A positional sound will only be heard by players that are within `exclude_player = name` can be applied to locationless, positional and object- bound sounds to exclude a single player from hearing them. -`SimpleSoundSpec` ------------------ +## `SimpleSoundSpec` Specifies a sound name, gain (=volume) and pitch. This is either a string or a table. @@ -940,35 +913,33 @@ the empty string for no sound. Table form has the following fields: -* `name`: Sound name -* `gain`: Volume (`1.0` = 100%) -* `pitch`: Pitch (`1.0` = 100%) +- `name`: Sound name +- `gain`: Volume (`1.0` = 100%) +- `pitch`: Pitch (`1.0` = 100%) `gain` and `pitch` are optional and default to `1.0`. Examples: -* `""`: No sound -* `{}`: No sound -* `"default_place_node"`: Play e.g. `default_place_node.ogg` -* `{name = "default_place_node"}`: Same as above -* `{name = "default_place_node", gain = 0.5}`: 50% volume -* `{name = "default_place_node", gain = 0.9, pitch = 1.1}`: 90% volume, 110% pitch +- `""`: No sound +- `{}`: No sound +- `"default_place_node"`: Play e.g. `default_place_node.ogg` +- `{name = "default_place_node"}`: Same as above +- `{name = "default_place_node", gain = 0.5}`: 50% volume +- `{name = "default_place_node", gain = 0.9, pitch = 1.1}`: 90% volume, 110% pitch -Special sound files -------------------- +## Special sound files These sound files are played back by the engine if provided. - * `player_damage`: Played when the local player takes damage (gain = 0.5) - * `player_falling_damage`: Played when the local player takes - damage by falling (gain = 0.5) - * `player_jump`: Played when the local player jumps - * `default_dig_`: Default node digging sound - (see node sound definition for details) +- `player_damage`: Played when the local player takes damage (gain = 0.5) +- `player_falling_damage`: Played when the local player takes + damage by falling (gain = 0.5) +- `player_jump`: Played when the local player jumps +- `default_dig_`: Default node digging sound + (see node sound definition for details) -Registered definitions -====================== +# Registered definitions Anything added using certain [Registration functions] gets added to one or more of the global [Registered definition tables]. @@ -982,21 +953,12 @@ Example: All nodes register with `minetest.register_node` get added to the table `minetest.registered_nodes`. -If you want to check the drawtype of a node, you could do: - - local function get_nodedef_field(nodename, fieldname) - if not minetest.registered_nodes[nodename] then - return nil - end - return minetest.registered_nodes[nodename][fieldname] - end - local drawtype = get_nodedef_field(nodename, "drawtype") - - +If you want to check the drawtype of a node, you could do it like this: + local def = minetest.registered_nodes[nodename] + local drawtype = def and def.drawtype -Nodes -===== +# Nodes Nodes are the bulk data of the world: cubes and other things that take the space of a cube. Huge amounts of them are handled efficiently, but they @@ -1017,8 +979,7 @@ They are represented by a table: them for certain automated functions. If you don't use these functions, you can use them to store arbitrary values. -Node paramtypes ---------------- +## Node paramtypes The functions of `param1` and `param2` are determined by certain fields in the node definition. @@ -1026,235 +987,232 @@ node definition. The function of `param1` is determined by `paramtype` in node definition. `param1` is reserved for the engine when `paramtype != "none"`. -* `paramtype = "light"` - * The value stores light with and without sun in its lower and upper 4 bits - respectively. - * Required by a light source node to enable spreading its light. - * Required by the following drawtypes as they determine their visual - brightness from their internal light value: - * torchlike - * signlike - * firelike - * fencelike - * raillike - * nodebox - * mesh - * plantlike - * plantlike_rooted -* `paramtype = "none"` - * `param1` will not be used by the engine and can be used to store - an arbitrary value +- `paramtype = "light"` + - The value stores light with and without sun in its lower and upper 4 bits + respectively. + - Required by a light source node to enable spreading its light. + - Required by the following drawtypes as they determine their visual + brightness from their internal light value: + - torchlike + - signlike + - firelike + - fencelike + - raillike + - nodebox + - mesh + - plantlike + - plantlike_rooted +- `paramtype = "none"` + - `param1` will not be used by the engine and can be used to store + an arbitrary value The function of `param2` is determined by `paramtype2` in node definition. `param2` is reserved for the engine when `paramtype2 != "none"`. -* `paramtype2 = "flowingliquid"` - * Used by `drawtype = "flowingliquid"` and `liquidtype = "flowing"` - * The liquid level and a flag of the liquid are stored in `param2` - * Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node; - see `minetest.get_node_level`, `minetest.set_node_level` and `minetest.add_node_level` - to access/manipulate the content of this field - * Bit 3: If set, liquid is flowing downwards (no graphical effect) -* `paramtype2 = "wallmounted"` - * Supported drawtypes: "torchlike", "signlike", "plantlike", - "plantlike_rooted", "normal", "nodebox", "mesh" - * The rotation of the node is stored in `param2` - * You can make this value by using `minetest.dir_to_wallmounted()` - * Values range 0 - 5 - * The value denotes at which direction the node is "mounted": - 0 = y+, 1 = y-, 2 = x+, 3 = x-, 4 = z+, 5 = z- -* `paramtype2 = "facedir"` - * Supported drawtypes: "normal", "nodebox", "mesh" - * The rotation of the node is stored in `param2`. Furnaces and chests are - rotated this way. Can be made by using `minetest.dir_to_facedir()`. - * Values range 0 - 23 - * facedir / 4 = axis direction: - 0 = y+, 1 = z+, 2 = z-, 3 = x+, 4 = x-, 5 = y- - * facedir modulo 4 = rotation around that axis -* `paramtype2 = "leveled"` - * Only valid for "nodebox" with 'type = "leveled"', and "plantlike_rooted". - * Leveled nodebox: - * The level of the top face of the nodebox is stored in `param2`. - * The other faces are defined by 'fixed = {}' like 'type = "fixed"' - nodeboxes. - * The nodebox height is (`param2` / 64) nodes. - * The maximum accepted value of `param2` is 127. - * Rooted plantlike: - * The height of the 'plantlike' section is stored in `param2`. - * The height is (`param2` / 16) nodes. -* `paramtype2 = "degrotate"` - * Valid for `plantlike` and `mesh` drawtypes. The rotation of the node is - stored in `param2`. - * Values range 0–239. The value stored in `param2` is multiplied by 1.5 to - get the actual rotation in degrees of the node. -* `paramtype2 = "meshoptions"` - * Only valid for "plantlike" drawtype. `param2` encodes the shape and - optional modifiers of the "plant". `param2` is a bitfield. - * Bits 0 to 2 select the shape. - Use only one of the values below: - * 0 = a "x" shaped plant (ordinary plant) - * 1 = a "+" shaped plant (just rotated 45 degrees) - * 2 = a "*" shaped plant with 3 faces instead of 2 - * 3 = a "#" shaped plant with 4 faces instead of 2 - * 4 = a "#" shaped plant with 4 faces that lean outwards - * 5-7 are unused and reserved for future meshes. - * Bits 3 to 7 are used to enable any number of optional modifiers. - Just add the corresponding value(s) below to `param2`: - * 8 - Makes the plant slightly vary placement horizontally - * 16 - Makes the plant mesh 1.4x larger - * 32 - Moves each face randomly a small bit down (1/8 max) - * values 64 and 128 (bits 6-7) are reserved for future use. - * Example: `param2 = 0` selects a normal "x" shaped plant - * Example: `param2 = 17` selects a "+" shaped plant, 1.4x larger (1+16) -* `paramtype2 = "color"` - * `param2` tells which color is picked from the palette. - The palette should have 256 pixels. -* `paramtype2 = "colorfacedir"` - * Same as `facedir`, but with colors. - * The first three bits of `param2` tells which color is picked from the - palette. The palette should have 8 pixels. -* `paramtype2 = "colorwallmounted"` - * Same as `wallmounted`, but with colors. - * The first five bits of `param2` tells which color is picked from the - palette. The palette should have 32 pixels. -* `paramtype2 = "glasslikeliquidlevel"` - * Only valid for "glasslike_framed" or "glasslike_framed_optional" - drawtypes. "glasslike_framed_optional" nodes are only affected if the - "Connected Glass" setting is enabled. - * Bits 0-5 define 64 levels of internal liquid, 0 being empty and 63 being - full. - * Bits 6 and 7 modify the appearance of the frame and node faces. One or - both of these values may be added to `param2`: - * 64 - Makes the node not connect with neighbors above or below it. - * 128 - Makes the node not connect with neighbors to its sides. - * Liquid texture is defined using `special_tiles = {"modname_tilename.png"}` -* `paramtype2 = "colordegrotate"` - * Same as `degrotate`, but with colors. - * The first (most-significant) three bits of `param2` tells which color - is picked from the palette. The palette should have 8 pixels. - * Remaining 5 bits store rotation in range 0–23 (i.e. in 15° steps) -* `paramtype2 = "none"` - * `param2` will not be used by the engine and can be used to store - an arbitrary value +- `paramtype2 = "flowingliquid"` + - Used by `drawtype = "flowingliquid"` and `liquidtype = "flowing"` + - The liquid level and a flag of the liquid are stored in `param2` + - Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node; + see `minetest.get_node_level`, `minetest.set_node_level` and `minetest.add_node_level` + to access/manipulate the content of this field + - Bit 3: If set, liquid is flowing downwards (no graphical effect) +- `paramtype2 = "wallmounted"` + - Supported drawtypes: "torchlike", "signlike", "plantlike", + "plantlike_rooted", "normal", "nodebox", "mesh" + - The rotation of the node is stored in `param2` + - You can make this value by using `minetest.dir_to_wallmounted()` + - Values range 0 - 5 + - The value denotes at which direction the node is "mounted": + 0 = y+, 1 = y-, 2 = x+, 3 = x-, 4 = z+, 5 = z- +- `paramtype2 = "facedir"` + - Supported drawtypes: "normal", "nodebox", "mesh" + - The rotation of the node is stored in `param2`. Furnaces and chests are + rotated this way. Can be made by using `minetest.dir_to_facedir()`. + - Values range 0 - 23 + - facedir / 4 = axis direction: + 0 = y+, 1 = z+, 2 = z-, 3 = x+, 4 = x-, 5 = y- + - facedir modulo 4 = rotation around that axis +- `paramtype2 = "leveled"` + - Only valid for "nodebox" with 'type = "leveled"', and "plantlike_rooted". + - Leveled nodebox: + - The level of the top face of the nodebox is stored in `param2`. + - The other faces are defined by 'fixed = {}' like 'type = "fixed"' + nodeboxes. + - The nodebox height is (`param2` / 64) nodes. + - The maximum accepted value of `param2` is 127. + - Rooted plantlike: + - The height of the 'plantlike' section is stored in `param2`. + - The height is (`param2` / 16) nodes. +- `paramtype2 = "degrotate"` + - Valid for `plantlike` and `mesh` drawtypes. The rotation of the node is + stored in `param2`. + - Values range 0–239. The value stored in `param2` is multiplied by 1.5 to + get the actual rotation in degrees of the node. +- `paramtype2 = "meshoptions"` + - Only valid for "plantlike" drawtype. `param2` encodes the shape and + optional modifiers of the "plant". `param2` is a bitfield. + - Bits 0 to 2 select the shape. + Use only one of the values below: + - 0 = a "x" shaped plant (ordinary plant) + - 1 = a "+" shaped plant (just rotated 45 degrees) + - 2 = a "\*" shaped plant with 3 faces instead of 2 + - 3 = a "#" shaped plant with 4 faces instead of 2 + - 4 = a "#" shaped plant with 4 faces that lean outwards + - 5-7 are unused and reserved for future meshes. + - Bits 3 to 7 are used to enable any number of optional modifiers. + Just add the corresponding value(s) below to `param2`: + - 8 - Makes the plant slightly vary placement horizontally + - 16 - Makes the plant mesh 1.4x larger + - 32 - Moves each face randomly a small bit down (1/8 max) + - values 64 and 128 (bits 6-7) are reserved for future use. + - Example: `param2 = 0` selects a normal "x" shaped plant + - Example: `param2 = 17` selects a "+" shaped plant, 1.4x larger (1+16) +- `paramtype2 = "color"` + - `param2` tells which color is picked from the palette. + The palette should have 256 pixels. +- `paramtype2 = "colorfacedir"` + - Same as `facedir`, but with colors. + - The first three bits of `param2` tells which color is picked from the + palette. The palette should have 8 pixels. +- `paramtype2 = "colorwallmounted"` + - Same as `wallmounted`, but with colors. + - The first five bits of `param2` tells which color is picked from the + palette. The palette should have 32 pixels. +- `paramtype2 = "glasslikeliquidlevel"` + - Only valid for "glasslike_framed" or "glasslike_framed_optional" + drawtypes. "glasslike_framed_optional" nodes are only affected if the + "Connected Glass" setting is enabled. + - Bits 0-5 define 64 levels of internal liquid, 0 being empty and 63 being + full. + - Bits 6 and 7 modify the appearance of the frame and node faces. One or + both of these values may be added to `param2`: + - 64 - Makes the node not connect with neighbors above or below it. + - 128 - Makes the node not connect with neighbors to its sides. + - Liquid texture is defined using `special_tiles = {"modname_tilename.png"}` +- `paramtype2 = "colordegrotate"` + - Same as `degrotate`, but with colors. + - The first (most-significant) three bits of `param2` tells which color + is picked from the palette. The palette should have 8 pixels. + - Remaining 5 bits store rotation in range 0–23 (i.e. in 15° steps) +- `paramtype2 = "none"` + - `param2` will not be used by the engine and can be used to store + an arbitrary value Nodes can also contain extra data. See [Node Metadata]. -Node drawtypes --------------- +## Node drawtypes There are a bunch of different looking node types. Look for examples in `games/devtest` or `games/minetest_game`. -* `normal` - * A node-sized cube. -* `airlike` - * Invisible, uses no texture. -* `liquid` - * The cubic source node for a liquid. - * Faces bordering to the same node are never rendered. - * Connects to node specified in `liquid_alternative_flowing`. - * Use `backface_culling = false` for the tiles you want to make - visible when inside the node. -* `flowingliquid` - * The flowing version of a liquid, appears with various heights and slopes. - * Faces bordering to the same node are never rendered. - * Connects to node specified in `liquid_alternative_source`. - * Node textures are defined with `special_tiles` where the first tile - is for the top and bottom faces and the second tile is for the side - faces. - * `tiles` is used for the item/inventory/wield image rendering. - * Use `backface_culling = false` for the special tiles you want to make - visible when inside the node -* `glasslike` - * Often used for partially-transparent nodes. - * Only external sides of textures are visible. -* `glasslike_framed` - * All face-connected nodes are drawn as one volume within a surrounding - frame. - * The frame appearance is generated from the edges of the first texture - specified in `tiles`. The width of the edges used are 1/16th of texture - size: 1 pixel for 16x16, 2 pixels for 32x32 etc. - * The glass 'shine' (or other desired detail) on each node face is supplied - by the second texture specified in `tiles`. -* `glasslike_framed_optional` - * This switches between the above 2 drawtypes according to the menu setting - 'Connected Glass'. -* `allfaces` - * Often used for partially-transparent nodes. - * External and internal sides of textures are visible. -* `allfaces_optional` - * Often used for leaves nodes. - * This switches between `normal`, `glasslike` and `allfaces` according to - the menu setting: Opaque Leaves / Simple Leaves / Fancy Leaves. - * With 'Simple Leaves' selected, the texture specified in `special_tiles` - is used instead, if present. This allows a visually thicker texture to be - used to compensate for how `glasslike` reduces visual thickness. -* `torchlike` - * A single vertical texture. - * If `paramtype2="[color]wallmounted": - * If placed on top of a node, uses the first texture specified in `tiles`. - * If placed against the underside of a node, uses the second texture - specified in `tiles`. - * If placed on the side of a node, uses the third texture specified in - `tiles` and is perpendicular to that node. - * If `paramtype2="none"`: - * Will be rendered as if placed on top of a node (see - above) and only the first texture is used. -* `signlike` - * A single texture parallel to, and mounted against, the top, underside or - side of a node. - * If `paramtype2="[color]wallmounted", it rotates according to `param2` - * If `paramtype2="none"`, it will always be on the floor. -* `plantlike` - * Two vertical and diagonal textures at right-angles to each other. - * See `paramtype2 = "meshoptions"` above for other options. -* `firelike` - * When above a flat surface, appears as 6 textures, the central 2 as - `plantlike` plus 4 more surrounding those. - * If not above a surface the central 2 do not appear, but the texture - appears against the faces of surrounding nodes if they are present. -* `fencelike` - * A 3D model suitable for a wooden fence. - * One placed node appears as a single vertical post. - * Adjacently-placed nodes cause horizontal bars to appear between them. -* `raillike` - * Often used for tracks for mining carts. - * Requires 4 textures to be specified in `tiles`, in order: Straight, - curved, t-junction, crossing. - * Each placed node automatically switches to a suitable rotated texture - determined by the adjacent `raillike` nodes, in order to create a - continuous track network. - * Becomes a sloping node if placed against stepped nodes. -* `nodebox` - * Often used for stairs and slabs. - * Allows defining nodes consisting of an arbitrary number of boxes. - * See [Node boxes] below for more information. -* `mesh` - * Uses models for nodes. - * Tiles should hold model materials textures. - * Only static meshes are implemented. - * For supported model formats see Irrlicht engine documentation. -* `plantlike_rooted` - * Enables underwater `plantlike` without air bubbles around the nodes. - * Consists of a base cube at the co-ordinates of the node plus a - `plantlike` extension above - * If `paramtype2="leveled", the `plantlike` extension has a height - of `param2 / 16` nodes, otherwise it's the height of 1 node - * If `paramtype2="wallmounted"`, the `plantlike` extension - will be at one of the corresponding 6 sides of the base cube. - Also, the base cube rotates like a `normal` cube would - * The `plantlike` extension visually passes through any nodes above the - base cube without affecting them. - * The base cube texture tiles are defined as normal, the `plantlike` - extension uses the defined special tile, for example: - `special_tiles = {{name = "default_papyrus.png"}},` +- `normal` + - A node-sized cube. +- `airlike` + - Invisible, uses no texture. +- `liquid` + - The cubic source node for a liquid. + - Faces bordering to the same node are never rendered. + - Connects to node specified in `liquid_alternative_flowing`. + - Use `backface_culling = false` for the tiles you want to make + visible when inside the node. +- `flowingliquid` + - The flowing version of a liquid, appears with various heights and slopes. + - Faces bordering to the same node are never rendered. + - Connects to node specified in `liquid_alternative_source`. + - Node textures are defined with `special_tiles` where the first tile + is for the top and bottom faces and the second tile is for the side + faces. + - `tiles` is used for the item/inventory/wield image rendering. + - Use `backface_culling = false` for the special tiles you want to make + visible when inside the node +- `glasslike` + - Often used for partially-transparent nodes. + - Only external sides of textures are visible. +- `glasslike_framed` + - All face-connected nodes are drawn as one volume within a surrounding + frame. + - The frame appearance is generated from the edges of the first texture + specified in `tiles`. The width of the edges used are 1/16th of texture + size: 1 pixel for 16x16, 2 pixels for 32x32 etc. + - The glass 'shine' (or other desired detail) on each node face is supplied + by the second texture specified in `tiles`. +- `glasslike_framed_optional` + - This switches between the above 2 drawtypes according to the menu setting + 'Connected Glass'. +- `allfaces` + - Often used for partially-transparent nodes. + - External and internal sides of textures are visible. +- `allfaces_optional` + - Often used for leaves nodes. + - This switches between `normal`, `glasslike` and `allfaces` according to + the menu setting: Opaque Leaves / Simple Leaves / Fancy Leaves. + - With 'Simple Leaves' selected, the texture specified in `special_tiles` + is used instead, if present. This allows a visually thicker texture to be + used to compensate for how `glasslike` reduces visual thickness. +- `torchlike` + - A single vertical texture. + - If `paramtype2="[color]wallmounted"`: + - If placed on top of a node, uses the first texture specified in `tiles`. + - If placed against the underside of a node, uses the second texture + specified in `tiles`. + - If placed on the side of a node, uses the third texture specified in + `tiles` and is perpendicular to that node. + - If `paramtype2="none"`: + - Will be rendered as if placed on top of a node (see + above) and only the first texture is used. +- `signlike` + - A single texture parallel to, and mounted against, the top, underside or + side of a node. + - If `paramtype2="[color]wallmounted"`, it rotates according to `param2` + - If `paramtype2="none"`, it will always be on the floor. +- `plantlike` + - Two vertical and diagonal textures at right-angles to each other. + - See `paramtype2 = "meshoptions"` above for other options. +- `firelike` + - When above a flat surface, appears as 6 textures, the central 2 as + `plantlike` plus 4 more surrounding those. + - If not above a surface the central 2 do not appear, but the texture + appears against the faces of surrounding nodes if they are present. +- `fencelike` + - A 3D model suitable for a wooden fence. + - One placed node appears as a single vertical post. + - Adjacently-placed nodes cause horizontal bars to appear between them. +- `raillike` + - Often used for tracks for mining carts. + - Requires 4 textures to be specified in `tiles`, in order: Straight, + curved, t-junction, crossing. + - Each placed node automatically switches to a suitable rotated texture + determined by the adjacent `raillike` nodes, in order to create a + continuous track network. + - Becomes a sloping node if placed against stepped nodes. +- `nodebox` + - Often used for stairs and slabs. + - Allows defining nodes consisting of an arbitrary number of boxes. + - See [Node boxes] below for more information. +- `mesh` + - Uses models for nodes. + - Tiles should hold model materials textures. + - Only static meshes are implemented. + - For supported model formats see Irrlicht engine documentation. +- `plantlike_rooted` + - Enables underwater `plantlike` without air bubbles around the nodes. + - Consists of a base cube at the co-ordinates of the node plus a + `plantlike` extension above + - If `paramtype2="leveled", the `plantlike`extension has a height of`param2 / 16` nodes, otherwise it's the height of 1 node + - If `paramtype2="wallmounted"`, the `plantlike` extension + will be at one of the corresponding 6 sides of the base cube. + Also, the base cube rotates like a `normal` cube would + - The `plantlike` extension visually passes through any nodes above the + base cube without affecting them. + - The base cube texture tiles are defined as normal, the `plantlike` + extension uses the defined special tile, for example: + `special_tiles = {{name = "default_papyrus.png"}},` `*_optional` drawtypes need less rendering time if deactivated (always client-side). -Node boxes ----------- +## Node boxes Node selection boxes are defined using "node boxes". @@ -1322,13 +1280,9 @@ To avoid collision issues, keep each value within the range of +/- 1.45. This also applies to leveled nodeboxes, where the final height shall not exceed this soft limit. +# Map terminology and coordinates - -Map terminology and coordinates -=============================== - -Nodes, mapblocks, mapchunks ---------------------------- +## Nodes, mapblocks, mapchunks A 'node' is the fundamental cubic unit of a world and appears to a player as roughly 1x1x1 meters in size. @@ -1344,8 +1298,7 @@ A 'mapchunk' (sometimes abbreviated to 'chunk') is usually 5x5x5 mapblocks the map generator. The size in mapblocks has been chosen to optimise map generation. -Coordinates ------------ +## Coordinates ### Orientation of axes @@ -1367,33 +1320,27 @@ node position (0,0,0) to node position (15,15,15). To calculate the blockpos of the mapblock that contains the node at 'nodepos', for each axis: -* blockpos = math.floor(nodepos / 16) +- blockpos = math.floor(nodepos / 16) #### Converting blockpos to min/max node positions To calculate the min/max node positions contained in the mapblock at 'blockpos', for each axis: -* Minimum: - nodepos = blockpos * 16 -* Maximum: - nodepos = blockpos * 16 + 15 +- Minimum: + nodepos = blockpos \* 16 +- Maximum: + nodepos = blockpos \* 16 + 15 +# HUD - - -HUD -=== - -HUD element types ------------------ +## HUD element types The position field is used for all element types. - To account for differing resolutions, the position coordinates are the percentage of the screen, ranging in value from `0` to `1`. -The name field is not yet used, but should contain a description of what the +The `name` field is not yet used, but should contain a description of what the HUD element represents. The `direction` field is the direction in which something is drawn. @@ -1417,19 +1364,18 @@ Lower z-index elements are displayed behind higher z-index elements. Elements with same z-index are displayed in an arbitrary order. Default 0. Supports negative values. By convention, the following values are recommended: -* -400: Graphical effects, such as vignette -* -300: Name tags, waypoints -* -200: Wieldhand -* -100: Things that block the player's view, e.g. masks -* 0: Default. For standard in-game HUD elements like crosshair, hotbar, +- -400: Graphical effects, such as vignette +- -300: Name tags, waypoints +- -200: Wieldhand +- -100: Things that block the player's view, e.g. masks +- 0: Default. For standard in-game HUD elements like crosshair, hotbar, minimap, builtin statbars, etc. -* 100: Temporary text messages or notification icons -* 1000: Full-screen effects such as full-black screen or credits. - This includes effects that cover the entire screen -* Other: If your HUD element doesn't fit into any category, pick a number - between the suggested values - +- 100: Temporary text messages or notification icons +- 1000: Full-screen effects such as full-black screen or credits. + This includes effects that cover the entire screen +If your HUD element doesn't fit into any category, pick a number +between the suggested values Below are the specific uses for fields in each type; fields not listed for that type are ignored. @@ -1438,98 +1384,100 @@ type are ignored. Displays an image on the HUD. -* `scale`: The scale of the image, with 1 being the original texture size. +- `scale`: The scale of the image, with 1 being the original texture size. Only the X coordinate scale is used (positive values). Negative values represent that percentage of the screen it should take; e.g. `x=-100` means 100% (width). -* `text`: The name of the texture that is displayed. -* `alignment`: The alignment of the image. -* `offset`: offset in pixels from position. +- `text`: The name of the texture that is displayed. +- `alignment`: The alignment of the image. +- `offset`: offset in pixels from position. ### `text` Displays text on the HUD. -* `scale`: Defines the bounding rectangle of the text. +- `scale`: Defines the bounding rectangle of the text. A value such as `{x=100, y=100}` should work. -* `text`: The text to be displayed in the HUD element. -* `number`: An integer containing the RGB value of the color used to draw the +- `text`: The text to be displayed in the HUD element. +- `number`: An integer containing the RGB value of the color used to draw the text. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on. -* `alignment`: The alignment of the text. -* `offset`: offset in pixels from position. -* `size`: size of the text. +- `alignment`: The alignment of the text. +- `offset`: offset in pixels from position. +- `size`: size of the text. The player-set font size is multiplied by size.x (y value isn't used). +- `style`: determines font style + Bitfield with 1 = bold, 2 = italic, 4 = monospace ### `statbar` Displays a horizontal bar made up of half-images with an optional background. -* `text`: The name of the texture to use. -* `text2`: Optional texture name to enable a background / "off state" +- `text`: The name of the texture to use. +- `text2`: Optional texture name to enable a background / "off state" texture (useful to visualize the maximal value). Both textures must have the same size. -* `number`: The number of half-textures that are displayed. +- `number`: The number of half-textures that are displayed. If odd, will end with a vertically center-split texture. -* `item`: Same as `number` but for the "off state" texture -* `direction`: To which direction the images will extend to -* `offset`: offset in pixels from position. -* `size`: If used, will force full-image size to this value (override texture +- `item`: Same as `number` but for the "off state" texture +- `direction`: To which direction the images will extend to +- `offset`: offset in pixels from position. +- `size`: If used, will force full-image size to this value (override texture pack image size) ### `inventory` -* `text`: The name of the inventory list to be displayed. -* `number`: Number of items in the inventory to be displayed. -* `item`: Position of item that is selected. -* `direction` -* `offset`: offset in pixels from position. +- `text`: The name of the inventory list to be displayed. +- `number`: Number of items in the inventory to be displayed. +- `item`: Position of item that is selected. +- `direction`: Direction the list will be displayed in +- `offset`: offset in pixels from position. ### `waypoint` Displays distance to selected world position. -* `name`: The name of the waypoint. -* `text`: Distance suffix. Can be blank. -* `precision`: Waypoint precision, integer >= 0. Defaults to 10. +- `name`: The name of the waypoint. +- `text`: Distance suffix. Can be blank. +- `precision`: Waypoint precision, integer >= 0. Defaults to 10. If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`. When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point. `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`). `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on: `precision = n` will show multiples of `1/n` -* `number:` An integer containing the RGB value of the color used to draw the +- `number:` An integer containing the RGB value of the color used to draw the text. -* `world_pos`: World position of the waypoint. -* `offset`: offset in pixels from position. -* `alignment`: The alignment of the waypoint. +- `world_pos`: World position of the waypoint. +- `offset`: offset in pixels from position. +- `alignment`: The alignment of the waypoint. ### `image_waypoint` Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint. -* `scale`: The scale of the image, with 1 being the original texture size. +- `scale`: The scale of the image, with 1 being the original texture size. Only the X coordinate scale is used (positive values). Negative values represent that percentage of the screen it should take; e.g. `x=-100` means 100% (width). -* `text`: The name of the texture that is displayed. -* `alignment`: The alignment of the image. -* `world_pos`: World position of the waypoint. -* `offset`: offset in pixels from position. +- `text`: The name of the texture that is displayed. +- `alignment`: The alignment of the image. +- `world_pos`: World position of the waypoint. +- `offset`: offset in pixels from position. ### `compass` Displays an image oriented or translated according to current heading direction. -* `size`: The size of this element. Negative values represent percentage +- `size`: The size of this element. Negative values represent percentage of the screen; e.g. `x=-100` means 100% (width). -* `scale`: Scale of the translated image (used only for dir = 2 or dir = 3). -* `text`: The name of the texture to use. -* `alignment`: The alignment of the image. -* `offset`: Offset in pixels from position. -* `dir`: How the image is rotated/translated: - * 0 - Rotate as heading direction - * 1 - Rotate in reverse direction - * 2 - Translate as landscape direction - * 3 - Translate in reverse direction +- `scale`: Scale of the translated image (used only for dir = 2 or dir = 3). +- `text`: The name of the texture to use. +- `alignment`: The alignment of the image. +- `offset`: Offset in pixels from position. +- `direction`: How the image is rotated/translated: + - 0 - Rotate as heading direction + - 1 - Rotate in reverse direction + - 2 - Translate as landscape direction + - 3 - Translate in reverse direction If translation is chosen, texture is repeated horizontally to fill the whole element. @@ -1537,47 +1485,40 @@ If translation is chosen, texture is repeated horizontally to fill the whole ele Displays a minimap on the HUD. -* `size`: Size of the minimap to display. Minimap should be a square to avoid +- `size`: Size of the minimap to display. Minimap should be a square to avoid distortion. -* `alignment`: The alignment of the minimap. -* `offset`: offset in pixels from position. +- `alignment`: The alignment of the minimap. +- `offset`: offset in pixels from position. -Representations of simple things -================================ +# Representations of simple things -Vector (ie. a position) ------------------------ +## Vector (ie. a position) vector.new(x, y, z) See [Spatial Vectors] for details. -`pointed_thing` ---------------- +## `pointed_thing` -* `{type="nothing"}` -* `{type="node", under=pos, above=pos}` - * Indicates a pointed node selection box. - * `under` refers to the node position behind the pointed face. - * `above` refers to the node position in front of the pointed face. -* `{type="object", ref=ObjectRef}` +- `{type="nothing"}` +- `{type="node", under=pos, above=pos}` + - Indicates a pointed node selection box. + - `under` refers to the node position behind the pointed face. + - `above` refers to the node position in front of the pointed face. +- `{type="object", ref=ObjectRef}` Exact pointing location (currently only `Raycast` supports these fields): -* `pointed_thing.intersection_point`: The absolute world coordinates of the +- `pointed_thing.intersection_point`: 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. -* `pointed_thing.box_id`: The ID of the pointed selection box (counting starts +- `pointed_thing.box_id`: The ID of the pointed selection box (counting starts from 1). -* `pointed_thing.intersection_normal`: Unit vector, points outwards of the +- `pointed_thing.intersection_normal`: 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. - - - -Flag Specifier Format -===================== +# Flag Specifier Format Flags using the standardized flag specifier format can be specified in either of two ways, by string or table. @@ -1610,25 +1551,20 @@ or even since, by default, no schematic attributes are set. - - - -Items -===== +# Items Items are things that can be held by players, dropped in the map and stored in inventories. Items come in the form of item stacks, which are collections of equal items that occupy a single inventory slot. -Item types ----------- +## Item types There are three kinds of items: nodes, tools and craftitems. -* Node: Placeable item form of a node in the world's voxel grid -* Tool: Has a changable wear property but cannot be stacked -* Craftitem: Has no special properties +- Node: Placeable item form of a node in the world's voxel grid +- Tool: Has a changable wear property but cannot be stacked +- Craftitem: Has no special properties Every registered node (the voxel in the world) has a corresponding item form (the thing in your inventory) that comes along with it. @@ -1648,8 +1584,7 @@ that acts as tool in a gameplay sense as a craftitem, and vice-versa. Craftitems can be used for items that neither need to be a node nor a tool. -Amount and wear ---------------- +## Amount and wear All item stacks have an amount between 0 and 65535. It is 1 by default. Tool item stacks can not have an amount greater than 1. @@ -1661,8 +1596,7 @@ a higher wear. Non-tools technically also have a wear property, but it is always 0. There is also a special 'toolrepair' crafting recipe that is only available to tools. -Item formats ------------- +## Item formats Items and item stacks can exist in three formats: Serializes, table format and `ItemStack`. @@ -1686,17 +1620,17 @@ Syntax: Examples: -* `"default:apple"`: 1 apple -* `"default:dirt 5"`: 5 dirt -* `"default:pick_stone"`: a new stone pickaxe -* `"default:pick_wood 1 21323"`: a wooden pickaxe, ca. 1/3 worn out -* `[[default:pick_wood 1 21323 "\u0001description\u0002My worn out pick\u0003"]]`: - * a wooden pickaxe from the `default` mod, - * amount must be 1 (pickaxe is a tool), ca. 1/3 worn out (it's a tool), - * with the `description` field set to `"My worn out pick"` in its metadata -* `[[default:dirt 5 0 "\u0001description\u0002Special dirt\u0003"]]`: - * analogeous to the above example - * note how the wear is set to `0` as dirt is not a tool +- `"default:apple"`: 1 apple +- `"default:dirt 5"`: 5 dirt +- `"default:pick_stone"`: a new stone pickaxe +- `"default:pick_wood 1 21323"`: a wooden pickaxe, ca. 1/3 worn out +- `[[default:pick_wood 1 21323 "\u0001description\u0002My worn out pick\u0003"]]`: + - a wooden pickaxe from the `default` mod, + - amount must be 1 (pickaxe is a tool), ca. 1/3 worn out (it's a tool), + - with the `description` field set to `"My worn out pick"` in its metadata +- `[[default:dirt 5 0 "\u0001description\u0002Special dirt\u0003"]]`: + - analogeous to the above example + - note how the wear is set to `0` as dirt is not a tool You should ideally use the `ItemStack` format to build complex item strings (especially if they use item metadata) @@ -1732,19 +1666,14 @@ An apple: A native C++ format with many helper methods. Useful for converting between formats. See the [Class reference] section for details. - - - -Groups -====== +# Groups In a number of places, there is a group table. Groups define the properties of a thing (item, node, armor of entity, tool capabilities) in such a way that the engine and other mods can can interact with the thing without actually knowing what the thing is. -Usage ------ +## Usage Groups are stored in a table, having the group names with keys and the group ratings as values. Group ratings are integer values within the @@ -1766,19 +1695,16 @@ You can read the rating of a group for an item or a node by using minetest.get_item_group(itemname, groupname) -Groups of items ---------------- +## Groups of items Groups of items can define what kind of an item it is (e.g. wool). -Groups of nodes ---------------- +## Groups of nodes In addition to the general item things, groups are used to define whether a node is destroyable and how long it takes to destroy by a tool. -Groups of entities ------------------- +## Groups of entities For entities, groups are, as of now, used only for calculating damage. The rating is the percentage of damage caused by items with this damage group. @@ -1787,14 +1713,12 @@ See [Entity damage mechanism]. object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100}) object.set_armor_groups({fleshy=30, cracky=80}) -Groups of tool capabilities ---------------------------- +## Groups of tool capabilities Groups in tool capabilities define which groups of nodes and entities they are effective towards. -Groups in crafting recipes --------------------------- +## Groups in crafting recipes An example: Make meat soup from any meat, any water and any bowl: @@ -1815,8 +1739,7 @@ Another example: Make red wool from white wool and red dye: recipe = {"wool:white", "group:dye,basecolor_red"}, } -Special groups --------------- +## Special groups The asterisk `(*)` after a group name describes that there is no engine functionality bound to it, and implementation is left up as a suggestion @@ -1824,102 +1747,93 @@ to games. ### Node and item groups -* `not_in_creative_inventory`: (*) Special group for inventory mods to indicate +- `not_in_creative_inventory`: (\*) Special group for inventory mods to indicate that the item should be hidden in item lists. - ### Node-only groups -* `attached_node`: if the node under it is not a walkable block the node will be +- `attached_node`: if the node under it is not a walkable block the node will be dropped as an item. If the node is wallmounted the wallmounted direction is checked. -* `bouncy`: value is bounce speed in percent -* `connect_to_raillike`: makes nodes of raillike drawtype with same group value +- `bouncy`: value is bounce speed in percent +- `connect_to_raillike`: makes nodes of raillike drawtype with same group value connect to each other -* `dig_immediate`: Player can always pick up node without reducing tool wear - * `2`: the node always gets the digging time 0.5 seconds (rail, sign) - * `3`: the node always gets the digging time 0 seconds (torch) -* `disable_jump`: Player (and possibly other things) cannot jump from node +- `dig_immediate`: Player can always pick up node without reducing tool wear + - `2`: the node always gets the digging time 0.5 seconds (rail, sign) + - `3`: the node always gets the digging time 0 seconds (torch) +- `disable_jump`: Player (and possibly other things) cannot jump from node or if their feet are in the node. Note: not supported for `new_move = false` -* `fall_damage_add_percent`: modifies the fall damage suffered when hitting +- `fall_damage_add_percent`: modifies the fall damage suffered when hitting the top of this node. There's also an armor group with the same name. The final player damage is determined by the following formula: - damage = - collision speed - * ((node_fall_damage_add_percent + 100) / 100) -- node group - * ((player_fall_damage_add_percent + 100) / 100) -- player armor group - - (14) -- constant tolerance + damage = + collision speed + _ ((node_fall_damage_add_percent + 100) / 100) -- node group + _ ((player_fall_damage_add_percent + 100) / 100) -- player armor group - (14) -- constant tolerance Negative damage values are discarded as no damage. -* `falling_node`: if there is no walkable block under the node it will fall -* `float`: the node will not fall through liquids (`liquidtype ~= "none"`) -* `level`: Can be used to give an additional sense of progression in the game. - * A larger level will cause e.g. a weapon of a lower level make much less - damage, and get worn out much faster, or not be able to get drops - from destroyed nodes. - * `0` is something that is directly accessible at the start of gameplay - * There is no upper limit - * See also: `leveldiff` in [Tool Capabilities] -* `slippery`: Players and items will slide on the node. +- `falling_node`: if there is no walkable block under the node it will fall +- `float`: the node will not fall through liquids (`liquidtype ~= "none"`) +- `level`: Can be used to give an additional sense of progression in the game. + - A larger level will cause e.g. a weapon of a lower level make much less + damage, and get worn out much faster, or not be able to get drops + from destroyed nodes. + - `0` is something that is directly accessible at the start of gameplay + - There is no upper limit + - See also: `leveldiff` in [Tool Capabilities] +- `slippery`: Players and items will slide on the node. Slipperiness rises steadily with `slippery` value, starting at 1. - ### Tool-only groups -* `disable_repair`: If set to 1 for a tool, it cannot be repaired using the +- `disable_repair`: If set to 1 for a tool, it cannot be repaired using the `"toolrepair"` crafting recipe - ### `ObjectRef` armor groups -* `immortal`: Skips all damage and breath handling for an object. This group +- `immortal`: 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). -* `fall_damage_add_percent`: Modifies the fall damage suffered by players +- `fall_damage_add_percent`: 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. -* `punch_operable`: For entities; disables the regular damage mechanism for +- `punch_operable`: 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. +## Known damage and digging time defining groups - -Known damage and digging time defining groups ---------------------------------------------- - -* `crumbly`: dirt, sand -* `cracky`: tough but crackable stuff like stone. -* `snappy`: something that can be cut using things like scissors, shears, +- `crumbly`: dirt, sand +- `cracky`: tough but crackable stuff like stone. +- `snappy`: something that can be cut using things like scissors, shears, bolt cutters and the like, e.g. leaves, small plants, wire, sheets of metal -* `choppy`: something that can be cut using force; e.g. trees, wooden planks -* `fleshy`: Living things like animals and the player. This could imply +- `choppy`: something that can be cut using force; e.g. trees, wooden planks +- `fleshy`: Living things like animals and the player. This could imply some blood effects when hitting. -* `explody`: Especially prone to explosions -* `oddly_breakable_by_hand`: - 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. +- `explody`: Especially prone to explosions +- `oddly_breakable_by_hand`: + 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. -Examples of custom groups -------------------------- +## Examples of custom groups Item groups are often used for defining, well, _groups of items_. -* `meat`: any meat-kind of a thing (rating might define the size or healing +- `meat`: any meat-kind of a thing (rating might define the size or healing ability or be irrelevant -- it is not defined as of yet) -* `eatable`: anything that can be eaten. Rating might define HP gain in half +- `eatable`: anything that can be eaten. Rating might define HP gain in half hearts. -* `flammable`: can be set on fire. Rating might define the intensity of the +- `flammable`: can be set on fire. Rating might define the intensity of the fire, affecting e.g. the speed of the spreading of an open fire. -* `wool`: any wool (any origin, any color) -* `metal`: any metal -* `weapon`: any weapon -* `heavy`: anything considerably heavy +- `wool`: any wool (any origin, any color) +- `metal`: any metal +- `weapon`: any weapon +- `heavy`: anything considerably heavy -Digging time calculation specifics ----------------------------------- +## Digging time calculation specifics Groups such as `crumbly`, `cracky` and `snappy` are used for this purpose. Rating is `1`, `2` or `3`. A higher rating for such a group implies @@ -1935,16 +1849,12 @@ Items define their properties by a list of parameters for groups. They cannot dig other groups; thus it is important to use a standard bunch of groups to enable interaction with items. - - - -Tool Capabilities -================= +# Tool Capabilities 'Tool capabilities' is a property of items that defines two things: -1) Which nodes it can dig and how fast -2) Which objects it can hurt by punching and by how much +1. Which nodes it can dig and how fast +2. Which objects it can hurt by punching and by how much Tool capabilities are available for all items, not just tools. But only tools can receive wear from digging and punching. @@ -1952,35 +1862,34 @@ But only tools can receive wear from digging and punching. Missing or incomplete tool capabilities will default to the player's hand. -Tool capabilities definition ----------------------------- +## Tool capabilities definition Tool capabilities define: -* Full punch interval -* Maximum drop level -* For an arbitrary list of node groups: - * Uses (until the tool breaks) - * Maximum level (usually `0`, `1`, `2` or `3`) - * Digging times -* Damage groups -* Punch attack uses (until the tool breaks) +- Full punch interval +- Maximum drop level +- For an arbitrary list of node groups: + - Uses (until the tool breaks) + - Maximum level (usually `0`, `1`, `2` or `3`) + - Digging times +- Damage groups +- Punch attack uses (until the tool breaks) -### Full punch interval +### Full punch interval `full_punch_interval` When used as a weapon, the item will do full damage if this time is spent between punches. If e.g. half the time is spent, the item will do half damage. -### Maximum drop level +### Maximum drop level `max_drop_level` Suggests the maximum level of node, when dug with the item, that will drop its useful item. (e.g. iron ore to drop a lump of iron). -This is not automated; it is the responsibility of the node definition -to implement this. +This value is not used in the engine; it is the responsibility of the game/mod +code to implement this. -### Uses (tools only) +### Uses `uses` (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 @@ -1989,23 +1898,23 @@ 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. -* `uses=10, leveldiff=0`: actual uses: 10 -* `uses=10, leveldiff=1`: actual uses: 30 -* `uses=10, leveldiff=2`: actual uses: 90 +- `uses=10, leveldiff=0`: actual uses: 10 +- `uses=10, leveldiff=1`: actual uses: 30 +- `uses=10, leveldiff=2`: actual uses: 90 For non-tools, this has no effect. -### Maximum level +### Maximum level `maxlevel` Tells what is the maximum level of a node of this group that the item will be able to dig. -### Digging times +### Digging times `times` 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 +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. @@ -2029,22 +1938,18 @@ the full punch interval. For non-tools, this has no effect. -Example definition of the capabilities of an item -------------------------------------------------- +## Example definition of the capabilities of an item tool_capabilities = { - full_punch_interval=1.5, - max_drop_level=1, groupcaps={ crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}} }, - damage_groups = {fleshy=2}, } This makes the item capable of digging nodes that fulfil both of these: -* Have the `crumbly` group -* Have a `level` group less or equal to `2` +- Have the `crumbly` group +- Have a `level` group less or equal to `2` Table of resulting digging times: @@ -2065,16 +1970,12 @@ Table of resulting tool uses: **Notes**: -* At `crumbly==0`, the node is not diggable. -* At `crumbly==3`, the level difference digging time divider kicks in and makes +- At `crumbly==0`, the node is not diggable. +- At `crumbly==3`, the level difference digging time divider kicks in and makes easy nodes to be quickly breakable. -* At `level > 2`, the node is not diggable, because it's `level > maxlevel` - - +- At `level > 2`, the node is not diggable, because it's `level > maxlevel` - -Entity damage mechanism -======================= +# Entity damage mechanism Damage calculation: @@ -2106,33 +2007,28 @@ On the Lua side, every punch calls: This should never be called directly, because damage is usually not handled by the entity itself. -* `puncher` is the object performing the punch. Can be `nil`. Should never be +- `puncher` is the object performing the punch. Can be `nil`. Should never be accessed unless absolutely required, to encourage interoperability. -* `time_from_last_punch` is time from last punch (by `puncher`) or `nil`. -* `tool_capabilities` can be `nil`. -* `direction` is a unit vector, pointing from the source of the punch to - the punched object. -* `damage` damage that will be done to entity -Return value of this function will determine if damage is done by this function -(retval true) or shall be done by engine (retval false) +- `time_from_last_punch` is time from last punch (by `puncher`) or `nil`. +- `tool_capabilities` can be `nil`. +- `direction` is a unit vector, pointing from the source of the punch to + the punched object. +- `damage` damage that will be done to entity + Return value of this function will determine if damage is done by this function + (retval true) or shall be done by engine (retval false) To punch an entity/object in Lua, call: - object:punch(puncher, time_from_last_punch, tool_capabilities, direction) +object:punch(puncher, time_from_last_punch, tool_capabilities, direction) -* Return value is tool wear. -* Parameters are equal to the above callback. -* If `direction` equals `nil` and `puncher` does not equal `nil`, `direction` +- Return value is tool wear. +- Parameters are equal to the above callback. +- If `direction` equals `nil` and `puncher` does not equal `nil`, `direction` will be automatically filled in based on the location of `puncher`. +# Metadata - - -Metadata -======== - -Node Metadata -------------- +## Node Metadata The instance of a node in the world normally only contains the three values mentioned in [Nodes]. However, it is possible to insert extra data into a node. @@ -2140,17 +2036,17 @@ It is called "node metadata"; See `NodeMetaRef`. Node metadata contains two things: -* A key-value store -* An inventory +- A key-value store +- An inventory Some of the values in the key-value store are handled specially: -* `formspec`: Defines an inventory menu that is opened with the - 'place/use' key. Only works if no `on_rightclick` was - defined for the node. See also [Formspec]. -* `infotext`: Text shown on the screen when the node is pointed at. - Line-breaks will be applied automatically. - If the infotext is very long, it will be truncated. +- `formspec`: Defines an inventory menu that is opened with the + 'place/use' key. Only works if no `on_rightclick` was + defined for the node. See also [Formspec]. +- `infotext`: Text shown on the screen when the node is pointed at. + Line-breaks will be applied automatically. + If the infotext is very long, it will be truncated. Example: @@ -2180,8 +2076,7 @@ Example: } }) -Item Metadata -------------- +## Item Metadata Item stacks can store metadata too. See [`ItemStackMetaRef`]. @@ -2189,20 +2084,20 @@ Item metadata only contains a key-value store. Some of the values in the key-value store are handled specially: -* `description`: Set the item stack's description. +- `description`: Set the item stack's description. See also: `get_description` in [`ItemStack`] -* `short_description`: Set the item stack's short description. +- `short_description`: Set the item stack's short description. See also: `get_short_description` in [`ItemStack`] -* `color`: A `ColorString`, which sets the stack's color. -* `palette_index`: If the item has a palette, this is used to get the +- `color`: A `ColorString`, which sets the stack's color. +- `palette_index`: If the item has a palette, this is used to get the current color from the palette. -* `count_meta`: Replace the displayed count with any string. -* `count_alignment`: Set the alignment of the displayed count value. This is an +- `count_meta`: Replace the displayed count with any string. +- `count_alignment`: Set the alignment of the displayed count value. This is an int value. The lowest 2 bits specify the alignment in x-direction, the 3rd and 4th bit specify the alignment in y-direction: 0 = default, 1 = left / up, 2 = middle, 3 = right / down The default currently is the same as right/down. - Example: 6 = 2 + 1*4 = middle,up + Example: 6 = 2 + 1\*4 = middle,up Example: @@ -2226,10 +2121,7 @@ Example manipulations of "description" and expected output behaviors: print(ItemStack("mod:item_with_no_desc"):get_description()) --> mod:item_with_no_desc - - -Formspec -======== +# Formspec Formspec defines a menu. This supports inventories and some of the typical widgets like buttons, checkboxes, text input fields, etc. @@ -2251,15 +2143,14 @@ of the menu or container. `W` and `H` are its width and height values. If the new system is enabled, all elements have unified coordinates for all elements with no padding or spacing in between. This is highly recommended -for new forms. See `real_coordinates[]` and `Migrating to Real -Coordinates`. +for new forms. See `real_coordinates[]` and `Migrating to Real Coordinates`. Inventories with a `player:` inventory location are only sent to the player named ``. When displaying text which can contain formspec code, e.g. text set by a player, use `minetest.formspec_escape`. -For coloured text you can use `minetest.colorize`. +For colored text you can use `minetest.colorize`. Since formspec version 3, elements drawn in the order they are defined. All background elements are drawn before all other elements. @@ -2272,8 +2163,7 @@ using `player:set_formspec_prepend()`, which may be the reason backgrounds are appearing when you don't expect them to, or why things are styled differently to normal. See [`no_prepend[]`] and [Styling Formspecs]. -Examples --------- +## Examples ### Chest @@ -2297,630 +2187,633 @@ Examples list[current_player;craft;3,0;3,3;] list[current_player;craftpreview;7,1;1,1;] -Version History ---------------- - -* Formspec version 1 (pre-5.1.0): - * (too much) -* Formspec version 2 (5.1.0): - * Forced real coordinates - * background9[]: 9-slice scaling parameters -* Formspec version 3 (5.2.0): - * Formspec elements are drawn in the order of definition - * bgcolor[]: use 3 parameters (bgcolor, formspec (now an enum), fbgcolor) - * box[] and image[] elements enable clipping by default - * new element: scroll_container[] -* Formspec version 4 (5.4.0): - * Allow dropdown indexing events -* Formspec version 5 (5.5.0): - * Added padding[] element - -Elements --------- +## Version History + +- Formspec version 1 (pre-5.1.0): + - (too much) +- Formspec version 2 (5.1.0): + - Forced real coordinates + - background9[]: 9-slice scaling parameters +- Formspec version 3 (5.2.0): + - Formspec elements are drawn in the order of definition + - bgcolor[]: use 3 parameters (bgcolor, formspec (now an enum), fbgcolor) + - box[] and image[] elements enable clipping by default + - new element: scroll_container[] +- Formspec version 4 (5.4.0): + - Allow dropdown indexing events +- Formspec version 5 (5.5.0): + - Added padding[] element +- Formspec version 6 (5.6.0): + - Add nine-slice images, animated_image, and fgimg_middle + +## Elements ### `formspec_version[]` -* Set the formspec version to a certain number. If not specified, +- Set the formspec version to a certain number. If not specified, version 1 is assumed. -* Must be specified before `size` element. -* Clients older than this version can neither show newer elements nor display +- Must be specified before `size` element. +- Clients older than this version can neither show newer elements nor display elements with new arguments correctly. -* Available since feature `formspec_version_element`. -* See also: [Version History] +- Available since feature `formspec_version_element`. +- See also: [Version History] ### `size[,,]` -* Define the size of the menu in inventory slots -* `fixed_size`: `true`/`false` (optional) -* deprecated: `invsize[,;]` +- Define the size of the menu in inventory slots +- `fixed_size`: `true`/`false` (optional) +- deprecated: `invsize[,;]` ### `position[,]` -* Must be used after `size` element. -* Defines the position on the game window of the formspec's `anchor` point. -* For X and Y, 0.0 and 1.0 represent opposite edges of the game window, +- Must be used after `size` element. +- Defines the position on the game window of the formspec's `anchor` point. +- For X and Y, 0.0 and 1.0 represent opposite edges of the game window, for example: - * [0.0, 0.0] sets the position to the top left corner of the game window. - * [1.0, 1.0] sets the position to the bottom right of the game window. -* Defaults to the center of the game window [0.5, 0.5]. + - [0.0, 0.0] sets the position to the top left corner of the game window. + - [1.0, 1.0] sets the position to the bottom right of the game window. +- Defaults to the center of the game window [0.5, 0.5]. ### `anchor[,]` -* Must be used after both `size` and `position` (if present) elements. -* Defines the location of the anchor point within the formspec. -* For X and Y, 0.0 and 1.0 represent opposite edges of the formspec, +- Must be used after both `size` and `position` (if present) elements. +- Defines the location of the anchor point within the formspec. +- For X and Y, 0.0 and 1.0 represent opposite edges of the formspec, for example: - * [0.0, 1.0] sets the anchor to the bottom left corner of the formspec. - * [1.0, 0.0] sets the anchor to the top right of the formspec. -* Defaults to the center of the formspec [0.5, 0.5]. + - [0.0, 1.0] sets the anchor to the bottom left corner of the formspec. + - [1.0, 0.0] sets the anchor to the top right of the formspec. +- Defaults to the center of the formspec [0.5, 0.5]. -* `position` and `anchor` elements need suitable values to avoid a formspec +- `position` and `anchor` elements need suitable values to avoid a formspec extending off the game window due to particular game window sizes. ### `padding[,]` -* Must be used after the `size`, `position`, and `anchor` elements (if present). -* Defines how much space is padded around the formspec if the formspec tries to +- Must be used after the `size`, `position`, and `anchor` elements (if present). +- Defines how much space is padded around the formspec if the formspec tries to increase past the size of the screen and coordinates have to be shrunk. -* For X and Y, 0.0 represents no padding (the formspec can touch the edge of the +- For X and Y, 0.0 represents no padding (the formspec can touch the edge of the screen), and 0.5 represents half the screen (which forces the coordinate size to 0). If negative, the formspec can extend off the edge of the screen. -* Defaults to [0.05, 0.05]. +- Defaults to [0.05, 0.05]. ### `no_prepend[]` -* Must be used after the `size`, `position`, `anchor`, and `padding` elements +- Must be used after the `size`, `position`, `anchor`, and `padding` elements (if present). -* Disables player:set_formspec_prepend() from applying to this formspec. +- Disables player:set_formspec_prepend() from applying to this formspec. ### `real_coordinates[]` -* INFORMATION: Enable it automatically using `formspec_version` version 2 or newer. -* When set to true, all following formspec elements will use the new coordinate system. -* If used immediately after `size`, `position`, `anchor`, and `no_prepend` elements +- INFORMATION: Enable it automatically using `formspec_version` version 2 or newer. +- When set to true, all following formspec elements will use the new coordinate system. +- If used immediately after `size`, `position`, `anchor`, and `no_prepend` elements (if present), the form size will use the new coordinate system. -* **Note**: Formspec prepends are not affected by the coordinates in the main form. +- **Note**: Formspec prepends are not affected by the coordinates in the main form. They must enable it explicitly. -* For information on converting forms to the new coordinate system, see `Migrating - to Real Coordinates`. +- For information on converting forms to the new coordinate system, see `Migrating to Real Coordinates`. ### `container[,]` -* Start of a container block, moves all physical elements in the container by +- Start of a container block, moves all physical elements in the container by (X, Y). -* Must have matching `container_end` -* Containers can be nested, in which case the offsets are added +- Must have matching `container_end` +- Containers can be nested, in which case the offsets are added (child containers are relative to parent containers) ### `container_end[]` -* End of a container, following elements are no longer relative to this +- End of a container, following elements are no longer relative to this container. ### `scroll_container[,;,;;;]` -* Start of a scroll_container block. All contained elements will ... - * take the scroll_container coordinate as position origin, - * be additionally moved by the current value of the scrollbar with the name +- Start of a scroll_container block. All contained elements will ... + - take the scroll_container coordinate as position origin, + - be additionally moved by the current value of the scrollbar with the name `scrollbar name` times `scroll factor` along the orientation `orientation` and - * be clipped to the rectangle defined by `X`, `Y`, `W` and `H`. -* `orientation`: possible values are `vertical` and `horizontal`. -* `scroll factor`: optional, defaults to `0.1`. -* Nesting is possible. -* Some elements might work a little different if they are in a scroll_container. -* Note: If you want the scroll_container to actually work, you also need to add a + - be clipped to the rectangle defined by `X`, `Y`, `W` and `H`. +- `orientation`: possible values are `vertical` and `horizontal`. +- `scroll factor`: optional, defaults to `0.1`. +- Nesting is possible. +- Some elements might work a little different if they are in a scroll_container. +- Note: If you want the scroll_container to actually work, you also need to add a scrollbar element with the specified name. Furthermore, it is highly recommended to use a scrollbaroptions element on this scrollbar. ### `scroll_container_end[]` -* End of a scroll_container, following elements are no longer bound to this +- End of a scroll_container, following elements are no longer bound to this container. ### `list[;;,;,;]` -* Show an inventory list if it has been sent to the client. -* If the inventory list changes (eg. it didn't exist before, it's resized, or its items +- Show an inventory list if it has been sent to the client. +- If the inventory list changes (eg. it didn't exist before, it's resized, or its items are moved) while the formspec is open, the formspec element may (but is not guaranteed to) adapt to the new inventory list. -* Item slots are drawn in a grid from left to right, then up to down, ordered +- Item slots are drawn in a grid from left to right, then up to down, ordered according to the slot index. -* `W` and `H` are in inventory slots, not in coordinates. -* `starting item index` (Optional): The index of the first (upper-left) item to draw. +- `W` and `H` are in inventory slots, not in coordinates. +- `starting item index` (Optional): The index of the first (upper-left) item to draw. Indices start at `0`. Default is `0`. -* The number of shown slots is the minimum of `W*H` and the inventory list's size minus +- The number of shown slots is the minimum of `W*H` and the inventory list's size minus `starting item index`. -* **Note**: With the new coordinate system, the spacing between inventory +- **Note**: With the new coordinate system, the spacing between inventory slots is one-fourth the size of an inventory slot by default. Also see [Styling Formspecs] for changing the size of slots and spacing. ### `listring[;]` -* Allows to create a ring of inventory lists -* Shift-clicking on items in one element of the ring +- Appends to an internal ring of inventory lists. +- Shift-clicking on items in one element of the ring will send them to the next inventory list inside the ring -* The first occurrence of an element inside the ring will +- The first occurrence of an element inside the ring will determine the inventory where items will be sent to ### `listring[]` -* Shorthand for doing `listring[;]` +- Shorthand for doing `listring[;]` for the last two inventory lists added by list[...] ### `listcolors[;]` -* Sets background color of slots as `ColorString` -* Sets background color of slots on mouse hovering +- Sets background color of slots as `ColorString` +- Sets background color of slots on mouse hovering ### `listcolors[;;]` -* Sets background color of slots as `ColorString` -* Sets background color of slots on mouse hovering -* Sets color of slots border +- Sets background color of slots as `ColorString` +- Sets background color of slots on mouse hovering +- Sets color of slots border ### `listcolors[;;;;]` -* Sets background color of slots as `ColorString` -* Sets background color of slots on mouse hovering -* Sets color of slots border -* Sets default background color of tooltips -* Sets default font color of tooltips +- Sets background color of slots as `ColorString` +- Sets background color of slots on mouse hovering +- Sets color of slots border +- Sets default background color of tooltips +- Sets default font color of tooltips ### `tooltip[;;;]` -* Adds tooltip for an element -* `bgcolor` tooltip background color as `ColorString` (optional) -* `fontcolor` tooltip font color as `ColorString` (optional) +- Adds tooltip for an element +- `bgcolor` tooltip background color as `ColorString` (optional) +- `fontcolor` tooltip font color as `ColorString` (optional) ### `tooltip[,;,;;;]` -* Adds tooltip for an area. Other tooltips will take priority when present. -* `bgcolor` tooltip background color as `ColorString` (optional) -* `fontcolor` tooltip font color as `ColorString` (optional) +- Adds tooltip for an area. Other tooltips will take priority when present. +- `bgcolor` tooltip background color as `ColorString` (optional) +- `fontcolor` tooltip font color as `ColorString` (optional) -### `image[,;,;]` +### `image[,;,;;]` -* Show an image +- Show an image. +- `middle` (optional): Makes the image render in 9-sliced mode and defines the middle rect. + - Requires formspec version >= 6. + - See `background9[]` documentation for more information. -### `animated_image[,;,;;;;;]` +### `animated_image[,;,;;;;;;]` -* Show an animated image. The image is drawn like a "vertical_frames" tile - animation (See [Tile animation definition]), but uses a frame count/duration - for simplicity -* `name`: Element name to send when an event occurs. The event value is the index of the current frame. -* `texture name`: The image to use. -* `frame count`: The number of frames animating the image. -* `frame duration`: Milliseconds between each frame. `0` means the frames don't advance. -* `frame start` (Optional): The index of the frame to start on. Default `1`. +- Show an animated image. The image is drawn like a "vertical_frames" tile + animation (See [Tile animation definition]), but uses a frame count/duration for simplicity +- `name`: Element name to send when an event occurs. The event value is the index of the current frame. +- `texture name`: The image to use. +- `frame count`: The number of frames animating the image. +- `frame duration`: Milliseconds between each frame. `0` means the frames don't advance. +- `frame start` (optional): The index of the frame to start on. Default `1`. +- `middle` (optional): Makes the image render in 9-sliced mode and defines the middle rect. + - Requires formspec version >= 6. + - See `background9[]` documentation for more information. ### `model[,;,;;;;;;;;]` -* Show a mesh model. -* `name`: Element name that can be used for styling -* `mesh`: The mesh model to use. -* `textures`: The mesh textures to use according to the mesh materials. - Texture names must be separated by commas. -* `rotation {X,Y}` (Optional): Initial rotation of the camera. +- Show a mesh model. +- `name`: Element name that can be used for styling +- `mesh`: The mesh model to use. +- `textures`: The mesh textures to use according to the mesh materials. + Texture names must be separated by commas. +- `rotation {X,Y}` (Optional): Initial rotation of the camera. The axes are euler angles in degrees. -* `continuous` (Optional): Whether the rotation is continuous. Default `false`. -* `mouse control` (Optional): Whether the model can be controlled with the mouse. Default `true`. -* `frame loop range` (Optional): Range of the animation frames. - * Defaults to the full range of all available frames. - * Syntax: `,` -* `animation speed` (Optional): Sets the animation speed. Default 0 FPS. +- `continuous` (Optional): Whether the rotation is continuous. Default `false`. +- `mouse control` (Optional): Whether the model can be controlled with the mouse. Default `true`. +- `frame loop range` (Optional): Range of the animation frames. + - Defaults to the full range of all available frames. + - Syntax: `,` +- `animation speed` (Optional): Sets the animation speed. Default 0 FPS. ### `item_image[,;,;]` -* Show an inventory image of registered item/node +- Show an inventory image of registered item/node ### `bgcolor[;;]` -* Sets background color of formspec. -* `bgcolor` and `fbgcolor` (optional) are `ColorString`s, they define the color +- Sets background color of formspec. +- `bgcolor` and `fbgcolor` (optional) are `ColorString`s, they define the color of the non-fullscreen and the fullscreen background. -* `fullscreen` (optional) can be one of the following: - * `false`: Only the non-fullscreen background color is drawn. (default) - * `true`: Only the fullscreen background color is drawn. - * `both`: The non-fullscreen and the fullscreen background color are drawn. - * `neither`: No background color is drawn. -* Note: Leave a parameter empty to not modify the value. -* Note: `fbgcolor`, leaving parameters empty and values for `fullscreen` that +- `fullscreen` (optional) can be one of the following: + - `false`: Only the non-fullscreen background color is drawn. (default) + - `true`: Only the fullscreen background color is drawn. + - `both`: The non-fullscreen and the fullscreen background color are drawn. + - `neither`: No background color is drawn. +- Note: Leave a parameter empty to not modify the value. +- Note: `fbgcolor`, leaving parameters empty and values for `fullscreen` that are not bools are only available since formspec version 3. ### `background[,;,;]` -* Example for formspec 8x4 in 16x resolution: image shall be sized - 8 times 16px times 4 times 16px. +- Example for formspec 8x4 in 16x resolution: image shall be sized + 8 times 16px times 4 times 16px. ### `background[,;,;;]` -* Example for formspec 8x4 in 16x resolution: - image shall be sized 8 times 16px times 4 times 16px -* If `auto_clip` is `true`, the background is clipped to the formspec size +- Example for formspec 8x4 in 16x resolution: + image shall be sized 8 times 16px times 4 times 16px +- If `auto_clip` is `true`, the background is clipped to the formspec size (`x` and `y` are used as offset values, `w` and `h` are ignored) ### `background9[,;,;;;]` -* 9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling -* Middle is a rect which defines the middle of the 9-slice. - * `x` - The middle will be x pixels from all sides. - * `x,y` - The middle will be x pixels from the horizontal and y from the vertical. - * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values - will be added to the width and height of the texture, allowing it to be used as the - distance from the far end. - * All numbers in middle are integers. -* Example for formspec 8x4 in 16x resolution: - image shall be sized 8 times 16px times 4 times 16px -* If `auto_clip` is `true`, the background is clipped to the formspec size +- 9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling +- Middle is a rect which defines the middle of the 9-slice. + - `x` - The middle will be x pixels from all sides. + - `x,y` - The middle will be x pixels from the horizontal and y from the vertical. + - `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values + will be added to the width and height of the texture, allowing it to be used as the + distance from the far end. + - All numbers in middle are integers. +- If `auto_clip` is `true`, the background is clipped to the formspec size (`x` and `y` are used as offset values, `w` and `h` are ignored) -* Available since formspec version 2 +- Available since formspec version 2 ### `pwdfield[,;,;;

,,...,;;;]` -* Show a tab**header** at specific position (ignores formsize) -* `X` and `Y`: position of the tabheader -* *Note*: Width and height are automatically chosen with this syntax -* `name` fieldname data is transferred to Lua -* `caption 1`...: name shown on top of tab -* `current_tab`: index of selected tab 1... -* `transparent` (optional): if true, tabs are semi-transparent -* `draw_border` (optional): if true, draw a thin line at tab base +- Show a tab**header** at specific position (ignores formsize) +- `X` and `Y`: position of the tabheader +- _Note_: Width and height are automatically chosen with this syntax +- `name` fieldname data is transferred to Lua +- `caption 1`...: name shown on top of tab +- `current_tab`: index of selected tab 1... +- `transparent` (optional): if true, tabs are semi-transparent +- `draw_border` (optional): if true, draw a thin line at tab base ### `tabheader[,;;;,,...,;;;]` -* Show a tab**header** at specific position (ignores formsize) -* **Important note**: This syntax for tabheaders can only be used with the +- Show a tab**header** at specific position (ignores formsize) +- **Important note**: This syntax for tabheaders can only be used with the new coordinate system. -* `X` and `Y`: position of the tabheader -* `H`: height of the tabheader. Width is automatically determined with this syntax. -* `name` fieldname data is transferred to Lua -* `caption 1`...: name shown on top of tab -* `current_tab`: index of selected tab 1... -* `transparent` (optional): show transparent -* `draw_border` (optional): draw border +- `X` and `Y`: position of the tabheader +- `H`: height of the tabheader. Width is automatically determined with this syntax. +- `name` fieldname data is transferred to Lua +- `caption 1`...: name shown on top of tab +- `current_tab`: index of selected tab 1... +- `transparent` (optional): show transparent +- `draw_border` (optional): draw border ### `tabheader[,;,;;,,...,;;;]` -* Show a tab**header** at specific position (ignores formsize) -* **Important note**: This syntax for tabheaders can only be used with the +- Show a tab**header** at specific position (ignores formsize) +- **Important note**: This syntax for tabheaders can only be used with the new coordinate system. -* `X` and `Y`: position of the tabheader -* `W` and `H`: width and height of the tabheader -* `name` fieldname data is transferred to Lua -* `caption 1`...: name shown on top of tab -* `current_tab`: index of selected tab 1... -* `transparent` (optional): show transparent -* `draw_border` (optional): draw border +- `X` and `Y`: position of the tabheader +- `W` and `H`: width and height of the tabheader +- `name` fieldname data is transferred to Lua +- `caption 1`...: name shown on top of tab +- `current_tab`: index of selected tab 1... +- `transparent` (optional): show transparent +- `draw_border` (optional): draw border ### `box[,;,;]` -* Simple colored box -* `color` is color specified as a `ColorString`. +- Simple colored box +- `color` is color specified as a `ColorString`. If the alpha component is left blank, the box will be semitransparent. If the color is not specified, the box will use the options specified by its style. If the color is specified, all styling options will be ignored. ### `dropdown[,;;;,, ...,;;]` -* Show a dropdown field -* **Important note**: There are two different operation modes: - 1. handle directly on change (only changed dropdown is submitted) - 2. read the value on pressing a button (all dropdown values are available) -* `X` and `Y`: position of the dropdown -* `W`: width of the dropdown. Height is automatically chosen with this syntax. -* Fieldname data is transferred to Lua -* Items to be shown in dropdown -* Index of currently selected dropdown item -* `index event` (optional, allowed parameter since formspec version 4): Specifies the +- Show a dropdown field +- **Important note**: There are two different operation modes: + 1. handle directly on change (only changed dropdown is submitted) + 2. read the value on pressing a button (all dropdown values are available) +- `X` and `Y`: position of the dropdown +- `W`: width of the dropdown. Height is automatically chosen with this syntax. +- Fieldname data is transferred to Lua +- Items to be shown in dropdown +- Index of currently selected dropdown item +- `index event` (optional, allowed parameter since formspec version 4): Specifies the event field value for selected items. - * `true`: Selected item index - * `false` (default): Selected item value + - `true`: Selected item index + - `false` (default): Selected item value ### `dropdown[,;,;;,, ...,;;]` -* Show a dropdown field -* **Important note**: This syntax for dropdowns can only be used with the +- Show a dropdown field +- **Important note**: This syntax for dropdowns can only be used with the new coordinate system. -* **Important note**: There are two different operation modes: - 1. handle directly on change (only changed dropdown is submitted) - 2. read the value on pressing a button (all dropdown values are available) -* `X` and `Y`: position of the dropdown -* `W` and `H`: width and height of the dropdown -* Fieldname data is transferred to Lua -* Items to be shown in dropdown -* Index of currently selected dropdown item -* `index event` (optional, allowed parameter since formspec version 4): Specifies the +- **Important note**: There are two different operation modes: + 1. handle directly on change (only changed dropdown is submitted) + 2. read the value on pressing a button (all dropdown values are available) +- `X` and `Y`: position of the dropdown +- `W` and `H`: width and height of the dropdown +- Fieldname data is transferred to Lua +- Items to be shown in dropdown +- Index of currently selected dropdown item +- `index event` (optional, allowed parameter since formspec version 4): Specifies the event field value for selected items. - * `true`: Selected item index - * `false` (default): Selected item value + - `true`: Selected item index + - `false` (default): Selected item value ### `checkbox[,;;