Chunk Format

Revision as of 20:37, 15 March 2016 by Fenhl (talk | contribs) (→‎Implementations: added outdated notice)
Jump to navigation Jump to search

This article describes the Chunk Section format used in the Chunk Data packet (Play, 0x20, clientbound).


  • Chunk Section: a 16×16×16 area, sometimes also called chunk.
  • Chunk Column: 16 chunks aligned vertically (totalling 16×256×16).


A Chunk Section is defined in terms of other data types. A Chunk Section consists of the following fields:

Field Name Field Type Notes
Bits Per Block Unsigned Byte How many bits per block in Data Array. If 0, the Palette Length and Palette fields are omitted and the global palette (with 13 bits per block) is used.
Palette Length Optional VarInt Length of the following array
Palette Optional Array of VarInt Mapping of block state IDs in the global palette to indices of this array
Data Array Length VarInt Number of bytes in the following array, divided by 8 (given as such because Notchian implements Data Array as an Array of Long)
Data Array Byte Array List of 4096 indices pointing to state IDs in the Palette, followed by padding to round the length up to the next multiple of 8 bytes
Block Light Byte Array Half byte per block
Sky Light Optional Byte Array Only if in the Overworld; half byte per block

Data Array, Block Light, and Sky Light are given for each block with increasing x coordinates, within rows of increasing z coordinates, within layers of increasing y coordinates.

The global palette encodes a block as 13 bits. It uses the block ID for the first 9 bits, and the block damage value for the last 4 bits. For example, diorite (block ID 1 for minecraft:stone with damage 3) would be encoded as 000000001 0011.

In half-byte arrays, two values are packed into each byte. Even-indexed items are packed into the high bits, odd-indexed into the low bits.


The following implement the previous format: