From 8e08ccf525782dedac98325054203f882f5bedc9 Mon Sep 17 00:00:00 2001
From: rubenwardy <rubenwardy@gmail.com>
Date: Sat, 21 Nov 2015 15:26:52 +0000
Subject: [PATCH] Update lua_api.html

---
 .gitignore        |   2 +
 lua_api.html      | 226 +++++++++++++++++++++++++++++++++++++++++-----
 update_lua_api.py |  10 +-
 3 files changed, 212 insertions(+), 26 deletions(-)

diff --git a/.gitignore b/.gitignore
index 924f80b..25b78cb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,4 @@
 _site
 .directory
+.jekyll-metadata
+*~*
diff --git a/lua_api.html b/lua_api.html
index d042d44..ff73b37 100644
--- a/lua_api.html
+++ b/lua_api.html
@@ -264,26 +264,39 @@ layout: default
 <li><a href="#methods_7">Methods</a></li>
 </ul>
 </li>
-<li><a href="#perlinnoise">PerlinNoise</a><ul>
+<li><a href="#securerandom">SecureRandom</a><ul>
 <li><a href="#methods_8">Methods</a></li>
 </ul>
 </li>
-<li><a href="#perlinnoisemap">PerlinNoiseMap</a><ul>
+<li><a href="#perlinnoise">PerlinNoise</a><ul>
 <li><a href="#methods_9">Methods</a></li>
 </ul>
 </li>
-<li><a href="#voxelmanip">VoxelManip</a><ul>
+<li><a href="#perlinnoisemap">PerlinNoiseMap</a><ul>
 <li><a href="#methods_10">Methods</a></li>
 </ul>
 </li>
-<li><a href="#voxelarea">VoxelArea</a><ul>
+<li><a href="#voxelmanip">VoxelManip</a><ul>
+<li><a href="#about-voxelmanip">About VoxelManip</a></li>
+<li><a href="#using-voxelmanip">Using VoxelManip</a><ul>
+<li><a href="#flat-array-format">Flat array format</a></li>
+<li><a href="#content-ids">Content IDs</a></li>
+<li><a href="#mapgen-voxelmanip-objects">Mapgen VoxelManip objects</a></li>
+<li><a href="#other-api-functions-operating-on-a-voxelmanip">Other API functions operating on a VoxelManip</a></li>
+<li><a href="#notes">Notes</a></li>
+</ul>
+</li>
 <li><a href="#methods_11">Methods</a></li>
 </ul>
 </li>
-<li><a href="#settings">Settings</a><ul>
+<li><a href="#voxelarea">VoxelArea</a><ul>
 <li><a href="#methods_12">Methods</a></li>
 </ul>
 </li>
+<li><a href="#settings">Settings</a><ul>
+<li><a href="#methods_13">Methods</a></li>
+</ul>
+</li>
 </ul>
 </li>
 <li><a href="#mapgen-objects">Mapgen objects</a><ul>
@@ -340,7 +353,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>This page was last updated 26/October/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>
+</ul>This page was last updated 21/November/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>
@@ -2415,9 +2428,35 @@ and <code>minetest.auth_reload</code> call the authetification handler.</p>
 <li>clear all objects in the environments</li>
 </ul>
 </li>
-<li><code>minetest.emerge_area(pos1, pos2)</code><ul>
-<li>queues all mapblocks in the area from pos1 to pos2, inclusive, for emerge</li>
-<li>i.e. asynchronously loads blocks from disk, or if inexistent, generates them</li>
+<li><code>minetest.emerge_area(pos1, pos2, [callback], [param])</code><ul>
+<li>Queue all blocks in the area from <code>pos1</code> to <code>pos2</code>, inclusive, to be asynchronously</li>
+<li>fetched from memory, loaded from disk, or if inexistent, generates them.</li>
+<li>If <code>callback</code> is a valid Lua function, this will be called for each block emerged.</li>
+<li>The function signature of callback is:</li>
+<li><code>function EmergeAreaCallback(blockpos, action, calls_remaining, param)</code></li>
+<li>
+<ul>
+<li><code>blockpos</code> is the <em>block</em> coordinates of the block that had been emerged</li>
+</ul>
+</li>
+<li>
+<ul>
+<li><code>action</code> could be one of the following constant values:</li>
+</ul>
+</li>
+<li><code>core.EMERGE_CANCELLED</code>, <code>core.EMERGE_ERRORED</code>, <code>core.EMERGE_FROM_MEMORY</code>,</li>
+<li><code>core.EMERGE_FROM_DISK</code>, <code>core.EMERGE_GENERATED</code></li>
+<li>
+<ul>
+<li><code>calls_remaining</code> is the number of callbacks to be expected after this one</li>
+</ul>
+</li>
+<li>
+<ul>
+<li><code>param</code> is the user-defined parameter passed to emerge_area (or nil if the</li>
+</ul>
+</li>
+<li>parameter was absent)</li>
 </ul>
 </li>
 <li><code>minetest.delete_area(pos1, pos2)</code><ul>
