PlayerSync

A Bukkit/Spigot/Paper plugin that synchronizes player inventory and Ender Chest data across multiple Minecraft servers.

Overview

PlayerSync uses a MySQL database to synchronize player inventory and Ender Chest data across multiple servers. It automatically loads data when a player joins a server and saves data when they leave.

Supported Versions

Minecraft: 1.21.x
Server: Bukkit, Spigot, Paper
Java: Java 21 or higher

Installation

Download the latest PlayerSync-X.X.X.jar from the release page
Place it in the server's plugins folder
Start the server to load the plugin
Edit plugins/PlayerSync/config.yml to configure the database
Restart the server

Database Setup

PlayerSync requires a MySQL database.

Creating the MySQL Database

CREATE DATABASE player_sync CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Configuration File

config.yml

Edit plugins/PlayerSync/config.yml to configure settings.

mysql:
  # MySQL server hostname
  host: localhost
  
  # MySQL server port number
  port: 3306
  
  # MySQL username
  username: root
  
  # MySQL password
  password: password
  
  # Database name to use
  database: player_sync
  
  # Use SSL connection
  useSSL: false

settings:
  # Read-only mode (true: read data only, false: read/write)
  read-only: false
  
  # UUID for server identification (left blank, it will be auto-generated)
  uuid: “”
  
  # Auto-sync interval (in seconds)
  # Automatically saves all online players' data at the specified interval
  auto-sync-interval: 60

settings

read-only (default: false)

true: Read only from the database (does not save)
false: Performs both read and write operations to the database
When using multiple servers, it is possible to set only one server to false and leave the others at true

uuid (optional)

UUID for server identification
If left blank, it will be generated automatically
Once generated, it is saved in config.yml

auto-sync-interval (Recommended: 60)

Automatic sync interval (in seconds)
Automatically saves all online players' data at the specified interval
Player data is always saved when they leave, so this setting is for periodic backups
Setting this to 0 or lower disables auto-sync

Message File

plugins/PlayerSync/messages.yml contains log messages output by the plugin. You can customize these messages by editing this file.

Usage

Basic Usage

Set up the database
Configure database connection details in config.yml
Start the server
When a player joins, their inventory and ender chest data are automatically loaded
When a player leaves, their data is automatically saved

Using Multiple Servers

Configure all servers to use the same database
Set each server's uuid to a unique value (auto-generated is acceptable)
Typically set read-only: false on all servers
If only one server saves data, set other servers to read-only: true

Troubleshooting

Database Connection Errors

Verify MySQL server is running
Confirm hostname, port, username, and password are correct
Verify MySQL ports are open in the firewall

Data Not Syncing

Confirm all servers use the same database
Check read-only settings
Verify database permissions

Performance Issues

Increase auto-sync-interval value (e.g., 120 seconds)
Adjust MySQL connection pool settings

License

This project is released under the Apache License 2.0.

For details, see the LICENSE file.

Support

If you encounter issues, please report them via GitHub Issues.

Player Sync

📖About Player Sync