Map item format

Maps do not store their information in the item; instead, they save a map number in the minecraft:map_id component that corresponds to the map number (ID) of a saved file. Their information is placed in the "data" directory within the world's save directory.

In Java Edition 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.

In Bedrock Edition each map can create 6 files, 1 associated with its original ID, 4 extra files that represent different scales of the map (which are stored as the parentMapIds), and another 1 extra file if the map was locked with a glass pane.

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

Data folder structure

In Java Edition, 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.

In Bedrock Edition, the map item files are contained in the mojang variant of the LevelDB file format. Each map's file name uses its own unique number, without using any prefix.

map_<#>.dat format (Java)

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

NBT structure

  • [NBT Compound / JSON Object] The root tag.
    • [NBT Compound / JSON Object] data: The map data.
      • [Byte] scale: 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.
      • [String] dimension: 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 resource location of a dimension instead. ​
      • [Byte] 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.
      • [Byte] unlimitedTracking: 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.
      • [Byte] locked: 1 if the map has been locked in a cartography table.
      • [Int] xCenter: Center of map according to real world by X.
      • [Int] zCenter: Center of map according to real world by Z.
      • [NBT List / JSON Array] banners: List of banner markers added to this map. May be empty.
        • [NBT Compound / JSON Object] A banner marker.
          • [String] Color: The color of the banner. Allowed values: white, orange, magenta, light_blue, yellow, lime, pink, gray, light_gray, cyan, purple, blue, brown, green, red, black.
          • [String] Name: The custom name of the banner, in JSON text. May not exist.
          • [NBT Compound / JSON Object] Pos: The block position of the banner in the world.
            • [Int] X: The x-position of the banner.
            • [Int] Y: The y-position of the banner.
            • [Int] Z: The z-position of the banner.
      • [NBT List / JSON Array] frames: List of map markers added to this map. May be empty.
        • [NBT Compound / JSON Object] A marker.
          • [Int] EntityId: Arbitrary unique value for the marker.
          • [Int] Rotation: The rotation of the marker, ranging from 0 to 360.
          • [NBT Compound / JSON Object] Pos: The block position of the marker in the world.
            • [Int] X: The x-position of the marker.
            • [Int] Y: The y-position of the marker.
            • [Int] Z: The z-position of the marker.
      • [Byte Array] colors: Width * Height array of color values (16384 entries for a default 128×128 map). Color can be accessed via the following method: colorID = Colors[widthOffset + heightOffset * width], where (widthOffset==0, heightOffset==0) is left upper point.
    • [Int] DataVersion: 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.

LevelDB format (Bedrock)

NBT structure

  • [NBT Compound / JSON Object]: The root tag.
    • [Long] mapId: The Unique ID of the map.
    • [Long] parentMapId: The Unique ID's of the parent maps.
    • [Byte] dimension: 0 = The Overworld, 1 = The Nether, 2 = The End, any other value = a static image with no player pin.
    • [Byte] fullExplored: 1 if the map is full explored.
    • [Byte] mapLocked: 1 if the map has been locked in a cartography table.
    • [Byte] scale: How zoomed in the map is, and must be a number between 0 and 4 (inclusive) that represent the level. Default 0. If this is changed in an anvil or a cartography table, the Unique ID of the map changes.
    • [Byte] unlimitedTracking: Unknown. Default 0.
    • [Short] height: The height of the map. Is associated with the scale level.
    • [Short] width The width of the map. Is associated with the scale level.
    • [Int] xCenter: Center of the map according to real world by X.
    • [Int] zCenter: Center of the map according to real world by Z.
    • [NBT List / JSON Array] decorations: A list of optional icons to display on the map.
      • [NBT Compound / JSON Object]: An individual decoration.
        • [NBT Compound / JSON Object] data
          • [Int] rot: The rotation of the symbol, ranging from 0 to 15. South = 0, West = 4, North = 8, East = 12.
          • [Int] type: The ID of the map icon to display.
          • [Int] x: The horizontal column (x) where the decoration is located on the map (per pixel).
          • [Int] y: The vertical column (y) where the decoration is located on the map (per pixel).
        • [NBT Compound / JSON Object] key
          • [Int] blockX: The world x-position of the decoration.
          • [Int] blockY: The world y-position of the decoration.
          • [Int] blockZ: The world z-position of the decoration.
          • [Int] type: Unknown.
    • [Byte Array] colors: An array of bytes that represent color values (65536 entries for a default 128×128 map).

