Minecraft Wiki
Advertisement

Chunk File Format

Chunks files store the terrain and entities within a 16x16x128 area. They also store precomputed lighting and heightmap data for Minecraft's performance. The file names contain the Base36 of the chunk's position.

The Data, SkyLight, and BlockLight are arrays of 4-bit values. The low bits of the first byte of one of these corresponds to the first block in the Blocks array

NBT Structure

  • TAG_Compound("Level"): Chunk data.
    • TAG_Byte_Array("Blocks"): 32768 bytes of block IDs defining the terrain. 8 bits per block. See Block Format below for byte ordering.
    • TAG_Byte_Array("Data"): 16384 bytes of block data additionally defining parts of the terrain. 4 bits per block.
    • TAG_Byte_Array("SkyLight"): 16384 bytes recording the amount of sun or moonlight hitting each block. 4 bits per block. Makes day/night transitions smoother compared to recomputing per level change.
    • TAG_Byte_Array("BlockLight"): 16384 bytes recording the amount of block-emitted light in each block. 4 bits per block. Makes load times faster compared to recomputing at load time.
    • TAG_Byte_Array("HeightMap"): 256 bytes 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 Z,X whereas the other array indexes are ordered X,Z,Y.
    • TAG_List("Entities"): Each TAG_Compound in this list defines an entity in the chunk. See Entity Format below.
    • TAG_List("TileEntities"): Each TAG_Compound in this list defines a tile entity in the chunk. See Tile Entity Format below.
    • TAG_Long("LastUpdate"): Tick when the chunk was last saved.
    • TAG_Int("xPos"): X position of the chunk. Should match the file name.
    • TAG_Int("zPos"): Z position of the chunk. Should match the file name.
    • TAG_Byte("TerrainPopulated"): 1 or 0 (true/false) indicate whether the terrain in this chunk was populated with special things. (Ores, special blocks, trees, dungeons, flowers, waterfalls, etc.)

Block Format

Blocks are laid out in sets of vertical columns, with the rows going east-west through chunk, and columns going north-south. Blocks in each chunk are accessed via the following method:

unsigned char BlockID = Blocks[ y + ( z * ChunkSizeY(=128) + ( x * ChunkSizeY(=128) * ChunkSizeZ(=16) ) ) ];

The coordinate system is as follows:

  • X increases South, decreases North
  • Y increases upwards, decreases downwards
  • Z increases West, decreases East

The Data, BlockLight, and SkyLight arrays have four bits for each byte of the Blocks array. The least significant bits of the first byte of the Data, BlockLight, or SkyLight arrays correspond to the first byte of the Blocks array.

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.

All entities share this base:

    • TAG_Compound: Entity data
      • TAG_String("id"): Entity ID
      • TAG_List("Pos"): 3 TAG_Doubles describing the current X,Y,Z position of the entity.
      • TAG_List("Motion"): 3 TAG_Doubles describing the current dX,dY,dZ velocity of the entity. (Note: Falling into the Void appears to set this to ridiculously high speeds. 0,0,0 is no motion.)
      • TAG_List("Rotation"): Two TAG_Floats representing rotation in degrees.
        • TAG_Float[0]: 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.
        • TAG_Float[1]: The entity's declination from the horizon (called pitch). Horizontal is 0. Positive values look downward. Does not exceed positive or negative 90 degrees.
      • TAG_Float("FallDistance"): Distance the entity has fallen. Larger values cause more damage when the entity lands.
      • TAG_Short("Fire"): Number of ticks until the fire is put out. Negative values reflect how long the entity can stand in fire before burning.
      • TAG_Short("Air"): 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.
      • TAG_Byte("OnGround"): 1 if the entity is touching the ground.
      • TAG_String("World"): Unknown, but probably the world entity belongs to

SkeletonFace Mobs

Known Mob Entity ids: Mob, Monster, Creeper, Skeleton, Spider, Giant, Zombie, Slime, PigZombie, Ghast, Pig, Sheep, Cow, Chicken, Wolf, Squid

Additional fields for mobs:

  • TAG_Short("AttackTime"): Number of ticks the entity's "invincibility shield" is lasting after the entity was last struck.
  • TAG_Short("DeathTime"): Number of ticks the entity has been dead for. Controls death animations.
  • TAG_Short("Health"): Amount of health the entity has. Players and enemies normally have up to 20 health. Livestock has up to 10 health.
  • TAG_Short("HurtTime"): Unknown

PigFace Pig has one additional field:

  • TAG_Byte("Saddle"): 1 or 0 (true/false) - true if there is a saddle on the pig.

SheepFace Sheep has two additional fields:

  • TAG_Byte("Sheared"): 1 or 0 (true/false) - true if the sheep has been sheared.
  • TAG_Byte("Color"): 0 to 15 - see wool data values for a mapping to colors.

