Ore Distribution

# Ore Distribution

**Take full control of ore generation — retune vanilla, mod, and datapack ores, and grow massive geological mega-veins — all placed deterministically and safely, on a dedicated-server-friendly, data-driven engine.**

Ore Distribution automatically discovers every ore in your world (vanilla, modded, and datapack) and hands you the dials: make diamonds ten times rarer, double your copper, disable an ore entirely, or drop in enormous cross-chunk **mega-veins** for a completely different mining economy — without writing a single datapack.

> Minecraft **1.21.1** · **NeoForge 21.1.x** · Java 21 · Server-authoritative (safe on dedicated servers)

---

## ✨ Highlights

- 🔎 **Automatic ore discovery** — finds vanilla, mod, and datapack ores on their own. No per-ore setup required.
- 🎚️ **Per-ore & per-dimension tuning** — frequency and size multipliers with intuitive, honest semantics.
- 🏔️ **Mega-veins** — large, natural-looking geological deposits that cross chunk borders seamlessly.
- 🌍 **Dimension-aware takeover** — change the Overworld and Nether while leaving other dimensions untouched.
- 🔒 **Secret-salted placement** — ore positions can't be computed from the public world seed by ordinary players.
- 🧩 **Adapter API** — mod authors can teach it about custom ore systems.
- 🛡️ **Safe by design** — structure protection, fail-safe startup, and hard performance limits.

---

## 🧠 How It Works

On first launch, Ore Distribution scans your server's registries and builds an editable configuration for **every** ore it finds, using each ore's **detected source values as the defaults**. With everything at `1.0`, your world generates exactly like vanilla-plus-mods — until you decide to change something.

At world generation time it does two things, once per new chunk:

1. **Suppresses** the original natural ore generation (only in dimensions you enabled).
2. **Replaces** it with controlled generation from the same source data — so the change is clean, with no duplicated or deleted ores.

Everything is computed from an immutable plan built at server start, so there's no config parsing or heavy work during chunk generation.

---

## 🎚️ Frequency & Size — Clear, Honest Numbers

A `frequency_multiplier` scales the **expected number of deposits linearly**:

| Value | Effect |
|------:|--------|
| `1.0` | Original frequency (unchanged) |
| `0.5` | About half as many |
| `0.1` | About one tenth — ten times rarer |
| `2.0` | About twice as many |
| `0.0` | Disabled |

`size` multipliers scale vein/deposit size the same way. Fractional values are handled with unbiased rounding, so rare ores **never accidentally drop to zero**.

---

## ⛏️ Standard Veins vs. Mega-Veins

**Standard veins** are the normal per-chunk ore scattering you already know — now fully tunable.

**Mega-veins** are an additional system: rare, large, branching geological deposits that span multiple chunks and connect naturally across borders (no ugly straight cuts at chunk edges). Choose a shape per ore:

- `BRANCHING_LODE` (default) · `ELLIPSOID_CLUSTER` · `RIBBON` · `STRATIFORM` · `PIPE`

Turn them on or off, and tune their frequency and size independently from standard veins.

---

## 🧬 Two Generation Strategies (per ore)

- **`SOURCE_COMPAT`** (default) — replays the original ore feature, so at `1.0` it preserves the source distribution exactly; frequency and size scale precisely from there.
- **`CUSTOM`** — ignore the source and define your own: output blocks, host rock, Y range, vertical distribution, vein sizes, and more.

---

## 🌍 Dimension-Aware Control

Every dimension is added to the config automatically. Defaults:

| Dimension | Default |
|-----------|:-------:|
| Overworld | ✅ enabled |
| Nether | ✅ enabled |
| The End | ❌ disabled |
| Modded / custom dimensions | ❌ disabled |

Because takeover is dimension-aware, an ore that appears in both an enabled and a disabled dimension keeps its **original** generation in the disabled one. Dimension height limits and relative anchors (above-bottom / below-top) are respected — no Overworld assumptions.

---

## 🔒 Secret-Salted, Deterministic Placement

Ore layout is a pure function of a **private per-world secret salt** plus the dimension, chunk/cell, ore, and algorithm version. This means:

- Generation is fully **deterministic** — identical no matter the chunk order, threading, or restarts.
- Ordinary players **cannot derive ore positions from the public world seed**.

The salt is created once per world with a cryptographically strong generator, stored privately, and **never logged, shown, or sent to clients**.

> Honest note: this does **not** stop X-ray clients, server-file theft, or operators with disk access. It closes the "seed → ore map" shortcut, nothing more.

---

## 🛡️ Safety First

- **Structure protection** — ore takeover targets natural generation only; structure blocks are never removed.
- **Fail-safe startup** — if anything can't be resolved safely, the mod leaves vanilla generation untouched rather than risk your world. A `STRICT` mode is available for admins who want startup to stop on any unresolved ore.
- **Performance budgets** — hard per-chunk limits keep an extreme config from freezing the server, with clear (rate-limited) warnings.

---

## 🧩 Compatibility — What's Actually Supported

**Works automatically** with anything using the standard Minecraft/NeoForge pipeline:

- Vanilla ores
- Mod ores registered as normal ore features
- Datapack-defined ores, biomes, features, and dimensions
- Custom dimensions and biome mods

**Supported via the Adapter API:** custom ore feature types (mod authors can add support without Ore Distribution depending on their mod).

**Detected, reported, and never silently changed:** mods that write ore outside the normal generation pipeline, replace the chunk generator, or place ore at runtime. These are listed in a compatibility report so nothing breaks quietly.

> This is **not** "compatible with every mod ever made" — and it won't pretend to be. It's honest about its boundary, and it never damages generation it doesn't understand.

---

## 🕹️ Commands (operator only)

```
/oredistribution report          Summary of what was detected and enabled
/oredistribution list ores       All discovered ore profiles
/oredistribution list dimensions Discovered dimensions and their status
/oredistribution explain <ore>   Effective values for an ore (and dimension)
/oredistribution validate        Check the configuration
/oredistribution scan            Rescan and update config files
/oredistribution debug chunk X Z Summarize deposits near a chunk
/oredistribution salt status     Confirm the salt exists (never shown)
```

---

## 🚀 Getting Started

1. Drop the jar in `mods/` on a NeoForge 1.21.1 setup and start the server once.
2. Ore Distribution generates editable config under `serverconfig/oredistribution/` and a compatibility report.
3. Stop the server, edit the TOML files, and restart.

**Important:** generation settings apply to **newly generated chunks only** — existing chunks are not changed retroactively. To apply new settings everywhere, reset the world or delete chunks. Your edits are preserved across restarts and rescans; new ores are added, removed ones are kept as orphans, and your values are never overwritten.

---

## 📦 Requirements

- Minecraft **1.21.1**
- **NeoForge 21.1.x**
- Install on the **server** (single-player worlds work too; all settings are world-side).

---

## ❓ FAQ

**My ores didn't change.** Only newly generated chunks are affected — explore new area or reset the world. Also check the dimension is enabled and takeover isn't `OFF`.

**An ore mod isn't detected.** Check `generated/unresolved-features.json`. If it uses a custom feature type, it needs a compatibility adapter — see the docs.

**Is it safe for existing worlds?** Yes. It won't retroactively edit generated chunks, and it fails safe if anything is uncertain.

**Client or server side?** All generation logic is server/world-side. It loads fine on clients but has no client-side gameplay.

---

## 🐛 Reporting Issues

Feel free to ask for any help or issue on comments. I will reply.

---

*Ore Distribution — your world, your ores, your rules.*