Java Edition Alpha level format

Infdev introduced a new data storage challenge while under development: Terrain generated in infdev has the potential to be almost 235 petabytes, which is 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 will only be able to search a tiny fraction of the map in a reasonable time frame. Alpha uses this technique, and both Beta and Minecraft 1.0 still use the general concept because of its success.

In Minecraft Beta 1.3, this format was superseded by the Region file format, where chunks are stored in groups of 32×32 in region 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): 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.
 * 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"

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, followed by the dimension ID.

These dimension IDs were used in Alpha:

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 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:
 * The root tag.
 * : Global level data.
 * : Stores the Unix time stamp (in milliseconds) when the player saved the game.
 * : Estimated size of the entire world in bytes.
 * : Random number providing the Random Seed for the terrain.
 * : X coordinate of the level's spawn position.
 * : Y coordinate of the level's spawn position.
 * : Z coordinate of the level's spawn position.
 * : Stores the current "time of day" in ticks. There are 20 ticks per real-life second, and 24000 ticks per 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.
 * : The Singleplayer player for the level.
 * : The dimension the player is in. 0 is the Overworld, and -1 is The Nether.
 * : List of 3 TAG_Doubles for the X, Y, and Z position of the player.
 * : List of 2 TAG_Floats for the Yaw and Pitch of the player's view.
 * : List of 3 TAG_Doubles for the X, Y, and Z motion in meters per tick.
 * : 1 or 0 (true/false) - true if the player is on the ground.
 * : How far the player has fallen.
 * : The number of hit points the player has. 20 is 10 hearts.
 * : Number of ticks the player is immune to attacks.
 * : Number of ticks the player is red from being attacked.
 * : Number of ticks the player has been dead for - used for controlling the death animation.
 * : The number of ticks before the player starts to drown. Starts at 300.
 * : When negative, the number of ticks before the player can catch on fire. When positive, the number of ticks before the fire is extinguished.
 * : The player's score. The score was never utilized in Alpha or even beta, so this value is irrelevant.
 * : List of TAG_Compounds representing the items in the player's inventory.
 * An inventory item.
 * : The Slot the item is in.
 * : The Item ID.
 * : The item's data value, or damage value for tools.
 * : 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:
 * The root tag.
 * : The level data in this chunk.
 * : The X chunk coordinate.
 * : The Z chunk coordinate.
 * : 1 or 0 (true/false) - true if Minecraft has generated special features in this chunk such as trees, flowers, ores, dungeons.
 * : The tick when the chunk as last updated.
 * : 32768 bytes of Block IDs, 8 bits per block.
 * : 16384 bytes of Block Data, 4 bits per block.
 * : 16384 bytes of Block Light, 4 bits per block.
 * : 16384 bytes of Sky Light, 4 bits per block.
 * : 256 bytes of Height Map information, 8 bits per XZ column. Used for speeding up sky light calculations.
 * : List of TAG_Compounds, one for each entity in the chunk.
 * An entity.
 * See Chunk format → Entity Format - not all information is applicable to Minecraft Alpha.
 * : List of TAG_Compounds, one for each tile entity in the chunk.
 * A tile entity.
 * See Chunk format → Tile Entity Format - not all information is applicable to Minecraft Alpha.