README.md

PlayerInvBackup

中文说明

Paper / Folia 1.21.1+ player backup plugin, PlayerInvBackup stores player inventory, armor, offhand, ender chest, and experience, then provides GUI and command tools for browsing, claiming, exporting, and restoring backups

🔂 Features

• Automatic backups by timer and by player events: join, quit, death, and world change
• Manual self backup, manual target backup, and one-by-one batch backup for all online players
• Backup scope includes inventory storage, hotbar, armor, offhand, ender chest, and experience
• Purpur expanded ender chest support: automatically detects 9-54 ender chest slots and works with six-rows and use-permissions-for-rows
• GUI backup list with pagination, time filters, trigger filters, backup ID search, date/time range search, refresh, and fast page jumps
• GUI backup preview with inventory / ender chest switching, slot claiming, restore confirmation, standalone experience restore, pending delivery, pin toggle, shulker export, and teleport to backup location
• Shulker export for the current preview view, with separate inventory and ender chest exports
• Pending-delivery queue for items that cannot fit into the operator's inventory during claiming
• Pinned backups and notes; pinned backups are listed first and excluded from automatic cleanup
• SHA-256 snapshot verification and pre-restore safety backup before restore
• Incompatible item protection for claiming, exporting, and restoring old or cross-version data
• Audit logs for sensitive operations such as backup, restore, slot claim, pending delivery, pin, note, and shulker export
• Asynchronous GitHub Releases update checker with console and administrator join reminders
• Storage backends: SQLite, Local, MySQL, PostgreSQL, and H2
• Bukkit native GUI and optional ProtocolLib packet GUI with automatic fallback
• Configurable GUI sounds, language files, time filters, retention, queue limits, and shulker box material
• bStats support

🌋 Runtime

• Java 21+
• Paper API 1.21
• Recommended server version: Paper / Folia 1.21.1+
• Optional dependency: ProtocolLib

ProtocolLib is only used for packet GUI mode; if it is not installed, the plugin still works and falls back to Bukkit native GUI automatically

🖥️ Server Support

Server	Support
Paper 1.21.1+	✅ Supported
Folia 1.21.1+	✅ Supported
Leaf 1.21.1+	✅ Supported
Purpur 1.21.1+	✅ Supported
Pufferfish 1.21.1+	✅ Supported
Spigot	❌ Not supported
CraftBukkit	❌ Not supported

Other server forks have not been fully tested, please evaluate and test them yourself

📦 Installation

Download: GitHub Releases

• Download the latest PlayerInvBackup.jar from the release Assets
• Confirm the server is running Java 21+ and Paper / Folia 1.21.1+
• Stop the server before replacing or installing the jar
• Put PlayerInvBackup.jar into the server plugins directory
• Optional: install ProtocolLib if you want packet GUI mode
• Start the server once and wait for config.yml, sounds.yml, and lang/ to be generated
• Edit plugins/PlayerInvBackup/config.yml or plugins/PlayerInvBackup/sounds.yml as needed
• Run /pib reload after editing config and language files, or restart the server
• Grant the required playerinvbackup.* permissions to administrators or permission groups

⌨️ Commands

Main command:

• /playerinvbackup
• Aliases: /pib, /invb, /invbackup

Argument convention:

• <> required
• [] optional

Command list:

• /pib
  Permission: none
  Shows plugin information and a clickable help entry
• /pib open [player]
  Permission: playerinvbackup.open
  Opens your own backup list or the specified player's backup list, in-game only
• /pib view [player]
  Permission: playerinvbackup.view for self, plus playerinvbackup.view.others for another player
  Opens a read-only backup list and preview, in-game only
• /pib backup [player]
  Permission: playerinvbackup.self without target, playerinvbackup.backup with target
  Creates a manual backup for yourself or an online target player
• /pib backupall
  Permission: playerinvbackup.backupall
  Creates one batch backup run for all currently online players
• /pib pending
  Permission: playerinvbackup.pending
  Delivers pending items into your inventory, in-game only
• /pib restore <player> <backup id>
  Permission: playerinvbackup.restore
  Restores the backup to the target online player
• /pib list <player> [page]
  Permission: playerinvbackup.list
  Lists backups in chat, 10 records per page
• /pib info <player> <backup id>
  Permission: playerinvbackup.info
  Shows backup metadata, location, SHA-256, claimed slots, pin state, and note
• /pib lock <player> <backup id> [note]
  Permission: playerinvbackup.lock
  Pins a backup and optionally writes a note
• /pib unlock <player> <backup id>
  Permission: playerinvbackup.lock
  Unpins a backup
• /pib note <player> <backup id> [note]
  Permission: playerinvbackup.lock
  Sets or clears a backup note
• /pib status
  Permission: playerinvbackup.status
  Shows runtime status, storage, GUI mode, audit settings, and queue usage
• /pib reload
  Permission: playerinvbackup.reload
  Reloads config and language files
• /pib help
  Permission: playerinvbackup.admin
  Shows command help
• /pib tips
  Permission: playerinvbackup.admin
  Shows usage tips

🔐 Permissions

• playerinvbackup.admin
  Default: op
  Command administration permission, also treated as all command sub-permissions by the plugin permission helper
• playerinvbackup.open
  Default: false
  Open and use the backup GUI
• playerinvbackup.view
  Default: false
  Open a read-only GUI for your own backups
• playerinvbackup.view.others
  Default: false
  Open a read-only GUI for other players' backups, also requires playerinvbackup.view
• playerinvbackup.backup
  Default: false
  Manually back up a specified online player
• playerinvbackup.backupall
  Default: false
  Manually back up all online players
• playerinvbackup.self
  Default: false
  Manually back up yourself
• playerinvbackup.backup.bypass
  Default: false
  Bypass self-backup cooldown
• playerinvbackup.restore
  Default: false
  Restore backups to online players
• playerinvbackup.export
  Default: false
  Export backup preview contents to shulker boxes
• playerinvbackup.teleport
  Default: false
  Run the backup location teleport command from the backup preview GUI
• playerinvbackup.pending
  Default: false
  Deliver pending items into your own inventory
• playerinvbackup.status
  Default: false
  View plugin runtime status
• playerinvbackup.reload
  Default: false
  Reload config and language files
• playerinvbackup.list
  Default: false
  List backups by command
• playerinvbackup.info
  Default: false
  View backup details by command
• playerinvbackup.lock
  Default: false
  Pin, unpin, and edit backup notes
• playerinvbackup.backup.exempt
  Default: false
  Exempt a player from automatic backups by timer and events; grant separately when needed

🛡️ Data Safety

• Backups store a SHA-256 hash and restore verifies the snapshot before applying it
• Restore creates a pre-restore safety backup first; if that safety backup fails, restore is cancelled
• Restoring inventory and ender chest overwrites the target player's current inventory and ender chest
• Standalone experience restore only overwrites the target player's level, total experience, and progress
• Claimed slots are excluded from restore
• Pinned backups and backups with undelivered items are excluded from automatic cleanup
• Incompatible items are blocked or skipped depending on the operation and config

🧾 Audit

Audit records administrator-sensitive operations for later review and troubleshooting

• Records actor, target, backup ID, action type, and operation details
• Covers manual backup, batch backup, restore, slot claim, pending delivery, pin, note, and shulker export
• Can also print audit entries to console
• Supports automatic retention cleanup

🛠️ Build

Windows:

./gradlew.bat clean build

Linux:

./gradlew clean build

Local artifact:

build/libs/PlayerInvBackup.jar

📄 License

This project is licensed under the GNU General Public License version 3, see LICENSE

📊 bStats