Перейти к содержимому
Mineforgian

MC-Data-Bridge

Seamlessly sync player inventory, health, XP, and effects across your BungeeCord/Velocity network.

Загрузки
811
Подписчики
5
Обновлён
26 июня 2026 г.
Лицензия
GPL-3.0-only

Опубликован 6 сентября 2025 г.

Исходный кодСообщить об ошибке

MC Data Bridge

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

Compatibility

  • Minecraft Version: 1.21.x and 26.1.x
  • Server Platforms: PaperMC (Purpur), Folia, Spigot
  • Proxy Platforms: 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

  • Hybrid Plugin: A single JAR file works on your PaperMC/Spigot/Folia servers and your BungeeCord/Velocity proxy.
  • Companion & Pet Synchronization: Fully synchronizes tamed wolves, cats, parrots, and other pets with support for shoulder-perched states, ownership, names, health, and metadata. Offers configurable modes (follow, return, untracked) with robust state merging and duplication prevention.
  • Relational Component Schema Normalization: Divides player data into normalized, targeted tables to optimize write performance and prevent write-amplification.
  • Binary NBT Serialization Option: Choose between JSON and compressed binary NBT format (database.serialization-format: binary) for highly optimized CPU serialization and database storage.
  • Embedded Prometheus Metrics Exporter: Provides an optional HTTP endpoint (/metrics) to monitor active transactions, cache efficiency, connection pool health, and sync latencies.
  • SHA-256 Data Integrity: Implements cryptographic checksums with server-side salting to detect and prevent manual database tampering or corruption.
  • Industrial Identity Protection: Tracks last_known_name and secure identity hashes to prevent identity hijacking and manage UUID transitions in hybrid (Cracked/Premium) environments.
  • Zero-Tick Identity Verification: 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.
  • Regionalized Folia Support: Built with SchedulerUtils to handle regionalized threading, ensuring safe execution on Folia's multi-threaded clusters.
  • Administrative Inspector GUI: A visual interface for administrators to inspect saved player data (inventories, stats, PDC) even when the player is offline.
  • 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.
  • Fully Asynchronous: All database and serialization operations are performed on a separate thread, ensuring that your server's main thread is never blocked.
  • Robust Locking Mechanism: A database-level locking mechanism with an automatic timeout and heartbeats prevents data corruption.
  • Version-Independent Item Serialization: Player inventories are serialized using native binary methods (Paper/Folia) or NBT-API fallback (Spigot), ensuring 100% integrity across updates.
  • Cross-Server Player Data Sync (Granular Control):
    • Health (Attribute-aware)
    • Food Level, Saturation, & Exhaustion
    • Experience (Total XP, current XP, and Level)
    • Inventory & Armor Contents
    • Active Potion Effects
    • Ender Chest Contents
    • Advancements & Recipes
    • Player Statistics (Vanilla stats)
    • Persistent Data Container (PDC) (Custom metadata)
    • Flight & GameMode status
    • Companions & Pets (Tamed wolves, cats, parrots, etc.)
  • Resilient Connection Pooling: Uses HikariCP with optimized settings for resilience against network jitter.
  • Flexible Storage: Support for MySQL/MariaDB or local SQLite databases.
  • Granular Sync Control: Enable or disable synchronization for any specific data type via config.yml.
  • Server/World Blacklist: Prevent synchronization on specific servers or worlds.

Installation

  1. Download the Plugin JAR:
    • Download the latest release JAR (mc-data-bridge-*.jar) from this page (Modrinth) or the official GitHub Releases.
  2. Deploy to Servers:
    • Copy the single mc-data-bridge-*.jar file into the plugins/ folder of each PaperMC/Folia server you wish to synchronize.
    • Copy the same JAR file into the plugins/ folder of your BungeeCord or Velocity proxy server.
  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.

