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" | . Unused values lead to invisible horses.
 *  (deprecated) : Contains the name of the player that tamed the horse. Has no effect on behavior.
 * : Contains the UUID of the player that tamed the horse. Has no effect on behavior.
 * : List of items. Only exists if ChestedHorse is true.
 * An item, including the Slot tag. Slots are numbered 2 to 16 for donkeys and mules, and none exist for all other horses.
 * See Item Format
 * : The armor item worn by this horse. May not exist.
 * See Item Format
 * : The saddle item worn by this horse. May not exist.
 * See Item Format
 * :  (removed as of 13w21a)  Armor type. 0 = none, 1 = iron, 2= gold, 3= diamond. Other values lead to loading of random textures.
 * :  (removed as of 13w21a snapshot and added again at 1.6.1 release)  1 or 0 (true/false) - true if there is a saddle on the horse. ''
 * : 1 or 0 (true/false) - true if the horse is a trapped skeleton horse. Does not affect horse type.
 * : Incremented each tick when SkeletonTrap is set to 1. The horse automatically despawns when it reaches 18000 (15 minutes).
 * Squid
 * Squid
 * Villager
 * Villager
 * VillagerGolem
 * Iron Golem
 * Witch
 * Witch
 * WitherBoss
 * Wither
 * Wolf
 * Wolf
 * Zombie
 * Zombie Zombie Villager
 * colspan="2" | . Unused values lead to invisible horses.
 *  (deprecated) : Contains the name of the player that tamed the horse. Has no effect on behavior.
 * : Contains the UUID of the player that tamed the horse. Has no effect on behavior.
 * : List of items. Only exists if ChestedHorse is true.
 * An item, including the Slot tag. Slots are numbered 2 to 16 for donkeys and mules, and none exist for all other horses.
 * See Item Format
 * : The armor item worn by this horse. May not exist.
 * See Item Format
 * : The saddle item worn by this horse. May not exist.
 * See Item Format
 * :  (removed as of 13w21a)  Armor type. 0 = none, 1 = iron, 2= gold, 3= diamond. Other values lead to loading of random textures.
 * :  (removed as of 13w21a snapshot and added again at 1.6.1 release)  1 or 0 (true/false) - true if there is a saddle on the horse. ''
 * : 1 or 0 (true/false) - true if the horse is a trapped skeleton horse. Does not affect horse type.
 * : Incremented each tick when SkeletonTrap is set to 1. The horse automatically despawns when it reaches 18000 (15 minutes).
 * See Item Format
 * : The saddle item worn by this horse. May not exist.
 * See Item Format
 * :  (removed as of 13w21a)  Armor type. 0 = none, 1 = iron, 2= gold, 3= diamond. Other values lead to loading of random textures.
 * :  (removed as of 13w21a snapshot and added again at 1.6.1 release)  1 or 0 (true/false) - true if there is a saddle on the horse. ''
 * : 1 or 0 (true/false) - true if the horse is a trapped skeleton horse. Does not affect horse type.
 * : Incremented each tick when SkeletonTrap is set to 1. The horse automatically despawns when it reaches 18000 (15 minutes).

Ghast

 * Ghast has these additional fields:
 * : The radius of the explosion created by the fireballs this ghast fires. Default value of 1.

Guardian

 * Guardian has these additional fields:
 * : 1 or 0 (true/false) - true if the Guardian is an Elder Guardian.

Ozelot

 * Ozelot has these additional fields:
 * : The ID of the skin the ocelot has. 0 is wild ocelot, 1 is tuxedo, 2 is tabby and 3 is siamese. Does not determine an ocelot's behavior: it will be wild unless its Owner string is not empty, meaning wild ocelots can look like cats and vice versa.

Pig

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

Rabbit

 * Rabbit has these additional fields:
 * : Determines the skin of the rabbit. Also determines if rabbit should be hostile. 0=Brown, 1=White, 2=Black, 3=Black & White, 4=Gold, 5=Salt & Pepper, 99=Killer Bunny.
 * : Formerly used for the ticks until the rabbit will "eat" planted carrots. (?) Depletes every tick until it reaches 0. Was set to a certain value upon eating planted carrots. (?)

