# 🧩 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.

[![Servers & Players](https://faststats.dev/embed/default:5b846603-95f8-4e64-b64c-c5cb16879210:servers-and-players?w=800&h=300&theme=dark)](https://faststats.dev/project/playerdatasyncreloaded/minecraft-plugin) --- # 🚀 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 ` 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-.jar` | Paper / Spigot `plugins/` | | `PlayerDataSyncReloaded-Velocity-.jar` | Velocity `plugins/` | | `PlayerDataSyncReloaded-Fabric--.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 ```yaml 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`): ```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 ` | One player's sync state: data applied, load in flight, applied record and last save timestamps | | `/pds save ` | Force-save a player | | `/pds saveall` | Force-save everyone online | | `/pds load ` | Reload a player from storage (overrides what they have now) | | `/pds backup list` | List available backups | | `/pds backup export ` | Export the whole database to a backup | | `/pds backup import ` | 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 ` output and the server log make reports actionable - 📚 Read the documentation - 💡 Share feature requests and suggestions --- # ❤️ Credits Developed with ❤️ by **DerGamer09**

julianfinke04

Organizations