X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=597f98c2cb27bc9a5c00bbd81f0de42e8bc1a538;hb=a4183994a446a065e3151745b4167270ebae6194;hp=f891b56f0d5dd0ac2f525123f760f5b55b1be12f;hpb=5bc14e2fe45f12cdb69d302807d05985ee5552ee;p=oweals%2Fminetest.git

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index f891b56f0..597f98c2c 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1,5 +1,5 @@
-Minetest Lua Modding API Reference 0.4.4
-==========================================
+Minetest Lua Modding API Reference 0.4.6
+========================================
 More information at http://c55.me/minetest/
 
 Introduction
@@ -27,6 +27,39 @@ Startup
 Mods are loaded during server startup from the mod load paths by running
 the init.lua scripts in a shared environment.
 
+Paths
+-----
+RUN_IN_PLACE=1: (Windows release, local build)
+ $path_user:  Linux:    <build directory>
+              Windows:  <build directory>
+ $path_share: Linux:    <build directory>
+              Windows:  <build directory>
+
+RUN_IN_PLACE=0: (Linux release)
+ $path_share: Linux:    /usr/share/minetest
+              Windows:  <install directory>/minetest-0.4.x
+ $path_user:  Linux:    ~/.minetest
+              Windows:  C:/users/<user>/AppData/minetest (maybe)
+
+Games
+-----
+Games are looked up from:
+  $path_share/games/gameid/
+  $path_user/games/gameid/
+where gameid is unique to each game.
+
+The game directory contains the file game.conf, which contains these fields:
+  name = <Human-readable full name of the game>
+  common_mods = <Comma-separated list of common mods>
+eg.
+  name = Minetest
+  common_mods = bucket, default, doors, fire, stairs
+
+Common mods are loaded from the pseudo-game "common".
+
+The game directory can contain the file minetest.conf, which will be used
+to set default settings when running the particular game.
+
 Mod load path
 -------------
 Generic:
@@ -170,18 +203,18 @@ from the available ones of the following files:
 Examples of sound parameter tables:
 -- Play locationless on all clients
 {
-	gain = 1.0, -- default
+    gain = 1.0, -- default
 }
 -- Play locationless to a player
 {
-	to_player = name,
-	gain = 1.0, -- default
+    to_player = name,
+    gain = 1.0, -- default
 }
 -- Play in a location
 {
-	pos = {x=1,y=2,z=3},
-	gain = 1.0, -- default
-	max_hear_distance = 32, -- default
+    pos = {x=1,y=2,z=3},
+    gain = 1.0, -- default
+    max_hear_distance = 32, -- default
 }
 -- Play connected to an object, looped
 {
@@ -233,11 +266,11 @@ local drawtype = get_nodedef_field(nodename, "drawtype")
 Example: minetest.get_item_group(name, group) has been implemented as:
 
 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_items[name].groups[group]
+    if not minetest.registered_items[name] or not
+            minetest.registered_items[name].groups[group] then
+        return 0
+    end
+    return minetest.registered_items[name].groups[group]
 end
 
 Nodes
@@ -277,6 +310,10 @@ param2 is reserved for the engine when any of these are used:
   paramtype2 == "facedir"
   ^ The rotation of the node is stored in param2. Furnaces and chests are
     rotated this way. Can be made by using minetest.dir_to_facedir().
+    Values range 0 - 23
+    facedir modulo 4 = axisdir
+    0 = y+    1 = z+    2 = z-    3 = x+    4 = x-    5 = y-
+    facedir's two less significant bits are rotation around the axis
 
 Nodes can also contain extra data. See "Node Metadata".
 
@@ -292,6 +329,7 @@ Look for examples in games/minimal or games/minetest_game.
 - liquid
 - flowingliquid
 - glasslike
+- glasslike_framed
 - allfaces
 - allfaces_optional
 - torchlike
@@ -335,6 +373,82 @@ A box is defined as:
 A box of a regular node would look like:
   {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
 
+Ore types
+---------------
+These tell in what manner the ore is generated.
+All default ores are of the uniformly-distributed scatter type.
+
+- scatter
+    Randomly chooses a location and generates a cluster of ore.
+    If noise_params is specified, the ore will be placed if the 3d perlin noise at 
+    that point is greater than the noise_threshhold, giving the ability to create a non-equal
+    distribution of ore.
+- sheet
+    Creates a sheet of ore in a blob shape according to the 2d perlin noise described by noise_params.
+    The relative height of the sheet can be controlled by the same perlin noise as well, by specifying
+    a non-zero 'scale' parameter in noise_params.  IMPORTANT: The noise is not transformed by offset or
+    scale when comparing against the noise threshhold, but scale is used to determine relative height.
+    The height of the blob is randomly scattered, with a maximum height of clust_size.
+    clust_scarcity and clust_num_ores are ignored.
+    This is essentially an improved version of the so-called "stratus" ore seen in some unofficial mods.
+- claylike - NOT YET IMPLEMENTED
+    Places ore if there are no more than clust_scarcity number of specified nodes within a Von Neumann
+    neighborhood of clust_size radius.
+
+Ore attributes
+-------------------
+Currently supported flags:  absheight
+ - absheight
+    Also produce this same ore between the height range of -height_max and -height_min.
+    Useful for having ore in sky realms without having to duplicate ore entries.
+
+HUD element types
+-------------------
+The position field is used for all element types.
+To account for differing resolutions, the position coordinates are the percentage of the screen,
+ranging in value from 0 to 1.
+The name field is not yet used, but should contain a description of what the HUD element represents.
+The direction field is the direction in which something is drawn.
+0 draws from left to right, 1 draws from right to left, 2 draws from top to bottom, and 3 draws from bottom to top.
+The alignment field specifies how the item will be aligned. It ranges from -1 to 1,
+with 0 being the center, -1 is moved to the left/up, and 1 is to the right/down. Fractional
+values can be used.
+The offset field specifies a pixel offset from the position. Contrary to position,
+the offset is not scaled to screen size. This allows for some precisely-positioned
+items in the HUD.
+Below are the specific uses for fields in each type; fields not listed for that type are ignored.
+
+Note: Future revisions to the HUD API may be incompatible; the HUD API is still in the experimental stages.
+
+- image
+    Displays an image on the HUD.
+	- scale: The scale of the image, with 1 being the original texture size.
+             Only the X coordinate scale is used.
+    - text: The name of the texture that is displayed.
+    - alignment: The alignment of the image.
+    - offset: offset in pixels from position.
+- text
+    Displays text on the HUD.
+    - scale: Defines the bounding rectangle of the text.
+             A value such as {x=100, y=100} should work.
+    - text: The text to be displayed in the HUD element.
+    - number: An integer containing the RGB value of the color used to draw the text.
+              Specify 0xFFFFFF for white text, 0xFF0000 for red, and so on.
+    - alignment: The alignment of the text.
+    - offset: offset in pixels from position.
+- statbar
+    Displays a horizontal bar made up of half-images.
+    - text: The name of the texture that is used.
+    - number: The number of half-textures that are displayed.
+              If odd, will end with a vertically center-split texture.
+    - direction
+    - offset: offset in pixels from position.
+- inventory
+    - text: The name of the inventory list to be displayed.
+    - number: Number of items in the inventory to be displayed.
+    - item: Position of item that is selected.
+    - direction
+
 Representations of simple things
 --------------------------------
 Position/vector:
@@ -412,9 +526,11 @@ a node is destroyable and how long it takes to destroy by a tool.
 Groups of entities
 -------------------
 For entities, groups are, as of now, used only for calculating damage.
+The rating is the percentage of damage caused by tools with this damage group.
+See "Entity damage mechanism".
 
-object.get_armor_groups() -> a group-rating table (eg. {fleshy=3})
-object.set_armor_groups({level=2, fleshy=2, cracky=2})
+object.get_armor_groups() -> a group-rating table (eg. {fleshy=100})
+object.set_armor_groups({fleshy=30, cracky=80})
 
 Groups of tools
 ----------------
@@ -435,7 +551,7 @@ An example: Make meat soup from any meat, any water and any bowl
 }
 An another example: Make red wool from white wool and red dye
 {
-	type = 'shapeless',
+    type = 'shapeless',
     output = 'wool:red',
     recipe = {'wool:white', 'group:dye,basecolor_red'},
 }
@@ -446,7 +562,7 @@ Special groups
 - level: Can be used to give an additional sense of progression in the game.
   - A larger level will cause eg. a weapon of a lower level make much less
     damage, and get weared out much faster, or not be able to get drops
-	from destroyed nodes.
+    from destroyed nodes.
   - 0 is something that is directly accessible at the start of gameplay
   - There is no upper limit
 - dig_immediate: (player can always pick up node without tool wear)
@@ -463,7 +579,6 @@ Special groups
 
 Known damage and digging time defining groups
 ----------------------------------------------
-Valid ratings for these are 0, 1, 2 and 3, unless otherwise stated.
 - crumbly: dirt, sand
 - cracky: tough but crackable stuff like stone.
 - snappy: something that can be cut using fine tools; eg. leaves, small
@@ -516,6 +631,7 @@ groups to enable interaction with tools.
     * Uses (until the tool breaks)
     * Maximum level (usually 0, 1, 2 or 3)
     * Digging times
+    * Damage groups
 
 **Full punch interval**:
 When used as a weapon, the tool will do full damage if this time is spent
@@ -547,17 +663,19 @@ maximum level.
     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
-    between hits, with a maximum time of ''full_punch_interval''.
+
+**Damage groups**
+List of damage for groups of entities. See "Entity damage mechanism".
 
 Example definition of the capabilities of a tool
 -------------------------------------------------
 tool_capabilities = {
-	full_punch_interval=1.5,
-	max_drop_level=1,
-	groupcaps={
-		crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
-	}
+    full_punch_interval=1.5,
+    max_drop_level=1,
+    groupcaps={
+        crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
+    }
+    damage_groups = {fleshy=2},
 }
 
 This makes the tool be able to dig nodes that fullfill both of these:
@@ -588,10 +706,12 @@ Notes:
 Entity damage mechanism
 ------------------------
 Damage calculation:
-- Take the time spent after the last hit
-- Limit time to full_punch_interval
-- 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 = 0
+foreach group in cap.damage_groups:
+    damage += cap.damage_groups[group] * limit(actual_interval / cap.full_punch_interval, 0.0, 1.0)
+        * (object.armor_groups[group] / 100.0)
+        -- Where object.armor_groups[group] is 0 for inexisting values
+return damage
 
 Client predicts damage based on damage groups. Because of this, it is able to
 give an immediate response when an entity is damaged or dies; the response is
@@ -717,7 +837,7 @@ field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
 ^ 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.
+    ^ Note: no extra text or more than a single variable is supported ATM.
 
 field[<name>;<label>;<default>]
 ^ as above but without position/size units
@@ -725,6 +845,9 @@ field[<name>;<label>;<default>]
 ^ 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
@@ -775,6 +898,9 @@ 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
+minetest.formspec_escape(string) -> string
+^ escapes characters like [, ], and \ that can not be used in formspecs
 
 minetest namespace reference
 -----------------------------
@@ -786,6 +912,11 @@ minetest.get_modnames() -> list of installed mods
 minetest.get_worldpath() -> eg. "/home/user/.minetest/world"
 ^ Useful for storing custom data
 minetest.is_singleplayer()
+minetest.features
+^ table containing API feature flags: {foo=true, bar=true}
+minetest.has_feature(arg) -> bool, missing_features
+^ arg: string or table in format {foo=true, bar=true}
+^ missing_features: {foo=true, bar=true}
 
 minetest.debug(line)
 ^ Always printed to stderr and logfile (print() is redirected here)
@@ -801,6 +932,7 @@ minetest.register_tool(name, item definition)
 minetest.register_craftitem(name, item definition)
 minetest.register_alias(name, convert_to)
 minetest.register_craft(recipe)
+minetest.register_ore(ore definition)
 
 Global callback registration functions: (Call these only at load time)
 minetest.register_globalstep(func(dtime))
@@ -857,6 +989,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:
@@ -875,10 +1008,12 @@ minetest.auth_reload()
 ^ These call the authentication handler
 minetest.check_player_privs(name, {priv1=true,...}) -> bool, missing_privs
 ^ A quickhand for checking privileges
+minetest.get_player_ip(name) -> IP address string
 
 Chat:
 minetest.chat_send_all(text)
-minetest.chat_send_player(name, text)
+minetest.chat_send_player(name, text, prepend)
+^ prepend: optional, if it is set to false "Server -!- " will not be prepended to the message
 
 Inventory:
 minetest.get_inventory(location) -> InvRef
@@ -888,8 +1023,10 @@ minetest.get_inventory(location) -> InvRef
 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, formspec)
