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