离渊系列插件Wiki

常见问题 ​

插件支持哪些服务端版本？ ​

项目声明了 api-version: 1.13，并以 Paper API 1.16.5-R0.1-SNAPSHOT 作为编译依赖。项目还包含旧版数字物品 ID 和英文物品 ID 的兼容处理。

实际使用时，应以插件包和服务端环境的兼容情况为准。当前项目证据没有声明更高版本的明确支持范围。

插件启动后玩家无法进入服务器 ​

插件初始化完成前，玩家登录会被拒绝，并提示插件尚未初始化完成。

如果启用了 MySQL 存储，还需要确认以下条件：

  • 已安装 LyMySQLCore。
  • mysql.enable 已按实际存储方案配置。
  • MySQL 数据库连接成功。
  • 数据库初始化已经完成。

MySQL 连接失败时，相关玩家数据无法正常加载或保存。不要只检查配置文件是否存在，还需要确认控制台中的数据库连接结果。

物品没有自动存入仓库 ​

请按以下顺序检查：

  1. 物品是否配置在对应仓库节点的 item 列表中。
  2. 玩家是否满足该仓库的 condition 条件。
  3. 物品是否与仓库预设物品完全一致。
  4. 对应的自动存入开关是否开启。
  5. 玩家数据是否已经成功加载。

仓库物品不是只按显示名称判断。插件会将拾取到的物品、背包内物品或主手物品与仓库预设进行匹配；物品材质、数量以及物品元数据不一致时，可能无法匹配。

仓库配置示例：

yaml
warehouse:
  分页1:
    title: '&7分类1战利品仓库'
    item:
      - '材料1'
      - '材料2'

如果是拾取时没有存入，检查：

yaml
pickup-item-to-warehouse: true

该功能只会处理已配置且匹配成功的物品。未写入任何 warehouse.*.item 列表的物品不会自动存入。

拾取物品没有进入仓库，但手动操作可以 ​

pickup-item-to-warehouse 只控制玩家拾取掉落物时的自动存入功能。

yaml
pickup-item-to-warehouse: true

以下情况不会自动存入：

  • 配置项为 false。
  • 物品不在仓库预设中。
  • 玩家不满足仓库的 condition。
  • 玩家数据尚未加载。
  • 掉落物与仓库预设的物品元数据不一致。

插件使用的是拾取事件处理逻辑。已经被其它插件取消的拾取事件不会继续处理。

Shift 右键无法存入主手物品 ​

检查配置：

yaml
shift-right-save-item: true

开启后，玩家需要手持仓库中已配置的物品，并使用潜行状态右键点击空气或方块。物品匹配成功且玩家满足仓库条件后，主手物品会被存入仓库。

如果玩家不满足该仓库的条件，会显示 message.right-error 对应的提示。常见原因包括：

  • 没有对应权限。
  • papi 条件判断未满足。
  • 物品没有配置在当前可用仓库中。
  • 物品的材质、数量或元数据与预设不一致。

在仓库界面点击背包物品没有存入 ​

仓库界面打开后，点击玩家背包中的物品可以尝试将该物品的匹配堆叠全部存入仓库。

请确认：

  • 点击的是玩家背包中的物品，而不是仓库界面按钮。
  • 该物品已经配置在当前可用仓库中。
  • 玩家满足仓库的 condition。
  • 玩家数据已经加载。

该操作会匹配玩家背包中相同的物品，并将匹配到的数量加入仓库。未带物品元数据的背包物品不会被该操作作为匹配物处理。

仓库打不开 ​

使用：

text
/llwh open <仓库ID>

其中 <仓库ID> 必须是 warehouse 下的节点名，例如：

yaml
warehouse:
  分页1:
    title: '&7分类1战利品仓库'

对应指令为：

text
/llwh open 分页1

请检查：

  • 指令中的仓库 ID 是否与配置节点名完全一致。
  • 仓库节点是否确实位于 warehouse 下。
  • 仓库物品列表是否正确加载。
  • 玩家是否满足该仓库的 condition。

open 指令本身不要求权限节点，代码中要求执行者是玩家。

配置了 condition 后玩家看不到仓库内容 ​

