Lua_api.txt: Document blockpos, coordinate conversion, map terminology (#8376)

Also fix and improve LVM 'calc_lighting()' warning.
This commit is contained in:
Paramat 2019-03-16 05:04:11 +00:00 committed by GitHub
parent ee57b63008
commit eadcbe474a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -1171,6 +1171,64 @@ A box of a regular node would look like:
Map terminology and coordinates
===============================
Nodes, mapblocks, mapchunks
---------------------------
A 'node' is the fundamental cubic unit of a world and appears to a player as
roughly 1x1x1 meters in size.
A 'mapblock' (often abbreviated to 'block') is 16x16x16 nodes and is the
fundamental region of a world that is stored in the world database, sent to
clients and handled by many parts of the engine.
'mapblock' is preferred terminology to 'block' to help avoid confusion with
'node', however 'block' often appears in the API.
A 'mapchunk' (sometimes abbreviated to 'chunk') is usually 5x5x5 mapblocks
(80x80x80 nodes) and is the volume of world generated in one operation by
the map generator.
The size in mapblocks has been chosen to optimise map generation.
Coordinates
-----------
### Orientation of axes
For node and mapblock coordinates, +X is East, +Y is up, +Z is North.
### Node coordinates
Almost all positions used in the API use node coordinates.
### Mapblock coordinates
Occasionally the API uses 'blockpos' which refers to mapblock coordinates that
specify a particular mapblock.
For example blockpos (0,0,0) specifies the mapblock that extends from
node position (0,0,0) to node position (15,15,15).
#### Converting node position to the containing blockpos
To calculate the blockpos of the mapblock that contains the node at 'nodepos',
for each axis:
* blockpos = math.floor(nodepos / 16)
#### Converting blockpos to min/max node positions
To calculate the min/max node positions contained in the mapblock at 'blockpos',
for each axis:
* Minimum:
nodepos = blockpos * 16
* Maximum:
nodepos = blockpos * 16 + 15
HUD HUD
=== ===
@ -3193,10 +3251,8 @@ Methods
* To be used only by a `VoxelManip` object from * To be used only by a `VoxelManip` object from
`minetest.get_mapgen_object`. `minetest.get_mapgen_object`.
* (`p1`, `p2`) is the area in which lighting is set, defaults to the whole * (`p1`, `p2`) is the area in which lighting is set, defaults to the whole
area if left out or nil. area if left out or nil. For almost all uses these should be left out
* Setting `p1`, `p2` to `emin`, `emax` of the mapgen object voxelmanip (the or nil to use the default.
entire volume of the voxelmanip: the mapchunk plus a 1 mapblock thick
shell around it) will cause an error.
* `propagate_shadow` is an optional boolean deciding whether shadows in a * `propagate_shadow` is an optional boolean deciding whether shadows in a
generated mapchunk above are propagated down into the mapchunk, defaults generated mapchunk above are propagated down into the mapchunk, defaults
to `true` if left out. to `true` if left out.