Minecraft:Chunk format

Template:Update Minecraft:Chunks store the terrain and entities within a 16×384×16 area in the Minecraft:Overworld, and 16×256×16 in Minecraft:the Nether and Minecraft:the End by default. They also store precomputed lighting, heightmap data for Minecraft's performance, and other meta information.

NBT structure

Chunks are stored as tags in regional Minecraft Anvil files, which are named in the form Template:Code. They are stored in Minecraft:NBT format, with the following structure (updated for 1.18):

• Template:Nbt The root tag.
  • Template:Nbt: Version of the chunk NBT structure.
  • Template:Nbt: X position of the chunk (in absolute chunks from world Template:Cd origin, not relative to the region).
  • Template:Nbt: Z position of the chunk (in absolute chunks from world Template:Cd origin, not relative to the region).
  • Template:Nbt: Lowest Y section position in the chunk (e.g. Template:Cd in 1.18).
  • Template:NbtTemplate:Until/Template:NbtTemplate:Upcoming: The chunk's world generation status. The possible statuses, in generation order, are Template:Code, Template:Code, Template:Code, Template:Code, Template:Code, Template:Code, Template:Code, Template:Code, Template:Code, and Template:Code. All status except Template:Code are used for chunks called proto-chunks, in other words, for chunks with incomplete generation.
  • Template:Nbt: Tick when the chunk was last saved.
  • Template:Nbt: List of Template:Nbt, each tag is a section (also known as sub-chunk). All sections in the world's height are present in this list, even those who are empty (filled with air).
    • Template:Nbt An individual section.
      • Template:Nbt: The Y position of this section.
      • Template:Nbt
        • Template:Nbt: Set of different block states used in this particular section. The vanilla implementation never includes any unused entries upon writing, so this array will never contain more than 4096 entries, and the indices in the data array will be at most 12 bits long. However the vanilla implementation is also able to handle larger palettes when reading. This may be a list of compounds, or a list of strings if every block represents the default block state.
          • Template:Nbt A block
            • Template:Nbt: Block Minecraft:resource location
            • Template:Nbt: List of Minecraft:block state properties, with Template:Cd being the name of the block state property
              • Template:Nbt: The block state's name and its value.
            • Template:Nbt Block Minecraft:resource location. This entry may be used instead of the above if it represents the default block state of a block. (The name of this entry is an empty string.)
          • Template:Nbt Block Minecraft:resource location
        • Template:Nbt: A packed array of 4096 indices pointing to the palette, stored in an array of 64-bit integers (Template:Nbt).
          • If only one block state is present in the palette, this field is not required and the block fills the whole section.
          • All indices are the same length. This length is set to the minimum amount of bits required to represent the largest index in the palette, and then set to a minimum size of 4 bits. The indices are not packed across multiple elements of the array, meaning that if there is no more space in a given 64-bit integer for the whole next index, it starts instead at the first (lowest) bit of the next 64-bit integer. Different sections of a chunk can have different lengths for the indices.
      • Template:Nbt
        • Template:Nbt: Set of different biomes used in this particular section. The vanilla implementation never includes any unused entries upon writing, so this array will never contain more than 64 entries, and the indices in the data array will be at most 6 bits long. However the vanilla implementation is also able to handle larger palettes when reading.
          • Template:Nbt: Biome Minecraft:resource location
        • Template:Nbt: A packed array of 64Template:Until/4096Template:Upcoming indices pointing to the palette, stored in an array of 64-bit integers (Template:Nbt).
          • Biomes in a world are stored in cells of 4×4×4 blocks, and only store 64 individual entries. Biomes at the block level are smoothed based on the cells.Template:Info neededTemplate:Until
          • If only one biome is present in the palette, this field is not required and the biome fills the whole section.
          • All indices are the same length: the minimum amount of bits required to represent the largest index in the palette. These indices do not have a minimum size. As with block states, the indices are not packed across multiple elements of the array. Different sections of a chunk can have different lengths for the indices.
      • Template:Nbt: 2048 Template:Nbt stores the amount of block-emitted light in each block. Makes load times faster compared to recomputing at load time. Omitted if no light reaches this section of the chunk. Light level is stored as 4 bits per block, 2 blocks sharing a byte: starting at 0, even blocks take the first nibble, and odd blocks the second one.
      • Template:Nbt: 2048 Template:Nbt stores the maximum sky light that reaches each block, regardless of current time. If the sky light data for a section is omitted you should look at the light data of the section directly above it. Take the 16x16 layer at the bottom of that section and repeat that light data 16 times to recompute the data for the omitted section. If there is no section above the current one, you are at the top section of the chunk. The light data for this top section should be set as completely bright (0xF for each block). The format of how these levels is stored is the same as for BlockLight.
  • Template:Nbt: Each Template:Nbt in this list defines a block entity in the chunk.
    • See Minecraft:Block entity format.
  • Template:Nbt: Only for proto-chunks (not confirmed for 1.18 format).
    • Template:Nbt: A series of bits indicating whether a cave has been dug at a specific position, stored in a byte array.
    • Template:Nbt: A series of bits indicating whether an underwater cave has been dug at a specific position, stored in a byte array.
  • Template:Nbt: Several different Minecraft:heightmaps corresponding to 256 values compacted at 9 bits per value (lowest being 0, highest being 384, both values inclusive). The 9-bit values are stored in an array of 37 Template:Nbt, each containing 7 values (Template:Nbt = 64 bits, 7×9 = 63; the last bit is unused). In versions prior to 1.16 the heightmaps were stored in 36 Template:Nbt values, where the bits were arranged in an uninterrupted "stream" across all values, resulting in all 2304 bits being used. The 9-bit values are unsigned, and indicate the amount of blocks above the bottom of the world. This means that converting a world to 1.18 adds 64 to every value.
    • Template:Nbt
    • Template:Nbt
    • Template:Nbt
    • Template:Nbt
    • Template:Nbt
    • Template:Nbt
  • Template:Nbt: A List of 16 lists that store positions of light sources per chunk section as shorts, only for proto-chunks (not confirmed for 1.18 format).
  • Template:Nbt: A list of entities in the proto-chunks, used when generating. This list is not present for fully generated chunks and entities are moved to a separated region files once the chunk is generated; see Entity format for more details. Before Minecraft:20w45a, it contained all the entities in the chunk. In Minecraft:21w43a this was renamed from "Entities".
    • Template:Nbt: An entity.
  • Template:Nbt: A list of Template:Nbt
    • Each Template:Nbt in this list is an "active" liquid in this chunk waiting to be updated. See Tile Tick Format below.
  • Template:Nbt: A list of Template:Nbt
    • Each Template:Nbt in this list is an "active" block in this chunk waiting to be updated. These are used to save the state of redstone machines or falling sand, and other activity. See Tile Tick Format below.
  • Template:Nbt: 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.
  • Template:Nbt: This stores the heights to blend terrain to.
    • Template:Nbt List of 16 heights measured in doubles that correspond to the y values at 16 locations on the edge of the chunk. (Specifically highest sand, red sand, stone, grass block, podzol, mycelium, coarse dirt, dirt, terracotta, or snow block) Template:More info
      • Template:Nbt Section-relative 12 ~ 00's y value.
      • Template:Nbt Section-relative 08 ~ 00's y value.
      • Template:Nbt Section-relative 04 ~ 00's y value.
      • Template:Nbt Section-relative 00 ~ 00's y value.
      • Template:Nbt Section-relative 00 ~ 04's y value.
      • Template:Nbt Section-relative 00 ~ 08's y value.
      • Template:Nbt Section-relative 00 ~ 12's y value.
      • Template:Nbt Section-relative 00 ~ 15's y value.
      • Template:Nbt Section-relative 04 ~ 15's y value.
      • Template:Nbt Section-relative 08 ~ 15's y value.
      • Template:Nbt Section-relative 12 ~ 15's y value.
      • Template:Nbt Section-relative 15 ~ 15's y value.
      • Template:Nbt Section-relative 15 ~ 12's y value.
      • Template:Nbt Section-relative 15 ~ 08's y value.
      • Template:Nbt Section-relative 15 ~ 04's y value.
      • Template:Nbt Section-relative 15 ~ 00's y value.
    • Template:Nbt: This appears to be the lowest chunk section the chunk has. Template:More info
    • Template:Nbt: This appears to be the highest chunk section the chunk has. Template:More info
  • Template:Nbt: A List of 24 Template:Nbt that store the positions of blocks that need to receive an update when a proto-chunk turns into a full chunk, packed in Template:Nbt. Each list corresponds to specific section in the height of the chunk.
    • See ToBeTicked format below for a description of the coordinate packing format. A common use case for this to is make liquids flow after generating a source block, such as springs in caves.
  • Template:Nbt: Structure data in this chunk.
    • Template:Nbt: Coordinates of chunks that contain starts.
      • Template:Nbt: Each 64-bit number of this array represents a chunk coordinate (i.e. block coordinate / 16), with its X packed into the low (least significant) 32 bits and Z packed into the high (most significant) 32 bits.
    • Template:Nbt: Structures that are yet to be generated, stored by general type. Some parts of the structures may have already been generated. Completely generated structures are removed by setting their id to "Template:Cd" and removing all other tags.
      • Template:Nbt: Only the structures that can spawn in this dimension are stored, for example, EndCity is stored only in the end chunks.
        • Template:Nbt: List of structure pieces making up this structure, that were not generated yet. Absent if id is Template:Cd.
          • Template:Nbt Structure piece data. Template:Info needed
            • Template:Nbt: Bounding box of the structure piece. (Does not include the part of a village roof that can overhang the road.) Value is 6 ints: the minimum X, Y, and Z coordinates followed by the maximum X, Y, and Z coordinates.
            • Template:Nbt: The ocean temperature this ocean ruins is in. Valid values are WARM and COLD.
            • Template:Nbt: (Village "ViSmH") Hut roof type.Template:Verify
            • Template:Nbt: (Village "ViF" and "ViDF") Crop in the farm plot.Template:Verify
              • Template:Nbt: Block Minecraft:resource location
              • Template:Nbt: List of Minecraft:block state properties, with [name] being the name of the block state property
                • Template:Nbt: The block state name and its value.
            • Template:Nbt: (Village "ViF" and "ViDF")
              • separate object with the same format as Template:Nbt
            • Template:Nbt: (Village "ViDF")
              • separate object with the same format as Template:Nbt
            • Template:Nbt: (Village "ViDF")
              • separate object with the same format as Template:Nbt
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Fortress "NeSCLT" and "NeSCRT") Whether this fortress piece should contain a chest but hasn't had one generated yet. (Stronghold "SHCC") Whether this chest in this stronghold piece was placed. (Village "ViS") Whether the blacksmith chest has been generated.
            • Template:Nbt: (Mineshaft "MSCrossing") Indicates the "incoming" direction for the crossing.
            • Template:Nbt: (Temples and huts) Depth of the structure (X/Z).
            • Template:Nbt: (Mineshaft "MSRoom") List of exits from the room.
              • Template:Nbt: Bounding box of the exit.
            • Template:Nbt: (Stronghold) The type of door at the entry to this piece.
            • Template:Nbt: Appears to be some sort of measure of how far this piece is from the start.
            • Template:Nbt:
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Desert temple) Whether 1st chest was placed.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Desert temple) Whether 2nd chest was placed.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Desert temple) Whether 3rd chest was placed.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Desert temple) Whether 4th chest was placed.
            • Template:Nbt: (Temples and huts) Height of the structure (Y).
            • Template:Nbt: (Temples, huts and villages) Y level the structure was moved to in order to place it on the surface, or -1 if it hasn't been moved yet.Template:Verify
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Mineshaft "MSCorridor") Whether the corridor has a cave spider monster spawner.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Mineshaft "MSCorridor") Whether the corridor has rails.
            • Template:Nbt: Identifier for the structure piece. Typically a heavily abbreviated code rather than something human-readable. Template:Info needed
            • Template:Nbt: The integrity of this structure (only used by ocean ruins).
            • Template:Nbt:
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - If this ocean ruin is big.
            • Template:Nbt: (Village) List of junction points. Template:Info needed
              • Template:Nbt: The junctions coordinates:
                • Template:Nbt: X.
                • Template:Nbt: Y.
                • Template:Nbt: Z.
                • Template:Nbt: Change Y. Template:Info needed
                • Template:Nbt: One of Template:Cd.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Stronghold "SHS") Whether the corridor has an opening on the left.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Stronghold "SH5C") Whether the 5-way crossing has an exit on the upper level on the side with the upward staircase.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Stronghold "SH5C") Whether the 5-way crossing has an exit on the lower level on the side with the upward staircase.
            • Template:Nbt: (Village "ViSR") Length of the road piece.Template:Verify
            • Template:Nbt:
            • Template:Nbt:
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Fortress "NeMT") Whether this fortress piece should contain a blaze monster spawner but hasn't had one generated yet. (Stronghold "SHPR") Whether the silverfish monster spawner has been placed in this piece.
            • Template:Nbt:
            • Template:Nbt: (Mineshaft "MSCorridor") Corridor length.
            • Template:Nbt: Likely orientation of the structure piece.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Jungle temple) Whether the hidden chest was placed.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Jungle temple) Whether the main chest was placed.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Jungle temple) Whether the hallway arrow trap dispenser was placed.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Jungle temple) Whether the chest arrow trap dispenser was placed.
            • Template:Nbt:
              • Template:Nbt: The namespaced type of this element.
              • Template:Nbt: The resource location for this element.
              • Template:Nbt:
                • Template:Nbt:
              • Template:Nbt: Appears to be a namespaced location.
              • Template:Nbt:
            • Template:Nbt: The X coordinate origin of this village part.
            • Template:Nbt: The Y coordinate origin of this village part.
            • Template:Nbt: The Z coordinate origin of this village part.
            • Template:Nbt:
              • Template:Nbt:
              • Template:Nbt:
              • Template:Nbt:
              • Template:Nbt:
              • Template:Nbt:
              • Template:Nbt:
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Stronghold "SHS") Whether the corridor has an opening on the right.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Stronghold "SH5C") Whether the 5-way crossing has an exit on the upper level on the side with the downward staircase.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Stronghold "SH5C") Whether the 5-way crossing has an exit on the lower level on the side with the downward staircase.
            • Template:Nbt: Rotation of ocean ruins and shipwrecks. Valid values are COUNTERCLOCKWISE_90, NONE, CLOCKWISE_90, and CLOCKWISE_180.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Mineshaft "MSCorridor") Whether the corridor has cobwebs.
            • Template:Nbt: (Fortress "NeBEF") Random seed for the broken-bridge fortress piece.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Stronghold "SHSD") Whether the spiral staircase is the source of the Stronghold or was randomly generated.
            • Template:Nbt: (Stronghold "SHFC") Length of the corridor
            • Template:Nbt: (Village "ViSmH") Table: 0 is no table, 1 and 2 place it on either side of the hut.Template:Verify
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Stronghold "SHLi") Whether the library has an upper level.
            • Template:Nbt: The template of the ocean ruin or shipwreck that was used.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Village "ViSH") Whether the house has a ladder to the roof and fencing.Template:Verify
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Mineshaft "MSCrossing") Whether the crossing is two floors tall.
            • Template:Nbt: The X coordinate origin of this ocean ruin or shipwreck.
            • Template:Nbt: The Y coordinate origin of this ocean ruin or shipwreck.
            • Template:Nbt: The Z coordinate origin of this ocean ruin or shipwreck.
            • Template:Nbt: (Village) Village type: 0=plains, 1=desert, 2=savanna, 3=taiga.Template:Verify
            • Template:Nbt: (Stronghold "SHRC") Indicates whether the room contains a pillar with torches, a fountain, an upper level with a chest, or is just empty room.
            • Template:Nbt: (Village) Count of villagers spawned along with this piece.Template:Verify
            • Template:Nbt:
            • Template:Nbt: (Temples and huts) Width of the structure (X/Z).
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Witch hut) Whether the initial witch has been spawned for the hut.
            • Template:Nbt: 1 or 0 (Template:Cd/Template:Cd) - (Village) Whether this village generated as a zombie village.Template:Verify
        • Template:Nbt: Chunk X coordinate of the start of the structure. Absent if id is Template:Cd.
        • Template:Nbt: Chunk Z coordinate of the start of the structure. Absent if id is Template:Cd.
        • Template:Nbt: If there's no structure of this kind in this chunk, this value is "Template:Cd", else it's the structure name.
        • Template:Nbt: (Monument only) List of chunks that have had their piece of the structure created. Absent if id is Template:Cd.
          • Template:Nbt: A chunk.
            • Template:Nbt: The chunk's X position (chunk coordinates, not block coordinates).
            • Template:Nbt: The chunk's Z position.
        • Template:Nbt: Template:Info needed

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 upward, decreases downward
• Z increases South, decreases North

