Merge pull request #228 from SkyBlade1978/master-1.20.6

Preserve legacy Mineralogy upgrades on Forge 1.20.6

Author: SkyBlade1978

CHANGELOG.txt

@@ -1,5 +1,10 @@
-Version 4.0.6
+Version 4.0.6.120061
 
+* Adopt target-qualified four-component versions so Minecraft and loader compatibility can be identified from the mod version.
+* Preserve generated worlds made with Mineralogy 1.10, 1.12, or 5.x by reading their saved mod metadata and exact legacy configuration before creating the OreSpawn world profile.
+* Write human-readable, idempotent upgrade reports for legacy OreSpawn and Mineralogy imports while retaining source files and existing chunks unchanged.
+* Audit automated runtime logs and dynamic-fluid generation so logged worldgen failures cannot pass merely because the process exits normally.
+* Qualify existing OreSpawn 4.0.4 global and per-world profiles without changing explicit Custom values or provider definitions.
 * Fix provider top and filler materials being generated one block below exposed ground.
 * Apply underwater materials from the corrected ground and ceiling materials to roof undersides.
 * Preserve trees, vegetation, structures and block entities by running surface replacement before late features.

README.md

@@ -39,13 +39,23 @@ Important files:
 | `<world>/serverconfig/orespawn-worldgen.json` | Complete settings snapshot for one world |
 | `config/<modid>-orespawn.json` | Optional modpack override for one provider |
 | `config/orespawn-guide/README.md` | Guide exported automatically on first load |
+| `config/orespawn-upgrade-report.txt` | Human summary produced when legacy OreSpawn rules are imported |
+| `<world>/serverconfig/orespawn-upgrade-report.txt` | Human summary produced when a generated legacy Mineralogy world is pinned to its saved settings |
 
 Profile edits affect newly generated chunks. Ore and flat-bedrock retrogen are
 separate opt-in features; OreSpawn never retro-generates rock strata.
 Stable Layers honours exact biome-ID geome influences on dynamic biome
 registries and spreads close geome transitions across layers rather than
 changing an entire vertical rock column at one boundary.
 
+When an already-generated world has saved Mineralogy 1.10, 1.12, or 5.x mod
+metadata but no OreSpawn world profile, OreSpawn reads the matching published
+configuration contract and records the exact engine, numeric settings, rock
+order, and white/blacklists in the new world profile. Saved-world identity
+wins over stale files in the installation. A fresh world is never reclassified
+merely because an old `mineralogy.cfg` or `mineralogy-common.toml` remains in
+the instance.
+
 To move a configured single-player world to a dedicated server, copy the
 world's `serverconfig/orespawn-worldgen.json` with the world and install the
 same provider mods on the server.

build.gradle

