Keep companion mod data during 1.18.2 world upgrades

.github/workflows/ci.yml

@@ -43,26 +43,30 @@ jobs:
           echo "repository=$mirror" >> "$GITHUB_OUTPUT"
 
       - name: Build, test, and audit first candidate
+        id: candidate
         run: |
+          version="$(sed -n 's/^mod_version=//p' gradle.properties | tr -d '\r')"
+          [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.118021$ ]]
+          stem="BaseMetals-$version"
+          echo "stem=$stem" >> "$GITHUB_OUTPUT"
           chmod +x ./gradlew
           ./gradlew clean check build javadoc verifyReleaseArtifacts writeReleaseChecksums \
             -PorespawnVerificationRepository="${{ steps.orespawn.outputs.repository }}" \
             --no-daemon --stacktrace
           first="$RUNNER_TEMP/basemetals-first"
           mkdir -p "$first"
-          cp build/libs/BaseMetals-3.1.1.118021.jar "$first/"
-          cp build/libs/BaseMetals-3.1.1.118021-sources.jar "$first/"
-          cp build/libs/BaseMetals-3.1.1.118021-javadoc.jar "$first/"
+          cp "build/libs/$stem.jar" "build/libs/$stem-sources.jar" "build/libs/$stem-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.1.118021.jar" build/libs/BaseMetals-3.1.1.118021.jar
-          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.1.118021-sources.jar" build/libs/BaseMetals-3.1.1.118021-sources.jar
-          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.1.118021-javadoc.jar" build/libs/BaseMetals-3.1.1.118021-javadoc.jar
+          stem="${{ steps.candidate.outputs.stem }}"
+          cmp "$RUNNER_TEMP/basemetals-first/$stem.jar" "build/libs/$stem.jar"
+          cmp "$RUNNER_TEMP/basemetals-first/$stem-sources.jar" "build/libs/$stem-sources.jar"
+          cmp "$RUNNER_TEMP/basemetals-first/$stem-javadoc.jar" "build/libs/$stem-javadoc.jar"
           cmp "$RUNNER_TEMP/basemetals-first/SHA256SUMS" build/release/SHA256SUMS
 
       - name: Run all required GameTests
@@ -128,9 +132,9 @@ jobs:
           if-no-files-found: error
           retention-days: 30
           path: |
-            build/libs/BaseMetals-3.1.1.118021.jar
-            build/libs/BaseMetals-3.1.1.118021-sources.jar
-            build/libs/BaseMetals-3.1.1.118021-javadoc.jar
+            build/libs/${{ steps.candidate.outputs.stem }}.jar
+            build/libs/${{ steps.candidate.outputs.stem }}-sources.jar
+            build/libs/${{ steps.candidate.outputs.stem }}-javadoc.jar
             build/release/SHA256SUMS
             CHANGELOG.txt
 

CHANGELOG.txt

@@ -1,3 +1,7 @@
+Base Metals 3.1.2.118021
+
+- Let companion mods preserve their saved block states, items and entities before Base Metals flattens a Minecraft 1.10 or 1.12 world.
+
 Base Metals 3.1.1.118021
 
 - Fix startup failures when Base Metals is added to an existing modern world, including worlds with external chunks or empty region files.

README.md

@@ -12,7 +12,7 @@ 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.18.2 Forge version, `3.1.1.118021`. It brings over the
+This is the Minecraft 1.18.2 Forge version, `3.1.2.118021`. It brings over the
 fixes and features from the earlier ports, 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
@@ -26,7 +26,7 @@ Tables are no longer needed.
 - OreSpawn `[4.1.0.118021,5.0.0)` on both client and server
 
 This version uses OreSpawn `4.1.0.118021`. Put
-`BaseMetals-3.1.1.118021.jar` and a compatible OreSpawn JAR in the `mods`
+`BaseMetals-3.1.2.118021.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.
 
@@ -130,6 +130,11 @@ 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.
 
+Companion mods can register a `Legacy112MigrationExtension` during common
+setup. It lets them prepare their own saved data and restore block metadata
+before Base Metals' legacy conversion would otherwise discard it. Existing
+Base Metals saves do not need the companion mod to use this upgrade path.
+
 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.
@@ -183,7 +188,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.1.118021`.
+`zone.moddev.mc.basemetals:BaseMetals:3.1.2.118021`.
 
 Report defects and compatibility problems through the
 [Base Metals issue tracker](https://github.com/MinecraftModDevelopmentMods/BaseMetals/issues).

docs/VERSIONS.md

@@ -1,6 +1,6 @@
 # Supported versions
 
-Base Metals `3.1.1.118021` targets Minecraft 1.18.2, Forge 40.3.0 and Java 17.
+Base Metals `3.1.2.118021` targets Minecraft 1.18.2, Forge 40.3.0 and Java 17.
 OreSpawn `4.1.0.118021` is the exact build and test dependency. Clients and
 servers need OreSpawn `[4.1.0.118021,5.0.0)`.
 
@@ -10,7 +10,7 @@ Its SHA-256 is
 `BD8D84A96DAFB7668E95D61B9D72C62AEF3440675473E41244C182C64653356F`.
 
 Release artifacts use Maven coordinate
-`zone.moddev.mc.basemetals:BaseMetals:3.1.1.118021`.
+`zone.moddev.mc.basemetals:BaseMetals:3.1.2.118021`.
 
 The provider remains schema 3, revision 1. OreSpawn 4.1 is needed for the
 configuration-screen API; the provider's eleven rule IDs and 1.18 distributions

gradle.properties

@@ -67,7 +67,7 @@ mod_name=Base Metals
 # The license of the mod. Review your options at https://choosealicense.com/. All Rights Reserved is the default.
 mod_license=LGPL-2.1
 # The mod version. See https://semver.org/
-mod_version=3.1.1.118021
+mod_version=3.1.2.118021
 # The group ID for the mod. It is only important when publishing as an artifact to a Maven repository.
 # This should match the base package used for the mod sources.
 # See https://maven.apache.org/guides/mini/guide-naming-conventions.html

gradle/ide/eclipse.gradle

@@ -304,7 +304,7 @@ def verifyEclipseProductionClasspath = tasks.register('verifyEclipseProductionCl
             }
         }
         String metadata = new File(projectDir, 'bin/main/META-INF/mods.toml').getText('UTF-8')