@@ -2773,6 +2812,18 @@ and <code>minetest.auth_reload</code> call the authetification handler.</p>
 <li><code>replacements</code> = <code>{["old_name"] = "convert_to", ...}</code></li>
 <li><code>force_placement</code> is a boolean indicating whether nodes other than <code>air</code> and
   <code>ignore</code> are replaced by the schematic</li>
+<li>Returns nil if the schematic could not be loaded.</li>
+</ul>
+</li>
+<li>
+<p><code>minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement)</code>:</p>
+<ul>
+<li>This function is analagous to minetest.place_schematic, but places a schematic onto the
+  specified VoxelManip object <code>vmanip</code> instead of the whole map.</li>
+<li>Returns false if any part of the schematic was cut-off due to the VoxelManip not
+  containing the full area required, and true if the whole schematic was able to fit.</li>
+<li>Returns nil if the schematic could not be loaded.</li>
+<li>After execution, any external copies of the VoxelManip contents are invalidated.</li>
 </ul>
 </li>
 <li>
@@ -3386,13 +3437,21 @@ Uses PCG32, an algorithm of the permuted congruential generator family, offering
 </ul>
 </li>
 </ul>
+<h3 id="securerandom"><code>SecureRandom</code></h3>
+<p>Interface for the operating system's crypto-secure PRNG.</p>
+<p>It can be created via <code>SecureRandom()</code>.  The constructor returns nil if a secure random device cannot be
+be found on the system.</p>
+<h4 id="methods_8">Methods</h4>
+<ul>
+<li><code>next_bytes([count])</code>: return next <code>count</code> (default 1, capped at 2048) many random bytes, as a string.</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_8">Methods</h4>
+<h4 id="methods_9">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>
@@ -3406,7 +3465,7 @@ for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
 <code>nil</code> is returned).</p>
 <p>For each of the functions with an optional <code>buffer</code> parameter:  If <code>buffer</code> is not
 nil, this table will be used to store the result instead of creating a new table.</p>
-<h4 id="methods_9">Methods</h4>
+<h4 id="methods_10">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>
@@ -3429,25 +3488,145 @@ nil, this table will be used to store the result instead of creating a new table
   <code>noisevals = noise:getMapSlice({x=24, z=1}, {x=1, z=1})</code></li>
 </ul>
 <h3 id="voxelmanip"><code>VoxelManip</code></h3>
