uuidswap

UUID Swap

UUID Swap is a Fabric mod that replaces Minecraft player save data by UUID and provides an in-game GUI for transferring ownership of tamed pets.

UUID Swap replaces Minecraft player save data by UUID. Fabric and Forge modules share the common file-transfer logic.

Compatibility

| Minecraft | Java | Module |
| — | —: | — |
| 1.20 | 17+ | fabric-1.20 |
| 1.20.1 | 17+ | forge-1.20.1 (Forge 47.4.23) |
| 1.20.2 | 17+ | fabric-1.20.2 |
| 1.20.3 | 17+ | fabric-1.20.3 |
| 1.20.4 | 17+ | fabric-1.20.4 |
| 1.20.5 | 21+ | fabric-1.20.5 |
| 1.20.6 | 21+ | fabric-1.20.6 |
| 1.21 | 21+ | fabric-1.21 |
| 1.21.1 | 21+ | fabric-1.21.1 |
| 1.21.2 | 21+ | fabric-1.21.2 |
| 1.21.3 | 21+ | fabric-1.21.3 |
| 1.21.4 | 21+ | fabric-1.21.4 |
| 1.21.5 | 21+ | fabric-1.21.5 |
| 1.21.6 | 21+ | fabric-1.21.6 |
| 1.21.7 | 21+ | fabric-1.21.7 |
| 1.21.8 | 21+ | fabric-1.21.8 |
| 1.21.9 | 21+ | fabric-1.21.9 |
| 1.21.10 | 21+ | fabric-1.21.10 |
| 1.21.11 | 21+ | fabric-1.21.11 |
| 26.1 | 25+ | fabric-26.1 |
| 26.1.1 | 25+ | fabric-26.1.1 |
| 26.1.2 | 25+ | fabric-26.1.2 |
| 26.2 | 25+ | fabric-26.2 |
| 26.3 | 25+ | fabric-26.3 |

Features

Player data replacement

The mod can copy a donor player’s saved data to a target UUID. The following files are handled:

• playerdata/<uuid>.dat — inventory, experience, health, position, dimension, ender chest, and other player data
• stats/<uuid>.json — statistics
• advancements/<uuid>.json — advancements

When transferPetsAutomatically=true, loaded tamed animals owned by the donor are reassigned to the target UUID.

Only entities in currently loaded worlds can be transferred automatically. Pets in unloaded chunks must be handled after their chunks are loaded.

Player selection GUI

Running /uuidswap opens a paginated chest GUI. Each player is shown as a player head with their name, UUID, skin, and online/offline status.

Pet owner replacement

Hold redstone dust, sneak, and right-click a tamed animal. Select the new owner from the player-head GUI.

Commands

/uuidswap

Open the GUI and replace your own data with the selected player’s data.

/uuidswap list

List known players, UUIDs, and online status.

/uuidswap <targetUuid>

Replace your own data with the data stored under targetUuid.

/uuidswap apply <sourceUuid> <targetUuid>

Replace the data stored under sourceUuid with the data stored under targetUuid. This form is intended for operators and the server console.

Online replacement behavior

If the source player is online, the mod disconnects them first, waits for the final save, and applies the replacement on the next server tick. The player can then reconnect and load the new data.

Configuration

The file config/uuid-config.json is created on first launch:

{
  "playerSwapPermissionLevel": 4,
  "petOwnerSwapPermissionLevel": 4,
  "backupBeforeOverwrite": true,
  "transferPetsAutomatically": true,
  "enablePetOwnerSwap": true
}

Permission levels are 0 (everyone), 1 (moderators), 2 (gamemasters), 3 (admins), and 4 (owners/full OP). Keep the default level 4 unless you fully understand the risk of allowing save-file replacement.

Backups

With backupBeforeOverwrite=true, the source player’s original files are backed up before replacement:

<world>/uuid_backups/<timestamp>_source-<sourceUuid>_from-<targetUuid>/

Build

Linux/macOS:

./gradlew build

Windows:

gradlew.bat build

The jar is generated in build/libs/. Place it in the mods directory of a Fabric client or server running the compatible Minecraft, Fabric Loader, Fabric API, and Java versions.

Development

For multiple Minecraft versions, keep shared business logic in a common module and put version-specific Minecraft/Fabric API code in separate modules such as fabric-1.21.11 and fabric-26.1.2. Each module should produce its own jar; one jar should not be assumed to work across incompatible Minecraft APIs.

Safety

Always test on a copy of the world and keep backupBeforeOverwrite=true. Save-data replacement is destructive if backups are disabled.

License

All rights reserved. See LICENSE.txt.