X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=7ba2ed0011fa69249cb9fed6321faa1213542686;hb=13358c29b8a754709c49b0ba997f029af26134bc;hp=61bc8e1c22b98a01d5babe4f72dad54aef42c63b;hpb=81554fbf720300e36060a628c786902918328612;p=oweals%2Fminetest.git

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 61bc8e1c2..7ba2ed001 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1,4 +1,4 @@
-Minetest Lua Modding API Reference 0.4.dev
+Minetest Lua Modding API Reference 0.4.4
 ==========================================
 More information at http://c55.me/minetest/
 
@@ -254,9 +254,9 @@ 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
-uses them for certain automated functions. If you don't use these
-functions, you can use them to store arbitrary values.
+param1 and param2 are 8 bit integers. The engine uses them for certain
+automated functions. If you don't use these functions, you can use them to
+store arbitrary values.
 
 The functions of param1 and param2 are determined by certain fields in the
 node definition:
@@ -280,6 +280,61 @@ param2 is reserved for the engine when any of these are used:
 
 Nodes can also contain extra data. See "Node Metadata".
 
+Node drawtypes
+---------------
+There are a bunch of different looking node types. These are mostly just
+copied from Minetest 0.3; more may be made in the future.
+
+Look for examples in games/minimal or games/minetest_game.
+
+- normal
+- airlike
+- liquid
+- flowingliquid
+- glasslike
+- allfaces
+- allfaces_optional
+- torchlike
+- signlike
+- plantlike
+- fencelike
+- raillike
+- nodebox -- See below. EXPERIMENTAL
+
+Node boxes
+-----------
+Node selection boxes are defined using "node boxes"
+
+The "nodebox" node drawtype allows defining visual of nodes consisting of
+arbitrary number of boxes. It allows defining stuff like stairs. Only the
+"fixed" box type is supported for these.
+^ Please note that this is still experimental, and may be incompatibly
+  changed in the future.
+
+A nodebox is defined as any of:
+{
+    -- A normal cube; the default in most things
+    type = "regular"
+}
+{
+    -- A fixed box (facedir param2 is used, if applicable)
+    type = "fixed",
+    fixed = box OR {box1, box2, ...}
+}
+{
+    -- A box like the selection box for torches
+    -- (wallmounted param2 is used, if applicable)
+    type = "wallmounted",
+    wall_top = box,
+    wall_bottom = box,
+    wall_side = box
+}
+
+A box is defined as:
+  {x1, y1, z1, x2, y2, z2}
+A box of a regular node would look like:
+  {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
+
 Representations of simple things
 --------------------------------
 Position/vector:
@@ -287,6 +342,11 @@ Position/vector:
 Currently the API does not provide any helper functions for addition,
 subtraction and whatever; you can define those that you need yourself.
 
+pointed_thing:
+  {type="nothing"}
+  {type="node", under=pos, above=pos}
+  {type="object", ref=ObjectRef}
+
 Items
 ------
 Node (register_node):
@@ -363,7 +423,7 @@ effective towards.
 
 Groups in crafting recipes
 ---------------------------
-An example:
+An example: Make meat soup from any meat, any water and any bowl
 {
     output = 'food:meat_soup_raw',
     recipe = {
@@ -371,7 +431,13 @@ An example:
         {'group:water'},
         {'group:bowl'},
     },
-    preserve = {'group:bowl'}, -- Not implemented yet (TODO)
+    -- preserve = {'group:bowl'}, -- Not implemented yet (TODO)
+}
+An another example: Make red wool from white wool and red dye
+{
+	type = 'shapeless',
+    output = 'wool:red',
+    recipe = {'wool:white', 'group:dye,basecolor_red'},
 }
 
 Special groups
@@ -387,6 +453,13 @@ Special groups
   - 2: node is removed without tool wear after 0.5 seconds or so
        (rail, sign)
   - 3: node is removed without tool wear immediately (torch)
+- disable_jump: Player (and possibly other things) cannot jump from node
+- fall_damage_add_percent: damage speed = speed * (1 + value/100)
+- bouncy: value is bounce speed in percent
+- falling_node: if there is no walkable block under the node it will fall
+- attached_node: if the node under it is not a walkable block the node will be
+                  dropped as an item. If the node is wallmounted the
+                  wallmounted direction is checked.
 
 Known damage and digging time defining groups
 ----------------------------------------------
@@ -612,32 +685,85 @@ Examples:
 
 Elements:
 
-invsize[<W>,<H>;]
+size[<W>,<H>]
 ^ Define the size of the menu in inventory slots
+^ deprecated: invsize[<W>,<H>;]
 
 list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]
