World file format explained · Java · Advanced

The Minecraft Anvil (.mca) Region File Format Explained in Detail

Every Minecraft Java Edition world stores its terrain, entities, and points of interest inside Anvil (.mca) region files. Understanding the binary structure of these files—from their 8KB lookup headers and 4KB sector alignment to their compressed NBT payloads—is essential for low-level world debugging, recovery, and optimization. This guide breaks down the exact byte-level layout of an .mca file and shows you how to inspect it safely right in your browser.

What you need

  • A Minecraft Java Edition world folder or .zip archive
  • A duplicate backup of your world before inspecting or modifying any region files
  • Our browser-based Region & Chunk Inspector and NBT Editor tools (which run locally without uploading your files)
  • Basic familiarity with binary data, hexadecimal notation, and bit shifting

Step by step

  1. 1Back Up Your World and Locate the Region Files

    Before inspecting or modifying binary world data, always create a complete copy of your world folder. Navigate into your world directory and look inside the 'region' folder for the Overworld, 'DIM-1/region' for the Nether, or 'DIM1/region' for the End. Here you will find files named in the format 'r.X.Z.mca', where X and Z are the region coordinates. Each single .mca file encapsulates a 32x32 grid of chunks (up to 1,024 chunks total), covering a 512x512 block area.

    Tip: You can calculate which region file holds a specific chunk by performing an arithmetic bit-shift right by 5 (ChunkCoordinate >> 5), which is equivalent to floor(ChunkCoordinate / 32).

  2. 2Load the World in the Local Browser Inspector

    Click 'Open world folder or .zip' in our on-site Region & Chunk Inspector to parse your world locally in your browser's memory. Because all processing happens client-side, your large .mca files are never uploaded to a server. Select any 'r.X.Z.mca' file from the directory tree to view its 32x32 chunk grid, header lookup tables, and raw hexadecimal structure.

  3. 3Decode the First 4KB Header: Chunk Location Offsets

    Every .mca file begins with an 8KB (8,192-byte) header split into two 4KB tables. The first 4,096 bytes (bytes 0 to 4095) contain 1,024 four-byte entries—one for each chunk in the 32x32 grid. For any chunk at coordinates (X, Z), its 4-byte entry is located at byte index 4 * ((X & 31) + (Z & 31) * 32). The first 3 bytes of this big-endian entry represent the starting offset in 4KB (4,096-byte) sectors from the very beginning of the file, while the 4th byte specifies the total number of 4KB sectors allocated to that chunk.

    Tip: If both the 3-byte offset and 1-byte sector count are 0, the chunk has never been generated or saved in this region file. Note that valid chunk offsets always start at sector 2 or higher, because sectors 0 and 1 are occupied by the 8KB header itself.

  4. 4Decode the Second 4KB Header: Epoch Timestamps

    Immediately following the location table, bytes 4096 to 8191 form the timestamp table. It uses the exact same 4 * ((X & 31) + (Z & 31) * 32) indexing math as the location table. Each 4-byte big-endian unsigned integer stores the Unix epoch timestamp (in seconds) of the last time that specific chunk was saved by the game engine. You can verify these decoded dates directly by hovering over any chunk tile in our Region & Chunk Inspector.

  5. 5Locate the Chunk Payload and Read Its 5-Byte Prefix

    Multiply the 3-byte sector offset from the first table by 4,096 to jump to the exact byte where the chunk data begins. Every chunk payload starts with a 5-byte prefix: a 4-byte big-endian integer indicating the exact byte length of the remaining chunk data (including the 5th prefix byte), followed by a 1-byte compression type identifier. A compression byte of '1' indicates GZip (RFC1952, rarely used), '2' indicates Zlib (RFC1950, the standard default), '3' indicates uncompressed raw NBT, and '4' indicates LZ4 framing (introduced in Java Edition 1.20.5).

    Tip: If a single chunk's compressed data grows larger than ~1MB (exceeding the 255-sector limit of a single byte), modern Java Edition writes a compression type with the high bit set (add 128 to the ID, e.g., 130 for Zlib) and saves the overflow payload in an external 'c.X.Z.mcc' file.

  6. 6Decompress and Inspect the Root NBT Tags

    Click on an active chunk in our Region & Chunk Inspector and switch to the integrated NBT Editor view. Our browser tool automatically reads the exact byte length, detects whether to apply Zlib or LZ4 decompression, and unpacks the binary stream into a human-readable Named Binary Tag (NBT) tree. Inside a terrain region file, you will immediately see top-level tags like 'DataVersion', 'xPos', 'zPos', 'Status', 'sections' (which holds block_states and biomes palettes), and 'block_entities'.

    Tip: When editing tags and re-saving via our tool, the browser automatically recalculates the compressed stream length, pads the end of the chunk payload with zero/null bytes so it aligns cleanly to a 4,096-byte sector boundary, and updates the 8KB header.

How it works

The Anvil (.mca) format is fundamentally a miniature filesystem inside a single file, designed around 4,096-byte (4KB) sectors. This 4KB alignment is not arbitrary; it matches the standard memory page size and disk block size of modern operating systems. By aligning chunks to 4KB boundaries, the Minecraft game engine can use random-access file pointers to read or overwrite a single chunk in place without having to rewrite or shift the entire multi-megabyte region file.

Because chunks change size dynamically as players build or add chests and entities, a chunk's compressed NBT payload rarely divides evenly by 4,096. If a compressed chunk plus its 5-byte header takes up 5,000 bytes, the engine allocates 2 sectors (8,192 bytes) and leaves the remaining 3,192 bytes as trailing padding. If that chunk later expands past 8,192 bytes, the engine looks for the next contiguous free gap of 3 sectors (or appends to the end of the .mca file) and updates the 3-byte offset in the first 4KB header.

