PlayerDataSync

[26.5.5.1-ALPHA] - 2026-05-20

Added

• Fabric: fabric-api (0.92.2+1.20.1) so lifecycle and server-play networking APIs resolve at compile time; fabric.mod.json declares a fabric-api dependency.
• Velocity: Gradle task generatePluginBuildInfo emits PluginBuildInfo.VERSION so the @Plugin version always matches the Gradle project version.
• Modrinth / Fabric: Guide pds-docs/modrinth-upload.md (Paper vs Fabric JAR); Gradle task checkFabricModMetadata asserts fabric.mod.json exists in the remapped Fabric JAR; Fabric archive base name playerdatasync-fabric so it is not confused with the Paper plugin artifact.
• Unified distribution JAR: The Paper PlayerDataSyncReloaded-*.jar (also copied to build/libs/) embeds bundled/playerdatasync-velocity.jar, bundled/playerdatasync-fabric.jar, and bundled/playerdatasync-forge.jar plus bundled/README.txt — one download; extract sibling JARs for Velocity/Fabric/Forge (classes are not merged to avoid mapping clashes).

Changed

• Gradle / bytecode targets: api and common use Java 17 (Fabric/Forge); plugin and Velocity use Java 21 so Paper 1.21.x can remap the shaded plugin (ASM does not accept class file 69). Nested :versions:* modules are set to 21 in versions/build.gradle.kts (they are not root subprojects, so they previously picked up the toolchain default and emitted 69).
• Velocity: velocity-api updated to 3.5.0-SNAPSHOT; Velocity→backend plugin messages use UTF-8 (StandardCharsets.UTF_8); ServerConnectedEvent log line uses event.getServer().getServerInfo() (Velocity 3 API).
• Shadow plugin: Replaced com.github.johnrengelman.shadow 8.1.1 with com.gradleup.shadow 8.3.10 so shadowJar can process modern class files when relocating (e.g. bundled jars).
• Forge: META-INF/mods.toml version is expanded from Gradle (mod_version); Forge build.gradle.kts no longer overrides root version / group.
• Fabric: build.gradle.kts no longer overrides root version / group (single version from gradle.properties).
• Gradle runtime: Configuration cache disabled in gradle.properties (ForgeGradle, Fabric Loom, and Shadow-related flows are not reliable with CC enabled); parallel and build caching remain enabled.
• CI: Workflow runs ./gradlew :plugin:build and uploads the unified build/libs/PlayerDataSyncReloaded-*.jar (includes bundled/ platform JARs).

Fixed

• Bukkit version handlers: v1_20_R1 and v26_1_R1 VersionHandlerImpl now extend BukkitBaseVersionHandler and implement capture / apply with PDSPlayer (restores compatibility after removal of BaseVersionHandler).
• Fabric PlayerDataSyncFabric: ServerPlayNetworking global receiver is registered in SERVER_STARTING after storage/SyncManager setup; SLF4J error logging for storage init; guards when syncManager is not ready yet.
• Forge PlayerDataSyncForge: storage init failures use Log4j instead of printStackTrace; packet and login handlers guard syncManager == null.
• Multi-platform build: Resolved Gradle dependency variant mismatches (Fabric vs api/common JVM level). v26_1_R1: compileClasspath requests JVM 25 so Paper 26 paper-api resolves while sources still compile with --release 21.

Notes

