InventoryBackup

插件

· 作者 zfzfg

一个 Minecraft Spigot 插件,可在玩家死亡时自动保存其物品栏,并提供全面的恢复功能。

0 本站下载 0 关注 更新于 1 个月前

最新 0.2.0 · 26.3 · Paper / Purpur

一键开服(送7天)

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. 自动死亡备份(两级缓存)

插件通过智能的两级机制捕获玩家状态:

  1. 伤害检测:当玩家受到使其生命值降至 4 颗心或以下的伤害时,其当前物品栏会在主线程上同步缓存。
  2. 死亡事件:当玩家死亡时,缓存的物品栏快照将异步保存到磁盘。

这确保了即使在瞬时致死伤害(如高空坠落、虚空伤害或即死效果)期间也能准确捕获物品栏。

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:玩家在岩浆/虚空中死亡

  1. 检查玩家的备份:/inv Steve list
  2. 在 GUI 中预览备份物品:/inv Steve show 2026-08-11_14-00-00_death.yml
  3. 恢复完整的背包:/inv Steve restore 2026-08-11_14-00-00_death.yml

场景 2:玩家丢失了部分物品但保留了一些装备

  1. 列出玩家的备份:/inv Alex list
  2. 仅发放缺失的物品:/inv Alex givemissing 2026-08-11_14-00-00_death.yml
  3. Alex 会在其背包中获得所有缺失的物品堆,而不会覆盖当前已装备的装备。

场景 3:恢复离线玩家

  1. 一名玩家在 Discord 上报告离线期间物品丢失。
  2. 管理员执行命令:/inv Steve restore 2026-08-11_14-00-00_death.yml
  3. 插件将恢复任务加入队列:Steve is offline - the restore will run on their next join.
  4. 验证队列状态:/inv Steve pending
  5. 一旦 Steve 登录服务器,其背包会自动恢复。

场景 4:服务器维护 / 活动前快照

  1. 在运行高风险服务器活动或进行维护之前:/inv backup all
  2. 所有在线玩家的精确背包将被快照保存。
  3. 如果出现问题,任何玩家都可以恢复到该精确的活动前状态。

开发者集成

将 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 以获取完整的开发者文档、事件监听器指南和线程规范。


作者与支持

  • 作者: Collin Lerche (zfzfg) | STERRA
  • 网站:
  • 邮箱: zfzfg@sterra.online
  • 许可证: MIT License(见 LICENSE)

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源