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
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.
 * : Unknown usage; entities are only saved in the region files for the dimension they are in. -1 for The Nether, 0 for The Overworld, and 1 for The End.
 * : 1 or 0 (true/false) - true if the entity should not take damage.
 * : The number of ticks before which the entity may be teleported back through a portal of any kind. Initially starts at 900 ticks (45 seconds) and counts down.

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.


 * Mobs have these additional fields:
 * : 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.
 * : 1 or 0 (true/false) - true if this effect is provided by a Beacon and therefore should be less intrusive on screen.
 * : The list of compound tags of the equipment the mob has. Each compound tag in the list is an Item without the slot tag. All 5 entries will always exist (even for players) but may be empty compound tags to indicate no item.
 * 0: The item being held in the mob's hand.
 * 1: Armor (Feet)
 * 2: Armor (Legs)
 * 3: Armor (Chest)
 * 4: Armor (Head)
 * : List of float values from 0 to 1 representing the chance for a carried item to drop. By default these are all 0.05, but they get set to 1 if the mob picks up an item.
 * 0: Chance to drop the item being carried.
 * 1: Chance for the armor. (Feet)
 * 2: Chance for the armor. (Legs)
 * 3: Chance for the armor. (Chest)
 * 4: Chance for the armor. (Head)
 * : 1 or 0 (true/false) - true if the mob can pick up loot (wear armor it picks up, use weapons it picks up).
 * : 1 or 0 (true/false) - true if the mob must not despawn naturally.


 * 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.


 * Bat has these additional fields:
 * : 1 when hanging upside-down from a block, 0 when flying.


 * Creeper has these additional fields:
 * : 1 or 0 (true/false) - May not exist. True if the creeper is charged from being struck by lightning.
 * : The radius of the explosion itself, default 3.
 * : The number of ticks before the creeper will explode (does not affect creepers that fall and explode upon impacting their victim).


 * Enderman has these additional fields:
 * : ID of the block carried by the Enderman.
 * : Additional data about the block carried by the Enderman.


 * Ozelot has these additional fields:
 * : The ID of the skin the tamed ocelot has.


 * LavaSlime has these additional fields:
 * All fields from Slime


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


 * PigZombie has these additional fields:
 * All fields from Zombie
 * : Anger level. Determines the aggressivity of the creature towards players.


 * Sheep has these 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.


 * Skeleton has these additional fields:
 * : 1 or 0 (true/false) - true if the skeleton is a Wither skeleton.


 * Slime has these additional fields:
 * : The size of the slime.


 * WitherBoss has these additional fields:
 * : The number of ticks of invulnerability left after being initially created.


 * Wolf has these additional fields:
 * : 1 or 0 (true/false) - true if the wolf is angry.
 * : The dye color of this tamed wolf's collar.


 * Villagerhead.png Villager has these 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.
 * : May not exist.
 * : List of trade options.
 * A trade option.
 * : The maximum number of times this trade can be used before it is disabled.
 * : The number of times this trade has been used. The trade becomes disabled when this is greater or equal to maxUses.
 * : 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.


 * VillagerGolem has these additional fields:
 * : 1 or 0 (true/false) - true if this golem was created by a player.


 * Zombie has these additional fields:
 * : 1 or 0 (true/false) - true if this is an infected villager.
 * : 1 or 0 (true/false) - true if this infected villager is a baby.
 * : -1 when not being converted back to a villager, positive for the number of ticks until conversion back into a villager. The regeneration effect will parallel this.

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.
 * Projectiles have these additional fields:
 * : 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.
 * : ID of tile projectile is in.
 * : 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)


 * Arrow has these additional fields:
 * : Metadata of tile arrow is in.
 * : 0 = cannot be picked up by players. 1 = can be picked up by players in survival or creative. 2 = can only be picked up by players in creative.
 * : Unknown how this affects actual damage inflicted by the arrow. May not be a whole number. 2.0 for normal arrows, and increased 0.5 per level of Power enchantment on the firing bow. If the Power enchantment is present, an additional 0.5 is added on (so Power I gives a bonus of 1.0, while Power II gives 1.5).


 * Fireball, SmallFireball, and WitherSkull have these additional fields:
 * : List of 3 floats.


 * ThrownEnderpearl has these additional fields:
 * : The name of the player this ender pearl will teleport upon impact.


 * ThrownPotion has these additional fields:
 * : The item that was thrown, without the slot tag.
 * See Item format. tag -> CustomPotionEffects is stored the same way.
 * : If the Potion tag does not exist, this value is used as the damagevalue of the thrown potion.

