From d197ff0f9dc55c165cfd7e84a41e2c0891c85111 Mon Sep 17 00:00:00 2001 From: AFCMS Date: Wed, 26 Apr 2023 20:09:08 +0200 Subject: [PATCH] Use Lua code blocks in `lua_api.md` --- doc/client_lua_api.md | 460 ++--- doc/lua_api.md | 4132 +++++++++++++++++++++-------------------- doc/menu_lua_api.md | 224 +-- 3 files changed, 2504 insertions(+), 2312 deletions(-) diff --git a/doc/client_lua_api.md b/doc/client_lua_api.md index 57049893d..70fae582d 100644 --- a/doc/client_lua_api.md +++ b/doc/client_lua_api.md @@ -170,26 +170,28 @@ from the available ones of the following files: Examples of sound parameter tables: - -- Play locationless - { - gain = 1.0, -- default - } - -- Play locationless, looped - { - gain = 1.0, -- default - loop = true, - } - -- Play in a location - { - pos = {x = 1, y = 2, z = 3}, - gain = 1.0, -- default - } - -- Play connected to an object, looped - { - object = , - gain = 1.0, -- default - loop = true, - } +```lua +-- Play locationless +{ + gain = 1.0, -- default +} +-- Play locationless, looped +{ + gain = 1.0, -- default + loop = true, +} +-- Play in a location +{ + pos = {x = 1, y = 2, z = 3}, + gain = 1.0, -- default +} +-- Play connected to an object, looped +{ + object = , + gain = 1.0, -- default + loop = true, +} +``` Looped sounds must either be connected to an object or played locationless. @@ -205,7 +207,9 @@ Representations of simple things ### Position/vector - {x=num, y=num, z=num} +```lua +{x=num, y=num, z=num} +``` For helper functions see "Vector helpers". @@ -231,19 +235,27 @@ is present, mapped to a boolean of any value, the specified flag is unset. E.g. A flag field of value - {place_center_x = true, place_center_y=false, place_center_z=true} +```lua +{place_center_x = true, place_center_y=false, place_center_z=true} +``` is equivalent to - {place_center_x = true, noplace_center_y=true, place_center_z=true} +```lua +{place_center_x = true, noplace_center_y=true, place_center_z=true} +``` which is equivalent to - "place_center_x, noplace_center_y, place_center_z" +```lua +"place_center_x, noplace_center_y, place_center_z" +``` or even - "place_center_x, place_center_z" +```lua +"place_center_x, place_center_z" +``` since, by default, no schematic attributes are set. @@ -996,14 +1008,14 @@ Please do not try to access the reference until the camera is initialized, other * `get_fov()` * Returns a table with X, Y, maximum and actual FOV in degrees: -```lua - { - x = number, - y = number, - max = number, - actual = number - } -``` + ```lua + { + x = number, + y = number, + max = number, + actual = number + } + ``` * `get_pos()` * Returns position of camera with view bobbing @@ -1053,16 +1065,16 @@ Methods: * `get_physics_override()` * returns: -```lua - { - speed = float, - jump = float, - gravity = float, - sneak = boolean, - sneak_glitch = boolean, - new_move = boolean, - } -``` + ```lua + { + speed = float, + jump = float, + gravity = float, + sneak = boolean, + sneak_glitch = boolean, + new_move = boolean, + } + ``` * `get_override_pos()` * returns override position @@ -1075,38 +1087,38 @@ Methods: * `get_movement_acceleration()` * returns acceleration of the player in different environments: -```lua - { - fast = float, - air = float, - default = float, - } -``` + ```lua + { + fast = float, + air = float, + default = float, + } + ``` * `get_movement_speed()` * returns player's speed in different environments: -```lua - { - walk = float, - jump = float, - crouch = float, - fast = float, - climb = float, - } -``` + ```lua + { + walk = float, + jump = float, + crouch = float, + fast = float, + climb = float, + } + ``` * `get_movement()` * returns player's movement in different environments: -```lua - { - liquid_fluidity = float, - liquid_sink = float, - liquid_fluidity_smooth = float, - gravity = float, - } -``` + ```lua + { + liquid_fluidity = float, + liquid_sink = float, + liquid_fluidity_smooth = float, + gravity = float, + } + ``` * `get_last_look_horizontal()`: * returns last look horizontal angle @@ -1115,20 +1127,20 @@ Methods: * `get_control()`: * returns pressed player controls -```lua - { - up = boolean, - down = boolean, - left = boolean, - right = boolean, - jump = boolean, - aux1 = boolean, - sneak = boolean, - zoom = boolean, - dig = boolean, - place = boolean, - } -``` + ```lua + { + up = boolean, + down = boolean, + left = boolean, + right = boolean, + jump = boolean, + aux1 = boolean, + sneak = boolean, + zoom = boolean, + dig = boolean, + place = boolean, + } + ``` * `get_armor_groups()` * returns a table with the armor group ratings @@ -1176,10 +1188,12 @@ Can be obtained via `minetest.get_meta(pos)`. A raycast on the map. It works with selection boxes. Can be used as an iterator in a for loop as: - local ray = Raycast(...) - for pointed_thing in ray do - ... - end +```lua +local ray = Raycast(...) +for pointed_thing in ray do + ... +end +``` The map is loaded as the ray advances. If the map is modified after the `Raycast` is created, the changes may or may not have an effect on the object. @@ -1207,97 +1221,100 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or #### Node Definition ```lua - { - has_on_construct = bool, -- Whether the node has the on_construct callback defined - has_on_destruct = bool, -- Whether the node has the on_destruct callback defined - has_after_destruct = bool, -- Whether the node has the after_destruct callback defined - name = string, -- The name of the node e.g. "air", "default:dirt" - groups = table, -- The groups of the node - paramtype = string, -- Paramtype of the node - paramtype2 = string, -- ParamType2 of the node - drawtype = string, -- Drawtype of the node - mesh = , -- Mesh name if existent - minimap_color = , -- Color of node on minimap *May not exist* - visual_scale = number, -- Visual scale of node - alpha = number, -- Alpha of the node. Only used for liquids - color = , -- Color of node *May not exist* - palette_name = , -- Filename of palette *May not exist* - palette = <{ -- List of colors - Color, - Color - }>, - waving = number, -- 0 of not waving, 1 if waving - connect_sides = number, -- Used for connected nodes - connects_to = { -- List of nodes to connect to - "node1", - "node2" - }, - post_effect_color = Color, -- Color overlayed on the screen when the player is in the node - leveled = number, -- Max level for node - sunlight_propogates = bool, -- Whether light passes through the block - light_source = number, -- Light emitted by the block - is_ground_content = bool, -- Whether caves should cut through the node - walkable = bool, -- Whether the player collides with the node - pointable = bool, -- Whether the player can select the node - diggable = bool, -- Whether the player can dig the node - climbable = bool, -- Whether the player can climb up the node - buildable_to = bool, -- Whether the player can replace the node by placing a node on it - rightclickable = bool, -- Whether the player can place nodes pointing at this node - damage_per_second = number, -- HP of damage per second when the player is in the node - liquid_type = , -- A string containing "none", "flowing", or "source" *May not exist* - liquid_alternative_flowing = , -- Alternative node for liquid *May not exist* - liquid_alternative_source = , -- Alternative node for liquid *May not exist* - liquid_viscosity = , -- How slow the liquid flows *May not exist* - liquid_renewable = , -- Whether the liquid makes an infinite source *May not exist* - liquid_range = , -- How far the liquid flows *May not exist* - drowning = bool, -- Whether the player will drown in the node - floodable = bool, -- Whether nodes will be replaced by liquids (flooded) - node_box = table, -- Nodebox to draw the node with - collision_box = table, -- Nodebox to set the collision area - selection_box = table, -- Nodebox to set the area selected by the player - sounds = { -- Table of sounds that the block makes - sound_footstep = SimpleSoundSpec, - sound_dig = SimpleSoundSpec, - sound_dug = SimpleSoundSpec - }, - legacy_facedir_simple = bool, -- Whether to use old facedir - legacy_wallmounted = bool -- Whether to use old wallmounted - move_resistance = , -- How slow players can move through the node *May not exist* - } +{ + has_on_construct = bool, -- Whether the node has the on_construct callback defined + has_on_destruct = bool, -- Whether the node has the on_destruct callback defined + has_after_destruct = bool, -- Whether the node has the after_destruct callback defined + name = string, -- The name of the node e.g. "air", "default:dirt" + groups = table, -- The groups of the node + paramtype = string, -- Paramtype of the node + paramtype2 = string, -- ParamType2 of the node + drawtype = string, -- Drawtype of the node + mesh = , -- Mesh name if existent + minimap_color = , -- Color of node on minimap *May not exist* + visual_scale = number, -- Visual scale of node + alpha = number, -- Alpha of the node. Only used for liquids + color = , -- Color of node *May not exist* + palette_name = , -- Filename of palette *May not exist* + palette = <{ -- List of colors + Color, + Color + }>, + waving = number, -- 0 of not waving, 1 if waving + connect_sides = number, -- Used for connected nodes + connects_to = { -- List of nodes to connect to + "node1", + "node2" + }, + post_effect_color = Color, -- Color overlayed on the screen when the player is in the node + leveled = number, -- Max level for node + sunlight_propogates = bool, -- Whether light passes through the block + light_source = number, -- Light emitted by the block + is_ground_content = bool, -- Whether caves should cut through the node + walkable = bool, -- Whether the player collides with the node + pointable = bool, -- Whether the player can select the node + diggable = bool, -- Whether the player can dig the node + climbable = bool, -- Whether the player can climb up the node + buildable_to = bool, -- Whether the player can replace the node by placing a node on it + rightclickable = bool, -- Whether the player can place nodes pointing at this node + damage_per_second = number, -- HP of damage per second when the player is in the node + liquid_type = , -- A string containing "none", "flowing", or "source" *May not exist* + liquid_alternative_flowing = , -- Alternative node for liquid *May not exist* + liquid_alternative_source = , -- Alternative node for liquid *May not exist* + liquid_viscosity = , -- How slow the liquid flows *May not exist* + liquid_renewable = , -- Whether the liquid makes an infinite source *May not exist* + liquid_range = , -- How far the liquid flows *May not exist* + drowning = bool, -- Whether the player will drown in the node + floodable = bool, -- Whether nodes will be replaced by liquids (flooded) + node_box = table, -- Nodebox to draw the node with + collision_box = table, -- Nodebox to set the collision area + selection_box = table, -- Nodebox to set the area selected by the player + sounds = { -- Table of sounds that the block makes + sound_footstep = SimpleSoundSpec, + sound_dig = SimpleSoundSpec, + sound_dug = SimpleSoundSpec + }, + legacy_facedir_simple = bool, -- Whether to use old facedir + legacy_wallmounted = bool -- Whether to use old wallmounted + move_resistance = , -- How slow players can move through the node *May not exist* +} ``` #### Item Definition ```lua - { - name = string, -- Name of the item e.g. "default:stone" - description = string, -- Description of the item e.g. "Stone" - type = string, -- Item type: "none", "node", "craftitem", "tool" - inventory_image = string, -- Image in the inventory - wield_image = string, -- Image in wieldmesh - palette_image = string, -- Image for palette - color = Color, -- Color for item - wield_scale = Vector, -- Wieldmesh scale - stack_max = number, -- Number of items stackable together - usable = bool, -- Has on_use callback defined - liquids_pointable = bool, -- Whether you can point at liquids with the item - tool_capabilities = , -- If the item is a tool, tool capabilities of the item - groups = table, -- Groups of the item - sound_place = SimpleSoundSpec, -- Sound played when placed - sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed - node_placement_prediction = string -- Node placed in client until server catches up - } +{ + name = string, -- Name of the item e.g. "default:stone" + description = string, -- Description of the item e.g. "Stone" + type = string, -- Item type: "none", "node", "craftitem", "tool" + inventory_image = string, -- Image in the inventory + wield_image = string, -- Image in wieldmesh + palette_image = string, -- Image for palette + color = Color, -- Color for item + wield_scale = Vector, -- Wieldmesh scale + stack_max = number, -- Number of items stackable together + usable = bool, -- Has on_use callback defined + liquids_pointable = bool, -- Whether you can point at liquids with the item + tool_capabilities =
, -- If the item is a tool, tool capabilities of the item + groups = table, -- Groups of the item + sound_place = SimpleSoundSpec, -- Sound played when placed + sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed + node_placement_prediction = string -- Node placed in client until server catches up +} ``` ----------------- ### Chat command definition (`register_chatcommand`) - { - params = " ", -- Short parameter description - description = "Remove privilege from player", -- Full description - func = function(param), -- Called when command is run. - -- Returns boolean success and text output. - } +```lua +{ + params = " ", -- Short parameter description + description = "Remove privilege from player", -- Full description + func = function(param), -- Called when command is run. + -- Returns boolean success and text output. +} +``` + ### Server info ```lua { @@ -1309,29 +1326,30 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or ``` ### HUD Definition (`hud_add`, `hud_get`) + ```lua - { - hud_elem_type = "image", -- see HUD element types, default "text" - -- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory" - position = {x=0.5, y=0.5}, - -- ^ Left corner position of element, default `{x=0,y=0}`. - name = "", -- default "" - scale = {x=2, y=2}, -- default {x=0,y=0} - text = "", -- default "" - number = 2, -- default 0 - item = 3, -- default 0 - -- ^ Selected item in inventory. 0 for no item selected. - direction = 0, -- default 0 - -- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top - alignment = {x=0, y=0}, -- default {x=0, y=0} - -- ^ See "HUD Element Types" - offset = {x=0, y=0}, -- default {x=0, y=0} - -- ^ See "HUD Element Types" - size = { x=100, y=100 }, -- default {x=0, y=0} - -- ^ Size of element in pixels - style = 0, - -- ^ For "text" elements sets font style: bitfield with 1 = bold, 2 = italic, 4 = monospace - } +{ + hud_elem_type = "image", -- see HUD element types, default "text" +-- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory" + position = {x=0.5, y=0.5}, +-- ^ Left corner position of element, default `{x=0,y=0}`. + name = "", -- default "" + scale = {x=2, y=2}, -- default {x=0,y=0} + text = "", -- default "" + number = 2, -- default 0 + item = 3, -- default 0 +-- ^ Selected item in inventory. 0 for no item selected. + direction = 0, -- default 0 +-- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top + alignment = {x=0, y=0}, -- default {x=0, y=0} +-- ^ See "HUD Element Types" + offset = {x=0, y=0}, -- default {x=0, y=0} +-- ^ See "HUD Element Types" + size = { x=100, y=100 }, -- default {x=0, y=0} +-- ^ Size of element in pixels + style = 0, +-- ^ For "text" elements sets font style: bitfield with 1 = bold, 2 = italic, 4 = monospace +} ``` Escape sequences @@ -1478,55 +1496,59 @@ Same as `image`, but does not accept a `position`; the position is instead deter ### Particle definition (`add_particle`) - { - pos = {x=0, y=0, z=0}, - velocity = {x=0, y=0, z=0}, - acceleration = {x=0, y=0, z=0}, +```lua +{ + pos = {x=0, y=0, z=0}, + velocity = {x=0, y=0, z=0}, + acceleration = {x=0, y=0, z=0}, -- ^ Spawn particle at pos with velocity and acceleration - expirationtime = 1, + expirationtime = 1, -- ^ Disappears after expirationtime seconds - size = 1, - collisiondetection = false, + size = 1, + collisiondetection = false, -- ^ collisiondetection: if true collides with physical objects - collision_removal = false, + collision_removal = false, -- ^ collision_removal: if true then particle is removed when it collides, -- ^ requires collisiondetection = true to have any effect - vertical = false, + vertical = false, -- ^ vertical: if true faces player using y axis only - texture = "image.png", + texture = "image.png", -- ^ Uses texture (string) - animation = {Tile Animation definition}, + animation = {Tile Animation definition}, -- ^ optional, specifies how to animate the particle texture - glow = 0 + glow = 0 -- ^ optional, specify particle self-luminescence in darkness - } +} +``` ### `ParticleSpawner` definition (`add_particlespawner`) - { - amount = 1, - time = 1, +```lua +{ + amount = 1, + time = 1, -- ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base - minpos = {x=0, y=0, z=0}, - maxpos = {x=0, y=0, z=0}, - minvel = {x=0, y=0, z=0}, - maxvel = {x=0, y=0, z=0}, - minacc = {x=0, y=0, z=0}, - maxacc = {x=0, y=0, z=0}, - minexptime = 1, - maxexptime = 1, - minsize = 1, - maxsize = 1, + minpos = {x=0, y=0, z=0}, + maxpos = {x=0, y=0, z=0}, + minvel = {x=0, y=0, z=0}, + maxvel = {x=0, y=0, z=0}, + minacc = {x=0, y=0, z=0}, + maxacc = {x=0, y=0, z=0}, + minexptime = 1, + maxexptime = 1, + minsize = 1, + maxsize = 1, -- ^ The particle's properties are random values in between the bounds: -- ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration), -- ^ minsize/maxsize, minexptime/maxexptime (expirationtime) - collisiondetection = false, + collisiondetection = false, -- ^ collisiondetection: if true uses collision detection - collision_removal = false, + collision_removal = false, -- ^ collision_removal: if true then particle is removed when it collides, -- ^ requires collisiondetection = true to have any effect - vertical = false, + vertical = false, -- ^ vertical: if true faces player using y axis only - texture = "image.png", + texture = "image.png", -- ^ Uses texture (string) - } +} +``` \ No newline at end of file diff --git a/doc/lua_api.md b/doc/lua_api.md index 0ca836ba9..8a6e4ef15 100644 --- a/doc/lua_api.md +++ b/doc/lua_api.md @@ -794,32 +794,36 @@ To transfer the color to a special drop, you need a drop table. Example: - minetest.register_node("mod:stone", { - description = "Stone", - tiles = {"default_stone.png"}, - paramtype2 = "color", - palette = "palette.png", - drop = { - items = { - -- assume that mod:cobblestone also has the same palette - {items = {"mod:cobblestone"}, inherit_color = true }, - } +```lua +minetest.register_node("mod:stone", { + description = "Stone", + tiles = {"default_stone.png"}, + paramtype2 = "color", + palette = "palette.png", + drop = { + items = { + -- assume that mod:cobblestone also has the same palette + {items = {"mod:cobblestone"}, inherit_color = true }, } - }) + } +}) +``` ### Colored items in craft recipes Craft recipes only support item strings, but fortunately item strings can also contain metadata. Example craft recipe registration: - minetest.register_craft({ - output = minetest.itemstring_with_palette("wool:block", 3), - type = "shapeless", - recipe = { - "wool:block", - "dye:red", - }, - }) +```lua +minetest.register_craft({ + output = minetest.itemstring_with_palette("wool:block", 3), + type = "shapeless", + recipe = { + "wool:block", + "dye:red", + }, +}) +``` To set the `color` field, you can use `minetest.itemstring_with_color`. @@ -852,23 +856,24 @@ To skip one face, set that overlay tile to an empty string. Example (colored grass block): - minetest.register_node("default:dirt_with_grass", { - description = "Dirt with Grass", - -- Regular tiles, as usual - -- The dirt tile disables palette coloring - tiles = {{name = "default_grass.png"}, - {name = "default_dirt.png", color = "white"}}, - -- Overlay tiles: define them in the same style - -- The top and bottom tile does not have overlay - overlay_tiles = {"", "", - {name = "default_grass_side.png"}}, - -- Global color, used in inventory - color = "green", - -- Palette in the world - paramtype2 = "color", - palette = "default_foilage.png", - }) - +```lua +minetest.register_node("default:dirt_with_grass", { + description = "Dirt with Grass", + -- Regular tiles, as usual + -- The dirt tile disables palette coloring + tiles = {{name = "default_grass.png"}, + {name = "default_dirt.png", color = "white"}}, + -- Overlay tiles: define them in the same style + -- The top and bottom tile does not have overlay + overlay_tiles = {"", "", + {name = "default_grass_side.png"}}, + -- Global color, used in inventory + color = "green", + -- Palette in the world + paramtype2 = "color", + palette = "default_foilage.png", +}) +``` @@ -900,44 +905,46 @@ from the available ones of the following files: Examples of sound parameter tables: - -- Play locationless on all clients - { - gain = 1.0, -- default - fade = 0.0, -- default, change to a value > 0 to fade the sound in - pitch = 1.0, -- default - } - -- Play locationless to one player - { - to_player = name, - gain = 1.0, -- default - fade = 0.0, -- default, change to a value > 0 to fade the sound in - pitch = 1.0, -- default - } - -- Play locationless to one player, looped - { - to_player = name, - gain = 1.0, -- default - loop = true, - } - -- Play at a location - { - pos = {x = 1, y = 2, z = 3}, - gain = 1.0, -- default - max_hear_distance = 32, -- default, uses a Euclidean metric - } - -- Play connected to an object, looped - { - object = , - gain = 1.0, -- default - max_hear_distance = 32, -- default, uses a Euclidean metric - loop = true, - } - -- Play at a location, heard by anyone *but* the given player - { - pos = {x = 32, y = 0, z = 100}, - max_hear_distance = 40, - exclude_player = name, - } +```lua +-- Play locationless on all clients +{ + gain = 1.0, -- default + fade = 0.0, -- default, change to a value > 0 to fade the sound in + pitch = 1.0, -- default +} +-- Play locationless to one player +{ + to_player = name, + gain = 1.0, -- default + fade = 0.0, -- default, change to a value > 0 to fade the sound in + pitch = 1.0, -- default +} +-- Play locationless to one player, looped +{ + to_player = name, + gain = 1.0, -- default + loop = true, +} +-- Play at a location +{ + pos = {x = 1, y = 2, z = 3}, + gain = 1.0, -- default + max_hear_distance = 32, -- default, uses a Euclidean metric +} +-- Play connected to an object, looped +{ + object = , + gain = 1.0, -- default + max_hear_distance = 32, -- default, uses a Euclidean metric + loop = true, +} +-- Play at a location, heard by anyone *but* the given player +{ + pos = {x = 32, y = 0, z = 100}, + max_hear_distance = 40, + exclude_player = name, +} +``` Looped sounds must either be connected to an object or played locationless to one player using `to_player = name`. @@ -1003,9 +1010,10 @@ All nodes registered with `minetest.register_node` get added to the table If you want to check the drawtype of a node, you could do it like this: - local def = minetest.registered_nodes[nodename] - local drawtype = def and def.drawtype - +```lua +local def = minetest.registered_nodes[nodename] +local drawtype = def and def.drawtype +``` @@ -1018,14 +1026,18 @@ are quite static. The definition of a node is stored and can be accessed by using - minetest.registered_nodes[node.name] +```lua +minetest.registered_nodes[node.name] +``` See [Registered definitions]. Nodes are passed by value between Lua and the engine. They are represented by a table: - {name="name", param1=num, param2=num} +```lua +{name="name", param1=num, param2=num} +``` `param1` and `param2` are 8-bit integers ranging from 0 to 255. The engine uses them for certain automated functions. If you don't use these functions, you can @@ -1301,63 +1313,69 @@ Node selection boxes are defined using "node boxes". A nodebox is defined as any of: - { - -- A normal cube; the default in most things - type = "regular" - } - { - -- A fixed box (or boxes) (facedir param2 is used, if applicable) - type = "fixed", - fixed = box OR {box1, box2, ...} - } - { - -- A variable height box (or boxes) with the top face position defined - -- by the node parameter 'leveled = ', or if 'paramtype2 == "leveled"' - -- by param2. - -- Other faces are defined by 'fixed = {}' as with 'type = "fixed"'. - type = "leveled", - fixed = box OR {box1, box2, ...} - } - { - -- A box like the selection box for torches - -- (wallmounted param2 is used, if applicable) - type = "wallmounted", - wall_top = box, - wall_bottom = box, - wall_side = box - } - { - -- A node that has optional boxes depending on neighboring nodes' - -- presence and type. See also `connects_to`. - type = "connected", - fixed = box OR {box1, box2, ...} - connect_top = box OR {box1, box2, ...} - connect_bottom = box OR {box1, box2, ...} - connect_front = box OR {box1, box2, ...} - connect_left = box OR {box1, box2, ...} - connect_back = box OR {box1, box2, ...} - connect_right = box OR {box1, box2, ...} - -- The following `disconnected_*` boxes are the opposites of the - -- `connect_*` ones above, i.e. when a node has no suitable neighbor - -- on the respective side, the corresponding disconnected box is drawn. - disconnected_top = box OR {box1, box2, ...} - disconnected_bottom = box OR {box1, box2, ...} - disconnected_front = box OR {box1, box2, ...} - disconnected_left = box OR {box1, box2, ...} - disconnected_back = box OR {box1, box2, ...} - disconnected_right = box OR {box1, box2, ...} - disconnected = box OR {box1, box2, ...} -- when there is *no* neighbor - disconnected_sides = box OR {box1, box2, ...} -- when there are *no* - -- neighbors to the sides - } +```lua +{ + -- A normal cube; the default in most things + type = "regular" +} +{ + -- A fixed box (or boxes) (facedir param2 is used, if applicable) + type = "fixed", + fixed = box OR {box1, box2, ...} +} +{ + -- A variable height box (or boxes) with the top face position defined + -- by the node parameter 'leveled = ', or if 'paramtype2 == "leveled"' + -- by param2. + -- Other faces are defined by 'fixed = {}' as with 'type = "fixed"'. + type = "leveled", + fixed = box OR {box1, box2, ...} +} +{ + -- A box like the selection box for torches + -- (wallmounted param2 is used, if applicable) + type = "wallmounted", + wall_top = box, + wall_bottom = box, + wall_side = box +} +{ + -- A node that has optional boxes depending on neighboring nodes' + -- presence and type. See also `connects_to`. + type = "connected", + fixed = box OR {box1, box2, ...} + connect_top = box OR {box1, box2, ...} + connect_bottom = box OR {box1, box2, ...} + connect_front = box OR {box1, box2, ...} + connect_left = box OR {box1, box2, ...} + connect_back = box OR {box1, box2, ...} + connect_right = box OR {box1, box2, ...} + -- The following `disconnected_*` boxes are the opposites of the + -- `connect_*` ones above, i.e. when a node has no suitable neighbor + -- on the respective side, the corresponding disconnected box is drawn. + disconnected_top = box OR {box1, box2, ...} + disconnected_bottom = box OR {box1, box2, ...} + disconnected_front = box OR {box1, box2, ...} + disconnected_left = box OR {box1, box2, ...} + disconnected_back = box OR {box1, box2, ...} + disconnected_right = box OR {box1, box2, ...} + disconnected = box OR {box1, box2, ...} -- when there is *no* neighbor + disconnected_sides = box OR {box1, box2, ...} -- when there are *no* + -- neighbors to the sides +} +``` A `box` is defined as: - {x1, y1, z1, x2, y2, z2} +```lua +{x1, y1, z1, x2, y2, z2} +``` A box of a regular node would look like: - {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}, +```lua +{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5}, +``` 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 @@ -1589,7 +1607,9 @@ Representations of simple things Vector (ie. a position) ----------------------- - vector.new(x, y, z) +```lua +vector.new(x, y, z) +``` See [Spatial Vectors] for details. @@ -1637,19 +1657,27 @@ is present, mapped to a boolean of any value, the specified flag is unset. E.g. A flag field of value - {place_center_x = true, place_center_y=false, place_center_z=true} +```lua +{place_center_x = true, place_center_y=false, place_center_z=true} +``` is equivalent to - {place_center_x = true, noplace_center_y=true, place_center_z=true} +```lua +{place_center_x = true, noplace_center_y=true, place_center_z=true} +``` which is equivalent to - "place_center_x, noplace_center_y, place_center_z" +```lua +"place_center_x, noplace_center_y, place_center_z" +``` or even - "place_center_x, place_center_z" +```lua +"place_center_x, place_center_z" +``` since, by default, no schematic attributes are set. @@ -1760,15 +1788,21 @@ Examples: 5 dirt nodes: - {name="default:dirt", count=5, wear=0, metadata=""} +```lua +{name="default:dirt", count=5, wear=0, metadata=""} +``` A wooden pick about 1/3 worn out: - {name="default:pick_wood", count=1, wear=21323, metadata=""} +```lua +{name="default:pick_wood", count=1, wear=21323, metadata=""} +``` An apple: - {name="default:apple", count=1, wear=0, metadata=""} +```lua +{name="default:apple", count=1, wear=0, metadata=""} +``` ### `ItemStack` @@ -1793,11 +1827,13 @@ 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 range [-32767, 32767]. For example: - -- Default dirt - groups = {crumbly=3, soil=1} +```lua +-- Default dirt +groups = {crumbly=3, soil=1} - -- A more special dirt-kind of thing - groups = {crumbly=2, soil=1, level=2, outerspace=1} +-- A more special dirt-kind of thing +groups = {crumbly=2, soil=1, level=2, outerspace=1} +``` Groups always have a rating associated with them. If there is no useful meaning for a rating for an enabled group, it shall be `1`. @@ -1807,7 +1843,9 @@ read groups, you must interpret `nil` and `0` as the same value, `0`. You can read the rating of a group for an item or a node by using - minetest.get_item_group(itemname, groupname) +```lua +minetest.get_item_group(itemname, groupname) +``` Groups of items --------------- @@ -1827,8 +1865,10 @@ 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. See [Entity damage mechanism]. - object:get_armor_groups() --> a group-rating table (e.g. {fleshy=100}) - object:set_armor_groups({fleshy=30, cracky=80}) +```lua +object:get_armor_groups() --> a group-rating table (e.g. {fleshy=100}) +object:set_armor_groups({fleshy=30, cracky=80}) +``` Groups of tool capabilities --------------------------- @@ -1844,38 +1884,46 @@ This means that any item in that group will be accepted as input. The basic syntax is: - "group:" +```lua +"group:" +``` For example, `"group:meat"` will accept any item in the `meat` group. It is also possible to require an input item to be in multiple groups at once. The syntax for that is: - "group:,,(...)," +```lua +"group:,,(...)," +``` For example, `"group:leaves,birch,trimmed"` accepts any item which is member of *all* the groups `leaves` *and* `birch` *and* `trimmed`. An example recipe: Craft a raw meat soup from any meat, any water and any bowl: - { - output = "food:meat_soup_raw", - recipe = { - {"group:meat"}, - {"group:water"}, - {"group:bowl"}, - }, - } +```lua +{ + output = "food:meat_soup_raw", + recipe = { + {"group:meat"}, + {"group:water"}, + {"group:bowl"}, + }, +} +``` Another example: Craft red wool from white wool and red dye (here, "red dye" is defined as any item which is member of *both* the groups `dye` and `basecolor_red`). - { - type = "shapeless", - output = "wool:red", - recipe = {"wool:white", "group:dye,basecolor_red"}, - } +```lua +{ + type = "shapeless", + output = "wool:red", + recipe = {"wool:white", "group:dye,basecolor_red"}, +} +``` Special groups -------------- @@ -2103,11 +2151,13 @@ For non-tools, this has no effect. Example definition of the capabilities of an item ------------------------------------------------- - tool_capabilities = { - groupcaps={ - crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}} - }, - } +```lua +tool_capabilities = { + groupcaps={ + crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}} + }, +} +``` This makes the item capable of digging nodes that fulfill both of these: @@ -2168,8 +2218,10 @@ a non-tool item, so that it can do something else than take damage. On the Lua side, every punch calls: - entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction, - damage) +```lua +entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction, + damage) +``` This should never be called directly, because damage is usually not handled by the entity itself. @@ -2186,7 +2238,9 @@ Return value of this function will determine if damage is done by this function To punch an entity/object in Lua, call: - object:punch(puncher, time_from_last_punch, tool_capabilities, direction) +```lua +object:punch(puncher, time_from_last_punch, tool_capabilities, direction) +``` * Return value is tool wear. * Parameters are equal to the above callback. @@ -2222,41 +2276,43 @@ Some of the values in the key-value store are handled specially: Example: - local meta = minetest.get_meta(pos) +```lua +local meta = minetest.get_meta(pos) - -- Set node formspec and infotext - meta:set_string("formspec", - "size[8,9]".. - "list[context;main;0,0;8,4;]".. - "list[current_player;main;0,5;8,4;]") - meta:set_string("infotext", "Chest"); +-- Set node formspec and infotext +meta:set_string("formspec", + "size[8,9]".. + "list[context;main;0,0;8,4;]".. + "list[current_player;main;0,5;8,4;]") +meta:set_string("infotext", "Chest"); - -- Set inventory list size of `"main"` list to 32 - local inv = meta:get_inventory() - inv:set_size("main", 32) +-- Set inventory list size of `"main"` list to 32 +local inv = meta:get_inventory() +inv:set_size("main", 32) - -- Dump node metadata - print(dump(meta:to_table())) +-- Dump node metadata +print(dump(meta:to_table())) - -- Set node metadata from a metadata table - meta:from_table({ - inventory = { - -- Set items of inventory in all 32 slots of the `"main"` list - main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", - [5] = "", [6] = "", [7] = "", [8] = "", [9] = "", - [10] = "", [11] = "", [12] = "", [13] = "", - [14] = "default:cobble", [15] = "", [16] = "", [17] = "", - [18] = "", [19] = "", [20] = "default:cobble", [21] = "", - [22] = "", [23] = "", [24] = "", [25] = "", [26] = "", - [27] = "", [28] = "", [29] = "", [30] = "", [31] = "", - [32] = ""} - }, - -- metadata fields - fields = { - formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]", - infotext = "Chest" - } - }) +-- Set node metadata from a metadata table +meta:from_table({ + inventory = { + -- Set items of inventory in all 32 slots of the `"main"` list + main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", + [5] = "", [6] = "", [7] = "", [8] = "", [9] = "", + [10] = "", [11] = "", [12] = "", [13] = "", + [14] = "default:cobble", [15] = "", [16] = "", [17] = "", + [18] = "", [19] = "", [20] = "default:cobble", [21] = "", + [22] = "", [23] = "", [24] = "", [25] = "", [26] = "", + [27] = "", [28] = "", [29] = "", [30] = "", [31] = "", + [32] = ""} + }, + -- metadata fields + fields = { + formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]", + infotext = "Chest" + } +}) +``` Item Metadata ------------- @@ -2289,26 +2345,29 @@ Some of the values in the key-value store are handled specially: Example: - local meta = stack:get_meta() - meta:set_string("key", "value") - print(dump(meta:to_table())) +```lua +local meta = stack:get_meta() +meta:set_string("key", "value") +print(dump(meta:to_table())) +``` Example manipulations of "description" and expected output behaviors: - print(ItemStack("default:pick_steel"):get_description()) --> Steel Pickaxe - print(ItemStack("foobar"):get_description()) --> Unknown Item +```lua +print(ItemStack("default:pick_steel"):get_description()) --> Steel Pickaxe +print(ItemStack("foobar"):get_description()) --> Unknown Item - local stack = ItemStack("default:stone") - stack:get_meta():set_string("description", "Custom description\nAnother line") - print(stack:get_description()) --> Custom description\nAnother line - print(stack:get_short_description()) --> Custom description +local stack = ItemStack("default:stone") +stack:get_meta():set_string("description", "Custom description\nAnother line") +print(stack:get_description()) --> Custom description\nAnother line +print(stack:get_short_description()) --> Custom description - stack:get_meta():set_string("short_description", "Short") - print(stack:get_description()) --> Custom description\nAnother line - print(stack:get_short_description()) --> Short - - print(ItemStack("mod:item_with_no_desc"):get_description()) --> mod:item_with_no_desc +stack:get_meta():set_string("short_description", "Short") +print(stack:get_description()) --> Custom description\nAnother line +print(stack:get_short_description()) --> Short +print(ItemStack("mod:item_with_no_desc"):get_description()) --> mod:item_with_no_desc +``` Formspec @@ -3765,8 +3824,10 @@ Two functions are provided to translate strings: `minetest.translate` and It is intended to be used in the following way, so that it avoids verbose repetitions of `minetest.translate`: - local S = minetest.get_translator(textdomain) - S(str, ...) + ```lua + local S = minetest.get_translator(textdomain) + S(str, ...) + ``` As an extra commodity, if `textdomain` is nil, it is assumed to be "" instead. @@ -3785,8 +3846,10 @@ Two functions are provided to translate strings: `minetest.translate` and For instance, suppose we want to translate "@1 Wool" with "@1" being replaced by the translation of "Red". We can do the following: - local S = minetest.get_translator() - S("@1 Wool", S("Red")) + ```lua + local S = minetest.get_translator() + S("@1 Wool", S("Red")) + ``` This will be displayed as "Red Wool" on old clients and on clients that do not have localization enabled. However, if we have for instance a translation @@ -4011,16 +4074,18 @@ noise = offset + scale * (abs(octave1) + For 2D or 3D perlin noise or perlin noise maps: - np_terrain = { - offset = 0, - scale = 1, - spread = {x = 500, y = 500, z = 500}, - seed = 571347, - octaves = 5, - persistence = 0.63, - lacunarity = 2.0, - flags = "defaults, absvalue", - } +```lua +np_terrain = { + offset = 0, + scale = 1, + spread = {x = 500, y = 500, z = 500}, + seed = 571347, + octaves = 5, + persistence = 0.63, + lacunarity = 2.0, + flags = "defaults, absvalue", +} +``` For 2D noise the Z component of `spread` is still defined but is ignored. A single noise parameter table can be used for 2D or 3D noise. @@ -4101,17 +4166,19 @@ by this ore type. This ore type is difficult to control since it is sensitive to small changes. The following is a decent set of parameters to work from: - noise_params = { - offset = 0, - scale = 3, - spread = {x=200, y=200, z=200}, - seed = 5390, - octaves = 4, - persistence = 0.5, - lacunarity = 2.0, - flags = "eased", - }, - noise_threshold = 1.6 +```lua +noise_params = { + offset = 0, + scale = 3, + spread = {x=200, y=200, z=200}, + seed = 5390, + octaves = 4, + persistence = 0.5, + lacunarity = 2.0, + flags = "eased", +}, +noise_threshold = 1.6 +``` **WARNING**: Use this ore type *very* sparingly since it is ~200x more computationally expensive than any other ore. @@ -4699,28 +4766,30 @@ Callbacks: Collision info passed to `on_step` (`moveresult` argument): - { - touching_ground = boolean, - -- Note that touching_ground is only true if the entity was moving and - -- collided with ground. +```lua +{ + touching_ground = boolean, + -- Note that touching_ground is only true if the entity was moving and + -- collided with ground. - collides = boolean, - standing_on_object = boolean, + collides = boolean, + standing_on_object = boolean, - collisions = { - { - type = string, -- "node" or "object", - axis = string, -- "x", "y" or "z" - node_pos = vector, -- if type is "node" - object = ObjectRef, -- if type is "object" - old_velocity = vector, - new_velocity = vector, - }, - ... - } - -- `collisions` does not contain data of unloaded mapblock collisions - -- or when the velocity changes are negligibly small + collisions = { + { + type = string, -- "node" or "object", + axis = string, -- "x", "y" or "z" + node_pos = vector, -- if type is "node" + object = ObjectRef, -- if type is "object" + old_velocity = vector, + new_velocity = vector, + }, + ... } + -- `collisions` does not contain data of unloaded mapblock collisions + -- or when the velocity changes are negligibly small +} +``` @@ -4730,27 +4799,28 @@ L-system trees Tree definition --------------- - treedef={ - axiom, --string initial tree axiom - rules_a, --string rules set A - rules_b, --string rules set B - rules_c, --string rules set C - rules_d, --string rules set D - trunk, --string trunk node name - leaves, --string leaves node name - leaves2, --string secondary leaves node name - leaves2_chance,--num chance (0-100) to replace leaves with leaves2 - angle, --num angle in deg - iterations, --num max # of iterations, usually 2 -5 - random_level, --num factor to lower number of iterations, usually 0 - 3 - trunk_type, --string single/double/crossed) type of trunk: 1 node, - -- 2x2 nodes or 3x3 in cross shape - thin_branches, --boolean true -> use thin (1 node) branches - fruit, --string fruit node name - fruit_chance, --num chance (0-100) to replace leaves with fruit node - seed, --num random seed, if no seed is provided, the engine - will create one. - } +```lua +treedef={ + axiom, --string initial tree axiom + rules_a, --string rules set A + rules_b, --string rules set B + rules_c, --string rules set C + rules_d, --string rules set D + trunk, --string trunk node name + leaves, --string leaves node name + leaves2, --string secondary leaves node name + leaves2_chance,--num chance (0-100) to replace leaves with leaves2 + angle, --num angle in deg + iterations, --num max # of iterations, usually 2 -5 + random_level, --num factor to lower number of iterations, usually 0 - 3 + trunk_type, --string single/double/crossed) type of trunk: 1 node, + -- 2x2 nodes or 3x3 in cross shape + thin_branches, --boolean true -> use thin (1 node) branches + fruit, --string fruit node name + fruit_chance, --num chance (0-100) to replace leaves with fruit node + seed, --num random seed, if no seed is provided, the engine will create one. +} +``` Key for special L-System symbols used in axioms ----------------------------------------------- @@ -4782,23 +4852,24 @@ Example Spawn a small apple tree: - 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) - +```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) +``` Privileges ========== @@ -4907,81 +4978,85 @@ Utilities current game. Note that other meta information (e.g. version/release number) can be manually read from `game.conf` in the game's root directory. - { - id = string, - title = string, - author = string, - -- The root directory of the game - path = string, - } + ```lua + { + id = string, + title = string, + author = string, + -- The root directory of the game + path = string, + } + ``` * `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"` * Useful for storing custom data * `minetest.is_singleplayer()` * `minetest.features`: Table containing API feature flags - { - glasslike_framed = true, -- 0.4.7 - nodebox_as_selectionbox = true, -- 0.4.7 - get_all_craft_recipes_works = true, -- 0.4.7 - -- The transparency channel of textures can optionally be used on - -- nodes (0.4.7) - use_texture_alpha = true, - -- Tree and grass ABMs are no longer done from C++ (0.4.8) - no_legacy_abms = true, - -- Texture grouping is possible using parentheses (0.4.11) - texture_names_parens = true, - -- Unique Area ID for AreaStore:insert_area (0.4.14) - area_store_custom_ids = true, - -- add_entity supports passing initial staticdata to on_activate - -- (0.4.16) - add_entity_with_staticdata = true, - -- Chat messages are no longer predicted (0.4.16) - no_chat_message_prediction = true, - -- The transparency channel of textures can optionally be used on - -- objects (ie: players and lua entities) (5.0.0) - object_use_texture_alpha = true, - -- Object selectionbox is settable independently from collisionbox - -- (5.0.0) - object_independent_selectionbox = true, - -- Specifies whether binary data can be uploaded or downloaded using - -- the HTTP API (5.1.0) - httpfetch_binary_data = true, - -- Whether formspec_version[] may be used (5.1.0) - formspec_version_element = true, - -- Whether AreaStore's IDs are kept on save/load (5.1.0) - area_store_persistent_ids = true, - -- Whether minetest.find_path is functional (5.2.0) - pathfinder_works = true, - -- Whether Collision info is available to an objects' on_step (5.3.0) - object_step_has_moveresult = true, - -- Whether get_velocity() and add_velocity() can be used on players (5.4.0) - direct_velocity_on_players = true, - -- nodedef's use_texture_alpha accepts new string modes (5.4.0) - use_texture_alpha_string_modes = true, - -- degrotate param2 rotates in units of 1.5° instead of 2° - -- thus changing the range of values from 0-179 to 0-240 (5.5.0) - degrotate_240_steps = true, - -- ABM supports min_y and max_y fields in definition (5.5.0) - abm_min_max_y = true, - -- dynamic_add_media supports passing a table with options (5.5.0) - dynamic_add_media_table = true, - -- particlespawners support texpools and animation of properties, - -- particle textures support smooth fade and scale animations, and - -- sprite-sheet particle animations can by synced to the lifetime - -- of individual particles (5.6.0) - particlespawner_tweenable = true, - -- allows get_sky to return a table instead of separate values (5.6.0) - get_sky_as_table = true, - -- VoxelManip:get_light_data accepts an optional buffer argument (5.7.0) - get_light_data_buffer = true, - -- When using a mod storage backend that is not "files" or "dummy", - -- the amount of data in mod storage is not constrained by - -- the amount of RAM available. (5.7.0) - mod_storage_on_disk = true, - -- "zstd" method for compress/decompress (5.7.0) - compress_zstd = true, - } + ```lua + { + glasslike_framed = true, -- 0.4.7 + nodebox_as_selectionbox = true, -- 0.4.7 + get_all_craft_recipes_works = true, -- 0.4.7 + -- The transparency channel of textures can optionally be used on + -- nodes (0.4.7) + use_texture_alpha = true, + -- Tree and grass ABMs are no longer done from C++ (0.4.8) + no_legacy_abms = true, + -- Texture grouping is possible using parentheses (0.4.11) + texture_names_parens = true, + -- Unique Area ID for AreaStore:insert_area (0.4.14) + area_store_custom_ids = true, + -- add_entity supports passing initial staticdata to on_activate + -- (0.4.16) + add_entity_with_staticdata = true, + -- Chat messages are no longer predicted (0.4.16) + no_chat_message_prediction = true, + -- The transparency channel of textures can optionally be used on + -- objects (ie: players and lua entities) (5.0.0) + object_use_texture_alpha = true, + -- Object selectionbox is settable independently from collisionbox + -- (5.0.0) + object_independent_selectionbox = true, + -- Specifies whether binary data can be uploaded or downloaded using + -- the HTTP API (5.1.0) + httpfetch_binary_data = true, + -- Whether formspec_version[] may be used (5.1.0) + formspec_version_element = true, + -- Whether AreaStore's IDs are kept on save/load (5.1.0) + area_store_persistent_ids = true, + -- Whether minetest.find_path is functional (5.2.0) + pathfinder_works = true, + -- Whether Collision info is available to an objects' on_step (5.3.0) + object_step_has_moveresult = true, + -- Whether get_velocity() and add_velocity() can be used on players (5.4.0) + direct_velocity_on_players = true, + -- nodedef's use_texture_alpha accepts new string modes (5.4.0) + use_texture_alpha_string_modes = true, + -- degrotate param2 rotates in units of 1.5° instead of 2° + -- thus changing the range of values from 0-179 to 0-240 (5.5.0) + degrotate_240_steps = true, + -- ABM supports min_y and max_y fields in definition (5.5.0) + abm_min_max_y = true, + -- dynamic_add_media supports passing a table with options (5.5.0) + dynamic_add_media_table = true, + -- particlespawners support texpools and animation of properties, + -- particle textures support smooth fade and scale animations, and + -- sprite-sheet particle animations can by synced to the lifetime + -- of individual particles (5.6.0) + particlespawner_tweenable = true, + -- allows get_sky to return a table instead of separate values (5.6.0) + get_sky_as_table = true, + -- VoxelManip:get_light_data accepts an optional buffer argument (5.7.0) + get_light_data_buffer = true, + -- When using a mod storage backend that is not "files" or "dummy", + -- the amount of data in mod storage is not constrained by + -- the amount of RAM available. (5.7.0) + mod_storage_on_disk = true, + -- "zstd" method for compress/decompress (5.7.0) + compress_zstd = true, + } + ``` * `minetest.has_feature(arg)`: returns `boolean, missing_features` * `arg`: string or table in format `{foo=true, bar=true}` @@ -4989,66 +5064,71 @@ Utilities * `minetest.get_player_information(player_name)`: Table containing information about a player. Example return value: - { - address = "127.0.0.1", -- IP address of client - ip_version = 4, -- IPv4 / IPv6 - connection_uptime = 200, -- seconds since client connected - protocol_version = 32, -- protocol version used by client - formspec_version = 2, -- supported formspec version - lang_code = "fr", -- Language code used for translation + ```lua + { + address = "127.0.0.1", -- IP address of client + ip_version = 4, -- IPv4 / IPv6 + connection_uptime = 200, -- seconds since client connected + protocol_version = 32, -- protocol version used by client + formspec_version = 2, -- supported formspec version + lang_code = "fr", -- Language code used for translation + + -- the following keys can be missing if no stats have been collected yet + min_rtt = 0.01, -- minimum round trip time + max_rtt = 0.2, -- maximum round trip time + avg_rtt = 0.02, -- average round trip time + min_jitter = 0.01, -- minimum packet time jitter + max_jitter = 0.5, -- maximum packet time jitter + avg_jitter = 0.03, -- average packet time jitter + -- the following information is available in a debug build only!!! + -- DO NOT USE IN MODS + --ser_vers = 26, -- serialization version used by client + --major = 0, -- major version number + --minor = 4, -- minor version number + --patch = 10, -- patch version number + --vers_string = "0.4.9-git", -- full version string + --state = "Active" -- current client state + } + ``` - -- the following keys can be missing if no stats have been collected yet - min_rtt = 0.01, -- minimum round trip time - max_rtt = 0.2, -- maximum round trip time - avg_rtt = 0.02, -- average round trip time - min_jitter = 0.01, -- minimum packet time jitter - max_jitter = 0.5, -- maximum packet time jitter - avg_jitter = 0.03, -- average packet time jitter - -- the following information is available in a debug build only!!! - -- DO NOT USE IN MODS - --ser_vers = 26, -- serialization version used by client - --major = 0, -- major version number - --minor = 4, -- minor version number - --patch = 10, -- patch version number - --vers_string = "0.4.9-git", -- full version string - --state = "Active" -- current client state - } * `minetest.get_player_window_information(player_name)`: - -- Will only be present if the client sent this information (requires v5.7+) + ```lua + -- Will only be present if the client sent this information (requires v5.7+) + -- + -- Note that none of these things are constant, they are likely to change during a client + -- connection as the player resizes the window and moves it between monitors + -- + -- real_gui_scaling and real_hud_scaling can be used instead of DPI. + -- OSes don't necessarily give the physical DPI, as they may allow user configuration. + -- real_*_scaling is just OS DPI / 96 but with another level of user configuration. + { + -- Current size of the in-game render target (pixels). -- - -- Note that none of these things are constant, they are likely to change during a client - -- connection as the player resizes the window and moves it between monitors - -- - -- real_gui_scaling and real_hud_scaling can be used instead of DPI. - -- OSes don't necessarily give the physical DPI, as they may allow user configuration. - -- real_*_scaling is just OS DPI / 96 but with another level of user configuration. - { - -- Current size of the in-game render target (pixels). - -- - -- This is usually the window size, but may be smaller in certain situations, - -- such as side-by-side mode. - size = { - x = 1308, - y = 577, - }, + -- This is usually the window size, but may be smaller in certain situations, + -- such as side-by-side mode. + size = { + x = 1308, + y = 577, + }, - -- Estimated maximum formspec size before Minetest will start shrinking the - -- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than - -- this and `padding[-0.01,-0.01]`. - max_formspec_size = { - x = 20, - y = 11.25 - }, + -- Estimated maximum formspec size before Minetest will start shrinking the + -- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than + -- this and `padding[-0.01,-0.01]`. + max_formspec_size = { + x = 20, + y = 11.25 + }, - -- GUI Scaling multiplier - -- Equal to the setting `gui_scaling` multiplied by `dpi / 96` - real_gui_scaling = 1, + -- GUI Scaling multiplier + -- Equal to the setting `gui_scaling` multiplied by `dpi / 96` + real_gui_scaling = 1, - -- HUD Scaling multiplier - -- Equal to the setting `hud_scaling` multiplied by `dpi / 96` - real_hud_scaling = 1, - } + -- HUD Scaling multiplier + -- Equal to the setting `hud_scaling` multiplied by `dpi / 96` + real_hud_scaling = 1, + } + ``` * `minetest.mkdir(path)`: returns success. * Creates a directory specified by `path`, creating parent directories @@ -6014,17 +6094,18 @@ Item handling * `items`: indexed [1-9] table with recipe items * `output`: string with item name and quantity * Example result for `"default:gold_ingot"` with two recipes: - + ```lua + { { - { - method = "cooking", width = 3, - output = "default:gold_ingot", items = {"default:gold_lump"} - }, - { - method = "normal", width = 1, - output = "default:gold_ingot 9", items = {"default:goldblock"} - } + method = "cooking", width = 3, + output = "default:gold_ingot", items = {"default:gold_lump"} + }, + { + method = "normal", width = 1, + output = "default:gold_ingot 9", items = {"default:goldblock"} } + } + ``` * `minetest.handle_node_drops(pos, drops, digger)` * `drops`: list of itemstrings @@ -6545,14 +6626,15 @@ Misc. * Cache and call the old version of this function if the position is not protected by the mod. This will allow using multiple protection mods. * Example: - - local old_is_protected = minetest.is_protected - function minetest.is_protected(pos, name) - if mymod:position_protected_from(pos, name) then - return true - end - return old_is_protected(pos, name) + ```lua + local old_is_protected = minetest.is_protected + function minetest.is_protected(pos, name) + if mymod:position_protected_from(pos, name) then + return true end + return old_is_protected(pos, name) + end + ``` * `minetest.record_protection_violation(pos, name)` * This function calls functions registered with `minetest.register_on_protection_violation`. @@ -6745,13 +6827,14 @@ use the provided load and write functions for this. * `get_area(id, include_corners, include_data)` * Returns the area information about the specified ID. * Returned values are either of these: - - nil -- Area not found - true -- Without `include_corners` and `include_data` - { - min = pos, max = pos -- `include_corners == true` - data = string -- `include_data == true` - } + ```lua + nil -- Area not found + true -- Without `include_corners` and `include_data` + { + min = pos, max = pos -- `include_corners == true` + data = string -- `include_data == true` + } + ``` * `get_areas_for_pos(pos, include_corners, include_data)` * Returns all areas as table, indexed by the area ID. @@ -6779,12 +6862,15 @@ use the provided load and write functions for this. Calling invalidates the cache, so that its elements have to be newly generated. * `params` is a table with the following fields: - + ```lua + { enabled = boolean, -- Whether to enable, default true block_radius = int, -- The radius (in nodes) of the areas the cache -- generates prefiltered lists for, minimum 16, -- default 64 limit = int, -- The cache size, minimum 20, default 1000 + } + ``` * `to_string()`: Experimental. Returns area store serialized as a (binary) string. * `to_file(filename)`: Experimental. Like `to_string()`, but writes the data to @@ -7009,29 +7095,31 @@ A metadata table is a table that has the following keys: Example: - metadata_table = { - -- metadata fields (key/value store) - fields = { - infotext = "Container", - anoter_key = "Another Value", - }, +```lua +metadata_table = { + -- metadata fields (key/value store) + fields = { + infotext = "Container", + anoter_key = "Another Value", + }, - -- inventory data (for nodes) - inventory = { - -- inventory list "main" with 4 slots - main = { - -- list of all item slots - [1] = "example:dirt", - [2] = "example:stone 25", - [3] = "", -- empty slot - [4] = "example:pickaxe", - }, - -- inventory list "hidden" with 1 slot - hidden = { - [1] = "example:diamond", - }, + -- inventory data (for nodes) + inventory = { + -- inventory list "main" with 4 slots + main = { + -- list of all item slots + [1] = "example:dirt", + [2] = "example:stone 25", + [3] = "", -- empty slot + [4] = "example:pickaxe", }, - } + -- inventory list "hidden" with 1 slot + hidden = { + [1] = "example:diamond", + }, + }, +} +``` `ModChannel` ------------ @@ -7205,23 +7293,27 @@ child will follow movement and rotation of that bone. * `is_player()`: returns true for players, false otherwise * `get_nametag_attributes()` * returns a table with the attributes of the nametag of an object - * { - text = "", - color = {a=0..255, r=0..255, g=0..255, b=0..255}, - bgcolor = {a=0..255, r=0..255, g=0..255, b=0..255}, + * ```lua + { + text = "", + color = {a=0..255, r=0..255, g=0..255, b=0..255}, + bgcolor = {a=0..255, r=0..255, g=0..255, b=0..255}, } + ``` * `set_nametag_attributes(attributes)` * sets the attributes of the nametag of an object * `attributes`: + ```lua { - text = "My Nametag", - color = ColorSpec, - -- ^ Text color - bgcolor = ColorSpec or false, - -- ^ Sets background color of nametag - -- `false` will cause the background to be set automatically based on user settings - -- Default: false + text = "My Nametag", + color = ColorSpec, + -- ^ Text color + bgcolor = ColorSpec or false, + -- ^ Sets background color of nametag + -- `false` will cause the background to be set automatically based on user settings + -- Default: false } + ``` #### Lua entity only (no-op for other objects) @@ -7721,10 +7813,12 @@ It can be created via `PseudoRandom(seed)`. A raycast on the map. It works with selection boxes. Can be used as an iterator in a for loop as: - local ray = Raycast(...) - for pointed_thing in ray do - ... - end +```lua +local ray = Raycast(...) +for pointed_thing in ray do + ... +end +``` The map is loaded as the ray advances. If the map is modified after the `Raycast` is created, the changes may or may not have an effect on the object. @@ -7844,201 +7938,205 @@ These properties are not persistent, but are applied automatically to the corresponding Lua entity using the given registration fields. Player properties need to be saved manually. - { - hp_max = 10, - -- Defines the maximum and default HP of the entity - -- For Lua entities the maximum is not enforced. - -- For players this defaults to `minetest.PLAYER_MAX_HP_DEFAULT`. +```lua +{ + hp_max = 10, + -- Defines the maximum and default HP of the entity + -- For Lua entities the maximum is not enforced. + -- For players this defaults to `minetest.PLAYER_MAX_HP_DEFAULT`. - breath_max = 0, - -- For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`. + breath_max = 0, + -- For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`. - zoom_fov = 0.0, - -- For players 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. + zoom_fov = 0.0, + -- For players 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. - eye_height = 1.625, - -- For players only. Camera height above feet position in nodes. + eye_height = 1.625, + -- For players only. Camera height above feet position in nodes. - physical = false, - -- Collide with `walkable` nodes. + physical = false, + -- Collide with `walkable` nodes. - collide_with_objects = true, - -- Collide with other objects if physical = true + collide_with_objects = true, + -- Collide with other objects if physical = true - collisionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5 }, -- default - selectionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5, rotate = false }, - -- { xmin, ymin, zmin, xmax, ymax, zmax } in nodes from object position. - -- Collision boxes cannot rotate, setting `rotate = true` on it has no effect. - -- If not set, the selection box copies the collision box, and will also not rotate. - -- If `rotate = false`, the selection box will not rotate with the object itself, remaining fixed to the axes. - -- If `rotate = true`, it will match the object's rotation and any attachment rotations. - -- Raycasts use the selection box and object's rotation, but do *not* obey attachment rotations. + collisionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5 }, -- default + selectionbox = { -0.5, -0.5, -0.5, 0.5, 0.5, 0.5, rotate = false }, + -- { xmin, ymin, zmin, xmax, ymax, zmax } in nodes from object position. + -- Collision boxes cannot rotate, setting `rotate = true` on it has no effect. + -- If not set, the selection box copies the collision box, and will also not rotate. + -- If `rotate = false`, the selection box will not rotate with the object itself, remaining fixed to the axes. + -- If `rotate = true`, it will match the object's rotation and any attachment rotations. + -- Raycasts use the selection box and object's rotation, but do *not* obey attachment rotations. - pointable = true, - -- Whether the object can be pointed at + pointable = true, + -- Whether the object can be pointed at - visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem" / "item", - -- "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. - -- Wielditems are scaled a bit. If you want a wielditem to appear - -- to be as large as a node, use `0.667` in `visual_size` - -- "item" is similar to "wielditem" but ignores the 'wield_image' parameter. + visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem" / "item", + -- "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. + -- Wielditems are scaled a bit. If you want a wielditem to appear + -- to be as large as a node, use `0.667` in `visual_size` + -- "item" is similar to "wielditem" but ignores the 'wield_image' parameter. - visual_size = {x = 1, y = 1, z = 1}, - -- Multipliers for the visual size. If `z` is not specified, `x` will be used - -- to scale the entity along both horizontal axes. + visual_size = {x = 1, y = 1, z = 1}, + -- Multipliers for the visual size. If `z` is not specified, `x` will be used + -- to scale the entity along both horizontal axes. - mesh = "model.obj", - -- File name of mesh when using "mesh" visual + mesh = "model.obj", + -- File name of mesh when using "mesh" visual - textures = {}, - -- 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) + textures = {}, + -- 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) - colors = {}, - -- Number of required colors depends on visual + colors = {}, + -- Number of required colors depends on visual - use_texture_alpha = false, - -- 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. + use_texture_alpha = false, + -- 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. - spritediv = {x = 1, y = 1}, - -- 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: - -- {columns, rows}. + spritediv = {x = 1, y = 1}, + -- 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: + -- {columns, rows}. - initial_sprite_basepos = {x = 0, y = 0}, - -- Used with spritesheet textures. - -- Defines the {column, row} position of the initially used frame in the - -- spritesheet. + initial_sprite_basepos = {x = 0, y = 0}, + -- Used with spritesheet textures. + -- Defines the {column, row} position of the initially used frame in the + -- spritesheet. - is_visible = true, - -- If false, object is invisible and can't be pointed. + is_visible = true, + -- If false, object is invisible and can't be pointed. - makes_footstep_sound = false, - -- If true, is able to make footstep sounds of nodes - -- (see node sound definition for details). + makes_footstep_sound = false, + -- If true, is able to make footstep sounds of nodes + -- (see node sound definition for details). - automatic_rotate = 0, - -- 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. + automatic_rotate = 0, + -- 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. - stepheight = 0, - -- If positive number, object will climb upwards when it moves - -- horizontally against a `walkable` node, if the height difference - -- is within `stepheight`. + stepheight = 0, + -- If positive number, object will climb upwards when it moves + -- horizontally against a `walkable` node, if the height difference + -- is within `stepheight`. - automatic_face_movement_dir = 0.0, - -- Automatically set yaw to movement direction, offset in degrees. - -- 'false' to disable. + automatic_face_movement_dir = 0.0, + -- Automatically set yaw to movement direction, offset in degrees. + -- 'false' to disable. - automatic_face_movement_max_rotation_per_sec = -1, - -- Limit automatic rotation to this value in degrees per second. - -- No limit if value <= 0. + automatic_face_movement_max_rotation_per_sec = -1, + -- Limit automatic rotation to this value in degrees per second. + -- No limit if value <= 0. - backface_culling = true, - -- Set to false to disable backface_culling for model + backface_culling = true, + -- Set to false to disable backface_culling for model - glow = 0, - -- 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. + glow = 0, + -- 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. - nametag = "", - -- 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. + nametag = "", + -- 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. - nametag_color = , - -- Sets text color of nametag + nametag_color = , + -- Sets text color of nametag - nametag_bgcolor = , - -- Sets background color of nametag - -- `false` will cause the background to be set automatically based on user settings. - -- Default: false + nametag_bgcolor = , + -- Sets background color of nametag + -- `false` will cause the background to be set automatically based on user settings. + -- Default: false - infotext = "", - -- Same as infotext for nodes. Empty by default + infotext = "", + -- Same as infotext for nodes. Empty by default - static_save = true, - -- 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'. + static_save = true, + -- 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'. - damage_texture_modifier = "^[brighten", - -- Texture modifier to be applied for a short duration when object is hit + damage_texture_modifier = "^[brighten", + -- Texture modifier to be applied for a short duration when object is hit - shaded = true, - -- Setting this to 'false' disables diffuse lighting of entity + shaded = true, + -- Setting this to 'false' disables diffuse lighting of entity - show_on_minimap = false, - -- Defaults to true for players, false for other entities. - -- If set to true the entity will show as a marker on the minimap. - } + show_on_minimap = false, + -- Defaults to true for players, false for other entities. + -- If set to true the entity will show as a marker on the minimap. +} +``` Entity definition ----------------- Used by `minetest.register_entity`. - { - initial_properties = { - visual = "mesh", - mesh = "boats_boat.obj", - ..., - }, - -- A table of object properties, see the `Object properties` section. - -- The properties in this table are applied to the object - -- once when it is spawned. +```lua +{ + initial_properties = { + visual = "mesh", + mesh = "boats_boat.obj", + ..., + }, + -- A table of object properties, see the `Object properties` section. + -- The properties in this table are applied to the object + -- once when it is spawned. - -- Refer to the "Registered entities" section for explanations - on_activate = function(self, staticdata, dtime_s), - on_deactivate = function(self, removal), - on_step = function(self, dtime, moveresult), - on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir, damage), - on_death = function(self, killer), - on_rightclick = function(self, clicker), - on_attach_child = function(self, child), - on_detach_child = function(self, child), - on_detach = function(self, parent), - get_staticdata = function(self), + -- Refer to the "Registered entities" section for explanations + on_activate = function(self, staticdata, dtime_s) end, + on_deactivate = function(self, removal) end, + on_step = function(self, dtime, moveresult) end, + on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir, damage) end, + on_death = function(self, killer) end, + on_rightclick = function(self, clicker) end, + on_attach_child = function(self, child) end, + on_detach_child = function(self, child) end, + on_detach = function(self, parent) end, + get_staticdata = function(self) end, - _custom_field = whatever, - -- You can define arbitrary member variables here (see Item definition - -- for more info) by using a '_' prefix - } + _custom_field = whatever, + -- You can define arbitrary member variables here (see Item definition + -- for more info) by using a '_' prefix +} +``` ABM (ActiveBlockModifier) definition @@ -8046,47 +8144,49 @@ ABM (ActiveBlockModifier) definition Used by `minetest.register_abm`. - { - label = "Lava cooling", - -- Descriptive label for profiling purposes (optional). - -- Definitions with identical labels will be listed as one. +```lua +{ + label = "Lava cooling", + -- Descriptive label for profiling purposes (optional). + -- Definitions with identical labels will be listed as one. - nodenames = {"default:lava_source"}, - -- Apply `action` function to these nodes. - -- `group:groupname` can also be used here. + nodenames = {"default:lava_source"}, + -- Apply `action` function to these nodes. + -- `group:groupname` can also be used here. - neighbors = {"default:water_source", "default:water_flowing"}, - -- 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. + neighbors = {"default:water_source", "default:water_flowing"}, + -- 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. - interval = 10.0, - -- Operation interval in seconds + interval = 10.0, + -- Operation interval in seconds - chance = 50, - -- Chance of triggering `action` per-node per-interval is 1.0 / chance + chance = 50, + -- Chance of triggering `action` per-node per-interval is 1.0 / chance - min_y = -32768, - max_y = 32767, - -- min and max height levels where ABM will be processed (inclusive) - -- can be used to reduce CPU usage + min_y = -32768, + max_y = 32767, + -- min and max height levels where ABM will be processed (inclusive) + -- can be used to reduce CPU usage - catch_up = true, - -- If true, catch-up behavior 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. + catch_up = true, + -- If true, catch-up behavior 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. - action = function(pos, node, active_object_count, active_object_count_wider), - -- 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. - } + action = function(pos, node, active_object_count, active_object_count_wider), + -- 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. +} +``` LBM (LoadingBlockModifier) definition ------------------------------------- @@ -8097,29 +8197,31 @@ A loading block modifier (LBM) is used to define a function that is called for specific nodes (defined by `nodenames`) when a mapblock which contains such nodes gets activated (not loaded!) - { - label = "Upgrade legacy doors", - -- Descriptive label for profiling purposes (optional). - -- Definitions with identical labels will be listed as one. +```lua +{ + label = "Upgrade legacy doors", + -- Descriptive label for profiling purposes (optional). + -- Definitions with identical labels will be listed as one. - name = "modname:replace_legacy_door", - -- Identifier of the LBM, should follow the modname: convention + name = "modname:replace_legacy_door", + -- Identifier of the LBM, should follow the modname: convention - nodenames = {"default:lava_source"}, - -- List of node names to trigger the LBM on. - -- Names of non-registered nodes and groups (as group:groupname) - -- will work as well. + nodenames = {"default:lava_source"}, + -- List of node names to trigger the LBM on. + -- Names of non-registered nodes and groups (as group:groupname) + -- will work as well. - run_at_every_load = false, - -- 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. + run_at_every_load = false, + -- 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. - action = function(pos, node, dtime_s), - -- Function triggered for each qualifying node. - -- `dtime_s` is the in-game time (in seconds) elapsed since the block - -- was last active - } + action = function(pos, node, dtime_s) end, + -- Function triggered for each qualifying node. + -- `dtime_s` is the in-game time (in seconds) elapsed since the block + -- was last active +} +``` Tile definition --------------- @@ -8146,31 +8248,33 @@ Tile definition Tile animation definition ------------------------- - { - type = "vertical_frames", +```lua +{ + type = "vertical_frames", - aspect_w = 16, - -- Width of a frame in pixels + aspect_w = 16, + -- Width of a frame in pixels - aspect_h = 16, - -- Height of a frame in pixels + aspect_h = 16, + -- Height of a frame in pixels - length = 3.0, - -- Full loop length - } + length = 3.0, + -- Full loop length +} - { - type = "sheet_2d", +{ + type = "sheet_2d", - frames_w = 5, - -- Width in number of frames + frames_w = 5, + -- Width in number of frames - frames_h = 3, - -- Height in number of frames + frames_h = 3, + -- Height in number of frames - frame_length = 0.5, - -- Length of a single frame - } + frame_length = 0.5, + -- Length of a single frame +} +``` Item definition --------------- @@ -8178,616 +8282,620 @@ Item definition Used by `minetest.register_node`, `minetest.register_craftitem`, and `minetest.register_tool`. - { - description = "", - -- Can contain new lines. "\n" has to be used as new line character. - -- See also: `get_description` in [`ItemStack`] +```lua +{ + description = "", + -- Can contain new lines. "\n" has to be used as new line character. + -- See also: `get_description` in [`ItemStack`] - short_description = "", - -- Must not contain new lines. - -- Defaults to nil. - -- Use an [`ItemStack`] to get the short description, e.g.: - -- ItemStack(itemname):get_short_description() + short_description = "", + -- Must not contain new lines. + -- Defaults to nil. + -- Use an [`ItemStack`] to get the short description, e.g.: + -- ItemStack(itemname):get_short_description() - groups = {}, - -- key = name, value = rating; rating = . - -- If rating not applicable, use 1. - -- e.g. {wool = 1, fluffy = 3} - -- {soil = 2, outerspace = 1, crumbly = 1} - -- {bendy = 2, snappy = 1}, - -- {hard = 1, metal = 1, spikes = 1} + groups = {}, + -- key = name, value = rating; rating = . + -- If rating not applicable, use 1. + -- e.g. {wool = 1, fluffy = 3} + -- {soil = 2, outerspace = 1, crumbly = 1} + -- {bendy = 2, snappy = 1}, + -- {hard = 1, metal = 1, spikes = 1} - inventory_image = "", - -- Texture shown in the inventory GUI - -- Defaults to a 3D rendering of the node if left empty. + inventory_image = "", + -- Texture shown in the inventory GUI + -- Defaults to a 3D rendering of the node if left empty. - inventory_overlay = "", - -- An overlay texture which is not affected by colorization + inventory_overlay = "", + -- An overlay texture which is not affected by colorization - wield_image = "", - -- Texture shown when item is held in hand - -- Defaults to a 3D rendering of the node if left empty. + wield_image = "", + -- Texture shown when item is held in hand + -- Defaults to a 3D rendering of the node if left empty. - wield_overlay = "", - -- Like inventory_overlay but only used in the same situation as wield_image + wield_overlay = "", + -- Like inventory_overlay but only used in the same situation as wield_image - wield_scale = {x = 1, y = 1, z = 1}, - -- Scale for the item when held in hand + wield_scale = {x = 1, y = 1, z = 1}, + -- Scale for the item when held in hand - palette = "", - -- An image file containing the palette of a node. - -- You can set the currently used color as the "palette_index" field of - -- the item stack metadata. - -- The palette is always stretched to fit indices between 0 and 255, to - -- ensure compatibility with "colorfacedir" (and similar) nodes. + palette = "", + -- An image file containing the palette of a node. + -- You can set the currently used color as the "palette_index" field of + -- the item stack metadata. + -- The palette is always stretched to fit indices between 0 and 255, to + -- ensure compatibility with "colorfacedir" (and similar) nodes. - color = "#ffffffff", - -- Color the item is colorized with. The palette overrides this. + color = "#ffffffff", + -- Color the item is colorized with. The palette overrides this. - stack_max = 99, - -- Maximum amount of items that can be in a single stack. - -- The default can be changed by the setting `default_stack_max` + stack_max = 99, + -- Maximum amount of items that can be in a single stack. + -- The default can be changed by the setting `default_stack_max` - range = 4.0, - -- Range of node and object pointing that is possible with this item held + range = 4.0, + -- Range of node and object pointing that is possible with this item held - liquids_pointable = false, - -- If true, item can point to all liquid nodes (`liquidtype ~= "none"`), - -- even those for which `pointable = false` + liquids_pointable = false, + -- If true, item can point to all liquid nodes (`liquidtype ~= "none"`), + -- even those for which `pointable = false` - light_source = 0, - -- When used for nodes: Defines amount of light emitted by node. - -- Otherwise: Defines texture glow when viewed as a dropped item - -- To set the maximum (14), use the value 'minetest.LIGHT_MAX'. - -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined - -- behavior. + light_source = 0, + -- When used for nodes: Defines amount of light emitted by node. + -- Otherwise: Defines texture glow when viewed as a dropped item + -- To set the maximum (14), use the value 'minetest.LIGHT_MAX'. + -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined + -- behavior. - -- See "Tool Capabilities" section for an example including explanation - tool_capabilities = { - full_punch_interval = 1.0, - max_drop_level = 0, - groupcaps = { - -- For example: - choppy = {times = {2.50, 1.40, 1.00}, uses = 20, maxlevel = 2}, - }, - damage_groups = {groupname = damage}, - -- Damage values must be between -32768 and 32767 (2^15) - - punch_attack_uses = nil, - -- Amount of uses this tool has for attacking players and entities - -- by punching them (0 = infinite uses). - -- For compatibility, this is automatically set from the first - -- suitable groupcap using the formula "uses * 3^(maxlevel - 1)". - -- It is recommend to set this explicitly instead of relying on the - -- fallback behavior. + -- See "Tool Capabilities" section for an example including explanation + tool_capabilities = { + full_punch_interval = 1.0, + max_drop_level = 0, + groupcaps = { + -- For example: + choppy = {times = {2.50, 1.40, 1.00}, uses = 20, maxlevel = 2}, }, + damage_groups = {groupname = damage}, + -- Damage values must be between -32768 and 32767 (2^15) - node_placement_prediction = nil, - -- If nil and item is node, prediction is made automatically. - -- If nil and item is not a node, no prediction is made. - -- If "" and item is anything, no prediction is made. - -- Otherwise should be name of node which the client immediately places - -- on ground when the player places the item. Server will always update - -- with actual result shortly. + punch_attack_uses = nil, + -- Amount of uses this tool has for attacking players and entities + -- by punching them (0 = infinite uses). + -- For compatibility, this is automatically set from the first + -- suitable groupcap using the formula "uses * 3^(maxlevel - 1)". + -- It is recommend to set this explicitly instead of relying on the + -- fallback behavior. + }, - node_dig_prediction = "air", - -- if "", no prediction is made. - -- if "air", node is removed. - -- Otherwise should be name of node which the client immediately places - -- upon digging. Server will always update with actual result shortly. + node_placement_prediction = nil, + -- If nil and item is node, prediction is made automatically. + -- If nil and item is not a node, no prediction is made. + -- If "" and item is anything, no prediction is made. + -- Otherwise should be name of node which the client immediately places + -- on ground when the player places the item. Server will always update + -- with actual result shortly. - sound = { - -- Definition of item sounds to be played at various events. - -- All fields in this table are optional. + node_dig_prediction = "air", + -- if "", no prediction is made. + -- if "air", node is removed. + -- Otherwise should be name of node which the client immediately places + -- upon digging. Server will always update with actual result shortly. - breaks = , - -- When tool breaks due to wear. Ignored for non-tools + sound = { + -- Definition of item sounds to be played at various events. + -- All fields in this table are optional. - eat = , - -- When item is eaten with `minetest.do_item_eat` + breaks = , + -- When tool breaks due to wear. Ignored for non-tools - punch_use = , - -- When item is used with the 'punch/mine' key pointing at a node or entity + eat = , + -- When item is eaten with `minetest.do_item_eat` - punch_use_air = , - -- When item is used with the 'punch/mine' key pointing at nothing (air) - }, + punch_use = , + -- When item is used with the 'punch/mine' key pointing at a node or entity - on_place = function(itemstack, placer, pointed_thing), - -- When the 'place' key was pressed with the item in hand - -- and a node was pointed at. - -- Shall place item and return the leftover itemstack - -- or nil to not modify the inventory. - -- The placer may be any ObjectRef or nil. - -- default: minetest.item_place + punch_use_air = , + -- When item is used with the 'punch/mine' key pointing at nothing (air) + }, - on_secondary_use = function(itemstack, user, pointed_thing), - -- Same as on_place but called when not pointing at a node. - -- Function must return either nil if inventory shall not be modified, - -- or an itemstack to replace the original itemstack. - -- The user may be any ObjectRef or nil. - -- default: nil + on_place = function(itemstack, placer, pointed_thing), + -- When the 'place' key was pressed with the item in hand + -- and a node was pointed at. + -- Shall place item and return the leftover itemstack + -- or nil to not modify the inventory. + -- The placer may be any ObjectRef or nil. + -- default: minetest.item_place - on_drop = function(itemstack, dropper, pos), - -- Shall drop item and return the leftover itemstack. - -- The dropper may be any ObjectRef or nil. - -- default: minetest.item_drop + on_secondary_use = function(itemstack, user, pointed_thing), + -- Same as on_place but called when not pointing at a node. + -- Function must return either nil if inventory shall not be modified, + -- or an itemstack to replace the original itemstack. + -- The user may be any ObjectRef or nil. + -- default: nil - on_pickup = function(itemstack, picker, pointed_thing, time_from_last_punch, ...), - -- Called when a dropped item is punched by a player. - -- Shall pick-up the item and return the leftover itemstack or nil to not - -- modify the dropped item. - -- Parameters: - -- * `itemstack`: The `ItemStack` to be picked up. - -- * `picker`: Any `ObjectRef` or `nil`. - -- * `pointed_thing` (optional): The dropped item (a `"__builtin:item"` - -- luaentity) as `type="object"` `pointed_thing`. - -- * `time_from_last_punch, ...` (optional): Other parameters from - -- `luaentity:on_punch`. - -- default: `minetest.item_pickup` + on_drop = function(itemstack, dropper, pos), + -- Shall drop item and return the leftover itemstack. + -- The dropper may be any ObjectRef or nil. + -- default: minetest.item_drop - on_use = function(itemstack, user, pointed_thing), - -- default: nil - -- When user pressed the 'punch/mine' key with the item in hand. - -- Function must return either nil if inventory shall not be modified, - -- or an itemstack to replace the original itemstack. - -- e.g. itemstack:take_item(); return itemstack - -- Otherwise, the function is free to do what it wants. - -- The user may be any ObjectRef or nil. - -- The default functions handle regular use cases. + on_pickup = function(itemstack, picker, pointed_thing, time_from_last_punch, ...), + -- Called when a dropped item is punched by a player. + -- Shall pick-up the item and return the leftover itemstack or nil to not + -- modify the dropped item. + -- Parameters: + -- * `itemstack`: The `ItemStack` to be picked up. + -- * `picker`: Any `ObjectRef` or `nil`. + -- * `pointed_thing` (optional): The dropped item (a `"__builtin:item"` + -- luaentity) as `type="object"` `pointed_thing`. + -- * `time_from_last_punch, ...` (optional): Other parameters from + -- `luaentity:on_punch`. + -- default: `minetest.item_pickup` - after_use = function(itemstack, user, node, digparams), - -- default: nil - -- If defined, should return an itemstack and will be called instead of - -- wearing out the item (if tool). If returns nil, does nothing. - -- If after_use doesn't exist, it is the same as: - -- function(itemstack, user, node, digparams) - -- itemstack:add_wear(digparams.wear) - -- return itemstack - -- end - -- The user may be any ObjectRef or nil. + on_use = function(itemstack, user, pointed_thing), + -- default: nil + -- When user pressed the 'punch/mine' key with the item in hand. + -- Function must return either nil if inventory shall not be modified, + -- or an itemstack to replace the original itemstack. + -- e.g. itemstack:take_item(); return itemstack + -- Otherwise, the function is free to do what it wants. + -- The user may be any ObjectRef or nil. + -- The default functions handle regular use cases. - _custom_field = whatever, - -- Add your own custom fields. By convention, all custom field names - -- should start with `_` to avoid naming collisions with future engine - -- usage. - } + after_use = function(itemstack, user, node, digparams), + -- default: nil + -- If defined, should return an itemstack and will be called instead of + -- wearing out the item (if tool). If returns nil, does nothing. + -- If after_use doesn't exist, it is the same as: + -- function(itemstack, user, node, digparams) + -- itemstack:add_wear(digparams.wear) + -- return itemstack + -- end + -- The user may be any ObjectRef or nil. + + _custom_field = whatever, + -- Add your own custom fields. By convention, all custom field names + -- should start with `_` to avoid naming collisions with future engine + -- usage. +} +``` Node definition --------------- Used by `minetest.register_node`. - { - -- +```lua +{ + -- - drawtype = "normal", -- See "Node drawtypes" + drawtype = "normal", -- See "Node drawtypes" - visual_scale = 1.0, - -- Supported for drawtypes "plantlike", "signlike", "torchlike", - -- "firelike", "mesh", "nodebox", "allfaces". - -- For plantlike and firelike, the image will start at the bottom of the - -- node. For torchlike, the image will start at the surface to which the - -- node "attaches". For the other drawtypes the image will be centered - -- on the node. + visual_scale = 1.0, + -- Supported for drawtypes "plantlike", "signlike", "torchlike", + -- "firelike", "mesh", "nodebox", "allfaces". + -- For plantlike and firelike, the image will start at the bottom of the + -- node. For torchlike, the image will start at the surface to which the + -- node "attaches". For the other drawtypes the image will be centered + -- on the node. - tiles = {tile definition 1, def2, def3, def4, def5, def6}, - -- Textures of node; +Y, -Y, +X, -X, +Z, -Z - -- List can be shortened to needed length. + tiles = {tile definition 1, def2, def3, def4, def5, def6}, + -- Textures of node; +Y, -Y, +X, -X, +Z, -Z + -- List can be shortened to needed length. - overlay_tiles = {tile definition 1, def2, def3, def4, def5, def6}, - -- Same as `tiles`, but these textures are drawn on top of the base - -- tiles. You can use this to colorize only specific parts of your - -- texture. If the texture name is an empty string, that overlay is not - -- drawn. Since such tiles are drawn twice, it is not recommended to use - -- overlays on very common nodes. + overlay_tiles = {tile definition 1, def2, def3, def4, def5, def6}, + -- Same as `tiles`, but these textures are drawn on top of the base + -- tiles. You can use this to colorize only specific parts of your + -- texture. If the texture name is an empty string, that overlay is not + -- drawn. Since such tiles are drawn twice, it is not recommended to use + -- overlays on very common nodes. - special_tiles = {tile definition 1, Tile definition 2}, - -- Special textures of node; used rarely. - -- List can be shortened to needed length. + special_tiles = {tile definition 1, Tile definition 2}, + -- Special textures of node; used rarely. + -- List can be shortened to needed length. - color = ColorSpec, - -- The node's original color will be multiplied with this color. - -- If the node has a palette, then this setting only has an effect in - -- the inventory and on the wield item. + color = ColorSpec, + -- The node's original color will be multiplied with this color. + -- If the node has a palette, then this setting only has an effect in + -- the inventory and on the wield item. - use_texture_alpha = ..., - -- Specifies how the texture's alpha channel will be used for rendering. - -- possible values: - -- * "opaque": Node is rendered opaque regardless of alpha channel - -- * "clip": A given pixel is either fully see-through or opaque - -- depending on the alpha channel being below/above 50% in value - -- * "blend": The alpha channel specifies how transparent a given pixel - -- of the rendered node is - -- The default is "opaque" for drawtypes normal, liquid and flowingliquid; - -- "clip" otherwise. - -- If set to a boolean value (deprecated): true either sets it to blend - -- or clip, false sets it to clip or opaque mode depending on the drawtype. + use_texture_alpha = ..., + -- Specifies how the texture's alpha channel will be used for rendering. + -- possible values: + -- * "opaque": Node is rendered opaque regardless of alpha channel + -- * "clip": A given pixel is either fully see-through or opaque + -- depending on the alpha channel being below/above 50% in value + -- * "blend": The alpha channel specifies how transparent a given pixel + -- of the rendered node is + -- The default is "opaque" for drawtypes normal, liquid and flowingliquid; + -- "clip" otherwise. + -- If set to a boolean value (deprecated): true either sets it to blend + -- or clip, false sets it to clip or opaque mode depending on the drawtype. - palette = "", - -- The node's `param2` is used to select a pixel from the image. - -- Pixels are arranged from left to right and from top to bottom. - -- The node's color will be multiplied with the selected pixel's color. - -- Tiles can override this behavior. - -- Only when `paramtype2` supports palettes. + palette = "", + -- The node's `param2` is used to select a pixel from the image. + -- Pixels are arranged from left to right and from top to bottom. + -- The node's color will be multiplied with the selected pixel's color. + -- Tiles can override this behavior. + -- Only when `paramtype2` supports palettes. - post_effect_color = "#00000000", - -- Screen tint if player is inside node, see "ColorSpec" + post_effect_color = "#00000000", + -- Screen tint if player is inside node, see "ColorSpec" - paramtype = "none", -- See "Nodes" + paramtype = "none", -- See "Nodes" - paramtype2 = "none", -- See "Nodes" + paramtype2 = "none", -- See "Nodes" - place_param2 = 0, - -- Value for param2 that is set when player places node + place_param2 = 0, + -- Value for param2 that is set when player places node - is_ground_content = true, - -- If false, the cave generator and dungeon generator will not carve - -- through this node. - -- Specifically, this stops mod-added nodes being removed by caves and - -- dungeons when those generate in a neighbor mapchunk and extend out - -- beyond the edge of that mapchunk. + is_ground_content = true, + -- If false, the cave generator and dungeon generator will not carve + -- through this node. + -- Specifically, this stops mod-added nodes being removed by caves and + -- dungeons when those generate in a neighbor mapchunk and extend out + -- beyond the edge of that mapchunk. - sunlight_propagates = false, - -- If true, sunlight will go infinitely through this node + sunlight_propagates = false, + -- If true, sunlight will go infinitely through this node - walkable = true, -- If true, objects collide with node + walkable = true, -- If true, objects collide with node - pointable = true, -- If true, can be pointed at + pointable = true, -- If true, can be pointed at - diggable = true, -- If false, can never be dug + diggable = true, -- If false, can never be dug - climbable = false, -- If true, can be climbed on like a ladder + climbable = false, -- If true, can be climbed on like a ladder - move_resistance = 0, - -- Slows down movement of players through this node (max. 7). - -- If this is nil, it will be equal to liquid_viscosity. - -- Note: If liquid movement physics apply to the node - -- (see `liquid_move_physics`), the movement speed will also be - -- affected by the `movement_liquid_*` settings. + move_resistance = 0, + -- Slows down movement of players through this node (max. 7). + -- If this is nil, it will be equal to liquid_viscosity. + -- Note: If liquid movement physics apply to the node + -- (see `liquid_move_physics`), the movement speed will also be + -- affected by the `movement_liquid_*` settings. - buildable_to = false, -- If true, placed nodes can replace this node + buildable_to = false, -- If true, placed nodes can replace this node - floodable = false, - -- If true, liquids flow into and replace this node. - -- Warning: making a liquid node 'floodable' will cause problems. + floodable = false, + -- If true, liquids flow into and replace this node. + -- Warning: making a liquid node 'floodable' will cause problems. - liquidtype = "none", -- specifies liquid flowing physics - -- * "none": no liquid flowing physics - -- * "source": spawns flowing liquid nodes at all 4 sides and below; - -- recommended drawtype: "liquid". - -- * "flowing": spawned from source, spawns more flowing liquid nodes - -- around it until `liquid_range` is reached; - -- will drain out without a source; - -- recommended drawtype: "flowingliquid". - -- If it's "source" or "flowing", then the - -- `liquid_alternative_*` fields _must_ be specified + liquidtype = "none", -- specifies liquid flowing physics + -- * "none": no liquid flowing physics + -- * "source": spawns flowing liquid nodes at all 4 sides and below; + -- recommended drawtype: "liquid". + -- * "flowing": spawned from source, spawns more flowing liquid nodes + -- around it until `liquid_range` is reached; + -- will drain out without a source; + -- recommended drawtype: "flowingliquid". + -- If it's "source" or "flowing", then the + -- `liquid_alternative_*` fields _must_ be specified - liquid_alternative_flowing = "", - liquid_alternative_source = "", - -- These fields may contain node names that represent the - -- flowing version (`liquid_alternative_flowing`) and - -- source version (`liquid_alternative_source`) of a liquid. - -- - -- Specifically, these fields are required if any of these is true: - -- * `liquidtype ~= "none" or - -- * `drawtype == "liquid" or - -- * `drawtype == "flowingliquid" - -- - -- Liquids consist of up to two nodes: source and flowing. - -- - -- There are two ways to define a liquid: - -- 1) Source node and flowing node. This requires both fields to be - -- specified for both nodes. - -- 2) Standalone source node (cannot flow). `liquid_alternative_source` - -- must be specified and `liquid_range` must be set to 0. - -- - -- Example: - -- liquid_alternative_flowing = "example:water_flowing", - -- liquid_alternative_source = "example:water_source", + liquid_alternative_flowing = "", + liquid_alternative_source = "", + -- These fields may contain node names that represent the + -- flowing version (`liquid_alternative_flowing`) and + -- source version (`liquid_alternative_source`) of a liquid. + -- + -- Specifically, these fields are required if any of these is true: + -- * `liquidtype ~= "none" or + -- * `drawtype == "liquid" or + -- * `drawtype == "flowingliquid" + -- + -- Liquids consist of up to two nodes: source and flowing. + -- + -- There are two ways to define a liquid: + -- 1) Source node and flowing node. This requires both fields to be + -- specified for both nodes. + -- 2) Standalone source node (cannot flow). `liquid_alternative_source` + -- must be specified and `liquid_range` must be set to 0. + -- + -- Example: + -- liquid_alternative_flowing = "example:water_flowing", + -- liquid_alternative_source = "example:water_source", - liquid_viscosity = 0, - -- Controls speed at which the liquid spreads/flows (max. 7). - -- 0 is fastest, 7 is slowest. - -- By default, this also slows down movement of players inside the node - -- (can be overridden using `move_resistance`) + liquid_viscosity = 0, + -- Controls speed at which the liquid spreads/flows (max. 7). + -- 0 is fastest, 7 is slowest. + -- By default, this also slows down movement of players inside the node + -- (can be overridden using `move_resistance`) - liquid_renewable = true, - -- If true, a new liquid source can be created by placing two or more - -- sources nearby + liquid_renewable = true, + -- If true, a new liquid source can be created by placing two or more + -- sources nearby - liquid_move_physics = nil, -- specifies movement physics if inside node - -- * false: No liquid movement physics apply. - -- * true: Enables liquid movement physics. Enables things like - -- ability to "swim" up/down, sinking slowly if not moving, - -- smoother speed change when falling into, etc. The `movement_liquid_*` - -- settings apply. - -- * nil: Will be treated as true if `liquidtype ~= "none"` - -- and as false otherwise. + liquid_move_physics = nil, -- specifies movement physics if inside node + -- * false: No liquid movement physics apply. + -- * true: Enables liquid movement physics. Enables things like + -- ability to "swim" up/down, sinking slowly if not moving, + -- smoother speed change when falling into, etc. The `movement_liquid_*` + -- settings apply. + -- * nil: Will be treated as true if `liquidtype ~= "none"` + -- and as false otherwise. - leveled = 0, - -- Only valid for "nodebox" drawtype with 'type = "leveled"'. - -- Allows defining the nodebox height without using param2. - -- The nodebox height is 'leveled' / 64 nodes. - -- The maximum value of 'leveled' is `leveled_max`. + leveled = 0, + -- Only valid for "nodebox" drawtype with 'type = "leveled"'. + -- Allows defining the nodebox height without using param2. + -- The nodebox height is 'leveled' / 64 nodes. + -- The maximum value of 'leveled' is `leveled_max`. - leveled_max = 127, - -- Maximum value for `leveled` (0-127), enforced in - -- `minetest.set_node_level` and `minetest.add_node_level`. - -- Values above 124 might causes collision detection issues. + leveled_max = 127, + -- Maximum value for `leveled` (0-127), enforced in + -- `minetest.set_node_level` and `minetest.add_node_level`. + -- Values above 124 might causes collision detection issues. - liquid_range = 8, - -- Maximum distance that flowing liquid nodes can spread around - -- source on flat land; - -- maximum = 8; set to 0 to disable liquid flow + liquid_range = 8, + -- Maximum distance that flowing liquid nodes can spread around + -- source on flat land; + -- maximum = 8; set to 0 to disable liquid flow - drowning = 0, - -- Player will take this amount of damage if no bubbles are left + drowning = 0, + -- Player will take this amount of damage if no bubbles are left - damage_per_second = 0, - -- If player is inside node, this damage is caused + damage_per_second = 0, + -- If player is inside node, this damage is caused - node_box = {type = "regular"}, -- See "Node boxes" + node_box = {type = "regular"}, -- See "Node boxes" - connects_to = {}, - -- Used for nodebox nodes with the type == "connected". - -- Specifies to what neighboring nodes connections will be drawn. - -- e.g. `{"group:fence", "default:wood"}` or `"default:stone"` + connects_to = {}, + -- Used for nodebox nodes with the type == "connected". + -- Specifies to what neighboring nodes connections will be drawn. + -- e.g. `{"group:fence", "default:wood"}` or `"default:stone"` - connect_sides = {}, - -- Tells connected nodebox nodes to connect only to these sides of this - -- node. possible: "top", "bottom", "front", "left", "back", "right" + connect_sides = {}, + -- Tells connected nodebox nodes to connect only to these sides of this + -- node. possible: "top", "bottom", "front", "left", "back", "right" - mesh = "", - -- File name of mesh when using "mesh" drawtype + mesh = "", + -- File name of mesh when using "mesh" drawtype - selection_box = { - -- see [Node boxes] for possibilities - }, - -- Custom selection box definition. Multiple boxes can be defined. - -- If "nodebox" drawtype is used and selection_box is nil, then node_box - -- definition is used for the selection box. + selection_box = { + -- see [Node boxes] for possibilities + }, + -- Custom selection box definition. Multiple boxes can be defined. + -- If "nodebox" drawtype is used and selection_box is nil, then node_box + -- definition is used for the selection box. - collision_box = { - -- see [Node boxes] for possibilities - }, - -- Custom collision box definition. Multiple boxes can be defined. - -- If "nodebox" drawtype is used and collision_box is nil, then node_box - -- definition is used for the collision box. + collision_box = { + -- see [Node boxes] for possibilities + }, + -- Custom collision box definition. Multiple boxes can be defined. + -- If "nodebox" drawtype is used and collision_box is nil, then node_box + -- definition is used for the collision box. - -- Support maps made in and before January 2012 - legacy_facedir_simple = false, - legacy_wallmounted = false, + -- Support maps made in and before January 2012 + legacy_facedir_simple = false, + legacy_wallmounted = false, - waving = 0, - -- Valid for drawtypes: - -- mesh, nodebox, plantlike, allfaces_optional, liquid, flowingliquid. - -- 1 - wave node like plants (node top moves side-to-side, bottom is fixed) - -- 2 - wave node like leaves (whole node moves side-to-side) - -- 3 - wave node like liquids (whole node moves up and down) - -- Not all models will properly wave. - -- plantlike drawtype can only wave like plants. - -- allfaces_optional drawtype can only wave like leaves. - -- liquid, flowingliquid drawtypes can only wave like liquids. + waving = 0, + -- Valid for drawtypes: + -- mesh, nodebox, plantlike, allfaces_optional, liquid, flowingliquid. + -- 1 - wave node like plants (node top moves side-to-side, bottom is fixed) + -- 2 - wave node like leaves (whole node moves side-to-side) + -- 3 - wave node like liquids (whole node moves up and down) + -- Not all models will properly wave. + -- plantlike drawtype can only wave like plants. + -- allfaces_optional drawtype can only wave like leaves. + -- liquid, flowingliquid drawtypes can only wave like liquids. - sounds = { - -- Definition of node sounds to be played at various events. - -- All fields in this table are optional. + sounds = { + -- Definition of node sounds to be played at various events. + -- All fields in this table are optional. - footstep = , - -- If walkable, played when object walks on it. If node is - -- climbable or a liquid, played when object moves through it + footstep = , + -- If walkable, played when object walks on it. If node is + -- climbable or a liquid, played when object moves through it - dig = or "__group", - -- While digging node. - -- If `"__group"`, then the sound will be - -- `{name = "default_dig_", gain = 0.5}` , where `` is the - -- name of the item's digging group with the fastest digging time. - -- In case of a tie, one of the sounds will be played (but we - -- cannot predict which one) - -- Default value: `"__group"` + dig = or "__group", + -- While digging node. + -- If `"__group"`, then the sound will be + -- `{name = "default_dig_", gain = 0.5}` , where `` is the + -- name of the item's digging group with the fastest digging time. + -- In case of a tie, one of the sounds will be played (but we + -- cannot predict which one) + -- Default value: `"__group"` - dug = , - -- Node was dug + dug = , + -- Node was dug - place = , - -- Node was placed. Also played after falling + place = , + -- Node was placed. Also played after falling - place_failed = , - -- When node placement failed. - -- Note: This happens if the _built-in_ node placement failed. - -- This sound will still be played if the node is placed in the - -- `on_place` callback manually. + place_failed = , + -- When node placement failed. + -- Note: This happens if the _built-in_ node placement failed. + -- This sound will still be played if the node is placed in the + -- `on_place` callback manually. - fall = , - -- When node starts to fall or is detached - }, + fall = , + -- When node starts to fall or is detached + }, - drop = "", - -- Name of dropped item when dug. - -- Default dropped item is the node itself. + drop = "", + -- Name of dropped item when dug. + -- Default dropped item is the node itself. - -- Using a table allows multiple items, drop chances and item filtering: - drop = { - max_items = 1, - -- Maximum number of item lists to drop. - -- The entries in 'items' are processed in order. For each: - -- Item filtering is applied, chance of drop is applied, if both are - -- successful the entire item list is dropped. - -- Entry processing continues until the number of dropped item lists - -- equals 'max_items'. - -- Therefore, entries should progress from low to high drop chance. - items = { - -- Examples: - { - -- 1 in 1000 chance of dropping a diamond. - -- Default rarity is '1'. - rarity = 1000, - items = {"default:diamond"}, - }, - { - -- Only drop if using an item whose name is identical to one - -- of these. - tools = {"default:shovel_mese", "default:shovel_diamond"}, - rarity = 5, - items = {"default:dirt"}, - -- Whether all items in the dropped item list inherit the - -- hardware coloring palette color from the dug node. - -- Default is 'false'. - inherit_color = true, - }, - { - -- Only drop if using an item whose name contains - -- "default:shovel_" (this item filtering by string matching - -- is deprecated, use tool_groups instead). - tools = {"~default:shovel_"}, - rarity = 2, - -- The item list dropped. - items = {"default:sand", "default:desert_sand"}, - }, - { - -- Only drop if using an item in the "magicwand" group, or - -- an item that is in both the "pickaxe" and the "lucky" - -- groups. - tool_groups = { - "magicwand", - {"pickaxe", "lucky"} - }, - items = {"default:coal_lump"}, + -- Using a table allows multiple items, drop chances and item filtering: + drop = { + max_items = 1, + -- Maximum number of item lists to drop. + -- The entries in 'items' are processed in order. For each: + -- Item filtering is applied, chance of drop is applied, if both are + -- successful the entire item list is dropped. + -- Entry processing continues until the number of dropped item lists + -- equals 'max_items'. + -- Therefore, entries should progress from low to high drop chance. + items = { + -- Examples: + { + -- 1 in 1000 chance of dropping a diamond. + -- Default rarity is '1'. + rarity = 1000, + items = {"default:diamond"}, + }, + { + -- Only drop if using an item whose name is identical to one + -- of these. + tools = {"default:shovel_mese", "default:shovel_diamond"}, + rarity = 5, + items = {"default:dirt"}, + -- Whether all items in the dropped item list inherit the + -- hardware coloring palette color from the dug node. + -- Default is 'false'. + inherit_color = true, + }, + { + -- Only drop if using an item whose name contains + -- "default:shovel_" (this item filtering by string matching + -- is deprecated, use tool_groups instead). + tools = {"~default:shovel_"}, + rarity = 2, + -- The item list dropped. + items = {"default:sand", "default:desert_sand"}, + }, + { + -- Only drop if using an item in the "magicwand" group, or + -- an item that is in both the "pickaxe" and the "lucky" + -- groups. + tool_groups = { + "magicwand", + {"pickaxe", "lucky"} }, + items = {"default:coal_lump"}, }, }, + }, - on_construct = function(pos), - -- Node constructor; called after adding node. - -- Can set up metadata and stuff like that. - -- Not called for bulk node placement (i.e. schematics and VoxelManip). - -- Note: Within an on_construct callback, minetest.set_node can cause an - -- infinite loop if it invokes the same callback. - -- Consider using minetest.swap_node instead. - -- default: nil + on_construct = function(pos), + -- Node constructor; called after adding node. + -- Can set up metadata and stuff like that. + -- Not called for bulk node placement (i.e. schematics and VoxelManip). + -- Note: Within an on_construct callback, minetest.set_node can cause an + -- infinite loop if it invokes the same callback. + -- Consider using minetest.swap_node instead. + -- default: nil - on_destruct = function(pos), - -- Node destructor; called before removing node. - -- Not called for bulk node placement. - -- default: nil + on_destruct = function(pos), + -- Node destructor; called before removing node. + -- Not called for bulk node placement. + -- default: nil - after_destruct = function(pos, oldnode), - -- Node destructor; called after removing node. - -- Not called for bulk node placement. - -- default: nil + after_destruct = function(pos, oldnode), + -- Node destructor; called after removing node. + -- Not called for bulk node placement. + -- default: nil - on_flood = function(pos, oldnode, newnode), - -- Called when a liquid (newnode) is about to flood oldnode, if it has - -- `floodable = true` in the nodedef. Not called for bulk node placement - -- (i.e. schematics and VoxelManip) or air nodes. If return true the - -- node is not flooded, but on_flood callback will most likely be called - -- over and over again every liquid update interval. - -- Default: nil - -- Warning: making a liquid node 'floodable' will cause problems. + on_flood = function(pos, oldnode, newnode), + -- Called when a liquid (newnode) is about to flood oldnode, if it has + -- `floodable = true` in the nodedef. Not called for bulk node placement + -- (i.e. schematics and VoxelManip) or air nodes. If return true the + -- node is not flooded, but on_flood callback will most likely be called + -- over and over again every liquid update interval. + -- Default: nil + -- Warning: making a liquid node 'floodable' will cause problems. - preserve_metadata = function(pos, oldnode, oldmeta, drops), - -- Called when `oldnode` is about be converted to an item, but before the - -- node is deleted from the world or the drops are added. This is - -- generally the result of either the node being dug or an attached node - -- becoming detached. - -- * `pos`: node position - -- * `oldnode`: node table of node before it was deleted - -- * `oldmeta`: metadata of node before it was deleted, as a metadata table - -- * `drops`: a table of `ItemStack`s, so any metadata to be preserved can - -- be added directly to one or more of the dropped items. See - -- "ItemStackMetaRef". - -- default: `nil` + preserve_metadata = function(pos, oldnode, oldmeta, drops), + -- Called when `oldnode` is about be converted to an item, but before the + -- node is deleted from the world or the drops are added. This is + -- generally the result of either the node being dug or an attached node + -- becoming detached. + -- * `pos`: node position + -- * `oldnode`: node table of node before it was deleted + -- * `oldmeta`: metadata of node before it was deleted, as a metadata table + -- * `drops`: a table of `ItemStack`s, so any metadata to be preserved can + -- be added directly to one or more of the dropped items. See + -- "ItemStackMetaRef". + -- default: `nil` - after_place_node = function(pos, placer, itemstack, pointed_thing), - -- Called after constructing node when node was placed using - -- minetest.item_place_node / minetest.place_node. - -- If return true no item is taken from itemstack. - -- `placer` may be any valid ObjectRef or nil. - -- default: nil + after_place_node = function(pos, placer, itemstack, pointed_thing), + -- Called after constructing node when node was placed using + -- minetest.item_place_node / minetest.place_node. + -- If return true no item is taken from itemstack. + -- `placer` may be any valid ObjectRef or nil. + -- default: nil - after_dig_node = function(pos, oldnode, oldmetadata, digger), - -- Called after destructing the node when node was dug using - -- `minetest.node_dig` / `minetest.dig_node`. - -- * `pos`: node position - -- * `oldnode`: node table of node before it was dug - -- * `oldmetadata`: metadata of node before it was dug, - -- as a metadata table - -- * `digger`: ObjectRef of digger - -- default: nil + after_dig_node = function(pos, oldnode, oldmetadata, digger), + -- Called after destructing the node when node was dug using + -- `minetest.node_dig` / `minetest.dig_node`. + -- * `pos`: node position + -- * `oldnode`: node table of node before it was dug + -- * `oldmetadata`: metadata of node before it was dug, + -- as a metadata table + -- * `digger`: ObjectRef of digger + -- default: nil - can_dig = function(pos, [player]), - -- Returns true if node can be dug, or false if not. - -- default: nil + can_dig = function(pos, [player]), + -- Returns true if node can be dug, or false if not. + -- default: nil - on_punch = function(pos, node, puncher, pointed_thing), - -- default: minetest.node_punch - -- Called when puncher (an ObjectRef) punches the node at pos. - -- By default calls minetest.register_on_punchnode callbacks. + on_punch = function(pos, node, puncher, pointed_thing), + -- default: minetest.node_punch + -- Called when puncher (an ObjectRef) punches the node at pos. + -- By default calls minetest.register_on_punchnode callbacks. - on_rightclick = function(pos, node, clicker, itemstack, pointed_thing), - -- default: nil - -- Called when clicker (an ObjectRef) used the 'place/build' key - -- (not necessarily an actual rightclick) - -- while pointing at the node at pos with 'node' being the node table. - -- itemstack will hold clicker's wielded item. - -- Shall return the leftover itemstack. - -- Note: pointed_thing can be nil, if a mod calls this function. - -- This function does not get triggered by clients <=0.4.16 if the - -- "formspec" node metadata field is set. + on_rightclick = function(pos, node, clicker, itemstack, pointed_thing), + -- default: nil + -- Called when clicker (an ObjectRef) used the 'place/build' key + -- (not necessarily an actual rightclick) + -- while pointing at the node at pos with 'node' being the node table. + -- itemstack will hold clicker's wielded item. + -- Shall return the leftover itemstack. + -- Note: pointed_thing can be nil, if a mod calls this function. + -- This function does not get triggered by clients <=0.4.16 if the + -- "formspec" node metadata field is set. - on_dig = function(pos, node, digger), - -- default: minetest.node_dig - -- By default checks privileges, wears out item (if tool) and removes node. - -- return true if the node was dug successfully, false otherwise. - -- Deprecated: returning nil is the same as returning true. + on_dig = function(pos, node, digger), + -- default: minetest.node_dig + -- By default checks privileges, wears out item (if tool) and removes node. + -- return true if the node was dug successfully, false otherwise. + -- Deprecated: returning nil is the same as returning true. - on_timer = function(pos, elapsed), - -- default: nil - -- called by NodeTimers, see minetest.get_node_timer and NodeTimerRef. - -- elapsed is the total time passed since the timer was started. - -- return true to run the timer for another cycle with the same timeout - -- value. + on_timer = function(pos, elapsed), + -- default: nil + -- called by NodeTimers, see minetest.get_node_timer and NodeTimerRef. + -- elapsed is the total time passed since the timer was started. + -- return true to run the timer for another cycle with the same timeout + -- value. - on_receive_fields = function(pos, formname, fields, sender), - -- fields = {name1 = value1, name2 = value2, ...} - -- Called when an UI form (e.g. sign text input) returns data. - -- See minetest.register_on_player_receive_fields for more info. - -- default: nil + on_receive_fields = function(pos, formname, fields, sender), + -- fields = {name1 = value1, name2 = value2, ...} + -- Called when an UI form (e.g. sign text input) returns data. + -- See minetest.register_on_player_receive_fields for more info. + -- default: nil - allow_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player), - -- Called when a player wants to move items inside the inventory. - -- Return value: number of items allowed to move. + allow_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player), + -- Called when a player wants to move items inside the inventory. + -- Return value: number of items allowed to move. - allow_metadata_inventory_put = function(pos, listname, index, stack, player), - -- 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. + allow_metadata_inventory_put = function(pos, listname, index, stack, player), + -- 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. - allow_metadata_inventory_take = function(pos, listname, index, stack, player), - -- 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. + allow_metadata_inventory_take = function(pos, listname, index, stack, player), + -- 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. - on_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player), - on_metadata_inventory_put = function(pos, listname, index, stack, player), - on_metadata_inventory_take = function(pos, listname, index, stack, player), - -- Called after the actual action has happened, according to what was - -- allowed. - -- No return value. + on_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player), + on_metadata_inventory_put = function(pos, listname, index, stack, player), + on_metadata_inventory_take = function(pos, listname, index, stack, player), + -- Called after the actual action has happened, according to what was + -- allowed. + -- No return value. - on_blast = function(pos, intensity), - -- intensity: 1.0 = mid range of regular TNT. - -- If defined, called when an explosion touches the node, instead of - -- removing the node. + on_blast = function(pos, intensity), + -- intensity: 1.0 = mid range of regular TNT. + -- If defined, called when an explosion touches the node, instead of + -- removing the node. - mod_origin = "modname", - -- stores which mod actually registered a node - -- If the source could not be determined it contains "??" - -- Useful for getting which mod truly registered something - -- example: if a node is registered as ":othermodname:nodename", - -- nodename will show "othermodname", but mod_origin will say "modname" - } + mod_origin = "modname", + -- stores which mod actually registered a node + -- If the source could not be determined it contains "??" + -- Useful for getting which mod truly registered something + -- example: if a node is registered as ":othermodname:nodename", + -- nodename will show "othermodname", but mod_origin will say "modname" +} +``` Crafting recipes ---------------- @@ -8852,85 +8960,93 @@ Parameters: A typical shaped recipe: - -- Stone pickaxe - { - output = "example:stone_pickaxe", - -- A 3x3 recipe which needs 3 stone in the 1st row, - -- and 1 stick in the horizontal middle in each of the 2nd and 3nd row. - -- The 4 remaining slots have to be empty. - recipe = { - {"example:stone", "example:stone", "example:stone"}, -- row 1 - {"", "example:stick", "" }, -- row 2 - {"", "example:stick", "" }, -- row 3 - -- ^ column 1 ^ column 2 ^ column 3 - }, - -- There is no replacements table, so every input item - -- will be consumed. - } +```lua +-- Stone pickaxe +{ + output = "example:stone_pickaxe", + -- A 3x3 recipe which needs 3 stone in the 1st row, + -- and 1 stick in the horizontal middle in each of the 2nd and 3nd row. + -- The 4 remaining slots have to be empty. + recipe = { + {"example:stone", "example:stone", "example:stone"}, -- row 1 + {"", "example:stick", "" }, -- row 2 + {"", "example:stick", "" }, -- row 3 + -- ^ column 1 ^ column 2 ^ column 3 + }, + -- There is no replacements table, so every input item + -- will be consumed. +} +``` Simple replacement example: - -- Wet sponge - { - output = "example:wet_sponge", - -- 1x2 recipe with a water bucket above a dry sponge - recipe = { - {"example:water_bucket"}, - {"example:dry_sponge"}, - }, - -- When the wet sponge is crafted, the water bucket - -- in the input slot is replaced with an empty - -- bucket - replacements = { - {"example:water_bucket", "example:empty_bucket"}, - }, - } +```lua +-- Wet sponge +{ + output = "example:wet_sponge", + -- 1x2 recipe with a water bucket above a dry sponge + recipe = { + {"example:water_bucket"}, + {"example:dry_sponge"}, + }, + -- When the wet sponge is crafted, the water bucket + -- in the input slot is replaced with an empty + -- bucket + replacements = { + {"example:water_bucket", "example:empty_bucket"}, + }, +} +``` Complex replacement example 1: - -- Very wet sponge - { - output = "example:very_wet_sponge", - -- 3x3 recipe with a wet sponge in the center - -- and 4 water buckets around it - recipe = { - {"","example:water_bucket",""}, - {"example:water_bucket","example:wet_sponge","example:water_bucket"}, - {"","example:water_bucket",""}, - }, - -- When the wet sponge is crafted, all water buckets - -- in the input slot become empty - replacements = { - -- Without these repetitions, only the first - -- water bucket would be replaced. - {"example:water_bucket", "example:empty_bucket"}, - {"example:water_bucket", "example:empty_bucket"}, - {"example:water_bucket", "example:empty_bucket"}, - {"example:water_bucket", "example:empty_bucket"}, - }, - } +```lua +-- Very wet sponge +{ + output = "example:very_wet_sponge", + -- 3x3 recipe with a wet sponge in the center + -- and 4 water buckets around it + recipe = { + {"","example:water_bucket",""}, + {"example:water_bucket","example:wet_sponge","example:water_bucket"}, + {"","example:water_bucket",""}, + }, + -- When the wet sponge is crafted, all water buckets + -- in the input slot become empty + replacements = { + -- Without these repetitions, only the first + -- water bucket would be replaced. + {"example:water_bucket", "example:empty_bucket"}, + {"example:water_bucket", "example:empty_bucket"}, + {"example:water_bucket", "example:empty_bucket"}, + {"example:water_bucket", "example:empty_bucket"}, + }, +} +``` Complex replacement example 2: - -- Magic book: - -- 3 magic orbs + 1 book crafts a magic book, - -- and the orbs will be replaced with 3 different runes. - { - output = "example:magic_book", - -- 3x2 recipe - recipe = { - -- 3 items in the group `magic_orb` on top of a book in the middle - {"group:magic_orb", "group:magic_orb", "group:magic_orb"}, - {"", "example:book", ""}, - }, - -- When the book is crafted, the 3 magic orbs will be turned into - -- 3 runes: ice rune, earth rune and fire rune (from left to right) - replacements = { - {"group:magic_orb", "example:ice_rune"}, - {"group:magic_orb", "example:earth_rune"}, - {"group:magic_orb", "example:fire_rune"}, - }, - } +```lua +-- Magic book: +-- 3 magic orbs + 1 book crafts a magic book, +-- and the orbs will be replaced with 3 different runes. +{ + output = "example:magic_book", + -- 3x2 recipe + recipe = { + -- 3 items in the group `magic_orb` on top of a book in the middle + {"group:magic_orb", "group:magic_orb", "group:magic_orb"}, + {"", "example:book", ""}, + }, + -- When the book is crafted, the 3 magic orbs will be turned into + -- 3 runes: ice rune, earth rune and fire rune (from left to right) + replacements = { + {"group:magic_orb", "example:ice_rune"}, + {"group:magic_orb", "example:earth_rune"}, + {"group:magic_orb", "example:fire_rune"}, + }, +} +``` ### Shapeless @@ -8949,17 +9065,19 @@ Parameters: #### Example - { - -- Craft a mushroom stew from a bowl, a brown mushroom and a red mushroom - -- (no matter where in the input grid the items are placed) - type = "shapeless", - output = "example:mushroom_stew", - recipe = { - "example:bowl", - "example:mushroom_brown", - "example:mushroom_red", - }, - } +```lua +{ + -- Craft a mushroom stew from a bowl, a brown mushroom and a red mushroom + -- (no matter where in the input grid the items are placed) + type = "shapeless", + output = "example:mushroom_stew", + recipe = { + "example:bowl", + "example:mushroom_brown", + "example:mushroom_red", + }, +} +``` ### Tool repair @@ -9015,12 +9133,14 @@ cases, e.g. for a super furnace that cooks items twice as fast. Cooking sand to glass in 3 seconds: - { - type = "cooking", - output = "example:glass", - recipe = "example:sand", - cooktime = 3.0, - } +```lua +{ + type = "cooking", + output = "example:glass", + recipe = "example:sand", + cooktime = 3.0, +} +``` ### Fuel @@ -9050,21 +9170,25 @@ long. Coal lump with a burntime of 20 seconds. Will be consumed when used. - { - type = "fuel", - recipe = "example:coal_lump", - burntime = 20.0, - } +```lua +{ + type = "fuel", + recipe = "example:coal_lump", + burntime = 20.0, +} +``` Lava bucket with a burn time of 60 seconds. Will become an empty bucket if used: - { - type = "fuel", - recipe = "example:lava_bucket", - burntime = 60.0, - replacements = {{"example:lava_bucket", "example:empty_bucket"}}, - } +```lua +{ + type = "fuel", + recipe = "example:lava_bucket", + burntime = 60.0, + replacements = {{"example:lava_bucket", "example:empty_bucket"}}, +} +``` Ore definition -------------- @@ -9073,103 +9197,105 @@ Used by `minetest.register_ore`. See [Ores] section above for essential information. - { - ore_type = "", - -- Supported: "scatter", "sheet", "puff", "blob", "vein", "stratum" +```lua +{ + ore_type = "", + -- Supported: "scatter", "sheet", "puff", "blob", "vein", "stratum" - ore = "", - -- Ore node to place + ore = "", + -- Ore node to place - ore_param2 = 0, - -- Param2 to set for ore (e.g. facedir rotation) + ore_param2 = 0, + -- Param2 to set for ore (e.g. facedir rotation) - wherein = "", - -- Node to place ore in. Multiple are possible by passing a list. + wherein = "", + -- Node to place ore in. Multiple are possible by passing a list. - clust_scarcity = 8 * 8 * 8, - -- Ore has a 1 out of clust_scarcity chance of spawning in a node. - -- If the desired average distance between ores is 'd', set this to - -- d * d * d. + clust_scarcity = 8 * 8 * 8, + -- Ore has a 1 out of clust_scarcity chance of spawning in a node. + -- If the desired average distance between ores is 'd', set this to + -- d * d * d. - clust_num_ores = 8, - -- Number of ores in a cluster + clust_num_ores = 8, + -- Number of ores in a cluster - clust_size = 3, - -- Size of the bounding box of the cluster. - -- In this example, there is a 3 * 3 * 3 cluster where 8 out of the 27 - -- nodes are coal ore. + clust_size = 3, + -- Size of the bounding box of the cluster. + -- In this example, there is a 3 * 3 * 3 cluster where 8 out of the 27 + -- nodes are coal ore. - y_min = -31000, - y_max = 31000, - -- Lower and upper limits for ore (inclusive) + y_min = -31000, + y_max = 31000, + -- Lower and upper limits for ore (inclusive) - flags = "", - -- Attributes for the ore generation, see 'Ore attributes' section above + flags = "", + -- Attributes for the ore generation, see 'Ore attributes' section above - noise_threshold = 0, - -- If noise is above this threshold, ore is placed. Not needed for a - -- uniform distribution. + noise_threshold = 0, + -- If noise is above this threshold, ore is placed. Not needed for a + -- uniform distribution. - noise_params = { - offset = 0, - scale = 1, - spread = {x = 100, y = 100, z = 100}, - seed = 23, - octaves = 3, - persistence = 0.7 - }, - -- NoiseParams structure describing one of the perlin noises used for - -- ore distribution. - -- Needed by "sheet", "puff", "blob" and "vein" ores. - -- Omit from "scatter" ore for a uniform ore distribution. - -- Omit from "stratum" ore for a simple horizontal strata from y_min to - -- y_max. + noise_params = { + offset = 0, + scale = 1, + spread = {x = 100, y = 100, z = 100}, + seed = 23, + octaves = 3, + persistence = 0.7 + }, + -- NoiseParams structure describing one of the perlin noises used for + -- ore distribution. + -- Needed by "sheet", "puff", "blob" and "vein" ores. + -- Omit from "scatter" ore for a uniform ore distribution. + -- Omit from "stratum" ore for a simple horizontal strata from y_min to + -- y_max. - biomes = {"desert", "rainforest"}, - -- List of biomes in which this ore occurs. - -- Occurs in all biomes if this is omitted, and ignored if the Mapgen - -- being used does not support biomes. - -- Can be a list of (or a single) biome names, IDs, or definitions. + biomes = {"desert", "rainforest"}, + -- List of biomes in which this ore occurs. + -- Occurs in all biomes if this is omitted, and ignored if the Mapgen + -- being used does not support biomes. + -- Can be a list of (or a single) biome names, IDs, or definitions. - -- Type-specific parameters + -- Type-specific parameters - -- "sheet" - column_height_min = 1, - column_height_max = 16, - column_midpoint_factor = 0.5, + -- "sheet" + column_height_min = 1, + column_height_max = 16, + column_midpoint_factor = 0.5, - -- "puff" - np_puff_top = { - offset = 4, - scale = 2, - spread = {x = 100, y = 100, z = 100}, - seed = 47, - octaves = 3, - persistence = 0.7 - }, - np_puff_bottom = { - offset = 4, - scale = 2, - spread = {x = 100, y = 100, z = 100}, - seed = 11, - octaves = 3, - persistence = 0.7 - }, + -- "puff" + np_puff_top = { + offset = 4, + scale = 2, + spread = {x = 100, y = 100, z = 100}, + seed = 47, + octaves = 3, + persistence = 0.7 + }, + np_puff_bottom = { + offset = 4, + scale = 2, + spread = {x = 100, y = 100, z = 100}, + seed = 11, + octaves = 3, + persistence = 0.7 + }, - -- "vein" - random_factor = 1.0, + -- "vein" + random_factor = 1.0, - -- "stratum" - np_stratum_thickness = { - offset = 8, - scale = 4, - spread = {x = 100, y = 100, z = 100}, - seed = 17, - octaves = 3, - persistence = 0.7 - }, - stratum_thickness = 8, -- only used if no noise defined - } + -- "stratum" + np_stratum_thickness = { + offset = 8, + scale = 4, + spread = {x = 100, y = 100, z = 100}, + seed = 17, + octaves = 3, + persistence = 0.7 + }, + stratum_thickness = 8, -- only used if no noise defined +} +``` Biome definition ---------------- @@ -9180,245 +9306,249 @@ 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. - { - name = "tundra", +```lua +{ + name = "tundra", - node_dust = "default:snow", - -- Node dropped onto upper surface after all else is generated + node_dust = "default:snow", + -- Node dropped onto upper surface after all else is generated - node_top = "default:dirt_with_snow", - depth_top = 1, - -- Node forming surface layer of biome and thickness of this layer + node_top = "default:dirt_with_snow", + depth_top = 1, + -- Node forming surface layer of biome and thickness of this layer - node_filler = "default:permafrost", - depth_filler = 3, - -- Node forming lower layer of biome and thickness of this layer + node_filler = "default:permafrost", + depth_filler = 3, + -- Node forming lower layer of biome and thickness of this layer - node_stone = "default:bluestone", - -- Node that replaces all stone nodes between roughly y_min and y_max. + node_stone = "default:bluestone", + -- Node that replaces all stone nodes between roughly y_min and y_max. - node_water_top = "default:ice", - depth_water_top = 10, - -- Node forming a surface layer in seawater with the defined thickness + node_water_top = "default:ice", + depth_water_top = 10, + -- Node forming a surface layer in seawater with the defined thickness - node_water = "", - -- Node that replaces all seawater nodes not in the surface layer + node_water = "", + -- Node that replaces all seawater nodes not in the surface layer - node_river_water = "default:ice", - -- Node that replaces river water in mapgens that use - -- default:river_water + node_river_water = "default:ice", + -- Node that replaces river water in mapgens that use + -- default:river_water - node_riverbed = "default:gravel", - depth_riverbed = 2, - -- Node placed under river water and thickness of this layer + node_riverbed = "default:gravel", + depth_riverbed = 2, + -- Node placed under river water and thickness of this layer - node_cave_liquid = "default:lava_source", - node_cave_liquid = {"default:water_source", "default:lava_source"}, - -- 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 behavior of lava and water distributed using 3D noise. - -- For no cave liquid, specify "air". + node_cave_liquid = "default:lava_source", + node_cave_liquid = {"default:water_source", "default:lava_source"}, + -- 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 behavior of lava and water distributed using 3D noise. + -- For no cave liquid, specify "air". - node_dungeon = "default:cobble", - -- 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'. - -- If present, the following two nodes are also used. + node_dungeon = "default:cobble", + -- 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'. + -- If present, the following two nodes are also used. - node_dungeon_alt = "default:mossycobble", - -- Node used for randomly-distributed alternative structure nodes. - -- If alternative structure nodes are not wanted leave this absent. + node_dungeon_alt = "default:mossycobble", + -- Node used for randomly-distributed alternative structure nodes. + -- If alternative structure nodes are not wanted leave this absent. - node_dungeon_stair = "stairs:stair_cobble", - -- Node used for dungeon stairs. - -- If absent, stairs fall back to 'node_dungeon'. + node_dungeon_stair = "stairs:stair_cobble", + -- Node used for dungeon stairs. + -- If absent, stairs fall back to 'node_dungeon'. - y_max = 31000, - y_min = 1, - -- Upper and lower limits for biome. - -- Alternatively you can use xyz limits as shown below. + y_max = 31000, + y_min = 1, + -- Upper and lower limits for biome. + -- Alternatively you can use xyz limits as shown below. - max_pos = {x = 31000, y = 128, z = 31000}, - min_pos = {x = -31000, y = 9, z = -31000}, - -- xyz limits for biome, an alternative to using 'y_min' and 'y_max'. - -- Biome is limited to a cuboid defined by these positions. - -- Any x, y or z field left undefined defaults to -31000 in 'min_pos' or - -- 31000 in 'max_pos'. + max_pos = {x = 31000, y = 128, z = 31000}, + min_pos = {x = -31000, y = 9, z = -31000}, + -- xyz limits for biome, an alternative to using 'y_min' and 'y_max'. + -- Biome is limited to a cuboid defined by these positions. + -- Any x, y or z field left undefined defaults to -31000 in 'min_pos' or + -- 31000 in 'max_pos'. - vertical_blend = 8, - -- 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. + vertical_blend = 8, + -- 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. - heat_point = 0, - humidity_point = 50, - -- Characteristic temperature and humidity for the biome. - -- These values 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. - } + heat_point = 0, + humidity_point = 50, + -- Characteristic temperature and humidity for the biome. + -- These values 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. +} +``` Decoration definition --------------------- See [Decoration types]. Used by `minetest.register_decoration`. - { - deco_type = "simple", - -- Type. "simple" or "schematic" supported +```lua +{ + deco_type = "simple", + -- Type. "simple" or "schematic" supported - place_on = "default:dirt_with_grass", - -- Node (or list of nodes) that the decoration can be placed on + place_on = "default:dirt_with_grass", + -- Node (or list of nodes) that the decoration can be placed on - sidelen = 8, - -- Size of the square (X / Z) divisions of the mapchunk being generated. - -- Determines the resolution of noise variation if used. - -- If the chunk size is not evenly divisible by sidelen, sidelen is made - -- equal to the chunk size. + sidelen = 8, + -- Size of the square (X / Z) divisions of the mapchunk being generated. + -- Determines the resolution of noise variation if used. + -- If the chunk size is not evenly divisible by sidelen, sidelen is made + -- equal to the chunk size. - fill_ratio = 0.02, - -- The value determines 'decorations per surface node'. - -- Used only if noise_params is not specified. - -- If >= 10.0 complete coverage is enabled and decoration placement uses - -- a different and much faster method. + fill_ratio = 0.02, + -- The value determines 'decorations per surface node'. + -- Used only if noise_params is not specified. + -- If >= 10.0 complete coverage is enabled and decoration placement uses + -- a different and much faster method. - noise_params = { - offset = 0, - scale = 0.45, - spread = {x = 100, y = 100, z = 100}, - seed = 354, - octaves = 3, - persistence = 0.7, - lacunarity = 2.0, - flags = "absvalue" + noise_params = { + offset = 0, + scale = 0.45, + spread = {x = 100, y = 100, z = 100}, + seed = 354, + octaves = 3, + persistence = 0.7, + lacunarity = 2.0, + flags = "absvalue" + }, + -- NoiseParams structure describing the perlin noise used for decoration + -- distribution. + -- A noise value is calculated for each square division and determines + -- 'decorations per surface node' within each division. + -- If the noise value >= 10.0 complete coverage is enabled and + -- decoration placement uses a different and much faster method. + + biomes = {"Oceanside", "Hills", "Plains"}, + -- List of biomes in which this decoration occurs. Occurs in all biomes + -- if this is omitted, and ignored if the Mapgen being used does not + -- support biomes. + -- Can be a list of (or a single) biome names, IDs, or definitions. + + y_min = -31000, + y_max = 31000, + -- Lower and upper limits for decoration (inclusive). + -- These parameters refer to the Y co-ordinate of the 'place_on' node. + + spawn_by = "default:water", + -- Node (or list of nodes) that the decoration only spawns next to. + -- Checks the 8 neighboring nodes on the same Y, and also the ones + -- at Y+1, excluding both center nodes. + + num_spawn_by = 1, + -- Number of spawn_by nodes that must be surrounding the decoration + -- position to occur. + -- If absent or -1, decorations occur next to any nodes. + + flags = "liquid_surface, force_placement, all_floors, all_ceilings", + -- Flags for all decoration types. + -- "liquid_surface": Instead of placement on the highest solid surface + -- in a mapchunk column, placement is on the highest liquid surface. + -- Placement is disabled if solid nodes are found above the liquid + -- surface. + -- "force_placement": Nodes other than "air" and "ignore" are replaced + -- by the decoration. + -- "all_floors", "all_ceilings": Instead of placement on the highest + -- surface in a mapchunk the decoration is placed on all floor and/or + -- ceiling surfaces, for example in caves and dungeons. + -- Ceiling decorations act as an inversion of floor decorations so the + -- effect of 'place_offset_y' is inverted. + -- Y-slice probabilities do not function correctly for ceiling + -- schematic decorations as the behavior is unchanged. + -- If a single decoration registration has both flags the floor and + -- ceiling decorations will be aligned vertically. + + ----- Simple-type parameters + + decoration = "default:grass", + -- The node name used as the decoration. + -- If instead a list of strings, a randomly selected node from the list + -- is placed as the decoration. + + height = 1, + -- Decoration height in nodes. + -- If height_max is not 0, this is the lower limit of a randomly + -- selected height. + + height_max = 0, + -- Upper limit of the randomly selected height. + -- If absent, the parameter 'height' is used as a constant. + + param2 = 0, + -- Param2 value of decoration nodes. + -- If param2_max is not 0, this is the lower limit of a randomly + -- selected param2. + + param2_max = 0, + -- Upper limit of the randomly selected param2. + -- If absent, the parameter 'param2' is used as a constant. + + place_offset_y = 0, + -- Y offset of the decoration base node relative to the standard base + -- node position. + -- Can be positive or negative. Default is 0. + -- Effect is inverted for "all_ceilings" decorations. + -- Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer + -- to the 'place_on' node. + + ----- Schematic-type parameters + + schematic = "foobar.mts", + -- If schematic is a string, it is the filepath relative to the current + -- working directory of the specified Minetest schematic file. + -- Could also be the ID of a previously registered schematic. + + schematic = { + size = {x = 4, y = 6, z = 4}, + data = { + {name = "default:cobble", param1 = 255, param2 = 0}, + {name = "default:dirt_with_grass", param1 = 255, param2 = 0}, + {name = "air", param1 = 255, param2 = 0}, + ... }, - -- NoiseParams structure describing the perlin noise used for decoration - -- distribution. - -- A noise value is calculated for each square division and determines - -- 'decorations per surface node' within each division. - -- If the noise value >= 10.0 complete coverage is enabled and - -- decoration placement uses a different and much faster method. - - biomes = {"Oceanside", "Hills", "Plains"}, - -- List of biomes in which this decoration occurs. Occurs in all biomes - -- if this is omitted, and ignored if the Mapgen being used does not - -- support biomes. - -- Can be a list of (or a single) biome names, IDs, or definitions. - - y_min = -31000, - y_max = 31000, - -- Lower and upper limits for decoration (inclusive). - -- These parameters refer to the Y co-ordinate of the 'place_on' node. - - spawn_by = "default:water", - -- Node (or list of nodes) that the decoration only spawns next to. - -- Checks the 8 neighboring nodes on the same Y, and also the ones - -- at Y+1, excluding both center nodes. - - num_spawn_by = 1, - -- Number of spawn_by nodes that must be surrounding the decoration - -- position to occur. - -- If absent or -1, decorations occur next to any nodes. - - flags = "liquid_surface, force_placement, all_floors, all_ceilings", - -- Flags for all decoration types. - -- "liquid_surface": Instead of placement on the highest solid surface - -- in a mapchunk column, placement is on the highest liquid surface. - -- Placement is disabled if solid nodes are found above the liquid - -- surface. - -- "force_placement": Nodes other than "air" and "ignore" are replaced - -- by the decoration. - -- "all_floors", "all_ceilings": Instead of placement on the highest - -- surface in a mapchunk the decoration is placed on all floor and/or - -- ceiling surfaces, for example in caves and dungeons. - -- Ceiling decorations act as an inversion of floor decorations so the - -- effect of 'place_offset_y' is inverted. - -- Y-slice probabilities do not function correctly for ceiling - -- schematic decorations as the behavior is unchanged. - -- If a single decoration registration has both flags the floor and - -- ceiling decorations will be aligned vertically. - - ----- Simple-type parameters - - decoration = "default:grass", - -- The node name used as the decoration. - -- If instead a list of strings, a randomly selected node from the list - -- is placed as the decoration. - - height = 1, - -- Decoration height in nodes. - -- If height_max is not 0, this is the lower limit of a randomly - -- selected height. - - height_max = 0, - -- Upper limit of the randomly selected height. - -- If absent, the parameter 'height' is used as a constant. - - param2 = 0, - -- Param2 value of decoration nodes. - -- If param2_max is not 0, this is the lower limit of a randomly - -- selected param2. - - param2_max = 0, - -- Upper limit of the randomly selected param2. - -- If absent, the parameter 'param2' is used as a constant. - - place_offset_y = 0, - -- Y offset of the decoration base node relative to the standard base - -- node position. - -- Can be positive or negative. Default is 0. - -- Effect is inverted for "all_ceilings" decorations. - -- Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer - -- to the 'place_on' node. - - ----- Schematic-type parameters - - schematic = "foobar.mts", - -- If schematic is a string, it is the filepath relative to the current - -- working directory of the specified Minetest schematic file. - -- Could also be the ID of a previously registered schematic. - - schematic = { - size = {x = 4, y = 6, z = 4}, - data = { - {name = "default:cobble", param1 = 255, param2 = 0}, - {name = "default:dirt_with_grass", param1 = 255, param2 = 0}, - {name = "air", param1 = 255, param2 = 0}, - ... - }, - yslice_prob = { - {ypos = 2, prob = 128}, - {ypos = 5, prob = 64}, - ... - }, + yslice_prob = { + {ypos = 2, prob = 128}, + {ypos = 5, prob = 64}, + ... }, - -- Alternative schematic specification by supplying a table. The fields - -- size and data are mandatory whereas yslice_prob is optional. - -- See 'Schematic specifier' for details. + }, + -- Alternative schematic specification by supplying a table. The fields + -- size and data are mandatory whereas yslice_prob is optional. + -- See 'Schematic specifier' for details. - replacements = {["oldname"] = "convert_to", ...}, - -- Map of node names to replace in the schematic after reading it. + replacements = {["oldname"] = "convert_to", ...}, + -- Map of node names to replace in the schematic after reading it. - flags = "place_center_x, place_center_y, place_center_z", - -- Flags for schematic decorations. See 'Schematic attributes'. + flags = "place_center_x, place_center_y, place_center_z", + -- Flags for schematic decorations. See 'Schematic attributes'. - rotation = "90", - -- Rotation can be "0", "90", "180", "270", or "random" + rotation = "90", + -- Rotation can be "0", "90", "180", "270", or "random" - place_offset_y = 0, - -- If the flag 'place_center_y' is set this parameter is ignored. - -- Y offset of the schematic base node layer relative to the 'place_on' - -- node. - -- Can be positive or negative. Default is 0. - -- Effect is inverted for "all_ceilings" decorations. - -- Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer - -- to the 'place_on' node. - } + place_offset_y = 0, + -- If the flag 'place_center_y' is set this parameter is ignored. + -- Y offset of the schematic base node layer relative to the 'place_on' + -- node. + -- Can be positive or negative. Default is 0. + -- Effect is inverted for "all_ceilings" decorations. + -- Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer + -- to the 'place_on' node. +} +``` Chat command definition ----------------------- @@ -9429,25 +9559,27 @@ Specifies the function to be called and the privileges required when a player issues the command. A help message that is the concatenation of the params and description fields is shown when the "/help" chatcommand is issued. - { - params = "", - -- Short parameter description. See the below note. +```lua +{ + params = "", + -- Short parameter description. See the below note. - description = "", - -- General description of the command's purpose. + description = "", + -- General description of the command's purpose. - privs = {}, - -- Required privileges to run. See `minetest.check_player_privs()` for - -- the format and see [Privileges] for an overview of privileges. + privs = {}, + -- Required privileges to run. See `minetest.check_player_privs()` for + -- the format and see [Privileges] for an overview of privileges. - func = function(name, param), - -- Called when command is run. - -- * `name` is the name of the player who issued the command. - -- * `param` is a string with the full arguments to the command. - -- Returns a boolean for success and a string value. - -- The string is shown to the issuing player upon exit of `func` or, - -- if `func` returns `false` and no string, the help message is shown. - } + func = function(name, param), + -- Called when command is run. + -- * `name` is the name of the player who issued the command. + -- * `param` is a string with the full arguments to the command. + -- Returns a boolean for success and a string value. + -- The string is shown to the issuing player upon exit of `func` or, + -- if `func` returns `false` and no string, the help message is shown. +} +``` Note that in params, the conventional use of symbols is as follows: @@ -9463,74 +9595,80 @@ Note that in params, the conventional use of symbols is as follows: Example: - { - params = " ", +```lua +{ + params = " ", - description = "Remove privilege from player", + description = "Remove privilege from player", - privs = {privs=true}, -- Require the "privs" privilege to run + privs = {privs=true}, -- Require the "privs" privilege to run - func = function(name, param), - } + func = function(name, param), +} +``` Privilege definition -------------------- Used by `minetest.register_privilege`. - { - description = "", - -- Privilege description +```lua +{ + description = "", + -- Privilege description - give_to_singleplayer = true, - -- Whether to grant the privilege to singleplayer. + give_to_singleplayer = true, + -- Whether to grant the privilege to singleplayer. - give_to_admin = true, - -- Whether to grant the privilege to the server admin. - -- Uses value of 'give_to_singleplayer' by default. + give_to_admin = true, + -- Whether to grant the privilege to the server admin. + -- Uses value of 'give_to_singleplayer' by default. - on_grant = function(name, granter_name), - -- Called when given to player 'name' by 'granter_name'. - -- 'granter_name' will be nil if the priv was granted by a mod. + on_grant = function(name, granter_name), + -- Called when given to player 'name' by 'granter_name'. + -- 'granter_name' will be nil if the priv was granted by a mod. - on_revoke = function(name, revoker_name), - -- Called when taken from player 'name' by 'revoker_name'. - -- 'revoker_name' will be nil if the priv was revoked by a mod. + on_revoke = function(name, revoker_name), + -- Called when taken from player 'name' by 'revoker_name'. + -- 'revoker_name' will be nil if the priv was revoked by a mod. - -- Note that the above two callbacks will be called twice if a player is - -- responsible, once with the player name, and then with a nil player - -- name. - -- Return true in the above callbacks to stop register_on_priv_grant or - -- revoke being called. - } + -- Note that the above two callbacks will be called twice if a player is + -- responsible, once with the player name, and then with a nil player + -- name. + -- Return true in the above callbacks to stop register_on_priv_grant or + -- revoke being called. +} +``` Detached inventory callbacks ---------------------------- Used by `minetest.create_detached_inventory`. - { - allow_move = function(inv, from_list, from_index, to_list, to_index, count, player), - -- Called when a player wants to move items inside the inventory. - -- Return value: number of items allowed to move. +```lua +{ + allow_move = function(inv, from_list, from_index, to_list, to_index, count, player), + -- Called when a player wants to move items inside the inventory. + -- Return value: number of items allowed to move. - allow_put = function(inv, listname, index, stack, player), - -- 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. + allow_put = function(inv, listname, index, stack, player), + -- 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. - allow_take = function(inv, listname, index, stack, player), - -- 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. + allow_take = function(inv, listname, index, stack, player), + -- 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. - on_move = function(inv, from_list, from_index, to_list, to_index, count, player), - on_put = function(inv, listname, index, stack, player), - on_take = function(inv, listname, index, stack, player), - -- Called after the actual action has happened, according to what was - -- allowed. - -- No return value. - } + on_move = function(inv, from_list, from_index, to_list, to_index, count, player), + on_put = function(inv, listname, index, stack, player), + on_take = function(inv, listname, index, stack, player), + -- Called after the actual action has happened, according to what was + -- allowed. + -- No return value. +} +``` HUD Definition -------------- @@ -9540,110 +9678,114 @@ documentation in [HUD] section. Used by `ObjectRef:hud_add`. Returned by `ObjectRef:hud_get`. - { - hud_elem_type = "image", - -- Type of element, can be "image", "text", "statbar", "inventory", - -- "waypoint", "image_waypoint", "compass" or "minimap" +```lua +{ + hud_elem_type = "image", + -- Type of element, can be "image", "text", "statbar", "inventory", + -- "waypoint", "image_waypoint", "compass" or "minimap" - position = {x=0.5, y=0.5}, - -- Top left corner position of element + position = {x=0.5, y=0.5}, + -- Top left corner position of element - name = "", + name = "", - scale = {x = 1, y = 1}, + scale = {x = 1, y = 1}, - text = "", + text = "", - text2 = "", + text2 = "", - number = 0, + number = 0, - item = 0, + item = 0, - direction = 0, - -- Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top + direction = 0, + -- Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top - alignment = {x=0, y=0}, + alignment = {x=0, y=0}, - offset = {x=0, y=0}, + offset = {x=0, y=0}, - world_pos = {x=0, y=0, z=0}, + world_pos = {x=0, y=0, z=0}, - size = {x=0, y=0}, + size = {x=0, y=0}, - z_index = 0, - -- Z index: lower z-index HUDs are displayed behind higher z-index HUDs + z_index = 0, + -- Z index: lower z-index HUDs are displayed behind higher z-index HUDs - style = 0, - } + style = 0, +} +``` Particle definition ------------------- Used by `minetest.add_particle`. - { - pos = {x=0, y=0, z=0}, - velocity = {x=0, y=0, z=0}, - acceleration = {x=0, y=0, z=0}, - -- Spawn particle at pos with velocity and acceleration +```lua +{ + pos = {x=0, y=0, z=0}, + velocity = {x=0, y=0, z=0}, + acceleration = {x=0, y=0, z=0}, + -- Spawn particle at pos with velocity and acceleration - expirationtime = 1, - -- Disappears after expirationtime seconds + expirationtime = 1, + -- Disappears after expirationtime seconds - size = 1, - -- Scales the visual size of the particle texture. - -- If `node` is set, size can be set to 0 to spawn a randomly-sized - -- particle (just like actual node dig particles). + size = 1, + -- Scales the visual size of the particle texture. + -- If `node` is set, size can be set to 0 to spawn a randomly-sized + -- particle (just like actual node dig particles). - collisiondetection = false, - -- If true collides with `walkable` nodes and, depending on the - -- `object_collision` field, objects too. + collisiondetection = false, + -- If true collides with `walkable` nodes and, depending on the + -- `object_collision` field, objects too. - collision_removal = false, - -- If true particle is removed when it collides. - -- Requires collisiondetection = true to have any effect. + collision_removal = false, + -- If true particle is removed when it collides. + -- Requires collisiondetection = true to have any effect. - object_collision = false, - -- If true particle collides with objects that are defined as - -- `physical = true,` and `collide_with_objects = true,`. - -- Requires collisiondetection = true to have any effect. + object_collision = false, + -- If true particle collides with objects that are defined as + -- `physical = true,` and `collide_with_objects = true,`. + -- Requires collisiondetection = true to have any effect. - vertical = false, - -- If true faces player using y axis only + vertical = false, + -- If true faces player using y axis only - texture = "image.png", - -- The texture of the particle - -- v5.6.0 and later: also supports the table format described in the - -- following section + texture = "image.png", + -- The texture of the particle + -- v5.6.0 and later: also supports the table format described in the + -- following section - playername = "singleplayer", - -- Optional, if specified spawns particle only on the player's client + playername = "singleplayer", + -- Optional, if specified spawns particle only on the player's client - animation = {Tile Animation definition}, - -- Optional, specifies how to animate the particle texture + animation = {Tile Animation definition}, + -- Optional, specifies how to animate the particle texture - glow = 0 - -- Optional, specify particle self-luminescence in darkness. - -- Values 0-14. + glow = 0 + -- Optional, specify particle self-luminescence in darkness. + -- Values 0-14. - node = {name = "ignore", param2 = 0}, - -- Optional, if specified the particle will have the same appearance as - -- node dig particles for the given node. - -- `texture` and `animation` will be ignored if this is set. + node = {name = "ignore", param2 = 0}, + -- Optional, if specified the particle will have the same appearance as + -- node dig particles for the given node. + -- `texture` and `animation` will be ignored if this is set. - node_tile = 0, - -- Optional, only valid in combination with `node` - -- If set to a valid number 1-6, specifies the tile from which the - -- particle texture is picked. - -- Otherwise, the default behavior is used. (currently: any random tile) + node_tile = 0, + -- Optional, only valid in combination with `node` + -- If set to a valid number 1-6, specifies the tile from which the + -- particle texture is picked. + -- Otherwise, the default behavior is used. (currently: any random tile) - drag = {x=0, y=0, z=0}, - -- v5.6.0 and later: Optional drag value, consult the following section + drag = {x=0, y=0, z=0}, + -- v5.6.0 and later: Optional drag value, consult the following section - bounce = {min = ..., max = ..., bias = 0}, - -- v5.6.0 and later: Optional bounce range, consult the following section - } + bounce = {min = ..., max = ..., bias = 0}, + -- v5.6.0 and later: Optional bounce range, consult the following section +} +``` `ParticleSpawner` definition @@ -9662,82 +9804,84 @@ The older syntax can be used in combination with the newer syntax (e.g. having the new syntax will override the older syntax; on older servers, the newer syntax will be ignored. - { - -- Common fields (same name and meaning in both new and legacy syntax) +```lua +{ + -- Common fields (same name and meaning in both new and legacy syntax) - amount = 1, - -- Number of particles spawned over the time period `time`. + amount = 1, + -- Number of particles spawned over the time period `time`. - time = 1, - -- Lifespan of spawner in seconds. - -- If time is 0 spawner has infinite lifespan and spawns the `amount` on - -- a per-second basis. + time = 1, + -- Lifespan of spawner in seconds. + -- If time is 0 spawner has infinite lifespan and spawns the `amount` on + -- a per-second basis. - collisiondetection = false, - -- If true collide with `walkable` nodes and, depending on the - -- `object_collision` field, objects too. + collisiondetection = false, + -- If true collide with `walkable` nodes and, depending on the + -- `object_collision` field, objects too. - collision_removal = false, - -- If true particles are removed when they collide. - -- Requires collisiondetection = true to have any effect. + collision_removal = false, + -- If true particles are removed when they collide. + -- Requires collisiondetection = true to have any effect. - object_collision = false, - -- If true particles collide with objects that are defined as - -- `physical = true,` and `collide_with_objects = true,`. - -- Requires collisiondetection = true to have any effect. + object_collision = false, + -- If true particles collide with objects that are defined as + -- `physical = true,` and `collide_with_objects = true,`. + -- Requires collisiondetection = true to have any effect. - attached = ObjectRef, - -- If defined, particle positions, velocities and accelerations are - -- relative to this object's position and yaw + attached = ObjectRef, + -- If defined, particle positions, velocities and accelerations are + -- relative to this object's position and yaw - vertical = false, - -- If true face player using y axis only + vertical = false, + -- If true face player using y axis only - texture = "image.png", - -- The texture of the particle + texture = "image.png", + -- The texture of the particle - playername = "singleplayer", - -- Optional, if specified spawns particles only on the player's client + playername = "singleplayer", + -- Optional, if specified spawns particles only on the player's client - animation = {Tile Animation definition}, - -- Optional, specifies how to animate the particles' texture - -- v5.6.0 and later: set length to -1 to synchronize the length - -- of the animation with the expiration time of individual particles. - -- (-2 causes the animation to be played twice, and so on) + animation = {Tile Animation definition}, + -- Optional, specifies how to animate the particles' texture + -- v5.6.0 and later: set length to -1 to synchronize the length + -- of the animation with the expiration time of individual particles. + -- (-2 causes the animation to be played twice, and so on) - glow = 0, - -- Optional, specify particle self-luminescence in darkness. - -- Values 0-14. + glow = 0, + -- Optional, specify particle self-luminescence in darkness. + -- Values 0-14. - node = {name = "ignore", param2 = 0}, - -- Optional, if specified the particles will have the same appearance as - -- node dig particles for the given node. - -- `texture` and `animation` will be ignored if this is set. + node = {name = "ignore", param2 = 0}, + -- Optional, if specified the particles will have the same appearance as + -- node dig particles for the given node. + -- `texture` and `animation` will be ignored if this is set. - node_tile = 0, - -- Optional, only valid in combination with `node` - -- If set to a valid number 1-6, specifies the tile from which the - -- particle texture is picked. - -- Otherwise, the default behavior is used. (currently: any random tile) + node_tile = 0, + -- Optional, only valid in combination with `node` + -- If set to a valid number 1-6, specifies the tile from which the + -- particle texture is picked. + -- Otherwise, the default behavior is used. (currently: any random tile) - -- Legacy definition fields + -- Legacy definition fields - minpos = {x=0, y=0, z=0}, - maxpos = {x=0, y=0, z=0}, - minvel = {x=0, y=0, z=0}, - maxvel = {x=0, y=0, z=0}, - minacc = {x=0, y=0, z=0}, - maxacc = {x=0, y=0, z=0}, - minexptime = 1, - maxexptime = 1, - minsize = 1, - maxsize = 1, - -- The particles' properties are random values between the min and max - -- values. - -- applies to: pos, velocity, acceleration, expirationtime, size - -- If `node` is set, min and maxsize can be set to 0 to spawn - -- randomly-sized particles (just like actual node dig particles). - } + minpos = {x=0, y=0, z=0}, + maxpos = {x=0, y=0, z=0}, + minvel = {x=0, y=0, z=0}, + maxvel = {x=0, y=0, z=0}, + minacc = {x=0, y=0, z=0}, + maxacc = {x=0, y=0, z=0}, + minexptime = 1, + maxexptime = 1, + minsize = 1, + maxsize = 1, + -- The particles' properties are random values between the min and max + -- values. + -- applies to: pos, velocity, acceleration, expirationtime, size + -- If `node` is set, min and maxsize can be set to 0 to spawn + -- randomly-sized particles (just like actual node dig particles). +} +``` ### Modern definition fields @@ -9755,91 +9899,93 @@ property definition are present, the highest-precedence form will be selected and all lower-precedence fields will be ignored, allowing for graceful degradation in older clients). - { - -- old syntax - maxpos = {x = 0, y = 0, z = 0}, - minpos = {x = 0, y = 0, z = 0}, +```lua +{ + -- old syntax + maxpos = {x = 0, y = 0, z = 0}, + minpos = {x = 0, y = 0, z = 0}, - -- absolute value - pos = 0, - -- all components of every particle's position vector will be set to this - -- value + -- absolute value + pos = 0, + -- all components of every particle's position vector will be set to this + -- value - -- vec3 - pos = vector.new(0,0,0), - -- all particles will appear at this exact position throughout the lifetime - -- of the particlespawner + -- vec3 + pos = vector.new(0,0,0), + -- all particles will appear at this exact position throughout the lifetime + -- of the particlespawner - -- vec3 range - pos = { - -- the particle will appear at a position that is picked at random from - -- within a cubic range + -- vec3 range + pos = { + -- the particle will appear at a position that is picked at random from + -- within a cubic range - min = vector.new(0,0,0), - -- `min` is the minimum value this property will be set to in particles - -- spawned by the generator + min = vector.new(0,0,0), + -- `min` is the minimum value this property will be set to in particles + -- spawned by the generator - max = vector.new(0,0,0), - -- `max` is the minimum value this property will be set to in particles - -- spawned by the generator + max = vector.new(0,0,0), + -- `max` is the minimum value this property will be set to in particles + -- spawned by the generator - bias = 0, - -- when `bias` is 0, all random values are exactly as likely as any - -- other. when it is positive, the higher it is, the more likely values - -- will appear towards the minimum end of the allowed spectrum. when - -- it is negative, the lower it is, the more likely values will appear - -- towards the maximum end of the allowed spectrum. the curve is - -- exponential and there is no particular maximum or minimum value - }, + bias = 0, + -- when `bias` is 0, all random values are exactly as likely as any + -- other. when it is positive, the higher it is, the more likely values + -- will appear towards the minimum end of the allowed spectrum. when + -- it is negative, the lower it is, the more likely values will appear + -- towards the maximum end of the allowed spectrum. the curve is + -- exponential and there is no particular maximum or minimum value + }, - -- tween table - pos_tween = {...}, - -- a tween table should consist of a list of frames in the same form as the - -- untweened pos property above, which the engine will interpolate between, - -- and optionally a number of properties that control how the interpolation - -- takes place. currently **only two frames**, the first and the last, are - -- used, but extra frames are accepted for the sake of forward compatibility. - -- any of the above definition styles can be used here as well in any combination - -- supported by the property type + -- tween table + pos_tween = {...}, + -- a tween table should consist of a list of frames in the same form as the + -- untweened pos property above, which the engine will interpolate between, + -- and optionally a number of properties that control how the interpolation + -- takes place. currently **only two frames**, the first and the last, are + -- used, but extra frames are accepted for the sake of forward compatibility. + -- any of the above definition styles can be used here as well in any combination + -- supported by the property type - pos_tween = { - style = "fwd", - -- linear animation from first to last frame (default) - style = "rev", - -- linear animation from last to first frame - style = "pulse", - -- linear animation from first to last then back to first again - style = "flicker", - -- like "pulse", but slightly randomized to add a bit of stutter + pos_tween = { + style = "fwd", + -- linear animation from first to last frame (default) + style = "rev", + -- linear animation from last to first frame + style = "pulse", + -- linear animation from first to last then back to first again + style = "flicker", + -- like "pulse", but slightly randomized to add a bit of stutter - reps = 1, - -- number of times the animation is played over the particle's lifespan + reps = 1, + -- number of times the animation is played over the particle's lifespan - start = 0.0, - -- point in the spawner's lifespan at which the animation begins. 0 is - -- the very beginning, 1 is the very end + start = 0.0, + -- point in the spawner's lifespan at which the animation begins. 0 is + -- the very beginning, 1 is the very end - -- frames can be defined in a number of different ways, depending on the - -- underlying type of the property. for now, all but the first and last - -- frame are ignored + -- frames can be defined in a number of different ways, depending on the + -- underlying type of the property. for now, all but the first and last + -- frame are ignored - -- frames + -- frames - -- floats - 0, 0, + -- floats + 0, 0, - -- vec3s - vector.new(0,0,0), - vector.new(0,0,0), + -- vec3s + vector.new(0,0,0), + vector.new(0,0,0), - -- vec3 ranges - { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 }, - { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 }, + -- vec3 ranges + { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 }, + { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 }, - -- mixed - 0, { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 }, - }, - } + -- mixed + 0, { min = vector.new(0,0,0), max = vector.new(0,0,0), bias = 0 }, + }, +} +``` All of the properties that can be defined in this way are listed in the next section, along with the datatypes they accept. @@ -9924,56 +10070,58 @@ In versions before v5.6.0, particlespawner textures could only be specified as a texture string. After v5.6.0, textures can now be specified as a table as well. This table contains options that allow simple animations to be applied to the texture. - texture = { - name = "mymod_particle_texture.png", - -- the texture specification string +```lua +texture = { + name = "mymod_particle_texture.png", + -- the texture specification string - alpha = 1.0, - -- controls how visible the particle is; at 1.0 the particle is fully - -- visible, at 0, it is completely invisible. + alpha = 1.0, + -- controls how visible the particle is; at 1.0 the particle is fully + -- visible, at 0, it is completely invisible. - alpha_tween = {1, 0}, - -- can be used instead of `alpha` to animate the alpha value over the - -- particle's lifetime. these tween tables work identically to the tween - -- tables used in particlespawner properties, except that time references - -- are understood with respect to the particle's lifetime, not the - -- spawner's. {1,0} fades the particle out over its lifetime. + alpha_tween = {1, 0}, + -- can be used instead of `alpha` to animate the alpha value over the + -- particle's lifetime. these tween tables work identically to the tween + -- tables used in particlespawner properties, except that time references + -- are understood with respect to the particle's lifetime, not the + -- spawner's. {1,0} fades the particle out over its lifetime. - scale = 1, - scale = {x = 1, y = 1}, - -- scales the texture onscreen + scale = 1, + scale = {x = 1, y = 1}, + -- scales the texture onscreen - scale_tween = { - {x = 1, y = 1}, - {x = 0, y = 1}, - }, - -- animates the scale over the particle's lifetime. works like the - -- alpha_tween table, but can accept two-dimensional vectors as well as - -- integer values. the example value would cause the particle to shrink - -- in one dimension over the course of its life until it disappears + scale_tween = { + {x = 1, y = 1}, + {x = 0, y = 1}, + }, + -- animates the scale over the particle's lifetime. works like the + -- alpha_tween table, but can accept two-dimensional vectors as well as + -- integer values. the example value would cause the particle to shrink + -- in one dimension over the course of its life until it disappears - blend = "alpha", - -- (default) blends transparent pixels with those they are drawn atop - -- according to the alpha channel of the source texture. useful for - -- e.g. material objects like rocks, dirt, smoke, or node chunks - blend = "add", - -- adds the value of pixels to those underneath them, modulo the sources - -- alpha channel. useful for e.g. bright light effects like sparks or fire - blend = "screen", - -- like "add" but less bright. useful for subtler light effects. note that - -- this is NOT formally equivalent to the "screen" effect used in image - -- editors and compositors, as it does not respect the alpha channel of - -- of the image being blended - blend = "sub", - -- the inverse of "add"; the value of the source pixel is subtracted from - -- the pixel underneath it. a white pixel will turn whatever is underneath - -- it black; a black pixel will be "transparent". useful for creating - -- darkening effects + blend = "alpha", + -- (default) blends transparent pixels with those they are drawn atop + -- according to the alpha channel of the source texture. useful for + -- e.g. material objects like rocks, dirt, smoke, or node chunks + blend = "add", + -- adds the value of pixels to those underneath them, modulo the sources + -- alpha channel. useful for e.g. bright light effects like sparks or fire + blend = "screen", + -- like "add" but less bright. useful for subtler light effects. note that + -- this is NOT formally equivalent to the "screen" effect used in image + -- editors and compositors, as it does not respect the alpha channel of + -- of the image being blended + blend = "sub", + -- the inverse of "add"; the value of the source pixel is subtracted from + -- the pixel underneath it. a white pixel will turn whatever is underneath + -- it black; a black pixel will be "transparent". useful for creating + -- darkening effects - animation = {Tile Animation definition}, - -- overrides the particlespawner's global animation property for a single - -- specific texture - } + animation = {Tile Animation definition}, + -- overrides the particlespawner's global animation property for a single + -- specific texture +} +``` Instead of setting a single texture definition, it is also possible to set a `texpool` property. A `texpool` consists of a list of possible particle textures. @@ -9983,25 +10131,27 @@ the `texpool` and assign it as that particle's texture. You can also specify a clients but will be sent to older (pre-v5.6.0) clients that do not implement texpools. - texpool = { - "mymod_particle_texture.png"; - { name = "mymod_spark.png", fade = "out" }, - { - name = "mymod_dust.png", - alpha = 0.3, - scale = 1.5, - animation = { - type = "vertical_frames", - aspect_w = 16, aspect_h = 16, +```lua +texpool = { + "mymod_particle_texture.png"; + { name = "mymod_spark.png", fade = "out" }, + { + name = "mymod_dust.png", + alpha = 0.3, + scale = 1.5, + animation = { + type = "vertical_frames", + aspect_w = 16, aspect_h = 16, - length = 3, - -- the animation lasts for 3s and then repeats - length = -3, - -- repeat the animation three times over the particle's lifetime - -- (post-v5.6.0 clients only) - }, - }, - } + length = 3, + -- the animation lasts for 3s and then repeats + length = -3, + -- repeat the animation three times over the particle's lifetime + -- (post-v5.6.0 clients only) + }, + }, +} +``` #### List of animatable texture properties @@ -10009,11 +10159,13 @@ While animated particlespawner values vary over the course of the particlespawne lifetime, animated texture properties vary over the lifespans of the individual particles spawned with that texture. So a particle with the texture property - alpha_tween = { - 0.0, 1.0, - style = "pulse", - reps = 4, - } +```lua +alpha_tween = { + 0.0, 1.0, + style = "pulse", + reps = 4, +} +``` would be invisible at its spawning, pulse visible four times throughout its lifespan, and then vanish again before expiring. @@ -10027,37 +10179,39 @@ lifespan, and then vanish again before expiring. Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`. - { - url = "http://example.org", +```lua +{ + url = "http://example.org", - timeout = 10, - -- Timeout for request to be completed in seconds. Default depends on engine settings. + timeout = 10, + -- Timeout for request to be completed in seconds. Default depends on engine settings. - method = "GET", "POST", "PUT" or "DELETE" - -- The http method to use. Defaults to "GET". + method = "GET", "POST", "PUT" or "DELETE" + -- The http method to use. Defaults to "GET". - data = "Raw request data string" OR {field1 = "data1", field2 = "data2"}, - -- 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. + data = "Raw request data string" OR {field1 = "data1", field2 = "data2"}, + -- 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. - user_agent = "ExampleUserAgent", - -- Optional, if specified replaces the default minetest user agent with - -- given string + user_agent = "ExampleUserAgent", + -- Optional, if specified replaces the default minetest user agent with + -- given string - extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" }, - -- Optional, if specified adds additional headers to the HTTP request. - -- You must make sure that the header strings follow HTTP specification - -- ("Key: Value"). + extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" }, + -- Optional, if specified adds additional headers to the HTTP request. + -- You must make sure that the header strings follow HTTP specification + -- ("Key: Value"). - multipart = boolean - -- Optional, if true performs a multipart HTTP request. - -- Default is false. - -- Post only, data must be array + multipart = boolean + -- Optional, if true performs a multipart HTTP request. + -- Default is false. + -- Post only, data must be array - post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"}, - -- Deprecated, use `data` instead. Forces `method = "POST"`. - } + post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"}, + -- Deprecated, use `data` instead. Forces `method = "POST"`. +} +``` `HTTPRequestResult` definition ------------------------------ @@ -10065,64 +10219,68 @@ Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`. Passed to `HTTPApiTable.fetch` callback. Returned by `HTTPApiTable.fetch_async_get`. - { - completed = true, - -- If true, the request has finished (either succeeded, failed or timed - -- out) +```lua +{ + completed = true, + -- If true, the request has finished (either succeeded, failed or timed + -- out) - succeeded = true, - -- If true, the request was successful + succeeded = true, + -- If true, the request was successful - timeout = false, - -- If true, the request timed out + timeout = false, + -- If true, the request timed out - code = 200, - -- HTTP status code + code = 200, + -- HTTP status code - data = "response" - } + data = "response" +} +``` Authentication handler definition --------------------------------- Used by `minetest.register_authentication_handler`. - { - get_auth = function(name), - -- Get authentication data for existing player `name` (`nil` if player - -- doesn't exist). - -- Returns following structure: - -- `{password=, privileges=
, last_login=}` +```lua +{ + get_auth = function(name), + -- Get authentication data for existing player `name` (`nil` if player + -- doesn't exist). + -- Returns following structure: + -- `{password=, privileges=
, last_login=}` - create_auth = function(name, password), - -- Create new auth data for player `name`. - -- Note that `password` is not plain-text but an arbitrary - -- representation decided by the engine. + create_auth = function(name, password), + -- Create new auth data for player `name`. + -- Note that `password` is not plain-text but an arbitrary + -- representation decided by the engine. - delete_auth = function(name), - -- Delete auth data of player `name`. - -- Returns boolean indicating success (false if player is nonexistent). + delete_auth = function(name), + -- Delete auth data of player `name`. + -- Returns boolean indicating success (false if player is nonexistent). - set_password = function(name, password), - -- Set password of player `name` to `password`. - -- Auth data should be created if not present. + set_password = function(name, password), + -- Set password of player `name` to `password`. + -- Auth data should be created if not present. - set_privileges = function(name, privileges), - -- Set privileges of player `name`. - -- `privileges` is in table form, auth data should be created if not - -- present. + set_privileges = function(name, privileges), + -- Set privileges of player `name`. + -- `privileges` is in table form, auth data should be created if not + -- present. - reload = function(), - -- Reload authentication data from the storage location. - -- Returns boolean indicating success. + reload = function(), + -- Reload authentication data from the storage location. + -- Returns boolean indicating success. - record_login = function(name), - -- Called when player joins, used for keeping track of last_login + record_login = function(name), + -- Called when player joins, used for keeping track of last_login - iterate = function(), - -- Returns an iterator (use with `for` loops) for all player names - -- currently in the auth database - } + iterate = function(), + -- Returns an iterator (use with `for` loops) for all player names + -- currently in the auth database +} +``` Bit Library ----------- diff --git a/doc/menu_lua_api.md b/doc/menu_lua_api.md index 8ebef3d00..480df7027 100644 --- a/doc/menu_lua_api.md +++ b/doc/menu_lua_api.md @@ -22,14 +22,16 @@ Gamedata The "gamedata" table is read when calling `core.start()`. It should contain: - { - playername = , - password = , - address = , - port = , - selected_world = , -- 0 for client mode - singleplayer = , - } +```lua +{ + playername = , + password = , + address = , + port = , + selected_world = , -- 0 for client mode + singleplayer = , +} +``` Functions @@ -116,53 +118,57 @@ HTTP Requests Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`. - { - url = "http://example.org", +```lua +{ + url = "http://example.org", - timeout = 10, - -- Timeout for connection in seconds. Default is 3 seconds. + timeout = 10, + -- Timeout for connection in seconds. Default is 3 seconds. - post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"}, - -- Optional, if specified a POST request with post_data is performed. - -- Accepts both a string and a table. If a table is specified, encodes - -- table as x-www-form-urlencoded key-value pairs. - -- If post_data is not specified, a GET request is performed instead. + post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"}, + -- Optional, if specified a POST request with post_data is performed. + -- Accepts both a string and a table. If a table is specified, encodes + -- table as x-www-form-urlencoded key-value pairs. + -- If post_data is not specified, a GET request is performed instead. - user_agent = "ExampleUserAgent", - -- Optional, if specified replaces the default minetest user agent with - -- given string + user_agent = "ExampleUserAgent", + -- Optional, if specified replaces the default minetest user agent with + -- given string - extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" }, - -- Optional, if specified adds additional headers to the HTTP request. - -- You must make sure that the header strings follow HTTP specification - -- ("Key: Value"). + extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" }, + -- Optional, if specified adds additional headers to the HTTP request. + -- You must make sure that the header strings follow HTTP specification + -- ("Key: Value"). - multipart = boolean - -- Optional, if true performs a multipart HTTP request. - -- Default is false. - } + multipart = boolean + -- Optional, if true performs a multipart HTTP request. + -- Default is false. +} +``` ### `HTTPRequestResult` definition Passed to `HTTPApiTable.fetch` callback. Returned by `HTTPApiTable.fetch_async_get`. - { - completed = true, - -- If true, the request has finished (either succeeded, failed or timed - -- out) +```lua +{ + completed = true, + -- If true, the request has finished (either succeeded, failed or timed + -- out) - succeeded = true, - -- If true, the request was successful + succeeded = true, + -- If true, the request was successful - timeout = false, - -- If true, the request timed out + timeout = false, + -- If true, the request timed out - code = 200, - -- HTTP status code + code = 200, + -- HTTP status code - data = "response" - } + data = "response" +} +``` Formspec @@ -209,38 +215,40 @@ GUI * name of current renderer, e.g. "OpenGL 4.6" * `core.get_window_info()`: Same as server-side `get_player_window_information` API. - -- Note that none of these things are constant, they are likely to change - -- as the player resizes the window and moves it between monitors + ```lua + -- Note that none of these things are constant, they are likely to change + -- as the player resizes the window and moves it between monitors + -- + -- real_gui_scaling and real_hud_scaling can be used instead of DPI. + -- OSes don't necessarily give the physical DPI, as they may allow user configuration. + -- real_*_scaling is just OS DPI / 96 but with another level of user configuration. + { + -- Current size of the in-game render target. -- - -- real_gui_scaling and real_hud_scaling can be used instead of DPI. - -- OSes don't necessarily give the physical DPI, as they may allow user configuration. - -- real_*_scaling is just OS DPI / 96 but with another level of user configuration. - { - -- Current size of the in-game render target. - -- - -- This is usually the window size, but may be smaller in certain situations, - -- such as side-by-side mode. - size = { - x = 1308, - y = 577, - }, + -- This is usually the window size, but may be smaller in certain situations, + -- such as side-by-side mode. + size = { + x = 1308, + y = 577, + }, - -- Estimated maximum formspec size before Minetest will start shrinking the - -- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than - -- this and `padding[-0.01,-0.01]`. - max_formspec_size = { - x = 20, - y = 11.25 - }, + -- Estimated maximum formspec size before Minetest will start shrinking the + -- formspec to fit. For a fullscreen formspec, use a size 10-20% larger than + -- this and `padding[-0.01,-0.01]`. + max_formspec_size = { + x = 20, + y = 11.25 + }, - -- GUI Scaling multiplier - -- Equal to the setting `gui_scaling` multiplied by `dpi / 96` - real_gui_scaling = 1, + -- GUI Scaling multiplier + -- Equal to the setting `gui_scaling` multiplied by `dpi / 96` + real_gui_scaling = 1, - -- HUD Scaling multiplier - -- Equal to the setting `hud_scaling` multiplied by `dpi / 96` - real_hud_scaling = 1, - } + -- HUD Scaling multiplier + -- Equal to the setting `hud_scaling` multiplied by `dpi / 96` + real_hud_scaling = 1, + } + ``` @@ -262,7 +270,7 @@ Package - content which is downloadable from the content db, may or may not be i Ex: - ``` + ```lua { mods = "/home/user/.minetest/mods", share = "/usr/share/minetest/mods", @@ -281,42 +289,45 @@ Package - content which is downloadable from the content db, may or may not be i * `core.get_games()` -> table of all games (possible in async calls) * `name` in return value is deprecated, use `title` instead. * returns a table (ipairs) with values: - - { - id = , - path = , - gamemods_path = , - title = , - menuicon_path = <full path to menuicon>, - author = "author", - DEPRECATED: - addon_mods_paths = {[1] = <path>,}, - } + ```lua + { + id = <id>, + path = <full path to game>, + gamemods_path = <path>, + title = <title of game>, + menuicon_path = <full path to menuicon>, + author = "author", + --DEPRECATED: + addon_mods_paths = {[1] = <path>,}, + } + ``` * `core.get_content_info(path)` * returns - - { - name = "technical_id", - type = "mod" or "modpack" or "game" or "txp", - title = "Human readable title", - description = "description", - author = "author", - path = "path/to/content", - depends = {"mod", "names"}, -- mods only - optional_depends = {"mod", "names"}, -- mods only - } + ```lua + { + name = "technical_id", + type = "mod" or "modpack" or "game" or "txp", + title = "Human readable title", + description = "description", + author = "author", + path = "path/to/content", + depends = {"mod", "names"}, -- mods only + optional_depends = {"mod", "names"}, -- mods only + } + ``` * `core.check_mod_configuration(world_path, mod_paths)` * Checks whether configuration is valid. * `world_path`: path to the world * `mod_paths`: list of enabled mod paths * returns: - - { - is_consistent = true, -- true is consistent, false otherwise - unsatisfied_mods = {}, -- list of mod specs - satisfied_mods = {}, -- list of mod specs - error_message = "", -- message or nil - } + ```lua + { + is_consistent = true, -- true is consistent, false otherwise + unsatisfied_mods = {}, -- list of mod specs + satisfied_mods = {}, -- list of mod specs + error_message = "", -- message or nil + } + ``` Logging ------- @@ -346,14 +357,15 @@ Worlds * `core.get_worlds()` -> list of worlds (possible in async calls) * returns - - { - [1] = { - path = <full path to world>, - name = <name of world>, - gameid = <gameid of world>, - }, - } + ```lua + { + [1] = { + path = <full path to world>, + name = <name of world>, + gameid = <gameid of world>, + }, + } + ``` * `core.create_world(worldname, gameid, init_settings)` * `core.delete_world(index)`