Chunk format

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

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 32x32 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 16x16x16 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.

NBT Structure
Chunks are stored in NBT format, with this structure:
 * The root tag.
 * : Chunk data.
 * : X position of the chunk.
 * : Z position of the chunk.
 * : Tick when the chunk was last saved.
 * : 1 or not present (true/false) indicate whether the terrain in this chunk was populated with special things. (Ores, special blocks, trees, dungeons, flowers, waterfalls, etc.) If set to zero then Minecraft will regenerate these features in the blocks that already exist.
 * : 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.
 * : 1024 bytes(256 TAG_Int) of heightmap data. 16 x 16. Each byte records the lowest level in each column where the light from the sky is at full strength. Speeds computing of the SkyLight. Note: This array's indexes are ordered ZX whereas the other array indexes are ordered XZ or YZX.
 * : List of Compound tags, each tag is a sub-chunk of sorts.
 * : 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.
 * : 4096 bytes of block IDs defining the terrain. 8 bits per block, plus the bits from the below Add tag. 3D order YZX.
 * : May not exist. 2048 bytes of additional block ID data. The value to add to (combine with) the above block ID to form the true block ID in the range 0 to 4095. 4 bits per block. 3D order YZX. Combining is done by shifting this value to the left 8 bits and then adding it to the block ID from above.
 * : 2048 bytes of block data additionally defining parts of the terrain. 4 bits per block. 3D order YZX.
 * : 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. 3D order YZX.
 * : 2048 bytes recording the amount of sun or moonlight hitting each block. Makes day/night transitions smoother compared to recomputing per level change. 4 bits per block. 3D order YZX.
 * : 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 Byte tags.
 * : Each TAG_Compound in this list defines a tile entity in the chunk. See Tile Entity Format below. If this list is empty it will be a list of Byte tags.
 * : May not exist. 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, falling sand or water, and other activity. See Tile Tick Format below. This tag may not exist.

Block Format
The information in this section may be incorrect; valid information is in the works.

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

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/moonlight is reaching the block - these values do not change when the light level from the sky changes; these values act as a sort of percentage.

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 TAG_Compound 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
 * : Entity ID. This tag does not exist for the Player entity.
 * : 3 TAG_Doubles describing the current X,Y,Z position of the entity.
 * : 3 TAG_Doubles describing the current dX,dY,dZ velocity of the entity in meters per tick.
 * : Two TAG_Floats representing rotation in degrees.
 * The entity's rotation clockwise around the Y axis (called yaw). Due west is 0. Can have large values because it accumulates all of the entity's lateral rotation throughout the game.
 * The entity's declination from the horizon (called pitch). Horizontal is 0. Positive values look downward. Does not exceed positive or negative 90 degrees.
 * : Distance the entity has fallen. Larger values cause more damage when the entity lands.
 * : Number of ticks until the fire is put out. Negative values reflect how long the entity can stand in fire before burning.
 * : How much air the entity has, in ticks. Fills to a maximum of 200 in air, giving 10 seconds submerged before the entity starts to drown, and a total of up to 20 seconds before the entity dies. Decreases while underwater. If 0 while underwater, the entity loses 1 health per second.
 * : 1 or 0 (true/false) - true if the entity is touching the ground.

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.


 * Additional fields for Mobs:
 * : Amount of health the entity has. A value of 1 is half a heart.
 * : Number of ticks the mob's "invincibility shield" lasts after the mob was last struck.
 * : Number of ticks the mob turns red for after being hit.
 * : Number of ticks the mob has been dead for. Controls death animations.
 * : The list of potion effects on this mob. May not exist.
 * A potion effect
 * : The effect ID.
 * : The potion effect level. 0 is level 1.
 * : The number of ticks before the effect wears off.


 * HeartParticle.png Additional fields for mobs that can breed:
 * : Number of ticks until the mob loses its breeding hearts and stops searching for a mate.
 * : Represents the age of the mob in ticks; when negative, the mob is a baby. When 0 or above, the mob is an adult. When above 0, represents the number of ticks before this mob can breed again.


 * Additional fields for mobs that can be tamed by players:
 * : Name of the player that owns this mob. Empty string if no owner.
 * : 1 or 0 (true/false) - true if the mob is sitting.


 * Creeper has one additional field:
 * : 1 or 0 (true/false) - May not exist. True if the creeper is charged from being struck by lightning.


 * Enderman has two additional fields:
 * : Id of the block carried by the Enderman.
 * : Additional data about the block carried by the Enderman.


 * Ozelot has one additional field:
 * : The ID of the skin the tamed ocelot has.


 * Pig has one additional field:
 * : 1 or 0 (true/false) - true if there is a saddle on the pig.


 * PigZombie has one additional field:
 * : Anger level. Determines the aggressivity of the creature towards players.


 * Sheep has two additional fields:
 * : 1 or 0 (true/false) - true if the sheep has been shorn.
 * : 0 to 15 - see wool data values for a mapping to colors.


 * Slime and LavaSlime have one additional field:
 * : The size of the slime.


 * Wolf has one additional field:
 * : 1 or 0 (true/false) - true if the wolf is angry.


 * Villagerhead.png Villager has 3 additional fields:
 * : The ID of the texture used for this villager. This also influences trading options.
 * : Unknown, but starts at 0 and increases when trading for diamonds.
 * : May not exist.
 * : List of trade options.
 * A trade option.
 * : The number of times this trade has been used.
 * : The first 'cost' item.
 * Same as an Item's structure, but without the Slot tag.
 * : May not exist. The second 'cost' item.
 * Same as an Item's structure, but without the Slot tag.
 * : The item being sold for each set of cost items.
 * Same as an Item's structure, but without the Slot tag.

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.


 * Additional fields for Projectiles:
 * : X coordinate of the item's position in the chunk.
 * : Y coordinate of the item's position in the chunk.
 * : Z coordinate of the item's position in the chunk.
 * : Unknown.
 * : The "shake" when arrows hit a block.
 * : 1 or 0 (true/false) - If the Projectile is in the ground or hit the ground already (For arrow pickup; you cannot pickup arrows in the air)


 * Additional fields for Arrow:
 * : Unknown.
 * : Unknown, not a boolean value. Affects whether the arrow can be picked up (e.g. fired in survival, fired in creative, fired from infinity bow, fired from skeleton, etc...)
 * : Unknown how this affects actual damage inflicted by the arrow. May not be a whole number.

