Bring Base Metals to Forge 1.21.1 with safe world upgrades

.github/workflows/ci.yml

@@ -1,19 +1,19 @@
-name: Base Metals 1.20.6 CI
+name: Base Metals 1.21.1 CI
 
 on:
   push:
     branches:
-      - master-1.20.6
+      - master-1.21.1
       - 'feature/**'
   pull_request:
     branches:
-      - master-1.20.6
+      - master-1.21.1
 
 permissions:
   contents: read
 
 concurrency:
-  group: basemetals-1.20.6-${{ github.workflow }}-${{ github.ref }}
+  group: basemetals-1.21.1-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
@@ -60,6 +60,9 @@ jobs:
           "$RUNNER_TEMP/nbt-tests/bin/pip" install nbtlib==2.0.4 numpy==2.4.6
           "$RUNNER_TEMP/nbt-tests/bin/python" -m unittest discover -s tools/validation -p 'test_*.py'
 
+      - name: Test upgrade log boundaries
+        run: node --test tools/validation/test_painting_registry.js
+
       - name: Build, test, and audit first candidate
         run: |
           chmod +x ./gradlew
@@ -68,19 +71,19 @@ jobs:
             --no-daemon --stacktrace
           first="$RUNNER_TEMP/basemetals-first"
           mkdir -p "$first"
-          cp build/libs/BaseMetals-3.1.0.120061.jar "$first/"
-          cp build/libs/BaseMetals-3.1.0.120061-sources.jar "$first/"
-          cp build/libs/BaseMetals-3.1.0.120061-javadoc.jar "$first/"
+          cp build/libs/BaseMetals-3.1.1.121011.jar "$first/"
+          cp build/libs/BaseMetals-3.1.1.121011-sources.jar "$first/"
+          cp build/libs/BaseMetals-3.1.1.121011-javadoc.jar "$first/"
           cp build/release/SHA256SUMS "$first/"
 
       - name: Rebuild and prove byte-identical archives
         run: |
           ./gradlew clean assemble verifyReleaseArtifacts writeReleaseChecksums \
             -PorespawnVerificationRepository="${{ steps.orespawn.outputs.repository }}" \
             --no-daemon --stacktrace
-          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.0.120061.jar" build/libs/BaseMetals-3.1.0.120061.jar
-          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.0.120061-sources.jar" build/libs/BaseMetals-3.1.0.120061-sources.jar
-          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.0.120061-javadoc.jar" build/libs/BaseMetals-3.1.0.120061-javadoc.jar
+          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.1.121011.jar" build/libs/BaseMetals-3.1.1.121011.jar
+          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.1.121011-sources.jar" build/libs/BaseMetals-3.1.1.121011-sources.jar
+          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.1.121011-javadoc.jar" build/libs/BaseMetals-3.1.1.121011-javadoc.jar
           cmp "$RUNNER_TEMP/basemetals-first/SHA256SUMS" build/release/SHA256SUMS
 
       - name: Run all required GameTests
@@ -92,14 +95,14 @@ jobs:
       - name: Install official Forge packaged runtimes
         id: forge-runtimes
         run: |
-          server_runtime="$RUNNER_TEMP/forge-1.20.6-50.2.0-server"
-          client_runtime="$RUNNER_TEMP/forge-1.20.6-50.2.0-client"
-          installer="$RUNNER_TEMP/forge-1.20.6-50.2.0-installer.jar"
+          server_runtime="$RUNNER_TEMP/forge-1.21.1-52.1.0-server"
+          client_runtime="$RUNNER_TEMP/forge-1.21.1-52.1.0-client"
+          installer="$RUNNER_TEMP/forge-1.21.1-52.1.0-installer.jar"
           mkdir -p "$server_runtime" "$client_runtime"
           curl --fail --location --retry 3 \
             --output "$installer" \
