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, 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.
  •  data: The map data.
    •  scale: How zoomed in the map is (it is in 2^scale blocks square per pixel, even for 0, where the map will be 1:1). Default 3, minimum 0 and maximum 4.
    •  dimension: 0 = The Overworld, -1 = The Nether, 1 = The End, any other value = map is a static image with no player pin.
    •  height: Height of map. Default (and only possible value) 128
    •  width: Width of map. Default (and only possible value) 128
    •  trackingPosition: 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.
    •  unlimitedTracking: 1 (default) 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.
    •  xCenter: Center of map according to real world by X
    •  zCenter: Center of map according to real world by Z
    •  colors: 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.
  •  map: 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 item format/header2

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.

Map Color ID	Multiply R,G,B By
Base Color ID*4 + 0	180
Base Color ID*4 + 1	220
Base Color ID*4 + 2	255 (same color)
Base Color ID*4 + 3	135

Map Pixel Art

Redstonehelper uses the staircase method in survival

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 36 colors to work with and is a lot easier to create an image. With the staircase, you have 108 colors 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 then the normal flat color.

With the flat method, the colors used is the 2nd shade of each color group can be used on the lists below. For the staircase method, the first 3 shades of the colors groups below. The 4th shade can not 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.

ID	Color	RGB	Blocks
0		Transparent
1		Transparent
2		Transparent
3		Transparent
4		89,125,39
5		109,153,48
6		127,178,56
7		67,94,29
8		174,164,115
9		213,201,140
10		247,233,163
11		130,123,86
12		138,138,138
13		169,169,169
14		197,197,197
15		104,104,104
16		180,0,0
17		220,0,0
18		255,0,0
19		135,0,0
20		112,112,180
21		138,138,220
22		160,160,255
23		84,84,135
24		117,117,117
25		144,144,144
26		167,167,167
27		88,88,88
28		0,87,0
29		0,106,0
30		0,124,0
31		0,65,0
32		180,180,180
33		220,220,220
34		255,255,255
35		135,135,135
36		115,118,129
37		141,144,158
38		164,168,184
39		86,88,97
40		129,74,33
41		157,91,40
42		183,106,47
43		96,56,24
44		79,79,79
45		96,96,96
46		112,112,112
47		59,59,59
48		101,84,51
49		123,103,62
50		143,119,72
51		76,63,38
52		45,45,180
53		55,55,220
54		64,64,255
55		33,33,135
56		180,177,172
57		220,217,211
58		255,252,245
59		135,133,129
60		152,89,36
61		186,109,44
62		216,127,51
63		114,67,27
64		125,53,152
65		153,65,186
66		178,76,216
67		94,40,114
68		72,108,152
69		88,132,186
70		102,153,216
71		54,81,114
72		161,161,36
73		197,197,44
74		229,229,51
75		121,121,27
76		89,144,17
77		109,176,21
78		127,204,25
79		67,108,13
80		170,89,116
81		208,109,142
82		242,127,165
83		128,67,87
84		53,53,53
85		65,65,65
86		76,76,76
87		40,40,40
88		108,108,108
89		132,132,132
90		153,153,153
91		81,81,81
92		53,89,108
93		65,109,132
94		76,127,153
95		40,67,81
96		89,44,125
97		109,54,153
98		127,63,178
99		67,33,94
100		36,53,125
101		44,65,153
102		51,76,178
103		27,40,94
104		72,53,36
105		88,65,44
106		102,76,51
107		54,40,27
108		72,89,36
109		88,109,44
110		102,127,51
111		54,67,27
112		108,36,36
113		132,44,44
114		153,51,51
115		81,27,27
116		17,17,17
117		21,21,21
118		25,25,25
119		13,13,13
120		176,168,54
121		215,205,66
122		250,238,77
123		132,126,40
124		64,154,150
125		79,188,183
126		92,219,213
127		48,115,112
128		52,90,180
129		63,110,220
130		74,128,255
131		39,67,135
132		0,153,40
133		0,187,50
134		0,217,58
135		0,114,30
136		90,59,34
137		110,73,41
138		127,85,48
139		67,44,25
140		79,1,0
141		96,1,0
142		112,2,0
143		59,1,0

1.7.2 Color Table

ID	Color	RGB	Blocks
0		Transparent
1		Transparent
2		Transparent
3		Transparent
4		89,125,39
5		109,153,48
6		127,178,56
7		67,94,29
8		174,164,115
9		213,201,140
10		247,233,163
11		130,123,86
12		180,0,0
13		220,0,0
14		255,0,0
15		135,0,0
16		112,112,180
17		138,138,220
18		160,160,255
19		84,84,135
20		117,117,117
21		144,144,144
22		167,167,167
23		88,88,88
24		0,87,0
25		0,106,0
26		0,124,0
27		0,65,0
28		180,180,180
29		220,220,220
30		255,255,255
31		135,135,135
32		115,118,129
33		141,144,158
34		164,168,184
35		86,88,97
36		129,74,33
37		157,91,40
38		183,106,47
39		96,56,24
40		79,79,79
41		96,96,96
42		112,112,112
43		59,59,59
44		45,45,180
45		55,55,220
46		64,64,255
47		33,33,135
48		73,58,35
49		89,71,43
50		104,83,50
51		55,43,26
52		180,177,172
53		220,217,211
54		255,252,245
55		135,133,129
56		152,89,36
57		186,109,44
58		216,127,51
59		114,67,27
60		125,53,152
61		153,65,186
62		178,76,216
63		94,40,114
64		72,108,152
65		88,132,186
66		102,153,216
67		54,81,114
68		161,161,36
69		197,197,44
70		229,229,51
71		121,121,27
72		89,144,17
73		109,176,21
74		127,204,25
75		66,108,13
76		170,89,116
77		208,109,142
78		242,127,165
79		128,67,87
80		53,53,53
81		65,65,65
82		76,76,76
83		40,40,40
84		108,108,108
85		132,132,132
86		153,153,153
87		81,81,81
88		53,89,108
89		65,109,132
90		76,127,153
91		40,67,81
92		89,44,125
93		109,54,153
94		127,63,178
95		67,33,94
96		36,53,125
97		44,65,153
98		51,76,178
99		27,40,94
100		72,53,36
101		88,65,44
102		102,76,51
103		54,40,27
104		72,89,36
105		88,109,44
106		102,127,51
107		54,67,27
108		108,36,36
109		132,44,44
110		153,51,51
111		81,27,27
112		17,17,17
113		21,21,21
114		25,25,25
115		13,13,13
116		176,168,54
117		215,205,66
118		250,238,77
119		132,126,40
120		64,154,150
121		79,188,183
122		92,219,213
123		48,115,112
124		52,90,180
125		63,110,220
126		74,128,255
127		39,67,135
128		0,153,40
129		0,187,50
130		0,217,58
131		0,114,30
132		14,14,21
133		18,17,26
134		21,20,31
135		11,10,16
136		79,1,0
137		96,1,0
138		112,2,0
139		59,1,0

Original Color Table

ID	Color	RGB	Blocks
0		Transparent
1		Transparent
2		Transparent
3		89,125,39
4		109,153,48
5		127,178,56
6		174,164,115
7		213,201,140
8		247,233,163
9		180,0,0
10		220,0,0
11		255,0,0
12		112,112,180
13		138,138,220
14		160,160,255
15		117,117,117
16		144,144,144
17		167,167,167
18		0,87,0
19		0,106,0
20		0,124,0
21		180,180,180
22		220,220,220
23		255,255,255
24		115,118,129
25		141,144,158
26		164,168,184
27		129,74,33
28		157,91,40
29		183,106,47
30		79,79,79
31		96,96,96
32		112,112,112
33		45,45,180
34		55,55,220
35		64,64,255
36		73,58,35
37		89,71,43
38		104,83,50

Code examples

Library name	Language	Link to Map-related code
MCModify	Java	Map.java
minecraftmap	Python	__init__.py
mcmapimg	Python	mcmapimg.py