# Database Configuration
database:
  type: mysql # "mysql" or "sqlite"
  host: localhost
  port: 3306
  database: minecraft
  username: user
  password: password
  sqlite-file: "player_data.db"
  serialization-format: "json" # "json" or "binary"

  # 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"

# Prefix for all database tables
table-prefix: ""

# Toggle specific data to sync
sync-data:
  health: true
  food-level: true
  experience: true
  inventory: true
  armor: true
  potion-effects: true
  ender-chest: true
  location: false
  advancements: true
  statistics: true
  pdc: true
  flight-gamemode: true
  companions: 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

# Companion/Pet Synchronization Settings
companions:
  scan-radius: 32
  mode: "follow" # "follow", "return", or "untracked"

# Prometheus Metrics Exporter
metrics:
  enabled: false
  port: 8080
  path: "/metrics"

# Server/World Blacklist
sync-blacklist:
  servers:
    - "example-blacklisted-server"
  worlds:
    - "example_world_nether"

Detailed Configuration Breakdown

  • database.type: Choose between mysql (external) or sqlite (local file).
  • database.serialization-format: Select binary for compressed NBT data or json for backward-compatible Base64 NBT.
  • server-id (Required): You must set a unique name for each backend server.
  • security.seed: A secret string used to salt all SHA-256 hashes. Change this immediately!
  • identity.mode: Choose between PREMIUM (strictly enforces UUID consistency) or HYBRID (allows flexible identity shifts). Note: HYBRID mode is required to enable auto-migration features like auto-migrate-fastlogin.
  • sync-data: Individual toggles for every data type.
  • companions: Set the detection radius and choose how pets behave when swapping servers.
  • metrics: Configure the embedded Prometheus HTTP server port and route.
  • sync-blacklist: Define servers or worlds where synchronization should be skipped.

📊 Technical: Database Schema

In addition to the primary tracking table (player_data), MC Data Bridge uses component tables to minimize database load.

Core Locking & Integrity Table: player_data

Column Type Description
uuid VARCHAR(36) The player's Unique ID (Primary Key).
data LONGBLOB The serialized binary data snapshot (legacy fallback).
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.
name_last_updated BIGINT Timestamp of when the player's name was last updated.
last_updated TIMESTAMP Auto-updated timestamp of the last lock state change.

Inventories Component: databridge_inventories

  • Holds inventory_blob (LONGBLOB/TEXT), armor_blob (LONGBLOB/TEXT), and ender_chest_blob (LONGBLOB/TEXT) snapshots.
  • Includes a last_updated auto-timestamp.

Statistics Component: databridge_statistics

  • Holds basic stats (health DOUBLE/REAL, food_level INT/INTEGER, xp_level INT/INTEGER, xp_exp FLOAT/REAL, xp_total INT/INTEGER, saturation FLOAT/REAL, exhaustion FLOAT/REAL).
  • Holds vanilla_stats_json (TEXT) containing dynamic statistics, locations, and recipe states.
  • Includes a last_updated auto-timestamp.

Metadata Component: databridge_metadata

  • Holds custom PDC data (pdc_data LONGTEXT/TEXT) and player advancement progress (advancements LONGTEXT/TEXT).
  • Includes a last_updated auto-timestamp.

Companions Component: databridge_companions (NEW)

  • Holds companion and pet metadata states (companions_nbt LONGTEXT/TEXT).
  • Includes a last_updated auto-timestamp.

For more detailed information, please refer to the official documentation.

Ченджлог

2.1.7Релиз26.1, 26.1.1, 26.1.2 · 26 июня 2026 г.

MC Data Bridge - Release Notes (v2.1.7)

Overview

Version 2.1.7 is a targeted bugfix release that upgrades the vanilla_stats_json column type in the statistics component table to LONGTEXT (for MySQL/MariaDB), preventing potential data truncation issues when synchronizing large volumes of vanilla player statistics. It also introduces automatic schema migration for existing databases.

Changes in v2.1.7