SlimeFace Slime has one additional field, and it can't be used as the Entity ID of a Monster Spawner:

  • TAG_Int("Size"): The size of the slime

WolfFace Wolf has three additional fields:

  • TAG_String("Owner"): Name of the player that owns this wolf. Empty string if no owner.
  • TAG_Byte("Sitting"): 1 or 0 (true/false) - true if the wolf is sitting.
  • TAG_Byte("Angry"): 1 or 0 (true/false) - true if the wolf is angry.

Stone Items

Known Item Entity ids: Item, Arrow, Snowball, Egg, Painting

Cobblestone Additional fields for Item:

  • TAG_Short("Health"): Unknown
  • TAG_Short("Age"): Unknown
  • TAG_Compound("Item"): Item data
    • TAG_Short("id"): Item or Block ID.
    • TAG_Short("Damage"): The amount of wear each item has suffered. 0 means undamaged. When the Damage exceeds the item's durability, it breaks and disappears. Only tools and armor accumulate damage normally.
    • TAG_Byte("Count"): Number of items stacked in this inventory slot. Any item can be stacked, including tools, armor, and vehicles. Range is 1-255. Values above 127 are not displayed in-game.

Arrow Snowball File:Egg2.png Additional fields for Arrow, Snowball and Egg:

  • TAG_Short("xTile"): X coordinate of the item's position in the chunk.
  • TAG_Short("yTile"): Y coordinate of the item's position in the chunk.
  • TAG_Short("zTile"): Z coordinate of the item's position in the chunk.
  • TAG_Byte("inTile"): Unknown
  • TAG_Byte("shake"): Unknown
  • TAG_Byte("inGround"): 1 or 0 (true/false) - Unknown

Painting Additional fields for Painting:

  • TAG_Byte("Dir"): Direction the painting faces: 0 is east, 1 is north, 2 is west, and 3 is south.
  • TAG_String("Motive"): The name of this Painting's art.
  • TAG_Int("TileX"): X coordinate of the block the painting is hanging on.
  • TAG_Int("TileY"): Y coordinate of the block the painting is hanging on.
  • TAG_Int("TileZ"): Z coordinate of the block the painting is hanging on.

File:Boat.png Vehicles

Known Vehicle Entity ids: Minecart, Boat

Minecart Additional fields for Minecart:

  • TAG_Byte("Type"): The type of the cart: 0 - empty, 1 - with a chest, 2 - with a furnace.

File:Powered Minecart.png For a minecart with a furnace there are three additional fields:

  • TAG_Double("PushX"): Unknown
  • TAG_Double("PushZ"): Unknown
  • TAG_Short("Fuel"): Unknown, but probably number of ticks until fuel runs out.[assumption]

File:Storage Minecart.png For a minecart with a chest there is one additional field:

  • TAG_List("Items"): List of items in the slots, same as for a chest.

Dynamic Tiles

Known Dynamic Tile Entity ids: PrimedTnt, FallingSand

TNT Additional fields for PrimedTnt

  • TAG_Byte("Fuse"): Ticks until explosion.

Sand Additional fields for FallingSand:

Tile Entity Format

Known TileEntity ids: Furnace, Sign, MonsterSpawner, Chest, Music, Trap

All tile entities share this base:

  • TAG_Compound: Tile entity data
    • TAG_String("id"): Tile entity ID
    • TAG_Int("x"):
    • TAG_Int("y"):
    • TAG_Int("z"): Local coordinates of the TileEntity.

A tile entity has additional fields depending on its id:


Furnace Furnace

  • TAG_Short("BurnTime"): Fuel time
  • TAG_Short("CookTime"): Cooking time
  • TAG_List("Items"): List of items in the slots


File:Sign.png Sign

  • TAG_String("Text1"): First row of text
  • TAG_String("Text2"): Second row of text
  • TAG_String("Text3"): Third row of text
  • TAG_String("Text4"): Fourth row of text


Monster Spawner Monster Spawner

  • TAG_String("EntityId"): The id of the mob.
  • TAG_Short("Delay"): Ticks until next spawn.


Chest Chest

  • TAG_List("Items"): List of items in the chest. Each item is a TAG_Compound identical to the ones in the Inventory list. Chest slots are numbered 0-26 with 0 in the top left corner.


Note Block Music

  • TAG_Byte("note"): Pitch (number of right-clicks)

Dispenser Trap

  • TAG_List("Items"): List of items in the dispenser, numbered 0-8.

Piston

Note: This tile-entity is a moving block (block 36), rather than the piston itself (blocks 29, 33, 34).

  • TAG_Byte("extending"):
  • TAG_Int("blockData"): metadata of moved block.
  • TAG_Int("blockId"): Id of moved block.
  • TAG_Int("facing"):
  • TAG_Float("progress"):
Advertisement