Bring OreSpawn 4.1 to Minecraft 1.14.4

.github/workflows/ci.yml

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

CHANGELOG.txt

@@ -1,3 +1,21 @@
+Version 4.1.0.114041
+
+* Reject invalid Geome IDs instead of silently renaming them.
+* Keep expanded mod metadata intact when Eclipse rebuilds resources.
+* Add an isolated shared-ore client profile and real Nether quartz checks.
+* Retry tag-only ore and fluid hosts after Forge loads the world's tags,
+  before spawn generation. Keep working block/family rules unchanged so
+  managed Nether quartz follows its saved rule without moving existing veins.
+
+* Add a directory for loaded provider mods and optional add-on settings screens.
+* Group OreSpawn-managed ores by exact block tags. Balanced, Single, Custom,
+  and Keep Original policies keep one placement budget per channel without
+  changing existing worlds' saved behaviour.
+* Add a biome directory with exact new-terrain replacement, palette settings,
+  and dimension-wide materials controls. Existing chunks are never rewritten.
+* Preserve missing-mod settings and dormant imported Ore Dictionary aliases.
+  Provider, global, and world schemas are now 5, 8, and 7; API major remains 1.
+
 Version 4.0.16.114041
 
 * Adopt the shared 4.0.16 release identity. Forge 1.14 has neither

README.md

@@ -17,8 +17,9 @@ End" policy used by mods such as Base Metals.
 This is not the unrelated mod that adds mobs and dimensions under the same
 name.
 
-This branch builds target-qualified version `4.0.16.114041`: the OreSpawn 4.0.16
-feature set for Minecraft 1.14.4 and Forge. See the
+This branch builds target-qualified version `4.1.0.114041` for Minecraft 1.14.4
+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.
 
 ## What Happens When It Is Installed?
@@ -54,6 +55,15 @@ Important files:
 Profile edits affect newly generated chunks. Ore and flat-bedrock retrogen are
 separate opt-in features; OreSpawn never retro-generates rock strata.
 
+**Ore Sources** groups ores by exact block tags such as `forge:ores/sulfur`.
+When two loaded ordinary MMD providers share one tag, new worlds use a
+Balanced output policy and one placement budget per channel. Older worlds keep
+their saved Keep Original behaviour. Imported Ore Dictionary aliases remain
+visible but dormant until you assign a known exact block tag. The **Biomes**
+directory can replace one loaded biome with another in new terrain; its
+**Overworld Materials** control applies across the dimension, not just the
+selected biome.
+
 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
@@ -122,7 +132,11 @@ launches exclude tests and fixtures. Published jars are deterministic,
 SRG-reobfuscated for the Forge 28 runtime, audited for their access transformer
 and contents, and accompanied by SHA-256 checksums.
 
-Machine-specific `AGENTS.md` and `agent-notes/` files are intentionally ignored.
+For a shared-ore GUI test, use the separate **runOreSourcesClient** Eclipse
+profile. It loads two dummy providers and keeps its worlds in `run-ore-sources`.
+See [the build guide](gradle/README.md#trying-shared-ores-in-the-editor) for the
+test blocks and controls. These providers are never included in release jars.
+
 Public developer and AI integration guidance lives in `docs/` and is included
 in the built jar.
 

docs/API.md

@@ -50,8 +50,22 @@ 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 4. Legacy provider schemas 1-3 remain
-readable. Schema 4 is required for biome palettes and dimension materials.
+The builder emits provider schema 5. 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.
+
+For custom ore patterns, `OreGenerationContext` extends the existing
+`OrePlacementContext` without changing its binary contract. It exposes the
+world seed, dimension, chunk coordinates, and an optional geology sampler.
+The `tryPlace(x, y, z, outputIdentity)` overload gives separated slices of one
+logical deposit the same output choice. Code built against the older context
+continues to work through the original `tryPlace` method.
+
+Client add-ons may register one optional configuration screen per mod through
+`WorldSettingsExtensionRegistry.registerConfigScreen(modId, factory)` during
+client initialization. OreSpawn shows it in the loaded-mod directory and
+returns Escape to that directory. Do not load this client-only API on a
+dedicated server.
 
 Provider-owned fluid deposits are declarative and may target several dimensions:
 

docs/BIOMES.md

@@ -171,10 +171,18 @@ then lexical template ID order.
 
 ## World-Creation Editor
 
-**Biomes & World Materials** is visible even when rock strata are disabled.
-It lists palettes and materials by dimension, uses installed-registry pickers,
-and validates IDs before world creation. The editor is creation-only in 4.0.0;
-existing worlds remain editable through their self-contained server profile.
+**Biomes** is visible even when rock strata are disabled. Its directory shows
+loaded and referenced biomes once, with provider placement rules and effective
+palette order. It can replace one loaded source biome with another in newly
+generated terrain. The exact replacement layer runs after ordinary palettes;
+existing chunks are never rewritten. A missing target stays dormant until its
+mod returns. Palette settings expose mode, scope, region size, coverage,
+fallback weight, and namespace filters without reordering provider palettes.
+
+The materials button belongs to the selected dimension, not the selected
+biome. Aquifer fluid, snow, and ice substitutions apply across every biome in
+that dimension. Forge 1.14.4 has no separate deep-aquifer generator fluid, so
+that stored field remains unavailable on this target.
 
 ## Performance Boundaries
 

docs/CONFIGURATION.md

@@ -4,13 +4,14 @@ OreSpawn uses three JSON contracts:
 
 | File | Schema | Purpose |
 |---|---:|---|
-| `config/orespawn-worldgen.json` | 6 | Installed-pack defaults for new worlds |
-| `<world>/serverconfig/orespawn-worldgen.json` | 5 | Self-contained snapshot for one world |
-| `config/<modid>-orespawn.json` | 4 | Optional authoritative provider override |
+| `config/orespawn-worldgen.json` | 8 | Installed-pack defaults for new worlds |
+| `<world>/serverconfig/orespawn-worldgen.json` | 7 | Self-contained snapshot for one world |
+| `config/<modid>-orespawn.json` | 5 | Optional authoritative provider override |
 
-A provider may package schema 4 at `data/<modid>/orespawn/provider.json`.
-Legacy provider schemas 1-3 remain accepted. Fluid deposits require schema 3;
-biome palettes and dimension materials require schema 4.
+A provider may package schema 5 at `data/<modid>/orespawn/provider.json`.
+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.
 
 The profile for a new world is merged in this order: passive OreSpawn defaults,
 packaged or API providers, provider override files, the global configuration,
@@ -29,7 +30,7 @@ report for the exact decision.
 
 | Field | Values | Meaning |
 |---|---|---|
-| `schema_version` | Contract-specific integer | Global 6, world 5, provider 4 |
+| `schema_version` | Contract-specific integer | Global 8, world 7, provider 5 |
 | `geology_mode` | `geome`, `legacy` | Sky/geome engine or Cyano legacy engine |
 | `place_fluid_deposits` | boolean | Master switch for configured fluid-deposit rules |
 | `manage_vanilla_ores` | boolean | Lets OreSpawn suppress and replace claimed vanilla ore features |
@@ -44,6 +45,8 @@ report for the exact decision.
 | `biome_palettes` | object keyed by provider-owned rule ID | Optional native-biome overlays and surfaces |
 | `dimension_materials` | object keyed by provider-owned rule ID | Aquifer fluid, snow, and ice substitutions |
 | `ores` | object keyed by rule ID | Ore outputs and per-dimension placement |
+| `ore_material_groups` | object keyed by material ID | Friendly names and exact block-tag aliases; imported Ore Dictionary names stay dormant |
+| `ore_source_policies` | object keyed by material and dimension | Saved output mode, weights, and placement source per channel |
 | `fluid_deposits` | object keyed by rule ID | Provider-owned fluids and per-dimension placement |
 | `retrogen` | object | Bounded ore retrogen controls |
 | `flat_bedrock` | object | Opt-in flat bedrock controls |
@@ -179,6 +182,7 @@ Each enabled ore dimension uses:
 | `node_size` | 1-32 | Cluster node size |
 | `length` | 1-64 | Pattern path length where supported |
 | `fluid` | registry ID | Fluid used by `underfluids` |
+| `placement_channel` | registry ID | Independent placement budget shared by equivalent ores in consolidated modes |
 
 At least one of `host_families`, `host_blocks`, or `host_tags` must be present.
 Hosts may be plain registry IDs or weighted objects such as
@@ -196,6 +200,30 @@ The selector `orespawn:all_except_nether_end` covers every dimension except
 the vanilla Nether and End. Explicit rules in `dimensions` override selector
 rules for the same ore and dimension, including explicit disabled rules.
 
+### Material groups and source policies
+
+Provider schema 5 may add a `material` ID to an ore. Otherwise OreSpawn infers
+the material only from exact loaded block tags under `*/ores/*`; it does not
+guess from a block or mod name. `ore_material_groups` stores a friendly name
+and `block_tag_entries` for each group. Imported `ore_dictionary_entries`
+remain dormant unless a user gives the group an exact tag mapping.
+
+`ore_source_policies` stores one material-and-dimension decision: Keep Original
+(`keep_separate`) or consolidated Balanced, Single, or Custom output selection.
+The `placement_sources` object names one source rule for each placement
+channel. Consolidation uses that rule's frequency, shape, depth, and hosts,
+then picks the selected output for a whole deposit. It does not give every
+output its own placement budget. External generators are shown for context but
+cannot be suppressed by OreSpawn.
+
+For a newly created world, two loaded ordinary MMD providers with the same
+exact ore tag start Balanced. A configured Sulfur or Lithium priority chooses
+the initial placement source; other conflicts use stable owner/rule-ID order.
+Missing providers create no phantom ores. Existing worlds retain their saved
+policy, defaulting to Keep Original on upgrade. Both global and world profile
+upgrades keep a backup; editing the global defaults in the UI is saved only
+when the main OreSpawn editor's Done is pressed.
+
 ## Fluid Deposits, Retrogen, And Bedrock
 
 Each `fluid_deposits` entry has a stable provider-namespaced rule ID, an

docs/DEVELOPER_GUIDE.md

@@ -12,6 +12,8 @@
 | Add covered underground oil or another fluid | Provider schema 3 fluid deposit |
 | Add or place biomes without a framework dependency | Provider schema 4 biome palette |
 | Replace surfaces, aquifers, snow, or ice | Provider schema 4 dimension materials |
+| Share placement between equivalent ore blocks | Provider schema 5 material and placement channel, with one exact block tag |
+| Add an OreSpawn-linked settings screen | Client-only `WorldSettingsExtensionRegistry` |
 | Inspect active geology at runtime | `GeologyProfileView` and `GeologySampler` |
 
 Strata are optional. If no enabled terrain dimension has eligible rocks,
@@ -21,7 +23,7 @@ blocks or tags.
 
 ## Provider JSON Quick Start
 
-Put a schema-4 file in your mod jar at:
+Put a schema-5 file in your mod jar at:
 
 ```text
 src/main/resources/data/examplemod/orespawn/provider.json
@@ -33,7 +35,7 @@ stone without enabling strata:
 
 ```json
 {
-  "schema_version": 4,
+  "schema_version": 5,
   "provider_modid": "examplemod",
   "provider_revision": 1,
   "ores": {
@@ -215,3 +217,14 @@ pattern beside every built-in type.
 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.
+
+For manual shared-ore testing, generate the Eclipse runs and select
+`runOreSourcesClient`. Two isolated dummy providers share a Sulfur tag and use
+coloured wool as test outputs. The profile keeps its saves in `run-ore-sources`
+and does not create worlds automatically. Normal launches and release jars
+exclude these providers.
+
+The opt-in `nativeOreIntegrationTest` uses an official Forge server supplied
+through `packagedForgeServerRuntime`. It checks managed quartz with Forge 28's
+netherrack tag and explicit block hosts, exact-save reload, and a depth change
+that affects new terrain only. All test worlds stay under `build/`.

docs/PLAYER_GUIDE.md

@@ -25,8 +25,10 @@ adds them. You can remove the starter rocks or add blocks from installed mods
 before creating the world.
 
 Mods can also offer new biomes and world materials without enabling strata.
-Use **Biomes & World Materials** to inspect installed dimension palettes,
-surface blocks, aquifer fluids, snow, and ice. The picker only accepts real
+Use **Biomes** to inspect loaded biomes, placement palettes, and surface rules.
+Replacing a biome changes only newly generated terrain. The dimension's
+**Materials** button changes aquifer fluid, snow, or ice across every biome in
+that dimension, not only the biome currently selected. The picker only accepts
 installed registry entries. Missing optional compatibility biomes are skipped
 safely instead of breaking world creation.
 
@@ -48,11 +50,13 @@ safely instead of breaking world creation.
   installed mod. These are covered underground deposits, not exposed vanilla
   lakes. **Solid Cover** controls the roof thickness, while **Solid Shell**
   prevents a deposit from opening into a cave at its sides or underside.
-- **Biomes & World Materials** controls broad biome regions and what their
-  surfaces, underground water, snow, and ice are made from. **Augment** mixes
-  new biomes into the existing source; **Replace** creates a complete provider
-  style. Namespace scope protects other biome mods unless a pack deliberately
-  opts them in.
+- **Biomes** lists installed and referenced biomes and their placement rules.
+  **Replace in new terrain with...** is an exact, one-to-one choice and does
+  not rewrite existing chunks. Palette settings still offer **Augment** for a
+  provider mix or **Replace** for a complete provider style.
+- **Ore Sources** groups interchangeable ores by exact block tags. Balanced
+  shares one placement budget across eligible outputs; Single picks one output;
+  Custom lets you choose weights. Keep Original leaves every rule independent.
 
 **World Materials** applies across an entire dimension. **Aquifer Fluid**
 changes the normal below-sea-level fluid. Minecraft 1.14.4 exposes only that

docs/PROVIDERS.md

@@ -6,12 +6,20 @@ Provider mods may contribute through Forge IMC, a packaged resource at
 present malformed override leaves that provider inactive instead of silently
 falling back.
 
-Provider schema 4 supports `profile_defaults`, `rocks`, `ores`,
+Provider schema 5 supports `profile_defaults`, `rocks`, `ores`,
 `fluid_deposits`, `geomes`, `biome_rules`, `terrain_dimensions`, and
 `templates`, plus `biome_palettes` and `dimension_materials`. Each file requires a
 matching `provider_modid`, a positive `provider_revision`, and at least one
-contribution. Legacy schemas 1-3 remain accepted; schema 3 introduced fluid
-deposits and schema 4 introduces biome and world-material controls.
+contribution. Legacy schemas 1-4 remain accepted; schema 3 introduced fluid
+deposits, schema 4 added biome and world-material controls, and schema 5 adds
+optional `material` and `placement_channel` IDs for exact ore grouping.
+
+Use the same exact loaded block tag, such as `forge:ores/sulfur`, for ores that
+are interchangeable. OreSpawn never infers equivalence from similar block or
+mod names. When two ordinary MMD providers for the same tag are loaded, a new
+world starts Balanced with one placement budget per channel. An absent mod
+adds no phantom output or placement rule, and old worlds keep their saved
+choices. Enrichment and dimension-specific providers are kept separate.
 
 An ore-only provider does not need rocks, geomes, or terrain dimensions. Give
 each ore explicit host blocks or tags and OreSpawn will leave vanilla terrain,

docs/README.md

@@ -6,6 +6,9 @@ shaded or embeddable engine artifact.
 
 Choose the guide that matches what you are doing:
 
+If you are integrating a mod, start with the developer guide; the API and
+provider guides give the exact Java and JSON contracts.
+
 - [Player and server guide](PLAYER_GUIDE.md)
 - [Developer quick start and complete integration map](DEVELOPER_GUIDE.md)
 - [Configuration field reference](CONFIGURATION.md)
@@ -18,7 +21,6 @@ Choose the guide that matches what you are doing:
 - [Migration](MIGRATION.md)
 - [Troubleshooting](TROUBLESHOOTING.md)
 - [Versioning and release conventions](VERSIONS.md)
-- [Compact instructions for coding agents](AGENTS.md)
 
 Validated examples are in `examples/`; JSON Schemas are in `schemas/`.
 The provider and migration guides include OS3-compatible ranged quantities and

docs/VERSIONS.md

@@ -51,8 +51,8 @@ Examples:
 
 | Minecraft | Loader | Target | Example full OreSpawn version |
 | --- | --- | ---: | --- |
-| 1.13.2 | Forge | `113021` | `4.0.6.113021` |
-| 1.14.4 | Forge | `114041` | `4.0.16.114041` |
+| 1.13.2 | Forge | `113021` | `4.0.16.113021` |
+| 1.14.4 | Forge | `114041` | `4.1.0.114041` |
 | 1.20.6 | Forge | `120061` | `4.0.6.120061` |
 | 1.21.11 | Forge | `121111` | `4.0.6.121111` |
 | 26.1.2 | Forge | `2601021` | `4.0.6.2601021` |
@@ -157,6 +157,11 @@ lifecycle portion of 4.0.16 are not applicable; it adopts the shared 4.0.16
 identity while retaining ordinary benchmark auto-stop. A branch may therefore
 legitimately skip functional version numbers.
 
+The 1.14.4 line now advances to 4.1.0 for material-group ore policies,
+the loaded-mod directory, and exact new-terrain biome replacements. It keeps
+the `114041` target suffix, API major 1, and the target's existing registry
+identities while provider/global/world schemas advance to 5/8/7.
+
 This provides three useful guarantees:
 
 1. A functional version is not used to describe two unrelated change sets.

docs/examples/examplemod-orespawn.json

@@ -1,5 +1,5 @@
 {
-  "schema_version": 4,
+  "schema_version": 5,
   "provider_modid": "examplemod",
   "provider_revision": 1,
   "rocks": {