MMD world-generation engine
One safe, declarative engine for ores, geology, underground deposits, biomes, world materials, retrogen, and complete modpack world profiles.
OreSpawn 4 is the next generation of MMD's world-generation library. It takes the mature ore controls of OreSpawn 3, combines them with the powerful geology work developed for Mineralogy, and turns the result into a general-purpose platform that any mod or modpack can use.
The most important idea is separation of content from world-generation policy. A metal mod can own its copper, tin, and silver blocks while OreSpawn decides how they are distributed. Mineralogy can supply dozens of rocks and geological regions without keeping a private worldgen engine. A total-conversion mod can contribute biomes, surfaces, aquifer fluids, snow, and ice. A pack author can then tune all of those contributions as one coherent world.
OreSpawn itself is deliberately passive. Simply installing it does not replace stone, remove vanilla ores, or change the Nether. A provider mod, a modpack profile, or a player using the Create World editor must choose what it should do.
Current OS4 builds
OreSpawn 4.0.1 beta builds are available for Minecraft 1.18.2 and Minecraft 1.19.4 on Forge. OreSpawn 3.3.1 remains available for older Minecraft 1.12.2 packs.
OreSpawn 3 was already much more capable than a simple “spawn this ore” utility. It supported multiple deposit patterns, weighted outputs and replacement blocks, biome filtering, fractional frequency, and retrogen. OS4 preserves that heritage and its configuration intent, but moves the whole system into a modern, provider-owned model.
Mineralogy then proved that a worldgen engine could do much more than scatter ores. Its Sky and Cyano geology modes created rock strata, geological regions, biome influence, custom ore hosts, and fluid deposits. The limitation was not the engine's ambition; it was that the engine belonged to one content mod.
OS4 makes those ideas reusable:
| Area | OreSpawn 3 | Mineralogy's engine | OreSpawn 4 |
|---|---|---|---|
| Main role | Configurable ore placement | Geology for Mineralogy's rocks and ores | Shared world-generation platform |
| Content ownership | Spawn files named blocks to place | Mineralogy supplied the content and engine | Every provider owns its declarations; OreSpawn owns execution |
| World scope | Legacy dimensions, heights, patterns, and biome filters | Rich Overworld geology with optional ore management | Ores, strata, deposits, biomes, materials, custom dimensions, and templates |
| Configuration | Primarily legacy JSON/config files | Mineralogy global and per-world geology settings | Providers, pack overrides, global defaults, templates, Create World edits, and self-contained world snapshots |
| Safety | Pack authors coordinated generators manually | Integrations were tied to Mineralogy's lifecycle | Provider validation, fail-closed overrides, ownership checks, and takeover status prevent silent duplication |
| Player experience | Powerful but configuration-led | Mineralogy supplied its own geology editor | A shared Create World editor, recommended defaults, tooltips, and an in-game guide |
The result is a single worldgen language that can describe a tiny ore-only mod, a carefully balanced expert pack, Mineralogy's complete rock system, or a dimension whose terrain and fluids are unlike the Overworld.
Start passive, then opt in through OreSpawn... on the Create World screen. Use installed blocks—or a balanced starter set of vanilla stone, deepslate, granite, diorite, andesite, and tuff—to design strata and ore placement without installing a full geology content mod.
Install a mod such as Mineralogy or Base Metals. Its provider supplies sensible defaults; OreSpawn validates them, merges them into the world profile, and performs the generation. Ore-only providers do not need to enable rock strata.
Tune providers without editing their jars, create named templates, manage vanilla ores, choose formation styles, and ship a reproducible global profile. Every world receives its own complete snapshot.
Package a declarative provider JSON or enqueue an immutable provider through Forge IMC. Keep your blocks and gameplay in your mod while OreSpawn handles dimensions, hosts, patterns, validation, and migration.
Add provider biomes, broad biome palettes, custom surfaces, aquifer fluids, deep fluids, snow, ice, rock strata, and underground deposits. Unconfigured dimensions keep their original generator.
Query the active profile, sample the exact production geology for gameplay decisions, or register a custom ore-pattern type whose settings are decoded and compiled before generation.
OS4 builds a new world's settings in a deliberate order. Later stages may tune earlier defaults, and the final result is copied into the world:
That snapshot lives at <world>/serverconfig/orespawn-worldgen.json. It travels with the world, so a single-player world moved to a dedicated server keeps the same geology when the same provider mods are installed.
Provider ownership is just as important. A present pack override is authoritative; if it is malformed, that provider becomes inactive instead of silently falling back to different defaults. A content mod should disable its native generator only when OreSpawn reports that its takeover is active. Bad IDs or invalid hosts therefore fail safely rather than quietly removing—or duplicating—ores.
Broad geological formations use sedimentary, metamorphic, intrusive igneous, and volcanic families. Geomes influence which families and rocks belong in a region, while the surface biome can bias geology without forcing identical borders.
Configure dimensions, Y ranges, frequency, fixed or ranged block budgets, height curves, cave exposure, rock families, blocks, tags, geomes, and biome filters. Outputs and hosts may both be weighted.
Create covered pockets of water, lava, oil, brine, or another installed fluid. Radius, vertical shape, lobes, solid roof, solid shell, hosts, biomes, and depth are independently configurable.
Augment an existing biome source or replace eligible regions with provider biomes. Define top, filler, underwater, and ceiling materials, then optionally change aquifer fluids, deep fluids, snow, and ice.
Target the Overworld, Nether, End, or installed custom dimensions by registry ID. Named templates can describe a complete optional world style, and total-conversion providers may offer a fresh-world default.
Optionally replace claimed vanilla ore features, flatten bedrock, and apply bounded ore or bedrock retrogen. Rock strata are never retro-generated, protecting existing terrain from a surprise rewrite.
OS4 retains two geology experiences:
The modern stable_layers algorithm is recommended for new worlds. The older sky_v1 algorithm remains available so migrated worlds can retain their established shape.
Every ore rule chooses a deposit shape. The built-in patterns are:
| Pattern | Best for |
|---|---|
| Compact | Dense, familiar, face-connected deposits |
| Vein | Wandering mineralised paths through rock |
| Normal cloud | Broad, diffuse deposits |
| Precision | Deterministic compact filling |
| Clusters | Groups of nearby connected nodes |
| Under fluids | Deposits that favour host blocks beneath a configured fluid |
Height distributions can be uniform, centre-peaked, deep-biased, or split between uniform and deep-biased placement. discard_chance_on_air_exposure controls how much ore remains hidden from cave walls. Pattern settings are compiled while the profile is baked, so generation does not repeatedly parse configuration.
Changes to a profile normally affect newly generated chunks. If you alter a world later, travel beyond explored terrain to see the new settings.
| Location or command | Purpose |
|---|---|
config/orespawn-worldgen.json | Defaults used when new worlds are created |
<world>/serverconfig/orespawn-worldgen.json | The complete, self-contained profile for one world |
config/<modid>-orespawn.json | A modpack's authoritative provider override |
config/orespawn-guide/ | The documentation bundle exported by OreSpawn |
/orespawn status | Show active mode, rules, providers, and retrogen state |
/orespawn reload | Reload providers and the active profile |
/orespawn retrogen [radius] | Queue bounded retrogen for loaded chunks |
/orespawn dump-biomes | Export the biome IDs visible to the installation |
Most mods need no custom world-generation code. Package a provider at:
src/main/resources/data/<modid>/orespawn/provider.jsonA minimal ore-only provider can be as small as:
{
"schema_version": 4,
"provider_modid": "examplemod",
"provider_revision": 1,
"ores": {
"examplemod:ore/tin": {
"block": "examplemod:tin_ore",
"enabled": true,
"dimensions": {
"minecraft:overworld": {
"enabled": true,
"min_y": -16,
"max_y": 96,
"frequency": 6.0,
"min_quantity": 4,
"max_quantity": 11,
"pattern": "vein",
"height_distribution": "triangle",
"host_tags": ["minecraft:stone_ore_replaceables"]
}
}
}
}
}That definition places tin in ordinary Overworld ore hosts. It does not enable rock strata, replace biomes, or require Mineralogy.
Provider schema 4 can additionally declare rocks, geomes, biome rules, terrain dimensions, templates, fluid deposits, biome palettes, and dimension materials. JSON Schemas and complete examples are included in the normal OreSpawn jar and exported into config/orespawn-guide/ on first load.
Mods that need programmatic construction can submit an immutable WorldgenProvider through InterModEnqueueEvent:
OreSpawnApi.enqueue(provider);Only zone.moddev.mc.orespawn.api is supported API. The normal OreSpawn jar is both the compile-time and runtime dependency; it is not intended to be shaded into another mod.
The API also provides:
A pack may override one provider with config/<modid>-orespawn.json. Overrides are ideal for changing heights, quantities, patterns, dimensions, or hosts without repacking the provider mod.
Templates are named profile overlays. They can configure formations, rocks, geomes, biome influences, ores, fluids, terrain dimensions, suppression, retrogen, and bedrock as one selectable world style. Switching templates starts from the merged provider/pack baseline, so settings from the previous template do not leak into the next one.
OS4's migration is designed to preserve intent rather than merely make old JSON parse.
It can import:
config/mineralogy-geomes.json;config/orespawn3/ and config/orespawn/;config/orespawn.cfg;The migrator understands OS3's ranged size ± variation, exclusive maximum height, fractional frequency, patterns, weighted blocks, biome filters, retrogen flags, and “all ordinary dimensions except Nether and End” behaviour. When a legacy output uniquely matches an installed provider rule, the user's values move under that provider's stable ID instead of creating a duplicate. Ambiguous entries are kept under a legacy ID and called out for review.
Migration is non-destructive: source files are retained, target profiles are backed up before persisted revisions, and a report is written to config/orespawn-migration/migration-report.txt. Existing rock strata are not rewritten.
OS4 resolves registry IDs, tags, dimensions, blocks, fluids, biomes, weights, patterns, and provider ownership before chunk generation. Its hot paths do not read JSON, call provider code, look up registry names, or log per block.
Compact deposits use pre-baked connected shapes. Unconfigured dimensions skip immediately. Biome palettes operate on cached holders and primitive weights. Retrogen is revision-marked, bounded, and scheduled a limited number of chunks per tick.
This design matters because OS4 is not only placing a few ore veins. In a full provider setup it may classify geology and replace terrain throughout every new chunk, so predictable work and fail-safe validation are first-class features.