mirror of
https://github.com/minetest/minetest.git
synced 2024-11-23 16:13:46 +01:00
Improve doc/lua_api.txt and add minetest.get_item_group(name, group)
This commit is contained in:
Perttu Ahola
parent
3214daca4c
commit
251c0c8508
@ -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
|
||||
|
||||
|
||||
113
doc/lua_api.txt
113
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,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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user