• One JAR download: build/libs/PlayerDataSyncReloaded-*.jar contains Paper + bundled/ Velocity/Fabric/Forge JARs; Modrinth still needs the extracted platform files per loader (see pds-docs/modrinth-upload.md).
• Modrinth: Use bundled/playerdatasync-fabric.jar (extracted from the distribution JAR) for the Fabric loader file — not the outer archive root (that is the Paper plugin with plugin.yml only).
• Paper 1.21.x: The main plugin classes are built as Java 21 bytecode so the server’s PluginRemapper can read them. Run the server on Java 21+ as required by Paper 1.21. Deploy the JAR whose name matches gradle.properties version (e.g. PlayerDataSyncReloaded-26.5.5.1-ALPHA.jar); delete any older file such as PlayerDataSyncReloaded-26.5.5-SNAPSHOT.jar from plugins/ so Paper does not remap a stale build. The shaded jar excludes META-INF/versions/** so multi-release dependency layers (class file 69) are not shipped to the remapper.

[26.5.4-Release] - 2026-05-05

Fixed

• Build Process: Redirected final shaded JAR output to the root build directory for easier access.
• Database Migration: Added automatic schema migration for SQL storage to fix "Unknown column" errors when upgrading from older versions.
• Legacy Fallback: Implemented automatic fallback to the legacy data format if the new JSON format is missing in SQL storage.

[26.5.3-Release] - 2026-05-05

Added

• Database Migration: Added automatic schema migration for SQL storage to fix "Unknown column" errors when upgrading from older versions.
• Legacy Fallback: Implemented automatic fallback to the legacy data format if the new JSON format is missing in SQL storage.

Changed

• Paper Compatibility: Updated NMS support for the stable Paper 26.1.2 release.
• Dependency Management: Updated internal version modules to target the latest stable API builds.

[26.5.2-Release] - 2026-05-03

Changed

• Paper Compatibility: Updated NMS support for the stable Paper 26.1.2 release.
• Dependency Management: Updated internal version modules to target the latest stable API builds.

[26.5.1-Release] - 2026-05-01

Fixed

• Thread Safety: Resolved IllegalStateException on Paper/Purpur servers where PlayerDataSaveEvent was incorrectly triggered on the main thread while marked as an asynchronous event. Both Save and Load events are now synchronous to ensure full compatibility with the Bukkit threading model.

[26.5-Release] - 2026-04-27

Added

• API Extensibility: Added extraData map to PlayerData for third-party plugin data synchronization.
• Save Cancellation: PlayerDataSaveEvent now implements Cancellable, allowing plugins to prevent data from being saved under specific conditions.
• Granular Sync Controls: Added new configuration options to disable syncing for Potion Effects, Food, GameMode, Advancements, and Statistics.
• Improved Version Detection: Better handling for Minecraft 1.21.1 and future sub-versions.

Changed

• Banner Update: Refreshed the startup banner with new colors and "Expansion Update" subtitle.
• Performance: Minor internal optimizations for event handling.

Fixed

• Potential edge case where data might save during an invalid state.

[26.4-Release] - 2026-04-18

Added

• Storage Migrator: Full release of the migration tool for seamless transitions between SQL and NoSQL.
• Zipped Backup System: Reliable export/import system for disaster recovery.
• Legacy Migration Support: Bridge for users coming from the original PlayerDataSync version.
• Vault Economy Sync: Stable cross-network balance synchronization.
• Advanced Sync Features: Full support for PDC, Attributes, Statistics, and Advancements.
• Auto-Save System: Background saving task to prevent data loss.
• Exclusion System: World and item blacklists for granular control.

Changed

• Modernized Version Support: Dropped legacy support. Now exclusively supporting 1.20, 1.21, and 26.1+.
• Performance Optimizations: GZIP compression and dedicated thread pools are now enabled by default.
• Inventory Hashing: Intelligent skip mechanics for unchanged data.

Fixed

• All issues discovered during the Beta phase, including NMS fallback and thread safety.

[26.4-BETA] - 2026-04-12

Added

• Storage Migrator: Added a powerful tool to move data between any supported database backend (MySQL, MariaDB, PostgreSQL, MongoDB).
• Zipped Backup System: Added /pds backup export/import for portable data management and safety.
• Legacy Migration Support: Added specialized support to migrate data from the old PlayerDataSync version to the new Reloaded format.
• Vault Economy Sync: Full synchronization for player balances across the network.
• Advanced Sync Features: Added support for Persistent Data Containers (PDC), modern Attributes, Statistics, and Advancements.
• Auto-Save System: Automated background saving of all online players to prevent data loss on server crashes.
• Exclusion System: Added blacklists for specific worlds and items (by material) to prevent them from being synchronized.
• Management Commands: Added /pds reload for hot-reloading connections and /pds migrate for data transfers.
• Real-time Feedback: Configurable chat messages for players during synchronization events.
• Debug Mode: Detailed logging for easier troubleshooting in complex environments.

Changed

• Modernized Version Support: Dropped legacy support for Minecraft 1.8 through 1.19. Now exclusively supporting 1.20, 1.21, and 26.1+.
• Massive Performance Boost:
  • Integrated GZIP Compression for serialized data, reducing storage size and network load by up to 90%.
  • Introduced Dedicated Thread Pools for all database I/O to ensure the main server thread is NEVER blocked.
  • Added Inventory Hashing to skip redundant database writes if data hasn't changed.
• Simplified Architecture: Refactored the core logic into a cleaner multi-module system.
• Banner: Updated the startup console banner for a premium look.

Fixed

• Fixed internal Attribute constant name changes between 1.20 and 1.21.
• Fixed NoClassDefFoundError occurring when specific version modules were missing.
• Fixed thread safety issues in MongoDB and SQL storage handlers.
• Fixed reflection issues for PersistentDataContainer compatibility across 1.20/1.21.

[26.4.1-SNAPSHOT] - 2026-04-11

Added

• Initial Reload Release: Complete rewrite and modernization of the sync engine.
• Java 25 Support: Leveraged the latest Java features for performance.
• Multi-Database Support: Added drivers for MySQL, MariaDB, PostgreSQL, and MongoDB.
• Redis Pub/Sub Sync: Implemented ultra-fast synchronization for high-traffic networks.
• Folia Compatibility: Support for region-based multithreading.
• AES Encryption: Secure player data storage and transmission.
• Expanded Sync Options:
  • Inventory and Ender Chest.
  • Health, Food, and Experience.
  • Potion Effects.
  • Advancements and Statistics.
  • Game Mode and Flight status.
  • Location tracking across instances.
  • Attributes and Persistent Data Container (PDC) data.
• New Command System: Improved /playerdatasync (aliases: /pds, /pdasync).
• Improved Config: New structured config.yml with clear documentation for all settings.

🚀 [Reloaded v26.4-SNAPSHOT] - 2026-03-28

The "Reloaded" version is a complete rewrite of the original PlayerDataSync plugin, designed for better performance, modern server support, and extensibility.

---

✨ Added

🧠 Core Engine Rewrite

• Completely new architecture for better stability and lower performance impact.

💾 Improved Database Handling

• Integrated HikariCP for high-performance connection pooling.
• MySQL/MariaDB support for cross-server synchronization.

🔄 Comprehensive Data Synchronization

• Inventories, Armor, and Ender Chests (Base64 serialized)
• Health (including Max Health and Scale)
• Food Level, Saturation, and Exhaustion
• Experience (Level, Progress, Total Exp) and Score
• GameMode, Flight status, and Location
• New: Potion Effects, Statistics, and Persistent Data Container (PDC)

🧩 Modern Server Support

• Native Folia support with regionalized scheduling
• Compatible with Paper, Spigot, and Bukkit (1.8 - 1.21+)

🌍 Internationalization (i18n)

• Multi-language support with dedicated translation files
• Included languages:
  • German
  • English
  • Chinese (TW)
  • Dutch
  • Korean
  • Malay
  • and more

🛠️ Enhanced Utilities

• ColorUtils: Support for modern HEX colors and legacy formatting
• Reflection API: Cross-version compatibility handling

📊 Metrics

• Integrated bStats to track plugin usage and statistics

---

🔄 Changed

• Migrated storage format to JSON for better extensibility
• Optimized save tasks with configurable intervals (auto-save-ticks)
• Improved join/quit logic to prevent data loss or race conditions

---

🐛 Fixed

• Resolved many legacy bugs associated with NBT serialization
• Fixed async database operations to prevent main-thread lag

---

❤️ Powered by CraftingStudioPro

[PlayerDataSync-26.3.4-SNAPSHOT] - 2026-03-11

🔧 Fixed & Improved

• Legacy Minecraft Support (1.8-1.16): Resolved multiple critical issues for older server versions.
• Java 8 Compatibility: Fixed NoSuchMethodError: String.isBlank() by replacing it with Java 8 compatible alternatives in MessageManager.
• FastStats Isolation: Isolated Java 17-dependent metrics library to prevent UnsupportedClassVersionError on Java 8 environments.
• JDBC Driver Fixes:
  • Implemented explicit driver registration to solve "No suitable driver found" errors in shaded environments (PaperSpigot 1.8.8).
  • Fixed AbstractMethodError: Connection.isValid() by adding safety wrappers for legacy JDBC drivers (SQLite).
• Configuration Robustness:
  • Fixed an issue where config.yml was being stripped of content and comments on older Bukkit versions by reducing unnecessary saves.
  • Implemented explicit UTF-8 loading for configuration files to prevent character encoding issues on Windows servers.
  • Enhanced configuration migration and initialization to correctly merge defaults without overwriting existing user settings.
• Stability and Performance:
  • Fixed a race condition where default configurations were not being saved to disk before being reloaded during the first startup.
  • Consolidated maintenance mode and version checking logs for better readability.

[PlayerDataSync-26.3.3-SNAPSHOT] - 2026-03-10

🚀 New Features

• Maintenance Mode: Pause all data syncing with /sync maintenance <on|off>. Useful for database migrations or emergency fixes.
• Management GUI: Use /sync menu for a visual way to toggle sync options and manage the plugin.
• Performance Profiler: Use /sync profile to track average and maximum save/load times for better performance monitoring.

🔧 Fixed

• Java Compatibility: Downgraded default Java target to Java 8 to ensure full compatibility with Minecraft 1.8.8 through 1.16.5 (Purpur) and resolved "Unsupported class file major version 65" errors.
• Build Configuration: Removed conflicting activeByDefault profile to prevent accidental Java 21 builds.

🔄 Update Checker

• Hardcoded API Key: Added a hardcoded API key (CSP-PDS-...) for streamlined server-to-API authentication.
• Improved Caching: Implemented a 1-hour cache for update metadata to reduce unnecessary API requests.
• Manual Check Command: Added /sync checkupdate command to manually trigger an update check (bypasses cache).
• Silent Reloading: Added simplified version check handling that can be called asynchronously without blocking the main thread.

[PlayerDataSync-26.3.2-SNAPSHOT] - 2026-03-07

🔄 Update Checker

• API Migration: Fully migrated to CraftingStudio Pro API v1 using modern HttpClient.
• API Key Support: Added hardcoded API key support directly in UpdateChecker.java for streamlined authentication.
• Improved Reliability: Replaced legacy HttpURLConnection with asynchronous requests and better error handling.
• Enhanced URLs: Updated download and plugin info links to the new category-based structure.

Update – PlayerDataSync 26.3.1-SNAPSHOT

A small update has been released for PlayerDataSync.

Changes

• Fixed an issue with the version display
• Corrected the plugin version number

Some users were seeing the incorrect version number 2025.03.
This version number was not correct.

With this update, the version has been corrected to 26.3.1-SNAPSHOT.

Please make sure to update to the latest version to avoid confusion with incorrect version information.

[PlayerDataSync-26.3-RELEASE] - 2026-03-04

🔧 Fixed

• MongoDB: Fixed MongoDB errors / MongoDB-Fehler behoben.

[PlayerDataSync-26.2-RELEASE] - 2026-02-20

🛠 XP Sync Fixes

• Fixed an edge-case where spent XP (for example after enchanting) could be restored on relog due to stale total XP capture.
• Added immediate autosave hooks for XP/level changes and enchanting to persist XP updates right away.
• Added new config toggle autosave.on_xp_change (default: true) for instant XP persistence.

🗃 Database & Compatibility

• Kept automatic schema update behavior on startup and runtime upgrade attempts for safe database migrations.
• Prepared compatibility messaging/docs for upcoming 26.1/26.2 cycle.

[1.3.0-RELEASE] - 2026-02-13

🔄 Reworked Update Checker

• Complete rewrite of version check flow with robust semantic comparison for tags like -RELEASE/-BETA
• Uses configurable request timeout (update_checker.timeout) for reliable network behavior
• Smarter latest-version detection avoids false positive update notifications

⚡ XP Synchronization Improvements

• Optimized XP apply flow with bounded correction attempts for more stable cross-version results
• Improved mismatch handling to prevent repeated over/under-correction on join/load
• More precise debug and warning logs for diagnosing XP sync edge-cases

💰 Economy Sync Optimization

• Optimized balance transfer with normalized precision for smooth and reliable Vault synchronization
• Added post-transfer verification and auto re-adjustment attempts to reduce desyncs
• Improved fallback logic when provider-specific setBalance implementations are inconsistent

[1.2.9-RELEASE] - 2026-01-25

🎯 Custom-Enchantment-Support & Database Upgrade / Custom-Enchantment-Support & Datenbank-Upgrade

🔧 Fixed

• Database Truncation Error (Critical Fix) / Datenbank-Truncation-Fehler (Critical Fix):

  • EN: Fixes "Data too long for column" errors with large inventories
  • DE: Behebt "Data too long for column" Fehler bei großen Inventaren
  • ✅ EN: Automatic upgrade from TEXT to LONGTEXT for inventory, enderchest, armor, and offhand columns
  • ✅ DE: Automatisches Upgrade von TEXT zu LONGTEXT für inventory, enderchest, armor und offhand Spalten
  • ✅ EN: Now supports inventories with many custom enchantments (e.g., ExcellentEnchants)
  • ✅ DE: Unterstützt jetzt Inventare mit vielen Custom-Enchantments (z.B. ExcellentEnchants)
  • ✅ EN: Upgrade is performed automatically on server start
  • ✅ DE: Upgrade wird automatisch beim Server-Start durchgeführt
  • ✅ EN: Runtime upgrade attempt on truncation errors
  • ✅ DE: Runtime-Upgrade-Versuch bei Truncation-Fehlern
  • ✅ EN: Improved error messages with solution suggestions
  • ✅ DE: Verbesserte Fehlermeldungen mit Lösungsvorschlägen
  • 🔧 EN: Fixes issues with large inventories and custom enchantments
  • 🔧 DE: Behebt Probleme mit großen Inventaren und Custom-Enchantments

• Custom-Enchantment Deserialization / Custom-Enchantment-Deserialisierung:

  • EN: Robust error handling for custom enchantments
  • DE: Robuste Fehlerbehandlung für Custom-Enchantments
  • ✅ EN: Improved detection of custom enchantment errors (e.g., minecraft:venom)
  • ✅ DE: Verbesserte Erkennung von Custom-Enchantment-Fehlern (z.B. minecraft:venom)
  • ✅ EN: Items are skipped instead of causing plugin crashes
  • ✅ DE: Items werden übersprungen statt Plugin-Absturz zu verursachen
  • ✅ EN: Data remains preserved in the database
  • ✅ DE: Daten bleiben in der Datenbank erhalten
  • ✅ EN: Detailed logging with enchantment names
  • ✅ DE: Detailliertes Logging mit Enchantment-Namen
  • ✅ EN: Support for ExcellentEnchants and similar plugins
  • ✅ DE: Unterstützung für ExcellentEnchants und ähnliche Plugins
  • 🔧 EN: Prevents crashes with unrecognized custom enchantments
  • 🔧 DE: Verhindert Abstürze bei nicht erkannten Custom-Enchantments

• Stale Player Data / Veraltete Spielerdaten:

  • EN: Fixes issue with outdated player data
  • DE: Behebt Problem mit nicht aktualisierten Spielerdaten
  • ✅ EN: Database upgrade enables successful saves
  • ✅ DE: Datenbank-Upgrade ermöglicht erfolgreiche Speicherungen
  • ✅ EN: Improved error handling prevents data loss
  • ✅ DE: Verbesserte Fehlerbehandlung verhindert Datenverlust
  • ✅ EN: Automatic recovery after database upgrade
  • ✅ DE: Automatische Wiederherstellung nach Datenbank-Upgrade

✨ Added

• Custom-Enchantment Synchronization / Custom-Enchantment-Synchronisation:

  • EN: Full support for custom enchantments
  • DE: Vollständige Unterstützung für Custom-Enchantments
  • ✅ EN: Preservation of all NBT data including custom enchantments during serialization
  • ✅ DE: Erhaltung aller NBT-Daten inklusive Custom-Enchantments beim Serialisieren
  • ✅ EN: Refresh mechanism after loading inventories (2-tick delay)
  • ✅ DE: Refresh-Mechanismus nach dem Laden von Inventaren (2-Tick-Delay)
  • ✅ EN: Explicit re-setting of items so plugins can process enchantments
  • ✅ DE: Explizites Neusetzen von Items, damit Plugins Enchantments verarbeiten können
  • ✅ EN: Works for main inventory, armor, offhand, and enderchest
  • ✅ DE: Funktioniert für Hauptinventar, Rüstung, Offhand und Enderchest
  • 📝 EN: Supports plugins like ExcellentEnchants that use custom enchantments
  • 📝 DE: Unterstützt Plugins wie ExcellentEnchants, die Custom-Enchantments verwenden

• Deserialization Statistics & Monitoring / Deserialisierungs-Statistiken & Monitoring:

  • EN: Comprehensive monitoring system
  • DE: Umfassendes Monitoring-System
  • ✅ EN: Counters for custom enchantment errors, version compatibility errors, and other errors
  • ✅ DE: Zähler für Custom-Enchantment-Fehler, Versionskompatibilitäts-Fehler und andere Fehler
  • ✅ EN: getDeserializationStats() method for statistics
  • ✅ DE: getDeserializationStats() Methode für Statistiken
  • ✅ EN: resetDeserializationStats() method to reset statistics
  • ✅ DE: resetDeserializationStats() Methode zum Zurücksetzen
  • ✅ EN: Integration into /sync cache command
  • ✅ DE: Integration in /sync cache Befehl
  • ✅ EN: Detailed error logging with enchantment names
  • ✅ DE: Detaillierte Fehlerprotokollierung mit Enchantment-Namen
  • 📝 EN: Admins can now easily monitor custom enchantment issues
  • 📝 DE: Admins können jetzt Probleme mit Custom-Enchantments einfach überwachen

• Improved Error Handling / Verbesserte Fehlerbehandlung:

  • EN: Extended error detection and handling
  • DE: Erweiterte Fehlererkennung und -behandlung
  • ✅ EN: Automatic extraction of enchantment names from error messages
  • ✅ DE: Automatische Extraktion von Enchantment-Namen aus Fehlermeldungen
  • ✅ EN: Detailed error chain analysis (up to 3 levels)
  • ✅ DE: Detaillierte Fehlerketten-Analyse (bis zu 3 Ebenen)
  • ✅ EN: Contextual error messages with solution suggestions
  • ✅ DE: Kontextuelle Fehlermeldungen mit Lösungsvorschlägen
  • ✅ EN: Better detection of various error types (IllegalStateException, NullPointerException, etc.)
  • ✅ DE: Bessere Erkennung verschiedener Fehlertypen (IllegalStateException, NullPointerException, etc.)
  • ✅ EN: Pattern-based detection of custom enchantment errors
  • ✅ DE: Pattern-basierte Erkennung von Custom-Enchantment-Fehlern

🔄 Changed

• Database Schema / Datenbank-Schema:

  • EN: Automatic upgrade for existing installations
  • DE: Automatisches Upgrade für bestehende Installationen
  • ✅ EN: inventory: TEXT → LONGTEXT (max. ~4GB instead of ~65KB)
  • ✅ DE: inventory: TEXT → LONGTEXT (max. ~4GB statt ~65KB)
  • ✅ EN: enderchest: TEXT → LONGTEXT
  • ✅ DE: enderchest: TEXT → LONGTEXT
  • ✅ EN: armor: TEXT → LONGTEXT
  • ✅ DE: armor: TEXT → LONGTEXT
  • ✅ EN: offhand: TEXT → LONGTEXT
  • ✅ DE: offhand: TEXT → LONGTEXT
  • ✅ EN: Upgrade is performed automatically on server start
  • ✅ DE: Upgrade wird beim Server-Start automatisch durchgeführt
  • 📝 EN: Existing data is preserved, no data migration needed
  • 📝 DE: Bestehende Daten bleiben erhalten, keine Datenmigration nötig

• EditorIntegration Removed / EditorIntegration entfernt:

  • EN: Preparation for website update
  • DE: Vorbereitung für Website-Update
  • ✅ EN: EditorIntegrationManager completely removed
  • ✅ DE: EditorIntegrationManager komplett entfernt
  • ✅ EN: All editor-related commands removed
  • ✅ DE: Alle Editor-bezogenen Befehle entfernt
  • ✅ EN: Code cleanup for future editor integration
  • ✅ DE: Code-Bereinigung für zukünftige Editor-Integration
  • 📝 EN: New editor integration will be added in a future version
  • 📝 DE: Neue Editor-Integration wird in zukünftiger Version hinzugefügt

📊 Technical Details

Database Upgrade Process / Datenbank-Upgrade-Prozess

EN: The plugin automatically performs an upgrade of database columns on startup:

DE: Das Plugin führt beim Start automatisch ein Upgrade der Datenbank-Spalten durch:

1. EN: Check: Verifies the current data type of each column DE: Prüfung: Überprüft den aktuellen Datentyp jeder Spalte
2. EN: Upgrade: Converts TEXT to LONGTEXT if necessary DE: Upgrade: Konvertiert TEXT zu LONGTEXT wenn nötig
3. EN: Logging: Logs all upgrades for transparency DE: Logging: Protokolliert alle Upgrades für Transparenz
4. EN: Runtime Upgrade: Also attempts to upgrade during runtime if an error occurs DE: Runtime-Upgrade: Versucht auch während des Betriebs zu upgraden, wenn ein Fehler auftritt

EN: Why LONGTEXT?
DE: Warum LONGTEXT?

• TEXT: Max. ~65KB (65,535 bytes)
• LONGTEXT: Max. ~4GB (4,294,967,295 bytes)
• EN: Custom enchantments with extensive NBT data can become very large
• DE: Custom-Enchantments mit vielen NBT-Daten können sehr groß werden
• EN: Large inventories with many items and enchantments require more space
• DE: Große Inventare mit vielen Items und Enchantments benötigen mehr Platz

Custom-Enchantment Error Handling / Custom-Enchantment-Fehlerbehandlung

EN: The improved error handling recognizes various error types:

DE: Die verbesserte Fehlerbehandlung erkennt verschiedene Fehlertypen:

• IllegalStateException with DataResult/Codec/Decoder
• NullPointerException in enchantment-related classes
• EN: Error messages with "enchantment not found/unknown/invalid"
• DE: Fehlermeldungen mit "enchantment not found/unknown/invalid"
• EN: Pattern-based detection of custom enchantment names
• DE: Pattern-basierte Erkennung von Custom-Enchantment-Namen

EN: Error Handling Flow:
DE: Fehlerbehandlung-Flow:

1. EN: Attempt normal deserialization DE: Versuch der normalen Deserialisierung
2. EN: On error: Check if it's a custom enchantment problem DE: Bei Fehler: Prüfung ob es ein Custom-Enchantment-Problem ist
3. EN: Extract enchantment name from error message DE: Extraktion des Enchantment-Namens aus der Fehlermeldung
4. EN: Detailed logging with context DE: Detailliertes Logging mit Kontext
5. EN: Item is skipped (null), but data remains in database DE: Item wird übersprungen (null), aber Daten bleiben in DB
6. EN: Statistics are updated DE: Statistiken werden aktualisiert

Refresh Mechanism / Refresh-Mechanismus

EN: After loading inventories, a refresh mechanism is executed:

DE: Nach dem Laden von Inventaren wird ein Refresh-Mechanismus ausgeführt:

1. EN: Initial Load: ItemStacks are loaded from database DE: Initiales Laden: ItemStacks werden aus der Datenbank geladen
2. EN: 2-Tick Delay: Waits 2 ticks to give plugins time to initialize DE: 2-Tick-Delay: Wartet 2 Ticks, damit Plugins Zeit haben zu initialisieren
3. EN: Refresh: Explicitly re-sets items to trigger plugin processing DE: Refresh: Setzt Items explizit neu, um Plugin-Verarbeitung zu triggern
4. EN: Update: Calls updateInventory() for client synchronization DE: Update: Ruft updateInventory() auf für Client-Synchronisation

EN: Why 2 Ticks?
DE: Warum 2 Ticks?

• EN: Gives custom enchantment plugins time to register their enchantments
• DE: Gibt Custom-Enchantment-Plugins Zeit, ihre Enchantments zu registrieren
• EN: Enables plugin event handlers to react to item changes
• DE: Ermöglicht Plugin-Event-Handler, auf Item-Änderungen zu reagieren
• EN: Prevents race conditions between plugin loading and item loading
• DE: Verhindert Race-Conditions zwischen Plugin-Loading und Item-Loading

Statistics System / Statistiken-System

EN: The new statistics system collects information about deserialization errors:

DE: Das neue Statistiken-System sammelt Informationen über Deserialisierungs-Fehler:

• EN: Custom Enchantment Errors: Counts items skipped due to unrecognized custom enchantments
• DE: Custom-Enchantment-Fehler: Zählt Items, die wegen nicht erkannter Custom-Enchantments übersprungen wurden
• EN: Version Compatibility Errors: Counts items with version compatibility issues
• DE: Versionskompatibilitäts-Fehler: Zählt Items mit Versionskompatibilitätsproblemen
• EN: Other Errors: Counts all other deserialization errors
• DE: Andere Fehler: Zählt alle anderen Deserialisierungs-Fehler

EN: Usage:
DE: Verwendung:

/sync cache          # EN: Shows all statistics / DE: Zeigt alle Statistiken
/sync cache clear    # EN: Resets statistics / DE: Setzt Statistiken zurück

🔍 Monitoring & Debugging

EN: Admins can now easily monitor custom enchantment issues:

DE: Admins können jetzt einfach Probleme mit Custom-Enchantments überwachen:

1. EN: View Statistics: /sync cache shows deserialization statistics DE: Statistiken anzeigen: /sync cache zeigt Deserialisierungs-Statistiken
2. EN: Analyze Errors: Detailed logs show exactly which enchantments cause problems DE: Fehler analysieren: Detaillierte Logs zeigen genau, welche Enchantments Probleme verursachen
3. EN: Fix Issues: Clear error messages with solution suggestions DE: Probleme beheben: Klare Fehlermeldungen mit Lösungsvorschlägen

EN: Example Output:
DE: Beispiel-Output:

Deserialization Stats: Deserialization failures: 5 total 
(Custom Enchantments: 3, Version Issues: 1, Other: 1)
⚠ If you see custom enchantment failures, ensure enchantment plugins 
(e.g., ExcellentEnchants) are loaded and all enchantments are registered.

⚠️ Important Notes / Wichtige Hinweise

• EN: Database Upgrade: On first start after update, columns are automatically upgraded DE: Datenbank-Upgrade: Beim ersten Start nach dem Update werden die Spalten automatisch geupgradet
• EN: Custom Enchantments: Ensure enchantment plugins (e.g., ExcellentEnchants) are installed and active on both servers DE: Custom-Enchantments: Stellen Sie sicher, dass Enchantment-Plugins (z.B. ExcellentEnchants) auf beiden Servern installiert und aktiv sind
• EN: Plugin Load Order: Enchantment plugins should load before PlayerDataSync (check plugin.yml) DE: Plugin-Load-Reihenfolge: Enchantment-Plugins sollten vor PlayerDataSync geladen werden (in plugin.yml prüfen)
• EN: EditorIntegration: EditorIntegration has been removed and will be re-implemented in a future version DE: EditorIntegration: Die EditorIntegration wurde entfernt und wird in einer zukünftigen Version neu implementiert

📝 Migration Guide

EN: For Existing Installations:

DE: Für bestehende Installationen:

1. EN: Automatic Upgrade: No manual action needed - plugin performs upgrade automatically DE: Automatisches Upgrade: Keine manuelle Aktion nötig - das Plugin führt das Upgrade automatisch durch
2. EN: Restart Server: Restart server after update to perform database upgrade DE: Server neu starten: Nach dem Update den Server neu starten, damit das Datenbank-Upgrade durchgeführt wird
3. EN: Check Logs: Verify logs for upgrade messages: DE: Logs prüfen: Überprüfen Sie die Logs auf Upgrade-Meldungen:

   [INFO] Upgraded inventory column from TEXT to LONGTEXT to support large inventories
   [INFO] Upgraded enderchest column from TEXT to LONGTEXT to support large inventories
   [INFO] Upgraded armor column from TEXT to LONGTEXT to support large inventories
   [INFO] Upgraded offhand column from TEXT to LONGTEXT to support large inventories
   

4. EN: Check Custom Enchantments: Ensure all enchantment plugins are loaded correctly DE: Custom-Enchantments prüfen: Stellen Sie sicher, dass alle Enchantment-Plugins korrekt geladen sind

EN: Troubleshooting:

DE: Bei Problemen:

• EN: Check /sync cache for deserialization statistics DE: Prüfen Sie /sync cache für Deserialisierungs-Statistiken
• EN: Review logs for custom enchantment errors DE: Überprüfen Sie die Logs auf Custom-Enchantment-Fehler
• EN: Ensure enchantment plugins are installed on both servers DE: Stellen Sie sicher, dass Enchantment-Plugins auf beiden Servern installiert sind
• EN: Check plugin load order in plugin.yml DE: Prüfen Sie die Plugin-Load-Reihenfolge in plugin.yml

---

[1.2.7-RELEASE] - 2026-01-03

🔧 Critical Fixes & New Features

This release includes critical bug fixes for XP synchronization and Vault economy, plus a new Respawn to Lobby feature.

Fixed

• Issue #45 - XP & Level Synchronization (Critical Fix): Complete rewrite of experience synchronization
  • ✅ Replaced unreliable setTotalExperience() with giveExp() as primary method
  • ✅ giveExp() is more reliable across all Minecraft versions (1.8-1.21.11)
  • ✅ Better error handling and verification with detailed logging
  • ✅ Automatic correction if experience doesn't match expected value
  • ✅ Prevents XP sync failures on all supported versions
  • ✅ Improved level calculation and synchronization
  • 🔧 Fixes Issue #43, #45 and XP sync problems across version range
  • 📝 Detailed logging for debugging XP sync issues
• Issue #46 - Vault Balance de-sync on server shutdown: Fixed economy balance not being saved during shutdown
  • ✅ Enhanced shutdown save process to ensure Vault economy is available
  • ✅ Reconfigure economy integration before shutdown save
  • ✅ Added delay to ensure Vault is fully initialized before saving
  • ✅ Force balance refresh before save to get latest balance
  • ✅ Better error handling and logging during shutdown
  • ✅ Prevents economy balance loss on server restart
  • 🔧 Fixes Issue #46: Vault Balance de-sync on server shutdown