+list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]
 ^ Show an inventory list
 
 image[<X>,<Y>;<W>,<H>;<texture name>]
 ^ Show an image
 ^ Position and size units are inventory slots
 
+item_image[<X>,<Y>;<W>,<H>;<item name>]
+^ Show an inventory image of registered item/node
+^ Position and size units are inventory slots
+
+background[<X>,<Y>;<W>,<H>;<texture name>]
+^ Use a background. Inventory rectangles are not drawn then.
+^ Position and size units are inventory slots
+^ Example for formspec 8x4 in 16x resolution: image shall be sized 8*16px x 4*16px
+
 field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
 ^ Textual field; will be sent to server when a button is clicked
+^ x and y position the field relative to the top left of the menu
+^ w and h are the size of the field
+^ fields are a set height, but will be vertically centred on h
+^ Position and size units are inventory slots
+^ name is the name of the field as returned in fields to on_receive_fields
+^ label, if not blank, will be text printed on the top left above the field
+^ default is the default value of the field
+  ^ default may contain variable references such as '${text}' which
+    will fill the value from the metadata value 'text'
+	^ Note: no extra text or more than a single variable is supported ATM.
+
+field[<name>;<label>;<default>]
+^ as above but without position/size units
+^ special field for creating simple forms, such as sign text input
+^ must be used without a size[] element
+^ a 'Proceed' button will be added automatically
+
+textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
+^ same as fields above, but with multi-line input
+
+label[<X>,<Y>;<label>]
+^ x and y work as per field
+^ label is the text on the label
 ^ Position and size units are inventory slots
-^ Not implemented
 
 button[<X>,<Y>;<W>,<H>;<name>;<label>]
 ^ Clickable button. When clicked, fields will be sent.
-^ Button will be visible as a field, with the value "active".
+^ x, y and name work as per field
+^ w and h are the size of the button
+^ label is the text on the button
 ^ Position and size units are inventory slots
-^ Not implemented
+
+image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]
+^ x, y, w, h, and name work as per button
+^ image is the filename of an image
+^ Position and size units are inventory slots
+
+item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]
+^ x, y, w, h, name and label work as per button
+^ item name is the registered name of an item/node,
+  tooltip will be made out of its descritption
+^ Position and size units are inventory slots
+
+button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]
+^ When clicked, fields will be sent and the form will quit.
+
+image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]
+^ When clicked, fields will be sent and the form will quit.
 
 Inventory location:
+
 - "context": Selected node metadata (deprecated: "current_name")
 - "current_player": Player to whom the menu is shown
 - "player:<name>": Any player
 - "nodemeta:<X>,<Y>,<Z>": Any node metadata
+- "detached:<name>": A detached inventory
 
 Helper functions
 -----------------
@@ -658,6 +784,8 @@ minetest namespace reference
 minetest.get_current_modname() -> string
 minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
 ^ Useful for loading additional .lua modules or static data from mod
+minetest.get_modnames() -> list of installed mods
+^ Return a list of installed mods, sorted alphabetically
 minetest.get_worldpath() -> eg. "/home/user/.minetest/world"
 ^ Useful for storing custom data
 minetest.is_singleplayer()