仓库条件会在玩家执行相关操作时进行判断。当前项目中使用了以下条件类型：

条件写法作用
permission:{权限}玩家拥有指定权限时满足条件
nopermission:{权限}玩家没有指定权限时满足条件
papi:{表达式}使用 PlaceholderAPI 处理变量后，再判断表达式

示例：

yaml
condition:
  - 'nopermission:{loots.分页2}'
  - 'permission:{loots.分页2}'
  - 'papi:{%player_level% < 100}'

papi 条件需要安装并正常运行 PlaceholderAPI。表达式支持数值比较、字符串相等或不等、&& 与 || 逻辑组合，以及基础的 +、-、*、/ 运算。

如果条件中使用了 PlaceholderAPI 变量，请确认变量实际能够返回值；变量未解析时，条件可能无法满足。

取出物品失败 ​

仓库界面中的取出数量由点击方式决定：

点击方式取出数量
左键1
Shift+左键10
右键32
Shift+右键64

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

  • 仓库中已有足够数量的物品。
  • 玩家背包至少有一个空位。
  • 玩家数据已经加载。

数量不足时会使用 message.get-error，其中 {need} 为本次需要的数量，{has} 为当前拥有的数量。

背包没有空位时会使用 message.slot-empty-error。插件会在扣除仓库数量前检查背包空位。

使用 /llwh dislodge 取出失败 ​

指令格式为：

text
/llwh dislodge <物品ID> <数量>

该指令只能由玩家执行，并且物品 ID 必须存在于仓库预设中。执行时还需要满足：

  • 玩家背包至少有一个空位。
  • 玩家仓库数量不少于取出数量。
  • 数量参数必须是有效的整数。

数量不足时会使用 message.get-error。成功时会使用 message.get-success。

指令给予失败 ​

指令格式为：

text
/llwh give <玩家> <物品ID> <数量>

该指令需要由 OP 执行，目标玩家必须在线，物品 ID 必须存在于仓库预设中。

如果提示物品 ID 不在战利品预设配置内，请检查该 ID 是否写入了某个 warehouse.*.item 列表，并确认拼写完全一致。

/llwh take 或 /llwh set 无法执行 ​

指令格式为：

text
/llwh take <玩家> <物品ID> <数量>
/llwh set <玩家> <物品ID> <数量>

这两个指令都需要 OP 执行，目标玩家必须在线，物品 ID 必须存在于仓库预设中。

  • take：扣除目标玩家指定数量的仓库物品。
  • set：将目标玩家的仓库物品数量设置为指定数量。

项目没有为这些指令声明独立的 Bukkit 权限节点，代码使用的是 OP 判断。

/llwh save 无法将物品收进仓库 ​

指令格式为：

text
/llwh save <玩家> <类型#槽位>

该指令需要 OP 执行，目标玩家必须在线。支持的槽位来源写法为：

text
GermPlugin#槽位ID
Minecraft#槽位ID

插件会读取指定槽位的物品，并尝试与仓库预设匹配。匹配成功后，物品数量会加入仓库，原槽位会被清空。

如果提示无法存储，请检查：

  • 类型是否为 GermPlugin 或 Minecraft。
  • 槽位格式中是否包含 #。
  • 指定槽位是否确实存在物品。
  • 物品是否与仓库预设完全匹配。

/llwh reload 重载后配置没有生效 ​

指令为：

text
/llwh reload

该指令需要 OP 执行。

重载后仍未生效时，请检查：

  • YAML 缩进是否正确。
  • 配置键名称是否拼写正确。
  • warehouse 节点下的仓库 ID 是否重复或写错。
  • 物品 ID 是否写在正确的 item 列表中。
  • 数据库开关变更是否已经重启服务器。

配置注释明确说明，数据库开关的变更需要重启服务器，不能只依赖重载指令。

MythicMobs 掉落没有自动进入仓库 ​

该功能由以下配置控制：

yaml
mythicmobs-drop-to-warehouse: false

只有将其设置为 true 后，MythicMobs 怪物掉落才会尝试优先进入仓库。

同时需要确认：

  • 已安装并正常运行 MythicMobs。
  • 怪物掉落由玩家击杀事件产生。
  • 掉落物与仓库预设完全匹配。
  • 玩家满足对应仓库的 condition。
  • 玩家数据已经加载。

