InventoryBackup 插件说明
概述
InventoryBackup 是一款功能强大、稳健且安全的 Minecraft Spigot/Paper 插件,旨在玩家死亡时自动归档其物品栏,并提供全面、灵活的恢复功能。该插件专为服务器管理员和开发者设计,提供了一套完整的生产就绪解决方案,包含丰富的开发者 API、离线玩家恢复支持、基于 UUID 的存储、多语言支持(英语和德语)以及防复制的物品栏预览功能。
- Modrinth 项目:
- 开发者 API 制品:
com.zfzfg:InventoryBackup-API:0.1.0
- 支持平台: Minecraft 1.20+ (Spigot / Paper / Purpur) & Java 17+
为什么使用 InventoryBackup?
?️ 保护玩家的进度
玩家投入无数时间收集装备、稀有附魔和建筑资源。意外的死亡、虚空坠落、服务器故障或误触消失机制可能会抹去数小时的辛勤工作。InventoryBackup 确保没有任何玩家会永久丢失其物品栏。
⚡ 轻松实现离线恢复
针对离线玩家执行恢复或缺失物品命令时,会自动将其排队至 pending-restores.yml。当玩家下次加入服务器时,排队的恢复操作将在第一时间安全执行——即使经历服务器重启或网络断开也无需任何手动跟进。
? 原生多语言支持 (i18n)
所有玩家和控制台消息均已完全本地化为英语 (en) 和德语 (de)。通过 /inv lang de 或 /inv lang en 即可在运行时即时切换语言,无需重启服务器。自定义翻译使用专用的消息文件,对于缺失的键值会自动回退到英语。
? 一流的开发者 API 与事件
直接集成到任务、小游戏、竞技场或自定义死亡系统中。简洁的 API 模块提供异步 Future,直接在主线程上完成,并附带五个自定义 Bukkit 事件(包括可取消的前置事件),以定制或否决任何备份和恢复操作。
? 企业级安全性与性能
防止路径遍历攻击、竞态条件、内存泄漏和 GUI 物品复制漏洞。备份时间戳直接从文件名解析以优化清理循环,文件 I/O 操作异步运行以确保零服务器 Tick 延迟。
主要功能
1. 自动死亡备份(两级缓存)
插件通过智能的两级机制捕获玩家状态:
- 伤害检测:当玩家受到使其生命值降至 4 颗心或以下的伤害时,其当前物品栏会在主线程上同步缓存。
- 死亡事件:当玩家死亡时,缓存的物品栏快照将异步保存到磁盘。
这确保了即使在瞬时致死伤害(如高空坠落、虚空伤害或即死效果)期间也能准确捕获物品栏。
2. 离线玩家恢复与加入队列
- 针对离线玩家的恢复操作会自动排队存储在
pending-restores.yml 中。
- 当玩家加入时,排队的恢复操作会在 1 Tick 延迟后应用,以防止其他登录监听器覆盖已恢复的物品栏。
- 使用
/inv <player> pending 检查排队的恢复操作,并使用 /inv <player> cancelpending 取消它们。
- 可配置的过期时间 (
pending-restore-expiry-days,默认 30 天) 会自动清除过期的排队条目。
3. 灵活的恢复与检查模式
- 完整恢复:用存档的备份完全替换玩家当前的物品栏、盔甲、副手、等级和经验值 (
/inv <player> restore <filename>)。
- 仅缺失物品:将备份与玩家当前持有的物品进行比较,仅归还他们缺少的物品,而不会清除他们当前的物品栏 (
/inv <player> givemissing <filename>)。
- 受保护的 GUI 预览:在交互式 GUI 窗口中检查任何备份的确切内容 (
/inv <player> show <filename>)。查看者无法从预览 GUI 中拖拽、点击或复制物品。
4. 基于 UUID 的存储与即时名称索引
- 备份存储在
plugins/InventoryBackup/inventories/<UUID>/ 下,以确保当玩家更改 Minecraft 用户名时,玩家历史记录永远不会丢失或孤立。
- 文件名格式为
<yyyy-MM-dd_HH-mm-ss>_<type>.yml(例如 2026-08-11_15-30-45_death.yml)。
- 通过
names.yml 进行快速、本地的名称到 UUID 查找,消除了在执行命令和 Tab 补全时对 Mojang API 的阻塞式 Web 请求。
- 服务器启动时无缝自动迁移旧版文件夹结构。
5. 多语言与翻译包
- 所有玩家消息、GUI 标题、列表条目和控制台日志的完整翻译。
- 消息包:
messages_en.yml(英语回退主文件)和 messages_de.yml(德语)。
- 即时切换语言:
/inv lang de 或 /inv lang en。
- 随时重新加载配置和包:
/inv reload。
- 全程支持颜色代码 (
&) 和动态占位符 ({player}, {file}, {count}, {level}, {type} 等)。
6. 开发者 API 与自定义事件
- 独立的 API 制品
com.zfzfg:InventoryBackup-API,用于通过 InventoryBackupProvider.get() 进行第三方插件集成。
- 非阻塞的
CompletableFuture,在 Bukkit 主线程上完成。
- 插件 JAR 中包含的自定义 Bukkit 事件:
BackupCreateEvent(可取消;修改类型或附加自定义元数据)
BackupCreatedEvent(备份保存后触发)
InventoryRestoreEvent(可取消;检查或过滤恢复的物品)
InventoryRestoredEvent(恢复应用后触发)
BackupDeletedEvent(带有原因 API、COMMAND 或 EXPIRED 时触发)
- 自由形式的备份类型(例如
quest, pvp, admin, checkpoint)和任意字符串键值元数据。
7. 自动化维护与清理
- 自动删除超过可配置天数(
auto-delete-days: 30)的备份。
- 后台清理任务按可配置间隔运行(
cleanup-interval-hours: 24)。
- 直接从文件名提取时间戳,无需进行繁重的 YAML 解析。
8. Modrinth 更新检查器
- 通过 Modrinth v2 API (
rpKY25cW) 在服务器启动时执行后台更新检查。
- 管理员加入时缓存更新通知(零登录网络延迟)。
- 通过
/inv version 手动按需检查,提供实时反馈和直接下载链接。
命令参考
基础命令为 /inv,别名包括 /inventory 和 /invbackup。
| 命令 |
描述 |
权限 |
/inv backup all |
为所有在线玩家创建手动备份 |
inventorybackup.backup |
/inv backup <player> |
为特定在线玩家创建手动备份 |
inventorybackup.backup |
/inv <player> restore <filename> |
恢复背包(立即应用或排队等待离线玩家) |
inventorybackup.restore |
/inv <player> show <filename> |
打开只读 GUI 预览已保存的备份 |
inventorybackup.show |
/inv <player> givemissing <filename> |
仅向在线玩家发放缺失的物品 |
inventorybackup.givemissing |
/inv <player> list |
列出玩家的所有备份及其类型 |
inventorybackup.show |
/inv <player> delete <filename> |
删除特定备份文件 |
inventorybackup.restore |
/inv <player> delete all |
删除特定玩家的所有备份 |
inventorybackup.restore |
/inv <player> pending |
查看为离线玩家排队的恢复任务 |
inventorybackup.pending |
/inv <player> cancelpending |
取消已排队的离线恢复任务 |
inventorybackup.pending |
/inv version |
检查 Modrinth 上的更新并显示版本信息 |
inventorybackup.use |
/inv lang |
显示当前激活的语言 |
inventorybackup.lang |
/inv lang <en|de> |
切换语言并即时重载消息包 |
inventorybackup.lang |
/inv reload |
重载 config.yml 和活动的消息包 |
inventorybackup.reload |
ℹ️ Tab 补全: 支持子命令、操作、在线及已知离线玩家、语言代码以及现有备份文件名的完整 Tab 补全。
权限
所有权限默认仅限服务器操作员(op):
| 权限 |
描述 |
默认值 |
inventorybackup.use |
访问基础 /inv 命令及 /inv version |
OP |
inventorybackup.restore |
恢复备份并删除单个或全部备份 |
OP |
inventorybackup.show |
打开 GUI 预览(show)及查看备份列表(list) |
OP |
inventorybackup.givemissing |
仅向玩家移交缺失的物品 |
OP |
inventorybackup.backup |
为单个玩家或所有在线玩家创建手动备份 |
OP |
inventorybackup.pending |
查看和取消离线玩家的排队恢复任务 |
OP |
inventorybackup.notify |
在保存备份时接收聊天通知 |
OP |
inventorybackup.update.notify |
加入服务器时接收更新通知消息 |
OP |
inventorybackup.lang |
查看和切换消息语言 |
OP |
inventorybackup.reload |
重载插件配置和消息包 |
OP |
配置
默认的 config.yml 提供了对所有功能的清晰、细粒度控制:
# 所有插件和控制台消息的语言:"en" (English) 或 "de" (German)。
# 消息文本位于与此文件同级的 messages_<language>.yml 中。
language: "en"
# 自动删除前保留物品栏文件的天数(0 = 禁用)
auto-delete-days: 30
# 文件清理的检查间隔(小时)
cleanup-interval-hours: 24
# 玩家死亡时自动保存物品栏
save-on-death: true
# 性能设置:伤害缓存清理间隔(秒)
cache-cleanup-interval: 30
# 未应用的离线恢复任务的保留期(天)(0 = 永久)
pending-restore-expiry-days: 30
# 通知设置
notify-on-backup: true
notify-ops-only: true
# 更新检查 (Modrinth)
update-check:
enabled: true # 总开关
check-on-startup: true # 服务器启动时获取
notify-admins-on-join: true # 管理员加入时在聊天中通知
modrinth-project-id: "rpKY25cW"
contact: "zfzfg@sterra.online" # 包含在 User-Agent 头中
stable-only: true # 忽略预发布版本
startup-delay-ticks: 20 # 启动检查延迟(20 tick = 1 秒)
语言包 (messages_en.yml, messages_de.yml)
消息文本与 config.yml 解耦。自定义消息只需编辑 messages_en.yml 或 messages_de.yml 并运行 /inv reload 即可。任何缺失的翻译键会自动回退到英文默认值,而不会导致插件执行中断。
文件结构
plugins/InventoryBackup/
├── config.yml <- 主插件设置
├── messages_en.yml <- 英文消息包
├── messages_de.yml <- 德文消息包
├── names.yml <- 玩家姓名 <-> UUID 索引缓存
├── pending-restores.yml <- 离线恢复队列
└── inventories/
└── <owner-uuid>/
├── 2026-08-11_14-00-00_death.yml <- 自动死亡备份
├── 2026-08-11_15-30-00_manual.yml <- 手动 /inv backup
└── 2026-08-11_16-45-00_quest.yml <- 带有自定义类型的 API 备份
常见管理员场景
场景 1:玩家在岩浆/虚空中死亡
- 检查玩家的备份:
/inv Steve list
- 在 GUI 中预览备份物品:
/inv Steve show 2026-08-11_14-00-00_death.yml
- 恢复完整的背包:
/inv Steve restore 2026-08-11_14-00-00_death.yml
场景 2:玩家丢失了部分物品但保留了一些装备
- 列出玩家的备份:
/inv Alex list
- 仅发放缺失的物品:
/inv Alex givemissing 2026-08-11_14-00-00_death.yml
- Alex 会在其背包中获得所有缺失的物品堆,而不会覆盖当前已装备的装备。
场景 3:恢复离线玩家
- 一名玩家在 Discord 上报告离线期间物品丢失。
- 管理员执行命令:
/inv Steve restore 2026-08-11_14-00-00_death.yml
- 插件将恢复任务加入队列:
Steve is offline - the restore will run on their next join.
- 验证队列状态:
/inv Steve pending
- 一旦 Steve 登录服务器,其背包会自动恢复。
场景 4:服务器维护 / 活动前快照
- 在运行高风险服务器活动或进行维护之前:
/inv backup all
- 所有在线玩家的精确背包将被快照保存。
- 如果出现问题,任何玩家都可以恢复到该精确的活动前状态。
开发者集成
将 API 依赖项添加到您的 pom.xml 中:
<dependency>
<groupId>com.zfzfg</groupId>
<artifactId>InventoryBackup-API</artifactId>
<version>0.1.0</version>
<scope>provided</scope>
</dependency>
快速代码示例
import com.zfzfg.inventorybackup.api.*;
// 获取 API 实例
InventoryBackupAPI api = InventoryBackupProvider.get();
// 在自定义小游戏/任务之前创建快照
api.createBackup(player, BackupRequest.builder()
.type("dungeon")
.sourcePlugin(this)
.metadata("dungeon-id", "shadow-crypt")
.build())
.thenAccept(optHandle -> optHandle.ifPresent(handle -> {
getLogger().info("Saved backup " + handle.id() + " for " + player.getName());
}));
请参阅 API.md 以获取完整的开发者文档、事件监听器指南和线程规范。
作者与支持
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:
- 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:
- 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.
- 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 reload.
- Color codes (
&) and dynamic placeholders ({player}, {file}, {count}, {level}, {type}, etc.) supported throughout.
6. Developer API & Custom Events
- Standalone API artifact
com.zfzfg:InventoryBackup-API for third-party plugin integration via InventoryBackupProvider.get().
- Non-blocking
CompletableFutures completing on the Bukkit main thread.
- Custom Bukkit events included in the plugin JAR:
BackupCreateEvent (Cancellable; modify type or attach custom metadata)
BackupCreatedEvent (Fired after backup is saved)
InventoryRestoreEvent (Cancellable; inspect or filter restored items)
InventoryRestoredEvent (Fired after restore is applied)
BackupDeletedEvent (Fired with reason API, COMMAND, or EXPIRED)
- Free-form backup types (e.g.,
quest, pvp, admin, checkpoint) and arbitrary string key/value metadata.
7. Automated Maintenance & Cleanup
- Automatic deletion of backups older than a configurable number of days (
auto-delete-days: 30).
- Background cleanup task runs at configurable intervals (
cleanup-interval-hours: 24).
- Fast timestamp extraction directly from filenames without heavy YAML parsing.
8. Modrinth Update Checker
- Background update check on server startup via Modrinth v2 API (
rpKY25cW).
- Cached update notifications for administrators upon joining (zero login network lag).
- Manual on-demand check via
/inv version with live feedback and direct download links.
Command Reference
The base command is /inv, with aliases /inventory and /invbackup.
| Command |
Description |
Permission |
/inv backup all |
Create a manual backup for all online players |
inventorybackup.backup |
/inv backup <player> |
Create a manual backup for a specific online player |
inventorybackup.backup |
/inv <player> restore <filename> |
Restore inventory (applies immediately or queues if offline) |
inventorybackup.restore |
/inv <player> show <filename> |
Open read-only GUI preview of a saved backup |
inventorybackup.show |
/inv <player> givemissing <filename> |
Give only missing items to an online player |
inventorybackup.givemissing |
/inv <player> list |
List all backups and their types for a player |
inventorybackup.show |
/inv <player> delete <filename> |
Delete a specific backup file |
inventorybackup.restore |
/inv <player> delete all |
Delete all backups for a specific player |
inventorybackup.restore |
/inv <player> pending |
View the restore queued for an offline player |
inventorybackup.pending |
/inv <player> cancelpending |
Cancel a queued offline restore |
inventorybackup.pending |
/inv version |
Check Modrinth for updates and display version info |
inventorybackup.use |
/inv lang |
Display the currently active language |
inventorybackup.lang |
/inv lang <en|de> |
Switch language and reload message bundles instantly |
inventorybackup.lang |
/inv reload |
Reload config.yml and active message bundle |
inventorybackup.reload |
ℹ️ Tab Completion: Full tab completion is supported for subcommands, actions, online and known offline players, language codes, and existing backup filenames.
Permissions
All permissions default to server operators (op):
| Permission |
Description |
Default |
inventorybackup.use |
Access to base /inv command and /inv version |
OP |
inventorybackup.restore |
Restore backups and delete individual or all backups |
OP |
inventorybackup.show |
Open GUI preview (show) and view backup list (list) |
OP |
inventorybackup.givemissing |
Hand over only missing items to a player |
OP |
inventorybackup.backup |
Create manual backups for single players or all online players |
OP |
inventorybackup.pending |
View and cancel queued restores for offline players |
OP |
inventorybackup.notify |
Receive chat notifications when a backup is saved |
OP |
inventorybackup.update.notify |
Receive update notification messages upon joining |
OP |
inventorybackup.lang |
View and switch the message language |
OP |
inventorybackup.reload |
Reload plugin configuration and message bundles |
OP |
Configuration
The default config.yml provides clean, granular control over all features:
# Language for all plugin and console messages: "en" (English) or "de" (German).
# Message texts live in messages_<language>.yml next to this file.
language: "en"
# How many days to keep inventory files before auto-deletion (0 = disabled)
auto-delete-days: 30
# Check interval for file cleanup (in hours)
cleanup-interval-hours: 24
# Save inventory automatically on player death
save-on-death: true
# Performance settings: damage cache cleanup interval (in seconds)
cache-cleanup-interval: 30
# Retention period for unapplied offline restores in days (0 = forever)
pending-restore-expiry-days: 30
# Notification settings
notify-on-backup: true
notify-ops-only: true
# Update check (Modrinth)
update-check:
enabled: true # Master switch
check-on-startup: true # Fetch on server start
notify-admins-on-join: true # Notice in chat when an admin joins
modrinth-project-id: "rpKY25cW"
contact: "zfzfg@sterra.online" # Included in User-Agent header
stable-only: true # Ignore pre-releases
startup-delay-ticks: 20 # Startup check delay (20 ticks = 1 second)
Language Bundles (messages_en.yml, messages_de.yml)
Message texts are decoupled from config.yml. Customizing messages is as simple as editing messages_en.yml or messages_de.yml and running /inv reload. Any missing translation keys automatically fall back to the English defaults without breaking plugin execution.
File Structure
plugins/InventoryBackup/
├── config.yml <- Main plugin settings
├── messages_en.yml <- English message bundle
├── messages_de.yml <- German message bundle
├── names.yml <- Player Name <-> UUID index cache
├── pending-restores.yml <- Offline restores queue
└── inventories/
└── <owner-uuid>/
├── 2026-08-11_14-00-00_death.yml <- Automatic death backup
├── 2026-08-11_15-30-00_manual.yml <- Manual /inv backup
└── 2026-08-11_16-45-00_quest.yml <- API backup with custom type
Common Administrator Scenarios
Scenario 1: Player Died in Lava / Void
- Check the player's backups:
/inv Steve list
- Preview the backup items in the GUI:
/inv Steve show 2026-08-11_14-00-00_death.yml
- Restore the full inventory:
/inv Steve restore 2026-08-11_14-00-00_death.yml
Scenario 2: Player Lost Specific Items but Kept Some Gear
- List the player's backups:
/inv Alex list
- Hand over only the missing items:
/inv Alex givemissing 2026-08-11_14-00-00_death.yml
- Alex receives all missing item stacks in their inventory without overwriting their currently equipped gear.
Scenario 3: Restoring an Offline Player
- A player reports item loss on Discord while offline.
- An admin executes:
/inv Steve restore 2026-08-11_14-00-00_death.yml
- The plugin queues the restore:
Steve is offline - the restore will run on their next join.
- Verify the queue:
/inv Steve pending
- As soon as Steve logs into the server, their inventory is restored automatically.
Scenario 4: Server Maintenance / Pre-Event Snapshot
- Before running a risky server event or maintenance:
/inv backup all
- All online players have their exact inventories snapshotted.
- If an issue occurs, any player can be restored to this exact pre-event state.
Developer Integration
Add the API dependency to your pom.xml:
<dependency>
<groupId>com.zfzfg</groupId>
<artifactId>InventoryBackup-API</artifactId>
<version>0.1.0</version>
<scope>provided</scope>
</dependency>
Quick Code Example
import com.zfzfg.inventorybackup.api.*;
// Obtain API instance
InventoryBackupAPI api = InventoryBackupProvider.get();
// Create a snapshot before a custom minigame / quest
api.createBackup(player, BackupRequest.builder()
.type("dungeon")
.sourcePlugin(this)
.metadata("dungeon-id", "shadow-crypt")
.build())
.thenAccept(optHandle -> optHandle.ifPresent(handle -> {
getLogger().info("Saved backup " + handle.id() + " for " + player.getName());
}));
See API.md for full developer documentation, event listener guides, and threading specifications.
Author & Support
- Author: Collin Lerche (zfzfg) | STERRA
- Website:
- Email: zfzfg@sterra.online
- License: MIT License (see LICENSE)
评论 0
登录后参与评分
还没有评论,来抢沙发吧