MC-Data-Bridge

MC Data Bridge - Release Notes (v2.2.2)

Overview

Version 2.2.2 is a major release introducing enterprise-grade concurrency, integrity, and performance protections derived from an architectural security audit. Features include monotonic distributed lock fencing tokens, normalized snapshot SHA-256 integrity validation, single-transaction atomic saves, event-driven lock release messaging to eliminate pre-login latency, standard HMAC-SHA256 identity hashing, and automated unit testing in CI. ---

Key Changes

Monotonic Distributed Lock Fencing Tokens (#41, AUDIT §2)

- Epoch Fencing Protection: Added lock_version (BIGINT DEFAULT 0) to player_data. Every lock acquisition increments lock_version, producing a monotonic fencing token. - Stale Write Prevention: Saves, heartbeats, and lock releases evaluate WHERE uuid = ? AND locking_server = ? AND lock_version = ?. Delayed servers or un-fenced post-GC pause writes are automatically rejected, protecting database state from stale session overwrites.

Normalized Data Integrity Checksums (#42, AUDIT §3)

- Normalized SHA-256 Checksum Verification: Added snapshot_checksum (VARCHAR(64)) to player_data. - Snapshot Integrity Verification: Computes canonical SHA-256 hashes across health, food, XP, NBT blobs (inventory, armor, ender chest, PDC), and game mode salted with security.seed. Protects against database tampering across normalized component tables.

Atomic Single-Transaction Persistence & Migration (#44, #45, AUDIT §5, §6)

- Single-Transaction Component Saves & Releases (#44): saveAndReleaseLockComponents now executes all component writes (databridge_inventories, statistics, metadata, companions, maps) and lock releases within a single database connection and transaction (setAutoCommit(false) ... commit()). - Transactional Legacy Migration (#45): loadLegacyData executes component migration and legacy data = NULL clearing inside a unified transaction with automatic rollback (rollback()) on failure to eliminate dual-source-of-truth conditions.

Event-Driven Lock Release Messaging — Up to 10X Faster Server Switching (#46, AUDIT §9)

- ⚡ Up to 10X Faster Cross-Server Transfers: Dispatches an instant LockReleased plugin message upon source server save completion. Destination servers wake up waiting pre-login threads immediately, slashing server-switch lock wait latency from ~500ms down to a near-instant ~50ms! - Resilient Fallback: Retains 500ms database polling loops as a zero-downtime fallback mechanism if network messages are dropped.

Keyed HMAC-SHA256 Identity Verification (#47, AUDIT §12)

- Standard HMAC-SHA256: Upgraded identity hashing in HashUtils to use standard HmacSHA256 key derivation with security.seed. - Seamless Dual Verification: Automatically verifies existing records against both HMAC-SHA256 and legacy salted SHA-256 digests for 100% backward compatibility without table migrations.

Automated CI Unit Testing & Concurrency Suite (#43, AUDIT §16)

- CI Test Automation: Re-enabled automated unit testing in GitHub Actions (.github/workflows/maven.yml) on pull requests and merges. - Concurrency & HMAC Unit Tests: Added LockFencingTest and HashUtilsTest verifying lock token increments, stale write rejections, HMAC generation, legacy fallback, and null safety.

Documentation & Onboarding Overhaul

- Streamlined Platform Descriptions: Overhauled README.md, DESCRIPTION.md, and Spigot/Modrinth listings with cleaner layouts and fast-start guides to improve reader onboarding. - Dedicated Technical Guides: Separated complex architectural concepts and database setup instructions into dedicated [ARCHITECTURE.md](github.com/westkevin12/mc-data-bridge/ARCHITECTURE.md) and [DATABASE_SETUP.md](github.com/westkevin12/mc-data-bridge/DATABASE_SETUP.md) files for cleaner readability. --- _For installation instructions and configuration details, please refer to [README.md](README.md), [ARCHITECTURE.md](ARCHITECTURE.md), and [DATABASE_SETUP.md](DATABASE_SETUP.md)._

MC Data Bridge - Release Notes (v2.2.1)

Overview

Version 2.2.1 is a release streamlining map synchronization architecture, introducing configurable map locking enforcement, fixing map canvas color palette rendering issues, and adding automatic config migration from v2.2.0. ---

Key Changes

Map Sync Architecture Simplification (#36, #39)

[!NOTE]

Developer Note: _"I couldn't think of a single valid use case for return mode with held map items. It seemed like a good idea at first, but having a broken, unusable map item on another server would likely never be the server admin's intention."_

- Streamlined Map Synchronization Model: Removed legacy maps.mode (return/untracked per-server stashing). Map synchronization is now toggled cleanly via sync-data.maps: false (default, vanilla style handling) or sync-data.maps: true (global map sync). - Configurable Map Locking (`maps.lock-global-maps`): Added maps.lock-global-maps: false (default). When set to true, enforces map locking (locked = 1) on cross-server maps to prevent target servers from re-scanning terrain or applying Fog of War over custom artwork. - Automatic Legacy Config Migration: Existing v2.2.0 configuration files are automatically upgraded on startup: - Legacy maps.mode: global -> Migrated to sync-data.maps: true, maps.lock-global-maps: true. - Legacy maps.mode: return / untracked / off -> Migrated to sync-data.maps: false, maps.lock-global-maps: false. - Obsolete maps.mode config entries are automatically removed. - Fixed `maps_nbt` Persistence: Corrected snapshot extraction and database merge logic to ensure map snapshots and canvas pixels are saved non-null to the {table-prefix}databridge_maps table. - Locked Map Resolution Support: Improved map ID resolution logic (resolveMapId) to resolve map IDs from item components and PDC (databridge:original_map_id), preventing locked maps created in Cartography Tables from being skipped during saves. - Canvas Palette & Renderer Fix: Resolved canvas rendering issues where maps rendered as solid brown blocks. Default background world renderers are now cleared (view.getRenderers().clear()) before applying custom raw canvas palette byte renderers. --- _For installation instructions and configuration details, please refer to the [README.md](README.md) and [config.yml](src/main/resources/config.yml)._

MC Data Bridge - Release Notes (v2.2.0)

Overview

Version 2.2.0 introduces Map Sync Between Servers and Separate Gamemode Inventories, allowing players and staff members to maintain isolated inventory profiles per gamemode and stash maps per-server across proxy networks without data conflicts, alongside core dependency updates. ---

Key Changes

Map Sync Between Servers (#36)

- Server-Isolated Map Stashing (`mode: return`): Filled map items created on Server A are tagged with origin metadata (databridge:origin_server and databridge:original_map_id). When transferring to Server B, foreign maps are safely stashed in the database (databridge_maps) and automatically restored to their inventory slots when returning to Server A. - Configurable Map Synchronization Modes: Added a new maps: config section supporting three modes: - return (default): Stashes and restores server-specific map items per server. - global: Synchronizes map canvas pixel data across all network servers. - untracked: Legacy vanilla map handling. - Component Database Storage: Added {table-prefix}databridge_maps table in MySQL and SQLite for atomic map persistence and cross-server UUID data migration.

Separate Gamemode Inventories (#33)

- Opt-In Gamemode Inventory Separation (`sync-data.separate-gamemode-inventories`): Staff members and players can maintain separate inventory, armor, and Ender Chest profiles for Survival, Creative, Adventure, and Spectator modes. - Live Gamemode Swapping Hook: Automatically snapshots and restores gamemode-specific inventory profiles when switching gamemodes on the fly (PlayerGameModeChangeEvent). - Isolated Component Table: Stores gamemode inventory profiles in {table-prefix}databridge_gamemode_inventories using (uuid, gamemode) composite key.

Dependency Updates

- MySQL Connector/J: Updated com.mysql:mysql-connector-j from 9.7.0 to 26.7.0. - Item NBT API: Updated de.tr7zw:item-nbt-api from 2.15.7 to 2.16.0. - JUnit Jupiter: Updated org.junit.jupiter:junit-jupiter from 6.1.0 to 6.1.3. --- _For installation instructions and configuration details, please refer to the [README.md](README.md) and [config.yml](src/main/resources/config.yml)._

MC Data Bridge - Release Notes (v2.1.9)

Overview

Version 2.1.9 delivers Proxy Subcommand Auto-Forwarding across proxy platforms (Velocity, BungeeCord, and Waterfall) and Real-Time Online Player Live Inventory Sync & Active Edit Lock Protection. ---

Key Changes

Proxy Subcommand Auto-Forwarding (#34)

- Proxy-to-Backend Command Routing: Non-unlock subcommands (e.g. /databridge or /db followed by invsee, endersee, inspect, reload, sync, migrate) executed by players on proxy servers (Velocity, BungeeCord, and Waterfall) are now automatically routed downstream to their connected backend Paper/Spigot server without requiring explicit namespace prefixes (/mc-data-bridge:databridge). - Namespace Interception Fix: Fixes command hijack and usage rejection issues when running shorthand /databridge subcommands across proxy setups.

Online Player Live Inventory Sync & Active Edit Lock (#31, #32)

- Real-Time In-Memory Update: Edits made to an online player's inventory or ender chest via /databridge invsee --edit or /databridge endersee --edit now immediately update the target player's live, in-memory inventory on their active server instance. - Cross-Server Live Sync: Dispatches a LiveInventorySync message over the mc-data-bridge:main plugin channel when editing online players on other servers across the proxy network, forcing an instant live memory reload without requiring player relog. - Pre-Fetch Memory Snapshot: Opening an inspection GUI for a locally online player automatically snapshots their live memory state first, preventing recent item pickups or drops from being overwritten by older database data. - Active Edit Lock Protection: Protects online target players from inventory desync or duplicate item exploits while an admin is actively modifying their inventory in an edit GUI. --- _For installation instructions and configuration details, please refer to the [README.md](README.md) and [config.yml](src/main/resources/config.yml)._

MC Data Bridge - Release Notes (v2.1.8)

Overview

Version 2.1.8 introduces Item Duplication Exploit Protection, Full Tab Completion, Interactive Inventory & Ender Chest Inspection (`invsee` & `endersee`) with read-only and edit modes, Granular Permissions, Database Schema Auto-Migration, and Paper 26.2 Platform Parity. ---

Key Changes

Item Duplication Exploit Protection (#30)

- Special Thanks: Special thanks to @AllenLinong for discovering and reporting this critical exploit ([#30](https://github.com/westkevin12/mc-data-bridge/issues/30))! - Safe Inventory Closure: Open inventory views are automatically closed before player data snapshots are captured during server switches. - Transfer Lock Enforcement: Cancels item drops, item pickups, container clicks, inventory drags, and block/entity interactions while a player transfer or database save is in progress.

Interactive Inventory & Ender Chest Inspector (invsee / endersee)

- New Subcommands & Aliases: - /databridge inspect <player> [inventory|enderchest] [--edit] - /databridge invsee <player> [--edit] - /databridge endersee <player> [--edit] - Safe View-Only Mode (Default): Inspection GUIs open in read-only mode by default (Left-Click in Overview GUI) to prevent accidental item modifications or unintended edits. - Interactive Edit Mode (`--edit` flag or Right-Click): Admins with databridge.inspect.edit permission can interactively edit items (Right-Click in Overview GUI or using --edit flag) in offline/cross-server player inventories or ender chests directly inside the GUI. - Database Auto-Save: Closing an editable GUI (InventoryCloseEvent) automatically serializes modified item stacks back to the database so changes apply when the player logs in.

Granular Permission Nodes

- databridge.inspect (or databridge.admin): Permission to view player data, inventories, and ender chests in safe read-only mode. - databridge.inspect.edit (or databridge.admin): Elevated permission required to open interactive edit mode using the --edit flag. - databridge.admin: Full administrative access to all commands and subcommands.

Full Command Tab Completion

- TabExecutor / Brigadier Integration: Added dynamic auto-completion for subcommands (unlock, inspect, invsee, endersee, migrate), online player names, view types (inventory, enderchest), and the --edit flag.

Database Schema Maintenance & Upgrades

- Auto-Update Schema: Added auto-update-schema configuration toggle (default true) to automatically manage table upgrades. - Column Expansion: Upgraded vanilla_stats_json column to LONGTEXT (MySQL/MariaDB) / TEXT (SQLite) to accommodate large recipe books, advancements, and vanilla statistics.

Paper 26.2 & Dependency Upgrades

- Updated Target API: Compiled and tested against Paper API 26.2 and verified on Paper 26.2+ servers. - HikariCP: Upgraded connection pool library to 7.1.0. - Platform Reflection: Retains full backward compatibility for pre-26.2 Spigot/Paper versions via dynamic reflection. --- _For installation instructions and configuration details, please refer to the [README.md](README.md) and [config.yml](src/main/resources/config.yml)._

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](README.md) and [config.yml](src/main/resources/config.yml)._

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](README.md) and [config.yml](src/main/resources/config.yml)._

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](README.md) and [config.yml](src/main/resources/config.yml)._

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

- [x] Verified compilation integrity on Java 25. - [x] Live tested on proxy environment (Velocity 3.5.0 handling two PaperMC 26.1.2 instances). - [x] Tested rapid server hopping back-and-forth between instances. - [x] Verified perfect synchronization across Health, Inventory, and complex NBT data during immediate server switches with zero proxy timeouts or deadlocks.

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. ---

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.

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.

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.

Release Notes - MC Data Bridge v2.0.3

New Features

Granular Data Synchronization*: You can now toggle exactly what data is synced in config.yml. Added sync-data section. Ender Chest Sync*: Added support for synchronizing Ender Chest contents! (Disabled by default, enable in config). Advancements Integration*: Added support for standard Advancements and Recipes! (Disabled by default). Admin Unlock Command*: Added /databridge unlock <player> to manually release a stuck lock. Blacklist*: Added sync-blacklist to disable synchronization on specific servers or worlds.

Improvements & Optimizations

Configurable Heartbeat*: Added lock-heartbeat-seconds to control how often the data lock is refreshed. Better Messages*: Updated message handling to use Adventure API for full modern chat component support. Database Check*: Added a startup check to warn if your database schema for data is LONGTEXT instead of the recommended MEDIUMBLOB.

Important Notes

Configuration Update: The plugin now features a Smart Auto-Updater. On startup, it will detect any missing configuration keys (like the new `sync-data` section) and safely append them to your existing `config.yml`. You do NOT need to reset your config.* Schema Optimization*: The plugin now supports LONGBLOB for the data column, which is more efficient than LONGTEXT. Automatic Migration*: A new check will run on startup. If you are using the old LONGTEXT format, the plugin will automatically attempt to migrate your table to LONGBLOB if the config option auto-update-schema is set to true (which is the default for updated configs). Manual*: If you prefer, you can manually run ALTER TABLE player_data MODIFY COLUMN data LONGBLOB NULL;.

Release Notes

Version 2.0.2

This maintenance release focuses on API modernization, code cleanup, and continued stability improvements.

Improvements & Fixes

Adventure API:* Switched to the Adventure API (Component.text) for handling disconnect and kick messages, replacing legacy string formatting. Dependency Updates:* Updated bungeecord-api to the latest 1.21-R0.4. Safety Checks:* Added null checks to prevent errors when kicking players during data application failures. Legacy Data Compatibility:* Explicitly marked and documented legacy NBT and potion effect handling to ensure older data formats continue to load correctly without generating build warnings. Code Cleanup:* Removed various unused imports and cleaned up code. ---

Release Notes - MC Data Bridge 2.0.1

This is a landmark update, representing a complete architectural overhaul of MC Data Bridge to introduce robust, high-performance, cross-server data synchronization for BungeeCord and Velocity networks.

Major New Features

Cross-Server Synchronization:* The plugin now fully supports synchronizing player data (inventory, health, XP, potion effects, etc.) across multiple servers connected via a BungeeCord or Velocity proxy. Database Locking System:* A sophisticated, atomic locking mechanism has been implemented to prevent all race conditions and data corruption. * When a player joins a server, the plugin acquires a lock on their data in the database. * This lock is continuously renewed via a "heartbeat" task while the player is online. * If a player switches servers, the new server waits for the old server to save and release the lock. * A configurable lock-timeout ensures that if a server crashes, its locks will eventually expire and can be claimed by another server, preventing players from being permanently locked out. Proxy Integration:* The plugin now listens for a custom mc-data-bridge:main plugin message from the proxy. This message tells the server to immediately save a player's data when they are switching servers, ensuring data is persisted before they connect to the next server. Startup Self-Healing:* On startup, the plugin will now find and release any "orphaned" locks that were held by that same server before a crash or shutdown, ensuring a clean state.

Configuration & Setup

`server-id` (Critical): A new, mandatory `server-id` has been added to `config.yml`. Each server connected to the same database must* have a unique ID for the locking system to function correctly. `lock-timeout`:* A new setting to control how long a lock is considered valid before it can be forcefully acquired by another server. The default is 60 seconds.

Compatibility

Minecraft Version:* This version is built for and compatible with Minecraft 1.21.x. Platform Support: The plugin now requires the Paper API (for Spigot servers) and includes support for BungeeCord API and Velocity API*.

Stability & Performance

New Serialization Format: Item data is now serialized to Base64*, which is significantly more robust and reliable than the previous NBT-based string method. Backward Compatibility:* The new version can still read the old NBT-based item format, ensuring a smooth upgrade path for existing users. Old data will be converted to the new format the next time it is saved. Optimized Database Logic:* All database interactions have been rewritten to be more efficient and atomic, using HikariCP for best-in-class connection pooling.

Important Notes for Upgrading

This is a major, breaking update.* It is a drop-in replacement, but its core logic is entirely new. Proxy Installation Required: For the new cross-server synchronization to work, you must install the same `mc-data-bridge-.jar file into the plugins/` folder of your BungeeCord or Velocity proxy server. Configuration is Critical: You must* define a unique server-id in your config.yml on every single one of your Spigot/Paper servers. Failure to do so will lead to data corruption in a multi-server environment.

Features * deps: A new script scripts/update_deps.sh has been added to automate the process of updating Maven dependencies. This script will check for the latest versions, update the pom.xml, and verify the build, which will streamline the development workflow. Refactoring * potion: The SerializablePotionEffect class has been updated to use the modern, key-based API for serializing and deserializing potion effect types. This change fixes the use of deprecated methods and makes the serialization more robust and future-proof. Chore * The project version has been bumped to 1.21.8.2.

MC Data Bridge

MC Data Bridge is a Spigot/Paper plugin designed to seamlessly synchronize player data across multiple Minecraft servers. This allows players to move between linked servers (e.g., a Towny server and a Resource server) and retain their health, hunger, experience, inventory, armor, and active potion effects.

Features

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 Configurable Database Connection:* Easily connect to your MySQL database. Flexible Synchronization Groups:* Create distinct synchronization groups by using different database credentials or table names for different sets of servers. For example, you can have one database for your "Towny" servers and another for your "vanilla" servers, ensuring data is synced only within those specific groups.

Installation

1. Build the Plugin: * Navigate to the plugin's root directory in your terminal. * Run mvn clean package to build the plugin. * The compiled JAR file (mc-data-bridge-1.21.8.1-shaded.jar) will be located in the target/ directory. 2. Deploy to Servers: * Copy the mc-data-bridge-1.21.8.1-shaded.jar file into the plugins/ folder of each PaperMC server you wish to synchronize.

Configuration

A config.yml file will be generated in the plugins/mc-data-bridge/ folder after the first run (or you can create it manually). You must update this file with your MySQL database credentials.

database:
  host: localhost
  port: 3306
  database: minecraft
  username: user
  password: password
debug: false

`database.host`*: Your MySQL database host (e.g., localhost, 127.0.0.1, a remote IP, or a [Docker named volume](https://docs.docker.com/storage/volumes/#create-and-manag… if your database is running in Docker). `database.port`*: The port your MySQL database is running on (default is 3306). `database.database`*: The name of the database to use for player data. `database.username`*: The username for connecting to your database. `database.password`*: The password for the database user. `debug`*: Set to true to enable verbose debugging messages in the server console. Set to false for normal operation.

Synchronizing Multiple Server Groups

To sync player data between specific groups of servers (e.g., a Towny server and a Towny resource server, separate from a Creative server), simply configure the database.database (or even entirely different database.host, username, password) to match for the servers you want to link. Example: Towny Servers (Towny-Main, Towny-Resource):*

    database:
      host: my_db_host
      port: 3306
      database: towny_player_data # All Towny servers use this database
      username: towny_user
      password: towny_password
    debug: false
    

Creative Servers (Creative-Build, Creative-Minigame):*

    database:
      host: my_db_host
      port: 3306
      database: creative_player_data # All Creative servers use this database
      username: creative_user
      password: creative_password
    debug: false
    

Usage

1. Add the JAR: Place the mc-data-bridge-1.21.8.1-shaded.jar file into the plugins/ folder of all your PaperMC servers. 2. Configure: Edit the config.yml in each server's plugins/mc-data-bridge/ folder with the appropriate database credentials for your desired synchronization groups. 3. Restart Servers: Restart your Minecraft server containers (or the servers themselves) to apply the plugin and configuration changes. 4. Enjoy! Players can now seamlessly switch between your linked servers, and their data will be synchronized automatically.

Important Notes

This plugin requires a MySQL database* to function. Ensure your database server is accessible from your Minecraft servers. * The plugin will automatically create the player_data table in your specified database if it doesn't already exist. * You might still see warnings about deprecated APIs during compilation. These are generally harmless and do not prevent the plugin from functioning.