-<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_10">Methods</h4>
+<h4 id="about-voxelmanip">About VoxelManip</h4>
+<p>VoxelManip is a scripting interface to the internal 'Map Voxel Manipulator' facility.  The purpose of
+this object is for fast, low-level, bulk access to reading and writing Map content.  As such, setting
+map nodes through VoxelManip will lack many of the higher level features and concepts you may be used
+to with other methods of setting nodes.  For example, nodes will not have their construction and
+destruction callbacks run, and no rollback information is logged.</p>
+<p>It is important to note that VoxelManip is designed for speed, and <em>not</em> ease of use or flexibility.
+If your mod requires a map manipulation facility that will handle 100% of all edge cases, or the use
+of high level node placement features, perhaps minetest.set_node() is better suited for the job.</p>
+<p>In addition, VoxelManip might not be faster, or could even be slower, for your specific use case.
+VoxelManip is most effective when setting very large areas of map at once - for example, if only
+setting a 5x5x5 node area, a minetest.set_node() loop may be more optimal.  Always profile code
+using both methods of map manipulation to determine which is most appropriate for your usage.</p>
+<h4 id="using-voxelmanip">Using VoxelManip</h4>
+<p>A VoxelManip object can be created any time using either:
+<code>VoxelManip([p1, p2])</code>, or <code>minetest.get_voxel_manip([p1, p2])</code>.</p>
+<p>If the optional position parameters are present for either of these routines, the specified region
+will be pre-loaded into the VoxelManip object on creation.  Otherwise, the area of map you wish to
+manipulate must first be loaded into the VoxelManip object using <code>VoxelManip:read_from_map()</code>.</p>
+<p>Note that <code>VoxelManip:read_from_map()</code> returns two position vectors.  The region formed by these
+positions indicate the minimum and maximum (respectively) positions of the area actually loaded in
+the VoxelManip, which may be larger than the area requested.  For convenience, the loaded area
+coordinates can also be queried any time after loading map data with <code>VoxelManip:get_emerged_area()</code>.</p>
+<p>Now that the VoxelManip object is populated with map data, your mod can fetch a copy of this data
+using either of two methods.  <code>VoxelManip:get_node_at()</code>, which retrieves an individual node in a
+MapNode formatted table at the position requested is the simplest method to use, but also the slowest.</p>
+<p>Nodes in a VoxelManip object may also be read in bulk to a flat array table using:
+<code>VoxelManip:get_data()</code> for node content (in Content ID form, see section 'Content IDs'),
+<code>VoxelManip:get_light_data()</code> for node light levels, and
+<code>VoxelManip:get_param2_data()</code> for the node type-dependent "param2" values.</p>
+<p>See section 'Flat array format' for more details.</p>
+<p>It is very important to understand that the tables returned by any of the above three functions
+represent a snapshot of the VoxelManip's internal state at the time of the call.  This copy of the
+data will <em>not</em> magically update itself if another function modifies the internal VoxelManip state.
+Any functions that modify a VoxelManip's contents work on the VoxelManip's internal state unless
+otherwise explicitly stated.</p>
+<p>Once the bulk data has been edited to your liking, the internal VoxelManip state can be set using:
+<code>VoxelManip:set_data()</code> for node content (in Content ID form, see section 'Content IDs'),
+<code>VoxelManip:set_light_data()</code> for node light levels, and
+<code>VoxelManip:set_param2_data()</code> for the node type-dependent "param2" values.</p>
+<p>The parameter to each of the above three functions can use any table at all in the same flat array
+format as produced by get_data() et al. and is <em>not required</em> to be a table retrieved from get_data().</p>
+<p>Once the internal VoxelManip state has been modified to your liking, the changes can be committed back
+to the map by calling <code>VoxelManip:write_to_map()</code>.</p>
+<p>Finally, a call to <code>VoxelManip:update_map()</code> is required to re-calculate lighting and set the blocks
+as being modified so that connected clients are sent the updated parts of map.</p>
+<h5 id="flat-array-format">Flat array format</h5>
+<p>Let
+    <code>Nx = p2.X - p1.X + 1</code>,
+    <code>Ny = p2.Y - p1.Y + 1</code>, and
+    <code>Nz = p2.Z - p1.Z + 1</code>.</p>
+<p>Then, for a loaded region of p1..p2, this array ranges from <code>1</code> up to and including the value of
+the expression <code>Nx * Ny * Nz</code>.</p>
+<p>Positions offset from p1 are present in the array with the format of:
+<code>[
+    (0, 0, 0),   (1, 0, 0),   (2, 0, 0),   ... (Nx, 0, 0),
+    (0, 1, 0),   (1, 1, 0),   (2, 1, 0),   ... (Nx, 1, 0),
+    ...
+    (0, Ny, 0),  (1, Ny, 0),  (2, Ny, 0),  ... (Nx, Ny, 0),
+    (0, 0, 1),   (1, 0, 1),   (2, 0, 1),   ... (Nx, 0, 1),
+    ...
+    (0, Ny, 2),  (1, Ny, 2),  (2, Ny, 2),  ... (Nx, Ny, 2),
+    ...
+    (0, Ny, Nz), (1, Ny, Nz), (2, Ny, Nz), ... (Nx, Ny, Nz)
+]</code></p>
+<p>and the array index for a position p contained completely in p1..p2 is:</p>
+<p><code>(p.Z - p1.Z) * Ny * Nx + (p.Y - p1.Y) * Nx + (p.X - p1.X) + 1</code></p>
+<p>Note that this is the same "flat 3D array" format as <code>PerlinNoiseMap:get3dMap_flat()</code>.
+VoxelArea objects (see section 'VoxelArea') can be used to simplify calculation of the index
+for a single point in a flat VoxelManip array.</p>
+<h5 id="content-ids">Content IDs</h5>
+<p>A Content ID is a unique integer identifier for a specific node type.  These IDs are used by VoxelManip
+in place of the node name string for <code>VoxelManip:get_data()</code> and <code>VoxelManip:set_data()</code>.  You can use
+<code>minetest.get_content_id()</code> to look up the Content ID for the specified node name, and
+<code>minetest.get_name_from_content_id()</code> to look up the node name string for a given Content ID.
+After registration of a node, its Content ID will remain the same throughout execution of the mod.
+Note that the node being queried needs to have already been been registered.</p>
+<p>The following builtin node types have their Content IDs defined as constants:
+<code>core.CONTENT_UNKNOWN (ID for "unknown" nodes)
+core.CONTENT_AIR     (ID for "air" nodes)
+core.CONTENT_IGNORE  (ID for "ignore" nodes)</code></p>
+<h5 id="mapgen-voxelmanip-objects">Mapgen VoxelManip objects</h5>
+<p>Inside of <code>on_generated()</code> callbacks, it is possible to retrieve the same VoxelManip object used by the
+core's Map Generator (commonly abbreviated Mapgen).  Most of the rules previously described still apply
+but with a few differences:
+<em> The Mapgen VoxelManip object is retrieved using: <code>minetest.get_mapgen_object("voxelmanip")</code>
+</em> This VoxelManip object already has the region of map just generated loaded into it; it's not necessary
+  to call <code>VoxelManip:read_from_map()</code> before using a Mapgen VoxelManip.
+<em> The <code>on_generated()</code> callbacks of some mods may place individual nodes in the generated area using
+  non-VoxelManip map modification methods.  Because the same Mapgen VoxelManip object is passed through
+  each <code>on_generated()</code> callback, it becomes necessary for the Mapgen VoxelManip object to maintain
+  consistency with the current map state.  For this reason, calling any of the following functions:
+  <code>minetest.add_node()</code>, <code>minetest.set_node()</code>, or <code>minetest.swap_node()</code>
+  will also update the Mapgen VoxelManip object's internal state active on the current thread.
+</em> After modifying the Mapgen VoxelManip object's internal buffer, it may be necessary to update lighting
+  information using either: <code>VoxelManip:calc_lighting()</code> or <code>VoxelManip:set_lighting()</code>.
+* <code>VoxelManip:update_map()</code> does not need to be called after <code>write_to_map()</code>.  The map update is performed
+  automatically after all on_generated callbacks have been run for that generated block.</p>
+<h5 id="other-api-functions-operating-on-a-voxelmanip">Other API functions operating on a VoxelManip</h5>
+<p>If any VoxelManip contents were set to a liquid node, <code>VoxelManip:update_liquids()</code> must be called
+for these liquid nodes to begin flowing.  It is recommended to call this function only after having
+written all buffered data back to the VoxelManip object, save for special situations where the modder
+desires to only have certain liquid nodes begin flowing.</p>
+<p>The functions <code>minetest.generate_ores()</code> and <code>minetest.generate_decorations()</code> will generate all
+registered decorations and ores throughout the full area inside of the specified VoxelManip object.</p>
+<p><code>minetest.place_schematic_on_vmanip()</code> is otherwise identical to <code>minetest.place_schematic()</code>,
+except instead of placing the specified schematic directly on the map at the specified position, it
+will place the schematic inside of the VoxelManip.</p>
+<h5 id="notes">Notes</h5>
 <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>
