# \u2728 XpMerge<\/p>\n
> **Less orbs. More frames. Same XP.**
\n> Automatically merges nearby experience orbs into one \u2014 silently, safely, and without ever duping a drop.<\/p>\n
—<\/p>\n
## \ud83d\udcd6 Overview<\/p>\n
**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 \u2014 no XP lost, no exploits, no drama.<\/p>\n
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 \u2014 they just notice the server feels smoother.<\/p>\n
—<\/p>\n
## \u2728 Features<\/p>\n
– \ud83d\udd01 **Interval-based sweeping** \u2014 merges fire on a configurable tick schedule, not every frame
\n– \ud83d\udcd0 **Radius-based clustering** \u2014 orbs within a set block radius collapse into one, preserving total XP
\n– \ud83e\uddf5 **Folia-native threading** \u2014 uses `RegionScheduler` per 8\u00d78 chunk region, meaning all entity reads and writes happen on the correct regional thread with zero unsafe cross-region access
\n– \ud83d\udd12 **Dupe-safe design** \u2014 re-validates orbs immediately before removal to handle race conditions from collection events mid-sweep
\n– \ud83c\udf0d **Multi-world support** \u2014 sweeps every loaded world simultaneously
\n– \ud83d\udee0\ufe0f **Live reload** \u2014 update config without restarting via `\/xpmerge reload`
\n– \ud83d\udcca **Status command** \u2014 inspect current settings and lifetime merge count at a glance
\n– \ud83d\udc1b **Debug mode** \u2014 optional per-merge console logging for diagnostics, off by default<\/p>\n
—<\/p>\n
## \ud83d\udd12 Dupe Safety & Bottled XP Compatibility<\/p>\n
XpMerge was rigorously tested against plugins that bottle, extract, or otherwise manipulate XP orb entities \u2014 a category of plugins that are particularly vulnerable to dupe exploits when combined with orb merging.<\/p>\n
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.<\/p>\n
Tested and confirmed dupe-free with:<\/p>\n
| Plugin | Repository |
\n|—|—|
\n| **Experience Manager (XPM)** by FruitLoopin | github.com\/jwkerr\/XPManager |
\n| **BottleEXP** by Mooshlol304 | github.com\/Mooshlol304\/BottleEXP-1.21.5 |
\n| **XP Bottling** by HoneyBerries | github.com\/HoneyBerries\/XPBottling |<\/p>\n
> 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.<\/p>\n
—<\/p>\n
## \ud83d\udda5\ufe0f Compatibility<\/p>\n
| Platform | Supported Versions |
\n|—|—|
\n| **Paper** | 1.21.10 \u2014 1.21.11 *(1.21.x broadly supported)* |
\n| **Folia** | 1.21.10 \u2014 1.21.11 *(natively threaded)* |<\/p>\n
> \u26a0\ufe0f Spigot\/Bukkit are **not** supported. Paper or Folia is required.
\n> Folia support is first-class \u2014 the sweep architecture was designed around `RegionScheduler` from the ground up, not bolted on after.<\/p>\n
—<\/p>\n
## \ud83d\udd27 Commands & Permissions<\/p>\n
| Command | Description | Permission |
\n|—|—|—|
\n| `\/xpmerge status` | Shows current interval, radius, debug state, and total orbs merged | `xpmerge.admin` |
\n| `\/xpmerge reload` | Hot-reloads config and restarts the merge task | `xpmerge.admin` |<\/p>\n
> `xpmerge.admin` defaults to **OP only**.<\/p>\n
—<\/p>\n
## \u2699\ufe0f Configuration<\/p>\n
The config file is located at:<\/p>\n
“`
\nplugins\/XpMerge\/config.yml
\n“`<\/p>\n
Below is the full default configuration:<\/p>\n
“`yaml
\n# How many ticks between each merge sweep. 20 ticks = 1 second.
\n# Lower = more aggressive merging, slightly more CPU. Minimum: 1.
\nmerge-interval: 5<\/p>\n
# Block radius within which orbs are merged together.
\n# All orbs within this distance of each other collapse into one.
\nmerge-radius: 20.00<\/p>\n
# Print a line to console every time orbs are merged. Turn off in production.
\ndebug: false
\n“`<\/p>\n
### Config Breakdown<\/p>\n
– **`merge-interval`** \u2014 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`.
\n– **`merge-radius`** \u2014 The block radius used to cluster nearby orbs. `20.0` casts a wide net, ideal for large farms and high-density XP setups.
\n– **`debug`** \u2014 When enabled, logs every individual merge to console including location, orb count, and total XP. Useful for testing \u2014 leave it off in production.<\/p>\n
—<\/p>\n
## \ud83d\udce6 Installation<\/p>\n
1. Download the latest `.jar` from the releases section
\n2. Drop it into your `\/plugins` folder
\n3. Restart your server *(not `\/reload`)*
\n4. Edit `plugins\/XpMerge\/config.yml` to your liking
\n5. Use `\/xpmerge reload` to apply config changes live<\/p>\n
—<\/p>\n
## \ud83d\udcdc License<\/p>\n
XpMerge is open-source and distributed under the **MIT License**.
\nContributions, issues, and pull requests are welcome on the project repository.<\/p>\n
—<\/p>\n
*Built for servers that don’t want to choose between XP farms and good performance.*<\/p>\n","protected":false},"excerpt":{"rendered":"
This is a Folia-compatible plugin for Minecraft that merges nearby experience orbs into one to reduce lag.<\/p>\n","protected":false},"featured_media":172616,"template":"","meta":{"_minecraft_slug":"xpmerge","_minecraft_project_id":"9sOFJCqT","_minecraft_author":"MooshFR","_minecraft_license":"MIT","_minecraft_downloads":58,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"xpmerge.zip","_minecraft_size_bytes":9354,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T20:50:29.143902Z","_minecraft_date_created":"2026-04-04T01:52:26.018501Z","_minecraft_date_modified":"2026-04-03T03:13:35.979227Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/xpmerge","_minecraft_icon_attachment_id":172616,"_minecraft_imported_at":"2026-06-09T22:15:18+00:00","_minecraft_import_hash":"21f216741f1c039ea088067d66f6a8cd","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[125,89,126,90,127,91,92],"mod_loader":[131,132],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-172615","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-folia","mod_category-game-mechanics","mod_category-management","mod_category-optimization","mod_category-paper","mod_category-storage","mod_category-utility","mod_loader-folia","mod_loader-paper","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n