仓库配置

LyLootsWareHouse 使用 warehouse 节点定义战利品仓库。每个子节点代表一个仓库分类，包含分类标题、开启条件和可存储的物品。

仓库中的物品数量按玩家分别保存，支持 YAML 文件或 MySQL 存储。启用 MySQL 时，必须安装 LyMySQLCore，并确保数据库连接成功；否则玩家数据无法正常加载和保存，相关功能不会生效。

基础结构

warehouse:
  分页1:
    title: '&7分类1战利品仓库'
    condition:
      - 'permission:{loots.分页1}'
    item:
      - '材料1'
      - '材料2'

配置键	类型	说明
warehouse	节点	所有仓库分类的根节点。
warehouse.<仓库id>	节点	单个仓库分类，<仓库id> 由配置文件决定。
title	字符串	打开该仓库时显示的界面标题，支持 & 颜色代码。
condition	字符串列表	玩家使用该仓库需要满足的条件。多个条件需要全部通过。
item	字符串列表	该仓库包含的物品 id。物品会按照此列表中的顺序显示。

<仓库id> 是配置节点名称，不是固定值。例如上面配置中的仓库 id 为 分页1。

仓库物品

item 列表中的每一项都会被解析为物品。项目默认配置注释以 MythicMobs 物品 id 为例：

warehouse:
  分类2:
    title: '&7分类2战利品仓库'
    condition:
      - 'permission:{loots.分页2}'
    item:
      - '材料3'
      - '材料4'

只有能够被插件解析成功的物品才会载入仓库。物品不存在或解析失败时，该物品不会进入仓库，服务器控制台会记录载入失败信息。

插件会以完整物品数据匹配存入物品，包括物品本身及其物品元数据。仅 id 相同但物品数据不一致的物品，不会被当作同一个仓库物品。

同一个物品可以出现在多个仓库分类中，但各分类的显示和条件判断分别根据对应配置处理。

开启条件

条件写在 condition 列表中。多个条件使用“全部满足”的判断方式。

写法	说明
permission:{权限}	玩家拥有指定权限时通过。
nopermission:{权限}	当前版本代码中的实际判断仍然是“玩家拥有指定权限时通过”。名称虽然表示无权限，但实际行为与名称不一致。
papi:{表达式}	使用 PlaceholderAPI 解析表达式，并通过表达式判断。

示例：

condition:
  - 'permission:{loots.vip}'
  - 'papi:{%player_level% < 100}'

PlaceholderAPI 条件

使用 papi:{...} 时，插件会移除外层条件标记和空格，再交给表达式判断逻辑处理。PlaceholderAPI 本身未安装或未正常启用时，相关占位符无法正常解析。

nopermission 的实际行为

项目中的条件判断代码对 nopermission:{权限} 使用了与 permission:{权限} 相同的通过逻辑：玩家没有该权限时条件不通过，玩家拥有该权限时条件通过。因此不能根据名称将它理解为“禁止拥有权限”。

如果需要限制玩家必须拥有权限，应使用：

condition:
  - 'permission:{loots.vip}'

存入方式

仓库只接收配置在 warehouse.*.item 中、并且与配置物品完整匹配的物品。

方式	配置或指令	说明
拾取存入	pickup-item-to-warehouse	开启后，玩家拾取与仓库物品匹配的掉落物时，物品会直接存入仓库，不进入背包。
Shift 右键存入	shift-right-save-item	开启后，玩家潜行时右键空气或方块，会尝试将主手物品存入仓库。
背包内批量存入	仓库界面中点击背包物品	打开仓库界面时，点击背包内匹配的物品，会将背包中匹配物品全部存入当前仓库。
MythicMobs 掉落存入	mythicmobs-drop-to-warehouse	开启后，插件会优先处理 MythicMobs 掉落以及实体死亡掉落中的匹配物品。成功匹配的物品不会掉落到地面。
指令给予	/llwh give <玩家> <物品id> <数量>	管理员向在线玩家的仓库增加指定数量。
槽位存入	/llwh save <玩家> <槽位类型#槽位>	管理员尝试将指定玩家指定槽位中的匹配物品存入仓库。

pickup-item-to-warehouse、shift-right-save-item 和 mythicmobs-drop-to-warehouse 都是布尔配置。项目默认值分别为 true、true 和 false。

MythicMobs 掉落处理

启用 mythicmobs-drop-to-warehouse 后：

• MythicMobs 掉落事件中的物品会优先尝试进入仓库。
• 普通实体死亡掉落中的匹配物品也会尝试进入仓库。
• 只有玩家击杀或玩家作为击杀者时才处理。
• 未匹配成功的物品会继续正常掉落。
• 仓库分类的开启条件仍然会参与判断。

取出方式

仓库界面每页最多显示 45 个物品，底部保留翻页和填充槽位。翻页按钮的位置由插件固定使用第 45 槽和第 53 槽。

操作	取出数量
左键	1
Shift + 左键	10
右键	32
Shift + 右键	64

取出时需要满足以下条件：

• 玩家仓库中拥有足够数量的物品。
• 玩家背包至少存在一个空槽位。
• 取出的物品会添加到玩家背包。
• 成功取出后，仓库数量立即扣除对应数量。

也可以使用以下指令取出指定物品：

/llwh dislodge <物品id> <数量>

该指令只能由玩家执行。物品 id 必须存在于仓库配置中，且玩家必须拥有足够数量和至少一个空背包槽位。

赠送物品

配置 trade-enable: true 后，玩家可以在仓库界面中键点击物品发起赠送。

赠送流程如下：

