Share legacy-world migration hooks on Forge 26.3

.github/workflows/ci.yml

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

CHANGELOG.txt

@@ -1,3 +1,10 @@
+Base Metals 3.1.2.2603001
+
+* Let compatible companion mods join the same legacy-world upgrade for blocks, inventories and players.
+* Keep each companion's selected-world registry snapshot independent.
+* Keep chunk-return hooks cooperative and preserve the old block-state fields used during conversion.
+* Test the shared upgrade with Power, Steam and Electric Advantage on 26.3.
+
 Base Metals 3.1.1.2603001
 
 - Port the released 26.2 version to Minecraft 26.3 and Forge 66, keeping Java 25.

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 26.3 Forge version, `3.1.1.2603001`. It keeps the
+This branch contains Base Metals `3.1.2.2603001` for Minecraft 26.3 Forge. It keeps the
 fixes and features from the released 26.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
@@ -28,7 +28,7 @@ Additional Loot Tables are no longer needed.
 The build uses Forge `66.0.0` and is also tested on `66.1.0`.
 
 This version uses OreSpawn `4.1.0.2603001`. Put
-`BaseMetals-3.1.1.2603001.jar` and a compatible OreSpawn JAR in the `mods`
+`BaseMetals-3.1.2.2603001.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.
 
@@ -147,6 +147,12 @@ in place; genuine legacy upgrades still make backups before changing saved data.
 The 26.3 update also protects imported terrain from dungeon placement during
 conversion. New chunks and the new underground areas can still generate normally.
 
+Compatible companion mods can now take part in the same legacy-world upgrade.
+Each companion keeps its own registry snapshot, so one mod's conversion does not
+replace another's. The shared hooks retain old block-state and inventory data for
+the companion to convert. This has been tested with the Power, Steam and Electric
+Advantage family on 26.3.
+
 ## Mod and data-pack compatibility
 
 Forge item, block, and fluid tags are Base Metals' public compatibility API.
@@ -206,7 +212,7 @@ the SDL/OpenGL context before starting Minecraft. Ordinary client launches keep
 the normal splash screen and graphics settings.
 
 Release artifacts use Maven coordinate
-`zone.moddev.mc.basemetals:BaseMetals:3.1.1.2603001`.
+`zone.moddev.mc.basemetals:BaseMetals:3.1.2.2603001`.
 
 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.3 instance.
 
 Minecraft's data fixer cannot identify third-party numeric block IDs from
@@ -159,3 +159,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.2603001` targets Minecraft 26.3, Forge 66.0.0 and Java 25.
+Base Metals `3.1.2.2603001` is a local candidate for Minecraft 26.3, Forge 66.0.0
+and Java 25. It is not published or fully qualified yet.
 Forge 66.1.0 is the additional compatibility target.
 OreSpawn `4.1.0.2603001` is the exact build and test dependency. Clients and
 servers need OreSpawn `[4.1.0.2603001,5.0.0)`.
@@ -11,7 +12,7 @@ Its SHA-256 is
 `A7FCDD626B9044091BFDB7277DA3169A5307EB5F97FCF88741A878401DCF1AEA`.
 
 Release artifacts use Maven coordinate
-`zone.moddev.mc.basemetals:BaseMetals:3.1.1.2603001`.
+`zone.moddev.mc.basemetals:BaseMetals:3.1.2.2603001`.
 
 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.2603001
+mod_version=3.1.2.2603001
 # 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.2603001"')) {
+        if (metadata.contains('${') || !metadata.contains('version="3.1.2.2603001"')) {
             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.2603001'
+        if (configuredReleaseIdentity.modVersion != '3.1.2.2603001'
                 || configuredReleaseIdentity.modGroup != expectedMavenGroup
                 || configuredReleaseIdentity.minecraftVersion != '26.3'
                 || configuredReleaseIdentity.forgeVersion != '66.0.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.2603001"')
+                    || !modsToml.contains('version="3.1.2.2603001"')
                     || !modsToml.contains('versionRange="[4.1.0.2603001,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.2603001'
+        if (values.getProperty('basemetals') != '3.1.2.2603001'
                 || values.getProperty('orespawn') != '4.1.0.2603001'
                 || values.getProperty('forge') != '66.0.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);
+    }
+}