UuidMigrate

Plugin for Spigot/Paper/Purpur/Bukkit to migrate player data between Online and Offline UUIDs. Useful for servers switching modes or handling mixed authentication data.

Requirements

• Java 17 or higher
• Spigot/Paper/Purpur/Bukkit 1.19+ (API version 1.19)
• Maven 3.6+ (for building)

Building

mvn clean package

The compiled JAR will be in the target/ directory.

Features

• Auto-Migration: Detects if player has data under a different UUID (Online vs Offline) on join.
• Safe: Creates a backup of all data before modifying anything. Default is COPY mode.
• Configurable: Choose what to migrate (Inventory, Stats, Advancements, Custom Paths).
• Smart: Detects world folders automatically, handles Nether/End.

Usage

1. Install the plugin JAR.
2. Configure config.yml if needed (e.g. enable Mojang API lookup if you are running Offline mode but want to pull Online UUID data).
3. Restart server.

When a player joins, the plugin checks logic:

• Server is Online Mode: Migrates from Offline UUID -> Online UUID.
• Server is Offline Mode: Migrates from Online UUID -> Offline UUID.

Commands

• /uuidmigrate status <player>: Check if the player has data to migrate.
• /uuidmigrate migrate <player>: Manually force migration for a player.
• /uuidmigrate dryrun <player>: See what would happen without changing files.
• /uuidmigrate reload: Reload config.

Permissions

• uuidmigrate.admin: Full access.

Configuration Custom Paths

You can add custom plugin paths in config.yml:

paths:
  customPaths:
    - "plugins/Essentials/userdata/{uuid}.yml"

Use {uuid} for the UUID and {name} for the player name.

Backup

Backups are stored in plugins/UuidMigrate/backups/<timestamp>/<player>/.