战利品仓库 LyLootsWareHouse

MySQL 前置要求

启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则本插件的 MySQL 数据读取、保存、同步和相关记录不会生效，服务器还会阻止玩家在数据库尚未连接时进入。

LyLootsWareHouse 用于把配置内的战利品转换为玩家仓库中的数量数据。玩家可以通过拾取、潜行右键、仓库界面或管理指令存入战利品，再从仓库界面按指定数量取出。

插件适合管理刷怪、副本和材料玩法产生的大量重复物品。符合仓库配置的物品会按照物品 ID 累计，不再长期占用玩家背包空间。

插件信息

项目	内容
插件名	`LyLootsWareHouse`
插件版本	`1.1.2`
作者	`Liyuan`
主命令	`/llwh`
Java 版本	Java 8
Bukkit API	`api-version: 1.13`
构建基准	Paper `1.16.5-R0.1-SNAPSHOT`
默认数据存储	玩家独立 YAML 文件
可选数据存储	MySQL

版本说明

项目确认使用 Paper 1.16.5 API 构建，并声明 Bukkit API 版本为 1.13。代码包含旧版数字材质 ID 与新版英文材质名的兼容处理，但不能据此推断所有 Minecraft 版本均已完成测试。

依赖与兼容

核心功能依赖

插件	用途	说明
`MythicMobs`	默认读取仓库物品模板	未启用其他物品库时，仓库 `item` 列表会从 MythicMobs 读取物品；代码中的掉落接管基于 MythicMobs 4.x 事件接口
`PlaceholderAPI`	仓库变量、界面文本和条件计算	用于注册 `%llwh_...%` 变量、解析 GUI Lore 和处理 `papi:{...}` 条件

可选扩展

插件或物品库	用途	启用方式
`LyMySQLCore`	配合 MySQL 安全加载与保存事件	设置 `mysql.enable: true`，并确保数据库成功连接
`AzureFlow`	从 AzureFlow 读取配置物品	设置 `AzureFlow: true`
`NeigeItems`	从 NeigeItems 读取配置物品	设置 `neigeItems: true`
`SX-Item`	从 SX-Item 读取配置物品	设置 `SX-Item: true`
`GermPlugin`	读取萌芽槽位并处理萌芽 GUI 内的仓库存入	插件存在时自动注册相关监听器

启用 AzureFlow、NeigeItems 或 SX-Item 后，如果指定物品无法从对应物品库读取，代码会继续尝试从 MythicMobs 获取。

玩法说明

管理员在 warehouse 节点下建立一个或多个仓库，并为每个仓库填写标题、开放条件和物品 ID。
玩家获得与配置模板完全匹配的物品后，可以通过已启用的存入方式转为仓库数量。
玩家使用 /llwh open [仓库] 打开 54 格仓库界面，其中前 45 格显示战利品，底部一行用于翻页和填充。
玩家点击仓库物品取出固定数量，或使用鼠标中键进入在线玩家赠送流程。
玩家数据发生变化后，插件按照 auto-save-interval 设置的周期自动保存；玩家退出和插件关闭时也会保存数据。

仓库只处理配置内能够成功加载的物品。拾取、潜行右键和掉落存入时，实际物品必须与加载出的模板物品完整匹配。

主要功能

功能	说明
多仓库分类	`warehouse` 下可建立多个仓库，每个仓库拥有独立标题、条件和物品列表
仓库内分页	每页显示 45 个战利品，槽位 45 和 53 分别作为上一页、下一页按钮
拾取自动存入	开启后，玩家拾取符合条件的仓库物品时会直接增加仓库数量，并移除地面掉落物
潜行右键存入	开启后，玩家潜行并右键时可把主手中的匹配物品全部存入仓库
界面批量存入	仓库界面打开期间，点击背包中的战利品会扫描背包前 36 个槽位，并存入全部相同物品
萌芽槽位存入	可通过管理指令读取 `GermPlugin` 身份槽位中的物品并存入仓库
怪物掉落接管	开启后，可在普通实体死亡掉落和 MythicMobs 战利品事件中优先匹配仓库物品
固定数量取出	支持左键取 1 个、Shift 左键取 10 个、右键取 32 个、Shift 右键取 64 个
指令数量取出	玩家可使用 `dislodge` 子命令取出指定数量的已配置物品
玩家赠送	开启后，中键点击仓库物品可通过聊天输入在线玩家名称和赠送数量
数量管理	管理员可给予、扣除或直接设置在线玩家的指定战利品数量
PlaceholderAPI 变量	可读取当前仓库、当前页数、指定物品数量和仓库槽位对应数量
Java API	提供物品查询、数量读取、设置、增加和扣除接口，支持物品 ID 或匹配函数
Bukkit 事件	存入和取出战利品时会触发对应事件，并提供玩家、物品和操作数量
YAML 存储	默认按玩家名称写入 `playerdata` 目录，并使用临时文件、备份文件和损坏恢复机制降低数据损坏风险
MySQL 存储	可按玩家 UUID 保存战利品数量数据，使用 HikariCP 连接池
自动保存	仅在玩家仓库数据发生变化后执行周期保存，减少无效写入