+<li>Attempting to read data from a VoxelManip object before map is read will result in a zero-length
+  array table for <code>VoxelManip:get_data()</code>, and an "ignore" node at any position for
+  <code>VoxelManip:get_node_at()</code>.</li>
+<li>If either a region of map has not yet been generated or is out-of-bounds of the map, that region is
+  filled with "ignore" nodes.</li>
+<li>Other mods, or the core itself, could possibly modify the area of map currently loaded into a VoxelManip
+  object.  With the exception of Mapgen VoxelManips (see above section), the internal buffers are not
+  updated.  For this reason, it is strongly encouraged to complete the usage of a particular VoxelManip
+  object in the same callback it had been created.</li>
+<li>If a VoxelManip object will be used often, such as in an <code>on_generated()</code> callback, consider passing
+  a file-scoped table as the optional parameter to <code>VoxelManip:get_data()</code>, which serves as a static
+  buffer the function can use to write map data to instead of returning a new table each call.  This
+  greatly enhances performance by avoiding unnecessary memory allocations.</li>
+</ul>
+<h4 id="methods_11">Methods</h4>
+<ul>
+<li><code>read_from_map(p1, p2)</code>:  Loads a chunk of map into the VoxelManip object containing
+  the region formed by <code>p1</code> and <code>p2</code>.<ul>
 <li>returns actual emerged <code>pmin</code>, actual emerged <code>pmax</code></li>
 </ul>
 </li>
 <li><code>write_to_map()</code>: Writes the data loaded from the <code>VoxelManip</code> back to the map.<ul>