Sheep

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

Shulker

 * Shulker has these additional fields:
 * : Height of the head of the shulker.
 * : Direction of the block the shulker is attached to.
 * : Approximate X coordinate.
 * : Approximate Y coordinate.
 * : Approximate Z coordinate.

Skeleton

 * Skeleton has these additional fields:
 * : 0 for normal skeleton, 1 for wither skeleton.

LavaSlime

 * Slime and LavaSlime have these additional fields:
 * : The size of the slime. Note that this value is zero-based, so 0 is the smallest slime, 1 is the next larger, etc. The sizes that spawn naturally are 0, 1, and 3.
 * : 1 or 0 (true/false) - true if slime is touching the ground.

WitherBoss

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

Wolf

 * Wolf has these additional fields:
 * : 1 or 0 (true/false) - true if the wolf is angry.
 * : The dye color of this wolf's collar. Present even for wild wolves (but does not render); default value is 14.

Villager

 * Villagerhead.png Villager has these additional fields:
 * : The ID of the texture used for this villager. This also influences trading options.
 * : Currently unused. Increases by the number of emeralds traded to a villager any time they are traded.
 * : The ID of this villager's career. This also influences trading options and the villager's name in the GUI (if it does not have a CustomName). If 0, the next time offers are refreshed, the game will assign a new Career and reset CareerLevel to 1.
 * : The current level of this villager's trading options. Influences the trading options generated by the villager; if it is greater than their career's maximum level, no new offers are generated. Increments when a trade causes offers to be refreshed. If 0, the next trade to do this will assign a new Career and set CareerLevel to 1. Set to a high enough level and there will be no new trades to release (Career must be set to 1 or above).
 * : 1 or 0 (true/false) - true if the villager is willing to mate. Becomes true after certain trades (those which would cause offers to be refreshed), and false after mating.
 * : Each compound tag in this list is an item in the villagers inventory, up to a maximum of 8 slots. Items in two or more slots that can be stacked together will automatically be condensed into one slot. If there are more than 8 slots, the last slot will be removed until the total is 8. If there are 9 slots but two previous slots can be condensed, the last slot will be present after the two other slots are combined.
 * An item in the inventory, excluding the Slot tag.
 * See Item structure.
 * : Is generated when the trading menu is opened for the first time.
 * : List of trade options.
 * A trade option.
 * : 1 or 0 (true/false) - true if this trade will provide XP orb drops.
 * : The maximum number of times this trade can be used before it is disabled. Increases by a random amount from 2 to 12 when offers are refreshed.
 * : 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, without the Slot tag.
 * See Item structure.
 * : May not exist. The second 'cost' item, without the Slot tag.
 * See Item structure.
 * : The item being sold for each set of cost items, without the Slot tag.
 * See Item structure.

VillagerGolem

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

Zombie

 * Zombie has these additional fields:
 * : 1 or 0 (true/false) - true if this zombie is an infected villager. May be absent.
 * : 1 or 0 (true/false) - true if this zombie is a baby. May be absent.
 * : -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.
 * : 1 or 0 (true/false) - true if the zombie can break doors (default value is 0).
 * : Used to determine what profession the zombie is represented as, as well as what profession it will become when cured.

PigZombie

 * PigZombie has these additional fields:
 * All fields from Zombie
 * : Ticks until the Zombie Pigman becomes neutral. -32,768 to 0 for neutral Zombie Pigmen; 1 to 32,767 for angry Zombie Pigmen. Value depletes by one every tick if value is greater than 0. When the value turns from 1 to 0, the Zombie Pigman does not stop tracking the player until the player has exited the Zombie Pigman's detection radius. When hit by a player or when another Zombie Pigman within 32 blocks is hit by a player, the value is set to a random number between 400 and 800.
 * : The UUID of the last player that attacked the Zombie Pigman.

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


 * Projectiles except Fireball, SmallFireball, and WitherSkull have these additional fields:
 * : The "shake" when arrows hit a block.

