From 7b1bc26170792e6a6fb230aa778dc53792b0fe87 Mon Sep 17 00:00:00 2001
From: rubenwardy <rubenwardy@gmail.com>
Date: Wed, 29 Apr 2015 18:17:32 +0100
Subject: [PATCH] Update lua_api.html

---
 lua_api.html      | 129 ++++++++++++++++++++++++++++++++++++++--------
 update_lua_api.py |   6 ++-
 2 files changed, 113 insertions(+), 22 deletions(-)

diff --git a/lua_api.html b/lua_api.html
index ef8ca8d..e9b16ed 100644
--- a/lua_api.html
+++ b/lua_api.html
@@ -246,26 +246,30 @@ layout: default
 <li><a href="#methods_5">Methods</a></li>
 </ul>
 </li>
-<li><a href="#perlinnoise">PerlinNoise</a><ul>
+<li><a href="#pcgrandom">PcgRandom</a><ul>
 <li><a href="#methods_6">Methods</a></li>
 </ul>
 </li>
-<li><a href="#perlinnoisemap">PerlinNoiseMap</a><ul>
+<li><a href="#perlinnoise">PerlinNoise</a><ul>
 <li><a href="#methods_7">Methods</a></li>
 </ul>
 </li>
-<li><a href="#voxelmanip">VoxelManip</a><ul>
+<li><a href="#perlinnoisemap">PerlinNoiseMap</a><ul>
 <li><a href="#methods_8">Methods</a></li>
 </ul>
 </li>
-<li><a href="#voxelarea">VoxelArea</a><ul>
+<li><a href="#voxelmanip">VoxelManip</a><ul>
 <li><a href="#methods_9">Methods</a></li>
 </ul>
 </li>
-<li><a href="#settings">Settings</a><ul>
+<li><a href="#voxelarea">VoxelArea</a><ul>
 <li><a href="#methods_10">Methods</a></li>
 </ul>
 </li>
+<li><a href="#settings">Settings</a><ul>
+<li><a href="#methods_11">Methods</a></li>
+</ul>
+</li>
 </ul>
 </li>
 <li><a href="#mapgen-objects">Mapgen objects</a><ul>
@@ -322,7 +326,7 @@ source code patches to <a href="&#109;&#97;&#105;&#108;&#116;&#111;&#58;&#99;&#1
 <ul>
 <li>More information at <a href="http://www.minetest.net/">http://www.minetest.net/</a></li>
 <li>Developer Wiki: <a href="http://dev.minetest.net/">http://dev.minetest.net/</a></li>
-</ul><h2 id="programming-in-lua">Programming in Lua</h2>
+</ul>This page was last updated 29/April/2015.<br />See <a href="https://github.com/minetest/minetest/blob/master/doc/lua_api.txt">doc/lua_api.txt</a> for the latest version (in plaintext).<br />Generated using <a href="https://github.com/rubenwardy/minetest_modding_book/blob/gh-pages/update_lua_api.py">a Python script</a>.<h2 id="programming-in-lua">Programming in Lua</h2>
 <p>If you have any difficulty in understanding this, please read
 <a href="http://www.lua.org/pil/">Programming in Lua</a>.</p>
 <h2 id="startup">Startup</h2>
@@ -668,6 +672,14 @@ the global <code>minetest.registered_*</code> tables.</p>
 </ul>
 </li>
 <li>
+<p><code>minetest.register_biome(biome definition)</code></p>
+<ul>
+<li>returns an integer uniquely identifying the registered biome</li>
+<li>added to <code>minetest.registered_biome</code> with the key of <code>biome.name</code></li>
+<li>if <code>biome.name</code> is nil, the key is the returned ID</li>
+</ul>
+</li>
+<li>
 <p><code>minetest.register_ore(ore definition)</code></p>
 <ul>
 <li>returns an integer uniquely identifying the registered ore</li>
@@ -684,16 +696,41 @@ the global <code>minetest.registered_*</code> tables.</p>
 </ul>
 </li>
 <li>
-<p><code>minetest.clear_registered_ores()</code></p>
+<p><code>minetest.register_schematic(schematic definition)</code></p>
+<ul>
+<li>returns an integer uniquely identifying the registered schematic</li>
+<li>added to <code>minetest.registered_schematic</code> with the key of <code>schematic.name</code></li>
+<li>if <code>schematic.name</code> is nil, the key is the returned ID</li>
+<li>if the schematic is loaded from a file, schematic.name is set to the filename</li>
+<li>if the function is called when loading the mod, and schematic.name is a relative path,</li>
+<li>then the current mod path will be prepended to the schematic filename</li>
+</ul>
 </li>
 <li>