-        if (metadata.contains('${') || !metadata.contains('version="3.1.1.118021"')) {
+        if (metadata.contains('${') || !metadata.contains('version="3.1.2.118021"')) {
             throw new GradleException('Eclipse output contains unresolved or invalid Base Metals version metadata')
         }
     }

gradle/prepare-forge-client-runtime.py

@@ -23,7 +23,7 @@
 FORGE_INSTALLER_SHA256 = "9434c29790504dcd11ce97cb30dd8891b4b18848982357bc1b5abfa79fb95103"
 VERSION_MANIFEST_URL = "https://piston-meta.mojang.com/mc/game/version_manifest_v2.json"
 ASSET_OBJECT_URL = "https://resources.download.minecraft.net/{prefix}/{digest}"
-USER_AGENT = "BaseMetals-release-validation/3.1.1.118021"
+USER_AGENT = "BaseMetals-release-validation/3.1.2.118021"
 
 
 def digest_file(path: Path, algorithm: str) -> str:

gradle/release/artifacts.gradle

@@ -199,7 +199,7 @@ tasks.register('verifyReleaseConfiguration') {
     dependsOn tasks.named('verifyMavenizerCompatibilityFixture')
     dependsOn tasks.named('verifyJava17Toolchain')
     doLast {
-        if (configuredReleaseIdentity.modVersion != '3.1.1.118021'
+        if (configuredReleaseIdentity.modVersion != '3.1.2.118021'
                 || configuredReleaseIdentity.modGroup != expectedMavenGroup
                 || configuredReleaseIdentity.minecraftVersion != '1.18.2'
                 || configuredReleaseIdentity.forgeVersion != '40.3.0'
@@ -308,7 +308,7 @@ tasks.register('verifyReleaseArtifacts') {
             }
             String modsToml = zip.getInputStream(zip.getEntry('META-INF/mods.toml')).getText('UTF-8')
             if (modsToml.contains('${')
-                    || !modsToml.contains('version="3.1.1.118021"')
+                    || !modsToml.contains('version="3.1.2.118021"')
                     || !modsToml.contains('versionRange="[4.1.0.118021,5.0.0)"')) {
                 throw new GradleException('Release mods.toml contains unresolved or incompatible metadata')
             }

gradle/verification/packaged-runtime.gradle

@@ -106,7 +106,7 @@ def packagedServerStartupSmoke = tasks.register('packagedServerStartupSmoke', Ex
         if (!marker.isFile()) throw new GradleException('Packaged dedicated-server completion marker is missing')
         Properties values = new Properties()
         marker.withInputStream { values.load(it) }
-        if (values.getProperty('basemetals') != '3.1.1.118021'
+        if (values.getProperty('basemetals') != '3.1.2.118021'
                 || values.getProperty('orespawn') != '4.1.0.118021'
                 || values.getProperty('forge') != '40.3.0') {
             throw new GradleException("Packaged dedicated-server versions are wrong: ${values}")

src/main/java/zone/moddev/mc/basemetals/api/migration/Legacy112MigrationExtension.java

@@ -0,0 +1,40 @@
+package zone.moddev.mc.basemetals.api.migration;
+
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.resources.ResourceLocation;
+import net.minecraft.world.level.block.state.BlockState;
+import zone.moddev.mc.basemetals.migration.Legacy112WorldMigrator;
+
+/**
+ * Lets a companion mod preserve its data when Base Metals pre-flattens a
+ * Minecraft 1.10 or 1.12 world. Register during common setup, before worlds load.
+ */
+public interface Legacy112MigrationExtension {
+    enum Payload { CHUNK, PLAYER }
+
+    /**
+     * Updates a legacy chunk or player payload in place, before vanilla's data
+     * fixer or the migrator's block entity snapshot. Return true on mutation.
+     */
+    default boolean prepareData(CompoundTag tag, int dataVersion, Payload payload) { return false; }
+
+    /** Runs immediately before the intermediate chunk data fix, only for chunks being converted. */
+    default void beforeChunkFlattening(CompoundTag chunk) { }
+
+    /**
+     * Checks or restores extension data after vanilla converts the embedded
+     * single-player record. The prepared source is a read-only snapshot.
+     */
+    default void afterPlayerFlattening(CompoundTag preparedSource, CompoundTag result) { }
+
+    /**
+     * Returns the native state for an owned legacy block, or null for an ID
+     * this extension does not own. Metadata is the original four-bit value.
+     */
+    default BlockState decodeBlockState(ResourceLocation legacyId, int metadata) { return null; }
+
+    /** The ID identifies the registering extension and must be unique. */
+    static void register(ResourceLocation id, Legacy112MigrationExtension extension) {
+        Legacy112WorldMigrator.registerExtension(id, extension);
+    }
+}