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 to 2.1
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.
File format used by versions 2.2 and later
The format is almost identical to 2.1 and the below will only describe the differences. The major change is that the height of the terrain was doubled from 128 to 256 blocks.
The name of the chunks file is changed to Chunks32h.dat instead of Chunks32.dat.
Each chunk is now 16 * 256 * 16 * sizeof(int) for blocks and 16 * 16 * sizeof(int) for surface, plus 16 bytes of header. Together 263184 bytes (as opposed to 132112 of previous format).
To calculate index of a Block in Blocks array of a chunk use the following formula:
int blockIndex = y + x * 256 + z * 256 * 16; // where x is 0-15, y is 0-255 and z is 0-15
There are no other changes.
53 Comments
Could someone please make an out of game world editing tool? I would prefer something similar to MCEdit for Minecraft, but any is acceptable.
Yah would be cool.
You lost me at chunks…
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.
Looks a bit more like C or C++ to me, and iPhones don’t support Java.
I’m trying to figure out how to open and edit Chunks.dat file but in vain… Which program may I use?
Chunks file is binary so you don’t really want to edit it by hand.
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…)
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.
If I manage to get the right sourcecode to work with, I’ll (or a friend of mine) be able to create some tools.
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.
so, I’M not the only person who knows c sharp at this age :D
At age 13 I know that Python is better.
notepad
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.
What is the mod? i would like to download it.
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
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.
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 :’)
how do you get texture packs
it won’t let me update can you update it on 1 mobile market please kaalus
game Tool making is impossible for under 20 years old.
:P I am 14 years old :D
Well i don’t think so. I am 12 and am very good in batch,python and visualbasic.
:D contact me bro :D facebook Arda Özkal
OKAY kaalus explain this in english!!!!!
This is not English, this is code… Big difference.
HI!!!
kaalus how do i get programming skills
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.
Is this written in C++? just curious.
I dunno. Maybe in just plain c
I have another question: Is this coding for a class, or is it something else entirely?
Hi this is my favorite game, but I want play in Multiplayer, its the only thing missing.
Yay! Thank you Kaalus for the 1.29 block structure info. Very useful.
In the 1.29 block structure, is bit 0 the most significant or least significant bit?
I don’t think you understand at all…
I meant this: https://en.wikipedia.org/wiki/Bit_numbering.
See also https://en.wikipedia.org/wiki/Most_significant_bit#Most_Significant_Bit_First_vs_Least_Significant_Bit_First.
You’re acting like the developer when you’re clearly just some wannabe coder.
Oh, really? You do realize Crayder is developing a high end tool for manipulating Survivalcraft worlds, right?
Little endian is the encoding. So just look it up😜
So umm… Imagine an 8.06420899555gb world…
The game is written in C#?
Yes, obviously. Look at the code.
Yeah. This is not C, or C++. It must be C#.
How would I create an empty world which is just a small floating platform of block over the void
I am starting to study this file format a bit myself, so I may be of some help.
First use his formulas to access the chunks/blocks you want to erase from existence, converting them to air, or if the block in context is your platform, to the block ID you want. This is not something you do by hand. This requires you to understand programming, someone with an imagination could program a tool for this in any language they preferred, but the documentation is provided in C#. This is not too hard to understand if you are a well seasoned programmer like Crayder. I am a programmer myself; however, without anyone to gauge my skill level against asside from Special K — who is superior by far — there is no knowing truly how advanced I am. 😋
hmmm well….. I decompiled the game using dnspy and did some digging, and I have a problem. I digged to see if there is a way to change block hardnesses but the values are nowhere to be found
lol
I’m working on a version of the Chunks32.dat format struct in the Kaitai Struct format. I’m almost done with it and it’s working well; I’ll post it here when I’m done. In case you don’t know, Kaitai Struct is a binary data structure system that works with several different programming languages. More info about Kaitai Struct is at http://kaitai.io/. But unfortunately, Kaitai Struct currently doesn’t support serialization of data, so you can’t use it to actually modify Chunks32.dat files.
i lost my kaitai struct thingy a while ago
In 2.2 worlds, the Unused1 value in SurfacePoint seems to be set to 65 (0x40) instead of 0.
Actually, it seems like these unused values can be various values. So maybe they aren’t actually unused anymore.
65 is not 0x40, 65 is 0x41. 64 is 0x40.