Schemas describing how to upgrade saved block data in older Minecraft: Bedrock Edition world saves

dev-master 2022-08-07 19:29 UTC

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 0131_1.18.20.27_beta_to_1.18.30.json.
  • remappedPropertyValues always 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.

type description
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 uvarint32 for strings (tag names and TAG_String values), svarint32 for TAG_Int/TAG_IntArray, and svarint64 for TAG_Long. (I recognize this is inconvenient for parsing, but it was the easiest way to dump the data from BDS. I may change the format in the future.)

Generating NBT upgrade schemas for new versions

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 input_files/old_block_palettes.

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

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_bit were 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


  1. Amended by hand in some cases, due to errors in Bedrock's own blockstate upgrader