-            https://maven.minecraftforge.net/net/minecraftforge/forge/1.20.6-50.2.0/forge-1.20.6-50.2.0-installer.jar
-          echo "8789098B077F5486449311A11DC05E977FEB9430913CB15F30B21A2D8AA213EA  $installer" | sha256sum --check --strict
+            https://maven.minecraftforge.net/net/minecraftforge/forge/1.21.1-52.1.0/forge-1.21.1-52.1.0-installer.jar
+          echo "F1B620F2879AD6A5BBE15DABA4D8F81EAB9F5E08004967604960B98996BDEBC4  $installer" | sha256sum --check --strict
           (
             cd "$server_runtime"
             java -jar "$installer" --installServer
@@ -142,21 +145,21 @@ jobs:
       - name: Upload audited release candidate
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
-          name: BaseMetals-1.20.6-${{ github.sha }}
+          name: BaseMetals-1.21.1-${{ github.sha }}
           if-no-files-found: error
           retention-days: 30
           path: |
-            build/libs/BaseMetals-3.1.0.120061.jar
-            build/libs/BaseMetals-3.1.0.120061-sources.jar
-            build/libs/BaseMetals-3.1.0.120061-javadoc.jar
+            build/libs/BaseMetals-3.1.1.121011.jar
+            build/libs/BaseMetals-3.1.1.121011-sources.jar
+            build/libs/BaseMetals-3.1.1.121011-javadoc.jar
             build/release/SHA256SUMS
             CHANGELOG.txt
 
       - name: Upload bounded diagnostics on failure
         if: failure()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
-          name: BaseMetals-1.20.6-diagnostics-${{ github.sha }}
+          name: BaseMetals-1.21.1-diagnostics-${{ github.sha }}
           if-no-files-found: ignore
           retention-days: 14
           path: |

.github/workflows/codeql-analysis.yml

@@ -3,11 +3,11 @@ name: CodeQL
 on:
   push:
     branches:
-      - master-1.20.6
+      - master-1.21.1
       - 'feature/**'
   pull_request:
     branches:
-      - master-1.20.6
+      - master-1.21.1
 
 permissions:
   actions: read

.github/workflows/validate-gradle-build.yml

@@ -3,11 +3,11 @@ name: Validate Gradle Wrapper
 on:
   push:
     branches:
-      - master-1.20.6
+      - master-1.21.1
       - 'feature/**'
   pull_request:
     branches:
-      - master-1.20.6
+      - master-1.21.1
 
 permissions:
   contents: read

CHANGELOG.txt

@@ -1,3 +1,16 @@
+Base Metals 3.1.1.121011
+
+- Fix startup failures when Base Metals is added to an existing modern world, including worlds with LZ4-compressed chunks, external chunks or empty region files.
+- Stop old level.dat_old backups from replacing current player data or enabling legacy terrain protection.
+- Keep genuine legacy upgrades, reloads and later-opened chunks supported, including chunks in nested custom dimensions.
+- Port the released 1.20.6 version to Minecraft 1.21.1 and Forge 52.1.0, keeping Java 21.
+- Keep raw metals, Kiri's ore overlays, filled buckets, High/Low Fantasy and the existing gameplay fixes.
+- Use vanilla copper forms where they overlap, while keeping old Base Metals items and blocks valid in saves.
+- Accept both copper versions in shared ingredients and keep recycling within the material cost.
+- Update recipes, tags, loot, advancements and enchantments for Minecraft 1.21's data formats.
+- Keep arrows and bolts tied to their firing weapon so native enchantments apply after material damage.
+- Use the published OreSpawn 4.1.0.121011 release with the same eleven ore rules and copper defaults.
+
 Base Metals 3.1.0.120061
 
 - Port the released 1.20.1 version to Minecraft 1.20.6, Forge 50.2.0 and Java 21.

README.md

@@ -1,7 +1,7 @@
 [![Discord](https://img.shields.io/badge/Discord-MMD-green.svg?style=flat&logo=Discord)](https://discord.moddev.zone)
 [![CurseForge downloads](https://cf.way2muchnoise.eu/full_base-metals_downloads.svg)](https://www.curseforge.com/minecraft/mc-mods/base-metals)
 [![Supported Minecraft versions](https://cf.way2muchnoise.eu/versions/Minecraft_base-metals_all.svg)](https://www.curseforge.com/minecraft/mc-mods/base-metals)
-[![Build, test, and audit](https://github.com/MinecraftModDevelopmentMods/BaseMetals/actions/workflows/ci.yml/badge.svg?branch=master-1.20.6)](https://github.com/MinecraftModDevelopmentMods/BaseMetals/actions/workflows/ci.yml?query=branch%3Amaster-1.20.6)
+[![Build, test, and audit](https://github.com/MinecraftModDevelopmentMods/BaseMetals/actions/workflows/ci.yml/badge.svg?branch=master-1.21.1)](https://github.com/MinecraftModDevelopmentMods/BaseMetals/actions/workflows/ci.yml?query=branch%3Amaster-1.21.1)
 
 # Base Metals
 
@@ -12,21 +12,21 @@ shields, bows, crossbows, arrows, and bolts. The mod also includes Crack
 Hammers, scythes, metal anvils, the human detector, villager trades,
 advancements, and structure loot.
 
-This is the Minecraft 1.20.6 Forge version, `3.1.0.120061`. It keeps the
-fixes and features from the released 1.20.1 version, including raw metals, ore texture
+This is the Minecraft 1.21.1 Forge version, `3.1.1.121011`. It keeps the
+fixes and features from the released 1.20.6 version, including raw metals, ore texture
 overlays and High/Low Fantasy modes. Existing Base Metals items and blocks keep
 their registry IDs. OreSpawn handles ore generation; MMDLib and Additional Loot
 Tables are no longer needed.
 
 ## Requirements
 
-- Minecraft `1.20.6`
-- Forge `50.2.0` or newer in the Minecraft 1.20.6 Forge 50 line
+- Minecraft `1.21.1`
+- Forge `52.1.0` or newer in the Minecraft 1.21.1 Forge 52 line
 - A current Java 21 runtime
-- OreSpawn `[4.1.0.120061,5.0.0)` on both client and server
+- OreSpawn `[4.1.0.121011,5.0.0)` on both client and server
 
-This version uses OreSpawn `4.1.0.120061`. Put
-`BaseMetals-3.1.0.120061.jar` and a compatible OreSpawn JAR in the `mods`
+This version uses OreSpawn `4.1.0.121011`. Put
+`BaseMetals-3.1.1.121011.jar` and a compatible OreSpawn JAR in the `mods`
 directory. MMDLib and Additional Loot Tables must not be carried forward from
 an older installation. Mineralogy is optional.
 
@@ -44,6 +44,12 @@ limits which items you can make. Recipes use Forge tags, so compatible ores,
 ingots, powders, plates, rods, gears and other components from different mods
 can be used together.
 
+Where vanilla has the same copper forms, recipes now produce vanilla ingots,
+blocks, doors, trapdoors, cut-copper slabs and stairs. The old Base Metals items
+and blocks stay registered and continue working in existing saves. Shared
+ingredient tags accept both versions, so older items and the rest of the copper
+recipe chains remain usable. Other Base Metals copper equipment is unchanged.
+
 Notable mechanics include:
 
 - Crack Hammers crush supported mined blocks through the data-driven
@@ -130,15 +136,19 @@ is unavailable.
 Always perform the first upgrade on a copy of the world and keep the untouched
 original. Read [Migration](docs/MIGRATION.md) before starting an upgraded world.
 
+Adding Base Metals to a modern world does not trigger the old numeric-ID
+conversion just because an older backup is present. Existing player data stays
+in place; genuine legacy upgrades still make backups before changing saved data.
+
 ## Mod and data-pack compatibility
 
 Forge item, block, and fluid tags are Base Metals' public compatibility API.
 
 Compatible tags and the existing recipe data for Mekanism, Thermal, Tinkers'
-Construct and Ender IO are retained, but these integrations are not supported
-on this target: those mods do not publish Forge 1.20.6 builds. Their older jars
-must not be added to this instance. No optional integration API is required to
-compile or launch Base Metals.
+Construct and Ender IO are retained, but their Java integrations are not enabled
+in this Forge 1.21.1 port. Do not add jars made for older Minecraft versions or
+NeoForge to this instance. No optional integration API is required to compile
+or launch Base Metals.
 
 The normal development client loads only Base Metals and OreSpawn.
 
@@ -185,7 +195,7 @@ artifacts. GameTests, smoke probes, migration fixtures, and reference sources
 are isolated from the published JAR.
 
 Release artifacts use Maven coordinate
-`zone.moddev.mc.basemetals:BaseMetals:3.1.0.120061`.
+`zone.moddev.mc.basemetals:BaseMetals:3.1.1.121011`.
 
 Report defects and compatibility problems through the
 [Base Metals issue tracker](https://github.com/MinecraftModDevelopmentMods/BaseMetals/issues).

build.gradle

@@ -9,12 +9,12 @@ plugins {
 ext.mavenizerCompatibilityJar = layout.projectDirectory.file(
         'ci-fixtures/tools/minecraft-mavenizer-0.5.21-orespawn-compat.jar')
 ext.mavenizerCompatibilitySha256 =
-        '4B14145595E900F178A082F2253A756F63897E6F61C2B8B5E7C819B82CD79E8C'
+        '019032A4A26ECB473D403EF017054D5892CE59A9904E8831B452287CD756397E'
 
 ext.mavenizerFixtureChecksums = [
         'minecraft-mavenizer-0.5.21-orespawn-compat.jar': mavenizerCompatibilitySha256,
-        'minecraft-source-compatibility.json': '931DAB31C238D8C9C38239671A61DA0942ADADF80149D6359197EE80A16380A8',
-        'minecraft-mavenizer-0.5.21-orespawn-compat.patch': 'A140C21312C2A5A8AFC56DC0B037B94D222CA68A7B868512B91684CD3754B650',
+        'minecraft-source-compatibility.json': '7F669F225520D0382E76991A8A3E5E4020840F0FA975F7DCB86681D7E7C3F766',
+        'minecraft-mavenizer-0.5.21-orespawn-compat.patch': '84FEA234619CC2D1931E609B22B6E5D96F59366F7D6C2783C3BEE0F726F3E876',
         'LICENSE-MAVENIZER.txt': '20C17D8B8C48A600800DFD14F95D5CB9FF47066A9641DDEAB48DC54AEC96E331'
 ]
 // Mavenizer runs during configuration, so verify its inputs before configuring Forge.
@@ -26,7 +26,7 @@ mavenizerFixtureChecksums.each { name, expected ->
     }
 }
 
-// Forge 50 needs no source repairs. The sealed fixture records that result
+// Forge 52 needs no source repairs. The sealed fixture records that result
 // and stays separate from the mod and its runtime dependencies.
 fgtools.configure('mavenizer') {
     classpath.from(mavenizerCompatibilityJar)

ci-fixtures/tools/README.md

@@ -2,7 +2,7 @@
 
 This directory contains a build-only derivative of MinecraftForge's
 MinecraftMavenizer `0.5.21`. It is used only while ForgeGradle prepares the
-exact Forge `1.20.6-50.2.0` development dependency and is excluded from every
+exact Forge `1.21.1-52.1.0` development dependency and is excluded from every
 Base Metals publication artifact.
 
 ## Provenance and licence
@@ -21,14 +21,14 @@ declaration and one accessor in that record. Missing, partial, duplicate or
 ambiguous states fail preparation. Targets without an explicit rule set are
 left unchanged.
 
-Forge `1.20.6-50.2.0` compiles without source compatibility edits. Its explicit
+Forge `1.21.1-52.1.0` compiles without source compatibility edits. Its explicit
 zero-rule entry proves that result is intentional and target-qualified rather
 than an accidental fall-through. A marker beside Mavenizer's output records
 the target and manifest SHA-256. Reprocessing the same source is idempotent.
 
 The derivative also propagates Gradle offline mode when the build sets
 `ORESPAWN_MAVENIZER_OFFLINE=true`. Mavenizer itself runs on Java 25; Base Metals
-and Minecraft 1.20.6 continue to compile for Java 21.
+and Minecraft 1.21.1 continue to compile for Java 21.
 
 ## Rebuild
 

ci-fixtures/tools/minecraft-mavenizer-0.5.21-orespawn-compat.patch

@@ -371,12 +371,11 @@ index 0000000..702d759
 +{
 +  "schema": 1,
 +  "targets": {
-+    "net.minecraftforge:forge:1.20.6-50.2.0": {
++    "net.minecraftforge:forge:1.21.1-52.1.0": {
 +      "expectedApplications": 0,
 +      "rules": []
 +    }
 +  }
 +}
 -- 
 2.55.0.windows.3
-

ci-fixtures/tools/minecraft-source-compatibility.json

@@ -1,7 +1,7 @@
 {
   "schema": 1,
   "targets": {
-    "net.minecraftforge:forge:1.20.6-50.2.0": {
+    "net.minecraftforge:forge:1.21.1-52.1.0": {
       "expectedApplications": 0,
       "rules": []
     }

docs/COMPATIBILITY.md

@@ -6,16 +6,21 @@ plates, rods, gears, casings, dense plates, crushed and purified ores, crystals,
 shards, clumps, dirty dusts, and molten fluids.
 
 Adamantite, Adamantium, Adamant, Quicksilver, and steel-sprocket names are
-forwarding tags. Copper-consuming recipes accept `forge:ingots/copper`, except
-Base Metals' own compacting and decompacting recipes, whose unambiguous output
-must remain the Base Metals item. Copper ore and storage tags contain both
-vanilla and Base Metals entries; Base Metals copper ore smelts to the Base
-Metals ingot.
+forwarding tags. Copper-consuming recipes accept `forge:ingots/copper`.
+Copper ingots, storage blocks, doors, trapdoors, slabs and stairs use their
+vanilla equivalents as new recipe outputs. The old Base Metals IDs remain
+registered; their ingredient tags include both versions. Copper ore and powders
+smelt to vanilla copper ingots. Existing copper equipment remains usable.
+
+Vanilla copper trapdoors cost three ingots each, while the old Base Metals
+trapdoors cost four. Their separate recycling recipes return those respective
+amounts, so the new recipes cannot turn three ingots into four. Other retained
+recycling recipes also accept the appropriate vanilla equivalent.
 
 The tags and existing integration data for Mekanism, Thermal, Tinkers' Construct
-and Ender IO remain available for future compatibility work. None currently
-has a published Forge 1.20.6 build, so their Java API hooks and runtime jars
-are not included in this port. Do not substitute jars made for 1.20.1 or NeoForge.
+and Ender IO remain available for future compatibility work. Their Java API hooks
+and runtime jars are not included in this Forge 1.21.1 port. Do not substitute
+jars made for older Minecraft versions or NeoForge.
 
 Other processors can use the shared Forge tags without a direct Java integration.
 

docs/MIGRATION.md

@@ -2,7 +2,7 @@
 
 Always upgrade a copy and retain the original legacy world. Install Base Metals
 3.1.0 and OreSpawn 4.1.0, but do not carry MMDLib, Additional Loot Tables, the
-OreSpawn 3 plugin, or the old native fallback generator into the 1.20.6 instance.
+OreSpawn 3 plugin, or the old native fallback generator into the 1.21.1 instance.
 
 Minecraft's data fixer cannot identify third-party numeric block IDs from
 before the 1.13 flattening. Base Metals snapshots those positions, runs
@@ -88,7 +88,7 @@ The mode is a server or modpack setting, not a setting stored in each world.
 
 ## Moving from 1.20.1
 
-Minecraft 1.20.6 stores item properties as components rather than the older item
+Minecraft 1.21.1 stores item properties as components rather than the older item
 tag. Base Metals keeps names, enchantments, durability and custom data during
 that conversion. Saved arrows and bolts also retain their ammunition.
 
@@ -112,3 +112,19 @@ dimensions, and heights.
 The generated manifests at `data/basemetals/registry_manifest_1_12.json` and
 `data/basemetals/registry_manifest.json` document the runtime baseline,
 restored content, and explicit 1.18 additions.
+
+## Existing modern worlds
+
+Modern worlds do not need the old numeric-ID conversion. Base Metals only runs
+it after confirming an older source save. A leftover `level.dat_old` does not
+replace the current player or turn on legacy terrain protection.
+
+For a genuine upgrade, the original single-player record is captured before
+Minecraft reads it. The world-local migration sidecar keeps the source version
+and saved registry map for reloads and chunks opened later; it does not store
+a player record. A saved registry map from an earlier upgrade takes precedence
+over an older backup.
+
+Chunk reading uses Minecraft's supported region formats. Empty region files
+are left alone, and backups include external chunk files when their region
+needs conversion.