@@ -303,6 +303,168 @@ tasks.named('javadoc', Javadoc).configure {
 
 tasks.named('test', Test).configure {
     useJUnitPlatform()
+    // Unit tests inspect target files relative to the checkout, but they do
+    // not need Forge's rolling runtime files. A console-only test logger keeps
+    // them from contending with Eclipse/client logs in this working directory.
+    systemProperty 'log4j.configurationFile', file('src/test/resources/log4j2-test.xml').absolutePath
+    // Loaded only through an isolated URLClassLoader by the parity test. This
+    // is deliberately not a Gradle dependency and cannot leak into Eclipse or
+    // a published OreSpawn jar.
+    File mineralogy5Oracle = file('../../MinecraftMineralogy 118/MinecraftMineralogy/build/libs/Mineralogy-1.18.2-5.4.0.jar')
+    if (mineralogy5Oracle.isFile()) {
+        systemProperty 'orespawn.mineralogy5Oracle', mineralogy5Oracle.absolutePath
+    }
+}
+
+// Several registry-focused tests initialize the real global config singleton.
+// Keep that target-native coverage without creating or changing a developer's
+// checkout config as a side effect of `test` or `build`.
+def unitTestWorldgenConfig = file('config/orespawn-worldgen.json')
+def unitTestWorldgenConfigWasPresent = false
+byte[] unitTestWorldgenConfigBytes = null
+tasks.named('test', Test).configure {
+    doFirst {
+        unitTestWorldgenConfigWasPresent = unitTestWorldgenConfig.isFile()
+        unitTestWorldgenConfigBytes = unitTestWorldgenConfigWasPresent
+                ? unitTestWorldgenConfig.bytes : null
+    }
+}
+def preserveDeveloperWorldgenConfig = tasks.register('preserveDeveloperWorldgenConfig') {
+    doLast {
+        if (unitTestWorldgenConfigWasPresent) {
+            byte[] after = unitTestWorldgenConfig.isFile() ? unitTestWorldgenConfig.bytes : null
+            if (after == null || !java.util.Arrays.equals(unitTestWorldgenConfigBytes, after)) {
+                unitTestWorldgenConfig.parentFile.mkdirs()
+                unitTestWorldgenConfig.bytes = unitTestWorldgenConfigBytes
+                throw new GradleException('Unit tests changed config/orespawn-worldgen.json; the original was restored')
+            }
+        } else if (unitTestWorldgenConfig.isFile()) {
+            delete unitTestWorldgenConfig
+        }
+    }
+}
+tasks.named('test') {
+    finalizedBy preserveDeveloperWorldgenConfig
+}
+
+// A Forge process is not green merely because it returns exit code zero. The
+// loader can log a worldgen/linkage failure and still shut down normally.
+def acceptedForge40LogNoise = [
+        ~/FML appears to be missing any signature data/,
+        ~/Found multiple arguments for option fml\.mcVersion/,
+        ~/Found multiple arguments for option fml\.forgeVersion/,
+        ~/\/FATAL\] \[net\.minecraftforge\.common\.ForgeConfig\/CORE\]: Forge config just got changed on the file system!$/,
+        ~/\/FATAL\] \[net\.minecraftforge\.fml\.packs\.ModFileResourcePack\/\]: Failed to clean up tempdir /
+]
+
+def runtimeCrashSnapshot = { File runDirectory ->
+    File crashDirectory = new File(runDirectory, 'crash-reports')
+    if (!crashDirectory.isDirectory()) return [] as Set
+    return fileTree(crashDirectory) { include '**/*' }.files
+            .findAll { it.isFile() }.collect { it.absolutePath } as Set
+}
+
+def assertRuntimeLogsClean = { File runDirectory, String context, Set priorCrashes ->
+    File crashDirectory = new File(runDirectory, 'crash-reports')
+    if (crashDirectory.isDirectory()) {
+        def crashes = fileTree(crashDirectory) { include '**/*' }.files
+                .findAll { it.isFile() && !priorCrashes.contains(it.absolutePath) }
+        if (!crashes.isEmpty()) {
+            throw new GradleException("${context} produced crash report ${crashes.first()}")
+        }
+    }
+
+    File logsDirectory = new File(runDirectory, 'logs')
+    if (!logsDirectory.isDirectory()) return
+    def failures = []
+    [new File(logsDirectory, 'latest.log'), new File(logsDirectory, 'debug.log')]
+            .findAll { it.isFile() }.each { File log ->
+        int lineNumber = 0
+        log.eachLine('UTF-8') { String line ->
+            lineNumber++
+            boolean unexpectedSeverity = line ==~ /.*\/(?:ERROR|FATAL)\].*/
+            boolean knownNoise = acceptedForge40LogNoise.any { line =~ it }
+            boolean fatalText = line.contains('Encountered an unexpected exception') ||
+                    line.contains('Exception stopping the server') ||
+                    line.contains('Migration audit failed') ||
+                    line.contains('java.lang.Error:') ||
+                    line.contains('NoSuchMethodError') ||
+                    line.contains('NoClassDefFoundError') ||
+                    line.contains('ExceptionInInitializerError') ||
+                    line.contains('Tried to assign a mutable BlockPos') ||
+                    line.contains('causing cascading worldgen lag')
+            if ((unexpectedSeverity && !knownNoise) || fatalText) {
+                failures.add("${log.name}:${lineNumber}: ${line}")
+            }
+        }
+    }
+    if (!failures.isEmpty()) {
+        throw new GradleException("${context} logged unexpected errors:\n"
+                + failures.take(20).join('\n'))
+    }
+}
+
+task runtimeLogScannerTest {
+    group = 'verification'
+    description = 'Proves runtime log validation accepts documented Forge noise and rejects real failures.'
+    doLast {
+        File probe = file("${buildDir}/runtime-log-scanner-test")
+        delete probe
+        File logs = new File(probe, 'logs'); logs.mkdirs()
+        new File(logs, 'latest.log').setText(
+                '[main/ERROR] [FML]: FML appears to be missing any signature data\n'
+                + '[Server thread/INFO] [FML]: Done\n', 'UTF-8')
+        assertRuntimeLogsClean(probe, 'scanner-accepted-noise-probe', [] as Set)
+        new File(logs, 'latest.log').setText(
+                '[Server thread/WARN]: Tried to assign a mutable BlockPos to tick data...\n', 'UTF-8')
+        boolean rejected = false
+        try { assertRuntimeLogsClean(probe, 'scanner-mutable-position-probe', [] as Set) }
+        catch (GradleException expected) { rejected = true }
+        if (!rejected) throw new GradleException('Runtime log scanner accepted a mutable BlockPos leak')
+        new File(logs, 'latest.log').setText(
+                '[Server thread/DEBUG] [FML]: Minecraft loaded a new chunk while populating another, causing cascading worldgen lag.\n', 'UTF-8')
+        rejected = false
+        try { assertRuntimeLogsClean(probe, 'scanner-cascading-probe', [] as Set) }
+        catch (GradleException expected) { rejected = true }
+        if (!rejected) throw new GradleException('Runtime log scanner accepted cascading worldgen')
+        new File(logs, 'latest.log').setText(
+                '[Server thread/ERROR] [example]: Unexpected fixture failure\n', 'UTF-8')
+        rejected = false
+        try { assertRuntimeLogsClean(probe, 'scanner-severity-probe', [] as Set) }
+        catch (GradleException expected) { rejected = true }
+        if (!rejected) throw new GradleException('Runtime log scanner accepted an unexpected ERROR line')
+        delete probe
+    }
+}
+
+check.dependsOn runtimeLogScannerTest
+
+task verifyMineralogyOracleIsolation {
+    group = 'verification'
+    description = 'Prevents published Mineralogy engines from leaking into Gradle configurations or ordinary Eclipse launches.'
+    doLast {
+        configurations.each { configuration ->
+            if (configuration.canBeResolved &&
+                    configuration.files.any { it.name ==~ /Mineralogy-.*\.jar/ }) {
+                throw new GradleException("Mineralogy oracle leaked into Gradle configuration ${configuration.name}")
+            }
+        }
+    }
+}
+
+check.dependsOn verifyMineralogyOracleIsolation
+
+['runClient', 'runServer', 'runData'].each { String taskName ->
+    tasks.matching { it.name == taskName }.all { JavaExec runTask ->
+        doFirst {
+            new File(runTask.workingDir, 'mods').mkdirs()
+            runTask.ext.oreSpawnCrashSnapshot = runtimeCrashSnapshot(runTask.workingDir)
+        }
+        doLast {
+            assertRuntimeLogsClean(runTask.workingDir, taskName,
+                    runTask.ext.oreSpawnCrashSnapshot as Set)
+        }
+    }
 }
 
 def surfaceIntegrationClasses = layout.buildDirectory.dir('surface-integration-fixture/classes')
