From cc8280426f804508c3273fc1eee1beaa3f234fa4 Mon Sep 17 00:00:00 2001
From: Gregor Parzefall <82708541+grorp@users.noreply.github.com>
Date: Fri, 28 Jul 2023 00:40:01 +0200
Subject: [PATCH] Minor additions to the VoxelManip docs
---
doc/lua_api.md | 21 ++++++++++++++++++---
1 file changed, 18 insertions(+), 3 deletions(-)
diff --git a/doc/lua_api.md b/doc/lua_api.md
index 0ce144f84..557f73e0e 100644
--- a/doc/lua_api.md
+++ b/doc/lua_api.md
@@ -4636,10 +4636,12 @@ 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()`.
Note that the region of map it has loaded is NOT THE SAME as the `minp`, `maxp`
parameters of `on_generated()`. Refer to `minetest.get_mapgen_object` docs.
+
* 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()`
@@ -4648,6 +4650,7 @@ differences:
`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()`.
@@ -4674,13 +4677,25 @@ inside the VoxelManip.
* 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
+
+* If you attempt to use a VoxelManip to read a region of the map that has
+ already been generated, but is not currently loaded, that region will be
+ loaded from disk. This means that reading a region of the map with a
+ VoxelManip has a similar effect as calling `minetest.load_area` on that
+ region.
+
+* If a region of the map has either not yet been generated or is outside the
+ map boundaries, it is filled with "ignore" nodes. Writing to regions of the
+ map that are not yet generated may result in unexpected behavior. You
+ can use `minetest.emerge_area` to make sure that the area you want to
+ read/write is already generated.
+
+* Other mods, or the core itself, could possibly modify the area of the 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