🗄️ Database Schema Upgrade & Migration

  • Upgrade to LONGTEXT: Upgraded the vanilla_stats_json column from TEXT to LONGTEXT in the databridge_statistics table to support larger JSON payloads without risk of truncation.
  • Automated Migration: Added support for automatically executing the ALTER TABLE ... MODIFY COLUMN ... statement when auto-update-schema is set to true in the configuration.
  • Admin Warning Notice: If auto-update-schema is disabled, the plugin will now log a prominent warning suggesting the manual execution of the schema migration command:
    ALTER TABLE `table_prefix_databridge_statistics` MODIFY COLUMN vanilla_stats_json LONGTEXT DEFAULT NULL;

For installation instructions and configuration details, please refer to the README.md and config.yml.

2.1.6Релиз26.1, 26.1.1, 26.1.2 · 12 июня 2026 г.

MC Data Bridge - Release Notes (v2.1.6)

Overview

Version 2.1.6 is a comprehensive feature and security update that introduces multi-server Companion & Pet Synchronization, implements dynamic Full Vanilla Player Statistics Synchronization, completes database schema normalization, adds compressed binary NBT serialization, embeds a Prometheus Metrics Exporter, and hardens overall network security with strict seed verification.

Key Features & Improvements

📊 Full Vanilla Player Statistics Synchronization

  • Dynamic Statistics Sync: Replaced the legacy hardcoded list of 16 statistics with a dynamic, version-independent synchronization loop that covers all vanilla player statistics.
  • Qualified/Typed Statistics Support: Fully syncs all typed statistics requiring qualifiers—including blocks mined, items crafted/used/broken/picked up/dropped, and entities killed or killed by (e.g., MINE_BLOCK:STONE, KILL_ENTITY:ZOMBIE, USE_ITEM:IRON_PICKAXE).
  • Intelligent State Application: Minimizes database updates and server overhead by only applying statistic changes when values differ from the server's current values.
  • State Cleanup & Resets: Restores synchronization parity by resetting any non-zero stats on the destination server that are not present in the player's database snapshot (setting them back to zero).
  • Graceful Version Resilience: Silently handles version-specific or custom blocks, items, and entity types, maintaining perfect compatibility across heterogeneous multi-server environments.

🐾 Companion & Pet Synchronization

  • Multi-Mode Synchronization: Added companions.mode (follow, return, untracked) to manage how pets are synced across the network.
  • Tamed Pet Persistence: Synchronizes tamed wolves, cats, parrots, and other pets across server switches.
  • Shoulder-Perched Entity Serialization: Saves and restores parrot shoulder-riding states.
  • State Preservation: Restores ownership, custom names, health/max health, and sitting status accurately.
  • NBT-Level Preservation: Utilizes NBTAPI metadata merging to preserve custom pet attributes, items, and collars.
  • Merge-on-Save Pattern: Adopts a robust relational state merging strategy to prevent NBT overrides and companion data loss across servers (critical for return mode).
  • Duplication Prevention: Despawns source entities synchronously upon snapshot generation to prevent duplication exploits.

🗄️ Relational Component Schema Normalization

  • Companions Component Table: Introduced the databridge_companions table for row-level normalized storage.
  • Optimized SQL Transactions: Avoids write-amplification by target-updating specific components (inventories, statistics, metadata, companions) independently.

⚡ Binary NBT Serialization Option

  • Compressed NBT Storage: Adds support for native binary compression (serialization-format: binary) to dramatically reduce database footprint, storage I/O, and CPU serialization overhead.

🛡️ Production Security Hardening

  • Fails-Strict Safe Mode: Prevents startup if the default cryptographic seed is detected and no secure seed is configured, mitigating identity hijacking risks.
  • DDL Column Whitelists: Enforces SQL parameter and column sanitation to secure automated schema migration queries.

