Skip to content

About

No description, website, or topics provided.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

UserOverUUID icon

UserOverUUID

Switch your server between online mode and offline mode without anyone losing their stuff.

Modrinth · Issues · Discord


Minecraft saves player data by UUID, and a player's UUID depends on the server's mode. Switch online-mode and everyone gets a new UUID. Their old inventory is still on disk, but the server doesn't look there, so they spawn with nothing.

UserOverUUID moves the data to the new UUID when the player joins, before the server loads it. They spawn with their inventory, ender chest, XP, position, stats and advancements, no rejoin needed.

Features

  • Automatic. Migrates on join, before the server reads the player's data.
  • Both directions. Online to offline, offline to online, and back again later.
  • Safe defaults. Copies instead of moving, never replaces existing data on its own, and backs up every file it touches.
  • Runs once per player. A ledger remembers finished migrations, so nothing repeats on the next login.
  • Proxy aware. Works behind BungeeCord and Velocity. The direction comes from the joining player's UUID, not from online-mode.
  • No internet needed. Online UUIDs are found in usercache.json and in the names saved inside player data. The Mojang API is an optional last resort.
  • Plugin data. Add any plugin file or folder that is named after a UUID, such as Essentials userdata.
  • 1.19 to 26.x. Supports the players/ folder layout that Minecraft 26.1 introduced.

Getting started

  1. Put UserOverUUID-<version>.jar in plugins/ and restart.
  2. Change online-mode in server.properties (or your proxy's setting) and restart.
  3. Done. Each player gets their data back the first time they join.

Switched before installing the plugin? Anyone who joined in between now has a fresh, empty profile under their new UUID, and the plugin won't overwrite that on its own. Check with /uom status <player> and bring the old data back with /uom migrate <player> --force. The fresh profile is backed up first.

Commands

Every command needs useroveruuid.admin (op by default). /uom and /uuidmigrate are aliases.

Command What it does
/uom status <player> Shows both UUIDs, where they were found, and whether there is anything to migrate
/uom dryrun <player> Lists every file a migration would copy, without changing anything
/uom migrate <player> Migrates now. Kicks the player first if they are online
/uom reload Reloads config.yml

dryrun and migrate take these options:

  • --force replaces data that already exists under the new UUID (backed up first)
  • --to-online or --to-offline picks the direction yourself, for example to prepare before switching

How it decides

Player joins with Data is copied from
An offline UUID Their online UUID, looked up in usercache.json, then in saved player data, then the Mojang API (if enabled)
An online UUID Their offline UUID. Other spellings of the name (steve vs Steve) are checked too
A Bedrock (Floodgate) UUID Nothing, Bedrock players are skipped

If the player already has data under the new UUID, it is kept and the console tells you how to replace it. The one exception is switching back: when the existing file is the stale copy left behind by the last migration and the other side is newer, it gets replaced (and backed up), so going online, offline and online again loses nothing.

Configuration

plugins/UserOverUUID/config.yml
# Migrate a player's data automatically the first time they join with their other UUID.
autoMigrate: true

# COPY keeps the files under the old UUID (safest). MOVE deletes them after migrating.
operation: COPY

# Replace data a player already has under their new UUID? Leave false and use
# /uom migrate <player> --force for single players instead.
overwriteTarget: false

# Kick the player after an automatic migration. Normally not needed.
kickAfterMigrate: false
kickMessage: "&aYour player data was migrated. Please rejoin."

worlds:
  autoDetect: true
  additionalWorldFolders: []

lookup:
  useUsercache: true
  scanPlayerData: true
  useMojangApi: false
  mojangApiTimeoutMs: 3000
  cacheTtlMinutes: 1440

paths:
  includeVanillaPlayerdata: true
  includeStats: true
  includeAdvancements: true
  # Placeholders: {uuid}, {uuid_nodash}, {name}. Relative to the server folder.
  customPaths:
    - "plugins/Essentials/userdata/{uuid}.yml"

Backups

Every migration writes a backup to plugins/UserOverUUID/backups/<date>_<player>_<uuid>/. It holds the migrated files (old-uuid/), any files they replaced (new-uuid/), and a manifest.txt listing what went where. To undo a migration, copy the files back while the player is offline.

plugins/UserOverUUID/ledger.properties lists finished migrations. Delete a line to let that one run again on join.

Good to know

  • For plugin data, only the file name or folder changes. Plugins that store UUIDs inside their files or in a database (LuckPerms, MySQL economies) need their own migration tools.
  • In offline mode anyone can join under any name, so whoever joins as "Steve" gets Steve's migrated data. Use an authentication plugin if that matters on your server.
  • Runs on Paper, Purpur, Spigot and Bukkit, Minecraft 1.19 to 26.x. Folia is not supported.

Upgrading from 1.0.0 (UuidMigrate)

Version 1.0.0 was called UuidMigrate. Delete UuidMigrate-1.0.0.jar and add the new jar. Your config and backups are copied over from plugins/UuidMigrate automatically, and /uuidmigrate and uuidmigrate.admin keep working.

Building

Needs Java 17 or newer.

./gradlew build

The jar ends up in build/libs/. It is compiled against the Spigot 1.19.4 API so a single jar runs everywhere. To check the code against the newest APIs:

./gradlew compileJava -PapiTarget=paper
./gradlew compileJava -PapiTarget=spigot26

About

No description, website, or topics provided.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages