Merge pull request #237 from SkyBlade1978/master-1.20.6-neo

Master 1.20.6 neo

Author: SkyBlade1978

CHANGELOG.txt

@@ -1,3 +1,18 @@
+Version 4.0.6.120062
+
+* 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.5 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.
+* Honour exact biome-to-geome weights on dynamic biome registries.
+* Stagger close Stable Layers geome transitions by layer instead of changing a whole rock column at one boundary.
+* Recalibrate Stable Layers edge-detail presets so Average retains natural variation at later rock contacts.
+* Existing chunks are not rewritten; the correction applies while generating new chunks.
+
 Version 4.0.5
 
 * Complete native translations for every shipped non-English locale

README.md

@@ -39,9 +39,22 @@ 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
@@ -84,9 +97,12 @@ Use Java 21 from the repository root:
 ```
 
 `build` runs the standard `check` lifecycle. In addition to the JUnit suite,
-that lifecycle packages a test-only provider mod, loads its custom biome in
-normal noise terrain, and verifies both fresh generation and reopening the
-same saved world. The fixture is not included in OreSpawn's published jars.
+that lifecycle packages a test-only provider mod and verifies exposed,
+underwater, filler, and ceiling surfaces in open and ceiling normal-noise
+dimensions. It also proves later vegetation, structures, and block entities
+survive, verifies identifier-weighted geology in a dynamic custom biome, then
+reopens and checks the exact saved world. The fixture is not included in
+OreSpawn's published jars.
 
 Import or refresh the project with Eclipse Buildship. NeoGradle supplies the
 Eclipse model and run configurations through the `eclipse` task; this branch

build.gradle

@@ -12,4 +12,6 @@ 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/AGENTS.md

@@ -133,9 +133,11 @@ OreSpawnApi.createSampler(server.overworld()).ifPresent(sampler -> {
 });
 ```
 
-`sampleColumn` performs one biome/geome classification and reuses it for every
-Y query. Sampling is read-only and is intended for gameplay decisions,
-diagnostics, and compatible generation outside OreSpawn's block loops.
+`sampleColumn` performs one biome/dominant-geome classification and reuses its
+transition scores for every Y query. `rockAt` therefore matches Stable Layers
+when a close geome transition is staggered by layer. Sampling is read-only and
+is intended for gameplay decisions, diagnostics, and compatible generation
+outside OreSpawn's block loops.
 Callbacks inside OreSpawn generation loops are intentionally unsupported.
 
 Custom pattern mods create a NeoForge `DeferredRegister<OrePatternType>` using

docs/API.md

@@ -126,6 +126,16 @@ Biome surfaces support:
 - `ceiling_block`: optional underside material;
 - `filler_depth`: 0-16 blocks.
 
+Provider surfaces run during `LOCAL_MODIFICATIONS`: after Minecraft has built
+base surfaces and lakes, but before structures and vegetation. That ordering
+lets OreSpawn replace the actual exposed ground while preserving later trees,
+plants, authored structures, and block entities. In ceiling dimensions,
+`ceiling_block` applies to the roof underside and does not replace the roof top.
+
+Surface correction is generation-only. Installing or updating OreSpawn does
+not rewrite already generated chunks; travel into new terrain to see a changed
+provider surface definition.
+
 Dimension materials support the ordinary aquifer fluid, a deep aquifer fluid
 and threshold, and replacements for vanilla snow and ice. OreSpawn converts
 weather products in loaded chunks and around players; it does not replace every

docs/BIOMES.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 |
@@ -75,10 +83,31 @@ When a control is `custom`, its value comes from `formations.custom`:
 | `edge_octaves` | 1-8 | Number of boundary-detail scales |
 | `continuity` | 0-1 | Proportion of formations retaining global identity |
 
+For Stable Layers, the Edge Detail presets use these
+`wavelength / amplitude / octaves` values:
+
+| Preset | Edge detail |
+|---|---:|
+| Tiny | `48 / 4 / 1` |
+| Small | `64 / 12 / 2` |
+| Average | `96 / 24 / 3` |
+| Large | `128 / 48 / 4` |
+| Huge | `192 / 96 / 5` |
+
+Average is calibrated to retain visible variation at later layer contacts.
+Custom profiles keep their explicit values; these numbers are only used by the
+named presets and as defaults for new Custom settings.
+
 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`,
@@ -90,6 +119,10 @@ weight by province. A weight of zero prevents selection in that context.
 Geomes contain a non-negative `base` weight and non-negative weights for each
 rock family. Biome and biome-dictionary maps multiply those geome weights.
 Missing optional-mod biome IDs are ignored during baking.
+Exact biome-ID maps remain effective when the target uses a dynamic biome
+registry. With Stable Layers, a close contest between two geomes transitions
+at a deterministic position per layer so the whole underground column does
+not change on one sheer plane.
 
 Terrain dimensions require `enabled`, `host_blocks`, and `host_tags`.
 `biome_ids` and `biome_namespaces` can narrow a custom dimension. The Overworld

docs/CONFIGURATION.md

@@ -198,10 +198,11 @@ bounded ore or bedrock retrogen is enabled.
 6. Confirm the provider appears in `/orespawn status`.
 7. Test a new world; profile edits do not rewrite already generated terrain.
 
-OreSpawn's own standard `check` lifecycle includes a consumer-style biome
-integration test. It loads a separate test provider and datapack biome, proves
-the provider is active, verifies biome selection, tags, climate and configured
-surface blocks in non-flat terrain, then reopens and rechecks the same saved
-world. Run `gradlew check` (or `gradlew build`, which includes it) before
-publishing any change to biome registration, palettes, surfaces or profile
-persistence.
+OreSpawn's own standard `check` lifecycle includes a consumer-style surface
+integration test. A separate test provider creates independently marked
+Grass/Dirt, underwater, filler, and roof columns in open and ceiling
+normal-noise dimensions. The gate verifies biome and chunk edges, late tree,
+vegetation, structure and chest sentinels, the roof underside, and exact save
+reload behavior. Run `gradlew check` (or `gradlew build`, which includes it)
+before publishing any change to biome registration, palettes, surfaces,
+feature ordering, height handling, or profile persistence.

docs/DEVELOPER_GUIDE.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/MIGRATION.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.