idcounts.dat format

The idcounts.dat file keeps track of the latest map added. It is stored as a Gzip'd NBT file.

NBT structure

  • [NBT Compound / JSON Object] The root tag.
    • [NBT Compound / JSON Object] data
      • [Int] map: Latest map ID.
    • [Int] DataVersion: Data version

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 that 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.)

ID Color RGB Blocks
0 NONE Transparent air, void air, cave air, barrier, cake (including cake with candles), powered rail, detector rail, torches, redstone wire, ladder, rail, lever, buttons, repeater, tripwire hook, tripwire, flower pot (including potted plants), head, comparator, activator rail, End rod, glass, glass pane, Nether portal, stained glass pane (all colors), structure void, iron bars, chain, light block, pink petals,‌ pointed dripstone,‌ redstone lamp
1 GRASS 127, 178, 56 grass block, slime block
2 SAND 247, 233, 163 sand, suspicious sand, birch (planks, log (vertical), stripped log, wood, stripped wood, sign, pressure plate, trapdoor, stairs, slab, fence gate, fence, door), sandstone (all variants, all slabs, all stairs, all walls), glowstone, End stone, End stone bricks (slab, stairs, wall), bone block, turtle egg, scaffolding, candle, ochre froglight, frogspawn
3 WOOL 199, 199, 199 cobweb, mushroom stem, bed (head), white candle
4 FIRE 255, 0, 0 lava, TNT, fire, redstone block
5 ICE 160, 160, 255 ice, frosted ice, packed ice, blue ice
6 METAL 167, 167, 167 block of iron, iron door, brewing stand, heavy weighted pressure plate, iron trapdoor, lantern, anvil (all damage levels), grindstone, lodestone,‌ heavy core, pale oak leaves, pale oak sapling, copper trapdoor‌ (including waxed and exposed/weathered variations)
7 PLANT 0, 124, 0 sapling, flowers, wheat, sugar cane, pumpkin stem, melon stem, lily pad, cocoa, carrots, potatoes, beetroots, sweet berry bush, grass,‌ tall grass, fern,‌ large fern, vines,‌ leaves‌ (except pale oak leaves, cherry leaves), cactus, bamboo, cave vines, spore blossom, (flowering) azalea, dripleaf (big and small), pink petals,‌ wildflowers, bush, torchflower seeds, pitcher pod, hanging roots
8 SNOW 255, 255, 255 snow, snow block, white (bed (foot), wool, stained glass, carpet, shulker box, glazed terracotta, concrete, concrete powder), powder snow, lodestone
9 CLAY 164, 168, 184 clay, heavy core
10 DIRT 151, 109, 77 dirt, coarse dirt, farmland, dirt path, granite (slab, stairs, wall), polished granite (slab, stairs), jungle (planks, log (vertical), stripped log, wood, stripped wood, sign, pressure plate, trapdoor, stairs, slab, fence gate, fence, door), jukebox, brown mushroom block, rooted dirt, hanging roots,‌ packed mud
11 STONE 112, 112, 112 stone (slab, stairs), andesite (slab, stairs, wall), polished andesite (slab, stairs), cobblestone (slab, stairs, wall), bedrock, gold ore, iron ore, coal ore, lapis lazuli ore, dispenser, mossy cobblestone (slab, stairs, wall), monster spawner, diamond ore, furnace, stone pressure plate, redstone ore, stone bricks (all variants, all slabs, all stairs, all walls), emerald ore, ender chest, dropper, smooth stone (slab), observer, smoker, blast furnace, stonecutter, sticky piston, piston, piston head, gravel, suspicious gravel, acacia log (side), cauldron (including cauldrons with water, lava, or powder snow), hopper, copper ore, crafter, vault, trial spawner, pale oak wood, pale oak log (side), infested block‌ (not including infested deepslate), heavy core
12 WATER 64, 64, 255 kelp, seagrass, water, bubble column, waterlogged leaves
13 WOOD 143, 119, 72 oak (planks, log (vertical), stripped log, wood, stripped wood, sign, door, pressure plate, fence, trapdoor, fence gate, slab, stairs), note block, bookshelf, chiseled bookshelf, chest, crafting table, trapped chest, daylight detector, loom, barrel, cartography table, fletching table, lectern, smithing table, composter, bamboo sapling, dead bush, petrified oak slab, beehive, banners (all colors, when not as markers)
14 QUARTZ 255, 252, 245 diorite (stairs, slab, wall), polished diorite (stairs, slab), birch log (side), quartz block (all variants, all slabs, all stairs), sea lantern, target, pale oak (planks, log (vertical), stripped log, stripped wood, sign, pressure plate, trapdoor, stairs, slab, fence gate, fence, door)
15 COLOR_ORANGE 216, 127, 51 acacia (planks, log (vertical), stripped log, stripped wood,‌ sign, trapdoor, slab, stairs, pressure plate, fence gate, fence, door), red sand, orange (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), pumpkin, carved pumpkin, jack o'lantern, terracotta, red sandstone (all variants, all stairs, all slabs, all walls), honey block, honeycomb block, block of copper (including all cut, waxed, stair, trapdoor,‌ and slab variants), lightning rod, block of raw copper, creaking heart (all orientations, active & inactive), open eyeblossom
16 COLOR_MAGENTA 178, 76, 216 magenta (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), purpur (all variants, slab, stairs)
17 COLOR_LIGHT_BLUE 102, 153, 216 light blue (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), soul fire
18 COLOR_YELLOW 229, 229, 51 yellow (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), bamboo (planks, stripped, sign, door, pressure plate, fence, trapdoor, fence gate, slab, stairs), bamboo mosaic (slab, stairs), sponge, wet sponge, hay bale, horn coral (coral block, coral,‌ coral fan‌), bee nest, short dry grass, tall dry grass
19 COLOR_LIGHT_GREEN 127, 204, 25 lime (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), melon
20 COLOR_PINK 242, 127, 165 pink (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), brain coral (coral block, coral,‌ coral fan‌), pearlescent froglight, cherry leaves, cherry sapling, cactus flower
21 COLOR_GRAY 76, 76, 76 gray (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), acacia wood, stripped wood,‌ dead coral (coral block, coral, coral fan), tinted glass, dried ghast
22 COLOR_LIGHT_GRAY 153, 153, 153 light gray (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), structure block, jigsaw block, pale moss carpet, pale moss block, test block
23 COLOR_CYAN 76, 127, 153 cyan (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), prismarine (slab, stairs, wall), warped (roots, fungus), twisting vines, Nether sprouts, sculk sensor,‌ warped (pressure plate,‌ sign,‌ slab,‌ trapdoor,‌ fence‌)
24 COLOR_PURPLE 127, 63, 178 shulker box, purple (wool, carpet, shulker box,‌ bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), mycelium, chorus plant, chorus flower, repeating command block, bubble coral (coral block, coral,‌ coral fan‌), amethyst block, budding amethyst, amethyst cluster, amethyst bud (all sizes)
25 COLOR_BLUE 51, 76, 178 blue (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), tube coral (coral block, coral,‌ coral fan‌)
26 COLOR_BROWN 102, 76, 51 brown (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), dark oak (planks, log, stripped log, wood, stripped wood, sign, pressure plate, trapdoor, stairs, slab, fence gate, fence, door), soul sand, command block, brown mushroom, soul soil, leaf litter
27 COLOR_GREEN 102, 127, 51 green (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), End portal frame, chain command block, sea pickle, moss carpet, moss block, dried kelp block
28 COLOR_RED 153, 51, 51 red (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), bricks (slab, stairs, wall), red mushroom block, Nether wart, enchanting table, Nether wart block, fire coral (coral block, coral,‌ coral fan‌), red mushroom, shroomlight, mangrove (planks, log (vertical), stripped log, wood, stripped wood, sign, door, pressure plate, fence, trapdoor, fence gate, slab, stairs), sniffer egg
29 COLOR_BLACK 25, 25, 25 black (wool, carpet, shulker box, bed (foot), stained glass, glazed terracotta, concrete, concrete powder, candle), obsidian, End portal, dragon egg, block of coal, End gateway, basalt, polished basalt, smooth basalt, block of netherite, ancient debris, crying obsidian, respawn anchor, blackstone (all variants, all stairs, all slabs, all walls), gilded blackstone, sculk, sculk vein, sculk catalyst, sculk shrieker, sculk sensor
30 GOLD 250, 238, 77 block of gold, light weighted pressure plate, bell, block of raw gold
31 DIAMOND 92, 219, 213 block of diamond, beacon, prismarine bricks (slab, stairs), dark prismarine (slab, stairs), conduit
32 LAPIS 74, 128, 255 block of lapis lazuli
33 EMERALD 0, 217, 58 block of emerald
34 PODZOL 129, 86, 49 podzol, spruce (planks, log (vertical), stripped log, wood, stripped wood, sign, pressure plate, trapdoor, stairs, slab, fence gate, fence, door), oak log (side), jungle log (side), campfire, soul campfire, mangrove log (side), mangrove roots, muddy mangrove roots
35 NETHER 112, 2, 0 netherrack, Nether bricks (fence, slab, stairs, wall, chiseled, cracked), Nether gold ore, Nether quartz ore, magma block, red Nether bricks (slab, stairs, wall), crimson (roots, fungus), weeping vines, crimson (pressure plate,‌ sign,‌ slab,‌ trapdoor,‌ fence‌)
36 TERRACOTTA_WHITE 209, 177, 161 white terracotta, calcite, cherry (planks, log (vertical), stripped log (vertical), sign, pressure plate, trapdoor, stairs, slab, fence gate, fence, door)
37 TERRACOTTA_ORANGE 159, 82, 36 orange terracotta, redstone lamp,‌ resin bricks (fence, slab, stairs, wall, chiseled), block of resin
38 TERRACOTTA_MAGENTA 149, 87, 108 magenta terracotta
39 TERRACOTTA_LIGHT_BLUE 112, 108, 138 light blue terracotta
40 TERRACOTTA_YELLOW 186, 133, 36 yellow terracotta
41 TERRACOTTA_LIGHT_GREEN 103, 117, 53 lime terracotta
42 TERRACOTTA_PINK 160, 77, 78 pink terracotta, cherry (stripped log (side), stripped wood)
43 TERRACOTTA_GRAY 57, 41, 35 gray terracotta, cherry log (side), cherry wood, tuff (all variants, all slabs, all stairs, all walls)
44 TERRACOTTA_LIGHT_GRAY 135, 107, 98 light gray terracotta, exposed copper (including all cut, waxed, stair, trapdoor‌ and slab variants), mud bricks (slab, stairs, wall)
45 TERRACOTTA_CYAN 87, 92, 92 cyan terracotta, mud
46 TERRACOTTA_PURPLE 122, 73, 88 purple (terracotta, shulker box‌)
47 TERRACOTTA_BLUE 76, 62, 92 blue terracotta
48 TERRACOTTA_BROWN 76, 50, 35 brown terracotta, pointed dripstone,‌ dripstone block
49 TERRACOTTA_GREEN 76, 82, 42 green terracotta, closed eyeblossom
50 TERRACOTTA_RED 142, 60, 46 red terracotta, decorated pot
51 TERRACOTTA_BLACK 37, 22, 16 black terracotta
52 CRIMSON_NYLIUM 189, 48, 49 crimson nylium
53 CRIMSON_STEM 148, 63, 97 crimson (door, stairs, stem, stripped stem, fence gate, planks, pressure plate,‌ sign,‌ slab,‌ trapdoor,‌ fence‌)
54 CRIMSON_HYPHAE 92, 25, 29 crimson (hyphae, stripped hyphae)
55 WARPED_NYLIUM 22, 126, 134 warped nylium, oxidized copper (including all cut, waxed, stair, trapdoor,‌ and slab variants)
56 WARPED_STEM 58, 142, 140 warped (door, stairs, stem, stripped stem, fence gate, planks, pressure plate,‌ sign,‌ slab,‌ trapdoor,‌ fence‌), weathered copper (including all cut, waxed, stair, trapdoor,‌ and slab variants)
57 WARPED_HYPHAE 86, 44, 62 warped (hyphae, stripped hyphae)
58 WARPED_WART_BLOCK 20, 180, 133 warped wart block
59 DEEPSLATE 100, 100, 100 deepslate (gold ore, iron ore, coal ore, lapis ore, diamond ore, redstone ore, emerald ore, copper ore), deepslate (all variants, all stairs, all slabs, and all walls), infested deepslate, reinforced deepslate
60 RAW_IRON 216, 175, 147 block of raw iron
61 GLOW_LICHEN 127, 167, 150 glow lichen, verdant froglight

