Minecraft:Java Edition Alpha level format

Template:Conjecture Template:Outdated Template:Exclusive Minecraft:Infdev introduced a new data storage challenge while under development: terrain generated in Infdev has the potential to be almost 235 petabytes (240,640 terabytes) in size when stored in memory, due to the sheer size of the map (several times the surface area of the Earth). Therefore, to reduce file size and memory usage, Notch decided to split the terrain into 16×128×16 chunks and store them on disk when not visible. In addition, terrain is only generated when it is within the drawing distance of the player's camera, significantly reducing save size, since most players are only able to search a tiny fraction of the map in a reasonable time frame. Alpha uses this technique, and both Beta and newer versions still use the general concept because of its success.

The first version to use this format was Infdev 20100327.

In Minecraft Minecraft:Beta 1.3, this format was superseded by the Minecraft:Region file format, where chunks are stored in groups of 32×32 in region files.

The save format was used for all versions between Minecraft:Infdev 20100327 and Minecraft:Beta 1.2_02 inclusive, with the important exception of Infdev 20100624, which used the new Minecraft:Zone file format which was immediately scrapped afterwards due to creating massive world files.

World folder structure

An Alpha level is actually a single folder containing at least one file named level.dat. There is also a session.lock file to make sure only one Minecraft opens the level at once.

The level folder may have up to 64 subfolders, each with up to 64 additional subfolders each. These folders contain the chunk files that hold the level's terrain and entities. Each chunk file is identified by its chunk position xPos and zPos. The varying parts of the chunk file's name are obtained by taking the base36 representation of the xPos and zPos. The names of the folders that the chunk file is placed in are found by taking xPos and zPos, modulo 64 (or bitwise ANDing with 63), and converting to base36. Negative coordinates must be interpreted as positive numbers, bitwise, via two's complement. So, -13 is treated as 243 (if its size is a byte).

As an example, to find the chunk at position (-13, 44):

• The first folder name is base36(-13 % 64). This is base36(243 % 64 = 51) which is "1f".
• The second folder name is base36(44 % 64). This is base36(44) which is "18".
• The chunk file's name is "c." + base36(-13) + "." + base36(44) + ".dat". This evaluates to "c.-d.18.dat"
• Thus, the chunk at (-13, 44) is stored in "1f/18/c.-d.18.dat"

Each chunk remembers its position independently of the file and folder names. See below to find out how to read a chunk's position from the file data.

Dimensions

Dimensions are saved in the same way normal worlds are, but instead of mixing the world files inside the save folder, the files are stored in an additional sub-folders with their own region and chunk data. Their names start with DIM, followed by the dimension ID.

These dimension IDs were used in Alpha:

ID	Folder	Dimension
0	saves/[World]/	Normal world (Overworld), always stored in the world folder without DIM
-1	saves/[World]/DIM-1/	Minecraft:The Nether, added with the Minecraft:Halloween Update

session.lock format

session.lock contains the timestamp of when the world was last touched. The file is eight bytes long, and contains a single 64-bit signed integer in big endian format. The value of this integer is the timestamp, stored as the number of milliseconds elapsed since 1970, in UTC.

Unlike typical lock files, session.lock ensures that the LAST program to open a world is that one that owns it. The process goes something like this:

1. program opens session.lock
2. program writes timestamp to session.lock
3. program monitors session.lock for changes
4. if the contents of session.lock change, program aborts and gives up its lock on the world.

level.dat format

The level.dat file is a GZip'd Minecraft:NBT file that stores global level data (time of day, player health, inventory, velocity, and position within the map, etc.). Most importantly, it stores the Random Seed that the terrain generator uses to seamlessly generate more terrain on the fly.

This file has this structure:

