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
-------------
-- 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
}
+SimpleSoundSpec:
+eg. ""
+eg. "default_place_node"
+eg. {}
+eg. {name="default_place_node"}
+eg. {name="default_place_node", gain=1.0}
+
Nodes
------
Nodes are the bulk data of the world: cubes and other things that take the
Please note that for unknown nodes (eg. a node of an uninstalled mod) the
minetest.registered_nodes field for the node is nil.
-Nodes are passed by value in Lua. They are represented by a table:
+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
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.
+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).
{'group:water'},
{'group:bowl'},
},
- preserve = {'group:bowl'},
+ preserve = {'group:bowl'},
}
Special groups
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
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
+- 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
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 the tool to be able to dig nodes that have a rating of 2 or 3
+ 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
Damage calculation:
- Take the time spent after the last hit
- Limit time to full_punch_interval
-- Take the damage groups, assume a node has them
+- 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
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
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"
minetest.register_craftitem(name, item 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
minetest.register_on_dignode(func(pos, oldnode, digger))
+^ Called when a node has been dug. digger can be nil.
minetest.register_on_punchnode(func(pos, node, puncher))
+^ 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_chat_message(func(name, message))
+
+Other registration functions:
minetest.register_chatcommand(cmd, chatcommand definition)
minetest.register_privilege(name, definition)
^ definition: "description text"
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
-^ Get rating of a group of a node. (0 = not in group)
+^ Deprecated: An alias for the former.
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
projects / oweals / minetest.git / commitdiff