Merge the Forge 26.2 companion migration hook

Keep companion block metadata, inventories and embedded host players when upgrading old worlds. Local and hosted checks passed with unchanged release jars.

Author: SkyBlade1978

.github/workflows/ci.yml

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

CHANGELOG.txt

@@ -1,3 +1,9 @@
+Base Metals 3.1.2.2602001
+
+- Port the shared companion migration API from 26.1.2, including saved-world registry context.
+- Preserve companion block metadata, inventories and embedded host players before vanilla flattening.
+- Let companion chunk-return hooks run without cancellation; leave modern worlds and existing player files authoritative.
+
 Base Metals 3.1.1.2602001
 
 - Port the released 26.1.2 version to Minecraft 26.2 and Forge 65, keeping Java 25.

README.md

@@ -12,7 +12,8 @@ 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 26.2 Forge version, `3.1.1.2602001`. It keeps the
+This is the Minecraft 26.2 Forge version, `3.1.2.2602001`, with the shared
+companion migration hook. It keeps the
 fixes and features from the released 26.1.2 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
@@ -25,10 +26,11 @@ Additional Loot Tables are no longer needed.
 - A current Java 25 runtime
 - OreSpawn `[4.1.0.2602001,5.0.0)` on both client and server
 
-The build uses Forge `65.1.0` and is also tested on `65.1.5`.
+The build uses Forge `65.1.0`; `65.1.5` remains the additional compatibility
+target.
 
 This version uses OreSpawn `4.1.0.2602001`. Put
-`BaseMetals-3.1.1.2602001.jar` and a compatible OreSpawn JAR in the `mods`
+`BaseMetals-3.1.2.2602001.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.
 
@@ -201,7 +203,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.2602001`.
+`zone.moddev.mc.basemetals:BaseMetals:3.1.2.2602001`.
 
 Report defects and compatibility problems through the
 [Base Metals issue tracker](https://github.com/MinecraftModDevelopmentMods/BaseMetals/issues).

docs/MIGRATION.md

@@ -1,7 +1,7 @@
 # Migrating from Base Metals 1.10 or 1.12
 
 Always upgrade a copy and retain the original legacy world. Install Base Metals
-3.1.1 and OreSpawn 4.1.0, but do not carry MMDLib, Additional Loot Tables, the
+3.1.2 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 26.2 instance.
 
 Minecraft's data fixer cannot identify third-party numeric block IDs from
@@ -156,3 +156,30 @@ an older `level.dat` over the upgraded save.
 If an older single-player save has its player only in `level.dat`, Base Metals
 preserves a separate player file before Minecraft converts the folders. An
 existing player file always wins; a stale backup cannot restore an older player.
+
+## Companion migration extensions
+
+Companion mods can register a common-side
+`zone.moddev.mc.basemetals.api.migration.Legacy112MigrationExtension` with a
+unique `Identifier` during common setup, before a world opens. Registrations
+run in identifier order; duplicate identifiers fail rather than replace an owner.
+
+`prepareWorld` receives an independent copy of the selected world's saved
+registry snapshot before conversion. It also runs for modern worlds, so a
+companion can clear registry IDs retained from a previously opened legacy world.
+
+`prepareData` receives `Payload.CHUNK` or `Payload.PLAYER` before legacy
+flattening. `beforeChunkFlattening` runs before the block-entity snapshot, and
+`decodeBlockState` can restore owned block properties from raw metadata.
+Return `null` for an unowned block; air or multiple claims fail conversion.
+
+When a legacy host has no existing player file, `afterPlayerFlattening`
+receives its prepared source and the mutable schema-3465 player, before item
+componentization. The resulting native player seeds a separate disk file before
+FileFixerUpper moves it. The legacy level retains its source schema. Detached
+player files receive preparation only and remain under native player-loading
+authority. Existing player files in either layout are never replaced by the host.
+
+Chunk finalization edits the returned tag in place and does not cancel other
+mods' return callbacks. Extensions must preserve unowned data, register on both
+physical sides, and avoid client-only classes in these common callbacks.

docs/VERSIONS.md

@@ -1,6 +1,7 @@
 # Supported versions
 
-Base Metals `3.1.1.2602001` targets Minecraft 26.2, Forge 65.1.0 and Java 25.
+Base Metals `3.1.2.2602001` is a local candidate for Minecraft 26.2, Forge 65.1.0
+and Java 25. It is not published or fully qualified yet.
 Forge 65.1.5 is the additional compatibility target.
 OreSpawn `4.1.0.2602001` is the exact build and test dependency. Clients and
 servers need OreSpawn `[4.1.0.2602001,5.0.0)`.
@@ -11,7 +12,7 @@ Its SHA-256 is
 `F74785025898DF059E0F00F6ADA53364E07ECBBC306807ED7CD55350609E2547`.
 
 Release artifacts use Maven coordinate
-`zone.moddev.mc.basemetals:BaseMetals:3.1.1.2602001`.
+`zone.moddev.mc.basemetals:BaseMetals:3.1.2.2602001` once approved and published.
 
 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.2602001
+mod_version=3.1.2.2602001
 # 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

@@ -334,7 +334,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.2602001"')) {
+        if (metadata.contains('${') || !metadata.contains('version="3.1.2.2602001"')) {
             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('verifyJava25Toolchain')
     doLast {
-        if (configuredReleaseIdentity.modVersion != '3.1.1.2602001'
+        if (configuredReleaseIdentity.modVersion != '3.1.2.2602001'
                 || configuredReleaseIdentity.modGroup != expectedMavenGroup
                 || configuredReleaseIdentity.minecraftVersion != '26.2'
                 || configuredReleaseIdentity.forgeVersion != '65.1.0'
@@ -332,7 +332,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.2602001"')
+                    || !modsToml.contains('version="3.1.2.2602001"')
                     || !modsToml.contains('versionRange="[4.1.0.2602001,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.2602001'
+        if (values.getProperty('basemetals') != '3.1.2.2602001'
                 || values.getProperty('orespawn') != '4.1.0.2602001'
                 || values.getProperty('forge') != '65.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,39 @@
+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 }
+
+    /**
+     * Supplies this selected world's saved registry context before any conversion.
+     * Each extension receives its own copy. Modern worlds are included so a
+     * companion can clear registry IDs retained from a previous world.
+     */
+    default void prepareWorld(CompoundTag levelSnapshot) { }
+
+    /** 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 at the 1.20.1 item schema, before componentization.
+     * The prepared source is read-only; result still uses historical Count/tag.
+     * On 26.1 and later this seeds a missing host file before FileFixerUpper moves it.
+     */
+    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);
+    }
+}