? 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.
/stopand/pds reloadsave 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 statusfor 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
下载 PlayerDataSync
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 PlayerDataSync
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 PlayerDataSync
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 PlayerDataSync
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 PlayerDataSync
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 PlayerDataSync
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 PlayerDataSync
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 PlayerDataSync
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 PlayerDataSync
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
下载 PlayerDataSync
需要联机服务器吗?
稳定流畅、一键部署,几分钟即可和朋友联机开服
最低仅需 8 元/月 即可畅快联机
PlayerDataSyncReloaded 26.10-ALPHA.001 — Fabric 1.20.1 – 26.2
Alpha 构建。 已编译并通过单元测试;尚未在实际网络环境中测试。请先在暂存服务器上测试。
文件
PlayerDataSyncReloaded-Fabric-26.10-ALPHA.001.jar —— 每个受支持的版本行各一个 jar。模组启动时从 Fabric Loader 读取 Minecraft 版本号并激活对应的适配器:
| Minecraft | Fabric Loader | Fabric API | Java |
|---|---|---|---|
| 1.20.1 | 0.15.11+ | 0.92.2+1.20.1 | 17+ |
| 1.21.4 | 0.16.14+ | 0.119.2+1.21.4 | 21+ |
| 26.1 | 0.19.3+ | 0.153.0+26.1.2 | 25+ |
| 26.2 | 0.19.3+ | 0.153.0+26.2 | 25+ |
配置文件:config/playerdatasync.properties,首次启动时创建。支持 MariaDB、PostgreSQL 或 MongoDB —— MySQL 驱动未打包在内;MariaDB 驱动可连接至 MySQL 服务器。
分发
- 现在提供涵盖所有 Minecraft 版本的独立下载包。此前单个版本的 Fabric jar 作为
bundled/playerdatasync-fabric.jar随 Paper jar 一起分发。
修复(所有版本行)
- 模组 jar 并非独立运行:它仅包含适配器类,加载时会因
NoClassDefFoundError失败。:api、:common以及运行时库(HikariCP、MariaDB/PostgreSQL 驱动、Mongo 驱动、Jedis)现已进行阴影处理(shaded)。Gson 和 SLF4J 被排除在外,因为 Minecraft 本身已自带它们。 - 生命值为 0 会在下一台服务器上杀死玩家:在死亡界面退出游戏会保存
health = 0,并在重新加入时应用。现在只有当生命值大于 0 时才会应用。
新增(所有版本行)
- 关闭时保存:
SERVER_STOPPING事件会保存每位在线玩家的数据;SERVER_STOPPED事件会在写入完成后关闭存储。此前存储从未被关闭过。 - 断开连接现在会清除玩家的每会话同步状态,与其他平台保持一致。
同步核心(所有平台共享)
- Redis 自动重连:订阅者原本运行在 common-pool 线程上,连接断开时会静默死亡,导致其他服务器停止接收重载通知。现在它运行在独立的线程上,并每 5 秒尝试重连一次。
- 加密失败不再写入明文:如果
CryptoUtil.encrypt抛出异常,保存操作将失败,而不是存储未加密的 JSON(适用于 SQL 和 Mongo)。 - 精确检查是否未更改:跳过保存的“无变化”判断现在比较的是完整的序列化物品栏数据,而非
String#hashCode,因此哈希冲突不再导致已更改的物品栏被丢弃。 SyncManager#handleQuit返回一个CompletableFuture,在写入完成时完成;新增saveAll和markLoaded用于处理关闭/重载场景。- 包含 26.9 的顺序修复:按玩家序列化加载顺序,在存储的配置档案应用之前拒绝保存,已应用的记录不会重复应用,失败的 SQL 写入会被计数并重试,而不是被缓存为“未更改”。
已知问题
- 各版本行的功能一致性
- 1.20.1 和 1.21.4:不支持末影箱、药水效果、属性、进度、统计数据。
- 26.1 和 26.2:不支持进度、统计数据。
- Fabric 尚不支持 Velocity 的保存握手。代理服务器会为每个 Fabric 服务器等待完整的超时时间,然后停止等待。
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
插件
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
插件
ExyliaPlugins 的库。
插件
通过对话框或铁砧界面帮助你的 Anthme
插件
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
插件
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
插件
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
评论 0
登录后参与评分
还没有评论,来抢沙发吧