Talk:Chunk format

1.13 chunk format changes
In 1.13 the Sections-Tag changes to this (BlockStates is a long array tag, but there is not yet a symbol for it in the wiki):


 * : List of Compound tags, each tag is a sub-chunk of sorts.
 * An individual Section.
 * : The Y index (not coordinate) of this section. Range 0 to 15 (bottom to top), with no duplicates but some sections may be missing if empty.
 * : Encodes the id-values from the Palette-Tag. The id-value is equal to the index of the palette entry. One long value might store multiple block ids at once, if possible. The minimum storage unit per block is 4 bit. One section always stores 16*16*16 = 4096 blocks, therefore the amount of bits per block can be calculated like that: size of BlockStates-Tag * 64 / 4096 (64 = bit of a long value). Since you can only have 4096 blocks in a section + the entry for air which is always there, the most that can be used is 2 byte = 16 bit per block.
 * : List of block states that exist in the section (first value is always air, even if there is no air in the section). Index-values are used in the BlockStates-Tag
 * : Block-ID-name of the block
 * : Only for blocks that have different states. Properties of the block state
 * : The value of the block state property.
 * : 2048 bytes recording the amount of block-emitted light in each block. Makes load times faster compared to recomputing at load time. 4 bits per block.
 * : 2048 bytes recording the amount of sunlight or moonlight hitting each block. 4 bits per block.
 * : 2048 bytes recording the amount of sunlight or moonlight hitting each block. 4 bits per block.

This is based on region file data I read using a custom program. --NeunEinser (talk) 20:49, 22 November 2017 (UTC)
 * Thanks, I was looking for this since it's not really documented anywhere else -- so has the chunk Version field changed with 1.13? ExtremeHeat11 (talk) 06:48, 19 February 2018 (UTC)

Removal of most entity data
I've noticed that the expansion areas for specific entities has been removed, and no replacement location for that information has been made available. This information is incredibly useful for map makers and the like, and certainly belongs somewhere on this wiki. I felt this page was an acceptable place for it, but apparently others disagree. Have plans been made to move this information elsewhere? and if so, where? Firebastard (talk) 01:51, 14 June 2018 (UTC)

Further information about BlockState format
I've just finished writing my own save file decoder (I know, it's been done, but half the fun is doing it myself).

Important information about the BlockState array that wasn't documented:


 * To recover the bitstream, process each of the uint64 values in _little_ endian order.
 * To assemble tokens from the bitstream, interpret each block of N bits in the stream in _little_ endian order.

This threw me, because most of the save file uses big-endian values, but I was getting corruption otherwise.

Relevant pieces of one Section from my 1.13 test save:

(palette entries 0x00 through 0x1d are valid): 0x00 - air 0x01 - netherrack 0x02 - magma ...

(first couple of words of BlockState, spaces added for clarity): 0x 1084 4201 8410 8400 0x 4210 8420 8400 0842 ...

Grouping the first word's binary data little-endian: (last) (0001) 00001 00001 00010 00010 00010 00010 00010 00001 00001 00001 00000 00000 (first)

...Getting air and netherrack and magma. Going through the rest of the Section gets more of the same.

Grouping the first word's binary data big-endian: (first) 00010 00010 00010 00100 00100 00100 00100 00100 00010 00010 00010 00000 (0000) (last)

...Getting air and magma and unexpected material. Alignment goes off by an extra bit with every new uint64 processed, so the Section ends up as a scrambled hash of unusual materials (and sometimes invalid palette entries).

I do not plan to get a login on this wiki any time soon. If anyone wants to fold in relevant parts of this material, go for it. Knowing about the endianness ahead of time would have really helped.

--107.142.102.195 22:37, 7 October 2018 (UTC)

Arrow OwnerUUIDLeast+Most
Can someone please point me to what I need to edit to add OwnerUUIDLeast and OwnerUUIDMost to the arrow NBT tree? And does someone know when they were added? Fabian42 (talk) 14:00, 2 August 2019 (UTC)
 * Similarly, to remove xTile, yTile and zTile from arrows, they apparently don't exist anymore. Fabian42 (talk) 11:50, 15 August 2019 (UTC)

1.15 biome tag array
The new biome tag layout seems to be missing information. From the chunks I've looked at, it's the same 16 values repeated 256 times. This is even less data than the original 256 integers previously. Is there more information hidden away somewhere else now?

73.51.11.196 20:29, 2 October 2019 (UTC)


 * The biome array no longer stores each x/y's biome ID, instead it's per 4x4x4 blocks. The overworld currently doesn't support the y axis biomes, but the nether does (no clue about the end).
 * The smooth curves of the biomes is no longer saved, and instead is done via an algorithem while the game runs. FVbico (talk) 08:30, 3 October 2019 (UTC)


 * Thanks. That's pretty freaking wild. Looks like there will be a decent amount of work to make this look nice in the Overviewer. 73.51.11.196 05:10, 4 October 2019 (UTC)

xPos/zPos coordinates system
When positions are specified in the NBT data for a chunk: xPos: X position of the chunk. zPos: Z position of the chunk

... are they supposed to be relative to the chunk origin (e.g: in the 0-31 range), or are they supposed to be absolute positions expressed in the world coordinate system?

-- Sylvain 80.67.177.9 17:55, 29 October 2019 (UTC)

HiddenEffect
According to Slicedlime (here), the "HiddenEffect" tag has no ID, but instead optionally another "HiddenEffect" tag. I have no idea how to edit or even navigate these complicated systems of templates and scripts, can someone else please correct this? Fabian42 (talk) 22:00, 16 January 2020 (UTC)
 * Done, thanks. FVbico (talk) 22:14, 16 January 2020 (UTC)

