Chunk Format
Byte Order
Chunk data is stored in Big Endian byte order unless mentioned otherwise.
NBT structure
- The root tag.
- DataVersion: Version of the chunk NBT structure.
- Level: Chunk data.
- xPos: X position of the chunk (in absolute chunks from
x
,z
origin, not relative to the region). - zPos: Z position of the chunk (in absolute chunks from
x
,z
origin, not relative to the region). - LastUpdate: Tick when the chunk was last saved.
- InhabitedTime: The cumulative number of ticks players have been in this chunk. Note that this value increases faster when more players are in the chunk. Used for Regional Difficulty.
- Biomes: 1024 entries of biome data. Each number in the array is the biome id for a 4×4×4 volume in the chunk. These 4×4×4 volumes are arranged by Z, then X, then Y. That is, the first 4×4 values in the array are for the 16×16 chunk, at Y levels 0-3, the next 4×4 is for Y levels 4-7, etc. If this tag does not exist, it gets created and filled by Minecraft.
- Heightmaps: Several different heightmaps corresponding to 256 values compacted at 9 bits per index (lowest being 0, highest being 256, both inclusive).
- MOTION_BLOCKING: The highest block that blocks motion or contains a fluid. Longs are stored in Little Endian
- MOTION_BLOCKING_NO_LEAVES: The highest block that blocks motion, contains a fluid, or is in the
minecraft:leaves
tag. Longs are stored in Little Endian - OCEAN_FLOOR: The highest block that is neither air or a fluid. Longs are stored in Little Endian
- OCEAN_FLOOR_WG: The highest block that is neither air or a fluid, for worldgen. Longs are stored in Little Endian
- WORLD_SURFACE: The highest non-air block. Longs are stored in Little Endian
- WORLD_SURFACE_WG: The highest non-air block, for worldgen. Longs are stored in Little Endian
- Sections: Each CompoundTag is a section (also known as subchunk). All sections in the world's height are present in this list. Empty sections are not stored.
- An individual section.
- Y: The Y position of this section.
- Palette: Set of different block states used in this particular section.
- A block state.
- Name: Block resource location.
- Properties: List of block state properties. Omitted if block has no properties.
- Name: The block state name and it's value.
- A block state.
- BlockStates: A packed array of 4096 indices pointing to the palette, stored in an array of longs. Longs are stored in Little Endian
- BlockLight: 2048 ByteTags storing the amount of block-emitted light in each block, Omitted if no light reaches this section of the chunk. Stored 4 bits per block.
- SkyLight: 2048 ByteTags storing the maximum sky light that reaches each block, Omitted if no sky light reaches this section of the chunk or the bottom 16×16 of the section above this one. Stored 4 bits per block.
- An individual section.
- Entities: Each CompoundTag in this list defines a entity in this chunk (Removed in 1.17). See Entity format for details.
- TileEntities: Each CompoundTag in this list defines a block entity in this chunk. See Tile Entity format for details.
- TileTicks: Each CompoundTag in this list is an "active" block in this chunk waiting to be updated. See Tile Tick format below.
- LiquidTicks: Each CompoundTag in this list is an "active" liquid in this chunk waiting to be updated. See Tile Tick format below.
- Lights: List of 16 Lists of ShortTags.
- LiquidsToBeTicks: List of 16 Lists of ShortTags.
- ToBeTicked: List of 16 Lists of ShortTags.
- PostProcessing: List of 16 Lists of ShortTags.
- Status: Defines the world generation status of this chunk.
It is always one of the following:empty
,structure_starts
,structure_references
,biomes
,noise
,surface
,carvers
,liquid_carvers
,features
,light
,spawn
,heightmaps
, orfull
.
All status exceptfull
are used for chunks called proto-chunks, in other words, for chunks with incomplete generation. - Structures: Structure data in this chunk. See Structure format for details.
- xPos: X position of the chunk (in absolute chunks from
Tile Ticks Data
- An active block.
- i: The ID of the block; used to activate the correct block update procedure.
- p: If multiple tile ticks are scheduled for the same tick, tile ticks with lower
p
are processed first. If they also have the samep
, order is unknown. - t: The number of ticks until processing should occur. May be negative when processing is overdue.
- x: X position.
- y: Y position.
- z: Z position.
Parsing the Chunk
Parsing the Blocks
Variables you'll need to calculate first
Name | Type | Formula |
---|---|---|
Bits Per Index | 32-bit integer | 64 - leadingZeros(palette.len()) |
Blocks Per Index | 32-bit integer | floor(64 ÷ Bits Per Index) |
Block Indices | 32-bit integer array. Size = ceil(4096 ÷ Blocks Per Index) × Blocks Per Index | Extract Blocks Per Index indices of Bits Per Index bits from each 64-bit integer and store them as their own index in the new 32-bit integer array |
Now that you have all the needed variables you can now loop the palette in XZY order (X increments first).
The index can be calculated with Y × 16 × 16 + Z × 16 + X
.
Indexing the block palette should look something like this: palette.get(block_indices[xzy_index])
Parsing the Biomes
Loop the biome id array in XZY order (X increments first).
The index can be calculated with (Y >> 2 & 0x3) × 16 + (Z >> 2 & 0x3) × 4 + (X >> 2 & 0x3)
.
Indexing the biomes is like a normal array: biomes[xzy_index]
.
Parsing the Heightmaps
Variables you'll need to calculate first
Name | Type | Formula |
---|---|---|
Block Indices | 32-bit integer array. Size = 259 (Only 256 indices used) | Extract 7 indices of 9 bits from each 64-bit integer and store them as their own index in the new 32-bit integer array |
Now that you have all the needed variables you can now loop the palette in XZ order (X increments first).
The index can be calculated with Z × 16 + X
.
Indexing the heightmap arrays is like a normal array: heightmap[xz_index]
.
License & Credits
This file is licensed under CC BY-NC-SA 3.0
.
The information here is from an old version of this Minecraft wiki page with some wording tweaked and/or simplify