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 will be 1:1). Default 3, minimum 0 and maximum 4.
 * : 0 = The Overworld, -1 = The Nether, 1 = The End, any other value = a static image with no player pin.
 * : 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 will make 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.

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.

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 13w42b, 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 128x128 and will read each block as a specific color. By placing blocks in a specific arrangement, it is possible to create pixel art images.

Methods for creating map pixel art is either flat, or staircase. With the flat method, you have 51 colors (version 1.12) to work with and is a lot easier to create an image. With the staircase, you have 153 colors (version 1.12) and is a lot more difficult to work with. For the staircase method, blocks are placed at different elevations to obtain the extra 2/3 of the colors. By placing a block higher or lower than the block north of it, or topside of the map, you can create a brighter or darker shade than the normal flat color.

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 colors groups below can be used. The 4th shade cannot be obtained in traditional gameplay, but with the use of an external tool.

1.8.1 Color Table
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.