Minor additions to the VoxelManip docs

This commit is contained in:
Gregor Parzefall 2023-07-28 00:40:01 +02:00 committed by GitHub
parent ba6de431a2
commit cc8280426f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -4636,10 +4636,12 @@ differences:
* The Mapgen VoxelManip object is retrieved using: * The Mapgen VoxelManip object is retrieved using:
`minetest.get_mapgen_object("voxelmanip")` `minetest.get_mapgen_object("voxelmanip")`
* This VoxelManip object already has the region of map just generated loaded * This VoxelManip object already has the region of map just generated loaded
into it; it's not necessary to call `VoxelManip:read_from_map()`. 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` 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. parameters of `on_generated()`. Refer to `minetest.get_mapgen_object` docs.
* The `on_generated()` callbacks of some mods may place individual nodes in the * The `on_generated()` callbacks of some mods may place individual nodes in the
generated area using non-VoxelManip map modification methods. Because the generated area using non-VoxelManip map modification methods. Because the
same Mapgen VoxelManip object is passed through each `on_generated()` 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()` `minetest.add_node()`, `minetest.set_node()` or `minetest.swap_node()`
will also update the Mapgen VoxelManip object's internal state active on the will also update the Mapgen VoxelManip object's internal state active on the
current thread. current thread.
* After modifying the Mapgen VoxelManip object's internal buffer, it may be * After modifying the Mapgen VoxelManip object's internal buffer, it may be
necessary to update lighting information using either: necessary to update lighting information using either:
`VoxelManip:calc_lighting()` or `VoxelManip:set_lighting()`. `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 * 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 result in a zero-length array table for `VoxelManip:get_data()`, and an
"ignore" node at any position for `VoxelManip:get_node_at()`. "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. * If you attempt to use a VoxelManip to read a region of the map that has
* Other mods, or the core itself, could possibly modify the area of map 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 currently loaded into a VoxelManip object. With the exception of Mapgen
VoxelManips (see above section), the internal buffers are not updated. For VoxelManips (see above section), the internal buffers are not updated. For
this reason, it is strongly encouraged to complete the usage of a particular this reason, it is strongly encouraged to complete the usage of a particular
VoxelManip object in the same callback it had been created. VoxelManip object in the same callback it had been created.
* If a VoxelManip object will be used often, such as in an `on_generated()` * 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 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 `VoxelManip:get_data()`, which serves as a static buffer the function can use