仓库配置

LyWarehouse 的仓库配置写在 warehouse 节点下。每个子节点都是一个仓库 ID，仓库 ID 会用于玩家数据、按钮动作、API 调用和解锁条件引用。

插件为玩家提供独立的多仓库存储空间。玩家可以在 GUI 中存入、取出、整理、搜索、出售、分解或删除仓库物品。物品数量独立记录，不受物品栏单组数量限制影响。

WARNING

仓库数据默认保存到插件数据目录；启用 MySQL 后会改用数据库保存。使用 MySQL 存储时，必须安装 LyMySQLCore，并且 LyMySQLCore 已成功连接数据库，否则玩家数据无法正常加载。

基础结构

warehouse:
  "仓库1":
    main-id: "54:0"
    main-name: "&6随身仓库1 {status}"
    main-lore:
      - "&7这是一个随身仓库"
      - "&a[点击解锁/打开]"
    title: "&6随身仓库"
    size: 5
    open-condition: []
    unlock-condition:
      - "eco:{10}"
    button:
      1:
        item: "54:0"
        name: "&6一键存入"
        lore:
          - "&a将背包物品尽可能存入本仓库"
        handle:
          - "dislodge"

仓库字段

配置键	类型	说明
main-id	字符串	仓库总览界面中显示的物品 ID。默认值为 CHEST:0。
main-name	字符串	仓库总览界面中的物品名称。支持 {status}，会替换为解锁或未解锁状态文本。
main-lore	字符串列表	仓库总览界面中的物品说明。支持 PlaceholderAPI 变量和 {status}。
title	字符串	打开仓库 GUI 后显示的标题。
size	整数	仓库物品区域的行数，每行 9 格。实际值会限制在 1-5 之间。底部另有 1 行按钮区域，因此 GUI 总高度为 (size + 1) × 9。
open-condition	字符串列表	仓库已解锁后，打开仓库时检查的条件。任意条件不满足时不会打开仓库。
unlock-condition	字符串列表	解锁仓库时检查的条件。所有条件都满足后才会解锁，并扣除其中配置的金币、点券或物品。
button	节点	仓库底部按钮配置。按钮槽位只能使用 0-8。未配置的槽位会填充 gui.fill-item。

仓库容量

size 表示仓库物品区域的行数：

• 每行包含 9 个物品槽位。
• 有效配置范围为 1-5。
• 小于 1 的值会按 1 处理。
• 大于 5 的值会按 5 处理。
• GUI 最底部额外保留 9 个按钮槽位。
• 仓库存储时会按配置顺序和槽位顺序查找可堆叠物品或空槽位。

例如，size: 5 时，仓库物品区域共有 45 个槽位，按钮区域位于第 46-54 个槽位。

总览界面显示

仓库总览界面使用以下配置控制显示：

gui:
  lock-replace: '&7[未解锁]'
  unlock-replace: '&a[已解锁]'
  main-title: '&6仓库总览'

配置键	说明
gui.main-title	仓库总览界面的标题。
gui.lock-replace	未解锁仓库替换 {status} 的文本。
gui.unlock-replace	已解锁仓库替换 {status} 的文本。

总览界面中的仓库图标会使用 main-id 创建，并将 main-name、main-lore 中的 {status} 替换为对应状态。main-lore 还会处理 PlaceholderAPI 变量。

解锁条件

unlock-condition 中的条件会逐项检查，全部满足后才会解锁仓库。金币、点券和物品条件在解锁成功时扣除。

