Difference between revisions of "Chunk Format"

From wiki.vg
Jump to navigation Jump to search
(Probably best to put a big warning here until everything is fixed...)
(→‎Format: Partial modernization; still need to explain how the data array is encoded and give examples)
Line 20: Line 20:
 
  | Bits Per Block
 
  | Bits Per Block
 
  | Unsigned Byte
 
  | 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.
+
  | Determines how many bits are used to encode a block. Note that the actual value does not always match this value.
 
  |-
 
  |-
 
  | Palette Length
 
  | Palette Length
  | Optional VarInt
+
  | VarInt
  | Length of the following array
+
  | Length of the following array.  May be 0.
 
  |-
 
  |-
 
  | Palette
 
  | Palette
  | Optional Array of VarInt
+
  | Array of VarInt
 
  | Mapping of block state IDs in the global palette to indices of this array
 
  | Mapping of block state IDs in the global palette to indices of this array
 
  |-
 
  |-
 
  | Data Array Length
 
  | Data Array Length
 
  | VarInt
 
  | VarInt
  | Number of bytes in the following array, divided by 8 (given as such because Notchian implements Data Array as an Array of Long)
+
  | Number of bytes in the following array
 
  |-
 
  |-
 
  | Data Array
 
  | Data Array
  | Byte Array
+
  | Long 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
+
  | List of 4096 indices pointing to state IDs in the Palette
 
  |-
 
  |-
 
  | Block Light
 
  | Block Light
Line 48: Line 48:
  
 
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.
 
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 format of the palette changes based off of the value of bits per block.
 +
 +
* 0: The palette array has a length of 0, but no actual blocks can be sent since each block is represented by 0 bits.  This generally shouldn't be done as instead the primary bit mask should be used to mark this chunk section as empty.
 +
* 1 to 4: Blocks are encoded as 4 bits.  The palette array is at max 16 entries long and is used.
 +
* 5 to 8: Blocks are encoded with the given number of bits.
 +
* 9 and above: The palette array has a length of 0, and blocks are always represented as 13 bits per block in reference to the global palette.
  
 
The global palette encodes a block as 13 bits. It uses the {{Minecraft Wiki|Data values#Block IDs|block ID}} for the first 9 bits, and the block damage value for the last 4 bits. For example, diorite (block ID <code>1</code> for <code>minecraft:stone</code> with damage <code>3</code>) would be encoded as <code>000000001 0011</code>.
 
The global palette encodes a block as 13 bits. It uses the {{Minecraft Wiki|Data values#Block IDs|block ID}} for the first 9 bits, and the block damage value for the last 4 bits. For example, diorite (block ID <code>1</code> for <code>minecraft:stone</code> with damage <code>3</code>) would be encoded as <code>000000001 0011</code>.

Revision as of 19:40, 9 April 2016

Warning.png This information, particularly about the palette and when it can be omitted, is incorrect. The article will be corrected as this format is researched and reverse-engineered. Sorry for any inconvenience. --Pokechu22 (talk) 01:46, 5 April 2016 (UTC)

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 Determines how many bits are used to encode a block. Note that the actual value does not always match this value.
Palette Length VarInt Length of the following array. May be 0.
Palette 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
Data Array Long Array List of 4096 indices pointing to state IDs in the Palette
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 format of the palette changes based off of the value of bits per block.

  • 0: The palette array has a length of 0, but no actual blocks can be sent since each block is represented by 0 bits. This generally shouldn't be done as instead the primary bit mask should be used to mark this chunk section as empty.
  • 1 to 4: Blocks are encoded as 4 bits. The palette array is at max 16 entries long and is used.
  • 5 to 8: Blocks are encoded with the given number of bits.
  • 9 and above: The palette array has a length of 0, and blocks are always represented as 13 bits per block in reference to the global palette.

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 low bits, odd-indexed into the high bits.

Implementations

The following implement the previous (before 1.9) format: