PlayerDataSync

🧩 PlayerDataSync

One player profile for your whole network.
Inventories, Ender Chests, XP, health, effects, attributes and economy follow your players to every server — automatically, safely, in the right order.

---

🚀 Overview

Players on a network expect one thing: what they had on Survival is still there on SkyBlock, and what they earned on SkyBlock is waiting for them back on Survival.

PlayerDataSync makes that happen. Every server writes to one shared database, every server reads from it on join, and Redis tells the others the moment something changed. Your network behaves like a single world.

No manual file transfers. No duplicated inventories. No lost progress. No "my boots are gone".

---

✨ What Gets Synchronized

Every entry is an individual toggle in the config, so you decide exactly what travels with your players.

Category	Included
Items	Inventory (incl. armor and off-hand), Ender Chest, selected hotbar slot
Progression	Experience, levels, advancements, statistics
Vitals	Health, absorption, hunger, saturation, exhaustion, air, fire ticks, freeze ticks, arrows in body
Effects & state	Potion effects, game mode, flight, walk & fly speed, fall distance, player time, player weather
Advanced	Attributes, Persistent Data Container, Vault economy balance
Optional	Location (disabled by default — see below)

📍 About location sync

Location sync teleports players to their stored position on join. It ships disabled (sync.location: false) because it only makes sense when the destination server has a world of the same name. If that world is missing, the restore is skipped with a log warning instead of dropping the player somewhere wrong.

---

🛡️ Built to Never Roll Back

Most sync plugins work fine until two things happen at once. PlayerDataSync is designed around exactly those moments:

• Proxy handshake. With the Velocity bridge, a server switch waits until the old server confirms its save. The new server never reads the database before the write has landed.
• Ordered loads. Join event, proxy notification and Redis notification all trigger loads — they are queued per player, so the newest record is always the one applied last.
• No premature saves. Autosave, quit and proxy saves are refused until the stored profile has been applied. The stale local player file can never overwrite the database.
• No redundant re-applies. A late notification for a record the player already has is ignored. Gear equipped in the meantime stays equipped.
• Save on shutdown. /stop and /pds reload save every online player and wait for the writes. Paper kicks players after disabling plugins — we save before that happens.
• Honest failures. A failed database write is counted, logged and retried on the next save instead of being silently marked as "unchanged".
• Encrypted means encrypted. If encryption is enabled and fails, the save fails. Plaintext never reaches the database by accident.

---

🧰 More Than Just Sync

• 🔴 Redis live sync — other servers reload a profile the moment it was saved; the subscriber reconnects automatically if Redis drops
• 🔐 AES encryption — encrypt stored profiles with your own key
• 💾 Backups — export the whole database to a compressed snapshot, import it back with one command
• 🔁 Storage migration — move between MySQL, MariaDB, PostgreSQL and MongoDB in place
• ⬆️ Legacy import — profiles from the original PlayerDataSync are read automatically
• 💬 Discord webhooks — notifications for sync successes and failures
• ⏱️ Autosave — periodic saves as a crash safeguard, with an optional minimum interval
• 🚫 Exclusions — skip specific worlds or specific item types
• 🔍 Diagnostics — /pds status for counters and the last error, /pds info <player> for one player's exact sync state
• 📊 bStats & FastStats metrics
• 🧩 Developer API — force-save, force-reload and direct access to stored profiles from your own plugins

---

🌟 Why PlayerDataSync?

Running a network without proper synchronization leads to lost inventories, duplicated items, missing experience and players who stop trusting your server.

PlayerDataSync removes those failure modes — including the rare ones that only show up under load.

• ✅ One shared player profile across your whole network
• ✅ Instant propagation with Redis
• ✅ Four database backends to choose from
• ✅ Asynchronous — the main thread stays free
• ✅ Skips saves when nothing changed
• ✅ Race conditions covered by unit tests, not by hope
• ✅ Open source (MIT) and actively maintained

---

🧱 Supported Platforms

Component	Supported
Minecraft	1.20 – 26.2
Server software	Paper, Spigot, Purpur, Folia, Fabric, Velocity (proxy bridge)
Java	21+ — Minecraft 26.x servers require Java 25
Database	MySQL, MariaDB, PostgreSQL, MongoDB

