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

This commit is contained in:
Perttu Ahola 2012-04-09 12:36:25 +03:00
parent 3214daca4c
commit 251c0c8508
2 changed files with 78 additions and 47 deletions

@ -55,11 +55,15 @@ function minetest.hash_node_position(pos)
return (pos.z+32768)*65536*65536 + (pos.y+32768)*65536 + pos.x+32768
end
function minetest.get_node_group(name, group)
if not minetest.registered_nodes[name] or not
minetest.registered_nodes[name].groups[group] then
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_nodes[name].groups[group]
return minetest.registered_items[name].groups[group]
end
function minetest.get_node_group(name, group)
return minetest.get_item_group(name, group)
end

@ -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,29 +239,6 @@ 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.
eg. 'default:dirt 5'
eg. 'default:pick_wood 21323'
eg. 'default:apple'
item: A stack of items in Lua table format.
eg. {name="default:dirt", count=5, wear=0, metadata=""}
^ 5 dirt nodes
eg. {name="default:pick_wood", count=1, wear=21323, metadata=""}
^ a wooden pick about 1/3 weared out
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.
SimpleSoundSpec:
eg. ""
eg. "default_place_node"
eg. {}
eg. {name="default_place_node"}
eg. {name="default_place_node", gain=1.0}
Items
------
Node (register_node):
@ -263,6 +248,28 @@ Tool (register_tool):
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'
Table format:
eg. {name="default:dirt", count=5, wear=0, metadata=""}
^ 5 dirt nodes
eg. {name="default:pick_wood", count=1, wear=21323, metadata=""}
^ a wooden pick about 1/3 weared out
eg. {name="default:apple", count=1, wear=0, metadata=""}
^ an apple.
ItemStack:
C++ native format with many helper methods. Useful for converting between
formats. See the Class reference section for details.
When an item must be passed to a function, it can usually be in any of
these formats.
Groups
-------
In a number of places, there is a group table. Groups define the
@ -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