Keep old expansion machine data when upgrading worlds on 1.21.11

.github/workflows/ci.yml

@@ -71,19 +71,19 @@ jobs:
             --no-daemon --stacktrace
           first="$RUNNER_TEMP/basemetals-first"
           mkdir -p "$first"
-          cp build/libs/BaseMetals-3.1.1.121111.jar "$first/"
-          cp build/libs/BaseMetals-3.1.1.121111-sources.jar "$first/"
-          cp build/libs/BaseMetals-3.1.1.121111-javadoc.jar "$first/"
+          cp build/libs/BaseMetals-3.1.2.121111.jar "$first/"
+          cp build/libs/BaseMetals-3.1.2.121111-sources.jar "$first/"
+          cp build/libs/BaseMetals-3.1.2.121111-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.121111.jar" build/libs/BaseMetals-3.1.1.121111.jar
-          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.1.121111-sources.jar" build/libs/BaseMetals-3.1.1.121111-sources.jar
-          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.1.121111-javadoc.jar" build/libs/BaseMetals-3.1.1.121111-javadoc.jar
+          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.2.121111.jar" build/libs/BaseMetals-3.1.2.121111.jar
+          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.2.121111-sources.jar" build/libs/BaseMetals-3.1.2.121111-sources.jar
+          cmp "$RUNNER_TEMP/basemetals-first/BaseMetals-3.1.2.121111-javadoc.jar" build/libs/BaseMetals-3.1.2.121111-javadoc.jar
           cmp "$RUNNER_TEMP/basemetals-first/SHA256SUMS" build/release/SHA256SUMS
 
       - name: Run all required GameTests
@@ -151,9 +151,9 @@ jobs:
           if-no-files-found: error
           retention-days: 30
           path: |
-            build/libs/BaseMetals-3.1.1.121111.jar
-            build/libs/BaseMetals-3.1.1.121111-sources.jar
-            build/libs/BaseMetals-3.1.1.121111-javadoc.jar
+            build/libs/BaseMetals-3.1.2.121111.jar
+            build/libs/BaseMetals-3.1.2.121111-sources.jar
+            build/libs/BaseMetals-3.1.2.121111-javadoc.jar
             build/release/SHA256SUMS
             CHANGELOG.txt
 

CHANGELOG.txt

@@ -1,3 +1,10 @@
+Base Metals 3.1.2.121111
+
+- Keep expansion machine directions, inventories and item wear before Minecraft converts old worlds.
+- Carry the shared migration extension hook forward to Minecraft 1.21.11.
+- Let companion chunk-migration callbacks finish before returning, so staged entities are not lost.
+- Keep existing block and item identities, recipes and material balance unchanged.
+
 Base Metals 3.1.1.121111
 
 - Port the released 1.21.1 version to Minecraft 1.21.11 and Forge 61, keeping Java 21.

README.md

@@ -5,14 +5,20 @@
 
 # Base Metals
 
+The 3.1.2.121111 patch preserves expansion machine data before Minecraft
+converts an older world. It also lets companion migration callbacks finish,
+so restored entities are not lost. Machine, upgrade, restart and endurance
+checks have passed with the matching basePower, baseSteam and baseElectric
+builds. Keep a backup and test an upgrade on a copy of your world first.
+
 Base Metals adds historically common metals, useful alloys, and fantasy metals
 to Minecraft. Depending on the material, these are available as ores, storage
 and decorative blocks, molten fluids, crafting components, tools, armour,
 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.21.11 Forge version, `3.1.1.121111`. It keeps the
+This is the Minecraft 1.21.11 Forge version, `3.1.2.121111`. It keeps the
 fixes and features from the released 1.21.1 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
@@ -28,7 +34,7 @@ Additional Loot Tables are no longer needed.
 The port has also been checked against Forge `61.2.4`.
 
 This version uses OreSpawn `4.1.0.121111`. Put
