SyncBot: Sync: new page from Minecraft

2026-04-21T11:09:28Z

Sync: new page from Minecraft

New page

{{cleanup}}
{{outdated|edition=java|As of [[Minecraft:Java Edition 1.2.1|1.2.1]], this format is no longer used.}}
The '''Region file format''' is the [[Wikipedia:Binary file|binary file format]] for storing Java Edition [[Minecraft:chunk]]s from [[Minecraft:Java Edition Beta 1.3|Beta 1.3]] to [[Minecraft:Java Edition 1.1|1.1]]. Each file stores a group of 32×32 chunks called a '''region'''.{{Efn|A total of 1024 chunks can be stored in the format, covering an area of 512×512 blocks.<ref>{{Citation|url=https://www.mojang.com/2012/02/new-minecraft-map-format-anvil/|title=New Minecraft Map Format, “Anvil”|author=[[Minecraft:Jens Bergensten|Bergensten, Jens]]|website=Mojang.com|date=February 14, 2012|archive-url=https://web.archive.org/web/20120302221152/https://www.mojang.com/2012/02/new-minecraft-map-format-anvil/|quote=Maximum build height has been increased to 256 (was 128)|archive-time=March 2, 2012}}</ref>}} The format took the place of the [[Minecraft:Java Edition Alpha level format|Alpha level format]], which had been in use since the [[Minecraft:Infdev]] development phase, where chunks were stored in individual files on the file system. The file does not begin with a [[Minecraft:wikipedia:Magic_number_(programming)#In_files|magic number]], unlike [[Minecraft:wikipedia:List_of_file_signatures|other file formats]], and begins directly with the header. The format has been superseded by the [[Minecraft:Anvil file format]]; however, the Anvil file format made changes only to the [[Minecraft:chunk format]] and changed the region file extensions from ".mcr" to ".mca".

The system is based on McRegion,<ref>http://www.minecraftforum.net/forums/mapping-and-modding/minecraft-mods/mods-discussion/1346703-mod-mcregion-v5-optimized-saves-1-2_02#p2619453</ref> a mod by [http://www.minecraftforum.net/members/Scaevolus Scaevolus], also known for his development of the Optimine project.<ref>https://www.minecraftforum.net/forums/mapping-and-modding-java-edition/minecraft-mods/1272374-v1-3-optimine-fps-boost-optimization-updated</ref> The McRegion format was adopted nearly unchanged, except for the addition of a table of chunk update timestamps. [[Minecraft:JahKob]] has claimed that this format is up to 7 times faster than the previous system.<ref>http://www.pcgamer.com/minecraft-dev-diary-new-block-magic-fiddles/</ref> The difference in a world's total file size between the Region file format and the Alpha level format is negligible.

{{Anchor|Region files|Region file location}}

== Location ==
Region files are found in your [[Minecraft:Java Edition level format|Java Edition world]] directory in the following directories:
* directory/entities
* directory/poi
* directory/region
Where directory may refer to the Minecraft world save directory.

In which, the region files will take the form <code>r.''x''.''z''.mcr</code>.
Or when referring to the [[Minecraft:Anvil file format]], the same but with the <code>.mca</code> file extension instead.

The X and Z position of a region file is determined through the floor of dividing the chunk [[Minecraft:coordinates]] by 32.
For example, a chunk at (30, -3) would be in the region (0, -1), and the chunk at (1500, -600) would be at (46, -19).

Written in code, this is more commonly achieved through performing an [[Wikipedia:Arithmetic shift|Arithmetic shift]] 5 bits to the right.
Note that an ''arithmetic shift'' is different from a [[Wikipedia:Logical shift|Logical shift]].
Most programming languages will perform this when using a [[Minecraft:wikipedia:Signed number representations|signed integer]].

Where getting the block position will be as simple as using 512 instead of 32. (<math>32\cdot16</math>)
And when shifting using 9 instead of 5. (<math>\text{log}_2\left(512\right)</math>)

Why bit shifting is used over standard division, even when using integers has to do that
integer division will ''only'' result in floored division if the integer is positive.
If the integer is negative, which it will be 50% of the time, the result is rounded up as opposed to rounded down.

=== Example ===
{{:Calculators/Chunk coordinates}}

== Structure ==

A region file is built-up out of sectors. These sectors are 4KiB large,
which is equal to the common [[Minecraft:wikipedia:Page (computer memory)|memory page]] size for [[Minecraft:wikipedia:Kernel (operating system)|operating system kernels]].
The entire file is sector-aligned, and the total size should thus be a multiple of 4KiB.
If the file isn't aligned to this boundary there is a possibility that it is corrupt.

The file has a header of two tables containing the chunk data.
Sectors following these tables may be allocated to a chunk.
When a chunk is newly created, or grows in sectors, the code will look for this number of sequential sectors that are free.
If it fails to find this, the chunk will be appended to the end of the file.

{| class="wikitable" data-description="Sector-level layout of the Region file"
|-
! Sector
! 0, 1
! 2...
|-
! Description
| Header, contains payload metadata.
| Payload data and unused sectors.
|}

=== Header ===
The first two sectors of the file contain the two headers, occupying one sector each.
The first table containing the position data of the chunks in the region file itself, the second providing timestamps for the last update of said chunks.

These tables compose of a 1024 element list (<math>32^2</math>) containing [[Minecraft:wikipedia:big-endian|big-endian]], 32-bit integers.
Each chunk has a corresponding X and Z position.
This is computed through floored division, and taking the [[Minecraft:wikipedia:modulo|modulo]] of the index, here represented as "i"
* <math>x=i\mod{32}</math>
* <math>z=\left\lfloor\frac{i}{32}\right\rfloor</math>
With the reverse being done here:
* <math>i=x+32z</math>
Ensuring X and Z are constrained to a value from 0..31 (inclusive), i.e. the result of a modulo of 32.

To read the position data out of the first table will require reading bytes <math>4i</math> to <math>4i+4</math> (exclusive).
The same can be done for the location data, but adding 1024 to both results.

The location data is stored with a specific format, with the first 3 bytes referring to
the offset in sectors from the start of the file.
The last, and least significant byte giving us the size in sectors of the chunk's data.

This implicitly means that the maximum amount of sectors for a chunk is 255, and thus 1MiB.

{| class="wikitable" data-description="Byte-level layout of location data"
|-
! Byte
! 0
! 1
! 2
! 3
|-
! Description
| colspan="3" | Offset
| Length
|}

=== Payload ===

Chunk data begins with a (big-endian) four-byte signed length field that 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'' does not accept files in which the last chunk is not padded. Note that this padding is not included in the length field.

{| class="wikitable" data-description="Chunk data bytes"
|-
! byte
! 0
! 1
! 2
! 3
! 4
! 5...
|-
! description
| colspan="4" | length (in bytes)
| compression type
| compressed data (length-1 bytes)
|}

There are currently five defined compression schemes:

{| class="wikitable" data-description="Compression schemes"
|-
! value
! method
|-
| 1
| GZip (RFC1952) (unused in practice)
|-
| 2
| Zlib (RFC1950)
|-
|3since a version before 1.15.1
|Uncompressed
|-
|4
|[[Minecraft:wikipedia:LZ4 (compression algorithm)|LZ4]] (since [[Minecraft:24w04a]], enabled in [[Minecraft:server.properties]])
|-
|127
|Custom compression algorithm (since [[Minecraft:24w05a]], for third-party servers)
A namespaced string must follow representing the algorithm used. The string is preceded by its length, encoded as an unsigned 16-bit integer.
|}

The uncompressed data is in [[Minecraft:NBT format]] and follows the information detailed on the [[Minecraft: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 are always saved using compression scheme 2 by the official client.

If the value of compression scheme increases by 128, the compressed data is saved in a file called <code>c.''x''.''z''.mcc</code>, where x and z are the chunk's coordinates, instead of the usual position.

== Migration and level.dat ==
[[File:Convert.png|thumb|How ''Minecraft'' looks when converting to the new format.]]
Beta 1.3 converts any "old" chunks into region files before loading the world, rather than incrementally, as they are loaded during play. As part of the conversion, <code>level.dat</code> is updated with TAG_Int("version") (note case) set to 19132. Beta 1.3 also introduces a new level name field, TAG_String("LevelName"). A new TAG_Byte("Sleeping") was introduced in player TAG_Compounds - level.dat in singleplayer, [player name].dat in multiplayer that indicates whether the player is in a bed. It has value of 1 (true) or 0 (false). In [[Minecraft:Java Edition Beta 1.8|Beta 1.8]], TAG_Int("GameType") was added. In [[Minecraft:Java Edition 1.0.0|1.0.0]], TAG_byte("hardcore") was added.

The format of [[Minecraft:Java Edition level format#level.dat format|level.dat]] is otherwise unchanged.

== See also ==

*[[Minecraft:Chunk format/McRegion|McRegion chunk format]]
*[[Minecraft:Java Edition level format]]
*[[Minecraft:Chunk format]]
*[[Minecraft:Anvil file format]]

== External links ==
*[https://web.archive.org/web/20120314044006/http://www.mojang.com/2011/02/minecraft-save-file-format-in-beta-1-3/ Mojang announcement of new region format; Jeb helping tool-makers]
*[http://www.minecraftforum.net/forums/mapping-and-modding/minecraft-mods/mods-discussion/1346703-mod-mcregion-v5-optimized-saves-1-2_02 McRegion]
*[http://pastebin.com/niWTqLvk RegionFile in Java]
*[http://pastebin.com/jvZ1yhAd RegionFileCache in Java]
*[https://dinnerbone.com/minecraft/tools/coordinates/ Find region file from coordinates]

== References ==

<references />

== Notes ==
{{Fnlist}}

== Software ==
The community has developed programs to work with region files:
{| class="wikitable" style="width: 100%" data-description="Region file editors"
|-
! Name
! Description
! Screenshot
|-
| [http://www.minecraftforum.net/forums/mapping-and-modding/minecraft-mods/mods-discussion/1346703-mod-mcregion-v5-optimized-saves-1-2_02 McRegion]
| This mod optimizes how chunks are stored on the disk, meaning pauses to load or save a chunk as the player moves around a world become much shorter and less noticeable.
|
|-
| [http://www.minecraftforum.net/forums/mapping-and-modding/minecraft-tools/1261480-minecraft-region-fixer 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.
|
|-
| [http://minecraft.tournier.org 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.
|
|-
| [https://lotr-minecraft-mod-exiles.fandom.com/wiki/Minecraft_Region_Scanner Region Scanner]
| A [[Minecraft:Java Edition 1.7.10]] (only) Java command line utility to analyze and mass edit region files
|
|}

== Navigation ==
{{Navbox Java Edition technical|general}}

[[Category:Development]]

[[Minecraft:de:Spielstand-Speicherung/Region Format]]
[[Minecraft:fr:Format de fichier Région]]
[[Minecraft:ja:Regionファイルフォーマット]]
[[Minecraft:nl:Regio bestandsformaat]]
[[Minecraft:zh:区域文件格式]]

Minecraft:Region file format - Revision history

SyncBot: Sync: new page from Minecraft