@@ -357,8 +519,16 @@ tasks.configureEach {
     } else if (name == 'runSurfaceIntegrationReload') {
         dependsOn 'runSurfaceIntegrationFresh'
     }
+    if (name == 'runSurfaceIntegrationFresh' || name == 'runSurfaceIntegrationReload') {
+        doFirst {
+            ext.oreSpawnCrashSnapshot = runtimeCrashSnapshot(workingDir)
+        }
+        doLast {
+            assertRuntimeLogsClean(workingDir, "Forge 50 ${name}",
+                    ext.oreSpawnCrashSnapshot as Set)
+        }
+    }
 }
-
 def surfaceIntegrationTest = tasks.register('surfaceIntegrationTest') {
     group = 'verification'
     description = 'Verifies provider surfaces and dynamic-biome geology across fresh and reloaded normal terrain.'

docs/AGENTS.md

@@ -12,4 +12,5 @@ Use the focused guides for implementation details:
 - [BIOMES.md](BIOMES.md) and [DIMENSIONS.md](DIMENSIONS.md) for world integration;
 - [TEMPLATES.md](TEMPLATES.md) for selectable world styles;
 - [CONFIGURATION.md](CONFIGURATION.md) for configuration behavior;
+- [VERSIONS.md](VERSIONS.md) for the shared four-component target-qualified versioning and branch-release convention;
 - [README.md](README.md) for schemas, examples, and the complete documentation index.

docs/CONFIGURATION.md

@@ -17,6 +17,14 @@ packaged or API providers, provider override files, the global configuration,
 the selected template, and Create World edits. The result is saved with the
 world. Restart after editing JSON by hand.
 
+An existing generated world follows a stricter safety order. Its existing
+`serverconfig/orespawn-worldgen.json` always wins. If none exists, saved legacy
+Mineralogy mod metadata may select the matching 1.10, 1.12, or 5.x config
+contract before the world profile is first written. Installed-pack defaults,
+Create World choices, and unrelated stale legacy files cannot override that
+saved-world identity. See `MIGRATION.md` and the generated per-world upgrade
+report for the exact decision.
+
 ## Top-Level Fields
 
 | Field | Values | Meaning |
@@ -94,6 +102,12 @@ Cyano settings use `cyano.geome_size` (4-32767),
 `cyano.rock_layer_noise` (1-32767), and `cyano.rock_layer_thickness` (1-255).
 They are ignored by Sky.
 
+Profiles created from a legacy Mineralogy world also retain
+`cyano.enabled`, `cyano.realistic_coal_layers`, the three effective
+`*_rocks` arrays, the six original `*_whitelist`/`*_blacklist` arrays, and
+source/version fields. These are migration snapshots, not new settings that a
+fresh pack needs to author.
+
 ## Rocks And Geomes
 
 A rock requires `enabled`, `family`, `depth_peak`, `depth_spread`, `min_y`,

docs/MIGRATION.md

@@ -13,6 +13,37 @@ legacy-ID behaviour.
 
 Migration is non-destructive. OreSpawn writes `config/orespawn-worldgen.json`
 only when that target does not already exist and retains every source file.
+When legacy OreSpawn rules are translated, a concise player-facing summary is
+also written atomically to `config/orespawn-upgrade-report.txt`; the existing
+detailed rule report remains at `config/orespawn-migration/migration-report.txt`.
+
+## Existing Mineralogy Worlds
+
+An already-generated world without an OreSpawn per-world profile is inspected
+before OreSpawn chooses any installed-pack or Create World default. OreSpawn
+uses saved mod metadata from `level.dat`, with a valid `level.dat_old` as a
+fallback, to distinguish these published contracts:
+
+- Mineralogy 1.10.2 `3.3.8.26` and its `mineralogy.cfg`;
+- Mineralogy 1.12.2 `3.8.0.53` and its distinct `mineralogy.cfg`;
+- Mineralogy 5.0.1 through 5.4.0 and `mineralogy-common.toml`.
+
+The resulting world profile preserves enablement, selected legacy/geome
+engine, geome size, layer noise and thickness, realistic-coal behavior where
+supported, exact effective rock order (including historical duplicates), and
+all six white/blacklists. Saved-world identity chooses the lineage even when a
+different stale config is present. Missing or malformed values use that
+lineage's published defaults and are reported rather than silently broadening
+the world configuration.
+
+The human-readable result is written atomically to
+`<world>/serverconfig/orespawn-upgrade-report.txt`. It identifies the saved
+version and metadata source, config source, selected engine and lineage,
+effective settings and outputs, missing IDs, fallbacks, and warnings. Source
+configuration and existing chunks are not rewritten. Once
+`orespawn-worldgen.json` exists it is authoritative and the import is not run
+again. A fresh world containing stale legacy files remains on its explicit
+OreSpawn/Create World settings.
 
 When `config/mineralogy-geomes.json` exists, OreSpawn imports the Mineralogy 6
 profile directly, updates its schema marker, and records `migrated_from`.

docs/PLAYER_GUIDE.md

@@ -93,3 +93,20 @@ the same mods. Alternatively, place a prepared global profile at
 
 The server console commands `/orespawn status`, `/orespawn reload`, and
 `/orespawn dump-biomes` help pack authors diagnose active providers and IDs.
+
+### Upgrading a Mineralogy world
+
+If the world was already generated with Mineralogy 1.10, 1.12, or 5.x and has
+no OreSpawn world profile yet, OreSpawn reads the Mineralogy version saved in
+the world and the matching old configuration. It preserves the selected
+engine, numeric settings, rock order, and lists rather than silently applying
+new-world defaults. Look for:
+
+```text
+<world>/serverconfig/orespawn-upgrade-report.txt
+```
+
+The report explains what was detected and retained, including any missing rock
+IDs or fallback values. OreSpawn leaves the old configuration and generated
+chunks untouched. A fresh world does not inherit this behavior merely because
+an old Mineralogy config is still present in the instance.