Difference between revisions of "Chunk Format"
(→Format: (Attempt to) improve the description of bits per block) |
(added missing info about a value of exactly 9, which should use the global palette based on previous versions of this article; formatting) |
||
| Line 1: | Line 1: | ||
| − | {{Warning2| | + | {{Warning2|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.}} |
This article describes the '''Chunk Section''' format used in the [[Protocol#Chunk Data|Chunk Data]] packet ([[Protocol#Play|Play]], 0x20, clientbound). | This article describes the '''Chunk Section''' format used in the [[Protocol#Chunk Data|Chunk Data]] packet ([[Protocol#Play|Play]], 0x20, clientbound). | ||
| Line 20: | Line 20: | ||
| Bits Per Block | | Bits Per Block | ||
| Unsigned Byte | | Unsigned Byte | ||
| − | | Determines how many bits are used to encode a block. | + | | Determines how many bits are used to encode a block. Note that not all numbers are valid here. This also changes whether the palette is present. |
|- | |- | ||
| Palette Length | | Palette Length | ||
| VarInt | | VarInt | ||
| − | | Length of the following array. | + | | Length of the following array. May be 0. |
|- | |- | ||
| Palette | | Palette | ||
| Line 49: | Line 49: | ||
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. | ||
| − | There are several values that can be used for the bits per block value. | + | There are several values that can be used for the bits per block value. In most cases, invalid values will be treated as if it is a different value when parsed by the Notchian client, meaning that chunk data will be parsed incorrectly if you use an invalid bits per block. Servers must make sure that the bits per block value is correct. |
| − | * 4: Blocks are encoded as 4 bits. | + | * 4: Blocks are encoded as 4 bits. The palette array is used and sent. |
| − | * 5 to 8: Blocks are encoded with the given number of bits. | + | * 5 to 8: Blocks are encoded with the given number of bits. The palette array is used and sent. |
| − | * | + | * 9 and above: Blocks are encoded by their whole ID in the global palette, with bits per block being set as the base 2 logarithm of the number of block states, rounded up. For the current vanilla release, this is 13 bits per block. |
| − | 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>. If a block is not found in the global palette (either due to not having a valid damage value or due to not being a valid ID), it will be treated as air. |
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''. | 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''. | ||
Revision as of 10:10, 12 April 2016
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.
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 not all numbers are valid here. This also changes whether the palette is present. |
| 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.
There are several values that can be used for the bits per block value. In most cases, invalid values will be treated as if it is a different value when parsed by the Notchian client, meaning that chunk data will be parsed incorrectly if you use an invalid bits per block. Servers must make sure that the bits per block value is correct.
- 4: Blocks are encoded as 4 bits. The palette array is used and sent.
- 5 to 8: Blocks are encoded with the given number of bits. The palette array is used and sent.
- 9 and above: Blocks are encoded by their whole ID in the global palette, with bits per block being set as the base 2 logarithm of the number of block states, rounded up. For the current vanilla release, this is 13 bits per block.
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. If a block is not found in the global palette (either due to not having a valid damage value or due to not being a valid ID), it will be treated as air.
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:
