Map item format

Maps do not store their information in the item; instead, their data value corresponds to the map number (ID) of a saved file. Their information is placed in the "data" directory within the world's save directory. Each map has its own file associated with its ID, and there is one file that keeps track of the highest (most recently created) map ID.

When used in the Nether, maps render as a kind of static, making them unreadable.

Data folder structure
The file idcounts.dat contains the latest ID for current map. Each map's file name uses the format map_<#>.dat, where <#> is the map's unique number.

map_<#>.dat format
map_<#>.dat files are GZip'd NBT files.

NBT structure

 * The root tag.
 * : The map data.
 * : How zoomed in the map is (it is in 2scale wide blocks square per pixel, even for 0, where the map is 1:1). Default 3, minimum 0 and maximum 4.
 * : For <1.16 (byte): 0 = The Overworld, -1 = The Nether, 1 = The End, any other value = a static image with no player pin. In >=1.16 this is the namespaced ID of a dimension instead.
 * : 1 (default) indicates that a positional arrow should be shown when the map is near its center coords. 0 indicates that the position arrow should never be shown.
 * : 1 allows the player position indicator to show as a smaller dot on the map's edge when the player is farther than 320 * (scale+1) blocks from the map's center. 0 makes the dot instead disappear when the player is farther than this distance. Defaults to 0 for maps created from an empty map and 1 for Explorer Maps.
 * : 1 if the map has been locked in a cartography table.
 * : Center of map according to real world by X.
 * : Center of map according to real world by Z.
 * : List of banner markers added to this map. May be empty.
 * A banner marker.
 * : The color of the banner. Allowed values:,  ,  ,  ,  ,  ,  ,  ,  ,  ,  ,  ,  ,  ,  ,.
 * : The custom name of the banner, in JSON text. May not exist.
 * : The block position of the banner in the world.
 * : The x-position of the banner.
 * : The y-position of the banner.
 * : The z-position of the banner.
 * : List map markers added to this map. May be empty.
 * A marker.
 * : Arbitrary unique value for the marker.
 * : The rotation of the marker, ranging from 0 to 360.
 * : The block position of the marker in the world.
 * : The x-position of the marker.
 * : The y-position of the marker.
 * : The z-position of the marker.
 * : Width * Height array of color values (16384 entries for a default 128&times;128 map). Color can be accessed via the following method: colorID = Colors[widthOffset + heightOffset * width], where (widthOffset==0, heightOffset==0) is left upper point.
 * : The version the map was created. If not present, defaults to 1343 (1.12.2)

When this structure is loaded, Colors array is transformed to standard dimension (if it's necessary) and then structure is saved with standard height and width.

idcounts.dat format
This file keeps track of the latest map added. It is stored as a raw (uncompressed) NBT file.

NBT structure

 * The root tag.
 * : Latest map ID.
 * : Latest map ID.

Color table
Maps use a color table to store the colors efficiently by ID.

Base colors
Blocks are colored according to their material. Each material has a base color which is multiplied by 135, 180, 220 or 255, and then divided by 255 to make the map color. Each base color below is associated with four map colors - to get the first map color ID for a base color, multiply the base color ID by 4. (Note: ID 0 has 4 gradients of itself despite them all being transparent)

Map colors
Each base color above has 4 associated map colors below. The conversion works by multiplying each of the red, green, and blue values by a value and then dividing by 255, finally rounding down to a whole number. As of 1.8.1-pre1, the fourth base color variant is now multiplied by 135, providing a darker set of colors rather than just a clone of the second base color variant.



Map Pixel Art


People have used the map to create pixel art. The default map has an image size of 128&times;128 and reads each block as a specific color. By placing blocks in a specific arrangement, it is possible to create pixel art images. Constructing the image will cover an square area 8 chunks on a side, and require 16,384 blocks (256 stacks worth) not counting any support blocks.

Two methods exist for creating map pixel art: flat and staircase. The flat method involves laying the pixel image across a flat surface, effectively creating a floor. The flat method is the easier of the two methods, but offers a smaller palette of only 58 colors. The staircase method offers 174 colors, but is much more complicated to use. In the staircase method, blocks are placed at different elevations to obtain specific color variations. A block's color is darker if placed at a lower elevation than the block north of it, or brighter if placed at a higher elevation than the block north of it. (This is a case of the mapping convention of top lighting.)

With the flat method, the 2nd shade of each color group on the lists below can be used. For the staircase method, the first 3 shades of the color groups below can be used. The 4th shade can only be obtained with the use of an external tool.

Full color tables

 * Note: The description may not list every possible block. Example: In 1.8.1, any block that uses colored wool can also use colored carpet or colored pane glass.

Code examples
Listed below are some libraries used for modifying and exporting map data.