@@ -680,11 +808,17 @@ 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))
+minetest.register_on_shutdown(func())
+^ Called before server shutdown
+^ WARNING: If the server terminates abnormally (i.e. crashes), the registered
+           callbacks WILL LIKELY NOT BE RUN.  Data should be saved at
+           semi-frequent intervals as well as on server shutdown.
+minetest.register_on_placenode(func(pos, newnode, placer, oldnode, itemstack))
 ^ Called when a node has been placed
+^ If return true no item is taken from itemstack
 ^ Deprecated: Use on_construct or after_place_node in node definition instead
 minetest.register_on_dignode(func(pos, oldnode, digger))
-^ Called when a node has been dug. digger can be nil.
+^ Called when a node has been dug.
 ^ Deprecated: Use on_destruct or after_dig_node in node definition instead
 minetest.register_on_punchnode(func(pos, node, puncher))
 ^ Called when a node is punched
@@ -699,7 +833,16 @@ 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
+minetest.register_on_joinplayer(func(ObjectRef))
+^ Called when a player joins the game
+minetest.register_on_leaveplayer(func(ObjectRef))
+^ Called when a player leaves the game
 minetest.register_on_chat_message(func(name, message))
+^ Called always when a player says something
+minetest.register_on_player_receive_fields(func(player, formname, fields))
+^ Called when a button is pressed in player's inventory form
+^ Newest functions are called first
+^ If function returns true, remaining functions are not called
 
 Other registration functions:
 minetest.register_chatcommand(cmd, chatcommand definition)
@@ -717,6 +860,7 @@ minetest.setting_set(name, value)
 minetest.setting_get(name) -> string or nil
 minetest.setting_getbool(name) -> boolean value or nil
 minetest.setting_get_pos(name) -> position or nil
+minetest.setting_save() -> nil, save all settings to config file
 minetest.add_to_creative_inventory(itemstring)
 
 Authentication:
@@ -744,6 +888,15 @@ Inventory:
 minetest.get_inventory(location) -> InvRef
 ^ location = eg. {type="player", name="celeron55"}
                  {type="node", pos={x=, y=, z=}}
+                 {type="detached", name="creative"}
+minetest.create_detached_inventory(name, callbacks) -> InvRef
+^ callbacks: See "Detached inventory callbacks"
+^ Creates a detached inventory. If it already exists, it is cleared.
+minetest.show_formspec(playername, formname, formspec)
+^ playername: name of player to show formspec
+^ formname: name passed to on_player_receive_fields callbacks
+^           should follow "modname:<whatever>" naming convention
+^ formspec: formspec to display
 
 Item handling:
 minetest.inventorycube(img1, img2, img3)
@@ -765,6 +918,27 @@ minetest.get_craft_result(input) -> output, decremented_input
 ^ output.item = ItemStack, if unsuccessful: empty ItemStack
 ^ output.time = number, if unsuccessful: 0
 ^ decremented_input = like input
+minetest.get_craft_recipe(output) -> input
+^ output is a node or item type such as 'default:torch'
+^ input.method = 'normal' or 'cooking' or 'fuel'
+^ input.width = for example 3
+^ input.items = for example { stack 1, stack 2, stack 3, stack 4,
+                              stack 5, stack 6, stack 7, stack 8, stack 9 }
+^ input.items = nil if no recipe found
+minetest.handle_node_drops(pos, drops, digger)
+^ drops: list of itemstrings
+^ Handles drops from nodes after digging: Default action is to put them into
+  digger's inventory
+^ Can be overridden to get different functionality (eg. dropping items on
+  ground)
+
+Rollbacks:
+minetest.rollback_get_last_node_actor(p, range, seconds) -> actor, p, seconds
+^ Find who has done something to a node, or near a node
+^ actor: "player:<name>", also "liquid".
+minetest.rollback_revert_actions_by(actor, seconds) -> bool, log messages
+^ Revert latest actions of someone
+^ actor: "player:<name>", also "liquid".
 
 Defaults for the on_* item definition functions:
 (These return the leftover itemstack)