This means indices are ordered like in a book, with its top to the North, read from beneath and with words written backward: each letter is a different X-index, each line a Z-index, and each page a Y-index. In case of a flat 2D array, the Y-index is omitted, and the array reads like a single page.

Each section is a 16×16×16-block area, with up to 16 sections in a chunk : from 0 at the bottom, to 15 on top. Empty sections are not saved. Each section has a "Y" byte for its Y-index (0 to 15), a "Palette" list linking IDs to block states, and a "BlockStates" long array storing the IDs per block location, compressed by fitting multiple IDs inside each entry (see NBT_structure above for details on the compression). There might be an additional section at the top and or bottom of the world used to store light, so that light travels properly over and under the world limits.

The pseudo-code below shows how to access individual block information from a single section.

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; 
compound Block = Palette[change_array_element_size(BlockStates,Log2(length(Palette)))[BlockPos]];
string BlockName = Block.Name; 
compound BlockState = Block.Properties; 
byte Blocklight = Nibble4(BlockLight, BlockPos); 
byte Skylight = Nibble4(SkyLight, BlockPos);

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.

• Template:Nbt A Tile Tick <section begin="tile tick format" />
  • Template:Nbt: The ID of the block; used to activate the correct block update procedure.
  • Template:Nbt: If multiple tile ticks are scheduled for the same tick, tile ticks with lower p are processed first. If they also have the same p, the order is unknown.
  • Template:Nbt: The number of ticks until processing should occur. May be negative when processing is overdue.
  • Template:Nbt: X position
  • Template:Nbt: Y position
  • Template:Nbt: Z position <section end="tile tick format" />

ToBeTicked format

This Template:Nbt is always present, and contains 16 Template:Nbt, each representing one of the "sections" of the chunk. Those inside lists may contain Template:Nbt, each representing a packed coordinate relative to the section : The 4 most significant bits are always 0, then each group of 4 bits (or nibble) represents a section-relative coordinate, from 0 to 15. The order of sections in the list appear to be ordered from bottom to top, and the packing order of the coordinates is Template:Cd, where Template:Cd refers to the chunk section. When converting proto-chunks to full chunks, only coordinates that are stored in PostProcessing appear to receive a tick update, tick updates stored in Template:Cd are ignored. Template:Verify