原创 开源 Deltaloot 搜刮箱插件 Paper 1.2.3

[MD] # DeltaLoot 1.2.3 适用于 **Paper 1.21.11 / Java 21** 的类三角洲搜刮箱插件。基础搜刮功能无需其他插件；搜索中的自定义图标从 CraftEngine 的 `default:search_mask` 读取，显示其模型需要玩家加载对应资源包。打开箱子后自动逐格识别物资，品质越高默认耗时越长；物品逐个揭示后点击领取整组，可以边搜索边取物。 这是独立的搜刮箱玩法插件，不包含枪械、撤离、战局匹配、经济出售或物品多格占位系统。 ## 安装与第一次使用 1. 将 `DeltaLoot-1.2.3.jar` 放到服务器的 `plugins` 文件夹，启动或正常重启 Paper 1.21.11。 2. 使用 OP 账号放置一个**空单箱、空陷阱箱或空木桶**，在 6 格内看向它。 3. 执行 `/dl create test civilian`。 4. 右键箱子后自动开始搜索，无需点击黑色玻璃格。左键或右键点击已揭示的真实物品领取。 5. 想立即测试一轮新物资，执行 `/dl reset test`，再打开箱子。 不能绑定大箱子、已有物品、正在被查看、带原版战利品表的容器。箱子 ID 区分大小写，仅接受 1–40 位小写字母、数字、`_`、`-`；`all` 为保留名称。 ## 已实现玩法 - 界面所有格子均可搜索：默认 4 行共 36 格；没有说明、信息、关闭按钮或底部装饰栏，按 Esc / 背包键关闭。 - 开箱只对有物品的格子自动搜索，从左到右、从上到下逐个识别；没有物品的格子直接留空，不显示玻璃、不占搜索时间。已揭示的格子会被跳过，点击未知格不会改变顺序。 - 不显示顶部进度条、动作栏提示、已搜索数量、百分比或悬停进度条；搜索图标仅显示固定名称“正在搜索”。自动搜索仍有识别时间，品质越高默认耗时越长。 - 未搜索格保持黑色玻璃板，当前格显示 CraftEngine 的 `default:search_mask` 自定义物品；搜索中有轻微节拍音，金色、红色物资揭示时播放独立提示音。 - 搜索确认为空，或物品被取走后，格子直接留空，不显示玻璃或其他占位物品。 - 白、绿、蓝、紫、金、红六档品质；材质、名称、描述、数量、权重与搜索时长均可修改。 - 三个示例掉落表：`civilian` 民用物资箱、`military` 军用补给箱、`medical` 医疗补给箱。 - 同一箱子同一轮的物资与揭示状态**全服共享**，同一时刻只有一人可以打开；其他人会收到占用提示。 - 关闭、离开有效距离、传送、死亡、退出会结束当前会话。重新打开后自动从第一个未揭示格继续，本格计时从零开始；已揭示的格子保留。默认受到实际伤害会打断本格，1 秒未再受伤后自动继续，窗口保留。 - 领取只使用普通背包储存格，不占用盔甲或副手格。背包装不下整组时不发放，物品留在箱中。 - GUI 中禁止拖拽、Shift 转移、数字键交换、双击收集、丢弃与创造模式复制；物品只通过点击已揭示格领取，不会自动塞入背包。 - 实体容器防破坏、防爆炸、防活塞、防合并大箱；拦截漏斗搬运与铜傀儡访问。解绑后恢复普通容器用途。 ## CraftEngine 搜索图标 在服务器安装并启用 CraftEngine，确保已注册 `default:search_mask`，并向玩家提供包含该物品模型的资源包。此插件使用现有物品定义，不创建或覆盖 CraftEngine 的配置和贴图。 每次开箱时从 CraftEngine 读取物品，克隆完整 ItemStack，保留模型数据、CustomModelData 与自定义数据；搜索时设置固定名称“正在搜索”、清空说明并将数量设为 1。它仅存在于界面，不会作为战利品发放。CraftEngine 重载物品后，重新打开箱子即可获取新图标。 CraftEngine 未启用、物品不存在或 API 不兼容时，控制台输出一次警告并使用黑色玻璃板作为搜索图标，仍可正常搜索，不再显示时钟。修复后下次开箱会重新尝试读取。 适配参考：[CraftEngine API 文档](https://xiao-momi.github.io/craft-engine-wiki/api/)。通过软依赖保证加载顺序，物品在实际开箱时解析；适配旧接口 `buildItemStack()` 与新接口 `buildBukkitItem()`，未在真实 CraftEngine 服务端执行联机测试。 ## 管理命令 主命令 `/deltaloot`，简写 `/dl`，支持 Tab 补全。 | 命令 | 作用 | | --- | --- | | `/dl create <ID> [掉落表]` | 绑定所看空容器；省略掉落表时为 `civilian` | | `/dl info [ID]` | 查看箱子信息和刷新时间 | | `/dl reset [ID]` | 关闭对应窗口、清除当前轮次，下次打开重新抽取 | | `/dl reset all` | 重置所有搜刮箱 | | `/dl remove [ID]` | 解绑并删除该箱剩余虚拟物资；实体方块保留 | | `/dl list` | 列出箱子，最多显示前 50 个 | | `/dl tables` | 列出所有掉落表 | | `/dl reload` | 严格校验并重新读取配置，关闭正在打开的搜刮界面 | `info`、`reset`、`remove` 省略 ID 时作用于玩家看向的箱子。控制台必须指定 ID。`reset` 和 `remove` 立即生效，无二次确认。 | 权限 | 默认值 | | --- | --- | | `deltaloot.use` | 所有玩家可用 | | `deltaloot.admin` | 仅 OP | ## 随机与刷新规则 第一次打开时，按掉落表的 `min-rolls` 到 `max-rolls` 抽取次数生成本轮物资，并随机放入可搜索格子。每次抽取先按 `empty-chance` 判定是否为空，否则按条目 `weight` 加权抽取；**允许重复条目**。落空或未被抽中的格子直接留空，自动搜索会立即跳过它们。整箱没有物品时直接显示空界面，不启动搜索。 `weight` 是相对权重，不是百分比。例如权重 10 和 30 在同一非空抽取中的概率为 25% 和 75%。配置名称或品质不会赋予额外属性；默认“医疗物品”依然是其原版材质对应的用途。 刷新倒计时从本轮首次生成时开始，以现实时间计算，服务器停机期间也会经过时间。**到期且没有人打开时，下一次打开才重新生成**；有人打开的旧界面不会在操作中途刷新。到期刷新会丢弃上一轮未领取物资。`reset` 可立即结束旧轮次。 ## 配置 首次启用生成 `plugins/DeltaLoot/config.yml`。完整中文示例见源码 `src/main/resources/config.yml`。简化结构如下： ```yaml gui: rows: 4 # 2–6 行，每行 9 格全部可搜索 search: max-distance: 5.0 # 从玩家脚部到箱子中心，1–16 格 cancel-on-damage: true loot-tables: civilian: title: "民用物资箱" min-rolls: 3 max-rolls: 8 refresh-seconds: 300 # 1–604800 秒 empty-chance: 0.15 # 0–1；每次抽取为空的概率 entries: supply: material: IRON_INGOT min-amount: 1 max-amount: 4 weight: 30 rarity-name: "精良" rarity-color: blue search-seconds: 2.0 # 0.1–3600 秒，按 20 TPS 换算 tick name: "工业零件" lore: - "从废弃设施中找到的金属部件" ``` 每张表至少包含一个条目，`max-rolls` 不能超过 `rows × 9`。物品数量不能超过材质本身的最大堆叠数。`rarity-color` 接受 Adventure 命名颜色，例如 `white`、`green`、`blue`、`light_purple`、`gold`、`red`。名称与描述为纯文本，不解析 `&` 色码或 MiniMessage。 修改后执行 `/dl reload`。坏配置会报错并继续保留旧配置；已生成的战利品、已揭示状态、搜索时间和本轮截止时间仍保留，新的掉落设置在下一轮生效。增加 GUI 行数会在下次打开时补充空白格；减少行数在下一轮生效，避免删除已有物资。不能删除仍被已绑定箱子引用的掉落表；先解绑这些箱子。距离与受伤中断设置重载后立即生效。 ## 从旧版本升级 停服后移除旧版本 JAR，放入 `DeltaLoot-1.2.3.jar`，保留 `plugins/DeltaLoot` 目录，再启动服务器。无需删除配置或箱子数据。原来 4 行界面的 27 个搜索格会保留原物资及状态，原功能栏的 9 格补为空白格；下一次刷新时，战利品会随机分布在全部 36 格中。可执行 `/dl reset all` 立即开始新一轮。 新版 `gui.rows` 表示纯搜索区域行数，任何位置都可以随机生成物资。搜索期间不再显示任何进度条或百分比，已揭示物资和存档继续保留。 从 1.1.x 升级也无需删除配置；自动搜索默认生效。已经全部搜索完的旧箱子会保持完成状态，到期刷新后才有新物资，或用 `/dl reset all` 立即开始新一轮。反复开关同一箱子不会重抽战利品。 ## 保存与运维 `plugins/DeltaLoot/boxes.yml` 保存箱子位置（世界 UUID）、绑定表、物品序列化数据、揭示状态和刷新时间。每次抽取、揭示、领取、绑定、解绑、重置都先写临时文件再替换存档；写入失败时取消变更。正常重启会保留当前轮次，不会仅因重启重新抽取。 领取会先持久化消费状态，再发到背包并保存玩家数据，避免正常操作中的重复领取。箱子文件与玩家文件不是跨文件事务，进程突然被杀、磁盘故障或断电仍可能造成极短窗口内的物资损失；不要把它当作数据库级事务保障。建议正常停服并备份世界玩家数据与 `DeltaLoot` 文件夹。 已有存档损坏会阻止插件启用，原文件不会被覆盖；请根据控制台错误修复或恢复备份。运行时不要手工修改 `boxes.yml`，修改不会自动热读，后续保存还会覆盖它。世界 UUID 改变时需重新绑定。插件停用或被移除后实体容器恢复普通用途。 保存目前在服务器主线程同步进行，适合中小规模部署；大量箱子与高并发使用前需在自己的服上压测。这里只使用 Paper API，不使用 NMS 或数据包拦截。不支持 Folia。其他插件、WorldEdit 或管理员命令直接改方块/库存不在保护范围内；领地插件兼容性仍需在实际组合中验收。 [/MD]