
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
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).
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.
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.
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.
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.
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.