InventoryBackup

# InventoryBackup Plugin Description ## Overview **InventoryBackup** is a powerful, robust, and secure Minecraft Spigot/Paper plugin designed to automatically archive player inventories upon death and provide comprehensive, flexible restore functionality. Built with server administrators and developers in mind, it offers a complete, production-ready solution featuring a rich Developer API, offline player restores, UUID-based storage, multi-language support (English and German), and dupe-proof inventory previews. - **Modrinth Project:** https://modrinth.com/project/rpKY25cW - **Developer API Artifact:** `com.zfzfg:InventoryBackup-API:0.1.0` - **Supported Platforms:** Minecraft 1.20+ (Spigot / Paper / Purpur) & Java 17+ --- ## Why Use InventoryBackup? ### 🛡️ Protect Your Players' Progress Players invest countless hours gathering gear, rare enchantments, and building resources. Unexpected deaths, void falls, server glitches, or accidental despawns can wipe out hours of hard work. InventoryBackup ensures that no player permanently loses their inventory. ### ⚡ Offline Restores Made Effortless Targeting an offline player with a restore or missing items command queues it automatically into `pending-restores.yml`. The items are safely restored the very next time the player joins the server — surviving server restarts and network disconnects without any manual follow-up required. ### 🌐 Native Multi-Language Support (i18n) All player and console messages are fully localized in English (`en`) and German (`de`). Switch languages on the fly at runtime with `/inv lang de` or `/inv lang en` without restarting the server. Custom translations use dedicated message files with automatic fallback to English for any missing keys. ### 🧩 First-Class Developer API & Events Integrate directly into quests, minigames, arenas, or custom death systems. The clean API module provides asynchronous futures that complete directly on the main thread, accompanied by five custom Bukkit events (including cancellable pre-events) to customize or veto any backup and restore operation. ### 🔒 Enterprise-Grade Security & Performance Protected against path traversal attacks, race conditions, memory leaks, and GUI item-duplication exploits. Backup timestamps are parsed directly from filenames to optimize cleanup loops, and file I/O operations run asynchronously to guarantee zero server tick lag. --- ## Key Features ### 1. Automatic Death Backups (Two-Stage Caching) The plugin captures player state through an intelligent two-stage mechanism: 1. **Damage Detection**: When a player takes damage that brings them to 4 hearts or less, their current inventory is cached synchronously on the main thread. 2. **Death Event**: When the player dies, the cached inventory snapshot is saved to disk asynchronously. This guarantees accurate inventory capture even during instantaneous, one-shot deaths (such as high falls, void damage, or instant-kill effects). ### 2. Offline Player Restores & Join Queue - Restores targeted at offline players are automatically queued in `pending-restores.yml`. - When the player joins, the queued restore is applied with a 1-tick delay to prevent other login listeners from overriding the restored inventory. - Inspect queued restores with `/inv <player> pending` and cancel them with `/inv <player> cancelpending`. - Configurable expiry (`pending-restore-expiry-days`, default 30 days) automatically purges stale pending entries. ### 3. Flexible Restore & Inspection Modes - **Full Restore**: Completely replaces the player's current inventory, armor, offhand, level, and experience with the archived backup (`/inv <player> restore <filename>`). - **Missing Items Only**: Compares the backup against what the player currently holds and gives back only the items they are lacking without wiping their current inventory (`/inv <player> givemissing <filename>`). - **Protected GUI Preview**: Inspect the exact contents of any backup in an interactive GUI window (`/inv <player> show <filename>`). Viewers cannot drag, click, or duplicate items out of the preview GUI. ### 4. UUID-Based Storage & Instant Name Index - Backups are stored in `plugins/InventoryBackup/inventories/<UUID>/` to ensure player history is never lost or orphaned when a player changes their Minecraft name. - File names follow the format `<yyyy-MM-dd_HH-mm-ss>_<type>.yml` (e.g. `2026-08-11_15-30-45_death.yml`). - Fast, local name-to-UUID lookups via `names.yml` eliminate blocking web requests to Mojang APIs during commands and tab completion. - Seamless automatic migration from legacy folder structures on server startup. ### 5. Multi-Language & Translation Bundles - Complete translations for all player messages, GUI titles, list entries, and console logs. - Message bundles: `messages_en.yml` (English fallback master) and `messages_de.yml` (German). - Switch languages on the fly: `/inv lang de` or `/inv lang en`. - Reload configuration and bundles at any time: `/inv reloa