-<p>clears all ores currently registered</p>
+<p><code>minetest.clear_registered_biomes()</code></p>
+<ul>
+<li>clears all biomes currently registered</li>
+</ul>
+</li>
+<li>
+<p><code>minetest.clear_registered_ores()</code></p>
+<ul>
+<li>clears all ores currently registered</li>
+</ul>
 </li>
 <li>
 <p><code>minetest.clear_registered_decorations()</code></p>
-</li>
+<ul>
 <li>clears all decorations currently registered</li>
 </ul>
+</li>
+<li>
+<p><code>minetest.clear_registered_schematics()</code></p>
+<ul>
+<li>clears all schematics currently registered</li>
+</ul>
+</li>
+</ul>
 <p>Note that in some cases you will stumble upon things that are not contained
 in these tables (e.g. when a mod has been removed). Always check for
 existence before trying to access the fields.</p>
@@ -1848,7 +1885,7 @@ value must (always) be two hexadecimal digits.</p>
 <h2 id="minetest-namespace-reference"><code>minetest</code> namespace reference</h2>
 <h3 id="utilities">Utilities</h3>
 <ul>
-<li><code>minetest.get_current_modname()</code>: returns a string</li>
+<li><code>minetest.get_current_modname()</code>: returns the currently loading mod's name, when we are loading a mod</li>
 <li><code>minetest.get_modpath(modname)</code>: returns e.g. <code>"/home/user/.minetest/usermods/modname"</code><ul>
 <li>Useful for loading additional <code>.lua</code> modules or static data from mod</li>
 </ul>
@@ -2236,10 +2273,16 @@ and <code>minetest.auth_reload</code> call the authetification handler.</p>
   should be applied to the default config or current active config</li>
 </ul>
 </li>
-<li><code>minetest.generate_ores(vm, p1, p2)</code></li>
-<li>Generate all registered ores within the VoxelManip <code>vm</code> and in the area from p1 to p2.</li>
-<li><code>minetest.generate_decorations(vm, p1, p2)</code></li>
-<li>Generate all registered decorations within the VoxelManip <code>vm</code> and in the area from p1 to p2.</li>
+<li><code>minetest.generate_ores(vm, pos1, pos2)</code><ul>
+<li>Generate all registered ores within the VoxelManip <code>vm</code> and in the area from <code>pos1</code> to <code>pos2</code>.</li>
+<li><code>pos1</code> and <code>pos2</code> are optional and default to mapchunk minp and maxp.</li>
+</ul>
+</li>
+<li><code>minetest.generate_decorations(vm, pos1, pos2)</code><ul>
+<li>Generate all registered decorations within the VoxelManip <code>vm</code> and in the area from <code>pos1</code> to <code>pos2</code>.</li>
+<li><code>pos1</code> and <code>pos2</code> are optional and default to mapchunk minp and maxp.</li>
+</ul>
+</li>
 <li><code>minetest.clear_objects()</code><ul>
 <li>clear all objects in the environments</li>
 </ul>
@@ -2596,6 +2639,27 @@ and <code>minetest.auth_reload</code> call the authetification handler.</p>
   <code>ignore</code> are replaced by the schematic</li>
 </ul>
 </li>
+<li>
+<p><code>minetest.serialize_schematic(schematic, format, options)</code></p>
+<ul>
+<li>Return the serialized schematic specified by schematic (see: Schematic specifier)</li>
+<li>in the <code>format</code> of either "mts" or "lua".</li>
+<li>"mts" - a string containing the binary MTS data used in the MTS file format</li>
+<li>"lua" - a string containing Lua code representing the schematic in table format</li>
+<li><code>options</code> is a table containing the following optional parameters:</li>
+<li>If <code>use_comments</code> is true and <code>format</code> is "lua", the Lua code generated will have (X, Z)</li>
+<li>position comments for every X row generated in the schematic data for easier reading.</li>
+<li>If <code>register_after_load</code> is true, then <code>schematic</code>, if not yet loaded, will be registered</li>
+<li>after loading and persist in memory.</li>
+<li>node_resolve_method can be one of either "none", "direct", or "deferred" (default: "none")</li>
+<li>This sets the way method by with node names are mapped to their content IDs, if loaded:</li>
+<li>"none" performs no node resolution and preserves all node names from the schematic definition</li>
+<li>"direct" performs an immediate lookup of content ID, given all the nodes that have been</li>
+<li>registered up to this point in script execution</li>
+<li>"deferred" pends node resolution until after the script registration phase has ended</li>
+<li>In practice, it is recommended to use "none" in nearly all use cases.</li>
+</ul>
+</li>
 </ul>
 <h3 id="misc">Misc.</h3>
 <ul>