Items
Items are a subclass of Entity.
 * Items have these additional fields:
 * : 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.


 * Item has these additional fields:
 * : The inventory item, without the Slot tag.
 * See Item Format.


 * XPOrb has these additional fields:
 * : The amount of experience the orb gives when picked up.

Vehicles
Vehicles are subclasses of Entity.
 * Minecart has these additional fields:
 * : The type of the cart: 0 - empty, 1 - with a chest, 2 - with a furnace.


 * Storage Minecarts have these additional fields:
 * : List of items.
 * An item, including the Slot tag. Slots are numbered 0 to 26.
 * See Item Format


 * Furnace Minecarts have these 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.
 * PrimedTnt has these additional fields:
 * : Ticks until explosion.


 * FallingSand has these additional fields:
 * : Block ID. Not limited to only sand, gravel, dragon eggs, or anvils.
 * : The data value for the block. (This gets weird with Anvils and needs further testing - values as high as 9 have been observed).
 * : The number of ticks the block has been moving.
 * : 1 or 0 (true/false) - true if the block should drop an item that can be picked up when it breaks.
 * : 1 or 0 (true/false) - true if the block should hurt entities it falls on.
 * : The maximum number of hitpoints of damage to inflict on entities that intersect this FallingSand. Anvils default to 20 (10 hearts).
 * : Multiplied by the FallDistance to calculate the amount of damage to inflict.

Other
Other entity types that are a subclass of Entity but do not fit into any of the above categories.
 * ItemFrame has these additional fields:
 * : The X coordinate within the chunk.
 * : The Y coordinate within the chunk.
 * : The Z coordinate within the chunk.
 * : Same as Direction.
 * : Same as Dir.
 * : The item, without the slot tag. If the item frame is empty, this tag does not exist.
 * See Item Structure.
 * : The chance the item will drop when the item frame breaks. 1.0 by default.
 * : The number of times the item has been rotated 90 degrees clockwise.


 * Painting has these additional fields:
 * : 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.


 * Beacon has these additional fields:
 * : The number of levels available from the pyramid.
 * : The primary power selected, see Potion effects for IDs. 0 means none.
 * : The secondary power selected, see Potion effects for IDs. 0 means none.


 * Cauldron has these additional fields:
 * : 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.

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


 * Control has these additional fields:
 * : The command to issue to the server.


 * Furnace has these additional fields:
 * : 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 using the Slot tag to describe its place in the furnace.
 * Slot 0: The item(s) being smelted.
 * Slot 1: The item(s) to use as the next fuel source.
 * Slot 2: The item(s) in the result slot. 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.


 * MobSpawner has these additional fields:
 * : The Entity ID. Both Mob Entity IDs and other Entity IDs will work. Purpose may have changed as of snapshot 12w49a.
 * : How many mobs to spawn each time.
 * : The radius around which the spawner attempts to place mobs randomly. The spawn area is square, includes the block the spawner is in, and is centred around the spawner's x,z coordinates - not the spawner itself.
 * : The tags to replace the default tags; any of the Entity or Mob tags may be used, including the Pos tag. Purpose may have changed as of snapshot 12w49a.
 * : Unknown.
 * Unknown.
 * : Unknown.
 * : Unknown.
 * : Unknown.
 * : Ticks until next spawn.
 * : The minimum random delay for the next spawn delay.
 * : The maximum random delay for the next spawn delay. Warning: Setting this value to 0 crashes Minecraft. Set to at least 1.
 * : Overrides the maximum number of nearby (within a box of spawnrange*2+1 x spawnrange*2+1 x spawnrange+1 centred around the spawner block) entities whose IDs match this spawner's entity ID.
 * : Overrides the block radius of the sphere of activation by players for this spawner.
 * : Unknown.
 * : Unknown.
 * : Unknown.
 * : Unknown.
 * : Unknown.


 * Music has these additional fields:
 * : Pitch (number of right-clicks).


 * Piston has these additional fields:
 * : 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.


 * RecordPlayer has these additional fields:
 * : 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. This is always overridden by the ID in RecordItem.
 * : The item, without the Slot tag.
 * See Item Format.


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


 * Skull has these additional fields:
 * : The type of the skull, similar to the Item IDs. (See Data values)
 * : Name of the player this is a skull of.
 * : The orientation, similar to signs. (See Data values)


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

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