@@ -774,6 +948,8 @@ minetest.item_place_object(itemstack, placer, pointed_thing)
 ^ Place item as-is
 minetest.item_place(itemstack, placer, pointed_thing)
 ^ Use one of the above based on what the item is.
+^ Calls on_rightclick of pointed_thing.under if defined instead
+^ Note: is not called when wielded item overrides on_place
 minetest.item_drop(itemstack, dropper, pos)
 ^ Drop the item
 minetest.item_eat(hp_change, replace_with_item)
@@ -797,6 +973,16 @@ minetest.after(time, func, param)
 ^ Call function after time seconds
 ^ param is optional; to pass multiple parameters, pass a table.
 
+Server:
+minetest.request_shutdown() -> request for server shutdown
+minetest.get_server_status() -> server status string
+
+Bans:
+minetest.get_ban_list() -> ban list (same as minetest.get_ban_description(""))
+minetest.get_ban_description(ip_or_name) -> ban description (string)
+minetest.ban_player(name) -> ban a player
+minetest.unban_player_or_ip(name) -> unban player or IP address
+
 Random:
 minetest.get_connected_players() -> list of ObjectRefs
 minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer
@@ -868,12 +1054,14 @@ methods:
   ^ Dig node with the same effects that a player would cause
 - punch_node(pos)
   ^ Punch node with the same effects that a player would cause
+  
+- get_meta(pos) -- Get a NodeMetaRef at that position
+- get_node_timer(pos) -- Get NodeTimerRef
 
 - add_entity(pos, name): Spawn Lua-defined entity at position
   ^ Returns ObjectRef, or nil if failed
 - add_item(pos, item): Spawn item
   ^ Returns ObjectRef, or nil if failed
-- get_meta(pos) -- Get a NodeMetaRef at that position
 - get_player_by_name(name) -- Get an ObjectRef to a player
 - get_objects_inside_radius(pos, radius)
 - set_timeofday(val): val: 0...1; 0 = midnight, 0.5 = midday
@@ -884,6 +1072,69 @@ methods:
   ^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
 - get_perlin(seeddiff, octaves, persistence, scale)
   ^ Return world-specific perlin noise (int(worldseed)+seeddiff)
+- clear_objects()
+  ^ clear all objects in the environments 
+- spawn_tree (pos, {treedef})
+  ^ spawns L-System tree at given pos with definition in treedef table
+treedef={
+  axiom,         - string  initial tree axiom
+  rules_a,       - string  rules set A
+  rules_b,       - string  rules set B
+  rules_c,       - string  rules set C
+  rules_d,       - string  rules set D
+  trunk,         - string  trunk node name
+  leaves,        - string  leaves node name
+  leaves2,       - string  secondary leaves node name
+  leaves2_chance,- num     chance (0-100) to replace leaves with leaves2
+  angle,         - num     angle in deg
+  iterations,    - num     max # of iterations, usually 2 -5
+  random_level,  - num     factor to lower nr of iterations, usually 0 - 3
+  trunk_type,    - string  single/double/crossed) type of trunk: 1 node, 2x2 nodes or 3x3 in cross shape
+  thin_branches, - boolean true -> use thin (1 node) branches
+  fruit,         - string  fruit node name
+  fruit_chance,  - num     chance (0-100) to replace leaves with fruit node
+  }
+
+Key for Special L-System Symbols used in Axioms
+  G  - move forward one unit with the pen up
+  F  - move forward one unit with the pen down drawing trunks and branches
+  f  - move forward one unit with the pen down drawing leaves (100% chance)
+  T  - move forward one unit with the pen down drawing trunks only
+  R  - move forward one unit with the pen down placing fruit
+  A  - replace with rules set A
+  B  - replace with rules set B
+  C  - replace with rules set C
+  D  - replace with rules set D
+  a  - replace with rules set A, chance 90%
+  b  - replace with rules set B, chance 80%
+  c  - replace with rules set C, chance 70%
+  d  - replace with rules set D, chance 60%
+  +  - yaw the turtle right by angle parameter
+  -  - yaw the turtle left by angle parameter
+  &  - pitch the turtle down by angle parameter
+  ^  - pitch the turtle up by angle parameter
+  /  - roll the turtle to the right by angle parameter
+  *  - roll the turtle to the left by angle parameter
+  [  - save in stack current state info
+  ]  - recover from stack state info
+
+Example usage: spawn small apple tree
+apple_tree={
+  axiom="FFFFFAFFBF",
+  rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
+  rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
+  trunk="default:tree",
+  leaves="default:leaves",
+  angle=30,
+  iterations=2,
+  random_level=0,
+  trunk_type="single",
+  thin_branches=true,
+  fruit_chance=10,
+  fruit="default:apple"
+  }
+minetest.env:spawn_tree(pos,apple_tree)
+
 Deprecated:
 - add_rat(pos): Add C++ rat object (no-op)
 - add_firefly(pos): Add C++ firefly object (no-op)
