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
• 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.).

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