Difference between revisions of "Chunk Format"

From wiki.vg
Jump to navigation Jump to search
(Remove warning at top - I think the page is accurate now.)
(→‎Format: Move example to its own section, some additions)
Line 34: Line 34:
 
  | Data Array
 
  | Data Array
 
  | Long Array
 
  | Long Array
−
  | List of 4096 indices pointing to state IDs in the Palette, compacted
+
  | Compacted list of 4096 indices pointing to state IDs in the Palette
 
  |-
 
  |-
 
  | Block Light
 
  | Block Light
Line 44: Line 44:
 
  | Only if in the Overworld; half byte per block
 
  | Only if in the Overworld; half byte per block
 
  |}
 
  |}
 +
 +
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''.
  
 
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. 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.
+
The Data Array, although varying in length, will never be padded due to the number of blocks being evenly divisible by 64, which is the number of bits in a long.
 +
 
 +
There are several values that can be used for the bits per block value. In most cases, invalid values will be interpreted as 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.
+
* up to 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.
 
* 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.
 
* 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>. 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.
+
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.
  
−
If Minecraft Forge is installed and a sufficiently large number of blocks are added, the bits per block value will be increased to compensate for the increased ID count.  This increase can go up to 16 bits per block (for a total of 4096 block IDs; when combined with the 16 damage values, there are 65536 total states).  You can get the number of blocks with the "Number of ids" field found in the [[Minecraft Forge Handshake#RegistryData|RegistryData packet in the Forge Handshake]].
+
If Minecraft Forge is installed and a sufficiently large number of blocks are added, the bits per block value for the global palette will be increased to compensate for the increased ID count.  This increase can go up to 16 bits per block (for a total of 4096 block IDs; when combined with the 16 damage values, there are 65536 total states).  You can get the number of blocks with the "Number of ids" field found in the [[Minecraft Forge Handshake#RegistryData|RegistryData packet in the Forge Handshake]].
  
 
The data array stores several entries within a single long, and sometimes overlaps one entry between multiple longs.  For a bits per block value of 13, the data is stored such that bits 1 through 13 are the first entry, 14 through 26 are the second, and so on.  Note that bit 1 is the ''least'' significant bit in this case, not the most significant bit.  The same behavior applies when a value stretches between two longs: for instance, block 5 would be bits 53 through 64 of the first long and then bit 65 of the second long.
 
The data array stores several entries within a single long, and sometimes overlaps one entry between multiple longs.  For a bits per block value of 13, the data is stored such that bits 1 through 13 are the first entry, 14 through 26 are the second, and so on.  Note that bit 1 is the ''least'' significant bit in this case, not the most significant bit.  The same behavior applies when a value stretches between two longs: for instance, block 5 would be bits 53 through 64 of the first long and then bit 65 of the second long.
  
−
For instance, with 13 bits per block, the following 2 longs would represent...
+
== Example ==
 +
 
 +
13 bits per block, using the global palette.
 +
 
 +
The following two longs would represent...
  
 
<code>1001880C0060020</code> =  
 
<code>1001880C0060020</code> =  
Line 77: Line 85:
 
#Gravel, <span style="border: solid 2px hsl(320, 90%, 60%)">13</span>:<span style="border: solid 2px hsl(320, 90%, 70%)">0</span>
 
#Gravel, <span style="border: solid 2px hsl(320, 90%, 60%)">13</span>:<span style="border: solid 2px hsl(320, 90%, 70%)">0</span>
 
#Stone, <span style="border: solid 2px rgb(60%, 60%, 60%)">1</span>:<span style="border: solid 2px rgb(70%, 70%, 70%)">0</span> (or potentially emerald ore, <span style="border: solid 2px rgb(60%, 60%, 60%)">129</span>:<span style="border: solid 2px rgb(70%, 70%, 70%)">0</span>)
 
#Stone, <span style="border: solid 2px rgb(60%, 60%, 60%)">1</span>:<span style="border: solid 2px rgb(70%, 70%, 70%)">0</span> (or potentially emerald ore, <span style="border: solid 2px rgb(60%, 60%, 60%)">129</span>:<span style="border: solid 2px rgb(70%, 70%, 70%)">0</span>)
−
 
−
The data array will never be padded due to the number of blocks being evenly divisible by 64, which is the number of bits in a long.
 
−
 
−
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 ==
 
== Implementations ==

Revision as of 18:30, 12 April 2016

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 longs in the following array
Data Array Long Array Compacted 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

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.

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 Data Array, although varying in length, will never be padded due to the number of blocks being evenly divisible by 64, which is the number of bits in a long.

There are several values that can be used for the bits per block value. In most cases, invalid values will be interpreted as 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.

  • up to 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.

If Minecraft Forge is installed and a sufficiently large number of blocks are added, the bits per block value for the global palette will be increased to compensate for the increased ID count. This increase can go up to 16 bits per block (for a total of 4096 block IDs; when combined with the 16 damage values, there are 65536 total states). You can get the number of blocks with the "Number of ids" field found in the RegistryData packet in the Forge Handshake.

The data array stores several entries within a single long, and sometimes overlaps one entry between multiple longs. For a bits per block value of 13, the data is stored such that bits 1 through 13 are the first entry, 14 through 26 are the second, and so on. Note that bit 1 is the least significant bit in this case, not the most significant bit. The same behavior applies when a value stretches between two longs: for instance, block 5 would be bits 53 through 64 of the first long and then bit 65 of the second long.

Example

13 bits per block, using the global palette.

The following two longs would represent...

1001880C0060020 = 0000000100000000000110001000000011000000000001100000000000100000
200D0068004C020 = 0000001000000000110100000000011010000000000001001100000000100000

9 blocks, with the start of a 10th (that would be finished in the next long).

  1. Grass, 2:0
  2. Dirt, 3:0
  3. Dirt, 3:0
  4. Coarse dirt, 3:1
  5. Stone, 1:0
  6. Stone, 1:0
  7. Diorite, 1:3
  8. Gravel, 13:0
  9. Gravel, 13:0
  10. Stone, 1:0 (or potentially emerald ore, 129:0)

Implementations

The following implement the previous (before 1.9) format:

Retrieved from "https://wiki.vg/index.php?title=Chunk_Format&oldid=7739"