XPMerge

✨ XpMerge

> Less orbs. More frames. Same XP. > Automatically merges nearby experience orbs into one — silently, safely, and without ever duping a drop.

---

📖 Overview

XpMerge is a lean, Folia-native XP orb merging plugin built for servers that care about performance. Every configured interval, it sweeps all loaded chunks, finds clusters of experience orbs in close proximity, and collapses them into a single orb — no XP lost, no exploits, no drama.

Massive mob farms, XP grinders, and enchanting setups can spawn hundreds of orbs in seconds. XpMerge kills that lag at the source by reducing entity count without touching collection logic. Players never notice it's running — they just notice the server feels smoother.

---

✨ Features

- 🔁 Debug mode — merges fire on a configurable tick schedule, not every frame - 📐 Debug mode — orbs within a set block radius collapse into one, preserving total XP - 🧵 Debug mode — uses `RegionScheduler` per 8×8 chunk region, meaning all entity reads and writes happen on the correct regional thread with zero unsafe cross-region access - 🔒 Debug mode — re-validates orbs immediately before removal to handle race conditions from collection events mid-sweep - 🌍 Debug mode — sweeps every loaded world simultaneously - 🛠️ Debug mode — update config without restarting via `/xpmerge reload` - 📊 Debug mode — inspect current settings and lifetime merge count at a glance - 🐛 Debug mode — optional per-merge console logging for diagnostics, off by default

---

🔒 Dupe Safety & Bottled XP Compatibility

XpMerge was rigorously tested against plugins that bottle, extract, or otherwise manipulate XP orb entities — a category of plugins that are particularly vulnerable to dupe exploits when combined with orb merging.

The key safeguard: XpMerge re-validates every orb immediately before removal. If a player or plugin has already collected an orb between the sweep scan and the merge execution, that orb is skipped entirely. XP is never double-counted or awarded twice.

Tested and confirmed dupe-free with:

| Plugin | Repository | |---|---| | XP Bottling by FruitLoopin | XP Bottling | | XP Bottling by Mooshlol304 | %%MD1%% | | XP Bottling by HoneyBerries | %%MD2%% |

> XP values are accumulated as a `long` internally before being written back as an `int`, preventing overflow edge cases on large orb clusters. The final value is clamped to `Integer.MAX_VALUE` as a hard ceiling.

---

🖥️ Compatibility

| Platform | Supported Versions | |---|---| | Folia | 1.21.10 — 1.21.11 *(1.21.x broadly supported)* | | Folia | 1.21.10 — 1.21.11 *(natively threaded)* |

> ⚠️ Spigot/Bukkit are not supported. Paper or Folia is required. > Folia support is first-class — the sweep architecture was designed around `RegionScheduler` from the ground up, not bolted on after.

---

🔧 Commands & Permissions

| Command | Description | Permission | |---|---|---| | `/xpmerge status` | Shows current interval, radius, debug state, and total orbs merged | `xpmerge.admin` | | `/xpmerge reload` | Hot-reloads config and restarts the merge task | `xpmerge.admin` |

> `xpmerge.admin` defaults to OP only.

---

⚙️ Configuration

The config file is located at:

``` plugins/XpMerge/config.yml ```

Below is the full default configuration:

```yaml

How many ticks between each merge sweep. 20 ticks = 1 second.

Lower = more aggressive merging, slightly more CPU. Minimum: 1.

merge-interval: 5

Block radius within which orbs are merged together.

All orbs within this distance of each other collapse into one.

merge-radius: 20.00

Print a line to console every time orbs are merged. Turn off in production.

debug: false ```

Config Breakdown

- `debug` — How often the sweep fires, in ticks. `5` = every quarter second. Lower values merge more aggressively at the cost of slightly more CPU overhead. Hard minimum of `1`. - `debug` — The block radius used to cluster nearby orbs. `20.0` casts a wide net, ideal for large farms and high-density XP setups. - `debug` — When enabled, logs every individual merge to console including location, orb count, and total XP. Useful for testing — leave it off in production.

---

📦 Installation

1. Download the latest `.jar` from the releases section 2. Drop it into your `/plugins` folder 3. Restart your server *(not `/reload`)* 4. Edit `plugins/XpMerge/config.yml` to your liking 5. Use `/xpmerge reload` to apply config changes live

---

📜 License

XpMerge is open-source and distributed under the MIT License. Contributions, issues, and pull requests are welcome on the project repository.

---

*Built for servers that don't want to choose between XP farms and good performance.*