✨ 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

• 🔁 Interval-based sweeping — merges fire on a configurable tick schedule, not every frame
• 📐 Radius-based clustering — orbs within a set block radius collapse into one, preserving total XP
• 🧵 Folia-native threading — 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
• 🔒 Dupe-safe design — re-validates orbs immediately before removal to handle race conditions from collection events mid-sweep
• 🌍 Multi-world support — sweeps every loaded world simultaneously
• 🛠️ Live reload — update config without restarting via /xpmerge reload
• 📊 Status command — 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 |
|---|---|
| Experience Manager (XPM) by FruitLoopin | github.com/jwkerr/XPManager |
| BottleEXP by Mooshlol304 | github.com/Mooshlol304/BottleEXP-1.21.5 |
| XP Bottling by HoneyBerries | github.com/HoneyBerries/XPBottling |

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 |
|---|---|
| Paper | 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:

# 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

• merge-interval — 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.
• merge-radius — 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.