Map item format

Minecraft Beta 1.6 added craftable map items. Unlike books, 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. This is limited to the size of a short (32,768). When Notch was adding them the first time he did not use the NBT format.

When used in The Nether or The End, 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 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 = map is a static image with no player pin.
 * : Height of map. Default (and only possible value) 128
 * : Width of map. Default (and only possible value) 128
 * : Center of map according to real world by X
 * : Center of map according to real world by Z
 * : Width * Height array of color values (16384 entries for a default 128x128 map). Color can be accessed via the following method: colorID = Colors[widthOffset + heightOffset * width], where (widthOffset==0, heightOffset==0) is left upper point.

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 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 to the nearest whole. As of weekly snapshot 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. Here is the color table for 1.9. The full 1.8.1 table is at the bottom