写法	说明
unlock:{仓库ID}	要求玩家已经解锁指定仓库。
eco:{数量}	要求玩家拥有足够的 Vault 经济余额；解锁成功后扣除对应金额。
point:{数量}	要求玩家拥有足够的 PlayerPoints 点券；解锁成功后扣除对应点券。
item:{物品名称#数量}	要求玩家背包内存在指定名称和数量的物品；解锁成功后扣除对应物品。
papi:{条件}	使用 PlaceholderAPI 变量进行条件判断。支持 >、>=、==、<、<=。
permission:{权限}	要求玩家拥有指定权限。
nopermission:{权限}	要求玩家没有指定权限。

示例：

unlock-condition:
  - 'unlock:{仓库0}'
  - 'eco:{10}'
  - 'point:{10}'
  - 'item:{&6牛马工具#10}'
  - 'papi:{%player_level% > 10}'
  - 'permission:{解锁权限.10级}'
  - 'nopermission:{解锁权限.10级}'

解锁行为

当玩家尝试打开未解锁仓库时，插件会根据 try-auto-unlock 决定是否自动尝试解锁：

try-auto-unlock: true

配置值	行为
true	玩家打开未解锁仓库时自动检查并尝试解锁。解锁失败则不会打开仓库。
false	不自动解锁。玩家需要通过其他方式调用插件 API 解锁，或自行制作菜单执行解锁逻辑。

打开条件

open-condition 只在仓库已经解锁后、玩家尝试打开仓库时检查。当前支持以下条件：

写法	说明
papi:{条件}	使用 PlaceholderAPI 变量进行条件判断。支持 >、>=、==、<、<=。
permission:{权限}	要求玩家拥有指定权限。
nopermission:{权限}	要求玩家没有指定权限。

示例：

open-condition:
  - 'papi:{%player_level% >= 10}'
  - 'permission:{warehouse.open.vip}'

打开条件不满足时，仓库不会打开。项目代码未为该情况配置单独的失败提示。

仓库按钮

每个仓库可以在 button 下配置最多 9 个按钮，槽位范围为 0-8。按钮实际显示在仓库 GUI 最底部的一行中。

button:
  1:
    item: '54:0'
    name: '&6一键存入'
    lore:
      - '&a将背包内尽可能所有物品依次尝试存入本仓库'
    handle:
      - 'dislodge'

配置键	类型	说明
button.<槽位>.item	字符串	按钮物品 ID。
button.<槽位>.name	字符串	按钮名称。支持 & 颜色代码。
button.<槽位>.lore	字符串列表	按钮说明。支持 PlaceholderAPI 变量。
button.<槽位>.handle	字符串列表	点击按钮后按列表顺序执行的动作。

按钮动作

动作	说明
dislodge	依次尝试将玩家背包前 36 个槽位中的物品存入仓库。成功存入的物品会从背包移除。存储时仍会检查禁止存储的 Lore、仓库容量和物品堆叠。
sort:<排序组ID>	根据 sort-button.<排序组ID> 中的 Lore 关键字排序仓库物品。排序期间玩家不能操作仓库。
message:<文本>	向玩家发送文本消息，支持 & 颜色代码。
open:<仓库ID>	打开指定仓库的存储模式。仓库仍会检查解锁状态和 open-condition。
fj:<仓库ID>	打开指定仓库的分解模式。分解结果由 LyDecomposition 提供。
sell:<仓库ID>	打开指定仓库的出售模式。出售价格和出售处理由 LySell 提供。
remove:<仓库ID>	打开指定仓库的删除模式，物品会被直接扣除且不会返还。
delay:<秒数>	等待指定秒数后继续执行后续动作，支持小数。
command:<指令>	以控制台身份执行指令，执行前会处理 PlaceholderAPI 变量。
close	关闭当前 GUI。

动作会按照 handle 列表中的顺序执行。例如：

handle:
  - 'message:&7你进入了仓库1存储模式'
  - 'open:仓库1'

WARNING

remove:<仓库ID> 是直接删除模式。删除后的物品不会进入玩家背包，建议只用于明确提示玩家的菜单。

仓库排序

排序组写在全局 sort-button 节点下，按钮通过 sort:<排序组ID> 调用。

sort-button:
  品质排序:
    - '&7品质: &6史诗'
    - '&7品质: &d极品'
    - '&7品质: &b精良'
    - '&7品质: &a优秀'
    - '&7品质: &f普通'
  作用排序:
    - '&7类型: &b武器'
    - '&7类型: &b装备'
    - '&7类型: &b首饰'
    - '&7类型: &b材料'
    - '&7类型: &b道具'

排序逻辑如下：

• 按排序组中的关键字从前往后匹配物品 Lore。
• 匹配到前面关键字的物品会排在前面。
• 未匹配到任何关键字的物品排在后面。
• 排序完成后会重新整理仓库槽位并刷新 GUI。
• sort:<排序组ID> 引用不存在的排序组时，会提示排序 ID 不存在。

存储规则

全局存储规则由以下配置控制：

prohibited-lore-for-storage:
  - '&c禁止放入随身仓库'

pickup-to-warehouse-enable: true
hide-item-amount: true

配置键	说明
prohibited-lore-for-storage	Lore 包含列表中任意文本的物品不能存入仓库，也不能通过自动拾取入库。
pickup-to-warehouse-enable	是否启用自动拾取入库功能。关闭后，地面拾取和 MythicMobs 掉落入库都不会生效。
hide-item-amount	控制 GUI 中物品图标显示的数量。该配置只影响界面显示，不影响仓库实际记录的数量。

普通存储和 dislodge 一键存入会：

• 优先尝试与已有相同物品堆叠。
• 无法堆叠时查找已解锁仓库中的第一个空槽位。
• 所有可用仓库都没有空间时提示仓库已满。
• 物品会按照 warehouse 配置顺序和仓库槽位顺序进行查找。

自动拾取入库

自动拾取入库由两个条件共同控制：

1. 全局配置 pickup-to-warehouse-enable 必须为 true。
2. 玩家个人自动拾取状态必须已开启。

符合条件时，普通地面物品会优先存入玩家已解锁仓库中的匹配物品槽位；没有可堆叠槽位时，会尝试放入第一个空槽位。成功入库后，地面物品会被移除。

玩家自动拾取状态对应变量为 %lyck_autopick%，返回 true 或 false。

MythicMobs 掉落入库

mythicmobs-drop-to-warehouse: true

启用后，插件会在击杀生物产生掉落时优先尝试将掉落物放入仓库。该功能还要求 pickup-to-warehouse-enable 为 true。

• 普通生物掉落会在掉落事件中尝试入库。
• MythicMobs 的物品掉落会在 MythicMobs 掉落事件中尝试入库。
• 成功入库的掉落不会继续掉落到地面。
• 无法入库时，MythicMobs 掉落会重新掉落到地面。
• 物品 Lore 禁止存储时不会入库。

GUI 模式

仓库 GUI 支持以下模式：

模式	说明
open	存储模式。玩家可从背包存入物品，也可从仓库取出物品。
fj	分解模式。使用 LyDecomposition 的分解配置处理仓库物品。
sell	出售模式。使用 LySell 的出售逻辑处理仓库物品。
remove	删除模式。直接删除仓库物品。

存储模式操作

在仓库物品上执行以下点击操作可以取出物品：

点击方式	操作
左键	取出 1 个。
右键	取出 10 个。
Shift + 左键	按物品最大堆叠数量取出。
Shift + 右键	尽可能取出，直到背包空间不足或仓库物品取完。

在背包物品上左键点击时，插件会统计背包内相同物品并尝试全部存入仓库。

中键点击仓库物品可以进行位置交换：

1. 第一次中键点击物品，记录其槽位。
2. 第二次中键点击另一个已有物品的槽位时，交换两个槽位的物品。
3. 第二次中键点击空槽位时，将物品移动到该槽位。

分解、出售和删除操作

模式	左键	右键	Shift + 左键	Shift + 右键
分解模式	分解 1 个	分解 10 个	分解 100 个	分解 1000 个
出售模式	出售 1 个	出售 10 个	出售 100 个	出售 1000 个
删除模式	删除 1 个	删除 10 个	删除 100 个	删除 1000 个

分解时，插件会检查分解结果和玩家背包空间；空间不足时不会执行分解。出售模式需要 LySell 提供出售处理，分解模式需要 LyDecomposition 提供分解结果。

GUI 显示配置

以下配置控制仓库物品、按钮和搜索界面的显示：

gui:
  fill-item: '160:9'
  fill-name: '&7封锁'
  search-last-item: '341:0'
  search-last-name: '&b上翻页'
  search-next-item: '341:0'
  search-next-name: '&b下翻页'
  extra-lore:
    - '&7&m                           '
    - '&7物品数量: &a{amount}'
  fj-lore:
    - '&7&m                           '
    - '&7物品数量: &a{amount}'
  sell-lore:
    - '&7&m                           '
    - '&7物品数量: &a{amount}'
  remove-lore:
    - '&7&m                           '
    - '&7物品数量: &a{amount}'

配置键	说明
gui.fill-item	未配置按钮槽位使用的填充物品。
gui.fill-name	填充物品名称。
gui.search-last-item	搜索结果界面上一页按钮的物品。
gui.search-last-name	搜索结果界面上一页按钮名称。
gui.search-next-item	搜索结果界面下一页按钮的物品。
gui.search-next-name	搜索结果界面下一页按钮名称。
gui.extra-lore	存储模式和搜索存储模式追加到物品 Lore 的文本。
gui.fj-lore	分解模式追加到物品 Lore 的文本。
gui.sell-lore	出售模式追加到物品 Lore 的文本。
gui.remove-lore	删除模式追加到物品 Lore 的文本。

上述 Lore 支持 {amount}，会替换为仓库内该物品的实际数量。

相关全局配置

仓库功能还会读取以下全局配置：

配置键	说明
papi-slot-amount-default-value	%lyck_slot_amount:<仓库ID>:<槽位ID>% 在指定槽位不存在物品时返回的默认值。
debug	调试开关。
auto-save-interval	自动保存间隔，单位为秒。默认值为 3。
show-operation-log	是否在日志中记录玩家对仓库进行的存储操作。
use-give-or-take-command-message	执行 give/take 相关操作时是否隐藏成功提示；失败时仍会提示。

变量

以下变量由插件提供：

变量	返回内容
%lyck_now_warehouse%	当前仓库 ID。
%lyck_now_warehouse_mode%	当前仓库模式：存储、分解、出售、删除、总览。
%lyck_unlock:<仓库ID>%	指定仓库是否已解锁，返回 true 或 false。
%lyck_empty_slot_all%	所有仓库剩余空槽位数量。
%lyck_empty_slot:<仓库ID>%	指定仓库剩余空槽位数量。
%lyck_amount:<物品名>%	所有仓库内指定物品名的数量。
%lyck_autopick%	玩家是否开启自动拾取入库，返回 true 或 false。
%lyck_slot_amount:<仓库ID>:<槽位ID>%	指定仓库指定槽位的物品数量。槽位不存在时返回 papi-slot-amount-default-value。
%lyck_autofj_<分解组>%	玩家是否开启指定自动分解组，返回 true 或 false。
%lyck_autosell_<出售组>%	玩家是否开启指定自动出售组，返回 true 或 false。

自动分解

自动分解配置写在 auto-decompose-item 节点下，按物品 Lore 关键字匹配：

auto-decompose-item:
  '垃圾分解':
    - '&7品质: &a优秀'
    - '&7品质: &f普通'
    - '&7品质: &7破烂'

自动分解组需要玩家主动开启后才会生效。玩家开启或关闭指定分解组时，需要拥有对应权限：

lyck.autofj.<分解组>

当物品存入仓库并且 Lore 匹配已开启的分解组时，插件会尝试调用 LyDecomposition 处理物品。分解结果会直接发放给玩家，不再保留该物品。

自动出售

自动出售配置写在 auto-sell-item 节点下，按物品 Lore 关键字匹配：

auto-sell-item:
  '垃圾出售':
    - '&7品质: &a优秀'
    - '&7品质: &f普通'
    - '&7品质: &7破烂'

自动出售组需要玩家主动开启后才会生效。玩家开启或关闭指定出售组时，需要拥有对应权限：

lyck.autosell.<出售组>

当物品存入仓库并且 Lore 匹配已开启的出售组时，插件会尝试调用 LySell 出售物品。自动分解优先级高于自动出售；同一物品同时匹配两种功能时，优先执行自动分解。

数据保存

YAML 保存

未使用 MySQL 时，玩家数据保存为插件数据目录中的玩家 YAML 文件：

plugins/LyWarehouse/data/<玩家UUID>.yml

保存内容包括：

• 已解锁仓库列表。
• 各仓库的物品槽位和数量。
• 玩家自动拾取入库状态。
• 已开启的自动出售组。
• 已开启的自动分解组。

玩家加入服务器时加载数据，退出或被踢出时保存数据。仓库 GUI 关闭时也会保存当前玩家数据。

MySQL 保存

mysql:
  enable: false
  databasename: mc2
  username: mc2
  password: mc1234
  port: 3306
  ip: 127.0.0.1

配置键	说明
mysql.enable	是否启用 MySQL 存储。修改后需要重启服务器。
mysql.databasename	数据库名称。
mysql.username	数据库用户名。
mysql.password	数据库密码。
mysql.port	数据库端口。默认值为 3306。
mysql.ip	数据库地址。默认值为 127.0.0.1。

启用 MySQL 时：

• 必须安装 LyMySQLCore。
• LyMySQLCore 必须成功连接数据库。
• 数据库未连接时，玩家登录会被阻止，直到数据库初始化完成。
• 插件会使用连接池访问数据库。
• 数据表名称使用插件名称，保存玩家名称和序列化后的仓库数据。

API 相关行为

插件 API 可以读取和修改玩家仓库数据，包括：

• 查询玩家全部仓库或指定物品的数量。
• 按物品对象、显示名称、Lore 或自定义匹配器扣除物品。
• 将物品存入玩家已解锁仓库。
• 解锁指定仓库或强制解锁仓库。
• 获取玩家全部仓库物品。
• 获取指定仓库物品。
• 获取玩家已解锁仓库 ID 列表。

API 存入物品时同样遵守仓库容量、物品相似度和禁止存储 Lore 等规则。API 相关 Java 类位于插件 API 包中，具体方法签名以项目发布的 API 类为准。

事件

插件提供以下 Bukkit 事件供其他插件监听：

事件	触发时机
LyWarehouseStorageItemEvent	物品尝试进入仓库时触发，包括普通存储、自动拾取、MythicMobs 掉落入库和 API 存储。事件可以取消本次操作，也可以修改存入数量。
LyWarehouseDislodgeItemEvent	玩家从仓库取出物品前触发。事件可以取消本次取出，也可以修改取出数量。

FAQ

为什么仓库容量不是配置的无限行数？

代码会将 size 限制在 1-5。配置小于 1 时按 1 处理，大于 5 时按 5 处理。

为什么仓库没有自动存入物品？

请检查以下内容：

• 玩家是否已经解锁至少一个仓库。
• 仓库是否存在空槽位或可堆叠的相同物品。
• 物品 Lore 是否命中 prohibited-lore-for-storage。
• pickup-to-warehouse-enable 是否为 true。
• 玩家是否已开启自动拾取入库状态。
• MySQL 模式下 LyMySQLCore 是否已成功连接数据库。

为什么解锁仓库后金币、点券或物品被扣除？

eco、point 和 item 条件不仅用于检查，还会在解锁成功时扣除对应资源。解锁失败时不会执行扣除。

为什么按钮动作没有效果？

请检查：

• 按钮槽位是否在 0-8 范围内。
• handle 动作前缀是否正确。
• open、fj、sell、remove 引用的仓库 ID 是否存在。
• sort 引用的排序组是否存在。
• 分解和出售模式所需的外部插件是否已安装并正常工作。

为什么分解或出售模式无法使用？

分解模式需要 LyDecomposition 提供对应的分解配置和结果；出售模式需要 LySell 提供出售处理。缺少对应插件或没有配置匹配物品时，相关操作不会成功。

为什么 MythicMobs 掉落仍然掉在地上？

请确认 mythicmobs-drop-to-warehouse 和 pickup-to-warehouse-enable 都为 true，并检查玩家是否有已解锁仓库以及仓库是否有可用空间。仓库无法接收物品时，掉落会继续掉落到地面。

删除模式会返还物品吗？

不会。remove 模式会直接从仓库扣除物品，不会将物品放入玩家背包。

为什么数据库模式下玩家无法登录？

MySQL 监听器会在数据库连接未成功时阻止玩家登录。请确认已安装 LyMySQLCore、数据库参数正确，并且该插件已经成功连接数据库。