PlayerDataSync/README.md

PlayerDataSync

A comprehensive Bukkit/Spigot plugin for Minecraft 1.8 to 1.21.11 that synchronizes player data across multiple servers using MySQL, SQLite, or PostgreSQL databases. Perfect for multi-server networks with BungeeCord or Velocity.

Player inventories, experience, health, achievements, economy balance, and more are stored in a shared database whenever they leave a server and restored when they join again.

✨ Features

• Full Player Data Sync: Inventory, EnderChest, Armor, Offhand, Experience, Health, Hunger, Potion Effects
• Multi-Server Support: Shared database across multiple servers (BungeeCord/Velocity compatible)
• Economy Integration: Vault economy balance synchronization
• Achievements & Statistics: Sync player advancements and statistics
• Respawn to Lobby: Automatically send players to lobby server after death/respawn
• Version Compatibility: Supports Minecraft 1.8 - 1.21.11 with automatic feature detection
• Performance Optimized: Async operations, connection pooling, batch processing
• Database Support: MySQL, SQLite, PostgreSQL

📋 Supported Versions

This plugin supports Minecraft versions 1.8 to 1.21.11. Some features are automatically disabled on older versions:

• Offhand sync: Requires 1.9+
• Attribute sync: Requires 1.9+
• Advancement sync: Requires 1.12+

The plugin automatically detects the server version and enables/disables features accordingly.

🚀 Quick Start

1. Download the latest release from the releases page
2. Place the jar file in your server's plugins/ directory
3. Configure the database connection in plugins/PlayerDataSync/config.yml
4. Restart your server
5. Enable BungeeCord/Velocity integration if using a proxy network

⚙️ Configuration

The config.yml file contains all configuration options. Here's a basic setup:

# Server Configuration
server:
  id: default  # Unique identifier for this server instance

# Database Configuration
database:
  type: mysql # Available options: mysql, sqlite, postgresql
  mysql:
    host: localhost
    port: 3306
    database: minecraft
    user: root
    password: password
    ssl: false
    max_connections: 10

# Player Data Synchronization Settings
sync:
  coordinates: true      # Player's current coordinates
  position: true         # Player's position (world, x, y, z, yaw, pitch)
  xp: true              # Experience points and levels
  gamemode: true        # Current gamemode
  inventory: true       # Main inventory contents
  enderchest: true      # Ender chest contents
  armor: true           # Equipped armor pieces
  offhand: true         # Offhand item
  health: true          # Current health
  hunger: true          # Hunger and saturation
  effects: true         # Active potion effects
  achievements: true    # Player advancements/achievements
  statistics: true      # Player statistics
  attributes: true      # Player attributes (max health, speed, etc.)
  economy: true         # Sync economy balance (requires Vault)

# Automatic Save Configuration
autosave:
  enabled: true
  interval: 1           # seconds between automatic saves, 0 to disable
  on_world_change: true # save when player changes world
  on_death: true        # save when player dies
  on_server_switch: true # save when player switches servers (BungeeCord/Velocity)
  on_kick: true         # save when player is kicked
  async: true           # perform saves asynchronously

# Integration Settings
integrations:
  bungeecord: false     # enable BungeeCord/Velocity support
  vault: true           # enable Vault integration for economy
  placeholderapi: false # enable PlaceholderAPI support
  invsee: true          # enable InvSee++ style inventory viewing integration
  openinv: true         # enable OpenInv style inventory viewing integration

# Respawn to Lobby Feature
# Sends players to a lobby server after death/respawn
# Requires BungeeCord or Velocity integration to be enabled
respawn_to_lobby:
  enabled: false        # enable respawn to lobby feature
  server: lobby         # name of the lobby server (must match BungeeCord/Velocity server name)

# Performance Settings
performance:
  connection_pooling: true # use connection pooling for better performance
  async_loading: true   # load player data asynchronously on join
  disable_achievement_sync_on_large_amounts: true # disable achievement sync if more than 1500 achievements exist
  achievement_batch_size: 50 # number of achievements to process in one batch
  achievement_timeout_ms: 5000 # timeout for achievement serialization (milliseconds)
  max_achievements_per_player: 2000 # hard limit to prevent infinite loops

# Message Configuration
messages:
  enabled: true
  show_sync_messages: true  # show sync messages when loading/saving data
  language: en
  prefix: "&8[&bPDS&8]"
  colors: true

Respawn to Lobby Feature

The Respawn to Lobby feature automatically sends players to a designated lobby server after they die and respawn. This is perfect for game servers where players should return to a hub after death.

Requirements:

• BungeeCord or Velocity integration must be enabled
• The lobby server name must match the server name in your proxy configuration

Configuration:

respawn_to_lobby:
  enabled: true         # Enable the feature
  server: lobby         # Server name from your proxy config

🔨 Building

This project uses Maven. To build the plugin:

# Clone the repository
git clone https://github.com/DerGamer009/PlayerDataSync.git
cd PlayerDataSync

# Build for default version (1.21)
mvn clean package

# Build for specific Minecraft version
mvn clean package -Pmc-1.8    # Minecraft 1.8 (Java 8)
mvn clean package -Pmc-1.9    # Minecraft 1.9-1.16 (Java 8)
mvn clean package -Pmc-1.17   # Minecraft 1.17 (Java 16)
mvn clean package -Pmc-1.18   # Minecraft 1.18-1.20 (Java 17)
mvn clean package -Pmc-1.21   # Minecraft 1.21+ (Java 21)

