PlayerSync

PlayerSync is a Minecraft Forge mod that synchronizes player data across multiple servers using a MySQL backend. It allows players to maintain their inventory, equipment, experience, advancements, and more when moving between servers in a network.

Mod Support

The following mods are explicitly handled by PlayerSync — their per-player state survives a server transfer:

• Curios API — functional and cosmetic stacks across all slot types
• Sophisticated Backpacks — equipped & ender-chest backpack contents, upgrades and settings
• Sophisticated Storage — shulker / barrel / chest contents carried as items
• Sophisticated Core — required dependency for the two above
• Refined Storage — disk contents linked to disk items in the inventory, ender chest and Curios slots
• Extra Disks — handled by the Refined Storage disk path
• Applied Energistics 2 — storage cell contents travel in item components (ae2:storage_cell_inv). Spatial cells and wireless links stay bound to the world that owns them
• Corail Tombstone — knowledge, alignment, perks and watcher knowledge (stored in the player persistent-data tag). Graves stay in the world where the player died
• Accessories — all Accessories slots (used by The Aether)
• The Aether — Accessories slots + AETHER_PLAYER attachment (portals, dart count, flight timer, life shards…)
• Cosmetic Armor Reworked — the 4 cosmetic armor slots
• Apotheosis — item DataComponents (affixes, sockets, gems, purity…) + WORLD_TIER / RADIAL_MINING_MODE attachments
• Apothic Enchanting — DataComponents on items (CRESCENDO, CHROMATIC…)
• Apothic Attributes — bonus attribute modifiers + AUX_DMG_TRACKER attachment
• Apothic Spawners — world-side only, no per-player state to sync
• Revive Me — death event runs at LOW priority + cancel guard, fallen players are not falsely flagged as dead
• Corpse / Gravestone (+ Curios-Compat) — dead players' curios are not overwritten with empty data

Any other mod that stores its per-player state through NeoForge AttachmentTypes is synced automatically (Ars Nouveau, Iron's Spellbooks, Pehkui, Spice of Life: Onion, etc.), as is any mod still using the older player persistent-data tag (sync_persistent_data).

Run /playersync compat on a live server to see exactly which of these are installed, how each one's data is carried, and whether its sync toggle is enabled. The same report is printed to the log at server start.

Any other mods support is also possible.

Development Setup

Database Setup (Docker)

A docker-compose.yml file is provided for easily setting up a MariaDB database instance for development testing.

1. Make sure Docker is installed.
2. Inside your work directory run:

   docker compose up -d

   This will download the MariaDB image (if not already present) and start a database container in the background.
3. Stoppinng the Database

   docker compose down

Data Persistence: The database uses a Docker volume, ensuring your data persists even if you stop and restart the containers.

Database Management Tool

The docker-compose.yml also includes an Adminer service, a lightweight database management tool.

• Access Adminer in your web browser at http://localhost:8080.
• Log in using the server with
  • username: playersync
  • database: playersync
  • password: see docker-compose.yml

For debugging purposes, you can enable use_legacy_serialization to have readable database fields. This can cause crashes and unintended side-effects. Do not enable this on a production server if not absolutely necessary!

Running the Mod

The project uses Gradle for building and running. Use the provided Gradle wrapper (gradlew for Linux/macOS, gradlew.bat for Windows).

1. Make sure that the MySQL database you configured is running.
2. Run the Server

   ./gradlew runServer

   or on Windows:

   .\gradlew.bat runServer

   This task compiles the mod and starts a dedicated Minecraft server instance with the mod loaded in the run directory.
3. Run the Client

   ./gradlew runClient

   or on Windows:

   .\gradlew.bat runClient