@@ -902,6 +1153,26 @@ methods:
 - to_table() -> nil or {fields = {...}, inventory = {list1 = {}, ...}}
 - from_table(nil or {})
   ^ See "Node Metadata"
+  
+NodeTimerRef: Node Timers - a high resolution persistent per-node timer
+- Can be gotten via minetest.env:get_node_timer(pos)
+methods:
+- set(timeout,elapsed)
+  ^ set a timer's state
+  ^ timeout is in seconds, and supports fractional values (0.1 etc)
+  ^ elapsed is in seconds, and supports fractional values (0.1 etc)
+  ^ will trigger the node's on_timer function after timeout-elapsed seconds
+- start(timeout)
+  ^ start a timer
+  ^ equivelent to set(timeout,0)
+- stop()
+  ^ stops the timer
+- get_timeout() -> current timeout in seconds
+  ^ if timeout is 0, timer is inactive
+- get_elapsed() -> current elapsed time in seconds
+  ^ the node's on_timer function will be called after timeout-elapsed seconds
+- is_started() -> boolean state of timer
+  ^ returns true if timer is started, otherwise false
 
 ObjectRef: Moving things in the game are generally these
 (basically reference to a C++ ServerActiveObject)
@@ -913,6 +1184,7 @@ methods:
 - punch(puncher, time_from_last_punch, tool_capabilities, direction)
   ^ puncher = an another ObjectRef,
   ^ time_from_last_punch = time since last punch action of the puncher
+  ^ direction: can be nil
 - right_click(clicker); clicker = an another ObjectRef
 - get_hp(): returns number of hitpoints (2 * number of hearts)
 - set_hp(hp): set number of hitpoints (2 * number of hearts)
@@ -922,6 +1194,10 @@ methods:
 - get_wielded_item() -> ItemStack
 - set_wielded_item(item): replaces the wielded item, returns true if successful
 - set_armor_groups({group1=rating, group2=rating, ...})
+- set_animation({x=1,y=1}, frame_speed=15, frame_blend=0)
+- set_attach(parent, "", {x=0,y=0,z=0}, {x=0,y=0,z=0})
+- set_detach()
+- set_bone_position("", {x=0,y=0,z=0}, {x=0,y=0,z=0})
 - set_properties(object property table)
 LuaEntitySAO-only: (no-op for other objects)
 - setvelocity({x=num, y=num, z=num})
@@ -933,8 +1209,8 @@ LuaEntitySAO-only: (no-op for other objects)
 - settexturemod(mod)
 - setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
 -           select_horiz_by_yawpitch=false)
-- ^ Select sprite from spritesheet with optional animation and DM-style
--   texture selection based on yaw relative to camera
+  ^ Select sprite from spritesheet with optional animation and DM-style
+    texture selection based on yaw relative to camera
 - get_entity_name() (DEPRECATED: Will be removed in a future version)
 - get_luaentity()
 Player-only: (no-op for other objects)
@@ -943,12 +1219,22 @@ Player-only: (no-op for other objects)
 - get_look_dir(): get camera direction as a unit vector
 - get_look_pitch(): pitch in radians
 - get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