Every platform is a separate download:

File	Goes to
PlayerDataSyncReloaded-<version>.jar	Paper / Spigot plugins/
PlayerDataSyncReloaded-Velocity-<version>.jar	Velocity plugins/
PlayerDataSyncReloaded-Fabric-<mc>-<version>.jar	Fabric mods/ — pick the jar for your Minecraft line (1.20, 1.21, 26.1, 26.2)

Please note:

• Fabric is not yet at feature parity. Advancements and statistics are not synchronized on Fabric. The 1.20 and 1.21 Fabric builds additionally lack Ender Chest, potion effects and attributes; the 26.x builds have those. Fabric does not answer the proxy save handshake yet.
• Forge is currently unavailable while its build tooling catches up with the Minecraft 26.x toolchain.
• On Fabric, use MariaDB, PostgreSQL or MongoDB. The MySQL driver is not bundled and mod loaders do not supply one. The MariaDB driver connects to MySQL servers just fine. Paper and Spigot are unaffected.
• SQLite is not supported for networks — data must live in a database every server can reach.

---

⚙️ Configuration

Full documentation: 👉 https://pds.devvoxel.de/config

• Paper / Spigot: plugins/PlayerDataSyncReloaded/config.yml
• Fabric: config/playerdatasync.properties, created on first start
• Velocity: plugins/playerdatasync/playerdatasync.properties, created on first start

storage:
  type: "mariadb"   # mysql, mariadb, postgres, mongodb
  host: "localhost"
  port: 3306
  database: "minecraft"
  username: "root"
  password: ""

redis:
  enabled: true     # strongly recommended for multi-server setups
  host: "localhost"
  port: 6379

autosave:
  enabled: true
  interval: 300     # seconds

sync:
  inventory: true
  ender_chest: true
  economy: true     # requires Vault + an economy plugin
  location: false   # teleports players on join

Velocity bridge (playerdatasync.properties):

# How long a server switch waits for the old server to confirm its save. 0 = don't wait.
save_ack_timeout_ms=2000

---

💬 Commands & Permissions

Everyday operation is fully automatic — players never touch a command. For administrators, everything lives under /playerdatasync (aliases /pds, /pdasync) behind the playerdatasync.admin permission.

Command	Description
/pds status	Load/save counters, skips, last durations, last error, excluded worlds
/pds info <player>	One player's sync state: data applied, load in flight, applied record and last save timestamps
/pds save <player>	Force-save a player
/pds saveall	Force-save everyone online
/pds load <player>	Reload a player from storage (overrides what they have now)
/pds backup list	List available backups
/pds backup export <name>	Export the whole database to a backup
/pds backup import <name>	Restore a backup into the database
/pds migrate	Migrate to the storage backend configured under migration
/pds debug on|off|toggle	Toggle verbose logging at runtime
/pds reload	Reload configuration and reconnect storage, Redis and Discord

---

📈 Performance

• ⚡ Asynchronous database operations on a dedicated pool — the main thread is never blocked
• 🔄 Saves are skipped when the inventory has not changed since the last write
• ⏳ Configurable minimum interval between saves
• 💾 Compressed, Base64-encoded item data; compressed backups
• 📉 Low CPU and memory footprint

Suitable for small communities and large networks alike.

---

📋 Requirements

• ☕ Java 21+ (Java 25 for Minecraft 26.x servers)
• 🗄️ MySQL, MariaDB, PostgreSQL or MongoDB
• 🧱 Paper, Spigot or Fabric server
• 🌐 Multiple servers pointed at the same database
• 🔴 Redis (optional, recommended) — instant cross-server propagation
• 🌉 Velocity bridge (optional, recommended) — save handshake on server switches
• 💰 Vault + an economy plugin (optional) — required for economy sync

---

🛠️ Support

• 💬 Join our Discord server
• 🐛 Report bugs on GitHub — /pds info <player> output and the server log make reports actionable
• 📚 Read the documentation
• 💡 Share feature requests and suggestions

---

❤️ Credits

Developed with ❤️ by DerGamer09