Chunk format

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):
 * The root tag.
 * : Version of the chunk NBT structure.
 * : Chunk data.
 * : X position of the chunk.
 * : Z position of the chunk.
 * : Tick when the chunk was last saved.
 * : The cumulative number of ticks players have been in this chunk. Note that this value increases faster when more players are in the chunk. Used for regional difficulty: increases the chances of mobs spawning with equipment, the chances of that equipment having enchantments, the chances of spiders having potion effects, the chances of mobs having the ability to pick up dropped items, and the chances of zombies having the ability to spawn other zombies when attacked. Note that at values 3600000 and above, regional difficulty is effectively maxed for this chunk. At values 0 and below, the difficulty is capped to a minimum (thus, if this is set to a negative number, it will behave identically to being set to 0, apart from taking time to build back up to the positives). See Regional Difficulty for more specifics.
 * : May not exist. 256 bytes of biome data, one byte for each vertical column in the chunk. See Data Values for biome IDs. If this tag does not exist it will be created and filled by Minecraft when the chunk is loaded and saved. If any values in this array are -1, Minecraft will also set them to the correct biome.
 * : List of Compound tags, each tag is a sub-chunk of sorts.
 * An individual Section.
 * : The Y index (not coordinate) of this section. Range 0 to 15 (bottom to top), with no duplicates but some sections may be missing if empty.
 * : Set of different block states used in the chunk.
 * : Block state
 * : Id of the block
 * : List of block state properties, with [name] being the name of the block state property
 * : value of the property
 * : 2048 bytes recording the amount of block-emitted light in each block. Makes load times faster compared to recomputing at load time. 4 bits per block.
 * : A variable amount of 64-bit longs, enough to fit 4096 indices. The indices correspond to the ordering of elements in the section's Palette. All indices are the same size in a section, which is the size required to represent the largest index (minimum of 4 bits). If the size of each index is not a factor of 64, the bits will continue on the next long.
 * : 2048 bytes recording the amount of sunlight or moonlight hitting each block. 4 bits per block.
 * : Each TAG_Compound in this list defines an entity in the chunk. See Entity Format below. If this list is empty it will be a list of End tags (before 1.10, list of Byte tags).
 * : Each TAG_Compound in this list defines a block entity in the chunk. See Block Entity Format below. If this list is empty it will be a list of End tags (before 1.10, list of Byte tags).
 * : Each TAG_Compound in this list is an "active" block in this chunk waiting to be updated. These are used to save the state of redstone machines or falling sand, and other activity. See Tile Tick Format below.
 * : A List of 16 lists.
 * : A List of 16 lists.
 * : A List of 16 lists.
 * : A List of 16 lists.
 * : One of the following: empty, base, carved, liquid_carved, decorated, lighted, mobs_spawned, finalized, fullchunk, or postprocessed.
 * : Only the structures that can spawn in this dimension are stored, for example, EndCity is only stored in the end chunks.
 * : Chunk X coordinate of the start of the structure. Absent if id is INVALID.
 * : Chunk Z coordinate of the start of the structure. Absent if id is INVALID.
 * : If there's no structure of this kind in this chunk, this value is "INVALID", else it's the structure name.
 * : The biome id this structure is in. Absent if id is INVALID.
 * : Bounding box of the entire structure. Value is 6 ints: the minimum X, Y, and Z coordinates followed by the maximum X, Y, and Z coordinates. Absent if id is INVALID.
 * : 1 or 0 (true/false) - (Village only) Whether the village generated at least 3 non-roads. Absent if id is INVALID.
 * : (Monument only) List of chunks that have had their piece of the structure created. Absent if id is INVALID.
 * : Chunk X coordinate
 * : Chunk Z coordinate
 * : List of structure pieces making up this structure. Absent if id is INVALID.
 * : Structure piece data.
 * : Identifier for the structure piece. Typically a heavily abbreviated code rather than something human-readable.
 * : Rotation of ocean ruins and shipwrecks. Valid values are COUNTERCLOCKWISE_90, NONE, CLOCKWISE_90, and CLOCKWISE_180.
 * : The ocean temperature this ocean ruins is in. Valid values are WARM and COLD.
 * : The template of the ocean ruin or shipwreck that was used.
 * : The integrity of this structure (only used by ocean ruins).
 * : The X coordinate origin of this ocean ruin or shipwreck.
 * : The Y coordinate origin of this ocean ruin or shipwreck.
 * : The Z coordinate origin of this ocean ruin or shipwreck.
 * : 1 or 0 (true/false) - If this ocean ruin is big.
 * : Appears to be some sort of measure of how far this piece is from the start.
 * : Likely orientation of the structure piece.
 * : Bounding box of the structure piece. (Does not include the part of a village roof that can overhang the road.) Value is 6 ints: the minimum X, Y, and Z coordinates followed by the maximum X, Y, and Z coordinates.
 * : (Temples and huts) Width of the structure (X/Z).
 * : (Temples and huts) Height of the structure (Y).
 * : (Temples and huts) Depth of the structure (X/Z).
 * : (Temples and huts) Y level the structure was moved to in order to place it on the surface, or -1 if it hasn't been moved yet.
 * : 1 or 0 (true/false) - (Jungle temple) Whether the hallway arrow trap dispenser was placed.
 * : 1 or 0 (true/false) - (Jungle temple) Whether the chest arrow trap dispenser was placed.
 * : (1 or 0 (true/false) - Jungle temple) Whether the main chest was placed.
 * : 1 or 0 (true/false) - (Jungle temple) Whether the hidden chest was placed.
 * : 1 or 0 (true/false) - (Desert temple) Whether chest was placed.
 * : 1 or 0 (true/false) - (Desert temple) Whether chest was placed.
 * : 1 or 0 (true/false) - (Desert temple) Whether chest was placed.
 * : 1 or 0 (true/false) - (Desert temple) Whether chest was placed.
 * : 1 or 0 (true/false) - (Witch hut) Whether the initial witch has been spawned for the hut.
 * : 1 or 0 (true/false) - (Mineshaft "MSCorridor") Whether the corridor has rails.
 * : 1 or 0 (true/false) - (Mineshaft "MSCorridor") Whether the corridor has cobwebs.
 * : 1 or 0 (true/false) - (Mineshaft "MSCorridor") Whether the corridor has a cave spider spawner.
 * : (Mineshaft "MSCorridor") Corridor length.
 * : 1 or 0 (true/false) - (Mineshaft "MSCrossing") Whether the crossing is two floors tall.
 * : (Mineshaft "MSCrossing") Indicates the "incoming" direction for the crossing.
 * : (Mineshaft "MSRoom") List of exits from the room.
 * : Bounding box of the exit.
 * : 1 or 0 (true/false) - (Fortress "NeSCLT" and "NeSCRT") Whether this fortress piece should contain a chest but hasn't had one generated yet. (Stronghold "SHCC") Whether this chest in this stronghold piece was placed. (Village "ViS") Whether the blacksmith chest has been generated.
 * : 1 or 0 (true/false) - (Fortress "NeMT") Whether this fortress piece should contain a Blaze spawner but hasn't had one generated yet. (Stronghold "SHPR") Whether the Silverfish spawner has been placed in this piece.
 * : (Fortress "NeBEF") Random seed for the broken-bridge fortress piece.
 * : (Stronghold) The type of door at the entry to this piece.
 * : (Stronghold "SHFC") Length of the corridor
 * : 1 or 0 (true/false) - (Stronghold "SH5C") Whether the 5-way crossing has an exit on the lower level on the side with the upward staircase.
 * : 1 or 0 (true/false) - (Stronghold "SH5C") Whether the 5-way crossing has an exit on the lower level on the side with the downward staircase.
 * : 1 or 0 (true/false) - (Stronghold "SH5C") Whether the 5-way crossing has an exit on the upper level on the side with the upward staircase.
 * : 1 or 0 (true/false) - (Stronghold "SH5C") Whether the 5-way crossing has an exit on the upper level on the side with the downward staircase.
 * : 1 or 0 (true/false) - (Stronghold "SHLi") Whether the library has an upper level.
 * : (Stronghold "SHRC") Indicates whether the room contains a pillar with torches, a fountain, an upper level with a chest, or is just empty room.
 * : 1 or 0 (true/false) - (Stronghold "SHSD") Whether the spiral staircase is the source of the Stronghold or was randomly generated.
 * : 1 or 0 (true/false) - (Stronghold "SHS") Whether the corridor has an opening on the left.
 * : 1 or 0 (true/false) - (Stronghold "SHS") Whether the corridor has an opening on the right.
 * : (Village) Village type: 0=plains, 1=desert, 2=savanna, 3=taiga.
 * : 1 or 0 (true/false) - (Village) Whether this village generated as a zombie village.
 * : (Village) Count of villagers spawned along with this piece.
 * : (Village) Y level the piece was moved to in order to place it on the surface, or -1 if it hasn't been moved yet.
 * : (Village "ViF" and "ViDF") Crop in the farm plot.
 * : Id of the block
 * : List of block state properties, with [name] being the name of the block state property
 * : value of the property
 * : (Village "ViF" and "ViDF") Crop in the farm plot.
 * : Id of the block
 * : List of block state properties, with [name] being the name of the block state property
 * : value of the property
 * : (Village "ViDF") Crop in the farm plot.
 * : Id of the block
 * : List of block state properties, with [name] being the name of the block state property
 * : value of the property
 * : (Village "ViDF") Crop in the farm plot.
 * : Id of the block
 * : List of block state properties, with [name] being the name of the block state property
 * : value of the property
 * : 1 or 0 (true/false) - (Village "ViSH") Whether the house has a ladder to the roof and fencing.
 * : (Village "ViSmH") Table: 0 is no table, 1 and 2 place it on either side of the hut.
 * : (Village "ViSmH") Hut roof type.
 * : (Village "ViSR") Length of the road piece.
 * : value of the property
 * : (Village "ViF" and "ViDF") Crop in the farm plot.
 * : Id of the block
 * : List of block state properties, with [name] being the name of the block state property
 * : value of the property
 * : (Village "ViDF") Crop in the farm plot.
 * : Id of the block
 * : List of block state properties, with [name] being the name of the block state property
 * : value of the property
 * : (Village "ViDF") Crop in the farm plot.
 * : Id of the block
 * : List of block state properties, with [name] being the name of the block state property
 * : value of the property
 * : 1 or 0 (true/false) - (Village "ViSH") Whether the house has a ladder to the roof and fencing.
 * : (Village "ViSmH") Table: 0 is no table, 1 and 2 place it on either side of the hut.
 * : (Village "ViSmH") Hut roof type.
 * : (Village "ViSR") Length of the road piece.

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(<abbr title="The Data byte array, 4 bits per block">Data, BlockPos); byte <abbr title="The block light for the block">Blocklight = Nibble4(<abbr title="The BlockLight byte array, 4 bits per block">BlockLight, BlockPos); byte <abbr title="The sky light for the block">Skylight = Nibble4(<abbr title="The SkyLight byte array, 4 bits per block">SkyLight, BlockPos);

Entity format
Every entity is an unnamed contained in the Entities list of a chunk file. The sole exception is the Player entity, stored in level.dat, or in .dat files on servers. All entities share this base:
 * Entity data

Mobs
Mobs are a subclass of Entity with additional tags to store their health, attacking/damaged state, potion effects, and more depending on the mob. Players are a subclass of Mob.

Projectiles
Projectiles are a subclass of Entity and have very obscure tags such as X,Y,Z coordinate tags despite Entity Pos tag, inTile despite inGround, and shake despite most projectiles not being arrows. While all projectiles share tags, they are all independently implemented through  and.

Items and XPOrbs
Items and XPOrbs are a subclass of Entity.

Vehicles
Vehicles are subclasses of Entity.

Dynamic tiles
Dynamic tiles are a subclass of Entity and are used to simulate realistically moving blocks.

Other
Other entity types that are a subclass of Entity but do not fit into any of the above categories.

Block entity format
A block entity (not related to entity) is used by Minecraft to store information about a block that can't be stored in the four bits of block data the block has. Block entities were called "tile entities" until the 1.8 snapshots and that term is still used in some command usage.

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.


 * A Tile Tick

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.

Chunkdaten Format de tronçon Chunkフォーマット 청크 구성 Segment formaat 区块格式