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.
 * : 1 or 0 (true/false) - If true, the server/client has already calculated lighting values for this chunk after generation.
 * : 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.
 * : Currently always saved as 1 and not actually loaded by the game. Likely a chunk version tag.
 * : 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.
 * : 1024 bytes(256 TAG_Int) of heightmap data. 16 × 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.
 * : 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.
 * : 4096 bytes of block IDs defining the terrain. 8 bits per block, plus the bits from the below Add tag.
 * : 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. 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.
 * : 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.
 * : 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 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 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

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: id Pos Motion Rotation FallDistance Fire Air OnGround Dimension Invulnerable PortalCooldown UUIDMost UUIDLeast UUID CustomName CustomNameVisible Silent Riding CommandStats SuccessCountObjective SuccessCountName AffectedBlocksObjective AffectedBlocksName AffectedEntitiesObjective AffectedEntitiesName AffectedItemsObjective AffectedItemsName QueryResultObjective QueryResultName

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.

{| class="wikitable" style="float:right;margin-right:0" ! colspan="2" | Mob Entities ! Entity ID ! Name
 * Bat
 * Bat
 * Blaze
 * Blaze
 * CaveSpider
 * Cave Spider
 * Chicken
 * Chicken
 * Cow
 * Cow
 * Creeper
 * Creeper
 * EnderDragon
 * Ender Dragon
 * Enderman
 * Enderman
 * Endermite
 * Endermite
 * Ghast
 * Ghast
 * Giant
 * Giant
 * Guardian
 * Guardian
 * EntityHorse
 * Horse
 * LavaSlime
 * Magma Cube
 * MushroomCow
 * Mooshroom
 * Ozelot
 * Ocelot
 * Pig
 * Pig
 * PigZombie
 * Zombie Pigman
 * Rabbit
 * Rabbit
 * Sheep
 * Sheep
 * Shulker
 * Shulker
 * ShulkerBullet
 * Shulker Bullet
 * Silverfish
 * Silverfish
 * Skeleton
 * Skeleton Wither Skeleton
 * Slime
 * Slime
 * SnowMan
 * Snow Golem
 * Spider
 * Spider
 * Squid
 * Squid
 * Villager
 * Villager
 * VillagerGolem
 * Iron Golem
 * Witch
 * Witch
 * WitherBoss
 * Wither
 * Wolf
 * Wolf
 * Zombie
 * Zombie Zombie Villager
 * colspan="2" |  to containers.
 * Item IDs are no longer used when specifying NBT data.
 * Added  to , using the alphabetical ID format.}}
 * Skeleton Wither Skeleton
 * Slime
 * Slime
 * SnowMan
 * Snow Golem
 * Spider
 * Spider
 * Squid
 * Squid
 * Villager
 * Villager
 * VillagerGolem
 * Iron Golem
 * Witch
 * Witch
 * WitherBoss
 * Wither
 * Wolf
 * Wolf
 * Zombie
 * Zombie Zombie Villager
 * colspan="2" |  to containers.
 * Item IDs are no longer used when specifying NBT data.
 * Added  to , using the alphabetical ID format.}}
 * Wither
 * Wolf
 * Wolf
 * Zombie
 * Zombie Zombie Villager
 * colspan="2" |  to containers.
 * Item IDs are no longer used when specifying NBT data.
 * Added  to , using the alphabetical ID format.}}
 * colspan="2" |  to containers.
 * Item IDs are no longer used when specifying NBT data.
 * Added  to , using the alphabetical ID format.}}