Region file format

The Region file format is a storage format for Minecraft chunks introduced in Minecraft Beta 1.3, in which groups of 32×32 chunks are stored in a region file. This file format took the place of the Alpha level format, which had been in use since the Infdev development phase, in which chunks were stored in individual files. It could be said that a region is a part of a file system where the header shows you positions for each file and sector is the allocation size.

The system is based on McRegion, a mod by Scaevolus, also known for his development of the Optimine project. The McRegion format was adopted nearly unchanged, except for the addition of a table of chunk update timestamps. JahKob has claimed that this format is up to 7 times faster than the previous system. The difference in a world's total file size between the Region file format and the Alpha level format are negligible.

The format has been superseded by the Anvil file format; however, the Anvil file format only made changes to the Chunk format and only changed the region file extensions from ".mcr" to ".mca".

Region files

Region file location

Region files are located in a subfolder of the world directory called "region", and have names in the form r.x.z.mca, where x and z are the region's coordinates. The coordinates for the region a chunk belongs to can be found by taking the floor of the chunk coordinates divided by 32.

In Java:

   int regionX = (int)floor(chunkX / 32.0);
   int regionZ = (int)floor(chunkZ / 32.0);

Or in bit-operation(bit shift):

   int regionX = chunkX >> 5
   int regionZ = chunkZ >> 5

For example, a chunk at (30, -3) would be in region (0, -1), and one at (70, -30) would be at (2, -1).

Structure

Region files begin with an 8kiB header containing information about which chunks are present in the region file, when they were last updated, and where they can be found. The location in the region file of a chunk at (x, z) (in chunk coordinates) can be found at byte offset 4 * ((x mod 32) + (z mod 32) * 32) in its region file. In case the values of x mod 32 or z mod 32 are negative (which happens when using % operator in Java/C/C++), simply add 32. Or you can replace mod with & (AND operator). Offset calculation will look like this: 4 * ((x & 31) + (z & 31) * 32). Its timestamp can be found 4096 bytes later in the file. The remainder of the file consists of data for up to 1024 chunks, interspersed with unused space.

byte	0 - 4095	4096 - 8191	8192...
description	locations (1024 entries)	timestamps (1024 entries)	chunks and unused space

Chunk location

Location information for a chunk consists of four bytes split into two fields: the first three bytes are a (big-endian) offset in 4KiB sectors from the start of the file, and a remaining byte which gives the length of the chunk (also in 4KiB sectors, rounded up). Chunks will always be less than 1MiB in size. If a chunk isn't present in the region file (e.g. because it hasn't been generated or migrated yet), both fields will be zero.

byte	0	1	2	3
description	offset			sector count

A chunk with an offset of 2 will begin right after the timestamps table.

Chunk timestamps

The entries in the timestamp table are individual four-byte big-endian integers, representing the last modification time of a chunk.

byte	0	1	2	3
description	timestamp

Chunk data

Chunk data begins with a (big-endian) four-byte length field which indicates the exact length of the remaining chunk data in bytes. The following byte indicates the compression scheme used for chunk data, and the remaining (length-1) bytes are the compressed chunk data.

Minecraft always pads the last chunk's data to be a multiple-of-4096B in length (so that the entire file has a size that is a multiple of 4KiB). Minecraft will not accept files in which the last chunk is not padded. Note that this padding is not included in the length field.

byte	0	1	2	3	4	5...
description	length (in bytes)				compression type	compressed data (length-1 bytes)

There are currently two defined compression schemes:

value	method
1	GZip (RFC1952) (unused in practice)
2	Zlib (RFC1950)

The uncompressed data is in NBT format and follows the information detailed on the chunk format article; if compressed with compression scheme 1, the compressed data would be the same as the on-disk content of an Alpha chunk file. Note that chunks will always be saved using compression scheme 2 by the official client.

Migration and level.dat

How Minecraft looks when converting to the new format.

Beta 1.3 will convert any "old" chunks into region files before loading the world, rather than incrementally as they are loaded during play. As part of the conversion, level.dat will be updated with TAG_Int("version") (note case) set to 19132. Beta 1.3 also introduces a new level name field, TAG_String("LevelName"). There's also introduced new TAG_Byte("Sleeping") in player TAG_Compounds - level.dat in single player, [player name].dat in multiplayer which indicates whether is player in the bed. It has value 1(true) or 0(false). For the beta 1.8, TAG_Int("GameType") was added. In beta 1.9, TAG_byte("hardcore") was added.

The format of level.dat is otherwise unchanged.

See also

• Level Format
• Chunk format
• Anvil file format

External links

• Mojang announcement of new region format; Jeb helping tool-makers
• McRegion
• RegionFile in Java
• RegionFileCache in Java

Software

The community has developed programs to work with region files:

Name	Description	Screenshot
McRegion	This mod optimizes how chunks are stored on the disk, meaning pauses to load or save a chunk as you move around a world become much shorter and less noticeable.
Minecraft Region Fixer	This tool is a python script that tries to fix problems in region files. It can find some typical errors (corrupted chunks, wrong located chunks, too many entities problems), and can fix these errors in various ways (deleting the chunks, replacing them with a backup copy, or relocating the chunk). This is a command line application.
MCA2NBT	A simple Unix command line utility to convert a Minecraft .mca region file (in anvil format) to a directory with the same basename containing an uncompressed NBT file for each of its chunks.
Region Scanner	A Minecraft 1.7.10 (only) Java command line utility to analyze and mass edit region files