From d291b1bcfd00a912598cb13c293e1f053ddd593c Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 19:27:49 +0200 Subject: [PATCH 01/95] Add some more `@nodiscard` --- api/http.lua | 2 ++ api/server.lua | 3 +++ 2 files changed, 5 insertions(+) diff --git a/api/http.lua b/api/http.lua index 1e0093a..feccff1 100644 --- a/api/http.lua +++ b/api/http.lua @@ -81,6 +81,7 @@ 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 +92,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/server.lua b/api/server.lua index 19a6722..84a9da3 100644 --- a/api/server.lua +++ b/api/server.lua @@ -17,14 +17,17 @@ function minetest.cancel_shutdown_requests() end ---@param name string ---@param joined any 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. From 690cd9a476b5581d7974e01c4509ad7c6308d057 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 19:34:48 +0200 Subject: [PATCH 02/95] Make `HTTPRequest` et `HTTPRequestResult` use the right class syntax --- api/http.lua | 51 +++++++++++++-------------------------------------- 1 file changed, 13 insertions(+), 38 deletions(-) diff --git a/api/http.lua b/api/http.lua index feccff1..85c8d88 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 From 80acd438125d37b927cef501a492ff4d1b1512e1 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 19:41:09 +0200 Subject: [PATCH 03/95] Some more `@nodiscard` --- api/environment.lua | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/api/environment.lua b/api/environment.lua index 145d8c9..4459df4 100644 --- a/api/environment.lua +++ b/api/environment.lua @@ -272,11 +272,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 +286,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 +299,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 +363,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 +398,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`. @@ -463,6 +470,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,6 +492,8 @@ 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 function minetest.spawn_tree(pos, treedef) end @@ -495,11 +505,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` @@ -561,4 +573,5 @@ function minetest.check_for_falling(pos) end ---@param x integer ---@param z integer ---@return integer +---@nodiscard function minetest.get_spawn_level(x, z) end From dd0124f7cc6edd15cf5ccb5824b5ce83cce653a0 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 21:24:40 +0200 Subject: [PATCH 04/95] `minetest.spawn_tree` --- api/environment.lua | 83 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/api/environment.lua b/api/environment.lua index 4459df4..bbe9709 100644 --- a/api/environment.lua +++ b/api/environment.lua @@ -496,6 +496,89 @@ function minetest.line_of_sight(pos1, pos2) end ---@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. From 3d4d06d6d639b0386717e710a13bdbff74525283 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 21:29:07 +0200 Subject: [PATCH 05/95] `minetest.clear_craft` --- api/register/gameplay.lua | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/api/register/gameplay.lua b/api/register/gameplay.lua index e72dc27..62adacb 100644 --- a/api/register/gameplay.lua +++ b/api/register/gameplay.lua @@ -79,3 +79,18 @@ ---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 From 6c6eb473e4b3773e1849d46e094448e8bb87366b Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 21:37:15 +0200 Subject: [PATCH 06/95] chat commands --- api/register/gameplay.lua | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/api/register/gameplay.lua b/api/register/gameplay.lua index 62adacb..d343eda 100644 --- a/api/register/gameplay.lua +++ b/api/register/gameplay.lua @@ -94,3 +94,35 @@ function minetest.register_craft(recipe) end ---@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 From a76e9c57898b57b2bf900479fb523572573691e6 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 21:38:46 +0200 Subject: [PATCH 07/95] Better node --- classes/node.lua | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) 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 From b4bc3ef9c5bc9d92f8a0984d6ef179706ed3701a Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 21:43:23 +0200 Subject: [PATCH 08/95] `@nodiscard` for auth functions --- auth.lua | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/auth.lua b/auth.lua index e88e46a..8689b30 100644 --- a/auth.lua +++ b/auth.lua @@ -20,6 +20,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 +46,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 +56,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 +67,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 +96,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 From 16d8a7cfe7e4581c1b27e3f4c1bd1129052d9486 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 21:45:11 +0200 Subject: [PATCH 09/95] Fix deprecated `@vararg` in `minetest.debug` --- log.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From a4247d0e7fa462c0ac052946bd401a5d217a915d Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 21:46:43 +0200 Subject: [PATCH 10/95] Fix missing `-` --- api/mod_channels.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 8ef0b8969b12bcf8063b195dc36b305052d6c8d6 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 21:53:31 +0200 Subject: [PATCH 11/95] `@nodiscard`some environment functions --- api/environment.lua | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/api/environment.lua b/api/environment.lua index bbe9709..b49857b 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: From e75e4d413e2d146dc3f07a62163b7013d32a0dcc Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 22:56:47 +0200 Subject: [PATCH 12/95] `minetest.get_inventory` + detached inventories --- classes/invref.lua | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/classes/invref.lua b/classes/invref.lua index 0e8bad9..10155ce 100644 --- a/classes/invref.lua +++ b/classes/invref.lua @@ -97,3 +97,44 @@ function InvRef:remove_item(listname, stack) end ---Returns a location compatible with `minetest.get_inventory(location)`. ---@return inventory_location function InvRef:get_location() end + +---Get an inventory. +---@param location {type: '"player"', name: string}|{type: '""', node: Vector}|{type: '"detached"', name: string} +---@return InvRef? +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 From 51815f615d8733b4e20442888fca65f0f9a700f2 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 1 Oct 2022 23:02:33 +0200 Subject: [PATCH 13/95] Add temporary registered_[nodes,items,tools,craftitems] tables --- config.lua | 2 ++ types/node_definition.lua | 12 ++++++++++++ 2 files changed, 14 insertions(+) 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/types/node_definition.lua b/types/node_definition.lua index b6ee0d3..d6f9a0d 100644 --- a/types/node_definition.lua +++ b/types/node_definition.lua @@ -501,3 +501,15 @@ function minetest.override_item(name, redefinition) end ---@param name string function minetest.unregister_item(name) end + +---@type table +minetest.registered_nodes = {} + +---@type table +minetest.registered_items = {} + +---@type table +minetest.registered_tools = {} + +---@type table +minetest.registered_craftitems = {} From 64aea48bd7b9dd347d1d5ae77b01c13a0380d7c8 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sun, 2 Oct 2022 15:45:46 +0200 Subject: [PATCH 14/95] Add VSCode settings --- .vscode/settings.json | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..bf562ac --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "material-icon-theme.activeIconPack": "none" +} From 8faf8a11151467b58ce736418df63629f93e8997 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sun, 2 Oct 2022 16:09:26 +0200 Subject: [PATCH 15/95] Document paramtype and paramtype2 --- types/node_definition.lua | 135 +++++++++++++++++++++++++++++++++++++- 1 file changed, 133 insertions(+), 2 deletions(-) diff --git a/types/node_definition.lua b/types/node_definition.lua index d6f9a0d..846e7c3 100644 --- a/types/node_definition.lua +++ b/types/node_definition.lua @@ -28,21 +28,152 @@ ---@alias tile_definition string|{name: string, animation: tile_animation_definition}|{name: string, backface_culling: boolean, align_style: '"node"'|'"world"'|'"user"', scale: integer}|{name: string, color: ColorSpec} ---@alias 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. ----|'"node"' # `param1` will not be used by the engine and can be used to store an arbitrary value +---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 +---|'"light"' +---`param1` will not be used by the engine and can be used to store an arbitrary value +---|'"node"' ---@alias paramtype2 +---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) ---|'"flowingliquid"' +---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- ---|'"wallmounted"' +---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 ---|'"facedir"' +---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. ---|'"leveled"' +---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. ---|'"degrotate"' +---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) ---|'"meshoptions"' +---`param2` tells which color is picked from the palette. +--- +---The palette should have 256 pixels. ---|'"color"' +---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. ---|'"colorfacedir"' +---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. ---|'"colorwallmounted"' +---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"}` ---|'"glasslikeliquidlevel"' +---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) ---|'"colordegrotate"' +---`param2` will not be used by the engine and can be used to store an arbitrary value ---|'"none"' ---@alias liquidtype From 28d1f8422520633410d33d61551baacee5313ade Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sun, 2 Oct 2022 16:12:17 +0200 Subject: [PATCH 16/95] Privilege definition use right `@class` syntax --- privs.lua | 21 +++++---------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/privs.lua b/privs.lua index a9fae56..5124104 100644 --- a/privs.lua +++ b/privs.lua @@ -1,37 +1,26 @@ ---@meta ---@class privilege_definition -local privilege_definition = {} - ---Privilege description. ----@type string -privilege_definition.description = nil - +---@field description string ---Whether to grant the privilege to singleplayer. ----@type boolean -privilege_definition.give_to_singleplayer = nil - +---@field give_to_singleplayer boolean ---Whether to grant the privilege to the server admin. --- ---Uses value of 'give_to_singleplayer' by default. ----@type boolean -privilege_definition.give_to_admin = nil - +---@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. ----@type fun(name: string, granter_name?: string): boolean -privilege_definition.on_grant = nil - +---@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. ----@type fun(name: string, revoker_name?: string): boolean -privilege_definition.on_revoke = nil +---@field on_revoke fun(name: string, revoker_name?: string): boolean ---Register a new privilege. From c80f68fd1ff64a6baf465e8e5eb339506631fdd1 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sun, 2 Oct 2022 16:25:33 +0200 Subject: [PATCH 17/95] player_informations use right `@class` syntax --- utils.lua | 75 +++++++++++++------------------------------------------ 1 file changed, 18 insertions(+), 57 deletions(-) diff --git a/utils.lua b/utils.lua index 9a8196b..ad77fac 100644 --- a/utils.lua +++ b/utils.lua @@ -150,105 +150,66 @@ minetest.features.get_sky_as_table = true function minetest.has_feature(arg) end ---@class player_informations -local player_informations = {} - ---IP address of the client. ----@type string -player_informations.address = nil - +---@field address string ---IPv4 / IPv6 ----@type 4|6 -player_informations.ip_version = nil - +---@field ip_version 4|6 ---Seconds since the client connected. ----@type integer -player_informations.connection_uptime = nil - +---@field connection_uptime integer ---Protocol version used by the client. ----@type integer -player_informations.protocol_version = nil - +---@field protocol_version integer ---Formspec version supported by the client. ----@type integer -player_informations.formspec_version = nil - +---@field formspec_version integer ---Language code used by the client for translation. ----@type lang_code -player_informations.lang_code = nil - +---@field lang_code lang_code ---Minimum round trip time. --- ---**Can be missing if no stats have been collected yet.** ----@type number -player_informations.min_rtt = nil - +---@field min_rtt number? ---Maximum round trip time. --- ---**Can be missing if no stats have been collected yet.** ----@type number -player_informations.max_rtt = nil - +---@field max_rtt number? ---Average round trip time. --- ---**Can be missing if no stats have been collected yet.** ----@type number -player_informations.avg_rtt = nil - +---@field avg_rtt number? ---Minimum packet time jitter. --- ---**Can be missing if no stats have been collected yet.** ----@type number -player_informations.min_jitter = nil - +---@field min_jitter number? ---Maximum packet time jitter. --- ---**Can be missing if no stats have been collected yet.** ----@type number -player_informations.max_jitter = nil - +---@field max_jitter number? ---Average packet time jitter. --- ---**Can be missing if no stats have been collected yet.** ----@type number -player_informations.avg_jitter = nil - +---@field avg_jitter number? ---Serialization version used by client. --- ---**DEBUG BUILD ONLY** ----@type integer -player_informations.ser_vers = nil - +---@field ser_vers integer? ---Major version number. --- ---**DEBUG BUILD ONLY** ----@type integer -player_informations.major = nil - +---@field major integer? ---Minor version number. --- ---**DEBUG BUILD ONLY** ----@type integer -player_informations.minor = nil - +---@field minor integer? ---Patch version number. --- ---**DEBUG BUILD ONLY** ----@type integer -player_informations.patch = nil - +---@field patch integer? ---Full version string. --- ---**DEBUG BUILD ONLY** ----@type string -player_informations.vers_string = nil - ---FIXME: all possible states - +---@field vers_string string? ---Current client state. --- ---**DEBUG BUILD ONLY** ----@type string -player_informations.state = nil +---@field state '"Invalid"'|'"Disconnecting"'|'"Denied"'|'"Created"'|'"AwaitingInit2"'|'"HelloSent"'|'"InitDone"'|'"DefinitionsSent"'|'"Active"'|'"SudoMode"'|nil ---Returns a table containing informations about a player. From b59b6fb9a02ea12ce5587ed1158048b5637ee437 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sun, 2 Oct 2022 16:27:00 +0200 Subject: [PATCH 18/95] engine_version use right `@class`syntax --- utils.lua | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/utils.lua b/utils.lua index ad77fac..f0b0d2c 100644 --- a/utils.lua +++ b/utils.lua @@ -285,19 +285,12 @@ function minetest.safe_file_write(path, content) end --- ---Compatible forks will have an entirely different name and version. ---@class engine_version -local engine_version = {} - ---Name of the project, eg, `"Minetest"`. ----@type string -engine_version.project = nil - +---@field project string ---Simple version, eg, `"1.2.3-dev"`. ----@type string -engine_version.string = nil - +---@field string string ---Full git version (only set if available), eg, `"1.2.3-dev-01234567-dirty"`. ----@type string -engine_version.hash = nil +---@field hash string ---Returns a table containing components of the engine version. ---@return engine_version From caa9de2d6d1810285a51d702577739c427ca39c2 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sun, 2 Oct 2022 16:28:31 +0200 Subject: [PATCH 19/95] dynamic_add_media_options use right `@class`syntax --- api/server.lua | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/api/server.lua b/api/server.lua index 84a9da3..33c48b0 100644 --- a/api/server.lua +++ b/api/server.lua @@ -47,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). --- From baecdbb17b8053870d33af8a5ed1e0ac73af1086 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sun, 2 Oct 2022 16:48:08 +0200 Subject: [PATCH 20/95] Object Properties Documentation --- classes/objectref.lua | 117 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 114 insertions(+), 3 deletions(-) diff --git a/classes/objectref.lua b/classes/objectref.lua index 7b69357..b06405b 100644 --- a/classes/objectref.lua +++ b/classes/objectref.lua @@ -151,38 +151,149 @@ function ObjectRef:get_bone_position(bone) end ---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. @@ -193,7 +304,7 @@ function ObjectRef:get_properties() end ---@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 function ObjectRef:is_player() end From 2a67abd5fad35f92d8dd301aa31b5475f4d2bd3c Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sun, 2 Oct 2022 19:20:55 +0200 Subject: [PATCH 21/95] Remove invalid comment --- classes/objectref.lua | 2 -- 1 file changed, 2 deletions(-) diff --git a/classes/objectref.lua b/classes/objectref.lua index b06405b..2a9f3cd 100644 --- a/classes/objectref.lua +++ b/classes/objectref.lua @@ -147,8 +147,6 @@ function ObjectRef:set_bone_position(bone, position, rotation) end ---@return Vector rotation function ObjectRef:get_bone_position(bone) end ---FIXME: document object_properties - ---Object Properties ---@class object_properties ---**Player Only** From 0cecf56a713d01e34b480bd4591260d43f2bf84a Mon Sep 17 00:00:00 2001 From: AFCMS Date: Sat, 8 Oct 2022 11:50:06 +0200 Subject: [PATCH 22/95] Fixes --- api/misc.lua | 2 +- classes/objectref.lua | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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/classes/objectref.lua b/classes/objectref.lua index 2a9f3cd..93da651 100644 --- a/classes/objectref.lua +++ b/classes/objectref.lua @@ -770,7 +770,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 From 6c98e9a00096f0efcb93078ecf2be28408ca8040 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 00:22:40 +0200 Subject: [PATCH 23/95] Make HUD definition use the right class syntax --- classes/objectref.lua | 71 ++++++++++++++++--------------------------- 1 file changed, 26 insertions(+), 45 deletions(-) diff --git a/classes/objectref.lua b/classes/objectref.lua index 93da651..540aadf 100644 --- a/classes/objectref.lua +++ b/classes/objectref.lua @@ -696,62 +696,43 @@ 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** --- From d005ff9ea9c558728c52bca40088de56a210215e Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 00:25:14 +0200 Subject: [PATCH 24/95] Make tool capabilities use the right class definition --- types/tool_capabilities.lua | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/types/tool_capabilities.lua b/types/tool_capabilities.lua index cf50368..0dff383 100644 --- a/types/tool_capabilities.lua +++ b/types/tool_capabilities.lua @@ -10,24 +10,14 @@ --- ---Missing or incomplete tool capabilities will default to the player's hand. ---@class tool_capabilities -local tool_capabilities = {} - ---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. ----@type number -tool_capabilities.full_punch_interval = nil - +---@field full_punch_interval number ---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. ----@type number -tool_capabilities.max_drop_level = nil - - ----@type table -tool_capabilities.groupcaps = {} - +---@field max_drop_level number +---@field groupcaps table ---Damage per groups of entities. See [Entity damage mechanism]. ----@type table -tool_capabilities.damage_groups = {} +---@field damage_groups table From 27bca74c3ca6c8984d87d9132784be5f08843d78 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 00:27:31 +0200 Subject: [PATCH 25/95] Make job use the right class syntax --- api/after.lua | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) 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 From 9bba3445ea2702c8ee94816469dc7fe2b18fcb33 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 00:41:54 +0200 Subject: [PATCH 26/95] Use the right class syntax for some ObjectRef param tables --- classes/objectref.lua | 159 ++++++++++-------------------------------- 1 file changed, 38 insertions(+), 121 deletions(-) diff --git a/classes/objectref.lua b/classes/objectref.lua index 540aadf..151cdab 100644 --- a/classes/objectref.lua +++ b/classes/objectref.lua @@ -656,31 +656,18 @@ function ObjectRef:get_player_control() end 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** --- @@ -830,93 +817,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** --- @@ -943,35 +898,22 @@ function ObjectRef:get_sky(as_table) end 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** --- @@ -1027,25 +969,16 @@ function ObjectRef:set_moon(parameters) end 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** --- @@ -1062,33 +995,20 @@ function ObjectRef:set_stars(parameters) end 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** --- @@ -1170,12 +1090,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** --- From b1e4a284220121103d344f3523dee5f20e0577bf Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 00:45:35 +0200 Subject: [PATCH 27/95] Make pointed_thing use the right class syntax --- classes/raycast.lua | 13 +++---------- types/pointed_thing.lua | 17 ++++------------- 2 files changed, 7 insertions(+), 23 deletions(-) diff --git a/classes/raycast.lua b/classes/raycast.lua index ba1d001..e13a162 100644 --- a/classes/raycast.lua +++ b/classes/raycast.lua @@ -13,25 +13,18 @@ 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 local raycast = {} diff --git a/types/pointed_thing.lua b/types/pointed_thing.lua index 6dab20c..ab57802 100644 --- a/types/pointed_thing.lua +++ b/types/pointed_thing.lua @@ -8,20 +8,11 @@ ---* `{type="object", ref=ObjectRef}` --- * Indicate a pointed ObjectRef ---@class pointed_thing -local pointed_thing - ---Indicates what is pointed at. ----@type '"nothing"'|'"node"'|'"object"' -pointed_thing.type = nil - +---@field type '"nothing"'|'"node"'|'"object"' ---Node position behind the pointed face. ----@type Vector -pointed_thing.under = nil - +---@field under Vector ---Node position in front of the pointed face. ----@type Vector -pointed_thing.above = nil - +---@field above Vector ---Pointed ObjectRef. ----@type ObjectRef -pointed_thing.ref = nil +---@field ref ObjectRef From 6d76b079fe5ac6921a697823f0455621fff72912 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 00:55:48 +0200 Subject: [PATCH 28/95] Fix `minetest.clear_objects` optional param --- api/environment.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/environment.lua b/api/environment.lua index b49857b..de3f789 100644 --- a/api/environment.lua +++ b/api/environment.lua @@ -449,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`. From d3e064ff600b4283f1c1b9e6502eba75f5bd61b3 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:06:43 +0200 Subject: [PATCH 29/95] Some helper functions --- api/helpers.lua | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) 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 From 655f6d39be274ec0bee3e2c834243c0c66b4f6fe Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:09:28 +0200 Subject: [PATCH 30/95] Add `@nodiscard` to color utils --- colors.lua | 8 ++++++++ 1 file changed, 8 insertions(+) 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 From 6f55caa7e9c853df50019cd6fb76193f8d892b5a Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:10:40 +0200 Subject: [PATCH 31/95] =?UTF-8?q?Add=C2=A0`@nodiscard`=20to=20some=20ban?= =?UTF-8?q?=20functions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api/bans.lua | 2 ++ 1 file changed, 2 insertions(+) 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 From 7568ce57a6e9490777a201c432a0cae502299347 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:13:11 +0200 Subject: [PATCH 32/95] Add some `@nodiscard` to `AreaStore` --- api/http.lua | 1 + classes/areastore.lua | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/api/http.lua b/api/http.lua index 85c8d88..0856638 100644 --- a/api/http.lua +++ b/api/http.lua @@ -51,6 +51,7 @@ 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. diff --git a/classes/areastore.lua b/classes/areastore.lua index 79852ce..1bba7c2 100644 --- a/classes/areastore.lua +++ b/classes/areastore.lua @@ -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 From b063cfa598ff74ff1e592c64670e482e7210e81e Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:15:04 +0200 Subject: [PATCH 33/95] Add some `@nodiscard` to `ItemStack` --- classes/itemstack.lua | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/classes/itemstack.lua b/classes/itemstack.lua index 2a146c4..e7762d7 100644 --- a/classes/itemstack.lua +++ b/classes/itemstack.lua @@ -3,6 +3,7 @@ ---Returns an `ItemStack` ---@param x ItemStack|string|table|nil ---@return ItemStack +---@nodiscard function ItemStack(x) end ---An `ItemStack` is a stack of items. @@ -11,10 +12,12 @@ 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,6 +142,7 @@ 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. From 1a040b30b535f70e0215d1b3bbfcb2bb59ef0500 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:18:18 +0200 Subject: [PATCH 34/95] Add some `@nodiscard` to `Vector` --- classes/vector.lua | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) 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 From 5e2d73aad9cb8adb9e843e98e46e9fd1bef9c141 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:20:37 +0200 Subject: [PATCH 35/95] Add some `@nodiscard` to `InvRef` --- classes/invref.lua | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/classes/invref.lua b/classes/invref.lua index 10155ce..39bc501 100644 --- a/classes/invref.lua +++ b/classes/invref.lua @@ -7,11 +7,13 @@ 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). @@ -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,11 +104,13 @@ 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 ---Get an inventory. ----@param location {type: '"player"', name: string}|{type: '""', node: Vector}|{type: '"detached"', name: string} +---@param location {type: '"player"', name: string}|{type: '"node"', node: Vector}|{type: '"detached"', name: string} ---@return InvRef? +---@nodiscard function minetest.get_inventory(location) end ---@class detached_inventory_callbacks From a401558ee3fec5b9541bb41182d4d52b4efd2187 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:22:03 +0200 Subject: [PATCH 36/95] Make inventory location use right class syntax --- types/inventory_location.lua | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/types/inventory_location.lua b/types/inventory_location.lua index 7034f01..1dd1ee4 100644 --- a/types/inventory_location.lua +++ b/types/inventory_location.lua @@ -1,18 +1,11 @@ ---@meta ---@class inventory_location -local inventory_location = {} - ---Define the inventory location type. ----@type '"player"'|'"node"'|'"detached"'|'"undefined"' -inventory_location.type = nil - +---@field type '"player"'|'"node"'|'"detached"'|'"undefined"' ---If inventory location is player, refers to the player name. --- ---If inventory location is detached, refers to the detached inventory name. ----@type string -inventory_location.name = nil - +---@field name string ---If inventory location is node, refers to the node position. ----@type Vector? -inventory_location.pos = nil +---@field pos Vector? From fc1421fcc5d8e3ad18dba3575d1a9b89dade9c45 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:24:38 +0200 Subject: [PATCH 37/95] Add some `@nodiscard` to metadata --- classes/metadata.lua | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/classes/metadata.lua b/classes/metadata.lua index 063e09b..cd4572c 100644 --- a/classes/metadata.lua +++ b/classes/metadata.lua @@ -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 = {} From cc4af6d1bc414650a74a01d6c7adc48031673beb Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:26:34 +0200 Subject: [PATCH 38/95] Add some `@nodiscard` to `Settings` --- classes/settings.lua | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) 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 From c7b3ba988e4abc004d8c76b43747f2b90300891b Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:27:12 +0200 Subject: [PATCH 39/95] Add `@nodiscard` to `ModChannel` --- classes/modchannel.lua | 1 + 1 file changed, 1 insertion(+) diff --git a/classes/modchannel.lua b/classes/modchannel.lua index 6d6dd35..73c770e 100644 --- a/classes/modchannel.lua +++ b/classes/modchannel.lua @@ -14,6 +14,7 @@ function ModChannel:leave() end ---Returns true if channel is writeable and mod can send over it. ---@return boolean +---@nodiscard function ModChannel:is_writable() end ---If mod channel is not writeable or invalid, message will be dropped. From 2ebe9cf03cb560c131638f7b6159c5e07e8b6285 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:28:07 +0200 Subject: [PATCH 40/95] Add some `@nodiscard` to `NodeTimerRef` --- classes/nodetimerref.lua | 3 +++ 1 file changed, 3 insertions(+) diff --git a/classes/nodetimerref.lua b/classes/nodetimerref.lua index 563f1c7..a9d7fc0 100644 --- a/classes/nodetimerref.lua +++ b/classes/nodetimerref.lua @@ -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 From b3232b7002790f9e88368579e3d6b731c337b54c Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:33:35 +0200 Subject: [PATCH 41/95] Add some `@nodiscard` to `ObjectRef` --- classes/objectref.lua | 52 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/classes/objectref.lua b/classes/objectref.lua index 151cdab..f7031a2 100644 --- a/classes/objectref.lua +++ b/classes/objectref.lua @@ -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. @@ -55,6 +57,7 @@ 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 @@ -65,18 +68,22 @@ 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 +93,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,6 +105,7 @@ 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. @@ -126,10 +135,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,6 +156,7 @@ 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 ---Object Properties @@ -296,6 +308,7 @@ function ObjectRef:get_bone_position(bone) end ---Returns object properties. ---@return object_properties +---@nodiscard function ObjectRef:get_properties() end ---Set objects properties. @@ -304,15 +317,17 @@ function ObjectRef:set_properties(object_properties) end ---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. @@ -346,6 +361,7 @@ function ObjectRef:set_acceleration(acc) end --- ---Returns the acceleration of the object. ---@return Vector +---@nodiscard function ObjectRef:get_acceleration() end ---**Luaentity Only** @@ -366,6 +382,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** @@ -378,6 +395,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** @@ -392,6 +410,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** @@ -419,6 +438,7 @@ 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 @@ -427,6 +447,7 @@ function ObjectRef:get_entity_name() end --- ---Returns object luaentity. ---@return table +---@nodiscard function ObjectRef:get_luaentity() end ----------------- @@ -439,6 +460,7 @@ function ObjectRef:get_luaentity() end --- ---Returns `""` if object isn't a player. ---@return string +---@nodiscard function ObjectRef:get_player_name() end ---**Player Only** @@ -446,6 +468,7 @@ function ObjectRef:get_player_name() end ---**DEPRECATED**, use `get_velocity()` instead. ---@deprecated ---@return Vector +---@nodiscard function ObjectRef:get_player_velocity() end ---**Player Only** @@ -459,6 +482,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** @@ -467,6 +491,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** @@ -483,6 +508,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** @@ -502,6 +528,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** @@ -524,6 +551,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** @@ -544,6 +572,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** @@ -569,6 +598,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** @@ -595,12 +625,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** @@ -633,6 +665,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** @@ -653,6 +686,7 @@ 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 @@ -679,6 +713,7 @@ 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 @@ -747,6 +782,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 @@ -769,6 +805,7 @@ function ObjectRef:hud_set_flags(flags) end --- ---Returns player HUD flags. ---@return hud_flags +---@nodiscard function ObjectRef:hud_get_flags() end ---**Player Only** @@ -781,6 +818,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** @@ -793,6 +831,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** @@ -805,6 +844,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 @@ -886,6 +926,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** @@ -895,6 +936,7 @@ 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 @@ -927,6 +969,7 @@ function ObjectRef:set_sun(parameters) end --- ---Returns the current sun settings. ---@return sun_parameters +---@nodiscard function ObjectRef:get_sun() end ---@class moon_parameters @@ -966,6 +1009,7 @@ function ObjectRef:set_moon(parameters) end --- ---Returns the current moon settings. ---@return moon_parameters +---@nodiscard function ObjectRef:get_moon() end ---@class star_parameters @@ -992,6 +1036,7 @@ function ObjectRef:set_stars(parameters) end --- ---Returns the current star settings. ---@return star_parameters +---@nodiscard function ObjectRef:get_stars() end ---@class cloud_parameters @@ -1022,6 +1067,7 @@ function ObjectRef:set_clouds(parameters) end --- ---Returns the current cloud settings. ---@return cloud_parameters +---@nodiscard function ObjectRef:get_clouds() end ---**Player Only** @@ -1036,6 +1082,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** @@ -1058,6 +1105,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** @@ -1074,6 +1122,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** @@ -1104,4 +1153,5 @@ function ObjectRef:set_lighting(definition) end --- ---Returns the current lighting of the player. ---@return light_definition +---@nodiscard function ObjectRef:get_lighting() end From 3dec3cb197138aacd8b36b20d5852a8de3b0180c Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:34:18 +0200 Subject: [PATCH 42/95] Add some `@nodiscard` to `PcgRandom` --- classes/pcgrandom.lua | 3 +++ 1 file changed, 3 insertions(+) diff --git a/classes/pcgrandom.lua b/classes/pcgrandom.lua index 2806f16..d4cc1e3 100644 --- a/classes/pcgrandom.lua +++ b/classes/pcgrandom.lua @@ -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 From 8013b1a6482f7f8c923da63babfc85887a718058 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:34:49 +0200 Subject: [PATCH 43/95] Add some `@nodiscard` to `PseudoRandom` --- classes/pseudorandom.lua | 2 ++ 1 file changed, 2 insertions(+) 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 From 71ea662b90fffc9255e9997c94dc41d602a89105 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:35:20 +0200 Subject: [PATCH 44/95] Add some `@nodiscard` to `Raycast` --- classes/raycast.lua | 2 ++ 1 file changed, 2 insertions(+) diff --git a/classes/raycast.lua b/classes/raycast.lua index e13a162..00743da 100644 --- a/classes/raycast.lua +++ b/classes/raycast.lua @@ -8,6 +8,7 @@ ---@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 @@ -33,4 +34,5 @@ local raycast = {} --- ---Returns the next thing pointed by the ray or nil. ---@return pointed_thing_raycast? +---@nodiscard function raycast:next() end From 9b4a8d09e291ded04a9b3c6a0d7dff7180a3304b Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:35:53 +0200 Subject: [PATCH 45/95] Add some `@nodiscard` to `SecureRandom` --- classes/securerandom.lua | 2 ++ 1 file changed, 2 insertions(+) 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 From f08d8d40e8b0c0c35ff487ffa1f9211b4a1751f0 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:38:50 +0200 Subject: [PATCH 46/95] Add some `@nodiscard` to `VoxelArea` --- classes/voxelarea.lua | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) 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 From 78a8a6f28d825f35952c2dcc510fefddb72d4092 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 01:39:58 +0200 Subject: [PATCH 47/95] Add some `@nodiscard` to `VoxelManip` --- classes/voxelmanip.lua | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/classes/voxelmanip.lua b/classes/voxelmanip.lua index 580d717..5f05360 100644 --- a/classes/voxelmanip.lua +++ b/classes/voxelmanip.lua @@ -40,6 +40,7 @@ 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 From 3292871bf19812c0b02b95cad400a46ff3b80b9e Mon Sep 17 00:00:00 2001 From: AFCMS Date: Tue, 11 Oct 2022 11:02:03 +0200 Subject: [PATCH 48/95] State documentation is official for the minetest namespace --- minetest.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/minetest.lua b/minetest.lua index 2a6c18c..c09d42b 100644 --- a/minetest.lua +++ b/minetest.lua @@ -2,7 +2,7 @@ ---Minetest 7ffc0268 API --- ----[Documentation](https://github.com/minetest/minetest/blob/7ffc0268/doc/lua_api.txt) +---[Official Documentation](https://github.com/minetest/minetest/blob/7ffc0268/doc/lua_api.txt) ---@class minetest minetest = {} From 70d13f2db18e89953764ef84db3d33aa4f064f0d Mon Sep 17 00:00:00 2001 From: AFCMS Date: Wed, 12 Oct 2022 17:26:32 +0200 Subject: [PATCH 49/95] Make noise_params use the right class syntax --- types/noise_params.lua | 33 ++++++++------------------------- 1 file changed, 8 insertions(+), 25 deletions(-) diff --git a/types/noise_params.lua b/types/noise_params.lua index 7abb098..c8c776e 100644 --- a/types/noise_params.lua +++ b/types/noise_params.lua @@ -1,20 +1,14 @@ ---@meta ---@class noise_params -local noise_params = {} - ---After the multiplication by `scale` this is added to the result and is the final step in creating the noise value. --- ---Can be positive or negative. ----@type number -noise_params.offset = nil - +---@field offset number ---Once all octaves have been combined, the result is multiplied by this. --- ---Can be positive or negative. ----@type number -noise_params.scale = nil - +---@field scale number ---For octave1, this is roughly the change of input value needed for a very large variation in the noise value generated by octave1. --- ---It is almost like a `wavelength` for the wavy noise variation. @@ -22,9 +16,7 @@ noise_params.scale = nil ---Each additional octave has a `wavelength` that is smaller than the previous octave, to create finer detail. `spread` will therefore roughly be the typical size of the largest structures in the final noise variation. --- ---`spread` is a vector with values for x, y, z to allow the noise variation to be stretched or compressed in the desired axes. Values are positive numbers. ----@type Vector -noise_params.spread = nil - +---@field spread Vector ---This is a whole number that determines the entire pattern of the noise variation. --- ---Altering it enables different noise patterns to be created. @@ -34,9 +26,7 @@ noise_params.spread = nil ---For this parameter you can randomly choose any whole number. Usually it is preferable for this to be different from other seeds, but sometimes it is useful to be able to create identical noise patterns. --- ---In some noise APIs the world seed is added to the seed specified in noise parameters. This is done to make the resulting noise pattern vary in different worlds, and be 'world-specific'. ----@type integer -noise_params.seed = nil - +---@field seed integer ---The number of simple noise generators that are combined. A whole number, 1 or more. --- ---Each additional octave adds finer detail to the noise but also increases the noise calculation load. @@ -48,9 +38,7 @@ noise_params.seed = nil ---For example: if `spread` is 512 nodes, `lacunarity` is 2.0 and finest detail required is 16 nodes, octaves will be 6 because the 'wavelengths' of the octaves will be 512, 256, 128, 64, 32, 16 nodes. --- ---**Warning:** If the 'wavelength' of any octave falls below 1 an error will occur. ----@type integer -noise_params.octaves = nil - +---@field octaves integer ---Each additional octave has an amplitude that is the amplitude of the previous octave multiplied by `persistence`, to reduce the amplitude of finer details, as is often helpful and natural to do so. --- ---Since this controls the balance of fine detail to large-scale detail `persistence` can be thought of as the 'roughness' of the noise. @@ -60,9 +48,7 @@ noise_params.octaves = nil ---A common medium value is 0.5, such that each octave has half the amplitude of the previous octave. --- ---This may need to be tuned when altering `lacunarity`; when doing so consider that a common medium value is 1 / lacunarity. ----@type number -noise_params.persistence = nil - +---@field persistence number ---Each additional octave has a 'wavelength' that is the 'wavelength' of the previous octave multiplied by 1 / lacunarity, to create finer detail. --- ---'lacunarity' is often 2.0 so 'wavelength' often halves per octave. @@ -70,11 +56,8 @@ noise_params.persistence = nil ---A positive number no smaller than 1.0. --- ---Values below 2.0 create higher quality noise at the expense of requiring more octaves to cover a paticular range of 'wavelengths'. ----@type number -noise_params.lacunarity = nil - +---@field lacunarity number ---Leave this field unset for no special handling. --- ---Currently supported are `defaults`, `eased` and `absvalue` ----@type string -noise_params.flags = nil +---@field flags string From 302243a7a669d80c611d18284309fcfe90007a85 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Wed, 12 Oct 2022 17:54:54 +0200 Subject: [PATCH 50/95] Make PlayerHPChangeReason use right class syntax --- types/player_hp_change_reason.lua | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/types/player_hp_change_reason.lua b/types/player_hp_change_reason.lua index 479c5b3..d0ff89e 100644 --- a/types/player_hp_change_reason.lua +++ b/types/player_hp_change_reason.lua @@ -1,8 +1,6 @@ ---@meta ---@class PlayerHPChangeReason -local player_hp_change = {} - ---Type of the change: ---* `set_hp`: A mod or the engine called `set_hp` without giving a type - use this for custom damage types. ---* `punch`: Was punched. `reason.object` will hold the puncher, or nil if none. @@ -10,21 +8,14 @@ local player_hp_change = {} ---* `node_damage`: `damage_per_second` from a neighbouring node. `reason.node` will hold the node name or nil. ---* `drown` ---* `respawn` ----@type '"set_hp"'|'"punch"'|'"fall"'|'"node_damage"'|'"drown"'|'"respawn"' -player_hp_change.type = nil - +---@field type '"set_hp"'|'"punch"'|'"fall"'|'"node_damage"'|'"drown"'|'"respawn"' ---The hp change origin. ----@type '"mod"'|'"engine"' -player_hp_change.from = nil - +---@field from '"mod"'|'"engine"' ---**Damage type: punch** --- ---The puncher object or `nil` if there is none. ----@type ObjectRef? -player_hp_change.object = nil - +---@field object ObjectRef? ---**Damage type: node_damage** --- ---The name of the damaging node ----@type string? -player_hp_change.node = nil +---@field node string? From a25e703a160366480b57a47e3a3fb92b120c7667 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Wed, 12 Oct 2022 18:01:22 +0200 Subject: [PATCH 51/95] Fix typo --- api/formspec.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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. --- From e41f5436d9e68363a1d0271484a22f90488c14c5 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Wed, 12 Oct 2022 18:01:52 +0200 Subject: [PATCH 52/95] Make SimpleSoundSpecTable use the right class syntax --- types/simple_sound_spec.lua | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/types/simple_sound_spec.lua b/types/simple_sound_spec.lua index b4152d8..2b6a782 100644 --- a/types/simple_sound_spec.lua +++ b/types/simple_sound_spec.lua @@ -24,16 +24,9 @@ ---@alias SimpleSoundSpec SimpleSoundSpecTable|string ---@class SimpleSoundSpecTable -local simple_sound_spec = {} - ---Sound name. ----@type string -simple_sound_spec.name = nil - +---@field name string ---Volume (`1.0` = `100%`) ----@type number -simple_sound_spec.gain = nil - +---@field gain number ---Pitch (`1.0` = `100%`) ----@type number -simple_sound_spec.pitch = nil +---@field pitch number From d962dbe0be7c70ccfa751253572e860329fe486d Mon Sep 17 00:00:00 2001 From: AFCMS Date: Wed, 12 Oct 2022 18:04:15 +0200 Subject: [PATCH 53/95] Make sound parameter table use the right class syntax --- types/sound_parameter_table.lua | 37 ++++++++------------------------- 1 file changed, 9 insertions(+), 28 deletions(-) diff --git a/types/sound_parameter_table.lua b/types/sound_parameter_table.lua index 700c999..a73f1a9 100644 --- a/types/sound_parameter_table.lua +++ b/types/sound_parameter_table.lua @@ -70,31 +70,12 @@ --- ---`exclude_player = name` can be applied to locationless, positional and object-bound sounds to exclude a single player from hearing them. ---@class SoundParameterTable -local sound_parameter_table = {} - ----@type string -sound_parameter_table.to_player = nil - ----@type ObjectRef -sound_parameter_table.object = nil - ----@type number -sound_parameter_table.gain = nil - ----@type number -sound_parameter_table.fade = nil - ----@type number -sound_parameter_table.pitch = nil - ----@type boolean -sound_parameter_table.loop = nil - ----@type Vector -sound_parameter_table.pos = nil - ----@type number -sound_parameter_table.max_hear_distance = nil - ----@type string -sound_parameter_table.exclude_player = nil +---@field to_player string +---@field object ObjectRef +---@field gain number +---@field fade number +---@field pitch number +---@field loop boolean +---@field pos Vector +---@field max_hear_distance number +---@field exclude_player string From 8af46fd3f174154f260822819358199339d20440 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Wed, 12 Oct 2022 18:07:17 +0200 Subject: [PATCH 54/95] Make moon_parameters table use the right class syntax --- classes/objectref.lua | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/classes/objectref.lua b/classes/objectref.lua index f7031a2..dbff4ed 100644 --- a/classes/objectref.lua +++ b/classes/objectref.lua @@ -973,12 +973,8 @@ function ObjectRef:set_sun(parameters) end 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. @@ -986,16 +982,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** --- From f445cbc704ac99e600f4708e9ee43192112aa9a2 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Wed, 12 Oct 2022 19:48:39 +0200 Subject: [PATCH 55/95] WIP Luaentity stuff --- classes/luaentity.lua | 5 +++++ classes/objectref.lua | 4 +--- types/entity_definition.lua | 12 ++++++++++++ types/moveresult.lua | 14 ++++++++++++++ 4 files changed, 32 insertions(+), 3 deletions(-) create mode 100644 types/entity_definition.lua create mode 100644 types/moveresult.lua diff --git a/classes/luaentity.lua b/classes/luaentity.lua index 75e8a0d..b6e85dd 100644 --- a/classes/luaentity.lua +++ b/classes/luaentity.lua @@ -3,3 +3,8 @@ ---@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 diff --git a/classes/objectref.lua b/classes/objectref.lua index dbff4ed..0972419 100644 --- a/classes/objectref.lua +++ b/classes/objectref.lua @@ -441,12 +441,10 @@ function ObjectRef:set_sprite(start_frame, num_frames, framelenght, select_x_by_ ---@nodiscard function ObjectRef:get_entity_name() end ---FIXME - ---**Luaentity Only** --- ---Returns object luaentity. ----@return table +---@return Luaentity ---@nodiscard function ObjectRef:get_luaentity() end diff --git a/types/entity_definition.lua b/types/entity_definition.lua new file mode 100644 index 0000000..ee5e517 --- /dev/null +++ b/types/entity_definition.lua @@ -0,0 +1,12 @@ +---@class entity_definition +---A table of object properties, see the `Object properties` section. +--- +---Object properties being read directly from the entity definition table is deprecated. +--- +---Define object properties in this `initial_properties` table instead. +---@field initial_properties object_properties +---@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 diff --git a/types/moveresult.lua b/types/moveresult.lua new file mode 100644 index 0000000..05a0bae --- /dev/null +++ b/types/moveresult.lua @@ -0,0 +1,14 @@ +---@class moveresult_collision +---@field type '"node"'|'"object"' +---@field axis '"x"'|'"y"'|'"z"' +---@field node_pos Vector +---@field object ObjectRef +---@field old_velocity Vector +---@field new_velocity Vector + +---@class moveresult +---@field touching_ground boolean +---@field collides boolean +---@field standing_on_object boolean +---Does not contain data of unloaded mapblock collisions or when the velocity changes are negligibly small +---@field collisions moveresult_collision[] From 7ffbc201884d47327ca29ce5ab4467030ec685c3 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Wed, 12 Oct 2022 19:59:31 +0200 Subject: [PATCH 56/95] ABM --- api/register/environment.lua | 45 ++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/api/register/environment.lua b/api/register/environment.lua index c736b5e..b6c2fba 100644 --- a/api/register/environment.lua +++ b/api/register/environment.lua @@ -119,3 +119,48 @@ --- ---@param def ore_definition function minetest.register_ore(def) end + +---@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 +---@param def abm_definition +function minetest.register_abm(def) end + +---@type abm_definition[] +minetest.registered_abm = {} From ffa081e8c3e221cdf40a2f2ac0545cb50ce44711 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Wed, 12 Oct 2022 20:04:19 +0200 Subject: [PATCH 57/95] LBM --- api/register/environment.lua | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/api/register/environment.lua b/api/register/environment.lua index b6c2fba..67b632f 100644 --- a/api/register/environment.lua +++ b/api/register/environment.lua @@ -158,9 +158,35 @@ function minetest.register_ore(def) end ---* `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 +---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). +--- +---Definitions with identical labels will be listed as one. +---@field label string +---@field name string +---List of node names to trigger the LBM on. +--- +---Also non-registered nodes will work. +--- +---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) +--- +---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 = {} From 6d15f5dd999ed2bfecf7924f7a8de29c20248a24 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Thu, 13 Oct 2022 00:29:21 +0200 Subject: [PATCH 58/95] Biome --- api/register/environment.lua | 96 ++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/api/register/environment.lua b/api/register/environment.lua index 67b632f..65cd624 100644 --- a/api/register/environment.lua +++ b/api/register/environment.lua @@ -190,3 +190,99 @@ function minetest.register_lbm(def) end ---@type lbm_definition[] minetest.registered_lbm = {} + +---@class biome_definition +---@field name string +---Node dropped onto upper surface after all else is generated +---@field node_dust string +---Node forming surface layer of biome +---@field node_top string +---Thickness of the surface layer +---@field depth_top integer +---Node forming lower layer of biome +---@field node_filler string +---Thickness of the lower layer +---@field depth_filler integer +---Node that replaces all stone nodes between roughly `y_min` and `y_max` +---@field node_stone string +---Node forming a surface layer in seawater +---@field node_water_top string +---Thickness of the seawater surface layer +---@field depth_water_top integer +---Node that replaces all seawater nodes not in the surface layer +---@field node_water string +---Node that replaces river water in mapgens that use it +---@field node_river_water string +---Node placed under river water +---@field node_riverbed string +---Thickness of layer under river water +---@field depth_riverbed integer +---Nodes placed inside 50% of the medium size caves. +--- +---Multiple nodes can be specified, each cave will use a randomly chosen node from the list. +--- +---If this field is left out or `nil`, cave liquids fall back to classic behaviour of lava and water distributed using 3D noise. +--- +---For no cave liquid, specify `"air"`. +---@field node_cave_liquid string|string[] +---Node used for primary dungeon structure. +--- +---If absent, dungeon nodes fall back to the `mapgen_cobble` mapgen alias, if that is also absent, dungeon nodes fall back to the biome `node_stone`. +---@field node_dungeon string +---Node used for randomly-distributed alternative structure nodes. +--- +---If alternative structure nodes are not wanted leave this absent for performance reasons. +---@field node_dungeon_alt string +---Node used for dungeon stairs. +--- +---If absent, stairs fall back to `node_dungeon`. +---@field node_dungeon_stair string +---Upper limit for biome. +--- +---Alternatively you can use the `max_pos` limit. +---@field y_max integer +---Lower limit for biome. +--- +---Alternatively you can use the `min_pos` limit. +---@field y_min integer +---Pos limit for biome, an alternative to using `y_min` and `y_max`. +--- +---Biome is limited to a cuboid defined by `max_pos` and `min_pos`. +---@field max_pos Vector +---Pos limit for biome, an alternative to using `y_min` and `y_max`. +--- +---Biome is limited to a cuboid defined by `max_pos` and `min_pos`. +---@field min_pos Vector +---Vertical distance in nodes above 'y_max' over which the biome will blend with the biome above. +--- +---Set to 0 for no vertical blend. Defaults to 0. +---@field vertical_blend integer +---Characteristic temperature for the biome. +--- +---`heat_point` and `humidity_point` create `biome points` on a voronoi diagram with heat and humidity as axes. +--- +---The resulting voronoi cells determine the distribution of the biomes. +--- +---Heat and humidity have average values of 50, vary mostly between 0 and 100 but can exceed these values. +---@field heat_point integer +---Characteristic humidity for the biome. +--- +---`heat_point` and `humidity_point` create `biome points` on a voronoi diagram with heat and humidity as axes. +--- +---The resulting voronoi cells determine the distribution of the biomes. +--- +---Heat and humidity have average values of 50, vary mostly between 0 and 100 but can exceed these values. +---@field humidity_point integer + +---Returns an integer object handle uniquely identifying the registered biome on success. +--- +---To get the biome ID, use `minetest.get_biome_id`. +--- +---The maximum number of biomes that can be used is 65535. +--- +---However, using an excessive number of biomes will slow down map generation. +--- +---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 From 25ef86bd703dad8cb59e9971629c5d9b588eae83 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Mon, 17 Oct 2022 00:49:41 +0200 Subject: [PATCH 59/95] Fix `ItemStack:take_item()` optional param --- classes/itemstack.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/classes/itemstack.lua b/classes/itemstack.lua index e7762d7..9fd1873 100644 --- a/classes/itemstack.lua +++ b/classes/itemstack.lua @@ -148,7 +148,7 @@ 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 From e2a58ae90ec35188f9c6df020aab87deee96437b Mon Sep 17 00:00:00 2001 From: AFCMS Date: Mon, 17 Oct 2022 00:50:10 +0200 Subject: [PATCH 60/95] `ModChannel:is_writable()` -> `ModChannel:is_writeable()` --- classes/modchannel.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/classes/modchannel.lua b/classes/modchannel.lua index 73c770e..27f4e6b 100644 --- a/classes/modchannel.lua +++ b/classes/modchannel.lua @@ -15,7 +15,7 @@ function ModChannel:leave() end ---Returns true if channel is writeable and mod can send over it. ---@return boolean ---@nodiscard -function ModChannel:is_writable() end +function ModChannel:is_writeable() end ---If mod channel is not writeable or invalid, message will be dropped. --- From 52bfbcbdb2a5c044df9b92ba745f93793adbcd8a Mon Sep 17 00:00:00 2001 From: AFCMS Date: Mon, 17 Oct 2022 00:50:56 +0200 Subject: [PATCH 61/95] Fix `ObjectRef:move_to()` optional param --- classes/objectref.lua | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/classes/objectref.lua b/classes/objectref.lua index 0972419..af78334 100644 --- a/classes/objectref.lua +++ b/classes/objectref.lua @@ -41,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. @@ -61,6 +61,7 @@ function ObjectRef:right_click(clicker) end function ObjectRef:get_hp() end --FIXME: reason table + ---Set number of health points of the object. ---@param hp integer ---@param reason table From 826be88061215753f471fdab1bcc5cf02f7e978e Mon Sep 17 00:00:00 2001 From: AFCMS Date: Mon, 17 Oct 2022 00:51:19 +0200 Subject: [PATCH 62/95] Fix `Raycast()` optional params --- classes/raycast.lua | 4 +- lua_api.txt | 8056 +++++++++++++++++++++---------------------- 2 files changed, 3900 insertions(+), 4160 deletions(-) diff --git a/classes/raycast.lua b/classes/raycast.lua index 00743da..8b1a329 100644 --- a/classes/raycast.lua +++ b/classes/raycast.lua @@ -5,8 +5,8 @@ ---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 diff --git a/lua_api.txt b/lua_api.txt index b2db971..7fd301e 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) +- `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) - - - -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,19 +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. +- `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. @@ -276,8 +260,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: @@ -307,11 +290,7 @@ Any mod can redefine `experimental:tnt` by using the name when registering it. That mod is required to have `experimental` as a dependency. - - - -Aliases -======= +# Aliases Aliases of itemnames can be added by using `minetest.register_alias(alias, original_name)` or @@ -334,8 +313,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 +324,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,45 +334,45 @@ 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. -* 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 +- 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 ### Setting the node used in Mapgen Singlenode @@ -403,11 +381,7 @@ example: minetest.register_alias("mapgen_singlenode", "default:stone") - - - -Textures -======== +# Textures Mods should generally prefix their textures with `modname_`, e.g. given the mod name `foomod`, a texture could be called: @@ -417,12 +391,10 @@ 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` - -Texture modifiers ------------------ +## Texture modifiers There are various texture modifiers that can be used to let the client generate textures on-the-fly. @@ -465,16 +437,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 +458,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 +525,7 @@ Example: #### `[transform` -* ``: transformation(s) to apply +- ``: transformation(s) to apply Rotates and/or flips the image. @@ -597,8 +569,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 +593,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 +626,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 +673,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 +700,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 +778,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 +820,7 @@ Example (colored grass block): palette = "default_foilage.png", }) - - - -Sounds -====== +# Sounds Only Ogg Vorbis files are supported. @@ -873,11 +839,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 +895,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 +905,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]. @@ -992,11 +955,7 @@ If you want to check the drawtype of a node, you could do: end local drawtype = get_nodedef_field(nodename, "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 +976,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 +984,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 +1277,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 +1295,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,26 +1317,21 @@ 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. @@ -1417,19 +1362,17 @@ 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 +- Other: 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 +1381,98 @@ 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). ### `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` +- `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. +- `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 If translation is chosen, texture is repeated horizontally to fill the whole element. @@ -1537,47 +1480,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 +1546,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 +1579,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 +1591,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 +1615,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 +1661,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 +1690,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 +1708,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 +1734,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 +1742,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 +1844,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,19 +1857,18 @@ 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 @@ -1989,9 +1893,9 @@ 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. @@ -2029,8 +1933,7 @@ 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, @@ -2043,8 +1946,8 @@ Example definition of the capabilities of an item 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 +1968,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 +2005,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 +2034,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 +2074,7 @@ Example: } }) -Item Metadata -------------- +## Item Metadata Item stacks can store metadata too. See [`ItemStackMetaRef`]. @@ -2189,20 +2082,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 +2119,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,8 +2141,7 @@ 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 ``. @@ -2272,8 +2161,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 +2185,628 @@ 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 + +## 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 +- Allows to create a 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[,;,;]` -* Show an image +- Show an 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`. ### `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. +- 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) -* Available since formspec version 2 +- Available since formspec version 2 ### `pwdfield[,;,;;