Update lua_api.html

2015-11-21 15:26:52 +00:00 · 2015-11-21 15:26:52 +00:00 · 8e08ccf525
commit 8e08ccf525
parent f18854d8c6
3 changed files with 212 additions and 26 deletions
--- a/.gitignore
+++ b/.gitignore
@ -1,2 +1,4 @@
 _site
 .directory
 .jekyll-metadata
 *~*
--- 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><code>minetest.emerge_area(pos1, pos2, [callback], [param])</code><ul>
-<li>queues all mapblocks in the area from pos1 to pos2, inclusive, for emerge</li>
+<li>Queue all blocks in the area from <code>pos1</code> to <code>pos2</code>, inclusive, to be asynchronously</li>
-<li>i.e. asynchronously loads blocks from disk, or if inexistent, generates them</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>
+<h4 id="about-voxelmanip">About VoxelManip</h4>
-<p>It can be created via <code>VoxelManip()</code> or <code>minetest.get_voxel_manip()</code>.
+<p>VoxelManip is a scripting interface to the internal 'Map Voxel Manipulator' facility.  The purpose of
-The map will be pre-loaded if two positions are passed to either.</p>
+this object is for fast, low-level, bulk access to reading and writing Map content.  As such, setting
-<h4 id="methods_10">Methods</h4>
+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
+<li>Attempting to read data from a VoxelManip object before map is read will result in a zero-length
-  region formed by <code>p1</code> and <code>p2</code>.<ul>
+  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
+<li><code>set_node_at(pos, node)</code>: Sets a specific <code>MapNode</code> in the <code>VoxelManip</code> at that position</li>
-  that position</li>
+<li><code>get_data([buffer])</code>: Retrieves the node content data loaded into the <code>VoxelManip</code> object<ul>
 <li><code>get_data(buffer)</code>: Gets the data read 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:
--- 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")