Namespace rename

src/data/bedrock/block/upgrade/BlockStateUpgradeSchema.php

@@ -0,0 +1,97 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\data\bedrock\block\upgrade;
+
+use pocketmine\data\bedrock\block\upgrade\BlockStateUpgradeSchemaValueRemap as ValueRemap;
+use pocketmine\nbt\tag\Tag;
+use function count;
+
+final class BlockStateUpgradeSchema{
+	/**
+	 * @var string[]
+	 * @phpstan-var array<string, string>
+	 */
+	public array $renamedIds = [];
+
+	/**
+	 * @var Tag[][]
+	 * @phpstan-var array<string, array<string, Tag>>
+	 */
+	public array $addedProperties = [];
+
+	/**
+	 * @var string[][]
+	 * @phpstan-var array<string, list<string>>
+	 */
+	public array $removedProperties = [];
+
+	/**
+	 * @var string[][]
+	 * @phpstan-var array<string, array<string, string>>
+	 */
+	public array $renamedProperties = [];
+
+	/**
+	 * @var ValueRemap[][][]
+	 * @phpstan-var array<string, array<string, list<ValueRemap>>>
+	 */
+	public array $remappedPropertyValues = [];
+
+	/**
+	 * @var BlockStateUpgradeSchemaBlockRemap[][]
+	 * @phpstan-var array<string, list<BlockStateUpgradeSchemaBlockRemap>>
+	 */
+	public array $remappedStates = [];
+
+	public function __construct(
+		public int $maxVersionMajor,
+		public int $maxVersionMinor,
+		public int $maxVersionPatch,
+		public int $maxVersionRevision,
+		private int $priority
+	){}
+
+	public function getVersionId() : int{
+		return ($this->maxVersionMajor << 24) | ($this->maxVersionMinor << 16) | ($this->maxVersionPatch << 8) | $this->maxVersionRevision;
+	}
+
+	public function getPriority() : int{ return $this->priority; }
+
+	public function isEmpty() : bool{
+		foreach([
+			$this->renamedIds,
+			$this->addedProperties,
+			$this->removedProperties,
+			$this->renamedProperties,
+			$this->remappedPropertyValues,
+			$this->remappedStates,
+		] as $list){
+			if(count($list) !== 0){
+				return false;
+			}
+		}
+
+		return true;
+	}
+}

src/data/bedrock/block/upgrade/BlockStateUpgradeSchemaBlockRemap.php

@@ -0,0 +1,55 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\data\bedrock\block\upgrade;
+
+use pocketmine\nbt\tag\CompoundTag;
+use pocketmine\nbt\tag\Tag;
+use pocketmine\utils\Utils;
+
+final class BlockStateUpgradeSchemaBlockRemap{
+
+	public CompoundTag $oldState;
+	public CompoundTag $newState;
+
+	/**
+	 * @param Tag[] $oldState
+	 * @param Tag[] $newState
+	 * @phpstan-param array<string, Tag> $oldState
+	 * @phpstan-param array<string, Tag> $newState
+	 */
+	public function __construct(
+		array $oldState,
+		public string $newName,
+		array $newState
+	){
+		$this->oldState = CompoundTag::create();
+		$this->newState = CompoundTag::create();
+		foreach(Utils::stringifyKeys($oldState) as $k => $v){
+			$this->oldState->setTag($k, $v);
+		}
+		foreach(Utils::stringifyKeys($newState) as $k => $v){
+			$this->newState->setTag($k, $v);
+		}
+	}
+}

src/data/bedrock/block/upgrade/BlockStateUpgradeSchemaUtils.php