1. 在仓库界面中键点击要赠送的物品。
2. 根据聊天提示输入目标玩家名称。
3. 输入要赠送的数量。
4. 插件检查目标玩家是否在线，以及发送者是否拥有足够数量。
5. 检查通过后扣除发送者仓库数量，并增加接收者仓库数量。

赠送只支持在线玩家。输入 取消 可以取消当前赠送流程。目标玩家不在线、数量不是整数或数量不足时，赠送不会完成。

界面配置

仓库界面相关配置位于 gui 节点：

配置键	说明
gui.item-name-format	仓库物品名称格式。{name} 会替换为物品名称，{amount} 会替换为玩家当前仓库数量。
gui.fill-item	底部填充物品。
gui.fill-name	底部填充物品名称。
gui.next-item1	上一页按钮物品。
gui.next-name1	上一页按钮名称。
gui.next-item2	下一页按钮物品。
gui.next-name2	下一页按钮名称。
gui.add-lore	追加到仓库物品 lore 下方的提示文本。支持 {amount} 和 PlaceholderAPI。

默认配置示例：

gui:
  item-name-format: '{name} x{amount}'
  fill-item: '160:9'
  fill-name: '&7封锁'
  next-item1: '341:0'
  next-name1: '&6上一页'
  next-item2: '341:0'
  next-name2: '&6下一页'
  add-lore:
    - ' '
    - '&a左键取1个 / Shift+左键取10个'
    - '&a右键取32个 / Shift+右键取64个'
    - ''
    - '&7在该界面点击背包内的战利品, 可全部存入仓库.'
    - ''
    - '&7鼠标中键点击, 可以将指定数量的该物品送给其他在线玩家.'
    - ''
    - '&7该战利品你当前还有 &a{amount} &7个. '

仓库物品名称

仓库物品显示名称按照以下顺序处理：

1. 优先使用物品的自定义显示名称。
2. 没有自定义名称时使用物品类型名称。
3. 使用 gui.item-name-format 追加当前仓库数量。

原物品 lore 会保留，gui.add-lore 会追加到原 lore 后面。

指令

插件注册的主指令为 /llwh。

指令	执行者	说明
/llwh	OP	显示管理员指令帮助。
/llwh reload	OP	重载配置、仓库分类和物品列表。启用 MySQL 时会根据配置重新建立数据库连接。
/llwh give <玩家> <物品id> <数量>	OP	向在线玩家增加指定仓库物品数量。物品 id 必须存在于仓库配置。
/llwh take <玩家> <物品id> <数量>	OP	从在线玩家仓库扣除指定数量。数量不足时最低扣除到 0。
/llwh set <玩家> <物品id> <数量>	OP	设置在线玩家的指定物品数量。
/llwh open <仓库id>	玩家	打开指定仓库的第一页。仓库 id 必须存在于 warehouse 节点。
/llwh dislodge <物品id> <数量>	玩家	尝试取出指定数量的仓库物品。
/llwh save <玩家> <槽位类型#槽位>	OP	尝试将玩家指定槽位中的物品存入仓库。

插件代码使用 OP 身份检查管理员指令，项目中没有为这些指令声明独立权限节点。

save 的槽位格式

<槽位类型#槽位> 目前支持以下格式：

格式	说明
Minecraft#<槽位编号>	读取玩家 Minecraft 背包中的指定槽位。
GermPlugin#<槽位编号>	读取 GermPlugin 界面中的指定槽位。

示例：

/llwh save Steve Minecraft#0
/llwh save Steve GermPlugin#1

只有与仓库配置物品完整匹配的槽位物品才会被存入。save 指令要求目标玩家在线。

数据保存

当 mysql.enable: false 时，玩家数据保存到插件目录下的玩家 YAML 文件中。

当 mysql.enable: true 时，插件使用 MySQL 保存玩家仓库数据。相关配置位于 mysql 节点：

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

MySQL 模式下，插件启动时会创建以插件名称命名的数据表，并在玩家加入、退出和服务器关闭时读取或保存仓库数据。

必须同时满足以下条件，MySQL 存储才会生效：

• 已安装 LyMySQLCore。
• mysql.enable 设置为 true。
• 数据库地址、端口、名称、用户名和密码正确。
• 插件成功连接数据库。

如果数据库未连接成功，插件会阻止玩家登录，直到数据库初始化完成。

自动保存

auto-save-interval: 3

auto-save-interval 用于设置自动保存间隔，单位为秒。默认值为 3。自动保存用于降低服务器异常停止造成的数据丢失风险。

玩家退出、被踢出服务器以及服务器关闭时，插件也会保存玩家仓库数据。

相关变量

仓库变量由 PlaceholderAPI 注册：

变量	说明
%llwh_<物品id>%	查询指定物品 id 的仓库数量。
%llwh_file%	查询当前仓库界面页数。
%llwh_warehouse%	查询当前仓库 id。
%llwh_slot_amount:<仓库id>:<槽位id>%	查询指定仓库指定槽位的物品数量。
%llwh_now_amount:<槽位id>%	查询当前仓库指定槽位的物品数量。

使用这些变量前，需要安装并启用 PlaceholderAPI。

注意事项

• 修改 mysql.enable 后需要重启服务器。
• 仓库配置物品必须能够被插件解析，否则不会载入。
• 仓库条件会在存入、掉落处理和使用仓库时参与判断。
• 玩家数据尚未加载完成时，仓库界面无法打开。
• 物品数量使用较大的整数类型保存，仓库本身没有按普通背包堆叠数量限制。
• nopermission:{权限} 当前实际要求玩家拥有该权限，不应按字面理解为“没有该权限”。