如果掉落物没有匹配到任何仓库预设，插件会继续将物品掉落到世界中，而不是直接丢弃。

赠送物品时没有反应 ​

仓库界面中键点击物品会进入赠送流程，但前提是：

yaml
trade-enable: true

赠送流程会通过聊天输入完成：

  1. 输入目标玩家名称。
  2. 输入赠送数量。
  3. 输入 取消 可取消当前操作。

目标玩家必须在线，数量必须是整数，且赠送者拥有足够的仓库物品。赠送完成后，目标玩家会收到提示。

如果 trade-enable 为 false，中键点击不会进入该赠送流程。

变量返回错误或没有显示 ​

插件配置中登记的变量如下：

变量返回内容
%llwh_<物品ID>%指定物品 ID 的数量
%llwh_file%当前仓库界面页数
%llwh_warehouse%当前仓库 ID
%llwh_slot_amount:<仓库ID>:<槽位ID>%指定仓库指定槽位的物品数量
%llwh_now_amount:<槽位ID>%当前仓库指定槽位的物品数量

使用变量时请注意：

  • 变量需要通过 PlaceholderAPI 使用。
  • <物品ID>、<仓库ID> 和 <槽位ID> 必须替换为实际值，不能保留尖括号。
  • 仓库界面相关变量需要玩家当前正在打开仓库界面。
  • 仓库 ID 必须与 warehouse 下的配置节点名一致。
  • 物品 ID 必须与 warehouse.*.item 中的配置一致。
  • 槽位 ID 必须使用实际界面槽位编号。

例如，以下内容中的尖括号只是占位说明，不能原样复制：

text
%llwh_物品ID%
%llwh_slot_amount:仓库ID:槽位ID%
%llwh_now_amount:槽位ID%

开启 MySQL 后数据仍然没有保存 ​

MySQL 存储不是只打开配置项就会生效。必须同时满足：

  1. 已安装 LyMySQLCore。
  2. MySQL 服务可访问。
  3. mysql.ip、mysql.port、mysql.databasename、mysql.username 和 mysql.password 正确。
  4. 数据库连接成功。
  5. 数据库初始化完成。

配置结构如下：

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

只有安装 LyMySQLCore 且成功连接数据库后，MySQL 相关的数据加载和保存功能才会生效。连接失败时，不能把问题归因于变量或仓库配置本身。

YAML 存储的数据没有及时写入 ​

未使用 MySQL 存储时，玩家数据会在加入、退出和被踢出服务器时进行加载或保存，并通过自动保存任务定期保存。

自动保存间隔由以下配置控制，单位为秒：

yaml
auto-save-interval: 3

如果担心数据丢失，请确认：

  • auto-save-interval 为有效的数值。
  • 服务器没有在保存过程中被强制关闭。
  • 玩家退出时没有发生其它插件或服务器异常。
  • 玩家数据文件所在目录具备正常的读写条件。

为什么物品数量可以超过普通堆叠上限 ​

仓库保存的是玩家拥有的数量数据，不受 Minecraft 普通物品堆叠上限限制。取出时，插件会按点击数量加入玩家背包；仓库中的数量不会因为界面显示或普通堆叠限制自动截断。

如果背包空间不足，取出操作会失败并显示空位提示。

物品显示名称与仓库 ID 不一致 ​

仓库匹配使用配置中的物品预设 ID 和对应的物品对象。消息中的 {item} 优先使用物品显示名称；如果物品没有显示名称，则使用物品类型名称或物品 ID 作为显示内容。

因此，消息显示名称与 warehouse.*.item 中的 ID 不同并不一定表示匹配失败。排查时应优先核对实际物品预设、物品元数据和仓库条件。

事件监听器没有收到仓库存入或取出事件 ​

插件在仓库存入成功和取出成功时分别触发对应事件：

  • LyLootsWarehouseStorageItemEvent
  • LyLootsWarehouseDislodgeItemEvent

事件只会在实际发生有效数量的存入或取出时触发。物品为空、玩家为空、数量不足、背包没有空位或操作没有匹配成功时，不会触发对应的有效仓库事件。