Chunk Format

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

Concepts

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

Format

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.

Implementations

• Java, 1.9
• Python, 1.9
• C, 1.9

The following implement the previous (before 1.9) format:

• Java, 1.8
• Python, 1.4
• Node.js, 1.8