LyWarehouse
MySQL 前置要求
启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则本插件的 MySQL 数据读取、保存、同步和本地数据迁移不会生效。
LyWarehouse 是虚拟仓库插件，用于把玩家物品集中存入多个可配置仓库。每种相同物品在仓库槽位中使用独立的长整数数量记录，不受单个物品堆叠上限限制。
插件提供仓库总览、条件解锁、物品存取、跨仓库搜索、Lore 排序、自动拾取、自动出售、自动分解、MythicMobs 掉落入库和管理指令，可用于随身仓库、材料仓库、刷怪掉落仓库及多页储物系统。
插件信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyWarehouse |
| 插件版本 | 1.1.6 |
| 作者 | 离渊 |
| 主命令 | /lyck |
| Java 版本 | Java 8 |
| API 版本声明 | 1.13 |
| 编译使用的服务端 API | Paper 1.16.5-R0.1-SNAPSHOT |
| 数据存储 | 本地 YAML 或 MySQL |
版本说明
项目仅能确认 plugin.yml 声明了 api-version: 1.13，并使用 Paper 1.16.5 API 编译。其他 Minecraft 服务端版本是否兼容，需要在实际环境中验证。
玩法与操作
仓库总览
玩家可通过 /lyck main 打开 6 行仓库总览。插件按照配置文件中 warehouse 节点的顺序显示仓库，单个总览界面最多展示 54 个仓库。
每个仓库入口可单独配置：
- 展示物品、名称和 Lore。
- 仓库标题。
- 存储区域行数。
- 打开条件和解锁条件。
- 底部操作按钮。
- 已解锁与未解锁状态文本。
点击未解锁仓库时，插件会尝试执行解锁；点击已解锁仓库时会打开仓库界面。
物品存储
仓库界面由存储区域和最底部一行操作按钮组成。仓库存储区域实际限制为 1 至 5 行，每行 9 个槽位，因此单个仓库最多保存 45 种不同物品。
玩家在普通仓库模式中左键点击自己背包里的物品时，会把背包内全部相似物品存入仓库。自定义按钮还可使用 dislodge 动作，将背包前 36 个槽位内可存储的物品依次尝试入库。
入库时按以下顺序寻找位置：
- 按仓库配置顺序，在全部已解锁仓库中寻找可叠加的相似物品。
- 如果操作来自指定仓库界面，优先寻找该仓库的空槽位。
- 按仓库配置顺序寻找其他已解锁仓库的空槽位。
- 没有可叠加槽位或空槽位时，提示仓库已满。
可通过 prohibited-lore-for-storage 禁止带有指定 Lore 的物品进入仓库。
物品取出
普通仓库模式和搜索结果界面支持以下取出操作：
| 操作 | 取出数量 |
|---|---|
| 左键 | 1 个 |
| 右键 | 10 个 |
| Shift + 左键 | 一组，数量取决于该物品的最大堆叠数 |
| Shift + 右键 | 在背包容量允许时尽量全部取出 |
普通仓库模式下还可依次中键点击两个仓库槽位，交换两个位置中的物品。
仓库模式
自定义按钮可以切换以下操作模式：
| 模式 | 按钮动作 | 功能 |
|---|---|---|
| 存储模式 | open:仓库ID | 存入、取出和交换仓库物品 |
| 分解模式 | fj:仓库ID | 按点击方式批量分解仓库物品 |
| 出售模式 | sell:仓库ID | 按点击方式批量出售仓库物品 |
| 删除模式 | remove:仓库ID | 永久删除指定数量的仓库物品 |
分解、出售和删除模式的默认点击数量如下：
| 操作 | 处理数量 |
|---|---|
| 左键 | 1 个 |
| 右键 | 10 个 |
| Shift + 左键 | 100 个 |
| Shift + 右键 | 1000 个 |
删除模式
删除模式会直接扣除仓库中的物品，不会返还物品或货币。仅应通过明确标注的按钮开放该模式。
主要功能
| 功能 | 说明 |
|---|---|
| 多仓库 | 可配置多个独立仓库，并按配置顺序显示和分配物品 |
| 大数量存储 | 槽位数量使用 long 保存，同类物品可在单个槽位累计大量数量 |
| 条件解锁 | 支持金币、点券、背包物品、PlaceholderAPI 表达式、拥有权限和缺少权限条件 |
| 打开限制 | 仓库解锁后仍可通过变量表达式、拥有权限或缺少权限限制打开 |
| 自动尝试解锁 | 打开未解锁仓库时可自动检查并扣除解锁消耗 |
| 一键存入 | 通过仓库按钮把玩家背包中的物品依次尝试存入仓库 |
| 自动拾取 | 玩家背包无法容纳拾取物时，可将物品转入已解锁仓库 |
| 范围拾取 | 管理员可把指定玩家附近的掉落物尝试存入其仓库 |
| 仓库搜索 | 跨全部已解锁仓库搜索物品名称和 Lore，支持拼音转换后的文本匹配 |
| 搜索分页 | 搜索界面每页显示 45 个结果，并提供上下翻页按钮 |
| Lore 排序 | 按配置的 Lore 关键词优先级重新排列指定仓库内的物品 |
| 自动出售 | 入库事件触发后，按玩家启用的出售组匹配物品 Lore 并调用出售插件 |
| 自动分解 | 入库事件触发后，按玩家启用的分解组匹配物品 Lore并生成分解产物 |
| 手动出售 | 通过出售模式批量出售仓库中的物品 |
| 手动分解 | 通过分解模式批量分解仓库中的物品，产物继续尝试进入仓库 |
| MythicMobs 入库 | 可将 MythicMobs 怪物掉落优先尝试存入玩家仓库 |
| 数据自动保存 | 按配置间隔保存在线玩家数据，关闭仓库和玩家退出时也会保存 |
| 操作日志 | 可将玩家的存入、取出、出售、分解和删除等数量变化写入日志 |
| 数据迁移 | 支持把本地 LyWarehouse YAML 数据写入 MySQL，并包含 LegendWarehouse 数据转换逻辑 |
| 开发接口 | 提供查询、扣除、发放、解锁和读取仓库内容的 API，并提供存入与取出事件 |
依赖与功能联动
软依赖
plugin.yml 中登记了以下软依赖：
| 插件 | 用途 |
|---|---|
PlaceholderAPI | 解析仓库展示文本、按钮指令、条件表达式和 %lyck_*% 变量 |
Vault | 为 eco:{数量} 解锁条件提供经济余额查询和扣款 |
PlayerPoints | 为 point:{数量} 解锁条件提供点券查询和扣除 |
ProtocolLib | 已登记为软依赖，现有证据未确认具体功能用途 |
软依赖并非所有功能都必须安装，但对应功能没有依赖时不可用。使用金币解锁时还需要 Vault 已连接有效的经济插件。
功能依赖
| 功能 | 需要的插件或条件 |
|---|---|
| MySQL 存储 | 必须安装 LyMySQLCore，并成功连接数据库 |
| 金币解锁 | Vault 和可用的经济插件 |
| 点券解锁 | PlayerPoints |
| PAPI 条件与变量解析 | PlaceholderAPI |
| 自动出售、出售模式 | 代码调用 LySell API；默认配置标注需要 LySell 2.0.3+ |
| 自动分解、分解模式 | 代码调用 LyDecompositionReload API；默认配置标注需要 LyDecompositionReload 1.0.7+ |
| MythicMobs 掉落入库 | MythicMobs；默认配置注明测试环境使用 4.11.0 |
插件主配置默认包含物品库格式的发放指令。指令补全中登记了 NeigeItems@、SX-Item@、Zaphkiel@、MythicMobs@、LyItemSave@ 和 SX-Attribute@ 前缀，实际取物能力取决于服务器安装的对应插件及物品 ID。
解锁与打开条件
仓库可以分别配置解锁条件和打开条件。多个条件按顺序检查，必须全部满足。
解锁条件
| 格式 | 说明 | 是否消耗 |
|---|---|---|
eco:{数量} | 检查 Vault 金币余额 | 解锁成功时扣除 |
point:{数量} | 检查 PlayerPoints 点券 | 解锁成功时扣除 |
item:{物品名称#数量} | 按物品名称检查玩家背包 | 解锁成功时扣除 |
papi:{表达式} | 检查 PlaceholderAPI 表达式 | 否 |
permission:{权限} | 要求玩家拥有指定权限 | 否 |
nopermission:{权限} | 要求玩家没有指定权限 | 否 |
PAPI 表达式支持 >、>=、==、< 和 <= 比较符号。
配置兼容性
默认配置示例中出现了 unlock:{仓库ID}，但当前解锁检查代码没有处理该条件。不要依赖它实现前置仓库解锁。
打开条件
仓库解锁后，打开时支持以下条件：
| 格式 | 说明 |
|---|---|
papi:{表达式} | PlaceholderAPI 表达式必须成立 |
permission:{权限} | 玩家必须拥有指定权限 |
nopermission:{权限} | 玩家必须没有指定权限 |
打开条件不满足时，当前代码会直接停止打开，不发送失败提示。
搜索机制
使用 /lyck search 搜索内容 可搜索玩家全部已解锁仓库。当前指令只读取一个参数，因此搜索内容不能包含空格。
搜索范围包括：
- 物品显示名称。
- 物品 Lore 的每一行。
- 名称和 Lore 转换为拼音后的文本。
- 不区分转换后的英文字母大小写。
搜索结果每页最多显示 45 个物品。点击搜索结果时会从物品实际所在仓库扣除数量。
自动功能
自动拾取
玩家可通过 /lyck autopick 保存自己的自动拾取开关。当正常拾取无法把物品放入背包，并且 pickup-to-warehouse-enable 已启用时，插件会尝试将物品存入仓库。
自动拾取状态会随玩家数据一同保存。
自动出售
玩家通过 /lyck autosell 出售组ID 开关一个出售组。物品进入仓库后，插件会检查其 Lore 是否包含该组配置的任意关键词。匹配成功且出售插件接受该物品时，物品会从仓库扣除并完成出售。
每个出售组需要对应动态权限：lyck.autosell.出售组ID。
自动分解
玩家通过 /lyck autofj 分解组ID 开关一个分解组。物品进入仓库后，插件会检查其 Lore 是否包含该组配置的任意关键词。匹配成功且存在有效分解结果时，原物品会从仓库扣除，分解产物会重新尝试存入仓库。
每个分解组需要对应动态权限：lyck.autofj.分解组ID。
默认设计中自动分解优先于自动出售。自动分解还会在执行前检查全部已解锁仓库的剩余槽位是否足以容纳分解结果。
玩家指令
| 指令 | 说明 | 使用者 |
|---|---|---|
/lyck main | 打开仓库总览 | 玩家 |
/lyck open 仓库ID | 打开指定仓库的存储模式 | 玩家 |
/lyck unlock 仓库ID | 检查条件并尝试解锁指定仓库 | 玩家 |
/lyck search 搜索内容 | 搜索全部已解锁仓库中的物品名称和 Lore | 玩家 |
/lyck autopick | 开关个人自动拾取入库 | 玩家 |
/lyck autosell 出售组ID | 开关指定自动出售组 | 玩家，需要对应动态权限 |
/lyck autofj 分解组ID | 开关指定自动分解组 | 玩家，需要对应动态权限 |
管理指令
管理指令通过是否为 OP 判断，没有在 plugin.yml 中登记独立权限节点。
| 指令 | 说明 | 限制 |
|---|---|---|
/lyck reload | 重载配置、重新读取仓库并重启自动保存任务 | OP |
/lyck pick 玩家 范围 | 把指定玩家范围内的掉落物尝试存入其仓库，成功后移除实体 | OP |
/lyck force-unlock 玩家 仓库ID | 强制解锁在线玩家的指定仓库 | OP |
/lyck give 玩家 物品库插件@物品ID 数量 | 获取指定物品并尝试发放至在线玩家仓库 | OP |
/lyck take 玩家 物品名称 数量 | 从在线玩家全部仓库扣除指定数量，数量不足时不扣除 | OP |
/lyck look 玩家 仓库ID | 查看在线玩家的指定仓库 | 玩家 OP |
/lyck yaml-to-mysql | 把 plugins/LyWarehouse/data/ 中的本地玩家数据写入 MySQL | 控制台 OP，必须已连接数据库 |
/lyck legenwarehouse | 读取 plugins/LegendWarehouse/data/ 下玩家物品数据并转换为 LyWarehouse 本地存档 | 控制台 OP |
数据迁移
执行迁移前应备份原插件数据和 plugins/LyWarehouse/data/。/lyck yaml-to-mysql 仅在 MySQL 已成功连接时执行；/lyck legenwarehouse 会按现有仓库顺序填充物品，并为转换玩家写入全部仓库的解锁记录，容量不足的条目不会写入。
权限
当前项目仅确认以下动态权限。其他玩家指令没有在 plugin.yml 或指令代码中检查固定权限节点。
| 权限 | 说明 |
|---|---|
lyck.autosell.出售组ID | 允许玩家开关指定自动出售组 |
lyck.autofj.分解组ID | 允许玩家开关指定自动分解组 |
仓库自身仍可通过 permission:{权限} 和 nopermission:{权限} 使用任意权限字符串控制解锁或打开。
数据存储
本地 YAML
未连接 MySQL 时，玩家数据保存在：
text
plugins/LyWarehouse/data/玩家UUID.yml存档内容包括：
- 已解锁仓库。
- 各仓库槽位中的序列化物品。
- 每个槽位的实际物品数量。
- 自动拾取开关。
- 自动出售组列表。
- 自动分解组列表。
本地保存使用临时文件和备份恢复机制，降低写入中断导致存档损坏的风险。
MySQL
启用 mysql.enable 后，插件通过 LyMySQLCore 获取数据库连接，并以插件名作为数据表名保存玩家名称和完整 YAML 数据字符串。
数据库开关需要重启服务器。仅执行 /lyck reload 不适合作为数据库模式切换方式。
已知数据保存问题
当前 1.1.6 代码在保存玩家数据时，将 auto-sell-group 写成了自动分解组列表。使用本地 YAML 或 MySQL 都可能导致自动出售组在重新加载数据后不正确。配置自动出售功能时需要留意此问题。
开发能力
插件提供公开 API，可完成以下操作：
- 按匹配函数、显示名称、Lore 或
ItemStack查询玩家全部仓库中的物品数量。 - 按匹配函数、显示名称、Lore 或
ItemStack扣除物品。 - 向玩家仓库发放
ItemStack。 - 尝试解锁或强制解锁仓库。
- 获取玩家全部仓库物品。
- 获取指定仓库物品。
- 获取玩家已解锁的仓库 ID。
项目还提供以下 Bukkit 事件：
| 事件 | 触发时机 |
|---|---|
LyWarehouseStorageItemEvent | 物品成功写入仓库后触发；管理发放指令也会在写入前调用该事件 |
LyWarehouseDislodgeItemEvent | 从仓库取出物品前触发，可取消或修改取出数量 |
API 的方法、返回值和事件使用方式应查看独立 API 页面，避免与首页功能说明重复。
页面导航
| 页面 | 内容 |
|---|---|
| 配置说明 | 全局开关、MySQL、自动保存、GUI、消息和日志配置 |
| 仓库配置 | 仓库节点、容量、解锁条件、打开条件和按钮动作 |
| 自动功能 | 自动拾取、自动出售、自动分解、MythicMobs 入库和排序 |
| 插件变量 | PlaceholderAPI 变量、参数和返回值 |
| API 文档 | API 方法、仓库数据访问和 Bukkit 事件 |
| 运行机制 | 入库顺序、数量存储、数据保存、搜索和操作模式 |
| 常见问题 | 数据库连接、依赖缺失、仓库容量和功能排查 |