• Template:Nbt The root tag.
  • Template:Nbt: Global level data.
    • Template:Nbt: Stores the Unix time stamp (in milliseconds) when the player saved the game.
    • Template:Nbt: Estimated size of the entire world in bytes.
    • Template:Nbt: Random number providing the random seed for the terrain.
    • Template:Nbt: X coordinate of the level's spawn position.
    • Template:Nbt: Y coordinate of the level's spawn position.
    • Template:Nbt: Z coordinate of the level's spawn position.
    • Template:Nbt: Stores the current "time of day" in ticks. There are 20 ticks per real-life second, and 24000 ticks per Minecraft Minecraft:day/night cycle, making the full cycle length 20 minutes. 0 is the start of daytime, 12000 is the start of sunset, 13800 is the start of nighttime, 22200 is the start of sunrise, and 24000 is daytime again. The value stored in level.dat is always increasing and can be larger than 24000, but the "time of day" is always modulo 24000 of the "Time" field value.
    • Template:Nbt: The Minecraft:Singleplayer player for the level.
      • Template:Nbt: The dimension the player is in. 0 is the Minecraft:Overworld, and -1 is Minecraft:The Nether.
      • Template:Nbt: List of 3 TAG_Doubles for the X, Y, and Z position of the player.
      • Template:Nbt: List of 2 TAG_Floats for the yaw and pitch of the player's view.
      • Template:Nbt: List of 3 TAG_Doubles for the X, Y, and Z motion in meters per tick.
      • Template:Nbt: 1 or 0 (true/false) - true if the player is on the ground.
      • Template:Nbt: How far the player has fallen.
      • Template:Nbt: The number of hit points the player has. 20 is 10 hearts.
      • Template:Nbt: Number of ticks the player is immune to attacks.
      • Template:Nbt: Number of ticks the player is red from being attacked.
      • Template:Nbt: Number of ticks the player has been dead for - used for controlling the death animation.
      • Template:Nbt: The number of ticks before the player starts to drown. Starts at 300.
      • Template:Nbt: When negative, the number of ticks before the player can catch on fire. When positive, the number of ticks before the fire is extinguished.
      • Template:Nbt: The player's score. The score was never utilized in Alpha or even beta, so this value is irrelevant.
      • Template:Nbt: List of TAG_Compounds representing the items in the player's inventory.
        • Template:Nbt An inventory item.
          • Template:Nbt: The slot the item is in.
          • Template:Nbt: The item ID.
          • Template:Nbt: The item's data value, or damage value for tools.
          • Template:Nbt: The number of this item in the stack. Range -128 to 127. Values less than 2 are not displayed in-game.

Chunk format

Chunk files, as described above, are GZip'd NBT files. They have this structure:

• Template:Nbt The root tag.
  • Template:Nbt: The level data in this chunk.
    • Template:Nbt: The X chunk coordinate.
    • Template:Nbt: The Z chunk coordinate.
    • Template:Nbt: 1 or 0 (true/false) - true if Minecraft has generated special features in this chunk such as trees, flowers, ores, dungeons.
    • Template:Nbt: The tick when the chunk was last updated.
    • Template:Nbt: 32768 bytes of block IDs, 8 bits per block.
    • Template:Nbt: 16384 bytes of block data, 4 bits per block.
    • Template:Nbt: 16384 bytes of block light, 4 bits per block.
    • Template:Nbt: 16384 bytes of sky light, 4 bits per block.
    • Template:Nbt: 256 bytes of height map information, 8 bits per XZ column. Used for speeding up sky light calculations.
    • Template:Nbt: List of TAG_Compounds, one for each entity in the chunk.
      • Template:Nbt An entity.
        • See Minecraft:Entity format - not all information is applicable to Minecraft Alpha.
    • Template:Nbt: List of TAG_Compounds, one for each tile entity in the chunk.
      • Template:Nbt A tile entity.
        • See Minecraft:Block entity format - not all information is applicable to Minecraft Alpha.

Block Format

Blocks are laid out in sets of vertical columns, with the rows going east-west through the chunk, and columns going north-south. Blocks in each chunk are accessed via the following method:

byte BlockID = Blocks[y + (z * ChunkSizeY(=128) + (x * ChunkSizeY(=128) * ChunkSizeZ(=16) ) ) ];

The coordinate system is as follows:

• X increases South, decreases North
• Y increases upwards, decreases downwards
• Z increases West, decreases East

All array indices are ordered YZX - the Y coordinate varies fastest. Note: The height map array is the only exception which has its indexes ordered ZX instead.

See also

• Indev level format
• Minecraft:Zone file format
• Minecraft:Region file format
• Minecraft:Anvil file format
  • Minecraft:Chunk format