仓库界面操作

操作	结果
左键点击仓库物品	取出 1 个
Shift + 左键点击仓库物品	取出 10 个
右键点击仓库物品	取出 32 个
Shift + 右键点击仓库物品	取出 64 个
鼠标中键点击仓库物品	在 `trade-enable` 开启时进入赠送流程
点击玩家背包中的仓库物品	存入背包前 36 个槽位内全部相同物品
点击槽位 45	返回上一页
点击槽位 53	前往下一页

取出物品前，玩家背包至少需要存在一个空槽位。仓库数量不足时，本次取出不会执行。

存入来源

来源	控制项	处理方式
玩家拾取地面物品	`pickup-item-to-warehouse`	取消拾取并移除地面实体，数量加入仓库
玩家潜行右键主手物品	`shift-right-save-item`	清空主手物品，数量加入仓库
仓库界面点击背包物品	无独立开关	收集背包前 36 个槽位内全部相同物品
MythicMobs 战利品事件	`mythicmobs-drop-to-warehouse`	匹配成功时直接加入击杀者仓库；不匹配的物品仍掉落到怪物位置
普通实体死亡掉落	`mythicmobs-drop-to-warehouse`	匹配成功时从死亡掉落列表移除并加入击杀者仓库
管理指令给予	`/llwh give`	直接增加在线玩家的仓库数量
槽位存入指令	`/llwh save`	读取 Minecraft 背包槽位或 GermPlugin 身份槽位并尝试存入
Java API	`giveItem`	由其他插件增加玩家的仓库数量

存入操作会检查玩家是否已经完成数据加载。仓库页面配置了条件时，拾取、潜行右键、界面存入和掉落接管只会处理玩家当前满足条件的仓库物品。

数据存储

YAML 模式

未启用 MySQL 时，玩家数据保存在：

text

plugins/LyLootsWareHouse/playerdata/玩家名称.yml

每个物品 ID 对应一个数量。保存时会先写入独立临时文件，再备份旧文件并替换主文件。读取到损坏的主文件时，插件会尝试从同名 .bak 备份恢复；无法恢复时返回空数据，并在控制台输出警告。

MySQL 模式

MySQL 表名使用插件名 LyLootsWareHouse，数据按照玩家 UUID 保存。表内包含自增 id、uuid 和序列化后的 data 字段。

切换存储方式

mysql.enable 的默认配置注释明确要求切换数据库开关后重启服务器。不要只依赖 /llwh reload 在 YAML 与 MySQL 模式之间切换，因为对应的数据监听器是在插件启动阶段注册的。

指令

主命令为 /llwh。

指令	使用者	说明
`/llwh`	OP	显示管理指令帮助
`/llwh reload`	OP	重载配置、仓库物品和自动保存任务；MySQL 已启用时会重新建立连接
`/llwh open [仓库]`	玩家	打开指定仓库的第一页，代码未设置额外命令权限
`/llwh give [玩家] [物品ID] [数量]`	OP	为在线玩家增加指定战利品数量
`/llwh take [玩家] [物品ID] [数量]`	OP	扣除在线玩家的指定战利品数量，最低保留为 0
`/llwh set [玩家] [物品ID] [数量]`	OP	直接设置在线玩家的指定战利品数量
`/llwh dislodge [物品ID] [数量]`	玩家	尝试从自己的仓库取出指定数量物品
`/llwh save [玩家] [槽位来源]`	OP	尝试把在线玩家指定槽位中的匹配物品存入仓库

give、take 和 set 只能操作已经写入仓库配置并成功加载的物品 ID，目标玩家必须在线。

`/llwh save` 槽位格式

格式	说明
`Minecraft#[槽位ID]`	读取玩家 Minecraft 背包中的指定槽位
`GermPlugin#[槽位标识]`	读取 GermPlugin 身份槽位中的物品

完整格式为：

text