@@ -2743,6 +2807,8 @@ end
 </li>
 </ul>
 <p>Please note that forceloaded areas are saved when the server restarts.</p>
+<p>minetest.global_exists(name)
+^ Checks if a global variable has been set, without triggering a warning.</p>
 <h3 id="global-objects">Global objects</h3>
 <ul>
 <li><code>minetest.env</code>: <code>EnvRef</code> of the server environment and world.<ul>
@@ -3095,7 +3161,8 @@ an itemstring, a table or <code>nil</code>.</p>
   Returns taken <code>ItemStack</code>.</li>
 </ul>
 <h3 id="pseudorandom"><code>PseudoRandom</code></h3>
-<p>A pseudorandom number generator.</p>
+<p>A 16-bit pseudorandom number generator.
+Uses a well-known LCG algorithm introduced by K&amp;R.</p>
 <p>It can be created via <code>PseudoRandom(seed)</code>.</p>
 <h4 id="methods_5">Methods</h4>
 <ul>
@@ -3106,13 +3173,27 @@ an itemstring, a table or <code>nil</code>.</p>
 </ul>
 </li>
 </ul>
+<h3 id="pcgrandom"><code>PcgRandom</code></h3>
+<p>A 32-bit pseudorandom number generator.
+Uses PCG32, an algorithm of the permuted congruential generator family, offering very strong randomness.</p>
+<p>It can be created via <code>PcgRandom(seed)</code> or <code>PcgRandom(seed, sequence)</code>.</p>
+<h4 id="methods_6">Methods</h4>
+<ul>
+<li><code>next()</code>: return next integer random number [<code>-2147483648</code>...<code>2147483647</code>]</li>
+<li><code>next(min, max)</code>: return next integer random number [<code>min</code>...<code>max</code>]</li>
+<li><code>rand_normal_dist(min, max, num_trials=6)</code>: return normally distributed random number [<code>min</code>...<code>max</code>]<ul>
+<li>This is only a rough approximation of a normal distribution with mean=(max-min)/2 and variance=1</li>
+<li>Increasing num_trials improves accuracy of the approximation</li>
+</ul>
+</li>
+</ul>
 <h3 id="perlinnoise"><code>PerlinNoise</code></h3>
 <p>A perlin noise generator.
 It can be created via <code>PerlinNoise(seed, octaves, persistence, scale)</code>
 or <code>PerlinNoise(noiseparams)</code>.
 Alternatively with <code>minetest.get_perlin(seeddiff, octaves, persistence, scale)</code>
 or <code>minetest.get_perlin(noiseparams)</code>.</p>
-<h4 id="methods_6">Methods</h4>
+<h4 id="methods_7">Methods</h4>
 <ul>
 <li><code>get2d(pos)</code>: returns 2D noise value at <code>pos={x=,y=}</code></li>
 <li><code>get3d(pos)</code>: returns 3D noise value at <code>pos={x=,y=,z=}</code></li>
@@ -3124,7 +3205,7 @@ or <code>minetest.get_perlin(noiseparams)</code>.</p>
 <p>Format of <code>size</code> is <code>{x=dimx, y=dimy, z=dimz}</code>.  The <code>z</code> conponent is ommitted
 for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
 <code>nil</code> is returned).</p>
-<h4 id="methods_7">Methods</h4>
+<h4 id="methods_8">Methods</h4>
 <ul>
 <li><code>get2dMap(pos)</code>: returns a <code>&lt;size.x&gt;</code> times <code>&lt;size.y&gt;</code> 2D array of 2D noise
   with values starting at <code>pos={x=,y=}</code></li>
@@ -3138,7 +3219,7 @@ for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
 <p>An interface to the <code>MapVoxelManipulator</code> for Lua.</p>
 <p>It can be created via <code>VoxelManip()</code> or <code>minetest.get_voxel_manip()</code>.
 The map will be pre-loaded if two positions are passed to either.</p>
