Chunk format/Anvil/Before 1.13

This article is a work in progress.

 

Please help expand and improve it. The talk page may contain suggestions.
Note:

Missing entity & tile entity data among other things

Chunks store the terrain and entities within a 16×256×16 area. They also store precomputed lighting, heightmap data for Minecraft's performance, and other meta information.

NBT structure

Chunks are stored in NBT format, with this structure (see Block Format below for the ordering of the blocks within each array):

Block format

In the Anvil format, block positions are ordered YZX for compression purposes.

The coordinate system is as follows:

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

This also happens to yield the most natural scan direction, because all indices in the least significant dimension (i.e. X in this case) appear for each index in the next most significant dimension; so one reads an array ordered YZX as one would a book lying with its top northward, all letters (or X-indices) on a single line (or Z-index) at a time, and all lines on a single page (or Y-index) at a time. For the 2D arrays (i.e. "Biomes" and "HeightMap") the inapplicable Y dimension is simply omitted, as though the book is only one page thick.

Each section in a chunk is a 16x16x16-block area, with up to 16 sections in a chunk. Section 0 is the bottom section of the chunk, and section 15 is the top section of the chunk. To save space, completely empty sections are not saved. Within each section is a byte tag "Y" for the Y index of the section, 0 to 15, and then byte arrays for the blocks. The "Block" byte array has 4096 partial block IDs at 8 bits per block. Another byte array "Add" is used for block with IDs over 255, and is 2048 bytes of the other part of the 4096 block IDs at 4 bits per block. When both the "Block" and "Add" byte arrays exist, the partial ID from the "Add" array is shifted left 8 bits and added to the partial ID from the "Blocks" array to form the true Block ID. The "Data" byte array is also 2048 bytes for 4096 block data values at 4 bits per block. The "BlockLight" and "SkyLight" byte arrays are the same as the "Data" byte array but they are used for block light levels and sky light levels respectively. The "SkyLight" values represent how much sunlight or moonlight can potentially reach the block, independent of the current light level of the sky.

The endianness of the 2048-byte arrays (i.e. "Add," "Data," "BlockLight," & "SkyLight"), which give only 4 bits per block, seems to stand as the one anomalous exception to the otherwise consistent, format-wide standard of big-endian data storage. It also runs counter to the presumably natural human-readable printing direction. If the blocks begin at 0, they are grouped with even numbers preceding odd numbers (i.e. 0 & 1 share a byte, 2 & 3 share the next, etc.); under these designations Minecraft stores even-numbered blocks in the least significant half-byte, and odd-numbered blocks in the most significant half-byte. Thus block[0] is byte[0] at 0x0F, block[1] is byte[0] at 0xF0, block[2] is byte[1] at 0x0F, block[3] is byte[1] at 0xF0, etc. ...

The pseudo-code below shows how to access individual block information from a single section. Hover over text to see additional information or comments.

byte Nibble4(byte[] arr, int index){ return index%2 == 0 ? arr[index/2]&0x0F : (arr[index/2]>>4)&0x0F; }
int BlockPos = y*16*16 + z*16 + x;
byte BlockID_a = Blocks[BlockPos];
byte BlockID_b = Nibble4(Add, BlockPos);
short BlockID = BlockID_a + (BlockID_b << 8);
byte BlockData = Nibble4(Data, BlockPos);
byte Blocklight = Nibble4(BlockLight, BlockPos);
byte Skylight = Nibble4(SkyLight, BlockPos);

Entity format

Every entity is an unnamed [NBT Compound / JSON Object] TAG_Compound contained in the Entities list of a chunk file. The sole exception is the Player entity, stored in level.dat, or in <player>.dat files on servers.

Tile tick format

Tile Ticks represent block updates that need to happen because they could not happen before the chunk was saved. Examples reasons for tile ticks include redstone circuits needing to continue updating, water and lava that should continue flowing, recently placed sand or gravel that should fall, etc. Tile ticks are not used for purposes such as leaf decay, where the decay information is stored in the leaf block data values and handled by Minecraft when the chunk loads. For map makers, tile ticks can be used to update blocks after a period of time has passed with the chunk loaded into memory.

History

Chunks were first introduced in Minecraft Infdev. Before the addition of the MCRegion format in Beta 1.3, chunks were stored as individual chunk files ".dat" where the file names contained the chunk's position encoded in Base36 - this is known as the Alpha level format. MCRegion changed this by storing groups of 32×32 chunks in individual ".mcr" files with the coordinates in Base10, with the goal being to reduce disk usage by cutting down on the number of file handles Minecraft had open at once. MCRegion's successor is the current format, Anvil, which only made changes to the chunk format. The region file technique is still used, but the region file extensions are ".mca" instead.

The major change from MCRegion to Anvil was the division of Chunks into Sections; each chunk has up to 16 individual 16×16×16 block Sections so that completely empty sections will not be saved at all. Preparation has also been made to support blocks with IDs in the range 0 to 4095, as compared to the previous 0 to 255 limitation. However, Minecraft is not fully prepared for such blocks to exist as items; many item IDs are already taken in the range 256 to 4095.

The Blocks, Data, BlockLight, and SkyLight arrays are now housed in individual chunk Sections. The Data, SkyLight, and BlockLight are arrays of 4-bit values, and the BlockLight and SkyLight arrays no longer house part of the block ID. The Blocks array is 8 bits per block, and the 4096-blocks support exists in the form of an optional Add byte array of 4-bits per block for additional block ID information. With the Anvil format, the NBT Format was changed from Notch's original specification to include an integer array tag similar to the existing byte array tag. It is currently only used for HeightMap information in chunks.