+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:
@@ -913,12 +1050,30 @@ minetest.get_craft_result(input) -> output, decremented_input
 ^ output.time = number, if unsuccessful: 0
 ^ decremented_input = like input
 minetest.get_craft_recipe(output) -> input
+^ returns last registered recipe for output item (node)
 ^ 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.get_all_craft_recipes(query item) -> table or nil
+^ returns indexed table with all registered recipes for query item (node)
+  or nil if no recipe was found
+  recipe entry table:
+  { 
+   method = 'normal' or 'cooking' or 'fuel'
+   width = 0-3, 0 means shapeless recipe
+   items = indexed [1-9] table with recipe items
+   output = string with item name and quantity
+  }
+  Example query for default:gold_ingot will return table:
+  {
+   1={type = "cooking", width = 3, output = "default:gold_ingot",
+    items = {1 = "default:gold_lump"}},
+   2={type = "normal", width = 1, output = "default:gold_ingot 9",
+    items = {1 = "default:goldblock"}}
+  }
 minetest.handle_node_drops(pos, drops, digger)
 ^ drops: list of itemstrings
 ^ Handles drops from nodes after digging: Default action is to put them into
@@ -963,9 +1118,9 @@ minetest.sound_play(spec, parameters) -> handle
 minetest.sound_stop(handle)
 
 Timing:
