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

1. Download the latest PlayerSync-X.X.X.jar from the release page
2. Place it in the server's plugins folder
3. Start the server to load the plugin
4. Edit plugins/PlayerSync/config.yml to configure the database
5. 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

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

Using Multiple Servers

1. Configure all servers to use the same database
2. Set each server's uuid to a unique value (auto-generated is acceptable)
3. Typically set read-only: false on all servers
4. 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.

Links

• Discord
• Official Website
• GitHub