-<h4 id="methods_8">Methods</h4>
+<h4 id="methods_9">Methods</h4>
 <ul>
 <li><code>read_from_map(p1, p2)</code>:  Reads a chunk of map from the map containing the
   region formed by <code>p1</code> and <code>p2</code>.<ul>
@@ -3199,7 +3280,7 @@ The map will be pre-loaded if two positions are passed to either.</p>
 <p>A helper class for voxel areas.
 It can be created via <code>VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}</code>.
 The coordinates are <em>inclusive</em>, like most other things in Minetest.</p>
-<h4 id="methods_9">Methods</h4>
+<h4 id="methods_10">Methods</h4>
 <ul>
 <li><code>getExtent()</code>: returns a 3D vector containing the size of the area formed by
   <code>MinEdge</code> and <code>MaxEdge</code></li>
@@ -3223,7 +3304,7 @@ The coordinates are <em>inclusive</em>, like most other things in Minetest.</p>
 <h3 id="settings"><code>Settings</code></h3>
 <p>An interface to read config files in the format of <code>minetest.conf</code>.</p>
 <p>It can be created via <code>Settings(filename)</code>.</p>
-<h4 id="methods_10">Methods</h4>
+<h4 id="methods_11">Methods</h4>
 <ul>
 <li><code>get(key)</code>: returns a value</li>
 <li><code>get_bool(key)</code>: returns a boolean</li>
@@ -3604,7 +3685,7 @@ minetest.spawn_tree(pos,apple_tree)
     ^ Called after destructing node when node was dug using
       minetest.node_dig / minetest.dig_node
     ^ default: nil ]]
-    can_dig = function(pos,player) --[[
+    can_dig = function(pos, [player]) --[[
     ^ returns true if node can be dug, or false if not
     ^ default: nil ]]
 
@@ -3733,6 +3814,10 @@ minetest.spawn_tree(pos,apple_tree)
 --  ^ Multiplier of the randomness contribution to the noise value at any
 --   given point to decide if ore should be placed.  Set to 0 for solid veins.
 --  ^ This parameter is only valid for ore_type == "vein".
+    biomes = {"desert", "rainforest"}
+--  ^ List of biomes in which this decoration occurs.  Occurs in all biomes if this is omitted,
+--  ^ and ignored if the Mapgen being used does not support biomes.
+--  ^ Can be a list of (or a single) biome names, IDs, or definitions.
 }
 </code></pre>
 <h3 id="decoration-definition-register_decoration">Decoration definition (<code>register_decoration</code>)</h3>
@@ -3752,6 +3837,7 @@ minetest.spawn_tree(pos,apple_tree)
     biomes = {"Oceanside", "Hills", "Plains"},
 --  ^ List of biomes in which this decoration occurs.  Occurs in all biomes if this is omitted,
 --  ^ and ignored if the Mapgen being used does not support biomes.
+--  ^ Can be a list of (or a single) biome names, IDs, or definitions.
     y_min = -31000
     y_max = 31000
 -- ^ Minimum and maximum `y` positions these decorations can be generated at.
@@ -3778,6 +3864,7 @@ minetest.spawn_tree(pos,apple_tree)
     schematic = "foobar.mts",
 --  ^ If schematic is a string, it is the filepath relative to the current working directory of the
 --  ^ specified Minetest schematic file.
+--  ^  - OR -, could be the ID of a previously registered schematic
 --  ^  - OR -, could instead be a table containing two mandatory fields, size and data,
 --  ^ and an optional table yslice_prob:
     schematic = {
diff --git a/update_lua_api.py b/update_lua_api.py
index 4475f6a..d8e7c80 100644
--- a/update_lua_api.py
+++ b/update_lua_api.py
@@ -1,4 +1,4 @@
-import markdown, urllib2
+import markdown, urllib2, datetime
 
 
 #
@@ -27,6 +27,10 @@ links = """<ul>
 
 html = md.convert(text).replace("{{", "{ {")
 html = html.replace(links, "")
+links += "This page was last updated "
+links += datetime.date.today().strftime("%d/%B/%Y")
+links += ".<br />See <a href=\"https://github.com/minetest/minetest/blob/master/doc/lua_api.txt\">doc/lua_api.txt</a> for the latest version (in plaintext)."
+links += "<br />Generated using <a href=\"https://github.com/rubenwardy/minetest_modding_book/blob/gh-pages/update_lua_api.py\">a Python script</a>."
 html = html.replace("<h2 id=\"programming-in-lua\">", links + "<h2 id=\"programming-in-lua\">")
 
 #