Improve LuaVoxelManip documentation

1 files changed, 158 insertions, 9 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 5008a5293..63e4971e5 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -2812,22 +2812,171 @@ nil, this table will be used to store the result instead of creating a new table
   `noisevals = noise:getMapSlice({x=24, z=1}, {x=1, z=1})`
 
 ### `VoxelManip`
-An interface to the `MapVoxelManipulator` for Lua.
 
-It can be created via `VoxelManip()` or `minetest.get_voxel_manip()`.
-The map will be pre-loaded if two positions are passed to either.
+#### About VoxelManip
+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.
+
+It is important to note that VoxelManip is designed for speed, and *not* 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.
+
+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.
+
+#### Using VoxelManip
+A VoxelManip object can be created any time using either:
+`VoxelManip([p1, p2])`, or `minetest.get_voxel_manip([p1, p2])`.
+
+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 `VoxelManip:read_from_map()`.
+
+Note that `VoxelManip:read_from_map()` 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 `VoxelManip:get_emerged_area()`.
+
+Now that the VoxelManip object is populated with map data, your mod can fetch a copy of this data
+using either of two methods.  `VoxelManip:get_node_at()`, which retrieves an individual node in a
+MapNode formatted table at the position requested is the simplest method to use, but also the slowest.
+
+Nodes in a VoxelManip object may also be read in bulk to a flat array table using:
+`VoxelManip:get_data()` for node content (in Content ID form, see section 'Content IDs'),
+`VoxelManip:get_light_data()` for node light levels, and
+`VoxelManip:get_param2_data()` for the node type-dependent "param2" values.
+
+See section 'Flat array format' for more details.
+
+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 *not* 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.
+
+Once the bulk data has been edited to your liking, the internal VoxelManip state can be set using:
+`VoxelManip:set_data()` for node content (in Content ID form, see section 'Content IDs'),
+`VoxelManip:set_light_data()` for node light levels, and
+`VoxelManip:set_param2_data()` for the node type-dependent "param2" values.
+
+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 *not required* to be a table retrieved from get_data().
+
+Once the internal VoxelManip state has been modified to your liking, the changes can be committed back
+to the map by calling `VoxelManip:write_to_map()`.
+
+Finally, a call to `VoxelManip:update_map()` is required to re-calculate lighting and set the blocks
+as being modified so that connected clients are sent the updated parts of map.
+
+
+##### Flat array format
+Let
+    `Nx = p2.X - p1.X + 1`,
+    `Ny = p2.Y - p1.Y + 1`, and
+    `Nz = p2.Z - p1.Z + 1`.
+
+Then, for a loaded region of p1..p2, this array ranges from `1` up to and including the value of
+the expression `Nx * Ny * Nz`.
+
+Positions offset from p1 are present in the array with the format of:
+```
+[
+    (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)
+]
+```
+
+and the array index for a position p contained completely in p1..p2 is:
+
+`(p.Z - p1.Z) * Ny * Nx + (p.Y - p1.Y) * Nx + (p.X - p1.X) + 1`
+
+Note that this is the same "flat 3D array" format as `PerlinNoiseMap:get3dMap_flat()`.
+VoxelArea objects (see section 'VoxelArea') can be used to simplify calculation of the index
+for a single point in a flat VoxelManip array.
+
+##### Content IDs
+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 `VoxelManip:get_data()` and `VoxelManip:set_data()`.  You can use
+`minetest.get_content_id()` to look up the Content ID for the specified node name, and
+`minetest.get_name_from_content_id()` 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.
+
+The following builtin node types have their Content IDs defined as constants:
+```
+core.CONTENT_UNKNOWN (ID for "unknown" nodes)
+core.CONTENT_AIR     (ID for "air" nodes)
+core.CONTENT_IGNORE  (ID for "ignore" nodes)
+```
+
+##### Mapgen VoxelManip objects
+Inside of `on_generated()` 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:
+* The Mapgen VoxelManip object is retrieved using: `minetest.get_mapgen_object("voxelmanip")`
+* This VoxelManip object already has the region of map just generated loaded into it; it's not necessary
+  to call `VoxelManip:read_from_map()` before using a Mapgen VoxelManip.
+* The `on_generated()` 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 `on_generated()` 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:
+  `minetest.add_node()`, `minetest.set_node()`, or `minetest.swap_node()`
+  will also update the Mapgen VoxelManip object's internal state active on the current thread.
+* After modifying the Mapgen VoxelManip object's internal buffer, it may be necessary to update lighting
+  information using either: `VoxelManip:calc_lighting()` or `VoxelManip:set_lighting()`.
+* `VoxelManip:update_map()` does not need to be called after `write_to_map()`.  The map update is performed
+  automatically after all on_generated callbacks have been run for that generated block.
+
+##### Other API functions operating on a VoxelManip
+If any VoxelManip contents were set to a liquid node, `VoxelManip:update_liquids()` 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.
+
+The functions `minetest.generate_ores()` and `minetest.generate_decorations()` will generate all
+registered decorations and ores throughout the full area inside of the specified VoxelManip object.
+
+`minetest.place_schematic_on_vmanip()` is otherwise identical to `minetest.place_schematic()`,
+except instead of placing the specified schematic directly on the map at the specified position, it
+will place the schematic inside of the VoxelManip.
+
+##### Notes
+* Attempting to read data from a VoxelManip object before map is read will result in a zero-length
+  array table for `VoxelManip:get_data()`, and an "ignore" node at any position for
+  `VoxelManip:get_node_at()`.
+* 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.
+* 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.
+* If a VoxelManip object will be used often, such as in an `on_generated()` callback, consider passing
+  a file-scoped table as the optional parameter to `VoxelManip:get_data()`, 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.
 
 #### Methods
-* `read_from_map(p1, p2)`:  Reads a chunk of map from the map containing the
-  region formed by `p1` and `p2`.
+* `read_from_map(p1, p2)`:  Loads a chunk of map into the VoxelManip object containing
+  the region formed by `p1` and `p2`.
     * returns actual emerged `pmin`, actual emerged `pmax`
 * `write_to_map()`: Writes the data loaded from the `VoxelManip` back to the map.
-    * **important**: data must be set using `VoxelManip:set_data` before calling this
+    * **important**: data must be set using `VoxelManip:set_data()` before calling this
 * `get_node_at(pos)`: Returns a `MapNode` table of the node currently loaded in
   the `VoxelManip` at that position
-* `set_node_at(pos, node)`: Sets a specific `MapNode` in the `VoxelManip` at
-  that position
-* `get_data(buffer)`: Gets the data read into the `VoxelManip` object
+* `set_node_at(pos, node)`: Sets a specific `MapNode` in the `VoxelManip` at that position
+* `get_data([buffer])`: Retrieves the node content data loaded into the `VoxelManip` object
     * returns raw node data in the form of an array of node content IDs
     * if the param `buffer` is present, this table will be used to store the result instead
 * `set_data(data)`: Sets the data contents of the `VoxelManip` object