aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorCiaran Gultnieks <ciaran@ciarang.com>2014-03-17 20:05:35 +0000
committerShadowNinja <shadowninja@minetest.net>2014-11-28 18:35:45 -0500
commitc30346ea3093ed96693e628493f5722c615ba138 (patch)
tree4b8a67e146336eabd97c3694f416f01763c46f40 /doc
parent2b1a151226ae274ca652e72e95b840199e9389b8 (diff)
downloadminetest-c30346ea3093ed96693e628493f5722c615ba138.tar.gz
minetest-c30346ea3093ed96693e628493f5722c615ba138.tar.bz2
minetest-c30346ea3093ed96693e628493f5722c615ba138.zip
Improve Lua API documentation
Changes: * Add extra documentation for remove_item. This isn't as silly as it sounds: iterate a list containing items with unique metadata each, and remove_item the first one you find, placing into a different - fine, except the remove will invariably remove the wrong one, leading to items being duplicated and others destroyed. Arguably it's a bug, and Inventory::removeItem should actually remove the item you tell it to. (i.e. if the passed ItemStack has metadata, match it). But it seems reasonable to just document the behaviour more clearly. * Improve string_to_pos documentation. * Clarify dig_node documentation (return value). * Better on_step documentation. * get_nodemeta -> get_meta. * Other minor fixes.
Diffstat (limited to 'doc')
-rw-r--r--doc/lua_api.txt16
1 files changed, 11 insertions, 5 deletions
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index f51d215ed..e2ef3faab 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1303,7 +1303,7 @@ string:trim()
minetest.pos_to_string({x=X,y=Y,z=Z}) -> "(X,Y,Z)"
^ Convert position to a printable string
minetest.string_to_pos(string) -> position
-^ Same but in reverse
+^ Same but in reverse. Returns nil if the string can't be parsed to a position.
minetest.formspec_escape(string) -> string
^ escapes characters [ ] \ , ; that can not be used in formspecs
minetest.is_yes(arg)
@@ -1505,6 +1505,7 @@ minetest.place_node(pos, node)
^ Place node with the same effects that a player would cause
minetest.dig_node(pos)
^ Dig node with the same effects that a player would cause
+ Returns true if successful, false on failure (e.g. protected location)
minetest.punch_node(pos)
^ Punch node with the same effects that a player would cause
@@ -1885,7 +1886,7 @@ Class reference
----------------
NodeMetaRef: Node metadata - reference extra data and functionality stored
in a node
-- Can be gotten via minetest.get_nodemeta(pos)
+- Can be gotten via minetest.get_meta(pos)
methods:
- set_string(name, value)
- get_string(name)
@@ -2052,8 +2053,11 @@ methods:
can be fully added to the list
- contains_item(listname, stack): returns true if the stack of items
can be fully taken from the list
- remove_item(listname, stack): take as many items as specified from the list,
- returns the items that were actually removed (as an ItemStack)
+- remove_item(listname, stack): take as many items as specified from the list,
+ returns the items that were actually removed (as an ItemStack) - note that
+ any item metadata is ignored, so attempting to remove a specific unique
+ item this way will likely remove the wrong one - to do that use set_stack
+ with an empty ItemStack
- get_location() -> location compatible to minetest.get_inventory(location)
-> {type="undefined"} in case location is not known
@@ -2224,7 +2228,9 @@ Registered entities
- on_activate(self, staticdata)
^ Called when the object is instantiated.
- on_step(self, dtime)
- ^ Called on every server tick (dtime is usually 0.1 seconds)
+ ^ Called on every server tick, after movement and collision processing.
+ dtime is usually 0.1 seconds, as per the dedicated_server_step setting
+ in minetest.conf.
- on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)
^ Called when somebody punches the object.
^ Note that you probably want to handle most punches using the