Difference between revisions of "Chunk Format"
(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 | ||
| − | | | + | | 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 | ||
| − | | | + | | VarInt |
| − | | Length of the following array | + | | Length of the following array. May be 0. |
|- | |- | ||
| Palette | | Palette | ||
| − | | | + | | 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 | + | | Number of bytes in the following array |
|- | |- | ||
| Data Array | | Data Array | ||
| − | | | + | | Long Array |
| − | | List of 4096 indices pointing to state IDs in the Palette | + | | 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
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:
