MoNTE48
/
Minetest
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

master
Perttu Ahola 2012-04-09 12:36:25 +03:00
parent 3214daca4c
commit 251c0c8508
2 changed files with 78 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
builtin/misc.lua
View File

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

113
doc/lua_api.txt
View File

@ -25,7 +25,7 @@ If you have any difficulty in understanding this, please read:
Startup Startup
-------- --------
Mods are loaded during server startup from the mod load paths by running 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 Mod load path
------------- -------------
@ -180,11 +180,18 @@ Examples of sound parameter tables:
-- Play connected to an object, looped -- Play connected to an object, looped
{ {
object = <an ObjectRef>, object = <an ObjectRef>,
gain = 1.0, -- default gain = 1.0, -- default
max_hear_distance = 32, -- default max_hear_distance = 32, -- default
loop = true, -- only sounds connected to objects can be looped 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
------ ------
Nodes are the bulk data of the world: cubes and other things that take the 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 Please note that for unknown nodes (eg. a node of an uninstalled mod) the
minetest.registered_nodes field for the node is nil. 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} {name="name", param1=num, param2=num}
param1 and param2 are 8 bit and 4 bit integers, respectively. The engine 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, Currently the API does not provide any helper functions for addition,
subtraction and whatever; you can define those that you need yourself. 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 Items
------ ------
Node (register_node): Node (register_node):
@ -263,6 +248,28 @@ Tool (register_tool):
Craftitem (register_craftitem): Craftitem (register_craftitem):
A miscellaneous item 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 Groups
------- -------
In a number of places, there is a group table. Groups define the 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 - 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. 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
---------------- ----------------
Groups of items can define what kind of an item it is (eg. wool). 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:water'},
{'group:bowl'}, {'group:bowl'},
}, },
preserve = {'group:bowl'}, preserve = {'group:bowl'},
} }
Special groups 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 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 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 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. suggests for the hand.
Examples of custom groups 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, 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 of this group, of the maximum level. For lower leveled nodes, the use count
is multiplied by 3^leveldiff. is multiplied by 3^leveldiff.
- uses=10, leveldiff=0 -> actual_uses=10 - uses=10, leveldiff=0 -> actual uses: 10
- uses=10, leveldiff=1 -> actual_uses=30 - uses=10, leveldiff=1 -> actual uses: 30
- uses=10, leveldiff=2 -> actual_uses=90 - uses=10, leveldiff=2 -> actual uses: 90
**Maximum level** **Maximum level**
Tells what is the maximum level of a node of this group that the tool will 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 List of digging times for different ratings of the group, for nodes of the
maximum level. maximum level.
* For example, as a lua table, ''times={2=2.00, 3=0.70}''. This would * 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. for this group, and unable to dig the rating 1, which is the toughest.
Unless there is a matching group that enables digging otherwise. Unless there is a matching group that enables digging otherwise.
* For entities, damage equals the amount of nodes dug in the time spent * For entities, damage equals the amount of nodes dug in the time spent
@ -460,7 +470,7 @@ Entity damage mechanism
Damage calculation: Damage calculation:
- Take the time spent after the last hit - Take the time spent after the last hit
- Limit time to full_punch_interval - 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. - 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 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). TODO).
- Currently a smoke puff will appear when an entity dies. - 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 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 group disables the regular damage mechanism for players punching it by hand or
or a non-tool item. 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, On the Lua side, every punch calls ''entity:on_punch(puncher,
time_from_last_punch, tool_capabilities, direction)''. This should never be time_from_last_punch, tool_capabilities, direction)''. This should never be
called directly, because damage is usually not handled by the entity itself. 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 * ''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. * ''time_from_last_punch'' is time from last punch (by puncher) or nil.
* ''tool_capabilities'' can be nil. * ''tool_capabilities'' can be nil.
* ''direction'' is a unit vector, pointing from the source of the punch to * ''direction'' is a unit vector, pointing from the source of the punch to
the punched object. 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. * Return value is tool wear.
* Parameters are equal to the above callback. * Parameters are equal to the above callback.
* If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be * 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.is_singleplayer()
minetest.debug(line) minetest.debug(line)
^ Goes to dstream ^ Always printed to stderr and logfile (print() is redirected here)
minetest.log(line) minetest.log(line)
minetest.log(loglevel, line) minetest.log(loglevel, line)
^ loglevel one of "error", "action", "info", "verbose" ^ 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_craftitem(name, item definition)
minetest.register_alias(name, convert_to) minetest.register_alias(name, convert_to)
minetest.register_craft(recipe) minetest.register_craft(recipe)
Global callback registration functions: (Call these only at load time)
minetest.register_globalstep(func(dtime)) minetest.register_globalstep(func(dtime))
^ Called every server step, usually interval of 0.05s
minetest.register_on_placenode(func(pos, newnode, placer)) minetest.register_on_placenode(func(pos, newnode, placer))
^ Called when a node has been placed
minetest.register_on_dignode(func(pos, oldnode, digger)) 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)) minetest.register_on_punchnode(func(pos, node, puncher))
^ Called when a node is punched
minetest.register_on_generated(func(minp, maxp, blockseed)) 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)) minetest.register_on_newplayer(func(ObjectRef))
^ Called after a new player has been created
minetest.register_on_dieplayer(func(ObjectRef)) minetest.register_on_dieplayer(func(ObjectRef))
^ Called when a player dies
minetest.register_on_respawnplayer(func(ObjectRef)) 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 ^ return true in func to disable regular player placement
^ currently called _before_ repositioning of player occurs
minetest.register_on_chat_message(func(name, message)) minetest.register_on_chat_message(func(name, message))
Other registration functions:
minetest.register_chatcommand(cmd, chatcommand definition) minetest.register_chatcommand(cmd, chatcommand definition)
minetest.register_privilege(name, definition) minetest.register_privilege(name, definition)
^ definition: "description text" ^ definition: "description text"
@ -628,11 +652,14 @@ Random:
minetest.get_connected_players() -> list of ObjectRefs minetest.get_connected_players() -> list of ObjectRefs
minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer
^ Gives a unique hash number for a node position (16+16+16=48bit) ^ 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 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: 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: Global tables:
minetest.registered_items minetest.registered_items