/llwh save [玩家] Minecraft#[槽位ID]
/llwh save [玩家] GermPlugin#[槽位标识]

仓库条件

每个仓库可以配置一组 condition。所有条件均通过后，该仓库中的物品才会参与拾取、潜行右键、界面点击和掉落存入匹配。

条件格式	用途
`permission:{权限节点}`	检查玩家是否拥有指定权限
`nopermission:{权限节点}`	配置文件声明为无权限条件，具体行为与注意事项见仓库配置页
`papi:{表达式}`	解析 PlaceholderAPI 变量并计算表达式

papi 表达式支持 &&、||、>、<、>=、<=、== 和 !=。数值部分支持 +、-、*、/ 与括号，字符串相等判断可使用单引号或双引号。

PlaceholderAPI 变量

变量标识符为 llwh。

变量	返回内容
`%llwh_[物品ID]%`	玩家指定物品 ID 的仓库数量
`%llwh_file%`	玩家当前打开的仓库页数；未记录时返回 `1`
`%llwh_warehouse%`	玩家当前打开的仓库 ID；未记录时返回空字符串
`%llwh_slot_amount:[仓库ID]:[槽位ID]%`	指定仓库内指定槽位所对应物品的数量，槽位从 `0` 开始
`%llwh_now_amount:[槽位ID]%`	当前仓库当前页中指定槽位所对应物品的数量，页面物品槽位从 `0` 开始

未识别的变量请求会返回错误文本。槽位格式错误或找不到对应物品时，槽位数量变量返回 0。

API 与事件

插件公开 LootsWarehouseAPI，可按物品 ID 或 Function<ItemStack, Boolean> 匹配器操作玩家数据。

API 能力	说明
`getAllItems()`	获取全部已加载物品 ID 与物品模板
`hasItem_forData(name, lore)`	按显示名称和 Lore 文本查找物品 ID
`hasItem(...)`	判断已加载物品中是否存在指定 ID 或匹配物品
`getItem(...)`	获取玩家指定物品的仓库数量
`setItem(...)`	设置玩家指定物品的仓库数量
`giveItem(...)`	增加玩家指定物品的仓库数量
`takeItem(...)`	扣除玩家指定物品的仓库数量，结果不会低于 0

插件提供两个 Bukkit 事件：

事件	触发时机
`LyLootsWarehouseStorageItemEvent`	物品通过仓库流程或 API 增加时触发
`LyLootsWarehouseDislodgeItemEvent`	物品通过界面、指令或 API 从仓库扣除时触发

事件可读取玩家、物品副本和操作数量。事件类包含取消状态与数量修改方法，但当前仓库处理流程在触发事件后不会读取取消状态或修改后的数量，因此不能依靠取消事件阻止已经执行的存取操作。

注意事项

仓库物品按照配置中的 ID 和物品模板匹配，不是只比较材质名称。
仓库物品加载失败时，控制台会提示对应仓库和物品 ID，并且该物品不会进入仓库列表。
仓库界面依赖玩家数据已经加载；数据尚未完成加载时无法打开。
mythicmobs-drop-to-warehouse 同时影响 MythicMobs 战利品事件和普通实体死亡掉落匹配。
自动保存仅处理在线且数据发生变化的玩家，周期单位为秒。
MySQL 模式使用 UUID 查询玩家数据；YAML 模式使用玩家名称作为文件名。
玩家赠送流程通过聊天输入目标玩家名称和数量，输入“取消”可以终止操作。
/llwh open [仓库] 只会在仓库 ID 存在时打开界面，不存在时不会打开任何页面。

页面索引

页面	内容
配置说明	物品库、MySQL、自动保存、GUI、消息和功能开关
仓库配置	仓库分页、开放条件、物品列表和槽位顺序
插件变量	PlaceholderAPI 变量格式、返回值和槽位计算
API 与事件	Java API 方法、匹配方式和 Bukkit 事件
运行机制	物品匹配、存取、掉落接管、自动保存和数据加载机制
常见问题	数据库连接、物品加载、仓库打不开和存取失败排查
更新日志	文档整理记录

战利品仓库 LyLootsWareHouse ​

插件信息 ​

依赖与兼容 ​

核心功能依赖 ​

可选扩展 ​

玩法说明 ​

主要功能 ​

仓库界面操作 ​

存入来源 ​

数据存储 ​

YAML 模式 ​

MySQL 模式 ​

指令 ​

/llwh save 槽位格式 ​

仓库条件 ​

PlaceholderAPI 变量 ​

API 与事件 ​

注意事项 ​

页面索引 ​