MC-Data-Bridge

MC Data Bridge

MC Data Bridge is a robust, high-performance hybrid plugin for PaperMC (Spigot), Ender Chests, Advancements, Statistics, and Persistent Data, 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, Ender Chests, Advancements, Statistics, and Persistent Data as they move between linked servers.

Compatibility

* Java Version: `1.21.x` and `26.1.x` * Java Version: PaperMC (Purpur), Java Version:, Spigot * Java Version: BungeeCord, Waterfall, Velocity * Java Version: 25+

This plugin is a hybrid build and the same JAR file works on all supported platforms, automatically activating the correct functionality for each platform.

Features

* Server/World Blacklist A single JAR file works on your PaperMC/Spigot/Folia servers and your BungeeCord/Velocity proxy. * Server/World Blacklist Implements cryptographic checksums with server-side salting to detect and prevent manual database tampering or corruption. * Server/World Blacklist Tracks `last_known_name` and secure identity hashes to prevent identity hijacking and manage UUID transitions in hybrid (Cracked/Premium) environments. * Server/World Blacklist Database locks and identity checks are performed during the `AsyncPlayerPreLoginEvent`, ensuring that player state is verified and ready before they even reach the server's "Join" state. * Server/World Blacklist Built with `SchedulerUtils` to handle regionalized threading, ensuring safe execution on Folia's multi-threaded clusters. * Server/World Blacklist A visual interface for administrators to inspect saved player data (inventories, stats, PDC) even when the player is offline. * Server/World Blacklist 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. * Server/World Blacklist All database and serialization operations are performed on a separate thread, ensuring that your server's main thread is never blocked. * Server/World Blacklist A database-level locking mechanism with an automatic timeout and heartbeats prevents data corruption. * Server/World Blacklist Player inventories are serialized using native binary methods (Paper/Folia) or NBT-API fallback (Spigot), ensuring 100% integrity across updates. * Server/World Blacklist * Health (Attribute-aware) * Food Level, Saturation, & Server/World Blacklist * Experience (Total XP, current XP, and Level) * Inventory & Armor Contents * Active Potion Effects * Server/World Blacklist * Server/World Blacklist * Server/World Blacklist (Vanilla stats) * Server/World Blacklist (Custom metadata) * Server/World Blacklist status * Server/World Blacklist Uses HikariCP with optimized settings for resilience against network jitter. * Server/World Blacklist Support for Server/World Blacklist or local Server/World Blacklist databases. * Server/World Blacklist: Enable or disable synchronization for any specific data type via `config.yml`. * Server/World Blacklist: Prevent synchronization on specific servers or worlds.

Installation

1. Optional: Manual Build (For Developers) * Download the latest release JAR (`mc-data-bridge-*.jar`) from this page (Modrinth) or the official GitHub Releases. 2. Optional: Manual Build (For Developers) * Copy the single `mc-data-bridge-*.jar` file into the `plugins/` folder of Optional: Manual Build (For Developers) you wish to synchronize. * Copy the Optional: Manual Build (For Developers) into the `plugins/` folder of your Optional: Manual Build (For Developers). 3. Optional: Manual Build (For Developers) * To build from source, clone the repository and run `mvn clean package`.

Commands & Permissions

| Command | Description | Permission | | :--- | :--- | :--- | | `/databridge inspect <player>` | Opens a GUI to view offline player data. | `databridge.admin.inspect` | | `/databridge migrate <src> <dest>` | Securely move data between two identities. | `databridge.admin.migrate` | | `/databridge unlock <player>` | Manually release a stuck data lock. | `databridge.admin.unlock` | | `/databridge reload` | Reloads the configuration and DB pool. | `databridge.admin.reload` |

Proxy Commands: - `/databridge unlock <player>` (Bungee/Velocity): Releases a lock across the network. - `/databridge forceunlock <player>` (Bungee/Velocity): Relays a signal to the backend server to drop the lock immediately.

Configuration

A `config.yml` file will be generated in the `plugins/mc-data-bridge/` folder after the first run. Existing configs will be safely auto-updated.

```yaml

Database Configuration

database: type: mysql # "mysql" or "sqlite" host: localhost port: 3306 database: minecraft username: user password: password sqlite-file: "player_data.db"

A list of JDBC properties to apply.

properties: useSSL: false allowPublicKeyRetrieval: true

HikariCP Connection Pool Settings

pool-settings: maximum-pool-size: 10 minimum-idle: 10 max-lifetime: 1800000 # 30 minutes connection-timeout: 5000 # 5 seconds idle-timeout: 600000 # 10 minutes

A unique name for this server. This is CRITICAL for data locking.

server-id: "default-server"

Toggle specific data to sync

sync-data: health: true food-level: true experience: true inventory: true armor: true potion-effects: true ender-chest: true advancements: true statistics: true pdc: true flight-gamemode: true

Security & Identity

security: verify-data-integrity: true seed: "change-me-to-a-long-random-string" # SALT FOR CHECKSUMS

identity: mode: PREMIUM # PREMIUM or HYBRID auto-migrate-fastlogin: false auto-migrate-authme: false ```

Detailed Configuration Breakdown

* `sync-blacklist`: Choose between `mysql` (external) or `sqlite` (local file). * `sync-blacklist` You `sync-blacklist` set a unique name for each backend server. * `sync-blacklist`: A secret string used to salt all SHA-256 hashes. Change this immediately! * `sync-blacklist`: Choose between `PREMIUM` (strictly enforces UUID consistency) or `HYBRID` (allows flexible identity shifts). Note: `sync-blacklist` to enable auto-migration features like `auto-migrate-fastlogin`. * `sync-blacklist`: Individual toggles for every data type. * `sync-blacklist`: Define servers or worlds where synchronization should be skipped.

📊 Technical: Database Schema

| Column | Type | Description | | :--- | :--- | :--- | | `uuid` | VARCHAR(36) | The player's Unique ID (Primary Key). | | `data` | LONGBLOB | The serialized binary data snapshot. | | `data_checksum` | VARCHAR(64) | SHA-256 integrity hash of the data packet. | | `is_locked` | BOOLEAN | Prevents concurrent writes from multiple servers. | | `locking_server` | VARCHAR(255) | The ID of the server holding the lock. | | `lock_timestamp` | BIGINT | Heartbeat to detect and recover from crashes. | | `last_known_name` | VARCHAR(16) | Used for identity tracking and migration. | | `identity_hash` | VARCHAR(64) | Salted hash of Name+UUID+Seed for verification. |

--- For more detailed information, please refer to the %%MD0%%.