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. This size is available as the constant core.MAP_BLOCKSIZE (=16).

'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.

Mapblock status

A mapblock being "loaded" means that is in memory. These are the mapblocks that API functions like core.get_node or core.set_node can operate on. To reach this state, the mapblock must first go through the process of being "emerged". This means that it is loaded from disk, and/or, if it isn't yet generated, generated by the map generator.

Mapblocks are loaded in a broad area around each player. They become "unloaded" again if no player is close enough. The engine commonly represents the contents of unloaded mapblocks as "ignore" nodes.

A mapblock being "active" means that it is not only in memory, but also affected by world simulation:

  • Entities are active
    • They are in memory as ServerActiveObject, exposed to Lua as ObjectRef
    • They exist in Lua as luaentity tables
  • ABMs are executed
  • Node timers are executed

Also, when a mapblock is "activated", LBMs are executed. Mapblocks are active in a smaller area around each player, and are "deactivated" again if no player is close enough.

Related API functions:

  • core.compare_block_status
  • core.forceload_block
  • core.load_area
  • core.emerge_area

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 / core.MAP_BLOCKSIZE)

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 * core.MAP_BLOCKSIZE
  • Maximum: nodepos = (blockpos + 1) * core.MAP_BLOCKSIZE - 1