mc-data-bridge -----
Seamlessly sync player inventory, health, XP, and effects across your BungeeCord/Velocity network.
MC Data Bridge
MC Data Bridge is a robust, high-performance hybrid plugin for PaperMC (Spigot), BungeeCord, and Velocity. It is designed to seamlessly synchronize player data across multiple Minecraft servers, ensuring that players have a consistent experience by retaining their health, hunger, experience, inventory, and more as they move between linked servers.
► Features
- Hybrid Plugin: A single JAR file works on your PaperMC/Spigot servers and your BungeeCord/Velocity proxy, automatically activating the correct functionality for each platform.
- Proxy-Initiated Saves: The proxy (BungeeCord/Velocity) orchestrates the data saving process, ensuring that a player's data is saved from their source server *before* they connect to the destination server. This eliminates race conditions and ensures data is never lost during a server switch.
- Fully Asynchronous: All database operations are performed on a separate thread, ensuring that your server's main thread is never blocked. This means no lag, even if your database is slow to respond.
- Robust Locking Mechanism: A database-level locking mechanism with an automatic timeout prevents data corruption and ensures that only one server can write a player's data at a time.
- Version-Independent Item Serialization: Player inventories are serialized using Minecraft's built-in Base64 methods, which is highly robust and prevents data loss when you update your Minecraft server to a new version. The plugin is also backward-compatible and can read old NBT-based item data.
- Cross-Server Player Data Sync: Synchronizes core player data including:
- Health
- Food Level & Saturation
- Experience (Total XP, current XP, and Level)
- Inventory Contents
- Armor Contents
- Active Potion Effects
- Resilient Connection Pooling: Uses HikariCP with optimized settings to ensure that the database connection is resilient to network issues and database restarts.
- Configurable & Flexible: Easily connect to your MySQL database and configure settings for your server environment.
► Installation
- Get the Plugin JAR:
- Download the latest compiled JAR (`mc-data-bridge-*.jar`) from the GitHub Releases page.
- ... or if building from source, clone the repository and run `mvn clean package` to build the JAR in the `target/` directory.
- Deploy to Servers:
- Copy the single `mc-data-bridge-*.jar` file into the `plugins/` folder of **each PaperMC server** you wish to synchronize.
- Copy the **same JAR file** into the `plugins/` folder of your **BungeeCord or Velocity proxy server**.
► Configuration
A `config.yml` file will be generated in the `plugins/mc-data-bridge/` folder on your PaperMC servers after the first run. You must update this file with your database credentials and a unique server ID.
Code (YAML):
# MySQL Database Configuration
database:
host : localhost
port : 3306
database : minecraft
username : user
password : password
# A list of JDBC properties to apply.
# These are recommended, but you can change/add/remove as needed.
properties:
useSSL : false
allowPublicKeyRetrieval : true
# HikariCP Connection Pool Settings
# These settings are optimized for resilience and performance.
# It is recommended to leave these at their default values unless you are an experienced administrator.
pool-settings:
maximum-pool-size : 10
minimum-idle : 10
max-lifetime : 1800000 # 30 minutes
connection-timeout : 5000 # 5 seconds
idle-timeout : 600000 # 10 minutes
# MySQL JDBC Optimizations
# These are advanced settings for the MySQL driver.
# Do not change these unless you know what you are doing.
optimizations:
cache-prep-stmts : true
prep-stmt-cache-size : 250
prep-stmt-cache-sql-limit : 2048
use-server-prep-stmts : true
use-local-session-state : true
rewrite-batched-statements : true
cache-result-set-metadata : true
cache-server-configuration : true
elide-set-auto-commits : true
maintain-time-stats : false
# Set to true to enable verbose debugging messages in the server console.
# This can be useful for diagnosing issues, but should be false for normal operation.
debug : false
# A unique name for this server. This is CRITICAL for data locking.
# Each server connected to the same database MUST have a unique name.
# Example: "survival-1", "creative", "lobby"
server-id : "default-server"
# The duration in milliseconds after which a player data lock is considered expired.
# This prevents players from being permanently locked out if a server crashes.
# Default: 60000 (1 minute)
lock-timeout : 60000
database:
host : localhost
port : 3306
database : minecraft
username : user
password : password
# A list of JDBC properties to apply.
# These are recommended, but you can change/add/remove as needed.
properties:
useSSL : false
allowPublicKeyRetrieval : true
# HikariCP Connection Pool Settings
# These settings are optimized for resilience and performance.
# It is recommended to leave these at their default values unless you are an experienced administrator.
pool-settings:
maximum-pool-size : 10
minimum-idle : 10
max-lifetime : 1800000 # 30 minutes
connection-timeout : 5000 # 5 seconds
idle-timeout : 600000 # 10 minutes
# MySQL JDBC Optimizations
# These are advanced settings for the MySQL driver.
# Do not change these unless you know what you are doing.
optimizations:
cache-prep-stmts : true
prep-stmt-cache-size : 250
prep-stmt-cache-sql-limit : 2048
use-server-prep-stmts : true
use-local-session-state : true
rewrite-batched-statements : true
cache-result-set-metadata : true
cache-server-configuration : true
elide-set-auto-commits : true
maintain-time-stats : false
# Set to true to enable verbose debugging messages in the server console.
# This can be useful for diagnosing issues, but should be false for normal operation.
debug : false
# A unique name for this server. This is CRITICAL for data locking.
# Each server connected to the same database MUST have a unique name.
# Example: "survival-1", "creative", "lobby"
server-id : "default-server"
# The duration in milliseconds after which a player data lock is considered expired.
# This prevents players from being permanently locked out if a server crashes.
# Default: 60000 (1 minute)
lock-timeout : 60000
- `database.*`: Standard configuration for your MySQL database connection.
- `debug`: Set to `true` to enable verbose debugging messages in the server console. Set to `false` for normal operation.
- `server-id` (Required): You **must** set a unique name for each of your PaperMC/Spigot servers. This is critical for the data locking system to work correctly. The proxy server does not need this configuration.
- `lock-timeout`: The time in milliseconds after which a data lock is considered expired. This prevents a player from being permanently locked if a server crashes while saving their data.
► Usage
- Add the JAR: Place the single `mc-data-bridge-*.jar` file into the `plugins/` folder of all your PaperMC servers AND your BungeeCord/Velocity proxy.
- Configure: Edit the `config.yml` in each PaperMC server's `plugins/mc-data-bridge/` folder. **Set a unique `server-id` for each server.**
- Restart Servers: Restart your proxy and all backend Minecraft servers.
- Enjoy! Players can now seamlessly switch between your linked servers, and their data will be synchronized automatically and safely.
► Important Notes
- Database Requirement: This plugin requires a MySQL or MariaDB database to function.
- Security Best Practice: For production servers, it is strongly recommended to create a dedicated MySQL user for this plugin with limited permissions. The user only needs `SELECT`, `INSERT`, `UPDATE`, `CREATE`, and `ALTER` on the specified database.
- Connectivity & Firewalls: Ensure your Minecraft servers and proxy can open a network connection to your database's `host` and `port`.
- Automatic Schema: The plugin will automatically create and update the `player_data` table in your database. The schema includes `uuid`, `data`, `is_locked`, `locking_server`, `lock_timestamp`, and `last_updated`.
Resource Information
Author:
----------
Total Downloads:
48
First Release:
Sep 6, 2025
Last Update:
Nov 7, 2025
Category:
---------------
All-Time Rating:
Find more info at github.com...
0 ratings
Version
-----
Released:
--------------------
Downloads:
------
Version Rating:
----------------------
-- ratings