-
+- set_inventory_formspec(formspec)
+  ^ Redefine player's inventory form
+  ^ Should usually be called in on_joinplayer
+- get_inventory_formspec() -> formspec string
+- get_player_control(): returns table with player pressed keys
+	{jump=bool,right=bool,left=bool,LMB=bool,RMB=bool,sneak=bool,aux1=bool,down=bool,up=bool}
+- get_player_control_bits(): returns integer with bit packed player pressed keys
+	bit nr/meaning: 0/up ,1/down ,2/left ,3/right ,4/jump ,5/aux1 ,6/sneak ,7/LMB ,8/RMB
+	
 InvRef: Reference to an inventory
 methods:
 - is_empty(listname): return true if list is empty
 - get_size(listname): get size of a list
 - set_size(listname, size): set size of a list
+- get_width(listname): get width of a list
+- set_width(listname, width): set width of list; currently used for crafting
 - get_stack(listname, i): get a copy of stack index i in list
 - set_stack(listname, i, stack): copy stack to index i in list
 - get_list(listname): return full list
@@ -960,6 +1246,8 @@ methods:
     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)
+- get_location() -> location compatible to minetest.get_inventory(location)
+                 -> {type="undefined"} in case location is not known
 
 ItemStack: A stack of items.
 - Can be created via ItemStack(itemstack or itemstring or table or nil)
@@ -1036,15 +1324,20 @@ Definition tables
 
 Object Properties
 {
+    hp_max = 1,
     physical = true,
+    weight = 5,
     collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
-    visual = "cube"/"sprite"/"upright_sprite",
+    visual = "cube"/"sprite"/"upright_sprite"/"mesh",
     visual_size = {x=1, y=1},
+    mesh = "model",
     textures = {}, -- number of required textures depends on visual
+    colors = {}, -- number of required colors depends on visual
     spritediv = {x=1, y=1},
     initial_sprite_basepos = {x=0, y=0},
     is_visible = true,
     makes_footstep_sound = false,
+    automatic_rotate = false,
 }
 
 Entity definition (register_entity)
@@ -1053,7 +1346,7 @@ Entity definition (register_entity)
     
     initial_properties = <initial object properties>,
 
-    on_activate = function(self, staticdata),
+    on_activate = function(self, staticdata, dtime_s),
     on_step = function(self, dtime),
     on_punch = function(self, hitter),
     on_rightclick = function(self, clicker),
@@ -1100,10 +1393,19 @@ Item definition (register_node, register_craftitem, register_tool)
             choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
         }
     }
+    node_placement_prediction = nil,
+    ^ If nil and item is node, prediction is made automatically
+    ^ If nil and item is not a node, no prediction is made
+    ^ If "" and item is anything, no prediction is made
+    ^ Otherwise should be name of node which the client immediately places
+      on ground when the player places the item. Server will always update
+      actual result to client in a short moment.
 
     on_place = func(itemstack, placer, pointed_thing),
+    ^ Shall place item and return the leftover itemstack
     ^ default: minetest.item_place
     on_drop = func(itemstack, dropper, pos),
+    ^ Shall drop item and return the leftover itemstack
     ^ default: minetest.item_drop
     on_use = func(itemstack, user, pointed_thing),
     ^  default: nil
@@ -1114,37 +1416,51 @@ Item definition (register_node, register_craftitem, register_tool)
     ^ The default functions handle regular use cases.
 }
 
