Skip to content

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.
          • 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.
      • 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, or full.
        All status except full 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.

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 same p, 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

NameTypeFormula
Bits Per Index32-bit integer64 - leadingZeros(palette.len())
Blocks Per Index32-bit integerfloor(64 ÷ Bits Per Index)
Block Indices32-bit integer array. Size = ceil(4096 ÷ Blocks Per Index) × Blocks Per IndexExtract 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

NameTypeFormula
Block Indices32-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

Contributors

The avatar of contributor named as BJTMastermind BJTMastermind
The avatar of contributor named as Dexrn ZacAttack Dexrn ZacAttack

Changelog

Contributors



Documentation page was setup by DexrnZacAttack.


Documentation is licensed under Creative Commons CC-BY 4.0 unless otherwise noted. For more info, check the NOTICE file.