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.

 

39 Comments

  1. Bryson
    Posted March 27, 2012 at 21:59 | Permalink | Reply

    Could someone please make an out of game world editing tool? I would prefer something similar to MCEdit for Minecraft, but any is acceptable.

    • Tanner
      Posted March 28, 2012 at 03:58 | Permalink | Reply

      Yah would be cool.

  2. jriot10
    Posted March 27, 2012 at 23:31 | Permalink | Reply

    You lost me at chunks…

  3. 1285done
    Posted March 30, 2012 at 03:29 | Permalink | Reply

    If you want to edit the code kaalus put in you need a java programmer (i have eclipse witch is free at eclipse.org) just copy and paste w/ other code lines (you have to know java to program this) and then you have part 1 of the sorce code because if ur gonna have a full game you need to have player data inventory etc.

    • Posted September 5, 2013 at 22:50 | Permalink | Reply

      Looks a bit more like C or C++ to me, and iPhones don’t support Java.

  4. korbaksc
    Posted April 2, 2012 at 11:34 | Permalink | Reply

    I’m trying to figure out how to open and edit Chunks.dat file but in vain… Which program may I use?

    • Posted April 2, 2012 at 11:41 | Permalink | Reply

      Chunks file is binary so you don’t really want to edit it by hand.

      • korbaksc
        Posted April 2, 2012 at 12:56 | Permalink | Reply

        Well in that case what are the resources we can use to create such “a tool that produces a patch of flat terrain so that you don’t have to flatten it yourself in creative mode”?
        (as you’ve maybe guessed my programming level is not as advanced as yours…)

        • Posted April 2, 2012 at 13:17 | Permalink

          If you are not a programmer this is of not much use to you. I released this information so that someone who has some programming skills can potentially create some tools without doing a lot of reverse enginnering.

      • korbaksc
        Posted April 2, 2012 at 13:28 | Permalink | Reply

        If I manage to get the right sourcecode to work with, I’ll (or a friend of mine) be able to create some tools.

      • nosyrbllewe
        Posted April 10, 2012 at 04:01 | Permalink | Reply

        Cool, I want to randomly put in 1’s and 0’s and see how my world will turn out. I know some basic C# I may be able to do something with the chunks.dat, but don’t put your hopes too high as I am only 13 years old.

        • Posted November 3, 2013 at 09:04 | Permalink

          so, I’M not the only person who knows c sharp at this age :D

    • Jake
      Posted March 17, 2013 at 22:40 | Permalink | Reply

      notepad

  5. 1285done
    Posted April 10, 2012 at 23:14 | Permalink | Reply

    hey dont worry im 13 and im making a mod for minecraft and just made a new block with a texture if you work on it alot youll do great.

    • nosyrbllewe
      Posted April 10, 2012 at 23:58 | Permalink | Reply

      What is the mod? i would like to download it.

      • 1285done
        Posted April 11, 2012 at 00:21 | Permalink | Reply

        actually i just started a couple days ago and i actually havent released it but if you want to keep up with how the mods going just follow my blog at decorationplus.wordpress.com i update quite often

  6. nosyrbllewe
    Posted April 23, 2012 at 03:38 | Permalink | Reply

    Im starting to make a companion program using the information above to edit create a flat landscape (with the choosen block type, humidity, ect) with maybe some other features too. The program will most likely be called “SCWorldEdit”. This program is console based. It is nothing like MCedit, although I may make the program non-console after it is released. You may ask me questions if you like (anything besides the release date) at brysonewell@hotmail.com.

    • Remy
      Posted January 10, 2013 at 01:02 | Permalink | Reply

      Is it possible to import schematic files?

      I mean it’d be great to import some creations from my minecraft maps to Survivalcraft I use to port PC maps to Pocket Edition with MCEdit n’ I’m just waitin’ to do the same with Survivalcraft :’)

  7. flamemage 1
    Posted January 19, 2013 at 09:44 | Permalink | Reply

    how do you get texture packs

  8. marvin
    Posted February 2, 2013 at 12:55 | Permalink | Reply

    it won’t let me update can you update it on 1 mobile market please kaalus

  9. papia sultana
    Posted May 6, 2013 at 11:51 | Permalink | Reply

    game Tool making is impossible for under 20 years old.

  10. riptide16
    Posted June 8, 2013 at 11:00 | Permalink | Reply

    Well i don’t think so. I am 12 and am very good in batch,python and visualbasic.

  11. Posted June 27, 2013 at 16:31 | Permalink | Reply

    OKAY kaalus explain this in english!!!!!

  12. Posted June 28, 2013 at 01:04 | Permalink | Reply

    HI!!!

  13. i dont know
    Posted July 11, 2013 at 20:57 | Permalink | Reply

    kaalus how do i get programming skills

  14. Henry Padilla
    Posted July 25, 2013 at 14:19 | Permalink | Reply

    Is this information still valid? I can’t seem to find the file specified above. I’d love to make some of these tools but I can’t start without a file.

  15. Posted April 8, 2015 at 18:55 | Permalink | Reply

    Is this written in C++? just curious.

  16. Posted April 8, 2015 at 19:38 | Permalink | Reply

    I have another question: Is this coding for a class, or is it something else entirely?

  17. Posted May 11, 2015 at 18:14 | Permalink | Reply

    Hi this is my favorite game, but I want play in Multiplayer, its the only thing missing.

  18. timskillman
    Posted January 14, 2016 at 22:11 | Permalink | Reply

    Yay! Thank you Kaalus for the 1.29 block structure info. Very useful.

  19. Posted January 18, 2016 at 18:58 | Permalink | Reply

    In the 1.29 block structure, is bit 0 the most significant or least significant bit?

  20. Posted January 26, 2016 at 19:30 | Permalink | Reply

    So umm… Imagine an 8.06420899555gb world…

Leave a Reply. No swearing please.

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s