-`BaseMetals-3.1.1.121111.jar` and a compatible OreSpawn JAR in the `mods`
+`BaseMetals-3.1.2.121111.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.
 
@@ -203,7 +209,7 @@ early splash window. Minecraft still opens its game window and runs the full
 world check. Ordinary client launches keep the normal splash screen.
 
 Release artifacts use Maven coordinate
-`zone.moddev.mc.basemetals:BaseMetals:3.1.1.121111`.
+`zone.moddev.mc.basemetals:BaseMetals:3.1.2.121111`.
 
 Report defects and compatibility problems through the
 [Base Metals issue tracker](https://github.com/MinecraftModDevelopmentMods/BaseMetals/issues).

docs/MIGRATION.md

@@ -135,3 +135,12 @@ 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.
+# Companion Migration Hooks
+
+The local 3.1.2.121111 patch exposes `Legacy112MigrationExtension` for mods
+whose machine state must be preserved before Base Metals runs Minecraft's
+legacy chunk and player conversion. Register during common setup. The source
+payload is prepared before flattening, and extensions can restore their
+owned metadata states without replacing vanilla data fixes. The original
+world backup and migration markers remain in force.
+

docs/VERSIONS.md

@@ -1,6 +1,6 @@
 # Supported versions
 
-Base Metals `3.1.1.121111` targets Minecraft 1.21.11, Forge 61.1.0 and Java 21.
+Base Metals `3.1.2.121111` targets Minecraft 1.21.11, Forge 61.1.0 and Java 21.
 Packaged client, server and save-upgrade checks also pass on Forge 61.2.4.
 OreSpawn `4.1.0.121111` is the exact build and test dependency. Clients and
 servers need OreSpawn `[4.1.0.121111,5.0.0)`.
@@ -11,7 +11,7 @@ Its SHA-256 is
 `DE39929057288CEA110196C9E9D708E129B80BC360A2E53976337FFA6A84A67B`.
 
 Release artifacts use Maven coordinate
-`zone.moddev.mc.basemetals:BaseMetals:3.1.1.121111`.
+`zone.moddev.mc.basemetals:BaseMetals:3.1.2.121111`.
 
 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.121111
+mod_version=3.1.2.121111
 # 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

@@ -317,7 +317,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.121111"')) {
+        if (metadata.contains('${') || !metadata.contains('version="3.1.2.121111"')) {
             throw new GradleException('Eclipse output contains unresolved or invalid Base Metals version metadata')
         }
     }

gradle/release/artifacts.gradle

@@ -202,7 +202,7 @@ tasks.register('verifyReleaseConfiguration') {
     dependsOn tasks.named('verifyMavenizerCompatibilityFixture')
     dependsOn tasks.named('verifyJava21Toolchain')
     doLast {
-        if (configuredReleaseIdentity.modVersion != '3.1.1.121111'
+        if (configuredReleaseIdentity.modVersion != '3.1.2.121111'
                 || configuredReleaseIdentity.modGroup != expectedMavenGroup
                 || configuredReleaseIdentity.minecraftVersion != '1.21.11'
                 || configuredReleaseIdentity.forgeVersion != '61.1.0'
@@ -326,7 +326,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.121111"')
+                    || !modsToml.contains('version="3.1.2.121111"')
                     || !modsToml.contains('versionRange="[4.1.0.121111,5.0.0)"')) {
                 throw new GradleException('Release mods.toml contains unresolved or incompatible metadata')
             }

gradle/verification/packaged-runtime.gradle

@@ -174,7 +174,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.121111'
+        if (values.getProperty('basemetals') != '3.1.2.121111'
                 || values.getProperty('orespawn') != '4.1.0.121111'
                 || values.getProperty('forge') != '61.1.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,32 @@
+package zone.moddev.mc.basemetals.api.migration;
+
+import net.minecraft.nbt.CompoundTag;
+import net.minecraft.resources.Identifier;
+import net.minecraft.world.level.block.state.BlockState;
+import zone.moddev.mc.basemetals.migration.Legacy112WorldMigrator;
+
+/** Preserves companion data before Base Metals converts a pre-flattening world. */
+public interface Legacy112MigrationExtension {
+    enum Payload { CHUNK, PLAYER }
+
+    /** Mutates owned legacy data before vanilla fixes and the block-entity snapshot. */
+    default boolean prepareData(CompoundTag tag, int dataVersion, Payload payload) { return false; }
+
+    /** Runs immediately before the intermediate chunk data fix. */
+    default void beforeChunkFlattening(CompoundTag chunk) { }
+
+    /**
+     * Restores owned data after vanilla reaches the 1.20.1 item schema, before
+     * native item componentization. The prepared source is read-only; the
+     * mutable result still stores historical Count/tag item payloads.
+     */
+    default void afterPlayerFlattening(CompoundTag preparedSource, CompoundTag result) { }
+
+    /** Returns a native owned state, or null for an unowned registry ID. */
+    default BlockState decodeBlockState(Identifier legacyId, int metadata) { return null; }
+
+    /** Register during common setup, before any world is opened. */
+    static void register(Identifier id, Legacy112MigrationExtension extension) {
+        Legacy112WorldMigrator.registerExtension(id, extension);
+    }
+}