📊 Embedded Prometheus Metrics Exporter

  • Live Server Metrics: Provides an optional HTTP /metrics scrape endpoint for Grafana/Prometheus tracking, exposing cache efficiency, database connection pool statistics, active transaction counts, and synchronization latencies.

For installation instructions and configuration details, please refer to the README.md and config.yml.

2.1.5Релиз26.1, 26.1.1, 26.1.2 · 29 апреля 2026 г.

MC Data Bridge - Release Notes (v2.1.5)

Overview

Version 2.1.5 is a stability patch focused on maintaining compatibility with the bleeding-edge Paper 26.1 API (Minecraft 1.21.4+). This release addresses a specific serialization issue with modern Adventure text objects and optimizes the plugin's internal dependency structure.

Changes & Fixes

🧩 Adventure Text Serialization Patch

  • Resolved a NoClassDefFoundError and serialization failure affecting niche Adventure text components, specifically those used in modern Player Head metadata.
  • Aligned internal dependencies with Adventure v4.26.1 to support the latest Minecraft 1.21.4 features.

🚀 Modern API & Build Stability

  • Paper 26.1 Support: Officially verified compatibility with the latest Paper alpha builds.
  • Dependency Optimization: Transitioned Adventure libraries to provided scope, maintaining a lightweight JAR (~3.0M) while ensuring native performance on Paper/Velocity.

For installation instructions and configuration details, please refer to the README.md and config.yml.

2.1.3Релиз26.1, 26.1.1, 26.1.2 · 17 апреля 2026 г.

Refactor: Modernize for Java 25 & Fix Velocity Proxy Deadlocks (v2.1.3)

📝 Description

This PR focuses on updating the core infrastructure to align with the bleeding-edge Minecraft 26.1.2 / Java 25 ecosystem. It also contains a critical fix for a cross-server data deadlock issue that occurred when switching servers on our proxy network.

🐛 Bug Fixes

  • Velocity Server Switch Deadlocks: Resolved a critical cross-server data lock issue where the proxy failed to gracefully intercept server transfers and release player SQL locks prior to routing.
  • Annotation Processor Mitigation: The root cause of the proxy deadlock was traced back to our Java 25 / Maven Annotation Processors suppressing proxy integration endpoints during compilation. By explicitly passing the @Plugin Velocity API annotation directly into the compiler arguments array, we've successfully recovered the generation of the velocity-plugin.json initialization file. The proxy component now initializes and intercepts transfers cleanly.
  • Structural Null Safety: Resolved BungeeCord and Velocity ByteArrayDataOutput.writeUTF structural inference problems around UUID String boundaries to ensure strict conformance to Guava expectations.

