? PlayerDataSync
一个玩家档案,贯穿整个服务器网络。
背包、末影箱、经验值、生命值、状态效果、属性以及经济数据都会跟随你的玩家自动、安全且按正确顺序同步到每一个服务器。

? 概览
网络中的玩家只期待一件事:他们在生存模式(Survival)中拥有的东西,在天空岛模式(SkyBlock)中依然存在;而他们在天空岛模式中获得的奖励,回到生存模式时也能继续享用。
PlayerDataSync 实现了这一目标。每个服务器都写入同一个共享数据库,每个服务器在玩家加入时从中读取数据,Redis 则在数据发生变化的瞬间通知其他服务器。你的服务器网络表现得就像一个单一的世界。
无需手动传输文件。没有重复的背包物品。没有丢失的进度。也不会出现“我的靴子不见了”这种糟心事。
✨ 同步内容
配置中的每一项都是独立的开关,由你决定哪些数据会跟随玩家同步。
| 类别 |
包含内容 |
| 物品 |
背包(包括盔甲栏和副手)、末影箱、选中的快捷栏槽位 |
| 进度 |
经验值、等级、进度(advancements)、统计数据 |
| 生命体征 |
生命值、吸收值、饥饿度、饱和度、疲惫值、空气值、火焰伤害刻数、冻结刻数、体内箭矢数量 |
| 效果与状态 |
药水效果、游戏模式、飞行状态、行走与飞行速度、坠落距离、玩家时间、玩家天气 |
| 高级功能 |
属性、持久化数据容器(Persistent Data Container)、Vault 经济余额 |
| 可选功能 |
位置信息(默认禁用 — 见下文) |
? 关于位置同步
位置同步会在玩家加入时将玩家传送至其存储的位置。该功能默认处于禁用状态 (sync.location: false),因为只有在目标服务器存在同名世界时它才有意义。如果缺少该世界,系统会跳过恢复操作并在日志中发出警告,而不是将玩家传送到错误的位置。
?️ 专为防止回滚而构建
大多数同步插件在两项事件同时发生时就会出问题。PlayerDataSync 正是针对这些关键时刻进行设计的:
- 代理握手。 通过 Velocity 桥接,服务器切换时会等待旧服务器确认保存完成。新服务器绝不会在写入完成之前从数据库中读取数据。
- 有序加载。 加入事件、代理通知和 Redis 通知都会触发加载操作——它们会被排入每个玩家的队列中,因此最新的记录总是最后应用的那一个。
- 避免过早保存。 在存储的玩家档案应用完毕之前,自动保存、退出和代理保存请求都会被拒绝。过时的本地玩家文件永远无法覆盖数据库。
- 避免冗余重新应用。 对于玩家已经拥有的记录,迟到的通知将被忽略。期间装备的装备将保持装备状态。
- 关机时保存。
/stop 和 /pds reload 命令会保存所有在线玩家并等待写入完成。Paper 会在禁用插件后踢出玩家——我们在此之前进行保存。
- 诚实的错误处理。 失败的数据库写入会被计数、记录并在下次保存时重试,而不是被静默地标记为“未更改”。
- 加密即加密。 如果启用了加密但失败,保存操作也会失败。明文绝不会意外到达数据库。
? 不仅仅是同步
- ? Redis 实时同步 — 其他服务器在配置文件保存后立即重新加载;如果 Redis 断开连接,订阅者会自动重连
- ? AES 加密 — 使用你自己的密钥加密存储的玩家档案
- ? 备份 — 将整个数据库导出为压缩快照,并通过一条命令将其导入回来
- ? 存储迁移 — 原地支持在 MySQL、MariaDB、PostgreSQL 和 MongoDB 之间迁移
- ⬆️ 旧版导入 — 自动读取原始 PlayerDataSync 的玩家档案
- ? Discord Webhook — 同步成功和失败的推送通知
- ⏱️ 自动保存 — 定期保存作为崩溃保护机制,支持设置最小间隔时间
- ? 排除项 — 跳过特定世界或特定的物品类型
- ? 诊断工具 —
/pds status 用于查看计数器和最近一次错误,/pds info <player> 用于查看单个玩家的精确同步状态
- ? bStats & FastStats 指标统计
- ? 开发者 API — 强制保存、强制重载以及从你自己的插件中直接访问存储的玩家档案
? 为什么选择 PlayerDataSync?
在没有适当同步的情况下运行服务器网络会导致背包丢失、物品重复、经验值缺失,以及玩家对你服务器的信任度下降。
PlayerDataSync 消除了这些故障模式——包括那些仅在负载下才会出现的罕见情况。
- ✅ 整个网络共用一个玩家档案
- ✅ 通过 Redis 实现即时同步
- ✅ 提供四种数据库后端供选择
- ✅ 异步运行——主线程保持空闲
- ✅ 无变更时跳过保存
- ✅ 竞态条件由单元测试覆盖,而非依赖运气
- ✅ 开源(MIT)且积极维护
? 支持平台
| 组件 |
支持情况 |
| Minecraft |
1.20 – 26.2 |
| 服务端软件 |
Paper, Spigot, Purpur, Folia, Fabric, Velocity(代理桥接) |
| Java |
21+ —— Minecraft 26.x 服务端需要 Java 25 |
| 数据库 |
MySQL, MariaDB, PostgreSQL, MongoDB |
每个平台都有单独的下载文件:
| 文件 |
放置位置 |
PlayerDataSyncReloaded-<version>.jar |
Paper / Spigot plugins/ |
PlayerDataSyncReloaded-Velocity-<version>.jar |
Velocity plugins/ |
PlayerDataSyncReloaded-Fabric-<mc>-<version>.jar |
Fabric mods/ —— 请根据你的 Minecraft 版本线(1.20, 1.21, 26.1, 26.2)选择对应的 jar 包 |
请注意:
- Fabric 版本尚未达到功能对等。 Advancements(进度)和统计数据在 Fabric 上不同步。1.20 和 1.21 的 Fabric 构建版还缺少末影箱、药水效果和属性;26.x 构建版则包含这些内容。Fabric 尚不支持代理保存握手。
- Forge 目前不可用,因为其构建工具正在追赶 Minecraft 26.x 的工具链。
- 在 Fabric 上,请使用 MariaDB、PostgreSQL 或 MongoDB。 MySQL 驱动未打包在内,且模组加载器不提供该驱动。MariaDB 驱动可以正常连接 MySQL 服务器。Paper 和 Spigot 不受此影响。
- SQLite 不支持用于多服务器网络——数据必须存储在每台服务器都能访问的数据库中。
⚙️ 配置
完整文档:?
- Paper / Spigot:
plugins/PlayerDataSyncReloaded/config.yml
- Fabric:
config/playerdatasync.properties,首次启动时创建
- Velocity:
plugins/playerdatasync/playerdatasync.properties,首次启动时创建
storage:
type: "mariadb" # mysql, mariadb, postgres, mongodb
host: "localhost"
port: 3306
database: "minecraft"
username: "root"
password: ""
redis:
enabled: true # 强烈建议在多服务器设置中启用
host: "localhost"
port: 6379
autosave:
enabled: true
interval: 300 # 秒
sync:
inventory: true
ender_chest: true
economy: true # 需要 Vault + 经济插件
location: false # 玩家加入时传送
Velocity 桥接配置 (playerdatasync.properties):
# 服务器切换时等待旧服务器确认保存的时间。0 = 不等待。
save_ack_timeout_ms=2000
? 命令与权限
日常操作完全自动进行——玩家无需使用任何命令。对于管理员,所有功能都位于 /playerdatasync 下(别名 /pds, /pdasync),并受 playerdatasync.admin 权限控制。
| 命令 |
描述 |
/pds status |
加载/保存计数器、跳过次数、上次持续时间、上次错误、排除的世界 |
/pds info <player> |
单个玩家的同步状态:已应用的数据、加载中的记录、最后保存时间戳 |
/pds save <player> |
强制保存某玩家 |
/pds saveall |
强制保存所有在线玩家 |
/pds load <player> |
从存储重新加载某玩家(覆盖其当前数据) |
/pds backup list |
列出可用备份 |
/pds backup export <name> |
将整个数据库导出为备份 |
/pds backup import <name> |
将备份恢复到数据库 |
/pds migrate |
迁移到 migration 下配置的存储后端 |
/pds debug on|off|toggle |
运行时切换详细日志记录 |
/pds reload |
重新加载配置并重新连接存储、Redis 和 Discord |
? 性能
- ⚡ 专用池上的异步数据库操作——主线程永远不会被阻塞
- ? 自上次写入以来物品栏未发生变化时跳过保存
- ⏳ 可配置的最小保存间隔
- ? 压缩并 Base64 编码的物品数据;压缩备份
- ? 低 CPU 和内存占用
适合小型社区和大型网络。
? 要求
- ☕ Java 21+(Minecraft 26.x 服务端需要 Java 25)
- ?️ MySQL, MariaDB, PostgreSQL 或 MongoDB
- ? Paper, Spigot 或 Fabric 服务端
- ? 多台服务器指向同一数据库
- ? Redis (可选,推荐)——实现跨服务器即时同步
- ? Velocity 桥接 (可选,推荐)——服务器切换时的保存握手
- ? Vault + 经济插件 (可选)——经济同步所需
?️ 支持
- ? 加入我们的 Discord 服务器
- ? 在 GitHub 上报告 bug——
/pds info <player> 输出和服务端日志能让报告更具可操作性
- ? 阅读文档
- ? 分享功能请求和建议
❤️ 致谢
由 DerGamer09 用 ❤️ 开发
? 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: ?
- 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
评论 0
登录后参与评分
还没有评论,来抢沙发吧