Schemas describing how to upgrade saved block data in older Minecraft: Bedrock Edition world saves
This package is auto-updated.
Last update: 2023-01-07 20:36:06 UTC
(Mostly) auto-generated schemas for upgrading blockstates found in older Minecraft: Bedrock worlds
These schemas describe how to upgrade blockstate NBT from one version to the next. The structure of the schema is described in
nbt_upgrade_schema_schema.json. An example implementation can be seen in PocketMine-MP 5.0.0-ALPHA2.
- Mojang don't always bump the format version when making backwards-incompatible changes. A prominent example of this is in the
remappedPropertyValuesalways uses the old property name, if the names were changed.
This JSON file contains a mapping of string ID -> legacy ID for all blocks known up 1.16.0.
Technically, you'd only need everything up to 1.2.13, but the excess might be handy in some cases.
This binary file contains a mapping of all known valid 1.12.0 block ID/meta combinations to their corresponding blockstate NBTs as of 1.18.10.
The following structure is repeated until EOF. There is no length prefix, so you have to read to EOF to read all the mappings.
|unsigned varint32||1.12 block string ID length|
|byte||1.12 block string ID|
|little-endian int16||1.12 block metadata|
|TAG_Compound (varint format)||1.18.10 NBT blockstate corresponding to the given 1.12 block. Varint NBT uses
First, you need to get a
.bin mapping file, which you can obtain using the current version of BDS + pmmp/mapping mod. It requires that you place the palette for the previous version in
The output file will be placed in
mapping_files/old_palette_mappings. This file is then provided as the input for the schema generator script, which produces the JSON schemas like the ones you see in this repo.
Currently the code needed for this is baked into an experimental branch of PocketMine-MP; it's planned to separate it into its own library in the future.
Since Minecraft Bedrock doesn't auto-upgrade terrain or inventories unless they've been loaded during a game session, any software that supports Minecraft Bedrock worlds has to accommodate all of the old blockstates all the way back to the first versions that used them, and many backwards-incompatible changes were made since then. If they do not, they may randomly fail to load chunks in older worlds that work just fine in latest Bedrock.
Other projects such as CloudburstMC/BlockStateUpdater attempted to address this by writing library code to deal with the problem; however, this approach comes with several problems:
- it is non-portable (can't be used by a non-JVM language)
- it relies on manual analysis of the Minecraft server binary
- it is created manually by humans, which is naturally an error-prone process
- it may not include all changes due to the game's own code not accounting for all changes (i.e. Mojang themselves sometimes miss things or don't bother to account for things, such as the addition of
This project aims to address the problem by providing schemas describing how to upgrade blockstates without binding the information to any particular language. These schemas are developed for future use in PocketMine-MP.
It has the following advantages which make it desirable:
- the schemas are JSON - any language and any implementation can parse and use them
- the quality of the mappings is guaranteed to be at least as good as Bedrock's own, due to being generated1 from information created by BDS itself using pmmp/mapping and pmmp/BlockPaletteArchive
- it includes changes which are not obvious from analysing the game code - e.g. properties such as
item_frame_photo_bitwere added without a version bump, and the game itself does not have an upgrader to add it
- tiny footprint - the schemas can be added to a binary with almost no noticeable increase in size after compression
Amended by hand in some cases, due to errors in Bedrock's own blockstate upgrader ↩