-minetest.after(time, func, param)
+minetest.after(time, func, ...)
 ^ Call function after time seconds
-^ param is optional; to pass multiple parameters, pass a table.
+^ Optional: Variable number of arguments that are passed to func
 
 Server:
 minetest.request_shutdown() -> request for server shutdown
@@ -977,6 +1132,37 @@ 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
 
+Particles:
+minetest.add_particle(pos, velocity, acceleration, expirationtime,
+    size, collisiondetection, texture, playername)
+^ Spawn particle at pos with velocity and acceleration
+^ Disappears after expirationtime seconds
+^ collisiondetection: if true collides with physical objects
+^ Uses texture (string)
+^ Playername is optional, if specified spawns particle only on the player's client
+
+minetest.add_particlespawner(amount, time,
+    minpos, maxpos,
+    minvel, maxvel,
+    minacc, maxacc,
+    minexptime, maxexptime,
+    minsize, maxsize,
+    collisiondetection, texture, playername)
+^ Add a particlespawner, an object that spawns an amount of particles over time seconds
+^ The particle's properties are random values in between the boundings:
+^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
+^ minsize/maxsize, minexptime/maxexptime (expirationtime)
+^ collisiondetection: if true uses collisiondetection
+^ Uses texture (string)
+^ Playername is optional, if specified spawns particle only on the player's client
+^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
+^ Returns and id
+
+minetest.delete_particlespawner(id, player)
+^ Delete ParticleSpawner with id (return value from add_particlespawner)
+^ If playername is specified, only deletes on the player's client,
+^ otherwise on all clients
+
 Random:
 minetest.get_connected_players() -> list of ObjectRefs
 minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer
@@ -1067,60 +1253,82 @@ methods:
 - get_perlin(seeddiff, octaves, persistence, scale)
   ^ Return world-specific perlin noise (int(worldseed)+seeddiff)
 - clear_objects()
-  ^ clear all objects in the environments 
+  ^ clear all objects in the environments
+- line_of_sight(pos1,pos2,stepsize) ->true/false
+  ^ checkif there is a direct line of sight between pos1 and pos2
+  ^ pos1 First position
+  ^ pos2 Second position
+  ^ stepsize smaller gives more accurate results but requires more computing
+             time. Default is 1.
+-find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm) -> table containing path
+  ^ returns a table of 3d points representing a path from pos1 to pos2 or nil
+  ^ pos1: start position
+  ^ pos2: end position
+  ^ searchdistance: number of blocks to search in each direction
+  ^ max_jump: maximum height difference to consider walkable
+  ^ max_drop: maximum height difference to consider droppable
+  ^ algorithm: A*_noprefetch(default), A*, Dijkstra
 - 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
