原创 娱乐 [1.16+] PlayerLockBox 玩家保险箱 - 轻量高效的个人保险箱插件 [支持TACZ] 1.0.0

[MD] ## 一、为什么选择 PlayerLockBox - **为每位玩家提供独立、安全的私人储物空间**，等级随权限成长，权限到期自动降级且不丢物品。 - **高性能、低开销**：为长期运行的服务器量身定制，不会因玩家数量增长而卡服。 - **数据完全本地化**：默认本地文件存储，可选 SQLite；不依赖任何外部服务。 - **安全可控**：黑名单、世界限制、权限驱动等级、防刷机制一应俱全。 - **支持模组物品**：完整NBT序列化存储，支持模组物品（包括TACZ）。 - **可热重载**：配置修改无需重启服务器。 --- ## 二、玩家视角速览 - 输入 `/playerlockbox` 打开**功能菜单**，可预览各等级并升级。 - 输入 `/playerlockbox open` 打开**保险箱**存放物品。 - 也可**潜行 + 快速双击副手键（F）**直接打开保险箱（需服务器开启）。 - 关闭保险箱界面即自动保存，下次打开物品原样保留。 ### 保险箱界面与存放规则 - 保险箱以 **3×3 物品区**呈现：已解锁的格子放你的物品；**未解锁的格子显示红色“未解锁”板**，不能存放；其余区域为黑色封边装饰，不可交互。 - 你可以自由在已解锁格内存取物品；**拖拽整理仅限于已解锁区域**，放入其他区域会被自动退回。 - 某些特殊物品（见“物品黑名单”）无法存入。 - 当保险箱处于**溢出模式**时，不能存入新物品，只能先取出多出的物品。 - 关闭界面即自动保存。 [/MD][MD] --- ## 三、等级与升级 共有 6 个等级，由小到大如下： | 等级 | 名称 | 物品格数 | 解锁权限节点 | 默认拥有 | |------|------|---------|-------------|---------| | 1x1 | 默认保险箱 | 1 | `playerlockbox.type.1x1` | ✅ 是 | | 1x2 | 轻型保险箱 | 2 | `playerlockbox.type.1x2` | ❌ 否 | | 1x3 | 小型保险箱 | 3 | `playerlockbox.type.1x3` | ❌ 否 | | 2x2 | 中型保险箱 | 4 | `playerlockbox.type.2x2` | ❌ 否 | | 2x3 | 大型保险箱 | 6 | `playerlockbox.type.2x3` | ❌ 否 | | 3x3 | 超大型保险箱 | 9 | `playerlockbox.type.3x3` | ❌ 否 | **如何升级** - 在功能菜单中，点击各等级图标可**预览**其可用空间（亮起为可用、灰色为不可用）；点击中间的**升级按钮**即可升级。 - 升级通常**逐级进行**；若你已拥有更高级权限，可一次升到当前可用的最高等级。 - 也可直接用 `/playerlockbox upgrade` 命令升级。 - 已是最高的等级时会提示“你已拥有最高规格”。 **权限到期与降级** - 插件会在玩家**上线、打开保险箱时、以及按配置定时**检查你的等级权限。 - 若当前等级权限已失效，会自动降级到仍可用的最高等级，并播放降级提示音。 - 降级后超出新等级容量的物品会进入**溢出模式**（见下文），不会丢失。 [/MD][MD] --- ## 四、溢出模式 当你的保险箱被降级、而原有物品超过新等级容量时： - 多出的物品进入**溢出暂存**，显示在保险箱的空闲格中，**只允许取出、不能再存入**。 - 取出溢出物品时，对应格子会补上红色“未解锁”板。 - 当你把溢出物品全部取出后，溢出模式结束，提示“溢出物品已取出，保险箱恢复正常”，恢复正常存放。 - 溢出模式下尝试存入新物品会提示“保险箱处于溢出模式，请取出多余物品”。 --- ## 五、技术优越性 ### 1. O(1) 事件识别，无实例登记表 保险箱界面使用原版箱子类型创建，Bukkit 会原样保留界面持有者（Holder）。事件监听仅通过一次 `getHolder() instanceof StorageHolder` 类型判断即可识别，**完全不需要任何“打开界面登记表”查询**。无论服务器在线多少人，单次点击处理都是常数级开销。 ### 2. 单一真相源（Single Source of Truth） 所有玩家保险箱数据统一经由内存缓存（`PlayerDataCache`）读写，它是运行时唯一权威数据源。界面只是缓存的“视图”，关闭界面时再同步回写。这样避免了多份数据相互覆盖的经典并发 bug。 ### 3. 异步落盘，主线程零阻塞 - 玩家加入时，**数据加载在异步线程完成**，不卡主线程。 - 关闭/退出保险箱时，**界面数据先同步写入内存缓存，再由异步任务写入存储后端**（YAML/SQLite），磁盘 I/O 不会拖慢游戏 tick。 - 权限定时检查、数据保存同样走异步，保障服务器流畅。 ### 4. 占位保护靠“事件取消”，而非定时任务 保险箱里的封边、未解锁格、溢出格的保护，全部由**点击事件取消（cancel）**在事件内同步完成；占位板的视觉补位延迟到下一 tick 复原。这意味着： - **没有任何每 tick 扫描的定时任务**； - **没有任何可被利用的跨 tick 空窗**； - 性能开销极低，且杜绝了“趁补位间隙作弊”的可能。 ### 5. 资源友好，仅一个可选定时任务 插件运行时几乎零常驻开销。唯一可选的定时任务是“权限定期检查”（可在配置中设为 0 关闭）。相比之下，多数同类插件会常驻扫描界面或背包，PlayerLockBox 没有这类负担。 ### 6. 并发安全 在线界面与缓存均使用并发安全的集合管理，支持大量玩家同时上下线与同时开关保险箱，不会出现状态错乱。 --- ## 六、本地持久化（数据安全核心） 这是本插件最重要的运维优势之一：**所有玩家数据保存在你自己的服务器上，不依赖任何外部服务。** ### 存储后端 通过统一的存储抽象层支持两种本地后端，配置项 `storage.type` 切换： | 类型 | 说明 | 适用场景 | |------|------|----------| | `yaml` | 默认。每位玩家一个本地 YAML 文件 | 中小服、易查看/备份 | | `sqlite` | 本地嵌入式数据库文件 | 大数据量、单文件管理 | 两者都是**服务器本地文件**，断网、外部数据库宕机都不影响保险箱基础功能——玩家数据永远在你手里。 ### 数据迁移 内置数据迁移器，可在 YAML 与 SQLite 之间搬迁历史数据，运维切换后端无需丢失玩家物品。 ### 防丢失机制 - **关闭即保存**：玩家关闭保险箱界面时自动回写。 - **退出/重载兜底**：玩家退出或服务器重载时，对仍打开的保险箱做兜底保存并清理登记，防止事件未触发导致的数据丢失或内存泄漏。 - **降级不丢物**：权限到期导致等级下降时，超出容量的物品进入溢出暂存，玩家可随时取出，绝不直接删除。 ### 备份友好 由于是本地文件（YAML 或单个 SQLite 文件），直接用服务器备份工具定期打包即可，无需额外导出流程。 --- ## 七、管理与安全能力一览 | 能力 | 说明 | |------|------| | 等级权限驱动 | 6 级保险箱由权限节点解锁，权限到期自动降级 | | 溢出暂存 | 降级时多出的物品安全暂存、仅可取出 | | 物品黑名单 | 按 Lore 关键词拦截特殊物品（如任务物品、不可交易）入库 | | 世界限制 | 可分别限制菜单与保险箱允许开启的世界 | | 打开冷却 | 可配置倒计时，且移动会取消，防止脚本/瞬开滥用 | | 快捷开启 | 潜行+双击副手键，可开关 | | 管理员命令 | 查看/清空他人保险箱、热重载配置 | | 权限检查 | 上线 / 打开 / 定时 三处校验，保证等级与权限一致 | --- ## 八、管理员命令 管理员需 `playerlockbox.admin` 权限（默认 OP）。以下命令用于运维玩家保险箱： ### /playerlockbox admin open <玩家> - 以管理员身份**打开目标玩家的保险箱**（目标玩家需在线）。 - 打开后你可查看其中的物品，并可直接放入/取出；**关闭界面即保存到该玩家数据**。 - 适用场景：协助玩家整理、转移物品，或排查数据问题。 ### /playerlockbox admin delete <玩家> - **清空并重置目标玩家的保险箱数据**（目标需在线）。 - 该操作会移除该玩家所有已存物品与等级状态，恢复为默认 1x1。 - ⚠️ 此操作不可撤销，请谨慎使用。 ### /playerlockbox reload - **重新加载配置文件**（`config.yml` 与消息/音效配置），无需重启服务器。 - 修改配置后执行即可生效。 --- ## 九、权限节点 | 权限节点 | 说明 | 默认 | |----------|------|------| | `playerlockbox.use` | 使用保险箱（打开/升级） | 所有玩家 | | `playerlockbox.type.1x1` | 1x1 等级（默认拥有） | 所有玩家 | | `playerlockbox.type.1x2` | 1x2 等级 | 否 | | `playerlockbox.type.1x3` | 1x3 等级 | 否 | | `playerlockbox.type.2x2` | 2x2 等级 | 否 | | `playerlockbox.type.2x3` | 2x3 等级 | 否 | | `playerlockbox.type.3x3` | 3x3 等级 | 否 | | `playerlockbox.admin` | 管理员（查看/清空他人箱、重载） | OP | | `playerlockbox.bypass.cooldown` | 跳过打开倒计时 | OP | --- QQ交流群：1047445039 （若金粒不够可进群下载） > © 2026 Harry_H2O All rights resevred --- ## bStats  [/MD]