Biomes Information Incorrect?
From my testing, the Biomes array is indexed by X, then Z, then Y instead of the Z, then X, then Y that the page currently specifies. Also, as far as I can tell, the game only respects the first 16 values in the Biomes array for all Y values in the Overworld, which may be worth mentioning. Can anyone confirm? --Mattrickdev (talk) 07:53, 26 February 2020 (UTC)


 * I can at least confirm the ordering of coordinates and have edited the article accordingly. —Fenhl 03:27, 27 June 2020 (UTC)

Correcting projectile entity data structure
The projectile entity data structure shown here is currently not correct. However, I don't feel familiar enough with the wiki to fix this. Could someone please have a try at this?


 * All currently listed projectiles and fireworks (they all have the same parent class) have since 20w10a the following tag: "OwnerUUID": Int array consisting of 4 ints: uuidMost >> 32, uuidMost & 0xFFFFFFFF, uuidLeast >> 32, uuidLeast 0xFFFFFFFF All other existing tags storing ownership of projectiles have been replaced by that
 * All thrown item projectiles (snowball, egg, enderpearl, xp bottle, potion) have the same parent class which defines
 * "Item" compound (so that could be inherited here on the wiki)
 * "shake", however that has no effect
 * "xTile", "yTile", "zTile", "inGround"
 * Arrow (which is not a thrown item projectile) defines these tags with the same name
 * "shake" for arrows affects the described shaking behavior
 * "inGround"
 * "inBlockState"; this does not exist for thrown item projectiles (wiki is currently wrong here)

--Marcono1234 (talk) 16:17, 7 March 2020 (UTC)

1.16 Chunk format changes
Behaviour in 20w19a: the blockstates array now contains longs with block indexes with no overflow: the longs are padded with 0s instead, and the overflowing index is in the next long.

An example, with a palette of 47, the block indexes are of length 6bits, there are 10 per long. BlockStates (long_array) 18300411153223745 - 0000 000001 000001 000001 000010 000010 000010 000010 000001 000001 000001  36314739852447809 - 0000 000010 000001 000001 000001 000001 000001 000001 000001 000001 000001

That means slightly larger save files at the benefit of much simpler read.

--73.240.200.10 19:27, 12 May 2020 (UTC)

Parsing Heightmaps field (1.15.2)
Supposedly the Heightmaps are a packed array of 9bit integers. The NBT file stores the array as thirty-six 64bit integers. That's 2304 bits of data, the same as 256 9-bit integers. So far so good. But the raw data doesn't make sense. In the bitstream I'm parsing, the first 36 bits are 100011111 100011111 100011111 100011111 which translates to 287, 287, 287, 287. But the maximum height of a chunk is 256. Any ideas how the Heightmap data is actually stored?

NVM: figured it out. I was parsing starting at the left of the bitstring. But it's a lot more complicated than that. The first 9 bit integer is the rightmost nine bits in the first 64, the second 9 bit integer is bits 18-10 (counting from the right), etc. The leftmost bit of the first 64 is actually the rightmost bit of the second 64. What a confusing way to pack bits. Glad this is changing in 1.16.

--100.11.95.53 21:55, 25 May 2020 (UTC)

DataVersion numbers in history section
It would be useful to document the values of the DataVersion tag at which relevant changes have been made. Does anyone have that data? —Fenhl 01:41, 27 June 2020 (UTC)
 * Data version – does that have what you need?  Nixinova   T   C   01:56, 27 June 2020 (UTC)

CustomName NBT at Block Entities
The CustomeName NBT tag for block entities can be set for some blocks(ex.chests,barrels) as the JSON text shows at the top of the GUI. But some blocks like beacons that doesn't have CustomeName can actually use them(CustomeName)(not like the example above) if the tag Lock is available.

When right-clicking block entities that have Lock tags enabled, it shows " is Locked!" When CustomeName is set,  at the title before shows the value of CustomName(as a plain text,not the JSON text itself).

So, what if we add CustomeName tags to other block entities like this? They do use it, but we don't see often. Sunnylee0 (talk) 13:05, 16 November 2020 (UTC)

Information about structure data is incorrect, or is confusingly worded
from the "NBT structure":
 * Starts: Structures that are yet to be generated, stored by general type. Some parts of the structures may have already been generated. Completely generated structures are removed by setting their id to "INVALID" and removing all other tags.

Consider this chunk, that has a lonely village hut in it: https://gist.github.com/MalbaCato/f71e5817ece404ab43915f8dc0b0c44e (the file is uncompressed nbt of the relevant chunk, for convenience). Following the quote above, it has nothing to do here. Clearly the hut is fully generated, because the status is "full". The "a swamp hut can't fully generate because it will always have to re-generate witches" interpretation may be valid, but is just confusing. Either some general explanation, or a list of structures that do and don't follow that behaviour is clearly needed.

While you have that file open, the Cat tag inside children is also missing from the nbt structure documentation. May I suggest splitting the tags by what structure they correspond to, similarly to what is done with advancement triggers? 141.226.208.139 13:46, 21 April 2021 (UTC)

Block Entity detail needs review and corrections
It's obvious that some of the text has been copy/pasted and simply is not valid for the block entities where it's found. For example, for Banner the text talks about Beacon, and that text refers to the beacon as a container. CaptainStarbuck (talk) 23:37, 5 September 2021 (UTC)