diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/lua_api.txt | 105 |
1 files changed, 66 insertions, 39 deletions
diff --git a/doc/lua_api.txt b/doc/lua_api.txt index bc4114419..aabc673f9 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -25,7 +25,7 @@ If you have any difficulty in understanding this, please read: 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 ------------- @@ -180,11 +180,18 @@ Examples of sound parameter tables: -- 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 @@ -197,7 +204,8 @@ The definition of a node is stored and can be accessed by name in 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 @@ -231,12 +239,23 @@ Position/vector: 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=""} @@ -244,24 +263,12 @@ 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 ------- @@ -282,6 +289,9 @@ Usage: - 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). @@ -314,7 +324,7 @@ Groups in crafting recipes {'group:water'}, {'group:bowl'}, }, - preserve = {'group:bowl'}, + preserve = {'group:bowl'}, } Special groups @@ -346,7 +356,7 @@ Valid ratings for these are 0, 1, 2 and 3, unless otherwise stated. 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 @@ -402,9 +412,9 @@ it's useful item. (eg. iron ore to drop a lump of iron). 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 @@ -414,7 +424,7 @@ be able to dig. 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 @@ -460,7 +470,7 @@ Entity damage mechanism 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 @@ -469,23 +479,24 @@ 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 @@ -514,7 +525,7 @@ minetest.get_worldpath() -> eg. "/home/user/.minetest/world" 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" @@ -527,17 +538,30 @@ minetest.register_tool(name, item definition) 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" @@ -628,11 +652,14 @@ 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 -^ 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 |