Update OreSpawn for Minecraft 1.13.2

.github/workflows/ci.yml

@@ -126,9 +126,9 @@ jobs:
           if-no-files-found: error
           retention-days: 30
           path: |
-            build/libs/OreSpawn-4.1.6.113021.jar
-            build/libs/OreSpawn-4.1.6.113021-sources.jar
-            build/libs/OreSpawn-4.1.6.113021-javadoc.jar
+            build/libs/OreSpawn-4.1.7.113021.jar
+            build/libs/OreSpawn-4.1.7.113021-sources.jar
+            build/libs/OreSpawn-4.1.7.113021-javadoc.jar
             build/release/SHA256SUMS
             CHANGELOG.txt
 

CHANGELOG.txt

@@ -1,3 +1,32 @@
+Version 4.1.7.113021
+
+* Add surveys, chunk reports and rule explanations for checking a modpack's
+  generated terrain. Restore clearchunk with clickable previews, verified
+  backups and checked undo.
+* Keep retrogen completion markers through normal saves and server restarts,
+  including when retrogen is switched off.
+  Recover chunk bookkeeping through Forge 1.13's capability persistence, where
+  the usual chunk-data load event is missing.
+* Add optional natural rock formations, shared placement/sampling APIs and
+  provider controls for background ore generation. Existing worlds keep their
+  saved geology and generation choices.
+* Let providers keep new structural defaults out of existing worlds, and let
+  templates preserve edited formation settings.
+* Replace ordinary Overworld fluid overrides after native terrain generation,
+  preserving caves, later lakes and springs. Keep the compatibility path for
+  fluids with different lighting properties.
+  Keep native water-dependent decoration, including swamp trees, ice and
+  aquatic plants, working with the substituted fluid.
+* Rebuild release checksums when a release jar changes.
+* Keep test fixtures compatible with Eclipse's Java 8 access restrictions.
+* Keep native stone-patch suppression working when vanilla ore management
+  wraps the same feature list.
+* Avoid repeated chunk lookups and temporary arrays in ore and rock selection.
+* Keep ore exposure checks inside the available generation region, fixing a
+  chunk-boundary crash when generating ores with air-exposure rules.
+* Keep saved ore settings when a provider renames a recognised rule. Add the
+  matching modern rule as a disabled alternative rather than another ore pass.
+
 Version 4.1.6.113021
 
 * Leave vanilla ores to Minecraft when Manage Vanilla Ores is off. When

README.md

@@ -14,10 +14,14 @@ Its OS3 compatibility layer preserves ranged legacy block budgets, exclusive
 legacy height ceilings, and the historical "all dimensions except Nether and
 End" policy used by mods such as Base Metals.
 