Arrow

 * Arrow and SpectralArrow have 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.
 * : 1 or 0 (true/false) - If pickup is not used, and this is true, the arrow can be picked up by players.
 * : Increments each tick when an arrow is not moving; resets to 0 if it moves. When it ticks to 1200, the arrow despawns.
 * : Damage dealt by the arrow, in half-hearts. 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).
 * : 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)

TippedArrow
A tipped arrow has since 15w44b no own object anymore, instead an Arrow is a tipped arrow if it has one of the following fields:
 * See Potion Effects tag tag

SpectralArrow
SpectralArrow has this additional field:
 * : The time in ticks that the Glowing effect will last.

DragonFireball

 * Fireball, SmallFireball, WitherSkull, and DragonFireball have this additional required field:
 * : List of 3 doubles. Should be identical to Motion.


 * Fireball has this additional field:
 * : The power and size of the explosion created by the fireball upon impact. Default value 1.

Snowball

 * ThrownEgg, ThrownEnderpearl, ThrownExpBottle, ThrownPotion, and Snowball have this additional field:
 * : The name of the player this projectile was thrown by.


 * ThrownPotion has these additional fields:
 * : The item that was thrown, without the slot tag.
 * See Item format and Potion Effects tag tag. In, the ThrownPotion entity will render as this stored item, no matter the item.
 *  (deprecated) : If the Potion tag does not exist, this value is used as the damage value of the thrown potion.

Items and XPOrbs
Items and XPOrbs are a subclass of Entity.
 * Items and XPOrbs have these additional fields:
 * : The number of ticks the item has been "untouched". After 6000 ticks (5 minutes ) the item is destroyed. If set to -32768, the Age will not increase, thus the item will not automatically despawn.

Item

 * Item has these additional fields:
 * : The health of the item, which starts at 5. Items take damage from fire, lava, falling anvils, and explosions. The item is destroyed when its health reaches 0.
 * : The number of ticks the item cannot be picked up. Decreases by 1 per tick. If set to 32767, the PickupDelay will not decrease, thus the item can never be picked up.
 * : If not an empty string, only the named player will be able to pick up this item, until it is within 10 seconds of despawning. Used by the give command (and can be set in a summon command) to prevent the wrong player from picking up the spawned item entity.
 * : Set to the name of the player who dropped the item, if dropped by a player. Used by the "Diamonds to you!" achievement.
 * : The inventory item, without the Slot tag.
 * See Item Format.

XPOrb

 * XPOrb has these additional fields:
 * : Same properties as Health in Item. However, this value is stored as a byte in saved data, and read as a short but clipped to the range of a byte. As a result, its range is 0-255, always positive, and values exceeding 255 will overflow.
 * : The amount of experience the orb gives when picked up.

Vehicles
Vehicles are subclasses of Entity.

Boat

 * Boat has these additional fields:
 * : The wood type of the boat. See boat data values for valid types.


 * All types of Minecarts may have these additional optional fields:
 * : Optional. 1 or 0 (true/false) - whether to display the custom tile in this minecart.
 * : Optional. The ID of the custom block in the minecart.
 * : Optional. The Data value of the custom block in the minecart.
 * : Optional. The offset of the block displayed in the Minecart in pixels. Positive values move the block upwards, while negative values move it downwards. A value of 16 will move the block up by exactly one multiple of its height.

Minecart

 * Minecart  (deprecated since 13w02a)  had these additional fields:
 * : Type of the cart: 0 - empty, 1 - with a chest, 2 - with a furnace.
 * All fields from MinecartRideable, MinecartChest or MinecartFurnace depending on Type.

MinecartHopper

 * MinecartChest and MinecartHopper have these additional fields:
 * : List of items.
 * An item, including the Slot tag. Slots are numbered 0 to 26 for chests, and 0 to 4 for hoppers.
 * See Item Format

MinecartChest
to containers.
 * MinecartChest has these additional fields:
 * : Optional. Loot table to be used to fill the chest when it is next opened, or the items are otherwise interacted with.
 * : Optional. Seed for generating the loot table. 0 or omitted will use a random seed.
 * Item IDs are no longer used when specifying NBT data.
 * Added  to , using the alphabetical ID format.}}