Items
Items are a subclass of Entity.


 * Additional fields for items:
 * : The health of the item, which starts at 5. Items take damage from fire, lava, and explosions. The item is destroyed when its health reaches 0.
 * : The number of ticks the item has been "untouched". After 6000 ticks (5 minutes ) the item is destroyed.


 * Additional fields for Item:
 * : The inventory item, without the Slot tag.
 * See Item Format.


 * Additional field for XPOrb:
 * : The amount of experience the orb gives when picked up.

Vehicles
Vehicles are subclasses of Entity.


 * Additional fields for Minecart:
 * : The type of the cart: 0 - empty, 1 - with a chest, 2 - with a furnace.


 * For a minecart with a chest there is one additional field:
 * : List of items.
 * An item, including the Slot tag. Slots are numbered 0 to 26.
 * See Item Format


 * For a minecart with a furnace there are three additional fields:
 * : Force along X axis, used for smooth acceleration/deceleration.
 * : Force along Z axis, used for smooth acceleration/deceleration.
 * : The number of ticks until the minecart runs out of fuel.

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


 * Additional fields for PrimedTnt
 * : Ticks until explosion.


 * Additional fields for FallingSand:
 * : Block ID. Not limited to only sand, gravel, or dragon eggs.
 * : Falling time in ticks.

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


 * Additional fields for Painting:
 * : Direction the painting faces: 0 is east, 1 is north, 2 is west, and 3 is south.
 * : The name of this Painting's art.
 * : X coordinate of the block the painting is hanging on.
 * : Y coordinate of the block the painting is hanging on.
 * : Z coordinate of the block the painting is hanging on.

Tile Entity Format
Tile Entities (not related to Entities) are used by Minecraft to store information about blocks that can't be stored in the 4-bits of block data the block has.

All tile entities share this base:
 * Tile entity data
 * : Tile entity ID
 * : X coordinate of the Tile Entity.
 * : Y coordinate of the Tile Entity.
 * : Z coordinate of the Tile Entity.

The original maximum burning time for the current fuel isn't stored, thus the current time left is assumed to be the maximum when this Tile Entity is loaded into memory.
 * Additional fields for Furnace:
 * : Number of ticks left before the current fuel runs out.
 * : Number of ticks the item has been smelting for. The item finishes smelting when this value reaches 200 (10 seconds). Is reset to 0 if BurnTime reaches 0.
 * : List of items in the furnace slots. Each item is a TAG_Compound as described in Item Format, but without the Slot tag.
 * 0: The item(s) being smeted.
 * 1: The item(s) to use as the next fuel source.
 * 2: The item(s) in the result slot.

Only the first 16 characters of each line are read, the rest are discarded.
 * Additional fields for Sign:
 * : First row of text.
 * : Second row of text.
 * : Third row of text.
 * : Fourth row of text.


 * Additional fields for MobSpawner:
 * : The Entity ID of the mob. Only Mob Entity IDs will work.
 * : How many mobs to spawn each time. (Has no effect unless MinSpawnDelay is also given.)
 * : The tags to replace the default tags; any of the Entity or Mob tags may be used, including the Pos tag.
 * : Ticks until next spawn.
 * : The minimum random delay for the next spawn delay. (If this field is given, MaxSpawnDelay and SpawnCount must also be given.)
 * : The maximum random delay for the next spawn delay. Warning: Setting this value to 0 crashes Minecraft. Set to at least 1. (Has no effect unless MinSpawnDelay is also given.)

Double chests are simply two Chest tile entities next to each other.
 * Additional fields for Chest:
 * : List of items in the chest. Each item is a TAG_Compound as described in Item Format, including the Slot tag. Chest slots are numbered 0-26 with 0 in the top left corner.


 * Additional fields for Music:
 * : Pitch (number of right-clicks).


 * Additional fields for Trap:
 * : List of items in the dispenser, each item includes the Slot tag. Slots are numbered 0-8.


 * Additional fields for RecordPlayer:
 * : Record currently playing. 0 is no record. Otherwise, it is the item ID of the record (e.g. 2261 for the "mall" record). Other IDs can be used to make other items or blocks pop out with a data value of 0.


 * Additional fields for Piston:
 * : Block_IDs of the block being moved.
 * : Data value of the block being moved.
 * : Direction in which the block will be pushed.
 * : How far the block has been moved.
 * : 1 or 0 (true/false) - true if the block is being pushed.


 * Additional fields for Cauldron:
 * : List of items in the brewing stand. Each item is a TAG_Compound as described in Item Format, including the Slot tag. The slots are numbered 0 to 3.
 * : The number of ticks the potions have been brewing for.

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
 * : The ID of the block; used to activate the correct block update procedure.
 * : The number of ticks until processing should occur. May be negative when processing is overdue.
 * : X position
 * : Y position
 * : Z position