Indev level file format

Jump to: navigation, search

This is a resurrection of the original page at

Level File Format

Minecraft levels uses a custom tagged binary format I've chosen to call Named Binary Tag (or NBT for short).
To be able to load and save Minecraft levels in a future proof way, please implement support for NBT.
You can read the specification here (includes an example of how to parse the format).

Minecraft level files have the file extension mclevel, and Internet media type ("MIME type") application/x-minecraft-level

Here's the layout of a minecraft level NBT file:
(Download sample file) (dead)

TAG_Compound "MinecraftLevel"
   TAG_Compound "Environment" 
      TAG_Short "SurroundingGroundHeight"// Height of surrounding ground (in blocks)
      TAG_Byte "SurroundingGroundType"   // Block ID of surrounding ground
      TAG_Short "SurroundingWaterHeight" // Height of surrounding water (in blocks)
      TAG_Byte "SurroundingWaterType"    // Block ID of surrounding water
      TAG_Short "CloudHeight"            // Height of the cloud layer (in blocks)
      TAG_Int "CloudColor"               // Hexadecimal value for the color of the clouds
      TAG_Int "SkyColor"                 // Hexadecimal value for the color of the sky
      TAG_Int "FogColor"                 // Hexadecimal value for the color of the fog
      TAG_Byte "SkyBrightness"           // The brightness of the sky, from 0 to 100
   TAG_List "Entities"
         // One of these per entity on the map.
         // These can change a lot, and are undocumented.
         // Feel free to play around with them, though.
         // The most interesting one might be the one with ID "LocalPlayer", which contains the player inventory
   TAG_Compound "Map"
      // To access a specific block from either byte array, use the following algorithm:
      // Index = x + (y * Depth + z) * Width

      TAG_Short "Width"                  // Width of the level (along X) 
      TAG_Short "Height"                 // Height of the level (along Y) 
      TAG_Short "Length"                 // Length of the level (along Z) 
      TAG_Byte_Array "Blocks"             // An array of Length*Height*Width bytes specifying the block types
      TAG_Byte_Array "Data"              // An array of Length*Height*Width bytes with data for each blocks
      TAG_List "Spawn"                   // Default spawn position
         TAG_Short x  // These values are multiplied by 32 before being saved
         TAG_Short y  // That means that the actual values are x/32.0, y/32.0, z/32.0
         TAG_Short z
   TAG_Compound "About"
      TAG_String "Name"                  // Level name
      TAG_String "Author"                // Name of the player who made the level
      TAG_Long "CreatedOn"               // Timestamp when the level was first created

And here are the currently implemented block ids:

0: Air
1: Rock
2: Grass
3: Dirt
4: Cobblestone
5: Wood
6: Sapling
7: Adminium
8: Water
9: Stationary water
10: Lava
11: Stationary lava
12: Sand
13: Gravel
14: Gold ore
15: Iron ore
16: Coal ore
17: Tree trunk
18: Leaves
19: Sponge
20: Glass
21 through 36: Cloth tiles of various colors
37: Flower
38: Rose
39: Red mushroom
40: Brown mushroom
41: Gold
42: Iron (honestly!)
43: Double stone slab
44: Single stone slab
45: Red brick tile
46: TNT
47: Bookshelf
48: Moss covered cobblestone
49: Obsidian
50: Torch
51: Fire
52: Infinite water source