🚀 Modernization & Technical Debt

  • API Standardization:
    • Updated paper-api to 26.1.2.build.7-alpha.
    • Updated velocity-api to 3.5.0-SNAPSHOT (Build #592).
    • Updated item-nbt-api to 2.15.7.
    • Updated testing dependencies (mockito) to 5.23.0.
  • Legacy Refactors:
    • Migrated health sync properties to utilize Attribute.MAX_HEALTH, fully deprecating the legacy GENERIC_ prefix requirements targeting modern APIs.
    • Restructured PlayerQuitEvent logic in our flow suites to adopt modern Component adventure text system, erasing legacy string deprecations natively.
    • Upgraded internal plugin message events to correctly route their legacy event parameters, accommodating proxy-transfer flags natively.

🛡 Zero-Suppression Defensive Null Safety

  • Phased out @SuppressWarnings for null validation loops across the entire bridge logic constraint map, replacing them with mechanically enforced java.util.Objects.requireNonNull validation layers cleanly.
  • Safely rewired ambiguous core Bukkit states (getLocation, advancementIterator, getCommand) to aggressively trap and seal implicit analyzer NPE leakages directly inside the event pipeline.

🏗 Build Pipeline Adjustments

  • Upgraded compiler compliance matrix to strictly target Java 25 (<release>25</release>).
  • Bumped maven-shade-plugin natively to 3.6.2, and injected cutting-edge org.ow2.asm 9.9.1 dependencies to successfully resolve shade failures against Java 25's new major bytecode signatures.

🧪 Testing & Verification

  • Verified compilation integrity on Java 25.
  • Live tested on proxy environment (Velocity 3.5.0 handling two PaperMC 26.1.2 instances).
  • Tested rapid server hopping back-and-forth between instances.
  • Verified perfect synchronization across Health, Inventory, and complex NBT data during immediate server switches with zero proxy timeouts or deadlocks.
2.1.2Релиз1.21.9, 1.21.10, 1.21.11 · 21 февраля 2026 г.

Release Notes - v2.1.2

MC Data Bridge v2.1.2 - Maintenance & Dependency Update

This release focuses on updating core dependencies and resolving build-time compatibility issues.

🔧 Maintenance

  • Dependency Updates:
    • Updated MockBukkit to 3.133.2.
    • Updated paper-api to 1.21.1-R0.1-SNAPSHOT (Fixed compatibility issues with newer MockBukkit).
    • Updated mysql-connector-j to 9.6.0.
    • Updated mockito to 5.14.2.
2.1.1Релиз1.21.9, 1.21.10, 1.21.11 · 25 декабря 2025 г.

Release Notes - v2.1.1

MC Data Bridge v2.1.1 - Critical Bug Fix & Stability Update

This patch release addresses a critical issue reported where players with boosted health (e.g., via Health Boost potion effects or attributes) were being kicked upon switching servers.

🐛 Bug Fixes

  • Fixed Kick on Server Switch with High Health: Resolved an issue where players with health greater than 20.0 (Health Boost) would be kicked with an IllegalArgumentException. The plugin now safely handles this by loading potions and attributes from the database before setting the max health attribute.
2.1.0Релиз1.21.9, 1.21.10, 1.21.11 · 13 декабря 2025 г.

Release Notes - v2.1.0

MC Data Bridge v2.1.0 - Official Minecraft 1.21.11 Support | Secure MySQL Player Data Synchronization

  • Now fully compatible with Minecraft 1.21.11. Securely syncs all player data (inventory, health, XP, hunger) using robust MySQL locking across your BungeeCord or Velocity network.

Deploy this JAR to all your PaperMC and Spigot servers, connecting to the corresponding proxy plugin (BungeeCord or Velocity) and a centralized MySQL database.

####⭐ What's New in v2.1.0* Minecraft 1.21.11 Compatibility: Full support for the latest Minecraft 1.21.11 release. This ensures all player data structures, including any new or updated serialization components introduced in the latest version, are correctly captured and applied without errors.

####🚀 Core Features & Stability* Complete Player Data Synchronization: Securely saves and loads all essential player attributes across your network, including:

  • Inventory and Armor

  • Health and Max Health

  • Experience Level and Progress

  • Full Hunger Attributes: Food Level, Saturation, and Exhaustion.

  • Potion Effects

  • Ender Chest, Advancements, and Statistics (configurable).

  • Robust Data Integrity (MySQL Locking): Employs a server-ID-based database locking mechanism to prevent race conditions and data corruption when players switch servers quickly or disconnect abruptly.

  • Lag-Free Performance: All database operations (lock acquisition, save, and load) are performed asynchronously off the main server thread to prevent server lag.

  • Admin Utility: Use the /databridge unlock <player> command to manually clear player data locks if a connection is unexpectedly terminated.

2.0.8Релиз1.21.8, 1.21.9, 1.21.10 · 13 декабря 2025 г.

Release Notes - v2.0.8

🐛 Bug Fixes

  • Fixed Saturation & Exhaustion Sync: Resolved an issue where saturation and exhaustion levels were not being saved or applied. These fields now correctly sync when food-level is enabled in config.yml.

Комментарии

Загружаем…