+Tile definition:
+- "image.png"
+- {name="image.png", animation={Tile Animation definition}}
+- {name="image.png", backface_culling=bool}
+  ^ backface culling only supported in special tiles
+- deprecated still supported field names:
+  - image -> name
+
+Tile animation definition:
+- {type="vertical_frames", aspect_w=16, aspect_h=16, length=3.0}
+
 Node definition (register_node)
 {
     <all fields allowed in item definitions>,
 
-    drawtype = "normal",
+    drawtype = "normal", -- See "Node drawtypes"
     visual_scale = 1.0,
-    tile_images = {"default_unknown_block.png"},
-    special_materials = {
-        {image="", backface_culling=true},
-        {image="", backface_culling=true},
-    },
+    tiles = {tile definition 1, def2, def3, def4, def5, def6},
+	^ Textures of node; +Y, -Y, +X, -X, +Z, -Z (old field name: tile_images)
+    ^ List can be shortened to needed length
+    special_tiles = {tile definition 1, Tile definition 2},
+	^ Special textures of node; used rarely (old field name: special_materials)
+    ^ List can be shortened to needed length
     alpha = 255,
-    post_effect_color = {a=0, r=0, g=0, b=0},
-    paramtype = "none",
-    paramtype2 = "none",
-    is_ground_content = false,
-    sunlight_propagates = false,
-    walkable = true,
-    pointable = true,
-    diggable = true,
-    climbable = false,
-    buildable_to = false,
-    drop = "",
-    -- alternatively drop = { max_items = ..., items = { ... } }
-    liquidtype = "none",
-    liquid_alternative_flowing = "",
-    liquid_alternative_source = "",
-    liquid_viscosity = 0,
-    light_source = 0,
-    damage_per_second = 0,
-    selection_box = {type="regular"},
+    post_effect_color = {a=0, r=0, g=0, b=0}, -- If player is inside node
+    paramtype = "none", -- See "Nodes"
+    paramtype2 = "none", -- See "Nodes"
+    is_ground_content = false, -- Currently not used for anything
+    sunlight_propagates = false, -- If true, sunlight will go infinitely through this
+    walkable = true, -- If true, objects collide with node
+    pointable = true, -- If true, can be pointed at
+    diggable = true, -- If false, can never be dug
+    climbable = false, -- If true, can be climbed on (ladder)
+    buildable_to = false, -- If true, placed nodes can replace this node
+    drop = "", -- alternatively drop = { max_items = ..., items = { ... } }
+    liquidtype = "none", -- "none"/"source"/"flowing"
+    liquid_alternative_flowing = "", -- Flowing version of source liquid
+    liquid_alternative_source = "", -- Source version of flowing liquid
+    liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
+    liquid_renewable = true, -- Can new liquid source be created by placing
+    two or more sources nearly?
+    light_source = 0, -- Amount of light emitted by node
+    damage_per_second = 0, -- If player is inside node, this damage is caused
+    node_box = {type="regular"}, -- See "Node boxes"
+    selection_box = {type="regular"}, -- See "Node boxes"
     legacy_facedir_simple = false, -- Support maps made in and before January 2012
     legacy_wallmounted = false, -- Support maps made in and before January 2012
     sounds = {
@@ -1164,9 +1480,10 @@ Node definition (register_node)
     ^ Node destructor; always called after removing node
     ^ default: nil
 
-    after_place_node = func(pos, placer),
+    after_place_node = func(pos, placer, itemstack),
     ^ Called after constructing node when node was placed using
       minetest.item_place_node / minetest.env:place_node
+    ^ If return true no item is taken from itemstack
     ^ default: nil
     after_dig_node = func(pos, oldnode, oldmetadata, digger),
     ^ oldmetadata is in table format
@@ -1180,44 +1497,49 @@ Node definition (register_node)
     on_punch = func(pos, node, puncher),
     ^ default: minetest.node_punch
     ^ By default: does nothing
-	on_dig = func(pos, node, digger),
+    on_rightclick = func(pos, node, clicker),
+    ^ default: nil
+    on_dig = func(pos, node, digger),
     ^ default: minetest.node_dig
     ^ By default: checks privileges, wears out tool and removes node
+    
+    on_timer = function(pos,elapsed),
+    ^ default: nil
+    ^ called by NodeTimers, see EnvRef and NodeTimerRef
+    ^ elapsed is the total time passed since the timer was started
+    ^ return true to run the timer for another cycle with the same timeout value
 
     on_receive_fields = func(pos, formname, fields, sender),
     ^ fields = {name1 = value1, name2 = value2, ...}
     ^ Called when an UI form (eg. sign text input) returns data
     ^ default: nil
 
-    on_metadata_inventory_move = func(pos, from_list, from_index,
-                                      to_list, to_index, count, player),
-    ^ Called when a player wants to move items inside the metadata
-    ^ Should move items, or some items, if permitted. If not, should do
-      nothing.
-    ^ The engine ensures the action is valid, i.e. the stack fits at the
-      given position
-    ^ default: minetest.node_metadata_inventory_move_allow_all
-
-    on_metadata_inventory_offer = func(pos, listname, index, stack, player),
-    ^ Called when a player wants to put something into the metadata
-      inventory
-    ^ Should check if the action is permitted (the engine ensures the
-      action is valid, i.e. the stack fits at the given position)
-      ^ If permitted, modify the metadata inventory and return the
-        "leftover" stack (normally nil).
-      ^ If not permitted, return itemstack.
-    ^ default: minetest.node_metadata_inventory_offer_allow_all
-
-    on_metadata_inventory_take = func(pos, listname, index, count, player),
-    ^ Called when a player wants to take something out of the metadata
-      inventory
-    ^ Should check if the action is permitted (the engine ensures the
-      action is valid, i.e. there's a stack of at least “count” items at
-      that position)
-      ^ If permitted, modify the metadata inventory and return the
-        stack of items
-      ^ If not permitted, return nil.
-    ^ default: minetest.node_metadata_inventory_take_allow_all
+	allow_metadata_inventory_move = func(pos, from_list, from_index,
+			to_list, to_index, count, player),
+	^ Called when a player wants to move items inside the inventory
+	^ Return value: number of items allowed to move
+	
+	allow_metadata_inventory_put = func(pos, listname, index, stack, player),
+	^ Called when a player wants to put something into the inventory
+	^ Return value: number of items allowed to put
+	^ Return value: -1: Allow and don't modify item count in inventory
+  
+	allow_metadata_inventory_take = func(pos, listname, index, stack, player),
+	^ Called when a player wants to take something out of the inventory
+	^ Return value: number of items allowed to take
+	^ Return value: -1: Allow and don't modify item count in inventory
+
+	on_metadata_inventory_move = func(pos, from_list, from_index,
+			to_list, to_index, count, player),
+	on_metadata_inventory_put = func(pos, listname, index, stack, player),
+	on_metadata_inventory_take = func(pos, listname, index, stack, player),
+	^ Called after the actual action has happened, according to what was allowed.
+	^ No return value
+    
+	on_blast = func(pos, intensity),
+	^ intensity: 1.0 = mid range of regular TNT
+	^ If defined, called when an explosion touches the node, instead of
+	  removing the node
 }
 
 Recipe for register_craft: (shaped)
@@ -1274,3 +1596,26 @@ Chatcommand definition (register_chatcommand)
     func = function(name, param), -- called when command is run
 }
 
+Detached inventory callbacks
+{
+	allow_move = func(inv, from_list, from_index, to_list, to_index, count, player),
+    ^ Called when a player wants to move items inside the inventory
+	^ Return value: number of items allowed to move
+	
+    allow_put = func(inv, listname, index, stack, player),
+    ^ Called when a player wants to put something into the inventory
+	^ Return value: number of items allowed to put
+	^ Return value: -1: Allow and don't modify item count in inventory
+   
+    allow_take = func(inv, listname, index, stack, player),
+    ^ Called when a player wants to take something out of the inventory
+	^ Return value: number of items allowed to take
+	^ Return value: -1: Allow and don't modify item count in inventory
+	
+	on_move = func(inv, from_list, from_index, to_list, to_index, count, player),
+    on_put = func(inv, listname, index, stack, player),
+    on_take = func(inv, listname, index, stack, player),
+	^ Called after the actual action has happened, according to what was allowed.
+	^ No return value
+}
+