Chunks.dat File Format

File format used by versions 1.4 to 1.28

The Chunks.dat file stores binary terrain blocks data. It does not contain entities data (where the player or creatures are, where pickable items are located etc.).

The terrain is stored as a sparse array of chunks 16x16x128 blocks each, with a fixed-size dictionary describing locations and offsets of existing chunks. Not all chunks are present in the file, only those that have been modified from the default (generated) state. The game builds the remaining chunks using the generation algorithm.

The chunks file contains two parts:

• The directory of chunks
• The array of chunks

Each entry in the directory contains description of a single chunk. The entry is 12 bytes, and there are 65536 entries (the space for all of them is reserved in the file). Unused entries are filled with zeroes. After 65536 entries, there is one extra dummy entry that always contains all zeroes. The whole directory size is 786444 bytes.

Each chunk contains a header, a 3-dimensional array of blocks (16x16x128 blocks, x/z/y) and a 2-dimensional array of surface parameters (16×16 surface points, x/z). Header is 16 bytes. Each block is 2 bytes long. Each surface point is 4 bytes long. Chunks are always saved whole, even if only one block differs from the generated version, so each chunk has the same size of 66576 bytes.

Data structures details

// All data little-endian.

// A single entry in directory of chunks
struct DirectoryEntry
{
    int ChunkX;   // Chunk position, (1 unit equals 16 blocks, must be positive)
    int ChunkZ;   // Chunk position, (1 unit equals 16 blocks, must be positive)
    int Offset;   // Offset of chunk data from the start of file, in bytes
}

// The whole directory of chunks
struct Directory
{
    DirectoryEntry Entries[65536];  // Directory entries, unused entries filled with 0
    DirectoryEntry Guard;           // Guard entry always filled with 0
}

// A single block
struct Block
{
    byte BlockType;  // Type of block (0-air, 1-bedrock, 2-dirt, 3-granite etc.)
    byte BlockData;  // 4 low bits contain light level, 4 high bits contain block-specific data
}

// A single surface point
struct SurfacePoint
{
    byte MaxHeight;      // Maximum height at this point (non-air blocks)
    byte TempHumidity;   // 4 low bits contain temperature, 4 high bits contain humidity
    byte Unused1;        // Currently unused (must be zero)
    byte Unused2;        // Currently unused (must be zero)
}

// Chunk header
struct ChunkHeader
{
    int Magic1;     // Must be 0xDEADBEEF
    int Magic2;     // Must be 0xFFFFFFFF
    int ChunkX;     // Chunk position (1 unit equals 16 blocks, must be positive)
    int ChunkZ;     // Chunk position (1 unit equals 16 blocks, must be positive)
}

// A single chunk
struct Chunk
{
    ChunkHeader Header;           // Chunk header
    Block Blocks[32768];          // Data of all blocks in chunk (16*16*128), in x/z/y order
    SurfacePoint Surface[256];    // Data of all surface points in chunk (16*16), in x/z order
}

// The whole chunks.dat file
struct ChunksFile
{
    Directory Dir;      // Chunks directory
    Chunk Chunks[];     // Array of chunks, variable size (0 to 65536 max)
}

Surface Points

Surface points contain height, temperature and humidity data. This data is theoretically redundant because it can be regenerated by the game engine. Such regeneration is however costly, so the data is stored along with the blocks. Each surface point describes the entire vertical “shaft” 1x1x128 blocks large, from the top to the bottom of the world.

Temperature is a value from 0 (extreme cold) to 15 (extreme hot). Humidity is a value from 0 (extreme dry) to 15 (extreme wet). Both these values are used to color certain blocks, such as leaves, water, grass. They are also initially used by the terrain generator to produce appropriate terrain features (e.g. trees when there is enough humidity).

Height is surface height inside the given shaft, in blocks, with 0 being the lowest and 127 the highest value. All blocks above that height are assumed to contain only non-light blocking blocks (mostly air). Height value is used to speed up lighting calculations.

To calculate index of a SurfacePoint in Surface array of a chunk use the following formula:

int surfacePointIndex = x + z * 16;  // where x is 0-15 and z is 0-15

Blocks

BlockType is a value from 0 to 255 that determines what type of block exists at that location. The XML blocks data file contains detailed description of all blocks available in game.

BlockData is 8-bit data value associated with each block instance. Low 4 bits contain light value (0 – complete darkness, 15 – full sunlight). High 4 bits contain block-specific data, such as door state, water level, torch location etc. This data is undocumented at the moment. For most blocks it is safe to set it to 0.

To calculate index of a Block in Blocks array of a chunk use the following formula:

int blockIndex = y + x * 128 + z * 128 * 16; // where x is 0-15, y is 0-127 and z is 0-15

File format used by versions 1.29 and later

The file format is very similar to 1.28, and this section will only describe differences from it. The major change is that blocks are now 32 bits long instead of 16 bits.

The name of the chunks file is Chunks32.dat instead of Chunks.dat.

The new 32 bit block format is as follows:

• Bits 0 to 9 (10 bits): Block type
• Bits 10 to 13 (4 bits): Block light value
• Bits 14 to 31 (18 bits): Block data determining state of the block

Each chunk size is now 16 * 128 * 16 * sizeof(int) for blocks and 16 * 16 * sizeof(int) for surface, plus 16 bytes of header. Together 132112 bytes (as opposed to 66576 of previous format).

Because the size of file can now grow beyond 4GB, there is a change in dictionary. Instead of saving chunk offset in bytes, each dictionary entry saves chunk index (starting at 0). To get actual chunk offset you need to multiply chunk index by chunk size and add dictionary size (which is unchanged).

All unused dictionary entries must have chunk index set to -1 (as opposed to chunk offset of 0 in the 1.28).

The chunk header magic number is changed to (0xDEADBEEF, 0xFFFFFFFE), instead of (0xDEADBEEF, 0xFFFFFFFF) in 1.28.

Otherwise the formats should be identical.