From eadcbe474a04174b78d35ab802e974bc2bf3fac6 Mon Sep 17 00:00:00 2001 From: Paramat Date: Sat, 16 Mar 2019 05:04:11 +0000 Subject: Lua_api.txt: Document blockpos, coordinate conversion, map terminology (#8376) Also fix and improve LVM 'calc_lighting()' warning. --- doc/lua_api.txt | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 60 insertions(+), 4 deletions(-) diff --git a/doc/lua_api.txt b/doc/lua_api.txt index a45466b5f..39e0a848d 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -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 === @@ -3193,10 +3251,8 @@ Methods * To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`. * (`p1`, `p2`) is the area in which lighting is set, defaults to the whole - area if left out or nil. - * Setting `p1`, `p2` to `emin`, `emax` of the mapgen object voxelmanip (the - entire volume of the voxelmanip: the mapchunk plus a 1 mapblock thick - shell around it) will cause an error. + area if left out or nil. For almost all uses these should be left out + or nil to use the default. * `propagate_shadow` is an optional boolean deciding whether shadows in a generated mapchunk above are propagated down into the mapchunk, defaults to `true` if left out. -- cgit v1.2.3