-Minetest Lua Modding API Reference 0.4.dev
+Minetest Lua Modding API Reference 0.4.0
==========================================
More information at http://c55.me/minetest/
Startup
--------
Mods are loaded during server startup from the mod load paths by running
-the init.lua scripts.
+the init.lua scripts in a shared environment.
Mod load path
-------------
~/.minetest/mods/gameid/ <-- User-installed mods
~/.minetest/worlds/worldname/worldmods
+Mod load path for world-specific games
+--------------------------------------
+It is possible to include a game in a world; in this case, no mods or
+games are loaded or checked from anywhere else.
+
+This is useful for eg. adventure worlds.
+
+This happens if the following directory exists:
+ $world/game/
+
+Mods should be then be placed in:
+ $world/game/mods/
+
+Modpack support
+----------------
+Mods can be put in a subdirectory, if the parent directory, which otherwise
+should be a mod, contains a file named modpack.txt. This file shall be
+empty, except for lines starting with #, which are comments.
+
Mod directory structure
------------------------
mods
-- Play connected to an object, looped
{
object = <an ObjectRef>,
- gain = 1.0, -- default
- max_hear_distance = 32, -- default
+ gain = 1.0, -- default
+ max_hear_distance = 32, -- default
loop = true, -- only sounds connected to objects can be looped
}
-Representations of simple things
+SimpleSoundSpec:
+eg. ""
+eg. "default_place_node"
+eg. {}
+eg. {name="default_place_node"}
+eg. {name="default_place_node", gain=1.0}
+
+Registered definitions of stuff
--------------------------------
-MapNode representation:
- {name="name", param1=num, param2=num}
+Anything added using certain minetest.register_* functions get added to
+the global minetest.registered_* tables.
+
+minetest.register_entity(name, prototype table)
+ -> minetest.registered_entities[name]
+
+minetest.register_node(name, node definition)
+ -> minetest.registered_items[name]
+ -> minetest.registered_nodes[name]
+
+minetest.register_tool(name, item definition)
+ -> minetest.registered_items[name]
+
+minetest.register_craftitem(name, item definition)
+ -> minetest.registered_items[name]
+
+Note that in some cases you will stumble upon things that are not contained
+in these tables (eg. when a mod has been removed). Always check for
+existence before trying to access the fields.
+
+Example: If you want to check the drawtype of a node, you could do:
+
+local function get_nodedef_field(nodename, fieldname)
+ if not minetest.registered_nodes[nodename] then
+ return nil
+ end
+ return minetest.registered_nodes[nodename][fieldname]
+end
+local drawtype = get_nodedef_field(nodename, "drawtype")
+
+Example: minetest.get_item_group(name, group) has been implemented as:
-MapNodes do not directly have any other data associated with them.
-If you want to access the definition of the node, you access
+function minetest.get_item_group(name, group)
+ if not minetest.registered_items[name] or not
+ minetest.registered_items[name].groups[group] then
+ return 0
+ end
+ return minetest.registered_items[name].groups[group]
+end
+
+Nodes
+------
+Nodes are the bulk data of the world: cubes and other things that take the
+space of a cube. Huge amounts of them are handled efficiently, but they
+are quite static.
+
+The definition of a node is stored and can be accessed by name in
minetest.registered_nodes[node.name]
+See "Registered definitions of stuff".
-param1 and param2 are 8 bit and 4 bit integers, respectively. They
-are reserved for certain automated functions. If you don't use these
+Nodes are passed by value between Lua and the engine.
+They are represented by a table:
+ {name="name", param1=num, param2=num}
+
+param1 and param2 are 8 bit and 4 bit integers, respectively. The engine
+uses them for certain automated functions. If you don't use these
functions, you can use them to store arbitrary values.
-param1 is reserved for the engine when:
- paramtype != "none"
+The functions of param1 and param2 are determined by certain fields in the
+node definition:
+param1 is reserved for the engine when paramtype != "none":
+ paramtype = "light"
+ ^ The value stores light with and without sun in it's
+ upper and lower 4 bits.
param2 is reserved for the engine when any of these are used:
liquidtype == "flowing"
+ ^ The level and some flags of the liquid is stored in param2
drawtype == "flowingliquid"
+ ^ The drawn liquid level is read from param2
drawtype == "torchlike"
drawtype == "signlike"
+ paramtype2 == "wallmounted"
+ ^ The rotation of the node is stored in param2. You can make this value
+ by using minetest.dir_to_wallmounted().
+ paramtype2 == "facedir"
+ ^ The rotation of the node is stored in param2. Furnaces and chests are
+ rotated this way. Can be made by using minetest.dir_to_facedir().
+
+Nodes can also contain extra data. See "Node Metadata".
+
+Node drawtypes
+---------------
+There are a bunch of different looking node types. These are mostly just
+copied from Minetest 0.3; more may be made in the future.
+
+Look for examples in games/minimal or games/minetest_game.
+
+- normal
+- airlike
+- liquid
+- flowingliquid
+- glasslike
+- allfaces
+- allfaces_optional
+- torchlike
+- signlike
+- plantlike
+- fencelike
+- raillike
+- nodebox -- See below. EXPERIMENTAL
+
+Node boxes
+-----------
+Node selection boxes are defined using "node boxes"
+
+The "nodebox" node drawtype allows defining visual of nodes consisting of
+arbitrary number of boxes. It allows defining stuff like stairs. Only the
+"fixed" box type is supported for these.
+^ Please note that this is still experimental, and may be incompatibly
+ changed in the future.
+
+A nodebox is defined as any of:
+{
+ -- A normal cube; the default in most things
+ type = "regular"
+}
+{
+ -- A fixed box (facedir param2 is used, if applicable)
+ type = "fixed",
+ 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 box is defined as:
+ {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},
+
+Representations of simple things
+--------------------------------
Position/vector:
{x=num, y=num, z=num}
Currently the API does not provide any helper functions for addition,
subtraction and whatever; you can define those that you need yourself.
-stackstring/itemstring: A stack of items in serialized format.
+pointed_thing:
+ {type="nothing"}
+ {type="node", under=pos, above=pos}
+ {type="object", ref=ObjectRef}
+
+Items
+------
+Node (register_node):
+ A node from the world
+Tool (register_tool):
+ A tool/weapon that can dig and damage things according to tool_capabilities
+Craftitem (register_craftitem):
+ A miscellaneous item
+
+Items and item stacks can exist in three formats:
+
+Serialized; This is called stackstring or itemstring:
eg. 'default:dirt 5'
eg. 'default:pick_wood 21323'
eg. 'default:apple'
-item: A stack of items in Lua table format.
+Table format:
eg. {name="default:dirt", count=5, wear=0, metadata=""}
^ 5 dirt nodes
eg. {name="default:pick_wood", count=1, wear=21323, metadata=""}
eg. {name="default:apple", count=1, wear=0, metadata=""}
^ an apple.
-Any time an item must be passed to a function, it can be an
-ItemStack (see below), an itemstring or a table in the above format.
+ItemStack:
+C++ native format with many helper methods. Useful for converting between
+formats. See the Class reference section for details.
-SimpleSoundSpec:
-eg. ""
-eg. "default_place_node"
-eg. {}
-eg. {name="default_place_node"}
-eg. {name="default_place_node", gain=1.0}
-
-Items
-------
-Node (register_node):
- A node from the world
-Tool (register_tool):
- A tool/weapon that can dig and damage things according to tool_capabilities
-Craftitem (register_craftitem):
- A miscellaneous item
+When an item must be passed to a function, it can usually be in any of
+these formats.
Groups
-------
- When not defined, the rating of a group defaults to 0. Thus when you
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)
+
Groups of items
----------------
Groups of items can define what kind of an item it is (eg. wool).
Groups of nodes
----------------
-In addition to the general item things, whether a node is diggable and how
-long it takes is defined by using groups.
+In addition to the general item things, groups are used to define whether
+a node is destroyable and how long it takes to destroy by a tool.
Groups of entities
-------------------
Groups in crafting recipes
---------------------------
-- Not implemented yet. (TODO)
-- Will probably look like this:
+An example:
{
output = 'food:meat_soup_raw',
recipe = {
{'group:water'},
{'group:bowl'},
},
- preserve = {'group:bowl'},
+ preserve = {'group:bowl'}, -- Not implemented yet (TODO)
}
Special groups
damage, and get weared out much faster, or not be able to get drops
from destroyed nodes.
- 0 is something that is directly accessible at the start of gameplay
+ - There is no upper limit
- dig_immediate: (player can always pick up node without tool wear)
- 2: node is removed without tool wear after 0.5 seconds or so
(rail, sign)
Known damage and digging time defining groups
----------------------------------------------
+Valid ratings for these are 0, 1, 2 and 3, unless otherwise stated.
- crumbly: dirt, sand
- cracky: tough but crackable stuff like stone.
- snappy: something that can be cut using fine tools; eg. leaves, small
Can be added to nodes that shouldn't logically be breakable by the
hand but are. Somewhat similar to dig_immediate, but times are more
like {[1]=3.50,[2]=2.00,[3]=0.70} and this does not override the
- speed of a tool if the tool can dig at a larger speed than this
+ speed of a tool if the tool can dig at a faster speed than this
suggests for the hand.
Examples of custom groups
purpose. Rating is 1, 2 or 3. A higher rating for such a group implies
faster digging time.
-Also, the **level** group is used.
+The **level** group is used to limit the toughness of nodes a tool can dig
+and to scale the digging times / damage to a greater extent.
+
+^ PLEASE DO UNDERSTAND THIS, otherwise you cannot use the system to it's
+ full potential.
Tools define their properties by a list of parameters for groups. They
cannot dig other groups; thus it is important to use a standard bunch of
groups to enable interaction with tools.
-**Example definition of the digging capabilities of a tool:**
+**Tools define:**
+ * Full punch interval
+ * Maximum drop level
+ * For an arbitrary list of groups:
+ * Uses (until the tool breaks)
+ * Maximum level (usually 0, 1, 2 or 3)
+ * Digging times
+
+**Full punch interval**:
+When used as a weapon, the tool will do full damage if this time is spent
+between punches. If eg. half the time is spent, the tool will do half
+damage.
+
+**Maximum drop level**
+Suggests the maximum level of node, when dug with the tool, that will drop
+it's useful item. (eg. iron ore to drop a lump of iron).
+- This is not automated; it is the responsibility of the node definition
+ to implement this
+
+**Uses**
+Determines how many uses the tool has when it is used for digging a node,
+of this group, of the maximum level. For lower leveled nodes, the use count
+is multiplied by 3^leveldiff.
+- uses=10, leveldiff=0 -> actual uses: 10
+- uses=10, leveldiff=1 -> actual uses: 30
+- uses=10, leveldiff=2 -> actual uses: 90
+
+**Maximum level**
+Tells what is the maximum level of a node of this group that the tool will
+be able to dig.
+
+**Digging times**
+List of digging times for different ratings of the group, for nodes of the
+maximum level.
+ * For example, as a lua table, ''times={2=2.00, 3=0.70}''. This would
+ result in the tool to be able to dig nodes that have a rating of 2 or 3
+ for this group, and unable to dig the rating 1, which is the toughest.
+ Unless there is a matching group that enables digging otherwise.
+ * For entities, damage equals the amount of nodes dug in the time spent
+ between hits, with a maximum time of ''full_punch_interval''.
+
+Example definition of the capabilities of a tool
+-------------------------------------------------
tool_capabilities = {
full_punch_interval=1.5,
max_drop_level=1,
groupcaps={
- crumbly={maxwear=0.01, maxlevel=2, times={[1]=0.80, [2]=0.60, [3]=0.40}}
+ crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
}
}
-**Tools define:**
- * Full punch interval Maximum drop level For an arbitrary list of groups:
- * Maximum level (usually 0, 1, 2 or 3) Maximum wear (0...1) Digging times
-
-**Full punch interval**: When used as a weapon, the tool will do full
-damage if this time is spent between punches. If eg. half the time is
-spent, the tool will do half damage.
-
-**Maximum drop level** suggests the maximum level of node, when dug with
-the tool, that will drop it's useful item. (eg. iron ore to drop a lump of
-iron).
-
-**Maximum level** tells what is the maximum level of a node of this group
-that the tool will be able to dig.
-
-**Maximum wear** determines how much the tool wears out when it is used for
-digging a node, of this group, of the maximum level. For lower leveled
-tools, the wear is divided by //4// to the exponent //level difference//.
-This means for a maximum wear of 0.1, a level difference 1 will result in
-wear=0.1/4=0.025, and a level difference of 2 will result in
-wear=0.1/(4*4)=0.00625.
-
-**Digging times** is basically a list of digging times for different
-ratings of the group. It also determines the damage done to entities, based
-on their "armor groups".
- * For example, as a lua table, ''times={2=2.00, 3=0.70}''. This would
- * result the tool to be able to dig nodes that have a rating of 2 or 3
- * for this group, and unable to dig the rating 1, which is the toughest.
- * Unless there is a matching group that enables digging otherwise. For
- * entities, damage equals the amount of nodes dug in the time spent
- * between hits, with a maximum of ''full_punch_interval''.
+This makes the tool be able to dig nodes that fullfill both of these:
+- Have the **crumbly** group
+- Have a **level** group less or equal to 2
+
+Table of resulting digging times:
+crumbly 0 1 2 3 4 <- level
+ -> 0 - - - - -
+ 1 0.80 1.60 1.60 - -
+ 2 0.60 1.20 1.20 - -
+ 3 0.40 0.80 0.80 - -
+
+level diff: 2 1 0 -1 -2
+
+Table of resulting tool uses:
+ -> 0 - - - - -
+ 1 180 60 20 - -
+ 2 180 60 20 - -
+ 3 180 60 20 - -
+
+Notes:
+- At crumbly=0, the node is not diggable.
+- At crumbly=3, the level difference digging time divider kicks in and makes
+ easy nodes to be quickly breakable.
+- At level > 2, the node is not diggable, because it's level > maxlevel
Entity damage mechanism
------------------------
+Damage calculation:
+- Take the time spent after the last hit
+- Limit time to full_punch_interval
+- Take the damage groups and imagine a bunch of nodes that have them
+- Damage in HP is the amount of nodes destroyed in this time.
+
Client predicts damage based on damage groups. Because of this, it is able to
give an immediate response when an entity is damaged or dies; the response is
pre-defined somehow (eg. by defining a sprite animation) (not implemented;
TODO).
+- Currently a smoke puff will appear when an entity dies.
-The group **immortal** will completely disable normal damage.
+The group **immortal** completely disables normal damage.
Entities can define a special armor group, which is **punch_operable**. This
-group will disable the regular damage mechanism for players punching it by hand
-or a non-tool item.
+group disables the regular damage mechanism for players punching it by hand or
+a non-tool item, so that it can do something else than take damage.
On the Lua side, every punch calls ''entity:on_punch(puncher,
time_from_last_punch, tool_capabilities, direction)''. This should never be
called directly, because damage is usually not handled by the entity itself.
* ''puncher'' is the object performing the punch. Can be nil. Should never be
- accessed unless absolutely required.
+ accessed unless absolutely required, to encourage interoperability.
* ''time_from_last_punch'' is time from last punch (by puncher) or nil.
* ''tool_capabilities'' can be nil.
* ''direction'' is a unit vector, pointing from the source of the punch to
the punched object.
-To punch an entity/object in Lua, call ''object:punch(puncher, time_from_last_punch, tool_capabilities, direction)''.
+To punch an entity/object in Lua, call ''object:punch(puncher,
+time_from_last_punch, tool_capabilities, direction)''.
* Return value is tool wear.
* Parameters are equal to the above callback.
* If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be
automatically filled in based on the location of ''puncher''.
+Node Metadata
+-------------
+The instance of a node in the world normally only contains the three values
+mentioned in "Nodes". However, it is possible to insert extra data into a
+node. It is called "node metadata"; See "NodeMetaRef".
+
+Metadata contains two things:
+- A key-value store
+- An inventory
+
+Some of the values in the key-value store are handled specially:
+- formspec: Defines a right-click inventory menu. See "Formspec".
+- infotext: Text shown on the screen when the node is pointed at
+
+Example stuff:
+
+local meta = minetest.env:get_meta(pos)
+meta:set_string("formspec",
+ "invsize[8,9;]"..
+ "list[context;main;0,0;8,4;]"..
+ "list[current_player;main;0,5;8,4;]")
+meta:set_string("infotext", "Chest");
+local inv = meta:get_inventory()
+inv:set_size("main", 8*4)
+print(dump(meta:to_table()))
+meta:from_table({
+ inventory = {
+ 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] = ""}
+ },
+ fields = {
+ formspec = "invsize[8,9;]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
+ infotext = "Chest"
+ }
+})
+
+Formspec
+--------
+Formspec defines a menu. Currently not much else than inventories are
+supported. It is a string, with a somewhat strange format.
+
+Spaces and newlines can be inserted between the blocks, as is used in the
+examples.
+
+Examples:
+- Chest:
+ invsize[8,9;]
+ list[context;main;0,0;8,4;]
+ list[current_player;main;0,5;8,4;]
+- Furnace:
+ invsize[8,9;]
+ list[context;fuel;2,3;1,1;]
+ list[context;src;2,1;1,1;]
+ list[context;dst;5,1;2,2;]
+ list[current_player;main;0,5;8,4;]
+- Minecraft-like player inventory
+ invsize[8,7.5;]
+ image[1,0.6;1,2;player.png]
+ list[current_player;main;0,3.5;8,4;]
+ list[current_player;craft;3,0;3,3;]
+ list[current_player;craftpreview;7,1;1,1;]
+
+Elements:
+
+invsize[<W>,<H>;]
+^ Define the size of the menu in inventory slots
+
+list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]
+^ Show an inventory list
+
+image[<X>,<Y>;<W>,<H>;<texture name>]
+^ Show an image
+^ Position and size units are inventory slots
+
+field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
+^ Textual field; will be sent to server when a button is clicked
+^ Position and size units are inventory slots
+^ Not implemented
+
+button[<X>,<Y>;<W>,<H>;<name>;<label>]
+^ Clickable button. When clicked, fields will be sent.
+^ Button will be visible as a field, with the value "active".
+^ Position and size units are inventory slots
+^ Not implemented
+
+Inventory location:
+- "context": Selected node metadata (deprecated: "current_name")
+- "current_player": Player to whom the menu is shown
+- "player:<name>": Any player
+- "nodemeta:<X>,<Y>,<Z>": Any node metadata
+
Helper functions
-----------------
dump2(obj, name="_", dumped={})
^ Return object serialized as a string, handles reference loops
dump(obj, dumped={})
^ Return object serialized as a string
+string:split(separator)
+^ eg. string:split("a,b", ",") == {"a","b"}
+string:trim()
+^ eg. string.trim("\n \t\tfoo bar\t ") == "foo bar"
+minetest.pos_to_string({x=X,y=Y,z=Z}) -> "(X,Y,Z)"
+^ Convert position to a printable string
+minetest.string_to_pos(string) -> position
minetest namespace reference
-----------------------------
minetest.get_current_modname() -> string
minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
^ Useful for loading additional .lua modules or static data from mod
-minetest.get_worldpath(modname) -> eg. "/home/user/.minetest/world"
+minetest.get_modnames() -> list of installed mods
+^ Return a list of installed mods, sorted alphabetically
+minetest.get_worldpath() -> eg. "/home/user/.minetest/world"
^ Useful for storing custom data
+minetest.is_singleplayer()
minetest.debug(line)
-^ Goes to dstream
+^ Always printed to stderr and logfile (print() is redirected here)
minetest.log(line)
minetest.log(loglevel, line)
^ loglevel one of "error", "action", "info", "verbose"
+Registration functions: (Call these only at load time)
minetest.register_entity(name, prototype table)
minetest.register_abm(abm definition)
minetest.register_node(name, node definition)
minetest.register_alias(name, convert_to)
minetest.register_craft(recipe)
+Global callback registration functions: (Call these only at load time)
minetest.register_globalstep(func(dtime))
+^ Called every server step, usually interval of 0.05s
minetest.register_on_placenode(func(pos, newnode, placer))
+^ Called when a node has been placed
+^ Deprecated: Use on_construct or after_place_node in node definition instead
minetest.register_on_dignode(func(pos, oldnode, digger))
+^ Called when a node has been dug. digger can be nil.
+^ Deprecated: Use on_destruct or after_dig_node in node definition instead
minetest.register_on_punchnode(func(pos, node, puncher))
-minetest.register_on_generated(func(minp, maxp))
+^ Called when a node is punched
+minetest.register_on_generated(func(minp, maxp, blockseed))
+^ Called after generating a piece of world. Modifying nodes inside the area
+ is a bit faster than usually.
minetest.register_on_newplayer(func(ObjectRef))
+^ Called after a new player has been created
minetest.register_on_dieplayer(func(ObjectRef))
+^ Called when a player dies
minetest.register_on_respawnplayer(func(ObjectRef))
+^ Called when player is to be respawned
+^ Called _before_ repositioning of player occurs
^ return true in func to disable regular player placement
-^ currently called _before_ repositioning of player occurs
+minetest.register_on_joinplayer(func(ObjectRef))
+^ Called when a player joins the game
+minetest.register_on_leaveplayer(func(ObjectRef))
+^ Called when a player leaves the game
minetest.register_on_chat_message(func(name, message))
-minetest.add_to_creative_inventory(itemstring)
+Other registration functions:
+minetest.register_chatcommand(cmd, chatcommand definition)
+minetest.register_privilege(name, definition)
+^ definition: "description text"
+^ definition: {
+ description = "description text",
+ give_to_singleplayer = boolean, -- default: true
+ }
+minetest.register_authentication_handler(handler)
+^ See minetest.builtin_auth_handler in builtin.lua for reference
+
+Setting-related:
+minetest.setting_set(name, value)
minetest.setting_get(name) -> string or nil
minetest.setting_getbool(name) -> boolean value or nil
+minetest.setting_get_pos(name) -> position or nil
+minetest.add_to_creative_inventory(itemstring)
+Authentication:
+minetest.notify_authentication_modified(name)
+^ Should be called by the authentication handler if privileges change.
+^ To report everybody, set name=nil.
+minetest.get_password_hash(name, raw_password)
+^ Convert a name-password pair to a password hash that minetest can use
+minetest.string_to_privs(str) -> {priv1=true,...}
+minetest.privs_to_string(privs) -> "priv1,priv2,..."
+^ Convert between two privilege representations
+minetest.set_player_password(name, password_hash)
+minetest.set_player_privs(name, {priv1=true,...})
+minetest.get_player_privs(name) -> {priv1=true,...}
+minetest.auth_reload()
+^ These call the authentication handler
+minetest.check_player_privs(name, {priv1=true,...}) -> bool, missing_privs
+^ A quickhand for checking privileges
+
+Chat:
minetest.chat_send_all(text)
minetest.chat_send_player(name, text)
-minetest.get_player_privs(name) -> set of privs
+
+Inventory:
minetest.get_inventory(location) -> InvRef
^ location = eg. {type="player", name="celeron55"}
{type="node", pos={x=, y=, z=}}
+Item handling:
+minetest.inventorycube(img1, img2, img3)
+^ Returns a string for making an image of a cube (useful as an item image)
+minetest.get_pointed_thing_position(pointed_thing, above)
+^ Get position of a pointed_thing (that you can get from somewhere)
+minetest.dir_to_facedir(dir)
+^ Convert a vector to a facedir value, used in param2 for paramtype2="facedir"
+minetest.dir_to_wallmounted(dir)
+^ Convert a vector to a wallmounted value, used for paramtype2="wallmounted"
+minetest.get_node_drops(nodename, toolname)
+^ Returns list of item names.
+^ Note: This will be removed or modified in a future version.
+minetest.get_craft_result(input) -> output, decremented_input
+^ input.method = 'normal' or 'cooking' or 'fuel'
+^ input.width = for example 3
+^ input.items = for example { stack 1, stack 2, stack 3, stack 4,
+ stack 5, stack 6, stack 7, stack 8, stack 9 }
+^ output.item = ItemStack, if unsuccessful: empty ItemStack
+^ output.time = number, if unsuccessful: 0
+^ decremented_input = like input
+minetest.get_craft_recipe(output) -> input
+^ output is a node or item type such as 'default:torch'
+^ input.method = 'normal' or 'cooking' or 'fuel'
+^ input.width = for example 3
+^ input.items = for example { stack 1, stack 2, stack 3, stack 4,
+ stack 5, stack 6, stack 7, stack 8, stack 9 }
+^ input.items = nil if no recipe found
+
+Defaults for the on_* item definition functions:
+(These return the leftover itemstack)
+minetest.item_place_node(itemstack, placer, pointed_thing)
+^ Place item as a node
+minetest.item_place_object(itemstack, placer, pointed_thing)
+^ Place item as-is
+minetest.item_place(itemstack, placer, pointed_thing)
+^ Use one of the above based on what the item is.
+minetest.item_drop(itemstack, dropper, pos)
+^ Drop the item
+minetest.item_eat(hp_change, replace_with_item)
+^ Eat the item. replace_with_item can be nil.
+
+Defaults for the on_punch and on_dig node definition callbacks:
+minetest.node_punch(pos, node, puncher)
+^ Calls functions registered by minetest.register_on_punchnode()
+minetest.node_dig(pos, node, digger)
+^ Checks if node can be dug, puts item into inventory, removes node
+^ Calls functions registered by minetest.registered_on_dignodes()
+
+Sounds:
minetest.sound_play(spec, parameters) -> handle
^ spec = SimpleSoundSpec
^ parameters = sound parameter table
minetest.sound_stop(handle)
+Timing:
minetest.after(time, func, param)
^ Call function after time seconds
^ param is optional; to pass multiple parameters, pass a table.
+Random:
+minetest.get_connected_players() -> list of ObjectRefs
+minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer
+^ Gives a unique hash number for a node position (16+16+16=48bit)
+minetest.get_item_group(name, group) -> rating
+^ Get rating of a group of an item. (0 = not in group)
+minetest.get_node_group(name, group) -> rating
+^ Deprecated: An alias for the former.
+minetest.serialize(table) -> string
+^ Convert a table containing tables, strings, numbers, booleans and nils
+ into string form readable by minetest.deserialize
+^ Example: serialize({foo='bar'}) -> 'return { ["foo"] = "bar" }'
+minetest.deserialize(string) -> table
+^ Convert a string returned by minetest.deserialize into a table
+^ String is loaded in an empty sandbox environment.
+^ Will load functions, but they cannot access the global environment.
+^ Example: deserialize('return { ["foo"] = "bar" }') -> {foo='bar'}
+^ Example: deserialize('print("foo")') -> nil (function call fails)
+ ^ error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)
+
Global objects:
-minetest.env - environment reference
+minetest.env - EnvRef of the server environment and world.
+^ Using this you can access nodes and entities
Global tables:
minetest.registered_items
----------------
EnvRef: basically ServerEnvironment and ServerMap combined.
methods:
-- add_node(pos, node)
+- set_node(pos, node)
+- add_node(pos, node): alias set_node(pos, node)
+ ^ Set node at position (node = {name="foo", param1=0, param2=0})
- remove_node(pos)
+ ^ Equivalent to set_node(pos, "air")
- get_node(pos)
^ Returns {name="ignore", ...} for unloaded area
- get_node_or_nil(pos)
^ Returns nil for unloaded area
- get_node_light(pos, timeofday) -> 0...15 or nil
^ timeofday: nil = current time, 0 = night, 0.5 = day
-- add_entity(pos, name): Returns ObjectRef or nil if failed
-- add_item(pos, itemstring)
-- add_rat(pos)
-- add_firefly(pos)
+
+- place_node(pos, node)
+ ^ Place node with the same effects that a player would cause
+- dig_node(pos)
+ ^ Dig node with the same effects that a player would cause
+- punch_node(pos)
+ ^ Punch node with the same effects that a player would cause
+
+- add_entity(pos, name): Spawn Lua-defined entity at position
+ ^ Returns ObjectRef, or nil if failed
+- add_item(pos, item): Spawn item
+ ^ Returns ObjectRef, or nil if failed
- get_meta(pos) -- Get a NodeMetaRef at that position
- get_player_by_name(name) -- Get an ObjectRef to a player
- get_objects_inside_radius(pos, radius)
- set_timeofday(val): val: 0...1; 0 = midnight, 0.5 = midday
- get_timeofday()
-
-NodeMetaRef (this stuff is subject to change in a future version)
+- find_node_near(pos, radius, nodenames) -> pos or nil
+ ^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
+- find_nodes_in_area(minp, maxp, nodenames) -> list of positions
+ ^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
+- get_perlin(seeddiff, octaves, persistence, scale)
+ ^ Return world-specific perlin noise (int(worldseed)+seeddiff)
+Deprecated:
+- add_rat(pos): Add C++ rat object (no-op)
+- add_firefly(pos): Add C++ firefly object (no-op)
+
+NodeMetaRef: Node metadata - reference extra data and functionality stored
+ in a node
+- Can be gotten via minetest.env:get_nodemeta(pos)
methods:
-- get_type()
-- allows_text_input()
-- set_text(text) -- eg. set the text of a sign
-- get_text()
-- get_owner()
-- set_owner(string)
-Generic node metadata specific:
-- set_infotext(infotext)
-- get_inventory() -> InvRef
-- set_inventory_draw_spec(string)
-- set_allow_text_input(bool)
-- set_allow_removal(bool)
-- set_enforce_owner(bool)
-- is_inventory_modified()
-- reset_inventory_modified()
-- is_text_modified()
-- reset_text_modified()
- set_string(name, value)
- get_string(name)
+- set_int(name, value)
+- get_int(name)
+- set_float(name, value)
+- get_float(name)
+- get_inventory() -> InvRef
+- to_table() -> nil or {fields = {...}, inventory = {list1 = {}, ...}}
+- from_table(nil or {})
+ ^ See "Node Metadata"
ObjectRef: Moving things in the game are generally these
(basically reference to a C++ ServerActiveObject)
- get_wield_index(): returns the index of the wielded item
- get_wielded_item() -> ItemStack
- set_wielded_item(item): replaces the wielded item, returns true if successful
+- set_armor_groups({group1=rating, group2=rating, ...})
+- set_properties(object property table)
LuaEntitySAO-only: (no-op for other objects)
- setvelocity({x=num, y=num, z=num})
- getvelocity() -> {x=num, y=num, z=num}
- settexturemod(mod)
- setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
- select_horiz_by_yawpitch=false)
-- ^ Select sprite from spritesheet with optional animation and DM-style
-- texture selection based on yaw relative to camera
-- set_armor_groups({group1=rating, group2=rating, ...})
+ ^ Select sprite from spritesheet with optional animation and DM-style
+ texture selection based on yaw relative to camera
- get_entity_name() (DEPRECATED: Will be removed in a future version)
- get_luaentity()
Player-only: (no-op for other objects)
-- get_player_name(): will return nil if is not a player
+- is_player(): true for players, false for others
+- get_player_name(): returns "" if is not a player
- get_look_dir(): get camera direction as a unit vector
- get_look_pitch(): pitch in radians
- get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
+- set_inventory_formspec(formspec)
+ ^ Redefine player's inventory form
+ ^ Should usually be called in on_joinplayer
+- get_inventory_formspec() -> formspec string
InvRef: Reference to an inventory
methods:
+- is_empty(listname): return true if list is empty
- get_size(listname): get size of a list
- set_size(listname, size): set size of a list
- get_stack(listname, i): get a copy of stack index i in list
PseudoRandom: A pseudorandom number generator
- Can be created via PseudoRandom(seed)
methods:
-- next(): return next random number [0...32767]
+- next(): return next integer random number [0...32767]
+- next(min, max): return next integer random number [min...max]
+ (max - min) must be 32767 or <= 6553 due to the simple
+ implementation making bad distribution otherwise.
+
+PerlinNoise: A perlin noise generator
+- Can be created via PerlinNoise(seed, octaves, persistence, scale)
+- Also minetest.env:get_perlin(seeddiff, octaves, persistence, scale)
+methods:
+- get2d(pos) -> 2d noise value at pos={x=,y=}
+- get3d(pos) -> 3d noise value at pos={x=,y=,z=}
Registered entities
--------------------
Definition tables
------------------
-Entity definition (register_entity)
+Object Properties
{
+ hp_max = 1,
physical = true,
+ weight = 5,
collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
- visual = "cube"/"sprite",
+ visual = "cube"/"sprite"/"upright_sprite",
visual_size = {x=1, y=1},
- textures = {texture,texture,texture,texture,texture,texture},
+ textures = {}, -- number of required textures depends on visual
spritediv = {x=1, y=1},
initial_sprite_basepos = {x=0, y=0},
+ is_visible = true,
+ makes_footstep_sound = false,
+ automatic_rotate = false,
+}
+
+Entity definition (register_entity)
+{
+ (Deprecated: Everything in object properties is read directly from here)
+
+ initial_properties = <initial object properties>,
+
on_activate = function(self, staticdata),
on_step = function(self, dtime),
on_punch = function(self, hitter),
on_rightclick = function(self, clicker),
get_staticdata = function(self),
+ ^ Called sometimes; the string returned is passed to on_activate when
+ the entity is re-activated from static state
+
# Also you can define arbitrary member variables here
myvariable = whatever,
}
ABM (ActiveBlockModifier) definition (register_abm)
{
+ -- In the following two fields, also group:groupname will work.
nodenames = {"default:lava_source"},
neighbors = {"default:water_source", "default:water_flowing"}, -- (any of these)
^ If left out or empty, any neighbor will do
choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
}
}
- on_drop = func(item, dropper, pos),
- on_place = func(item, placer, pointed_thing),
- on_use = func(item, user, pointed_thing),
+ 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
+ actual result to client in a short moment.
+
+ on_place = func(itemstack, placer, pointed_thing),
+ ^ Shall place item and return the leftover itemstack
+ ^ default: minetest.item_place
+ on_drop = func(itemstack, dropper, pos),
+ ^ Shall drop item and return the leftover itemstack
+ ^ default: minetest.item_drop
+ on_use = func(itemstack, user, pointed_thing),
+ ^ default: nil
+ ^ Function must return either nil if no item shall be removed from
+ inventory, or an itemstack to replace the original itemstack.
+ eg. itemstack:take_item(); return itemstack
+ ^ Otherwise, the function is free to do what it wants.
+ ^ The default functions handle regular use cases.
}
+Tile definition:
+- "image.png"
+- {name="image.png", animation={Tile Animation definition}}
+- {name="image.png", backface_culling=bool}
+ ^ backface culling only supported in special tiles
+- deprecated still supported field names:
+ - image -> name
+
+Tile animation definition:
+- {type="vertical_frames", aspect_w=16, aspect_h=16, length=3.0}
+
Node definition (register_node)
{
<all fields allowed in item definitions>,
- drawtype = "normal",
+ drawtype = "normal", -- See "Node drawtypes"
visual_scale = 1.0,
- tile_images = {"default_unknown_block.png"},
- special_materials = {
- {image="", backface_culling=true},
- {image="", backface_culling=true},
- },
+ tiles = {tile definition 1, def2, def3, def4, def5, def6},
+ ^ List can be shortened to needed length
+ ^ Old field name: tile_images
+ special_tiles = {tile definition 1, Tile definition 2},
+ ^ List can be shortened to needed length
+ ^ Old field name: special_materials
alpha = 255,
post_effect_color = {a=0, r=0, g=0, b=0},
paramtype = "none",
buildable_to = false,
drop = "",
-- alternatively drop = { max_items = ..., items = { ... } }
- metadata_name = "",
liquidtype = "none",
liquid_alternative_flowing = "",
liquid_alternative_source = "",
liquid_viscosity = 0,
light_source = 0,
damage_per_second = 0,
- selection_box = {type="regular"},
+ node_box = {type="regular"}, -- See "Node boxes"
+ selection_box = {type="regular"}, -- See "Node boxes"
legacy_facedir_simple = false, -- Support maps made in and before January 2012
legacy_wallmounted = false, -- Support maps made in and before January 2012
sounds = {
dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
dug = <SimpleSoundSpec>,
},
+
+ on_construct = func(pos),
+ ^ Node constructor; always called after adding node
+ ^ Can set up metadata and stuff like that
+ ^ default: nil
+ on_destruct = func(pos),
+ ^ Node destructor; always called before removing node
+ ^ default: nil
+ after_destruct = func(pos, oldnode),
+ ^ Node destructor; always called after removing node
+ ^ default: nil
+
+ after_place_node = func(pos, placer),
+ ^ Called after constructing node when node was placed using
+ minetest.item_place_node / minetest.env:place_node
+ ^ default: nil
+ after_dig_node = func(pos, oldnode, oldmetadata, digger),
+ ^ oldmetadata is in table format
+ ^ Called after destructing node when node was dug using
+ minetest.node_dig / minetest.env:dig_node
+ ^ default: nil
+ can_dig = function(pos,player)
+ ^ returns true if node can be dug, or false if not
+ ^ default: nil
+
+ on_punch = func(pos, node, puncher),
+ ^ default: minetest.node_punch
+ ^ By default: does nothing
+ on_dig = func(pos, node, digger),
+ ^ default: minetest.node_dig
+ ^ By default: checks privileges, wears out tool and removes node
+
+ on_receive_fields = func(pos, formname, fields, sender),
+ ^ fields = {name1 = value1, name2 = value2, ...}
+ ^ Called when an UI form (eg. sign text input) returns data
+ ^ default: nil
+
+ on_metadata_inventory_move = func(pos, from_list, from_index,
+ to_list, to_index, count, player),
+ ^ Called when a player wants to move items inside the metadata
+ ^ Should move items, or some items, if permitted. If not, should do
+ nothing.
+ ^ The engine ensures the action is valid, i.e. the stack fits at the
+ given position
+ ^ default: minetest.node_metadata_inventory_move_allow_all
+
+ on_metadata_inventory_offer = func(pos, listname, index, stack, player),
+ ^ Called when a player wants to put something into the metadata
+ inventory
+ ^ Should check if the action is permitted (the engine ensures the
+ action is valid, i.e. the stack fits at the given position)
+ ^ If permitted, modify the metadata inventory and return the
+ "leftover" stack (normally nil).
+ ^ If not permitted, return itemstack.
+ ^ default: minetest.node_metadata_inventory_offer_allow_all
+
+ on_metadata_inventory_take = func(pos, listname, index, count, player),
+ ^ Called when a player wants to take something out of the metadata
+ inventory
+ ^ Should check if the action is permitted (the engine ensures the
+ action is valid, i.e. there's a stack of at least “count” items at
+ that position)
+ ^ If permitted, modify the metadata inventory and return the
+ stack of items
+ ^ If not permitted, return nil.
+ ^ default: minetest.node_metadata_inventory_take_allow_all
}
-Recipe: (register_craft)
+Recipe for register_craft: (shaped)
{
output = 'default:pick_stone',
recipe = {
{'default:cobble', 'default:cobble', 'default:cobble'},
{'', 'default:stick', ''},
- {'', 'default:stick', ''},
+ {'', 'default:stick', ''}, -- Also groups; eg. 'group:crumbly'
},
replacements = <optional list of item pairs,
replace one input item with another item on crafting>
}
-Recipe (shapeless):
+Recipe for register_craft (shapeless)
{
type = "shapeless",
output = 'mushrooms:mushroom_stew',
replace one input item with another item on crafting>
}
-Recipe (tool repair):
+Recipe for register_craft (tool repair)
{
type = "toolrepair",
additional_wear = -0.02,
}
-Recipe (cooking):
+Recipe for register_craft (cooking)
{
type = "cooking",
output = "default:glass",
cooktime = 3,
}
-Recipe (furnace fuel):
+Recipe for register_craft (furnace fuel)
{
type = "fuel",
recipe = "default:leaves",
burntime = 1,
}
+Chatcommand definition (register_chatcommand)
+{
+ params = "<name> <privilege>", -- short parameter description
+ description = "Remove privilege from player", -- full description
+ privs = {privs=true}, -- require the "privs" privilege to run
+ func = function(name, param), -- called when command is run
+}
projects / dragonfireclient.git / blobdiff