diff --git a/tools/generate-item-upgrade-schema.php b/tools/generate-item-upgrade-schema.php
new file mode 100644
index 000000000..5e8c9f008
--- /dev/null
+++ b/tools/generate-item-upgrade-schema.php
@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This script is used to generate a version-to-version item upgrade schema.
+ * The following inputs are required:
+ * - A full item mapping table from a current version (e.g. r16_to_current_block_map.json)
+ * - A directory containing schemas for previous versions' incremental updates
+ */
+namespace pocketmine\tools\generate_item_upgrade_schema;
+
+use pocketmine\errorhandler\ErrorToExceptionHandler;
+use Webmozart\PathUtil\Path;
+use function count;
+use function file_get_contents;
+use function file_put_contents;
+use function is_array;
+use function json_decode;
+use function json_encode;
+use function ksort;
+use function scandir;
+
+require __DIR__ . '/vendor/autoload.php';
+
+if(count($argv) !== 4){
+	\GlobalLogger::get()->error("Required arguments: path to mapping table, path to current schemas, path to output file");
+	exit(1);
+}
+
+[, $mappingTableFile, $upgradeSchemasDir, $outputFile] = $argv;
+
+$target = json_decode(ErrorToExceptionHandler::trapAndRemoveFalse(fn() => file_get_contents($mappingTableFile)), true, JSON_THROW_ON_ERROR);
+if(!is_array($target)){
+	\GlobalLogger::get()->error("Invalid mapping table file");
+	exit(1);
+}
+
+$files = ErrorToExceptionHandler::trapAndRemoveFalse(fn() => scandir($upgradeSchemasDir, SCANDIR_SORT_ASCENDING));
+
+$merged = [];
+foreach($files as $file){
+	if($file === "." || $file === ".."){
+		continue;
+	}
+	\GlobalLogger::get()->info("Processing schema file $file");
+	$data = json_decode(ErrorToExceptionHandler::trapAndRemoveFalse(fn() => file_get_contents(Path::join($upgradeSchemasDir, $file))), associative: true, flags: JSON_THROW_ON_ERROR);
+	if(!is_array($data)){
+		\GlobalLogger::get()->error("Invalid schema file $file");
+		exit(1);
+	}
+	foreach(($data["renamedIds"] ?? []) as $oldId => $newId){
+		if(isset($merged["simple"][$oldId])){
+			\GlobalLogger::get()->warning("Duplicate rename for $oldId in file $file (was " . $merged["simple"][$oldId] . ", now $newId)");
+		}
+		$merged["simple"][$oldId] = $newId;
+	}
+
+	foreach(($data["remappedMetas"] ?? []) as $oldId => $mappings){
+		foreach($mappings as $meta => $newId){
+			if(isset($merged["complex"][$oldId][$meta])){
+				\GlobalLogger::get()->warning("Duplicate meta remap for $oldId meta $meta in file $file (was " . $merged["complex"][$oldId][$meta] . ", now $newId)");
+			}
+			$merged["complex"][$oldId][$meta] = $newId;
+		}
+	}
+}
+
+$newDiff = [];
+
+foreach($target["simple"] as $oldId => $newId){
+	if(($merged["simple"][$oldId] ?? null) !== $newId){
+		$newDiff["renamedIds"][$oldId] = $newId;
+	}
+}
+if(isset($newDiff["renamedIds"])){
+	ksort($newDiff["renamedIds"], SORT_STRING);
+}
+
+foreach($target["complex"] as $oldId => $mappings){
+	foreach($mappings as $meta => $newId){
+		if(($merged["complex"][$oldId][$meta] ?? null) !== $newId){
+			if($oldId === "minecraft:spawn_egg" && $meta === 130 && ($newId === "minecraft:axolotl_bucket" || $newId === "minecraft:axolotl_spawn_egg")){
+				//TODO: hack for vanilla bug workaround
+				continue;
+			}
+			$newDiff["remappedMetas"][$oldId][$meta] = $newId;
+		}
+	}
+	if(isset($newDiff["remappedMetas"][$oldId])){
+		ksort($newDiff["remappedMetas"][$oldId], SORT_STRING);
+	}
+}
+if(isset($newDiff["remappedMetas"])){
+	ksort($newDiff["remappedMetas"], SORT_STRING);
+}
+ksort($newDiff, SORT_STRING);
+
+\GlobalLogger::get()->info("Writing output file to $outputFile");
+file_put_contents($outputFile, json_encode($newDiff, JSON_PRETTY_PRINT | JSON_FORCE_OBJECT));