Skip to content

Migrating from EssentialsX

Already running EssentialsX (or a few other plugins)? You don't have to lose your players' data. uxmEssentials ships a built-in importer that reads your existing files and pulls the data across in one shot.

How It Works

The importer is a single admin command:

/uxmess import <source> [--dry-run]
  • It runs off the main thread, so your server never freezes during an import.
  • It is idempotent — every record is written as an upsert keyed by identity. Balances are set, never added, so re-running an import can never double a player's money.
  • It's safe to run again if something looked off, or if new data appeared.

To see which sources are available on your setup:

/uxmess import --list

You need the uxmessentials.admin.import permission (operators have it by default).

Back up first, then dry-run

Always take a backup of your world and plugin data before importing, and always run with --dry-run first. A dry run produces the exact same per-record report as a real import — it just doesn't write anything — so you can review precisely what would change before committing.

Enabling the Importer

The importer lives in the migration module, which is the only module that ships disabled (it's a one-shot admin tool, not something you want running day to day).

  1. Open plugins/uxmEssentials/modules/migration/config.conf.
  2. Set enabled = true.
  3. Run /uxmess reload migration.

When you're done migrating, set it back to enabled = false and reload again.

Import Sources

These are the sources uxmEssentials can read:

Source Brings across Notes
essentialsx Homes, balance (default currency), mail, warps, kits, jail/mute Reads the EssentialsX file tree
vault Balance Live read of the running Vault economy
playerpoints Balance Live read of the running PlayerPoints plugin
litebans Bans, IP-bans, mutes, warns Reads the LiteBans database over JDBC
decentholograms Holograms Reads plugins/DecentHolograms/holograms/*.yml
fancyholograms Holograms Reads plugins/FancyHolograms/holograms.yml

What EssentialsX brings over

From each player's userdata/<uuid>.yml, plus warps/, kits.yml and jail.yml:

  • ✅ Homes
  • ✅ Balance (default currency only)
  • ✅ Mail
  • ✅ Warps
  • ✅ Kits (written into the kit catalog)
  • ✅ Jail & mute state

Not migrated: nicknames / display names, chat formatting, powertools, per-permission kit-delay overrides, GeoIP data, spawn-on-join, and non-native or multi-economy balances. EssentialsX has no player-vault data, so no vaults are produced.

Where does it look?

The EssentialsX path defaults to plugins/Essentials and can be changed with source-path in modules/migration/config.conf. For LiteBans, an empty jdbc-url will auto-detect the local LiteBans database.

Conflict Policy

When an incoming record collides with something already in uxmEssentials, the on-conflict setting in modules/migration/config.conf decides what happens:

Keep what's already there. The safest choice — nothing existing is overwritten.

The imported value replaces the existing one.

Combine both: warps/homes are unioned by name, mail is de-duplicated, and for moderation records the longest-remaining expiry wins.

Balances have their own conservative guard, balance-policy (default skip-if-present), so an import won't quietly stomp on money a player already has.

Imported homes and vaults go through the same rules as /sethome and /vault, so your per-group quotas still apply to migrated data.

  1. Back up your world folder and plugins/ directory.
  2. Install uxmEssentials and start the server once so it generates its files.
  3. Enable the migration module (enabled = true → /uxmess reload migration).
  4. Check available sources with /uxmess import --list.
  5. Dry-run first: /uxmess import essentialsx --dry-run and review the report.
  6. Set your on-conflict / balance-policy if you want anything other than the safe defaults.
  7. Import for real: /uxmess import essentialsx.
  8. Repeat for any other sources (vault, litebans, ...).
  9. Spot-check in-game: /home, /balance, /warp list, /kit.
  10. Disable the migration module again and remove the old plugin.

Next Steps