Skip to content
Browse files

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


Also fix and improve LVM 'calc_lighting()' warning.
  • Loading branch information
paramat committed Mar 16, 2019
1 parent ee57b63 commit eadcbe474a04174b78d35ab802e974bc2bf3fac6
Showing with 60 additions and 4 deletions.
  1. +60 −4 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.


### 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


@@ -3193,10 +3251,8 @@ Methods
* To be used only by a `VoxelManip` object from
* (`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.

1 comment on commit eadcbe4


This comment has been minimized.

Copy link

@tacotexmex tacotexmex commented on eadcbe4 Mar 16, 2019

Very nice additions!

Please sign in to comment.