-      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
-      thin_trunks,  - boolean   true -> use thin trunks
-      fruit_tree,   - boolean   true -> is a fruit tree
-      fruit         - string    fruit node name
+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
+  seed,          - num     random seed
   }
 
-  Key for Special L-System Symbols used in Axioms
-    G  - move forward one unit with the pin down
-    F  - move forward one unit with the pin up
-    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,
-      thin_trunks=true,
-      fruit_tree=true,
-      fruit="default:apple"
+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)
+minetest.env:spawn_tree(pos,apple_tree)
 
 Deprecated:
 - add_rat(pos): Add C++ rat object (no-op)
@@ -1182,9 +1390,15 @@ methods:
 - 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_attach(parent, bone, position, rotation)
+  ^ bone = string
+  ^ position = {x=num, y=num, z=num} (relative)
+  ^ rotation = {x=num, y=num, z=num}
 - set_detach()
-- set_bone_position("", {x=0,y=0,z=0}, {x=0,y=0,z=0})
+- set_bone_position(bone, position, rotation)
+  ^ bone = string
+  ^ position = {x=num, y=num, z=num} (relative)
+  ^ rotation = {x=num, y=num, z=num}
 - set_properties(object property table)
 LuaEntitySAO-only: (no-op for other objects)
 - setvelocity({x=num, y=num, z=num})
@@ -1206,15 +1420,30 @@ 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_look_pitch(radians): sets look pitch
+- set_look_yaw(radians): sets look yaw
 - 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}
+    {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
-	
+    bit nr/meaning: 0/up ,1/down ,2/left ,3/right ,4/jump ,5/aux1 ,6/sneak ,7/LMB ,8/RMB
+- set_physics_override(speed, jump, gravity)
+    modifies per-player walking speed, jump height, and gravity.
+    Values default to 1 and act as offsets to the physics settings 
+    in minetest.conf. nil will keep the current setting.
+- hud_add(hud definition): add a HUD element described by HUD def, returns ID number on success
+- hud_remove(id): remove the HUD element of the specified id
+- hud_change(id, stat, value): change a value of a previously added HUD element
+  ^ element stat values: position, name, scale, text, number, item, dir
+- hud_get(id): gets the HUD element definition structure of the specified ID
+- hud_set_flags(flags): sets specified HUD flags to true/false
+  ^ flags: (is visible) hotbar, healthbar, crosshair, wielditem
+  ^ pass a table containing a true/false value of each flag to be set or unset
+  ^ if a flag is nil, the flag is not modified
+
 InvRef: Reference to an inventory
 methods:
 - is_empty(listname): return true if list is empty
@@ -1299,8 +1528,8 @@ Registered entities
     ^ puncher: ObjectRef (can be nil)
     ^ time_from_last_punch: Meant for disallowing spamming of clicks (can be nil)
     ^ tool_capabilities: capability table of used tool (can be nil)
-	^ dir: unit vector of direction of punch. Always defined. Points from
-	       the puncher to the punched.
+    ^ dir: unit vector of direction of punch. Always defined. Points from
+           the puncher to the punched.
   - on_rightclick(self, clicker)
   - get_staticdata(self)
     ^ Should return a string that will be passed to on_activate when
@@ -1375,10 +1604,10 @@ Item definition (register_node, register_craftitem, register_tool)
         max_drop_level=0,
         groupcaps={
             -- For example:
-            fleshy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
             snappy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
             choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
-        }
+        },
+        damage_groups = {groupname=damage},
     }
     node_placement_prediction = nil,
     ^ If nil and item is node, prediction is made automatically
@@ -1387,6 +1616,9 @@ Item definition (register_node, register_craftitem, register_tool)
     ^ 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.
+    sound = {
+        place = <SimpleSoundSpec>,
+    }
 
     on_place = func(itemstack, placer, pointed_thing),
     ^ Shall place item and return the leftover itemstack
@@ -1421,12 +1653,13 @@ Node definition (register_node)
     drawtype = "normal", -- See "Node drawtypes"
     visual_scale = 1.0,
     tiles = {tile definition 1, def2, def3, def4, def5, def6},