+Recognised provider rule renames keep the saved ore settings and add the modern
+rule as a disabled, editable alternative, avoiding an extra generation pass.
+See [retained provider rules](docs/MIGRATION.md#retained-provider-rules).
+
 This is not the unrelated mod that adds mobs and dimensions under the same
 name.
 
-This branch builds target-qualified version `4.1.6.113021` for Minecraft 1.13.2
+This branch builds target-qualified version `4.1.7.113021` for Minecraft 1.13.2
 and Forge. It adds material-group ore arbitration, exact biome replacements,
 and a directory for installed provider mods to the OreSpawn 4.0.16 base. See the
 [versioning policy](docs/VERSIONS.md) for the encoding and release convention.
@@ -37,6 +41,11 @@ TerraBlender.
 
 ## Players And Server Owners
 
+Modpack authors can measure loaded terrain with [admin and survey tools](docs/ADMIN_TOOLS.md).
+Clearing requires a preview, confirmation and verified backup.
+Add-ons can declare [natural rock formations](docs/ROCK_FORMATIONS.md) without
+changing existing worlds that do not have those settings.
+
 When a provider exposes world settings, use **OreSpawn...** on the Create World
 screen. **Recommended Defaults** restores the settings supplied by the
 installed mods and pack. The in-game **Help & Guide** explains the controls.
@@ -132,7 +141,7 @@ launches exclude tests and fixtures. Published jars are deterministic,
 SRG-reobfuscated for the Forge 25 runtime, audited for their access transformer
 and contents, and accompanied by SHA-256 checksums.
 
-Public developer and AI integration guidance lives in `docs/` and is included
+Developer guidance lives in `docs/` and is included
 in the built jar.
 
 OreSpawn is licensed under LGPL-2.1.

build.gradle

@@ -13,7 +13,7 @@ plugins {
 
 group = project.mod_group
 version = project.mod_version
-base.archivesName = 'OreSpawn'
+base.archivesName = project.mod_artifact
 
 def versionParts = project.mod_version.toString().tokenize('.')
 if (versionParts.size() != 4 || !versionParts.every { it ==~ /\d+/ }) {
@@ -53,6 +53,9 @@ tasks.withType(JavaCompile).configureEach {
     targetCompatibility = JavaVersion.VERSION_1_8
     options.encoding = 'UTF-8'
     options.compilerArgs.addAll(['-Xmaxerrs', '1000'])
+    // javac 8 can change anonymous-class constant pools after a partial compile.
+    // Compile the whole source set so incremental and clean jars match.
+    options.incremental = false
 }
 tasks.named('compileTestJava', JavaCompile) { options.compilerArgs.add('-proc:none') }
 tasks.withType(Test).configureEach {
@@ -263,8 +266,11 @@ tasks.named('processResources', ProcessResources) {
     inputs.property('forge_version_range', project.forge_version_range)
     inputs.property('loader_version_range', project.loader_version_range)
     inputs.property('minecraft_version_range', project.minecraft_version_range)
+    def modMetadata = ['mod_id', 'mod_name', 'mod_authors', 'mod_description', 'mod_license',
+                       'mod_url', 'mod_issue_url'].collectEntries { name -> [(name): project.property(name)] }
+    inputs.properties(modMetadata)
     filesMatching('META-INF/mods.toml') {
-        expand([
+        expand(modMetadata + [
                 version: project.version,
                 minecraft_version: project.minecraft_version,
                 forge_version_range: project.forge_version_range,
@@ -306,4 +312,6 @@ apply from: 'gradle/release/publishing.gradle'
 apply from: 'gradle/verification/packaged-forge.gradle'
 apply from: 'gradle/verification/ore-sources.gradle'
 apply from: 'gradle/verification/native-ores.gradle'
+apply from: 'gradle/verification/admin-tools.gradle'
+apply from: 'gradle/verification/parity.gradle'
 apply from: 'gradle/verification/performance.gradle'

docs/ADMIN_TOOLS.md

@@ -0,0 +1,131 @@
+# Admin and distribution tools
+
+Use these tools in a disposable Creative world while tuning a pack. Surveys
+do not generate terrain or enable OreSpawn's vanilla-ore management. Clearing
+is different: it changes saved blocks, including matching player-placed rocks.
+
+## Measure what actually generated
+
+```
+/orespawn help
+/orespawn status verbose
+/orespawn chunk
+/orespawn chunk -2 3
+/orespawn survey 1
+/orespawn survey 2 --y 0 48 --block minecraft:redstone_ore
+/orespawn survey 0 --center -2 3 --block minecraft:diorite
+/orespawn explain minecraft:redstone_ore 100 20 -40
+/orespawn retrogen status
+/orespawn jobs
+/orespawn jobs <job-id>
+/orespawn cancel <job-id>
+```
+
+New diagnostic commands require permission level 2. Ordinary `status` remains
+available without operator permission. Existing `reload`, `retrogen [radius]`
+and `dump-biomes` commands keep their behaviour. `retrogen status` never queues
+work, enables retrogen or writes a generation marker. Its completed flag is
+session bookkeeping, not a claim about a chunk's complete history.
+
+Chunk coordinates are block coordinates divided by 16, rounding down, including
+negative coordinates. Without coordinates, commands use the player's chunk;
+the console uses Overworld spawn. Shared options are `--center <chunkX chunkZ>`,
+`--dimension <loaded-numeric-or-namespaced-ID>`, `--y <min max>` and the survey
+filter `--block <namespace:block[property=value]>`. Heights are inclusive. Radius
+defaults to 1 and is limited to 8: a square of `(2 * radius + 1)` chunks per side.
+
+Only chunks already loaded are visited. The tool records skipped chunks and
+chunks that unload during a scan. A partial report is not a complete regional
+sample. Scans happen over a recorded interval, not at one atomic world instant.
+For a fair comparison, use the same seed, dimensions, coordinates, height range
+and coverage, and avoid mining or construction while collecting the sample.
+
+Reports are stored in the world's `orespawn/diagnostics/reports/<job-id>/`.
+Long chat summaries end in `...`; the saved reports are not shortened.
+Check `jobs <job-id>` for export completion or I/O failure. JSON records block
+states and categories, exact Y levels, biome columns, per-chunk counts, coverage
+and the active profile fingerprint. CSV files provide the same count tables.
+Total sampled volume includes air; non-air volume is reported separately. A
+block filter restricts both those denominators to the matching sample.
+
+Known ores come from native identities, configured outputs and exact block-tag registrations. Blocks are counted once even if several providers
+share them. All observed states are exported, including unclassified blocks.
+Configured fluid outputs are listed separately from ores. Reports do not
+identify which mod historically placed a block or declare that a distribution
+is statistically correct from a small sample.
+
+`explain` uses OreSpawn's actual baked placement budget, host tests and
+chunk-centre biome checks. Frequency means expected attempts per chunk, not
+guaranteed blocks. Weighted host tests, random geometry, exposure rolls and
+private extension checks still affect results. A rock under the cursor today
+is not necessarily the host that existed during original generation. Chunk
+geology information is labelled as a current base-geology prediction, not
+saved formation provenance.
+`chunk` also records observed block states down the centre column, every 16
+blocks and at the selected range's endpoints. These sparse samples are not a
+whole-chunk count; use `survey 0` for that.
+
+## Expose one chunk, with a way back
+
+```
+/orespawn clearchunk --center -2 3
+/orespawn clearchunk confirm <preview-token>
+/orespawn undo <backup-id>
+/orespawn undo <backup-id> confirm <undo-preview-token>
+/orespawn jobs backups
+```
+
+Clearing and undo require permission level 4. Player operators must be Creative
+or Spectator; clearing is refused while a Survival/Adventure player occupies
+the target chunk. Keep the surrounding lighting area loaded. The aliases
+`/clearchunk` and `/clearchunks` are registered only if another mod has not
+claimed them. Both mean one chunk, not a region.
+
+The first command only scans and prints a preview; no blocks change yet.
+Review the coordinates, height range and removal count, then open chat (T by
+default) and click **Confirm clearing**. That click sends the confirmation
+command. **Cancel** dismisses the preview without changing blocks; **Details**
+opens the job report. Hover over a link to see its exact command. The commands
+above also work when typed, and the server console prints a copyable command.
+
+After clearing, the **Undo…** link starts a restoration preview, not an
+immediate restore. Review it and click **Confirm undo** to restore the blocks.
+Tokens expire after 120 seconds and belong to their operator and snapshot.
+A changed profile or snapshot requires a new preview. There is no immediate, unconfirmed clear mode.
+
+Clearing removes recognised native/provider host rocks and background fluids.
+Known ore outputs, configured fluid deposits, bedrock, tile entities and
+unrecognised blocks are protected. Protection wins if a state is both an ore
+and a host. When a configured deposit uses ordinary water or lava, the same
+fluid elsewhere is protected too: there is no reliable historical provenance.
+
+Before the first write, the tool writes, flushes and verifies an immutable
+checksummed journal under `orespawn/diagnostics/backups/<backup-id>/`.
+If that fails, no clearing occurs. Backups are not automatically deleted.
+They remain on disk after restarts; `jobs backups` gives their directory.
+Journals record the Minecraft version and are not interchangeable with backups
+from other Minecraft versions, whose height and block-state encodings differ.
+
+Undo validates every recorded state and checks the current blocks before
+restoring anything. Already-restored cells are harmless; other intervening
+edits cause a conflict rather than being overwritten. Work can be cancelled
+or interrupted, so always inspect its final job status. A partial edit remains
+recoverable from its original journal and never resumes by itself after restart.
+Cancellation stops block writes, then finishes bounded lighting cleanup. If
+the chunk or its lighting area unloads, the report records the interruption
+and the journal remains available for checked recovery instead of claiming completion.
+Only unfinished height and lighting cleanup is retained with the chunk. It resumes
+in bounded steps when its lighting area is loaded; block edits never resume by themselves.
+
+Undo restores recorded block states, not entity movement, elapsed time, mining
+or changes made elsewhere. Fluids from outside the selection can later flow
+back in. It is not a substitute for a full world backup.
+
+One server job runs at a time, yielding after 16,384 block visits or a 4 ms
+cooperative budget. File output runs separately and touches no live world.
+No command expands the loaded chunk set to finish a report or an edit.
+Reports stop with an explicit error above 500,000 count-table rows; individual
+sidecars are limited to 32 MiB. Reduce the area or height range if you hit a
+limit. Existing backups are never removed to make room.
+The file-worker backlog is capped at 32 tasks. A full queue reports failure;
+it never runs file output on the server thread or starts an unbacked edit.

docs/API.md

@@ -51,7 +51,7 @@ coverage with `OreDefinition.Builder.dimensionSelector(...)` and
 `OreDimensionSelector.ALL_EXCEPT_NETHER_AND_END`. Explicit dimensions
 override that selector and prevent duplicate placement.
 
-The builder emits provider schema 5. Legacy provider schemas 1-4 remain
+The builder emits provider schema 5, or schema 6 when it declares rock formations. Legacy provider schemas 1-4 remain
 readable. Schema 4 is required for biome palettes and dimension materials;
 schema 5 adds explicit material and placement-channel IDs. API major remains 1.
 
@@ -178,3 +178,11 @@ generation.
 
 `OreSpawnOreIntegration` remains as a deprecated facade for early ore-provider
 integrations. New code should use `OreSpawnApi`.
+
+## Formation and background controls
+
+New integrations can use `mergeNewEntriesIntoExistingWorlds(false)` on the
+provider builder and `backgroundGenerationScale(value)` on an ore dimension.
+Both preserve existing behavior when omitted. Formation declarations and the
+read-only `GeologyColumn.formationAt(y)` query are described in
+[Natural formations](ROCK_FORMATIONS.md).

docs/CONFIGURATION.md

@@ -9,6 +9,9 @@ OreSpawn uses three JSON contracts:
 | `config/<modid>-orespawn.json` | 5 | Optional authoritative provider override |
 
 A provider may package schema 5 at `data/<modid>/orespawn/provider.json`.
+Providers that declare `rock_formations` use schema 6; all existing schemas
+remain supported. Formation materials use flattened block IDs and optional
+exact `properties`, not numeric metadata.
 Legacy provider schemas 1-4 remain accepted. Fluid deposits require schema 3;
 biome palettes and dimension materials require schema 4. Explicit ore material
 and placement-channel IDs require schema 5.
@@ -276,3 +279,6 @@ ordinary solid blocks, and hostless rules are rejected before generation.
 Copying a world's `serverconfig/orespawn-worldgen.json` to the same location in
 a dedicated server world reproduces its choices when the same referenced mods,
 blocks, biomes, dimensions, and tags are installed.
+See [Natural formations](ROCK_FORMATIONS.md) for substrate bodies and
+[Admin tools](ADMIN_TOOLS.md) for measured distribution reports. Neither
+changes existing terrain merely by installing this update.

docs/MIGRATION.md

@@ -1,5 +1,41 @@
 # Migration
 
+## Retained Provider Rules
+
+An older profile can keep an ore rule after its provider renames that rule.
+OreSpawn must not add a second generation pass just because the ID changed.
+The merge recognises OreSpawn's imported `orespawn:legacy/<provider>/...`
+rules and the following exact Base Metals replacements:
+
+- `basemetals:legacy/<material>_ore` to `basemetals:ore/<material>` for
+  coldiron, adamantine, starsteel, tin, lead, zinc, silver, mercury, nickel
+  and platinum.
+
+A match needs one saved rule and one provider candidate with the same single
+output, default metadata, and dimension/selector and effective placement-channel
+footprint. Conflicting provider ownership, mixed outputs, different deep outputs
+and ambiguous matches are not treated as replacements. A generic mod's
+`legacy/` name is not enough evidence.
+
+For a recognised match, the missing modern rule is added as a complete,
+disabled alternative. The saved rule keeps its rates, hosts, heights, pattern,
+enablement and source choices, including disabled and zero-rate settings.
+Fresh worlds still use the provider's normal defaults.
+
+You can enable the alternative in the ore settings. Later merges retain that
+choice, existing modern rules and recorded deletions. A recorded deletion of
+one of the historical Base Metals IDs also leaves its mapped replacement
+disabled. Deleted imports without an exact mapping are not guessed from their
+names.
+
+This repair does not automatically remove an already-saved historical
+Base Metals/modern pair: both may have been selected deliberately. Review
+ambiguous or previously affected profiles before changing their choices.
+It does not alter generated chunks, public APIs or saved formats.
+
+The existing OS1 import repair still applies when its own provenance and
+backup checks are met; this rule-rename check does not replace it.
+
 ## Provider-Aware OS3 Imports
 
 When an OreSpawn 2/3 file is named for an installed provider, the migrator now
@@ -120,3 +156,15 @@ On Minecraft 1.13.2, revision 10 converts only untouched managed-ore signatures
 to the target's native height range, frequency, quantity, pattern, and exposure
 behavior. It also restores the separate Badlands gold rule. Hand-edited rules
 and explicitly stored Custom values are preserved.
+## Retrogen and geology in 4.1.7
+
+Completed retrogen revisions now survive ordinary saves, reloads and periods
+with retrogen disabled. Changing the configured revision does not mark an
+unprocessed chunk complete. Force and the explicit retrogen command still
+request another pass; this fix cannot recover completion markers already
+lost before the update.
+
+Profiles without `rock_formations` stay without them. New provider formations
+are not merged into existing worlds. No formation or material retrogen is
+introduced. Saved ore rates, hosts, source choices and deliberate deletions
+remain intact.

docs/PLAYER_GUIDE.md

@@ -115,3 +115,10 @@ 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.
+## Checking a modpack's distribution
+
+Operators can use `/orespawn survey 1` to count blocks in loaded chunks,
+`/orespawn chunk` for a local report and `/orespawn explain <rule-id>`
+to inspect eligibility. These do not load new terrain or turn on vanilla-ore
+management. See [Admin tools](ADMIN_TOOLS.md) before using clearing or undo;
+those commands change blocks and are intended for disposable test worlds.