Improve doc/lua_api.txt and add minetest.get_item_group(name, group)

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