-	^ Textures of node; +Y, -Y, +X, -X, +Z, -Z (old field name: tile_images)
+    ^ 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)
+    ^ Special textures of node; used rarely (old field name: special_materials)
     ^ List can be shortened to needed length
     alpha = 255,
+    use_texture_alpha = false, -- Use texture's alpha channel
     post_effect_color = {a=0, r=0, g=0, b=0}, -- If player is inside node
     paramtype = "none", -- See "Nodes"
     paramtype2 = "none", -- See "Nodes"
@@ -1448,12 +1681,14 @@ Node definition (register_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"
+    ^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used
     legacy_facedir_simple = false, -- Support maps made in and before January 2012
     legacy_wallmounted = false, -- Support maps made in and before January 2012
     sounds = {
         footstep = <SimpleSoundSpec>,
         dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
         dug = <SimpleSoundSpec>,
+        place = <SimpleSoundSpec>,
     },
 
     on_construct = func(pos),
@@ -1480,12 +1715,14 @@ Node definition (register_node)
     can_dig = function(pos,player)
     ^ returns true if node can be dug, or false if not
     ^ default: nil
-	
+    
     on_punch = func(pos, node, puncher),
     ^ default: minetest.node_punch
     ^ By default: does nothing
-    on_rightclick = func(pos, node, clicker),
+    on_rightclick = func(pos, node, clicker, itemstack),
     ^ default: nil
+    ^ if defined, itemstack will hold clicker's wielded item
+      Shall return the leftover itemstack
     on_dig = func(pos, node, digger),
     ^ default: minetest.node_dig
     ^ By default: checks privileges, wears out tool and removes node
@@ -1501,32 +1738,32 @@ Node definition (register_node)
     ^ Called when an UI form (eg. sign text input) returns data
     ^ default: nil
 
-	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_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
+    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
+    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)
@@ -1575,6 +1812,30 @@ Recipe for register_craft (furnace fuel)
     burntime = 1,
 }
 
+Ore definition (register_ore)
+{
+    ore_type = "scatter" -- See "Ore types"
+    ore = "default:stone_with_coal",
+    wherein = "default:stone",
+    clust_scarcity = 8*8*8,
+    ^ Ore has a 1 out of clust_scarcity chance of spawning in a node
+    ^ This value should be *MUCH* higher than your intuition might tell you!
+    clust_num_ores = 8,
+    ^ Number of ores in a cluster
+    clust_size = 3,
+    ^ Size of the bounding box of the cluster
+    ^ In this example, there is a 3x3x3 cluster where 8 out of the 27 nodes are coal ore
+    height_min = -31000,
+    height_max = 64,
+    flags = "",
+    ^ Attributes for this ore generation
+    noise_threshhold = 0.5,
+    ^ If noise is above this threshhold, ore is placed.  Not needed for a uniform distribution
+    noise_params = {offset=0, scale=1, spread={x=100, y=100, z=100}, seed=23, octaves=3, persist=0.70}
+    ^ NoiseParams structure describing the perlin noise used for ore distribution.
+    ^ Needed for sheet ore_type.  Omit from scatter ore_type for a uniform ore distribution
+}
+
 Chatcommand definition (register_chatcommand)
 {
     params = "<name> <privilege>", -- short parameter description
@@ -1585,24 +1846,43 @@ Chatcommand definition (register_chatcommand)
 
 Detached inventory callbacks
 {
-	allow_move = func(inv, from_list, from_index, to_list, to_index, count, player),
+    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
-	
+    ^ 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
+    ^ 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),
+    ^ 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
+    ^ Called after the actual action has happened, according to what was allowed.
+    ^ No return value
 }
 
+HUD Definition (hud_add, hud_get)
+{
+    hud_elem_type = "image", -- see HUD element types
+    ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
+    position = {x=0.5, y=0.5},
+    ^ Left corner position of element
+    name = "<name>",
+    scale = {x=2, y=2},
+    text = "<text>",
+    number = 2,
+    item = 3,
+    ^ Selected item in inventory.  0 for no item selected.
+    direction = 0,
+    ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
+    alignment = {x=0, y=0},
+    ^ See "HUD Element Types"
+    offset = {x=0, y=0},
+    ^ See "HUD Element Types"
+}