Tints

For tints in ingame rendering, see Color § Biome colors.

In Bedrock Edition maps, certain blocks lack their own color and instead are assigned a color based on biome. These blocks are categorized by tint, with all blocks in a given tint sharing the same color within a biome.

Foliage

Grass

Water

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 Color ID Multiply R,G,B By = Multiplier
Base Color ID×4 + 0 180 0.71
Base Color ID×4 + 1 220 0.86
Base Color ID×4 + 2 255 (same color) 1
Base Color ID×4 + 3 135 0.53
All the different shades of each color

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 128×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 covers a square area 8 chunks on a side, and requires 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 61 colors. The staircase method offers 183 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 be obtained only with the use of an external tool.

Full color tables

The content of this section is disputed.
 
The color IDs for 1.7.2, 1.8.1, and 1.12 appear incompatible with each other, which conflicts with third-party code samples.
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.

Algorithm

The depth ranges for water

The natural generation makes use of Heightmaps to determine which block should be drawn.

For all blocks other than water, the shade is based on the height difference with the block directly north of it. If the current block is shorter, the 1st shade is used; if they are the same height, the 2nd shade is used; and if the current block is taller, the 3rd shade is used. The 4th shade does not occur naturally in this context.

For water, on the other hand, the map conveys the depth to the first non-water block beneath it. To represent this, the algorithm uses five distinct levels of depth: the 3 shades, plus two intermediate checker patterns that alternate between the two adjacent shades.

History

This section needs to be updated.
 
Please update this section to reflect recent updates or newly available information.
Reason: Incomplete history. TODO: find versions where block colors were added for new blocks
Java Edition Beta
?When Notch was adding maps for the first time he did not use the NBT format.[1]
1.6Test Build 3Added maps.
Map IDs are limited to the size of a short (32,768).[2]
Java Edition
1.8.1pre1Added the color "NETHER" (35), increasing the number of base colors from 35 to 36.
The shading multiplier for the fourth color is changed from 220 (0.86) to 135 (0.53).
1.1217w17aAdded 16 map colors for every color of terracotta: "TERRACOTTA_WHITE" (36), "TERRACOTTA_ORANGE" (37), "TERRACOTTA_MAGENTA" (38), "TERRACOTTA_LIGHT_BLUE" (39), "TERRACOTTA_YELLOW" (40), "TERRACOTTA_LIGHT_GREEN" (41), "TERRACOTTA_PINK" (42), "TERRACOTTA_GRAY" (43), "TERRACOTTA_LIGHT_GRAY" (44), "TERRACOTTA_CYAN" (45), "TERRACOTTA_PURPLE" (46), "TERRACOTTA_BLUE" (47), "TERRACOTTA_BROWN" (48), "TERRACOTTA_GREEN" (49), "TERRACOTTA_RED" (50), and "TERRACOTTA_BLACK" (51), increasing the number of base colors from 36 to 52.
1.1317w47aMaps ids are no longer shorts, but rather ints, as they are no longer based on damage values of the item.
idcounts.dat now uses an int instead of a short.
18w19aAdded DataVersion to saved map_<#>.dat. (idcounts.dat still doesn't have a DataVersion.)
1.1419w02aAdded locked to saved map_<#>.dat.
19w04aAdded DataVersion to idcounts.dat.
idcounts.dat is now gzipped.
1.16Pre-release 6Added 7 new colors: "CRIMSON_NYLIUM" (52), "CRIMSON_STEM" (53), "CRIMSON_HYPHAE" (54), "WARPED_NYLIUM" (55), "WARPED_STEM" (56), "WARPED_HYPHAE" (57), and "WARPED_WART_BLOCK" (58), increasing the number of base colors from 52 to 59.

External links

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

Library name, color version Language Link to Map-related code
MCModify (1.8) Java Map.java
minecraftmap (1.7) Python __init__.py
mcmapimg (1.19) Python mcmapimg.py

References

Navigation