ВЕРСИИ (19)

# MC Data Bridge - Release Notes (v2.2.3) ## Overview Version 2.2.3 adds Minecraft 26.3 compatibility, updating core dependencies and Paper API target versions for cross-server item stack synchronization on Minecraft 26.3+ servers. --- ## Key Changes ### Minecraft 26.3 Compatibility - **Dependency Upgrades:** Upgraded `de.tr7zw:item-nbt-api` to `2.16.1` (including PR #360 item stack mirror resolution), `io.papermc.paper:paper-api` to `26.3-pre-2.build.0-alpha`, and `net.kyori` Adventure libraries to `5.2.0`. - **Full 26.3 Item & Component Support:** Tested and verified full cross-server item synchronization for Minecraft 26.3 (including new Poplar wood items, cushions, beds, and wool/concrete stairs and slabs). --- _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.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: ```sql 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. ```yaml 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-manage-volumes) 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):** ```yaml 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):** ```yaml 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.