UUID Data Restorer

UUID Data Restorer is a Minecraft server-side mod that preserves player data when switching your server from online mode to offline mode. It works by renaming existing player data files from the old online UUID to the new offline UUID, ensuring players keep all their items, stats, and progress..

Backup Warning

MAKE SURE YOU BACK UP YOUR world/playerdata FOLDER BEFORE USING THIS MOD!
This mod directly renames .dat files and cannot undo changes automatically.

What This Mod Does

• Reads a mapping of player usernames to original online UUIDs from a config file.
• When a player logs in:
  • If their username is listed and their old .dat file exists:
  • Their current (offline) .dat file is backed up.
  • They are kicked once.
  • The server renames the original .dat file (from online UUID) to the new offline UUID.
  • On rejoin, the player keeps all previous stats, inventory, and progress.
  • If no mapping or file is found, the player is allowed to join without interruption.

Setup Instructions (with Python Script)

Since the Java-based MappingFileManager.java API lookup currently doesn’t function reliably, this must be done via a Python script.

1. Download the Python Script

Use the included lookup_players.py.

2. Prepare a Folder

Create a new folder and place into it:

• lookup_players.py
• All the UUID.dat files from your online server's world/playerdata folder

3. Run the Script

Open a terminal or command prompt in that folder and run:

python lookup_players.py

This will generate a file:

player_uuid_mapping.json

4. Copy the Mapping File

Move player_uuid_mapping.json to your server’s:

/config/

directory.

on Server Start

• The mod will read the mapping file and check if a player’s name matches.
• If a matching old .dat file is found:
  • The player is kicked with a short message.
  • The data file is renamed to the new offline UUID.
  • On rejoining, the player resumes with their original data.
• If no matching .dat file is found, no action is taken, and the player joins normally.

If you find any issues, feel free to Contact me on my Discord Server: https://discord.gg/ddeu3GbP