Minecraft:Map item format

Minecraft: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.

Template:IN 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.

Template:IN 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 Minecraft:glass pane.

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

Data folder structure

Template:IN, 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.

Template:IN, 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

• Template:Nbt The root tag.
  • Template:Nbt: The map data.
    • Template:Nbt: How zoomed in the map is (it is in 2^scale wide blocks square per pixel, even for 0, where the map is 1:1). Default 3, minimum 0 and maximum 4.
    • Template:Nbt: For <1.16 (byte): 0 = The Minecraft:Overworld, -1 = Minecraft:The Nether, 1 = Minecraft:The End, any other value = a static image with no player pin. In >=1.16 this is the resource location of a dimension instead. Template:More info
    • Template:Nbt: 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.
    • Template:Nbt: 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 Minecraft:Explorer Maps.
    • Template:Nbt: 1 if the map has been locked in a Minecraft:cartography table.
    • Template:Nbt: Center of map according to real world by X.
    • Template:Nbt: Center of map according to real world by Z.
    • Template:Nbt: List of banner markers added to this map. May be empty.
      • Template:Nbt A banner marker.
        • Template:Nbt: 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.
        • Template:Nbt: The custom name of the banner, in JSON text. May not exist.
        • Template:Nbt: The block position of the banner in the world.
          • Template:Nbt: The x-position of the banner.
          • Template:Nbt: The y-position of the banner.
          • Template:Nbt: The z-position of the banner.
    • Template:Nbt: List of map markers added to this map. May be empty.
      • Template:Nbt A marker.
        • Template:Nbt: Arbitrary unique value for the marker.
        • Template:Nbt: The rotation of the marker, ranging from 0 to 360.
        • Template:Nbt: The block position of the marker in the world.
          • Template:Nbt: The x-position of the marker.
          • Template:Nbt: The y-position of the marker.
          • Template:Nbt: The z-position of the marker.
    • Template:Nbt: 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.
  • Template:Nbt: 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

• Template:Nbt: The root tag.
  • Template:Nbt: The Unique ID of the map.
  • Template:Nbt: The Unique ID's of the parent maps.
  • Template:Nbt: 0 = The Minecraft:Overworld, 1 = Minecraft:The Nether, 2 = Minecraft:The End, any other value = a static image with no player pin.
  • Template:Nbt: 1 if the map is full explored.
  • Template:Nbt: 1 if the map has been locked in a Minecraft:cartography table.
  • Template:Nbt: 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 Minecraft:anvil or a Minecraft:cartography table, the Unique ID of the map changes.
  • Template:Nbt: Unknown. Default 0.
  • Template:Nbt: The height of the map. Is associated with the scale level.
  • Template:Nbt The width of the map. Is associated with the scale level.
  • Template:Nbt: Center of the map according to real world by X.
  • Template:Nbt: Center of the map according to real world by Z.
  • Template:Nbt: A list of optional icons to display on the map.
    • Template:Nbt: An individual decoration.
      • Template:Nbt
        • Template:Nbt: The rotation of the symbol, ranging from 0 to 15. South = 0, West = 4, North = 8, East = 12.
        • Template:Nbt: The ID of the map icon to display.
        • Template:Nbt: The horizontal column (x) where the decoration is located on the map (per pixel).
        • Template:Nbt: The vertical column (y) where the decoration is located on the map (per pixel).
      • Template:Nbt
        • Template:Nbt: The world x-position of the decoration.
        • Template:Nbt: The world y-position of the decoration.
        • Template:Nbt: The world z-position of the decoration.
        • Template:Nbt: Unknown.
  • Template:Nbt: An array of bytes that represent color values (65536 entries for a default 128×128 map), each pixel is represented as 4 bytes (r,g,b,a), colors can be accessed with rgba = colors.slice((xOffset + yOffset * 128) * 4, (xOffset + yOffset * 128 + 1) * 4).

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

• Template:Nbt The root tag.
  • Template:Nbt
    • Template:Nbt: Latest map ID.
  • Template:Nbt: Minecraft: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.) Minecraft:Map item format/header

Tints

Template:For In Minecraft: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

• Template:BlockLink
• Template:BlockLink
• Template:BlockLink
• Template:BlockLink
• Template:BlockLink
• Template:BlockLink

Grass

• Template:BlockLink
• Template:BlockLink (note Template:BlockLink is not included)
• Template:BlockLink (note Template:BlockLink is not included)
• Minecraft:Corals and Minecraft:Coral Fans

Water

• Template:BlockLink

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.

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

File:Map colors.png

All the different shades of each color

All map colors and shades organized from black to white in Oklab with the index number below each set.

All map colors and shades organized from black to white in Oklab with the index number below each set.

Map pixel art

File:Map Pixel Art Train.jpg

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

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

File:MapWaterLevels.png

The depth ranges for water

The natural generation makes use of Minecraft: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. Blocks that use the NONE color are not drawn; they instead draw the block underneath them.

For water, 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.

When the Minecraft:Void is present on a map, it is drawn as the STONE color. Additionally, when a block that uses the NONE color is above the void and nothing else, nothing is drawn, resembling unexplored areas of a map.

External links

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

Name	Game Version	Language	Link to Source
minecraftmap	1.7	Python	__init__.py
MCModify	1.8	Java	Map.java
mcmapimg	1.19	Python	mcmapimg.py
MapColors	1.21	Java	github.com/nothub/MapColors
Palette	1.21	Java	github.com/plonck/palette