@@ -0,0 +1,321 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\data\bedrock\block\upgrade;
+
+use pocketmine\data\bedrock\block\upgrade\model\BlockStateUpgradeSchemaModel;
+use pocketmine\data\bedrock\block\upgrade\model\BlockStateUpgradeSchemaModelBlockRemap;
+use pocketmine\data\bedrock\block\upgrade\model\BlockStateUpgradeSchemaModelTag;
+use pocketmine\data\bedrock\block\upgrade\model\BlockStateUpgradeSchemaModelValueRemap;
+use pocketmine\errorhandler\ErrorToExceptionHandler;
+use pocketmine\nbt\tag\ByteTag;
+use pocketmine\nbt\tag\IntTag;
+use pocketmine\nbt\tag\StringTag;
+use pocketmine\nbt\tag\Tag;
+use pocketmine\utils\Utils;
+use Webmozart\PathUtil\Path;
+use function array_map;
+use function count;
+use function file_get_contents;
+use function get_debug_type;
+use function gettype;
+use function implode;
+use function is_object;
+use function json_decode;
+use function ksort;
+use function str_pad;
+use function strval;
+use const JSON_THROW_ON_ERROR;
+use const SORT_NUMERIC;
+use const STR_PAD_LEFT;
+
+final class BlockStateUpgradeSchemaUtils{
+
+	public static function describe(BlockStateUpgradeSchema $schema) : string{
+		$lines = [];
+		$lines[] = "Renames:";
+		foreach($schema->renamedIds as $rename){
+			$lines[] = "- $rename";
+		}
+		$lines[] = "Added properties:";
+		foreach(Utils::stringifyKeys($schema->addedProperties) as $blockName => $tags){
+			foreach(Utils::stringifyKeys($tags) as $k => $v){
+				$lines[] = "- $blockName has $k added: $v";
+			}
+		}
+
+		$lines[] = "Removed properties:";
+		foreach(Utils::stringifyKeys($schema->removedProperties) as $blockName => $tagNames){
+			foreach($tagNames as $tagName){
+				$lines[] = "- $blockName has $tagName removed";
+			}
+		}
+		$lines[] = "Renamed properties:";
+		foreach(Utils::stringifyKeys($schema->renamedProperties) as $blockName => $tagNames){
+			foreach(Utils::stringifyKeys($tagNames) as $oldTagName => $newTagName){
+				$lines[] = "- $blockName has $oldTagName renamed to $newTagName";
+			}
+		}
+		$lines[] = "Remapped property values:";
+		foreach(Utils::stringifyKeys($schema->remappedPropertyValues) as $blockName => $remaps){
+			foreach(Utils::stringifyKeys($remaps) as $tagName => $oldNewList){
+				foreach($oldNewList as $oldNew){
+					$lines[] = "- $blockName has $tagName value changed from $oldNew->old to $oldNew->new";
+				}
+			}
+		}
+		return implode("\n", $lines);
+	}
+
+	public static function tagToJsonModel(Tag $tag) : BlockStateUpgradeSchemaModelTag{
+		$model = new BlockStateUpgradeSchemaModelTag();
+		if($tag instanceof IntTag){
+			$model->int = $tag->getValue();
+		}elseif($tag instanceof StringTag){
+			$model->string = $tag->getValue();
+		}elseif($tag instanceof ByteTag){
+			$model->byte = $tag->getValue();
+		}else{
+			throw new \UnexpectedValueException("Unexpected value type " . get_debug_type($tag));
+		}
+
+		return $model;
+	}
+
+	private static function jsonModelToTag(BlockStateUpgradeSchemaModelTag $model) : Tag{
+		return match(true){
+			isset($model->byte) && !isset($model->int) && !isset($model->string) => new ByteTag($model->byte),
+			!isset($model->byte) && isset($model->int) && !isset($model->string) => new IntTag($model->int),
+			!isset($model->byte) && !isset($model->int) && isset($model->string) => new StringTag($model->string),
+			default => throw new \UnexpectedValueException("Malformed JSON model tag, expected exactly one of 'byte', 'int' or 'string' properties")
+		};
+	}
+
+	public static function fromJsonModel(BlockStateUpgradeSchemaModel $model, int $priority) : BlockStateUpgradeSchema{
+		$result = new BlockStateUpgradeSchema(
+			$model->maxVersionMajor,
+			$model->maxVersionMinor,
+			$model->maxVersionPatch,
+			$model->maxVersionRevision,
+			$priority
+		);
+		$result->renamedIds = $model->renamedIds ?? [];
+		$result->renamedProperties = $model->renamedProperties ?? [];
+		$result->removedProperties = $model->removedProperties ?? [];
+
+		foreach(Utils::stringifyKeys($model->addedProperties ?? []) as $blockName => $properties){
+			foreach(Utils::stringifyKeys($properties) as $propertyName => $propertyValue){
+				$result->addedProperties[$blockName][$propertyName] = self::jsonModelToTag($propertyValue);
+			}
+		}
+
+		$convertedRemappedValuesIndex = [];
+		foreach(Utils::stringifyKeys($model->remappedPropertyValuesIndex ?? []) as $mappingKey => $mappingValues){
+			foreach($mappingValues as $k => $oldNew){
+				$convertedRemappedValuesIndex[$mappingKey][$k] = new BlockStateUpgradeSchemaValueRemap(
+					self::jsonModelToTag($oldNew->old),
+					self::jsonModelToTag($oldNew->new)
+				);
+			}
+		}
+
+		foreach(Utils::stringifyKeys($model->remappedPropertyValues ?? []) as $blockName => $properties){
+			foreach(Utils::stringifyKeys($properties) as $property => $mappedValuesKey){
+				if(!isset($convertedRemappedValuesIndex[$mappedValuesKey])){
+					throw new \UnexpectedValueException("Missing key from schema values index $mappedValuesKey");
+				}
+				$result->remappedPropertyValues[$blockName][$property] = $convertedRemappedValuesIndex[$mappedValuesKey];
+			}
+		}
+
+		foreach(Utils::stringifyKeys($model->remappedStates ?? []) as $oldBlockName => $remaps){
+			foreach($remaps as $remap){
+				$result->remappedStates[$oldBlockName][] = new BlockStateUpgradeSchemaBlockRemap(
+					array_map(fn(BlockStateUpgradeSchemaModelTag $tag) => self::jsonModelToTag($tag), $remap->oldState),
+					$remap->newName,
+					array_map(fn(BlockStateUpgradeSchemaModelTag $tag) => self::jsonModelToTag($tag), $remap->newState),
+				);
+			}
+		}
+
+		return $result;
+	}
+
+	private static function buildRemappedValuesIndex(BlockStateUpgradeSchema $schema, BlockStateUpgradeSchemaModel $model) : void{
+		if(count($schema->remappedPropertyValues) === 0){
+			return;
+		}
+		$dedupMapping = [];
+		$dedupTable = [];
+		$dedupTableMap = [];
+		$counter = 0;
+
+		foreach(Utils::stringifyKeys($schema->remappedPropertyValues) as $blockName => $remaps){
+			foreach(Utils::stringifyKeys($remaps) as $propertyName => $remappedValues){
+				$remappedValuesMap = [];
+				foreach($remappedValues as $oldNew){
+					$remappedValuesMap[$oldNew->old->toString()] = $oldNew;
+				}
+
+				foreach(Utils::stringifyKeys($dedupTableMap) as $dedupName => $dedupValuesMap){
+					if(count($remappedValuesMap) !== count($dedupValuesMap)){
+						continue;
+					}
+
+					foreach(Utils::stringifyKeys($remappedValuesMap) as $oldHash => $remappedOldNew){
+						if(
+							!isset($dedupValuesMap[$oldHash]) ||
+							!$remappedOldNew->old->equals($dedupValuesMap[$oldHash]->old) ||
+							!$remappedOldNew->new->equals($dedupValuesMap[$oldHash]->new)
+						){
+							continue 2;
+						}
+					}
+
+					//we found a match
+					$dedupMapping[$blockName][$propertyName] = $dedupName;
+					continue 2;
+				}
+
+				//no match, add the values to the table
+				$newDedupName = $propertyName . "_" . str_pad(strval($counter++), 2, "0", STR_PAD_LEFT);
+				$dedupTableMap[$newDedupName] = $remappedValuesMap;
+				$dedupTable[$newDedupName] = $remappedValues;
+				$dedupMapping[$blockName][$propertyName] = $newDedupName;
+			}
+		}
+
+		$modelTable = [];
+		foreach(Utils::stringifyKeys($dedupTable) as $dedupName => $valuePairs){
+			foreach($valuePairs as $k => $pair){
+				$modelTable[$dedupName][$k] = new BlockStateUpgradeSchemaModelValueRemap(
+					BlockStateUpgradeSchemaUtils::tagToJsonModel($pair->old),
+					BlockStateUpgradeSchemaUtils::tagToJsonModel($pair->new),
+				);
+			}
+		}
+
+		$model->remappedPropertyValuesIndex = $modelTable;
+		$model->remappedPropertyValues = $dedupMapping;
+	}
+
+	public static function toJsonModel(BlockStateUpgradeSchema $schema) : BlockStateUpgradeSchemaModel{
+		$result = new BlockStateUpgradeSchemaModel();
+		$result->maxVersionMajor = $schema->maxVersionMajor;
+		$result->maxVersionMinor = $schema->maxVersionMinor;
+		$result->maxVersionPatch = $schema->maxVersionPatch;
+		$result->maxVersionRevision = $schema->maxVersionRevision;
+		$result->renamedIds = $schema->renamedIds;
+		$result->renamedProperties = $schema->renamedProperties;
+		$result->removedProperties = $schema->removedProperties;
+
+		foreach(Utils::stringifyKeys($schema->addedProperties) as $blockName => $properties){
+			foreach(Utils::stringifyKeys($properties) as $propertyName => $propertyValue){
+				$result->addedProperties[$blockName][$propertyName] = self::tagToJsonModel($propertyValue);
+			}
+		}
+
+		self::buildRemappedValuesIndex($schema, $result);
+
+		foreach(Utils::stringifyKeys($schema->remappedStates) as $oldBlockName => $remaps){
+			foreach($remaps as $remap){
+				$result->remappedStates[$oldBlockName][] = new BlockStateUpgradeSchemaModelBlockRemap(
+					array_map(fn(Tag $tag) => self::tagToJsonModel($tag), $remap->oldState->getValue()),
+					$remap->newName,
+					array_map(fn(Tag $tag) => self::tagToJsonModel($tag), $remap->newState->getValue()),
+				);
+			}
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Returns a list of schemas ordered by priority. Oldest schemas appear first.
+	 *
+	 * @return BlockStateUpgradeSchema[]
+	 */
+	public static function loadSchemas(string $path, int $currentVersion) : array{
+		$iterator = new \RegexIterator(
+			new \FilesystemIterator(
+				$path,
+				\FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::SKIP_DOTS | \FilesystemIterator::UNIX_PATHS
+			),
+			'/\/(\d{4}).*\.json$/',
+			\RegexIterator::GET_MATCH
+		);
+
+		$result = [];
+
+		/** @var string[] $matches */
+		foreach($iterator as $matches){
+			$filename = $matches[0];
+			$priority = (int) $matches[1];
+
+			$fullPath = Path::join($path, $filename);
+
+			try{
+				$raw = ErrorToExceptionHandler::trapAndRemoveFalse(fn() => file_get_contents($fullPath));
+			}catch(\ErrorException $e){
+				throw new \RuntimeException("Loading schema file $fullPath: " . $e->getMessage(), 0, $e);
+			}
+
+			try{
+				$schema = self::loadSchemaFromString($raw, $priority);
+			}catch(\RuntimeException $e){
+				throw new \RuntimeException("Loading schema file $fullPath: " . $e->getMessage(), 0, $e);
+			}
+
+			if($schema->getVersionId() > $currentVersion){
+				//this might be a beta schema which shouldn't be applicable
+				//TODO: why do we load the whole schema just to throw it away if it's too new? ...
+				continue;
+			}
+
+			$result[$priority] = $schema;
+		}
+
+		ksort($result, SORT_NUMERIC);
+		return $result;
+	}
+
+	public static function loadSchemaFromString(string $raw, int $priority) : BlockStateUpgradeSchema{
+		try{
+			$json = json_decode($raw, false, flags: JSON_THROW_ON_ERROR);
+		}catch(\JsonException $e){
+			throw new \RuntimeException($e->getMessage(), 0, $e);
+		}
+		if(!is_object($json)){
+			throw new \RuntimeException("Unexpected root type of schema file " . gettype($json) . ", expected object");
+		}
+
+		$jsonMapper = new \JsonMapper();
+		try{
+			$model = $jsonMapper->map($json, new BlockStateUpgradeSchemaModel());
+		}catch(\JsonMapper_Exception $e){
+			throw new \RuntimeException($e->getMessage(), 0, $e);
+		}
+
+		return self::fromJsonModel($model, $priority);
+	}
+}

src/data/bedrock/block/upgrade/BlockStateUpgradeSchemaValueRemap.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\data\bedrock\block\upgrade;
+
+use pocketmine\nbt\tag\Tag;
+
+final class BlockStateUpgradeSchemaValueRemap{
+
+	public function __construct(
+		public Tag $old,
+		public Tag $new
+	){}
+}

src/data/bedrock/block/upgrade/BlockStateUpgrader.php

@@ -0,0 +1,184 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\data\bedrock\block\upgrade;
+
+use pocketmine\data\bedrock\block\BlockStateData;
+use pocketmine\nbt\tag\CompoundTag;
+use pocketmine\nbt\tag\Tag;
+use pocketmine\utils\Utils;
+use function ksort;
+use const SORT_NUMERIC;
+
+final class BlockStateUpgrader{
+	/** @var BlockStateUpgradeSchema[][] */
+	private array $upgradeSchemas = [];
+
+	/**
+	 * @param BlockStateUpgradeSchema[] $upgradeSchemas
+	 * @phpstan-param array<int, BlockStateUpgradeSchema> $upgradeSchemas
+	 */
+	public function __construct(array $upgradeSchemas){
+		foreach($upgradeSchemas as $schema){
+			$this->addSchema($schema);
+		}
+	}
+
+	public function addSchema(BlockStateUpgradeSchema $schema) : void{
+		$schemaList = $this->upgradeSchemas[$schema->getVersionId()] ?? [];
+
+		$priority = $schema->getPriority();
+		if(isset($schemaList[$priority])){
+			throw new \InvalidArgumentException("Cannot add two schemas to the same version with the same priority");
+		}
+		$schemaList[$priority] = $schema;
+		ksort($schemaList, SORT_NUMERIC);
+		$this->upgradeSchemas[$schema->getVersionId()] = $schemaList;
+
+		ksort($this->upgradeSchemas, SORT_NUMERIC);
+	}
+
+	public function upgrade(BlockStateData $blockStateData) : BlockStateData{
+		$version = $blockStateData->getVersion();
+		foreach($this->upgradeSchemas as $resultVersion => $schemas){
+			if($version > $resultVersion){
+				//even if this is actually the same version, we have to apply it anyway because mojang are dumb and
+				//didn't always bump the blockstate version when changing it :(
+				continue;
+			}
+			foreach($schemas as $schema){
+				$oldName = $blockStateData->getName();
+				if(isset($schema->remappedStates[$oldName])){
+					foreach($schema->remappedStates[$oldName] as $remap){
+						if($blockStateData->getStates()->equals($remap->oldState)){
+							$blockStateData = new BlockStateData($remap->newName, clone $remap->newState, $resultVersion);
+							continue 2;
+						}
+					}
+				}
+				$newName = $schema->renamedIds[$oldName] ?? null;
+
+				$stateChanges = 0;
+				$states = $blockStateData->getStates();
+
+				$states = $this->applyPropertyAdded($schema, $oldName, $states, $stateChanges);
+				$states = $this->applyPropertyRemoved($schema, $oldName, $states, $stateChanges);
+				$states = $this->applyPropertyRenamedOrValueChanged($schema, $oldName, $states, $stateChanges);
+				$states = $this->applyPropertyValueChanged($schema, $oldName, $states, $stateChanges);
+
+				if($newName !== null || $stateChanges > 0){
+					$blockStateData = new BlockStateData($newName ?? $oldName, $states, $resultVersion);
+					//don't break out; we may need to further upgrade the state
+				}
+			}
+		}
+
+		return $blockStateData;
+	}
+
+	private function cloneIfNeeded(CompoundTag $states, int &$stateChanges) : CompoundTag{
+		if($stateChanges === 0){
+			$states = clone $states;
+		}
+		$stateChanges++;
+
+		return $states;
+	}
+
+	private function applyPropertyAdded(BlockStateUpgradeSchema $schema, string $oldName, CompoundTag $states, int &$stateChanges) : CompoundTag{
+		$newStates = $states;
+		if(isset($schema->addedProperties[$oldName])){
+			foreach(Utils::stringifyKeys($schema->addedProperties[$oldName]) as $propertyName => $value){
+				$oldValue = $states->getTag($propertyName);
+				if($oldValue === null){
+					$newStates = $this->cloneIfNeeded($newStates, $stateChanges);
+					$newStates->setTag($propertyName, $value);
+				}
+			}
+		}
+
+		return $newStates;
+	}
+
+	private function applyPropertyRemoved(BlockStateUpgradeSchema $schema, string $oldName, CompoundTag $states, int &$stateChanges) : CompoundTag{
+		$newStates = $states;
+		if(isset($schema->removedProperties[$oldName])){
+			foreach($schema->removedProperties[$oldName] as $propertyName){
+				if($states->getTag($propertyName) !== null){
+					$newStates = $this->cloneIfNeeded($newStates, $stateChanges);
+					$newStates->removeTag($propertyName);
+				}
+			}
+		}
+
+		return $newStates;
+	}
+
+	private function locateNewPropertyValue(BlockStateUpgradeSchema $schema, string $oldName, string $oldPropertyName, Tag $oldValue) : Tag{
+		if(isset($schema->remappedPropertyValues[$oldName][$oldPropertyName])){
+			foreach($schema->remappedPropertyValues[$oldName][$oldPropertyName] as $mappedPair){
+				if($mappedPair->old->equals($oldValue)){
+					return $mappedPair->new;
+				}
+			}
+		}
+
+		return $oldValue;
+	}
+
+	private function applyPropertyRenamedOrValueChanged(BlockStateUpgradeSchema $schema, string $oldName, CompoundTag $states, int &$stateChanges) : CompoundTag{
+		if(isset($schema->renamedProperties[$oldName])){
+			foreach(Utils::stringifyKeys($schema->renamedProperties[$oldName]) as $oldPropertyName => $newPropertyName){
+				$oldValue = $states->getTag($oldPropertyName);
+				if($oldValue !== null){
+					$states = $this->cloneIfNeeded($states, $stateChanges);
+					$states->removeTag($oldPropertyName);
+
+					//If a value remap is needed, we need to do it here, since we won't be able to locate the property
+					//after it's been renamed - value remaps are always indexed by old property name for the sake of
+					//being able to do changes in any order.
+					$states->setTag($newPropertyName, $this->locateNewPropertyValue($schema, $oldName, $oldPropertyName, $oldValue));
+				}
+			}
+		}
+
+		return $states;
+	}
+
+	private function applyPropertyValueChanged(BlockStateUpgradeSchema $schema, string $oldName, CompoundTag $states, int &$stateChanges) : CompoundTag{
+		if(isset($schema->remappedPropertyValues[$oldName])){
+			foreach(Utils::stringifyKeys($schema->remappedPropertyValues[$oldName]) as $oldPropertyName => $remappedValues){
+				$oldValue = $states->getTag($oldPropertyName);
+				if($oldValue !== null){
+					$newValue = $this->locateNewPropertyValue($schema, $oldName, $oldPropertyName, $oldValue);
+					if($newValue !== $oldValue){
+						$states = $this->cloneIfNeeded($states, $stateChanges);
+						$states->setTag($oldPropertyName, $newValue);
+					}
+				}
+			}
+		}
+
+		return $states;
+	}
+}

src/data/bedrock/block/upgrade/LegacyBlockStateMapper.php

@@ -0,0 +1,73 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\data\bedrock\block\upgrade;
+
+use pocketmine\data\bedrock\block\BlockStateData;
+use pocketmine\data\bedrock\LegacyBlockIdToStringIdMap;
+use pocketmine\network\mcpe\protocol\serializer\NetworkNbtSerializer;
+use pocketmine\utils\BinaryStream;
+
+/**
+ * Handles translating legacy 1.12 block ID/meta into modern blockstates.
+ */
+final class LegacyBlockStateMapper{
+	/**
+	 * @param BlockStateData[][] $mappingTable
+	 * @phpstan-param array<string, array<int, BlockStateData>> $mappingTable
+	 */
+	public function __construct(
+		private array $mappingTable,
+		private LegacyBlockIdToStringIdMap $legacyNumericIdMap
+	){}
+
+	public function fromStringIdMeta(string $id, int $meta) : ?BlockStateData{
+		return $this->mappingTable[$id][$meta] ?? $this->mappingTable[$id][0] ?? null;
+	}
+
+	public function fromIntIdMeta(int $id, int $meta) : ?BlockStateData{
+		$stringId = $this->legacyNumericIdMap->legacyToString($id);
+		if($stringId === null){
+			return null;
+		}
+		return $this->fromStringIdMeta($stringId, $meta);
+	}
+
+	public static function loadFromString(string $data, LegacyBlockIdToStringIdMap $idMap) : self{
+		$mappingTable = [];
+
+		$legacyStateMapReader = new BinaryStream($data);
+		$nbtReader = new NetworkNbtSerializer();
+		while(!$legacyStateMapReader->feof()){
+			$id = $legacyStateMapReader->get($legacyStateMapReader->getUnsignedVarInt());
+			$meta = $legacyStateMapReader->getLShort();
+
+			$offset = $legacyStateMapReader->getOffset();
+			$state = $nbtReader->read($legacyStateMapReader->getBuffer(), $offset)->mustGetCompoundTag();
+			$legacyStateMapReader->setOffset($offset);
+			$mappingTable[$id][$meta] = BlockStateData::fromNbt($state);
+		}
+
+		return new self($mappingTable, $idMap);
+	}
+}

src/data/bedrock/block/upgrade/model/BlockStateUpgradeSchemaModel.php

@@ -0,0 +1,98 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\data\bedrock\block\upgrade\model;
+
+use function count;
+use function is_array;
+
+/**
+ * Model for loading upgrade schema data from JSON.
+ */
+final class BlockStateUpgradeSchemaModel implements \JsonSerializable{
+	/** @required */
+	public int $maxVersionMajor;
+	/** @required */
+	public int $maxVersionMinor;
+	/** @required */
+	public int $maxVersionPatch;
+	/** @required */
+	public int $maxVersionRevision;
+
+	/**
+	 * @var string[]
+	 * @phpstan-var array<string, string>
+	 */
+	public array $renamedIds;
+
+	/**
+	 * @var BlockStateUpgradeSchemaModelTag[][]
+	 * @phpstan-var array<string, array<string, BlockStateUpgradeSchemaModelTag>>
+	 */
+	public array $addedProperties;
+
+	/**
+	 * @var string[][]
+	 * @phpstan-var array<string, list<string>>
+	 */
+	public array $removedProperties;
+
+	/**
+	 * @var string[][]
+	 * @phpstan-var array<string, array<string, string>>
+	 */
+	public array $renamedProperties;
+
+	/**
+	 * @var string[][]
+	 * @phpstan-var array<string, array<string, string>>
+	 */
+	public array $remappedPropertyValues;
+
+	/**
+	 * @var BlockStateUpgradeSchemaModelValueRemap[][]
+	 * @phpstan-var array<string, list<BlockStateUpgradeSchemaModelValueRemap>>
+	 */
+	public array $remappedPropertyValuesIndex;
+
+	/**
+	 * @var BlockStateUpgradeSchemaModelBlockRemap[][]
+	 * @phpstan-var array<string, list<BlockStateUpgradeSchemaModelBlockRemap>>
+	 */
+	public array $remappedStates;
+
+	/**
+	 * @return mixed[]
+	 */
+	public function jsonSerialize() : array{
+		$result = (array) $this;
+
+		foreach($result as $k => $v){
+			if(is_array($v) && count($v) === 0){
+				unset($result[$k]);
+			}
+		}
+
+		return $result;
+	}
+}

src/data/bedrock/block/upgrade/model/BlockStateUpgradeSchemaModelBlockRemap.php

@@ -0,0 +1,56 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\data\bedrock\block\upgrade\model;
+
+final class BlockStateUpgradeSchemaModelBlockRemap{
+
+	/**
+	 * @var BlockStateUpgradeSchemaModelTag[]
+	 * @phpstan-var array<string, BlockStateUpgradeSchemaModelTag>
+	 * @required
+	 */
+	public array $oldState;
+
+	/** @required */
+	public string $newName;
+
+	/**
+	 * @var BlockStateUpgradeSchemaModelTag[]
+	 * @phpstan-var array<string, BlockStateUpgradeSchemaModelTag>
+	 * @required
+	 */
+	public array $newState;
+
+	/**
+	 * @param BlockStateUpgradeSchemaModelTag[] $oldState
+	 * @param BlockStateUpgradeSchemaModelTag[] $newState
+	 * @phpstan-param array<string, BlockStateUpgradeSchemaModelTag> $oldState
+	 * @phpstan-param array<string, BlockStateUpgradeSchemaModelTag> $newState
+	 */
+	public function __construct(array $oldState, string $newName, array $newState){
+		$this->oldState = $oldState;
+		$this->newName = $newName;
+		$this->newState = $newState;
+	}
+}

src/data/bedrock/block/upgrade/model/BlockStateUpgradeSchemaModelTag.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\data\bedrock\block\upgrade\model;
+
+final class BlockStateUpgradeSchemaModelTag{
+	public int $byte;
+	public int $int;
+	public string $string;
+}

src/data/bedrock/block/upgrade/model/BlockStateUpgradeSchemaModelValueRemap.php

@@ -0,0 +1,36 @@
+<?php
+
+/*
+ *
+ *  ____            _        _   __  __ _                  __  __ ____
+ * |  _ \ ___   ___| | _____| |_|  \/  (_)_ __   ___      |  \/  |  _ \
+ * | |_) / _ \ / __| |/ / _ \ __| |\/| | | '_ \ / _ \_____| |\/| | |_) |
+ * |  __/ (_) | (__|   <  __/ |_| |  | | | | | |  __/_____| |  | |  __/
+ * |_|   \___/ \___|_|\_\___|\__|_|  |_|_|_| |_|\___|     |_|  |_|_|
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * @author PocketMine Team
+ * @link http://www.pocketmine.net/
+ *
+ *
+ */
+
+declare(strict_types=1);
+
+namespace pocketmine\data\bedrock\block\upgrade\model;
+
+final class BlockStateUpgradeSchemaModelValueRemap{
+	/** @required */
+	public BlockStateUpgradeSchemaModelTag $old;
+	/** @required */
+	public BlockStateUpgradeSchemaModelTag $new;
+
+	public function __construct(BlockStateUpgradeSchemaModelTag $old, BlockStateUpgradeSchemaModelTag $new){
+		$this->old = $old;
+		$this->new = $new;
+	}
+}