Starting in recent versions of Java Edition, the exact same .mca container architecture is used across three distinct subfolders: 'region' (terrain, biomes, and block entities), 'entities' (mobs and dropped items, split out in 1.17), and 'poi' (villager job sites, beds, and Nether portals). While the internal NBT tag structures inside the decompressed payloads differ depending on the folder, the 8KB header, 4KB sector allocation logic, and Zlib/LZ4 compression wrappers remain 100% identical.

Common mistakes

  • Forgetting to include the 1-byte compression scheme identifier when calculating or reading the 4-byte payload length prefix (the actual compressed NBT stream length is always the 4-byte length value minus 1).
  • Assuming the chunks inside the file body are stored in sequential coordinate order; because chunks are reallocated to new sectors whenever they outgrow their current sector count, the physical order of chunks after byte 8,192 is completely fragmented.
  • Using signed remainder math instead of bitwise AND (X & 31) for negative chunk coordinates when calculating header indices, which results in out-of-bounds or inverted grid lookups.
  • Failing to pad a manually modified chunk back out to a clean multiple of 4,096 bytes, which corrupts the sector offsets of every subsequent chunk in the file.

FAQ

Why is my .mca file size always a precise multiple of 4,096 bytes?

Because both the 8,192-byte header (2 sectors) and every allocated chunk payload are strictly padded to 4,096-byte (4KB) sector boundaries. Even if the final chunk in the file only uses 300 bytes of its last sector, the file is padded to the end of that 4KB block.

How does Minecraft switch between Zlib and LZ4 compression in .mca files?

Since Java Edition 1.20.5, the server.properties file includes a 'region-file-compression' setting (defaulting to 'deflate' for Zlib, with options for 'lz4' or 'none'). Because each chunk stores its own 1-byte compression ID (2 for Zlib, 4 for LZ4), a single .mca file can simultaneously hold older Zlib chunks alongside newly saved LZ4 chunks.

What causes empty gaps of unused sectors inside an .mca file?

When a chunk is modified and its compressed NBT size grows beyond its currently allocated 4KB sectors, Minecraft moves the chunk to a new location at the end of the file (or a larger free gap) and updates its header pointer. The old sectors are left behind as unreferenced dead space until another small chunk is saved into that gap.

The Minecraft Anvil (.mca) format operates as a 4KB-sector-aligned mini-filesystem where an 8KB header maps a 32x32 grid of chunks to their timestamps and Zlib- or LZ4-compressed NBT payloads.

More world file format explained guides

World file format explainedHow Minecraft Bedrock Stores Worlds: LevelDB Keys, .ldb, and .log Files ExplainedUnlike Java Edition's grid of region files, Minecraft Bedrock Edition stores its entire world inside a high-performance key-value database called LevelDB. Understanding how `.ldb` files, `.log` files, and binary chunk keys work is essential for advanced debugging, world recovery, and low-level NBT editing. Because our browser-based tools process these database files locally on your device without ever uploading them, you can safely inspect and modify complex world records with zero server lag or privacy risks.BedrockAdvanced5 steps
World file format explainedMinecraft Chunk Heightmaps Explained: WORLD_SURFACE vs MOTION_BLOCKINGMinecraft stores precomputed 2D elevation grids inside every chunk called Heightmaps, allowing the game engine to skip scanning vertical columns of blocks from top to bottom. Understanding the difference between WORLD_SURFACE and MOTION_BLOCKING tags is essential for debugging lighting glitches, rain passing through roofs, map rendering, and mob spawning mechanics. This advanced guide shows you how to inspect and decode these 9-bit packed long arrays directly inside your browser using our client-side NBT Editor.JavaAdvanced5 steps
World file format explainedInside a Modern Minecraft Chunk: Sections, Block Palettes, and Bit-Packed StatesModern Minecraft Java Edition worlds store terrain using a highly optimized system of 16x16x16 sub-chunks, dynamic block palettes, and bit-packed integer arrays. Understanding this structure allows you to manually inspect, debug, and surgical-edit chunk data at the lowest possible level. This guide explores the anatomy of post-1.18 chunk sections using our browser-based NBT Editor, where all your files are processed locally and never uploaded.JavaAdvanced6 steps
World file format explainedHow the DataVersion Tag and DataFixerUpper Upgrade Minecraft WorldsHave you ever wondered how a Minecraft Java Edition world created a decade ago can still open seamlessly in the latest game release? The secret lies in a simple integer tag called DataVersion and an internal conversion engine known as DataFixerUpper. This guide explains how Minecraft tracks world versions across level.dat and region files, and why downgrading a world to an older version destroys chunks.JavaIntermediate4 steps
World file format explainedWhy Minecraft Separated region, entities, and poi Into Three FoldersBefore Minecraft Java Edition 1.17, nearly everything inside a chunk—terrain blocks, mobs, dropped items, and villager workstations—was crammed into a single region file. To improve game performance and allow asynchronous chunk loading, the developers split this data into three distinct folders: region, entities, and poi. This guide explains the logic behind this separation and shows you how to inspect and manage these folders safely using our browser-based tools.JavaIntermediate5 steps
World file format explainedComplete Reference to Every Field in Minecraft's level.dat FileThe level.dat file is the brain of every Java Edition Minecraft world, storing everything from the global random seed and weather cycle to boss fight progression and gamerules. Understanding what every root tag inside the Data compound does gives you complete control over your world's mechanics and behavior. Using our browser-based level.dat Editor, you can safely inspect and modify these settings locally on your machine without uploading your private world files anywhere.JavaIntermediate6 steps