If you have any difficulty in understanding this, please read Programming in Lua.
experimental as a dependency)
The : prefix can also be used for maintaining backwards compatibility.
Aliases can be added by using minetest.register_alias(name, convert_to).
Aliases can be added by using minetest.register_alias(name, convert_to) or
+`minetest.register_alias_force(name, convert_to).
This will make Minetest to convert things called name to things called
convert_to.
The only difference between minetest.register_alias and
+minetest.register_alias_force is that if an item called name exists,
+minetest.register_alias will do nothing while
+minetest.register_alias_force will unregister it.
This can be used for maintaining backwards compatibility.
This can be also used for setting quick access names for things, e.g. if
you have an item called epiclylongmodname:stuff, you could do
Textures can be grouped together by enclosing them in ( and ).
Example: cobble.png^(thing1.png^thing2.png)
A texture for thing1.png^thing2.png is created and the resulting
-texture is overlaid over cobble.png.
cobble.png.
+Modifiers that accept texture names (e.g. [combine) accept escaping to allow
+passing complex texture names as arguments. Escaping is done with backslash and
+is required for ^ and :.
Example: cobble.png^[lowpart:50:color.png\^[mask\:trans.png
The lower 50 percent of color.png^[mask:trans.png are overlaid
+on top of cobble.png.
[crack:<n>:<p>Example:
default_sandstone.png^[opacity:127
[invert:<mode>Inverts the given channels of the base image. +Mode may contain the characters "r", "g", "b", "a". +Only the channels that are mentioned in the mode string will be inverted.
+Example:
+default_apple.png^[invert:rgb
+[brightenBrightens the texture.
Example:
@@ -631,7 +655,7 @@ Rotations are counter-clockwise.default_stone.png^[transformFXR90
[inventorycube{<top>{<left>{<right>^ is replaced by & in texture names.
Escaping does not apply here and ^ is replaced by & in texture names instead.
Create an inventory cube texture using the side textures.
Example:
[inventorycube{grass.png{dirt.png&grass_side.png{dirt.png&grass_side.png
@@ -746,6 +770,14 @@ the global minetest.registered_* tables.
#added to minetest.registered_items[name]
+#
+minetest.unregister_item(name)
+
+- Unregisters the item name from engine, and deletes the entry with key
+- #
name from minetest.registered_items and from the associated item
+- table according to its nature: minetest.registered_nodes[] etc
+
+
#
minetest.register_biome(biome definition)
@@ -1120,7 +1152,7 @@ in the form of a table. This table specifies the following fields:
- #The
data field is a flat table of MapNode tables making up the schematic,
in the order of [z [y [x]]]. (required)
Each MapNode table contains:
-- #
name: the name of the map node to place (required)
+- #
name: the name of the map node to place (required)
- #
prob (alias param1): the probability of this node being placed (default: 255)
- #
param2: the raw param2 value of the node being placed onto the map (default: 0)
- #
force_place: boolean representing if the node should forcibly overwrite any
@@ -1204,7 +1236,7 @@ in the experimental stages.
waypoint
Displays distance to selected world position.
-- #
name: The name of the waypoint.
+- #
name: The name of the waypoint.
- #
text: Distance suffix. Can be blank.
- #
number: An integer containing the RGB value of the color used to draw the text.
- #
world_pos: World position of the waypoint.
@@ -1598,6 +1630,17 @@ list[current_player;craftpreview;7,1;1,1;]
- #
fixed_size: true/false (optional)
- #deprecated:
invsize[<W>,<H>;]
+container[<X>,<Y>]
+
+- Start of a container block, moves all physical elements in the container by (X, Y)
+- Must have matching container_end
+- Containers can be nested, in which case the offsets are added
+ (child containers are relative to parent containers)
+
+container_end[]
+
+- End of a container, following elements are no longer relative to this container
+
list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]
- Show an inventory list
@@ -1675,7 +1718,7 @@ list[current_player;craftpreview;7,1;1,1;]
- #If
true the background is clipped to formspec size
(x and y are used as offset values, w and h are ignored)
-pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>;<close_on_enter>]
+pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]
- Textual password style field; will be sent to server when a button is clicked
- When enter is pressed in field, fields.key_enter_field will be sent with the name
@@ -1684,12 +1727,11 @@ list[current_player;craftpreview;7,1;1,1;]
- #
w and h are the size of the field
- #Fields are a set height, but will be vertically centred on
h
- Position and size units are inventory slots
-- #
name is the name of the field as returned in fields to on_receive_fields
+- #
name is the name of the field as returned in fields to on_receive_fields
- #
label, if not blank, will be text printed on the top left above the field
-- #
close_on_enter (optional) is whether the form should accept and close when enter is
- pressed in this field. Defaults to true.
+- See field_close_on_enter to stop enter closing the formspec
-field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>;<close_on_enter>]
+field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
- Textual field; will be sent to server when a button is clicked
- When enter is pressed in field, fields.key_enter_field will be sent with the name
@@ -1698,7 +1740,7 @@ list[current_player;craftpreview;7,1;1,1;]
- #
w and h are the size of the field
- #Fields are a set height, but will be vertically centred on
h
- Position and size units are inventory slots
-- #
name is the name of the field as returned in fields to on_receive_fields
+- #
name is the name of the field as returned in fields to on_receive_fields
- #
label, if not blank, will be text printed on the top left above the field
- #
default is the default value of the field
- #
default may contain variable references such as ${text}' which
@@ -1706,10 +1748,9 @@ list[current_player;craftpreview;7,1;1,1;]
- Note: no extra text or more than a single variable is supported ATM.
-- #
close_on_enter (optional) is whether the form should accept and close when enter is
- pressed in this field. Defaults to true.
+- See field_close_on_enter to stop enter closing the formspec
-field[<name>;<label>;<default>;<close_on_enter>]
+field[<name>;<label>;<default>]
- As above, but without position/size units
- When enter is pressed in field, fields.key_enter_field will be sent with the name
@@ -1717,8 +1758,13 @@ list[current_player;craftpreview;7,1;1,1;]
- Special field for creating simple forms, such as sign text input
- #Must be used without a
size[] element
- A "Proceed" button will be added automatically
-- #
close_on_enter (optional) is whether the form should accept and close when enter is
- pressed in this field. Defaults to true.
+- See field_close_on_enter to stop enter closing the formspec
+
+field_close_on_enter[<name>;<close_on_enter>]
+
+ is the name of the field - if
is false, pressing enter in the field will submit the form but not close it
+- defaults to true when not specified (ie: no tag for a field)
textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
@@ -1781,7 +1827,7 @@ list[current_player;craftpreview;7,1;1,1;]
- Scrollable item list showing arbitrary text elements
- #
x and y position the itemlist relative to the top left of the menu
- #
w and h are the size of the itemlist
-- #
name fieldname sent to server on doubleclick value is current selected element
+- #
name fieldname sent to server on doubleclick value is current selected element
- #
listelements can be prepended by #color in hexadecimal format RRGGBB (only),
- if you want a listelement to start with "#" write "##".
@@ -1792,7 +1838,7 @@ list[current_player;craftpreview;7,1;1,1;]
- Scrollable itemlist showing arbitrary text elements
- #
x and y position the item list relative to the top left of the menu
- #
w and h are the size of the item list
-- #
name fieldname sent to server on doubleclick value is current selected element
+- #
name fieldname sent to server on doubleclick value is current selected element
- #
listelements can be prepended by #RRGGBB (only) in hexadecimal format
- if you want a listelement to start with "#" write "##"
@@ -1805,7 +1851,7 @@ list[current_player;craftpreview;7,1;1,1;]
- Show a tabheader at specific position (ignores formsize)
- #
x and y position the itemlist relative to the top left of the menu
-- #
name fieldname data is transferred to Lua
+- #
name fieldname data is transferred to Lua
- #
caption 1...: name shown on top of tab
- #
current_tab: index of selected tab 1...
- #
transparent (optional): show transparent
@@ -1836,7 +1882,7 @@ list[current_player;craftpreview;7,1;1,1;]
- Show a checkbox
- #
x and y: position of checkbox
-- #
name fieldname data is transferred to Lua
+- #
name fieldname data is transferred to Lua
- #
label to be shown left of checkbox
- #
selected (optional): true/false
@@ -1861,7 +1907,7 @@ list[current_player;craftpreview;7,1;1,1;]
- #Displays cells as defined by the previous
tablecolumns[]
- #
x and y: position the itemlist relative to the top left of the menu
- #
w and h are the size of the itemlist
-- #
name: fieldname sent to server on row select or doubleclick
+- #
name: fieldname sent to server on row select or doubleclick
- #
cell 1...cell n: cell contents given in row-major order
- #
selected idx: index of row to be selected within table (first row = 1)
- #See also
minetest.explode_table_event (main menu: engine.explode_table_event)
@@ -1990,7 +2036,8 @@ The following functions provide escape sequences:
- #
vector.distance(p1, p2): returns a number
- #
vector.length(v): returns a number
- #
vector.normalize(v): returns a vector
-- #
vector.round(v): returns a vector, each dimension rounded to floor
+- #
vector.floor(v): returns a vector, each dimension rounded down
+- #
vector.round(v): returns a vector, each dimension rounded to nearest int
- #
vector.apply(v, func): returns a vector
- #
vector.equals(v1, v2): returns a boolean
@@ -2119,6 +2166,17 @@ The following functions provide escape sequences:
- nil: return all entries,
- true: return only subdirectory names, or
- false: return only file names.
+- #
minetest.get_version(): returns a table containing components of the
+ engine version. Components:
+- #
project: Name of the project, eg, "Minetest"
+- #
string: Simple version, eg, "1.2.3-dev"
+- #
hash: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
+ Use this for informational purposes only. The information in the returned
+ table does not represent the capabilities of the engine, nor is it
+ reliable or verifyable. Compatible forks will have a different name and
+ version entirely. To check for the presence of engine features, test
+ whether the functions exported by the wanted features exist. For example:
+ if core.nodeupdate then ... end.
@@ -2143,7 +2201,9 @@ The following functions provide escape sequences:
#minetest.register_node(name, node definition)
#minetest.register_tool(name, item definition)
#minetest.register_craftitem(name, item definition)
+#minetest.unregister_item(name)
#minetest.register_alias(name, convert_to)
+#minetest.register_alias_force(name, convert_to)
#minetest.register_craft(recipe)
- Check recipe table syntax for different types below.
@@ -2158,18 +2218,16 @@ The following functions provide escape sequences:
#minetest.register_ore(ore definition)
+#minetest.register_biome(biome definition)
#minetest.register_decoration(decoration definition)
-#
-minetest.override_item(name, redefinition)
-
+- #
minetest.override_item(name, redefinition)
- Overrides fields of an item registered with register_node/tool/craftitem.
- Note: Item must already be defined, (opt)depend on the mod defining it.
- #Example:
minetest.override_item("default:mese", {light_source=LIGHT_MAX})
-- #
-
minetest.clear_registered_ores()
-
+- #
minetest.clear_registered_ores()
+- #
minetest.clear_registered_biomes()
- #
minetest.clear_registered_decorations()
Global callback registration functions
@@ -2552,19 +2610,20 @@ and minetest.auth_reload call the authetification handler.
#minetest.get_mapgen_setting_noiseparams(name)
-#minetest.set_mapgen_setting(name, value, [override_meta=false])
+#minetest.set_mapgen_setting(name, value, [override_meta])
#Sets a mapgen param to value, and will take effect if the corresponding mapgen setting
- is not already present in map_meta.txt. If the optional boolean override_meta is set to true,
- this setting will become the active setting regardless of the map metafile contents.
+ is not already present in map_meta.txt.
+#override_meta is an optional boolean (default: false). If this is set to true,
+ the setting will become the active setting regardless of the map metafile contents.
Note: to set the seed, use "seed", not "fixed_map_seed"
-#minetest.set_mapgen_setting_noiseparams(name, value, [override_meta=false])
-Same as above, except value is a NoiseParams table
+#minetest.set_mapgen_setting_noiseparams(name, value, [override_meta])
+Same as above, except value is a NoiseParams table.
#minetest.set_noiseparams(name, noiseparams, set_default)
-- #Sets the noiseparams setting of
name to the noiseparams table specified in noiseparams.
+- #Sets the noiseparams setting of
name to the noiseparams table specified in noiseparams.
- #
set_default is an optional boolean (default: true) that specifies whether the setting
should be applied to the default config or current active config
@@ -2904,6 +2963,7 @@ and minetest.auth_reload call the authetification handler.
#minetest.request_shutdown([message],[reconnect]): request for server shutdown. Will display message to clients,
and reconnect == true displays a reconnect button.
#minetest.get_server_status(): returns server status string
+#minetest.get_server_uptime(): returns the server uptime in seconds
Bans
@@ -3064,7 +3124,7 @@ and minetest.auth_reload call the authetification handler.
#minetest.get_content_id(name): returns an integer
#minetest.get_name_from_content_id(content_id): returns a string
@@ -3100,7 +3160,7 @@ and minetest.auth_reload call the authetification handler.
#minetest.deserialize(string): returns a table
- #Convert a string returned by
minetest.deserialize into a table
-- #
string is loaded in an empty sandbox environment.
+- #
string is loaded in an empty sandbox environment.
- Will load functions, but they cannot access the global environment.
- #Example:
deserialize('return { ["foo"] = "bar" }'), returns {foo='bar'}
- #Example:
deserialize('print("foo")'), returns nil (function call fails)
@@ -3136,7 +3196,7 @@ and minetest.auth_reload call the authetification handler.
- #
minetest.is_protected(pos, name): returns boolean
-- #Returns true, if player
name shouldn't be abled to dig at pos or do other
+ - #Returns true, if player
name shouldn't be abled to dig at pos or do other
actions, defineable by mods, due to some mod-defined ownership-like concept.
Returns false or nil, if the player is allowed to do such actions.
- This function should be overridden by protection mods and should be used to
@@ -3184,18 +3244,22 @@ end
-- #
-
minetest.forceload_block(pos)
+ - #
+
minetest.forceload_block(pos[, transient])
- #forceloads the position
pos.
- #returns
true if area could be forceloaded
-- Please note that forceloaded areas are saved when the server restarts.
+- #If
transient is false or absent, the forceload will be persistent
+ (saved between server runs). If true, the forceload will be transient
+ (not saved between server runs).
-- #
-
minetest.forceload_free_block(pos)
+ - #
+
minetest.forceload_free_block(pos[, transient])
- #
@@ -3511,7 +3575,7 @@ Can be gotten via
minetest.get_node_timer(pos).
- #
hud_get_hotbar_selected_image: returns texturename
- #
hud_replace_builtin(name, hud_definition)
@@ -3592,7 +3656,8 @@ chosen for you.
Methods
- #
get_area(id, include_borders, include_data): returns the area with the id id.
- (optional) Boolean values include_borders and include_data control what's copied.
+ (optional) Boolean values include_borders and include_data control what's copied.
+ Returns nil if specified area id does not exist.
- #
get_areas_for_pos(pos, include_borders, include_data): returns all areas that contain
the position pos. (optional) Boolean values include_borders and include_data control
what's copied.
@@ -3633,13 +3698,11 @@ an itemstring, a table or nil.
- #
is_empty(): Returns true if stack is empty.
- #
get_name(): Returns item name (e.g. "default:stone").
-- #
set_name(item_name): Returns boolean success.
- Clears item on failure.
+- #
set_name(item_name): Returns boolean whether item was cleared
- #
get_count(): Returns number of items on the stack.
-- #
set_count(count)
+- #
set_count(count): Returns boolean whether item was cleared
- #
get_wear(): Returns tool wear (0-65535), 0 for non-tools.
-- #
set_wear(wear): Returns boolean success.
- Clears item on failure.
+- #
set_wear(wear): Returns boolean whether item was cleared
- #
get_metadata(): Returns metadata (a string attached to an item stack).
- #
set_metadata(metadata): Returns true.
- #
clear(): removes all items from the stack, making it empty.
@@ -3914,7 +3977,11 @@ will place the schematic inside of the VoxelManip.
- #expects lighting data in the same format that
get_light_data() returns
-#get_param2_data(): Gets the raw param2 data read into the VoxelManip object
+#get_param2_data([buffer]): Gets the raw param2 data read into the VoxelManip object
+
#set_param2_data(param2_data): Sets the param2 contents of each node in the VoxelManip
#calc_lighting([p1, p2], [propagate_shadow]): Calculate lighting within the VoxelManip
- #To be used only by a
VoxelManip object from minetest.get_mapgen_object
@@ -4013,14 +4080,16 @@ numeric unique decoration ID.
Registered entities
- #Functions receive a "luaentity" as
self:
-- #Callbacks:
-- #
on_activate(self, staticdata)
+- #Callbacks:
-- #
on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir
+- #
on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)
- Called when somebody punches the object.
- Note that you probably want to handle most punches using the
automatic armor group system.
@@ -4155,7 +4224,7 @@ minetest.spawn_tree(pos,apple_tree)
on_activate = function(self, staticdata, dtime_s),
on_step = function(self, dtime),
- on_punch = function(self, hitter),
+ on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir),
on_rightclick = function(self, clicker),
get_staticdata = function(self),
-- ^ Called sometimes; the string returned is passed to on_activate when
@@ -4240,15 +4309,18 @@ minetest.spawn_tree(pos,apple_tree)
on_place = func(itemstack, placer, pointed_thing),
--[[
^ Shall place item and return the leftover itemstack
+ ^ The placer may be any ObjectRef or nil.
^ default: minetest.item_place ]]
on_secondary_use = func(itemstack, user, pointed_thing),
--[[
^ Same as on_place but called when pointing at nothing.
+ ^ The user may be any ObjectRef or nil.
^ pointed_thing : always { type = "nothing" }
]]
on_drop = func(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 = func(itemstack, user, pointed_thing),
--[[
@@ -4257,6 +4329,7 @@ minetest.spawn_tree(pos,apple_tree)
inventory, 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.
]]
after_use = func(itemstack, user, node, digparams),
@@ -4269,6 +4342,7 @@ minetest.spawn_tree(pos,apple_tree)
itemstack:add_wear(digparams.wear)
return itemstack
end
+ ^ The user may be any ObjectRef or nil.
]]
}
{
deco_type = "simple", -- See "Decoration types"
place_on = "default:dirt_with_grass",
--- ^ Node that decoration can be placed on
+-- ^ Node (or list of nodes) that the decoration can be placed on
sidelen = 8,
-- ^ Size of divisions made in the chunk being generated.
-- ^ If the chunk size is not evenly divisible by sidelen, sidelen is made equal to the chunk size.
@@ -4601,6 +4678,13 @@ The Biome API is still in an experimental phase and subject to change.
-- ^ Minimum and maximum `y` positions these decorations can be generated at.
-- ^ This parameter refers to the `y` position of the decoration base, so
-- the actual maximum height would be `height_max + size.Y`.
+ spawn_by = "default:water",
+-- ^ Node (or list of nodes) that the decoration only spawns next to.
+-- ^ Checks two horizontal planes of neighbouring nodes (including diagonal neighbours),
+-- ^ one plane at Y = surface and one plane at Y = surface = + 1.
+ 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",
-- ^ Flags for all decoration types.
-- ^ "liquid_surface": Instead of placement on the highest solid surface
@@ -4618,13 +4702,6 @@ The Biome API is still in an experimental phase and subject to change.
height_max = 0,
-- ^ Number of nodes the decoration can be at maximum.
-- ^ If absent, the parameter 'height' is used as a constant.
- spawn_by = "default:water",
--- ^ Node that the decoration only spawns next to.
--- ^ The neighbours checked are the 8 nodes horizontally surrounding the lowest node of the
--- ^ decoration, and the 8 nodes horizontally surrounding the ground node below the decoration.
- 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.
----- Schematic-type parameters
schematic = "foobar.mts",
@@ -4755,6 +4832,8 @@ The Biome API is still in an experimental phase and subject to change.
collision_removal = false,
-- ^ collision_removal: if true then particle is removed when it collides,
-- ^ requires collisiondetection = true to have any effect
+ attached = ObjectRef,
+-- ^ attached: if defined, makes particle positions relative to this object.
vertical = false,
-- ^ vertical: if true faces player using y axis only
texture = "image.png",