-<li><strong>important</strong>: data must be set using <code>VoxelManip:set_data</code> before calling this</li>
+<li><strong>important</strong>: data must be set using <code>VoxelManip:set_data()</code> before calling this</li>
 </ul>
 </li>
 <li><code>get_node_at(pos)</code>: Returns a <code>MapNode</code> table of the node currently loaded in
   the <code>VoxelManip</code> at that position</li>
-<li><code>set_node_at(pos, node)</code>: Sets a specific <code>MapNode</code> in the <code>VoxelManip</code> at
-  that position</li>
-<li><code>get_data(buffer)</code>: Gets the data read into the <code>VoxelManip</code> object<ul>
+<li><code>set_node_at(pos, node)</code>: Sets a specific <code>MapNode</code> in the <code>VoxelManip</code> at that position</li>
+<li><code>get_data([buffer])</code>: Retrieves the node content data loaded into the <code>VoxelManip</code> object<ul>
 <li>returns raw node data in the form of an array of node content IDs</li>
 <li>if the param <code>buffer</code> is present, this table will be used to store the result instead</li>
 </ul>
@@ -3494,7 +3673,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_11">Methods</h4>
+<h4 id="methods_12">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>
@@ -3518,7 +3697,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_12">Methods</h4>
+<h4 id="methods_13">Methods</h4>
 <ul>
 <li><code>get(key)</code>: returns a value</li>
 <li><code>get_bool(key)</code>: returns a boolean</li>
@@ -3875,6 +4054,7 @@ minetest.spawn_tree(pos,apple_tree)
         dig = &lt;SimpleSoundSpec&gt;, -- "__group" = group-based sound (default)
         dug = &lt;SimpleSoundSpec&gt;,
         place = &lt;SimpleSoundSpec&gt;,
+        place_failed = &lt;SimpleSoundSpec&gt;,
     },
     drop = "",  -- Name of dropped node when dug. Default is the node itself.
     -- Alternatively:
diff --git a/update_lua_api.py b/update_lua_api.py
index 80f3c25..5d2a5b7 100644
--- a/update_lua_api.py
+++ b/update_lua_api.py
@@ -8,6 +8,10 @@ print("Downloading lua_api.txt...")
 
 url = "https://raw.githubusercontent.com/minetest/minetest/master/doc/lua_api.txt"
 text = urllib2.urlopen(url).read()
+
+
+print("Pre-processing...")
+
 header = """Minetest Lua Modding API Reference 0.4.13
 ========================================="""
 text = text.replace(header, "")
@@ -19,13 +23,15 @@ text = text.replace(header, "")
 #
 print("Generating HTML...")
 md = markdown.Markdown(extensions=['markdown.extensions.toc'])
+html = md.convert(text)
 
+print("Post-processing...")
 links = """<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>"""
 
-html = md.convert(text).replace("{{", "{ {")
+html = html.replace("{{", "{ {")
 html = html.replace(links, "")
 links += "This page was last updated "
 links += datetime.date.today().strftime("%d/%B/%Y")
@@ -45,5 +51,3 @@ file.write(html)
 file.close()
 
 print("Done")
-
-