The resulting jar file will be in the target/ directory.

The build process uses Maven Shade plugin to bundle required dependencies directly into the final jar, so no additional libraries need to be installed on the server.

🔧 Multi-Server Setup (BungeeCord/Velocity)

To use PlayerDataSync across multiple servers:

1. Configure the same database on all servers
2. Enable BungeeCord/Velocity integration in config.yml:

   integrations:
     bungeecord: true
   

3. Set unique server IDs for each server (optional, defaults to "default"):

   server:
     id: survival    # Different ID for each server
   

4. Enable server switching autosave:

   autosave:
     on_server_switch: true
   

The plugin will automatically save player data when they switch servers and restore it when they join a new server.

⚠️ Performance Considerations

Achievement Synchronization

If you experience server freezing or lag when players join, it may be caused by achievement synchronization. The plugin includes automatic protection, but you should:

1. Set performance.disable_achievement_sync_on_large_amounts: true in config.yml
2. Consider setting sync.achievements: false if problems persist
3. Monitor server logs for timeout warnings

For servers with many achievements (1500+), the plugin automatically:

• Disables sync if too many achievements exist
• Processes achievements in batches
• Loads asynchronously to avoid blocking the main thread

Recommended Performance Settings

performance:
  connection_pooling: true
  async_loading: true
  disable_achievement_sync_on_large_amounts: true
  achievement_batch_size: 50
  achievement_timeout_ms: 5000
  max_achievements_per_player: 2000

Disabling Achievement Sync

If you experience performance issues, you can disable achievement synchronization entirely:

sync:
  achievements: false  # Disable achievement sync to prevent lag

🐛 Known Issues & Fixes

Fixed Issues

• ✅ Issue #45 - XP Sync: Fixed experience synchronization not working across versions 1.8-1.21.11
• ✅ Issue #46 - Vault Balance de-sync: Fixed economy balance not being saved on server shutdown

Troubleshooting

Server Freezing:

1. Set sync.achievements: false in config.yml
2. Enable performance settings (see above)
3. Check server logs for timeout warnings

Economy Balance Not Syncing:

1. Ensure Vault and an economy plugin are installed
2. Check that sync.economy: true in config.yml
3. Verify Vault integration is enabled: integrations.vault: true

Players Not Switching Servers:

1. Enable BungeeCord/Velocity integration: integrations.bungeecord: true
2. Verify server names match your proxy configuration
3. Check that autosave.on_server_switch: true is enabled

Data Not Syncing:

1. Verify database connection settings
2. Check server logs for database errors
3. Ensure all servers use the same database
4. Verify server IDs are set correctly (if using multiple servers)

📝 Version Compatibility

Tested Versions

• ✅ Minecraft 1.8 - 1.21.11: Full compatibility with automatic feature detection
• ✅ Paper 1.20.4 - 1.21.11: Full compatibility
• ✅ Spigot 1.8 - 1.21.11: Full compatibility

Compatibility Settings

compatibility:
  safe_attribute_sync: true      # Use reflection-based attribute syncing
  disable_attributes_on_error: false # Auto-disable attributes if errors occur
  version_check: true            # Perform version compatibility checks on startup

The plugin automatically detects the server version and enables/disables features accordingly.

🔐 Permissions

The plugin uses the following permissions:

• playerdatasync.* - All permissions
• playerdatasync.message.show.loading - Show loading messages
• playerdatasync.message.show.loaded - Show loaded messages
• playerdatasync.message.show.saving - Show saving messages
• playerdatasync.message.show.errors - Show error messages

📊 Metrics

The plugin uses bStats to collect anonymous usage statistics. You can disable this in the config:

metrics:
  bstats: false  # Disable bStats metrics collection

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• GitHub: https://github.com/DerGamer009/PlayerDataSync
• Issues: https://github.com/DerGamer009/PlayerDataSync/issues
• Releases: https://github.com/DerGamer009/PlayerDataSync/releases

📚 Changelog

See CHANGELOG.md for a detailed list of changes.

💡 Features in Detail

Experience & Level Sync

• Reliable XP synchronization using giveExp() method
• Works across all Minecraft versions (1.8-1.21.11)
• Automatic verification and correction if XP doesn't match

Economy Sync (Vault)

• Synchronizes economy balance across servers
• Requires Vault and an economy plugin (e.g., EssentialsX, CMI)
• Ensures balance is saved on server shutdown

Inventory Sync

• Full inventory synchronization
• EnderChest support
• Armor and offhand items
• Client synchronization after loading

Respawn to Lobby

• Automatically sends players to lobby server after death
• Uses BungeeCord/Velocity server switching
• Saves player data before transfer
• Smart detection to prevent unnecessary transfers

Database Support

• MySQL: Full support with connection pooling
• SQLite: File-based database for single-server setups
• PostgreSQL: Experimental support

🆘 Support

If you encounter any issues:

1. Check the Issues page
2. Review server logs for error messages
3. Verify your configuration matches the examples
4. Create a new issue with details about your problem

---

Made with ❤️ for the Minecraft community