离渊系列插件Wiki

常见问题 ​

LyPearls 是如何触发宝珠镶嵌的？ ​

插件监听玩家在背包界面中的点击操作。玩家需要将宝珠放在鼠标光标位置，再点击目标装备。

目标装备必须满足以下条件：

  • 目标物品存在物品元数据。
  • 目标物品包含 lore。
  • 目标物品数量为 1。
  • 宝珠物品存在显示名称。
  • 宝珠显示名称与宝珠配置中的 name 一致。
  • 目标装备包含对应宝珠配置中的 item-need-lore。

插件也支持 GermPlugin 的 GUI 槽位点击事件。只有检测到 GermPlugin 已启用时，才会注册对应的 GUI 监听器。

宝珠点击装备没有反应 ​

按以下顺序检查：

  1. 宝珠物品是否存在显示名称。
  2. 宝珠显示名称是否与配置中的 name 一致。颜色代码也会参与匹配，建议直接复制配置中的名称。
  3. 目标装备是否存在 lore。
  4. 目标装备数量是否为 1。
  5. 目标装备是否包含 item-need-lore 中的任意一条 lore。
  6. 是否在插件监听的背包点击位置或 GermPlugin GUI 槽位中操作。
  7. 是否在短时间内重复点击。插件对同一玩家的点击存在约 500 毫秒的冷却处理。

如果目标装备不满足镶嵌条件，插件会发送宝珠自定义的 message.不可附魔，没有自定义消息时使用全局配置中的 message.不可附魔。

哪些物品可以被镶嵌？ ​

目标物品必须有 lore，并且数量不能大于 1。同时，目标物品必须包含宝珠配置中 item-need-lore 列表的任意一条内容。

当 remove-default-lore 为 false 时，插件会以匹配到的可镶嵌 lore 为位置参考，将结果 lore 添加到该位置之后。

当 remove-default-lore 为 true 时，插件会优先移除匹配到的可镶嵌 lore，再在对应位置写入结果 lore。

一件装备可以镶嵌多个宝珠吗？ ​

同一件装备不会保留同一宝珠配置的多个结果。再次镶嵌时，插件会先清理该宝珠生成的旧结果 lore，再写入新的结果。

因此，重新镶嵌后旧宝珠结果消失属于插件机制，不是物品损坏。

不同宝珠配置会互相覆盖吗？ ​

插件会根据宝珠配置的内部标识区分生成的结果 lore。重新镶嵌时会清理当前宝珠配置对应的结果标识，再写入新结果。

如果你修改了宝珠配置的标识，旧物品上由旧标识生成的结果可能不会被新配置识别为同一组结果。

某个结果一直不出现 ​

结果是否进入随机池由 condition 决定。只有所有条件都满足时，该结果才会参与权重计算。

检查以下内容：

  • permission:{权限节点}：玩家必须拥有对应权限。
  • nopermission:{权限节点}：玩家不能拥有对应权限。
  • papi:{表达式}：表达式计算结果必须为真。
  • roll:{几率}：随机几率检查必须通过。
  • 结果的 weight 是否大于 0。

如果所有结果的条件都不满足，插件没有可正常选择的结果，相关配置需要重新检查。

weight 是固定概率吗？ ​

不是。weight 用于在当前满足条件的结果之间进行加权随机。

不满足条件的结果不会加入总权重，因此其他满足条件的结果会在剩余权重中重新计算。roll:{几率} 还会额外进行一次随机检查，数值按百分比处理，例如 roll:{10} 表示约 10% 的通过几率。

condition 中支持哪些条件？ ​

当前代码支持以下条件格式：

条件格式作用
permission:{权限节点}玩家拥有权限节点时通过
nopermission:{权限节点}玩家没有权限节点时通过
papi:{表达式}先解析 PlaceholderAPI 占位符，再计算表达式
roll:{几率}按百分比进行随机检查

同一个结果配置多条条件时，所有条件都必须通过。

papi:{} 条件无法生效 ​

papi:{} 条件依赖 PlaceholderAPI。插件在 plugin.yml 中将 PlaceholderAPI 声明为软依赖，但只有服务器实际安装并启用 PlaceholderAPI 时，占位符处理才有对应功能。

检查以下内容：

  • PlaceholderAPI 是否已安装并启用。
  • 使用的占位符是否由已安装的扩展提供。
  • 表达式中的比较运算符是否正确。
  • 占位符替换后的内容是否为有效的数字、字符串或布尔值。

papi:{} 表达式支持哪些写法？ ​

表达式支持数值比较、字符串比较、布尔判断、数学运算，以及 && 和 || 逻辑组合。

支持的比较运算符包括：

  • >
  • <
  • >=
  • <=
  • ==
  • !=

示例：

yaml
condition:
  - 'papi:{%player_level% >= 30}'
  - 'papi:{%player_name% == "Steve"}'

表达式中的数学运算支持 +、-、*、/ 和括号。

随机数值格式报错 ​

范围随机必须使用以下格式：

text
{最小值~最大值~格式}

例如：

yaml
lore:
  - '&7物理伤害 +{200~400~%.0f}'
  - '&7暴击几率 +{20~40~%.2f}%'

其中：

  • 第一段是最小值。
  • 第二段是最大值。
  • 第三段是 Java 格式化字符串，例如 %.0f 或 %.2f。

随机数值可以用于结果的 lore 和 nbt 值。

公式计算格式报错 ​

公式计算必须使用以下格式：

text
<公式~格式>

公式会先处理 PlaceholderAPI 占位符，再进行数学计算。

示例：

yaml
lore:
  - '&7物理伤害 +<{200~400~%.0f}*%player_level%~%.0f>'
  - '&7暴击几率 +<60*%player_level%~%.2f>%'

公式内部可以继续嵌套范围随机。公式运算支持 +、-、*、/ 和括号。

结果中的颜色代码没有生效 ​

配置中的颜色代码使用 &，插件在写入结果 lore、替换物品名称和发送消息时会转换为 Minecraft 颜色代码。

检查配置是否使用了正确的 & 颜色格式，并确认 YAML 字符串没有因为特殊字符导致解析错误。

镶嵌成功后宝珠数量没有变化 ​

成功镶嵌时，插件会将光标上的宝珠数量减少 1，然后把剩余物品重新设置到光标位置。

如果点击没有满足镶嵌条件，宝珠不会被消耗。

镶嵌成功后物品名称被修改 ​

结果配置存在 replace-name 时，插件会将目标装备的物品名称替换为该值。

不需要修改物品名称时，删除对应结果中的 replace-name 配置即可。

NBT 没有写入 ​

插件通过当前服务端对应的 NMS 实现读写物品 NBT。启动时会根据 Bukkit 版本初始化对应实现；如果控制台显示 初始化API失败!，NBT 相关功能无法正常使用。

当前项目包含以下服务端版本的 NMS 实现：

  • 1.7.10
  • 1.8.8
  • 1.11.2
  • 1.12.2
  • 1.13.2
  • 1.14.4
  • 1.15.2
  • 1.16.5
  • 1.17.1
  • 1.18.2
  • 1.19.2
  • 1.19.4
  • 1.20.1
  • 1.20.2
  • 1.20.3

如果服务端版本不在上述列表中，项目中没有对应的 NMS 初始化分支，NBT 相关结果不能保证正常工作。

NBT 配置支持哪些类型？ ​

NMS 接口提供字符串键和整数键的读写方法，但宝珠配置中的 nbt 内容按配置值读取并写入字符串键值。

项目示例中使用单层 NBT 配置：

yaml
nbt:
  测试NBT: '这是一个NBT节点'

不建议在 nbt 中配置多层嵌套结构。项目示例也明确标注该功能只支持单层。

镶嵌成功消息没有发送 ​

消息发送优先级如下：

  1. 宝珠自身的 message.附魔成功。
  2. 全局 config.yml 中的 message.附魔成功。

将消息设置为 none 时，不发送该消息。

镶嵌失败时使用相同的优先级规则，但对应配置键为 message.不可附魔。

如何关闭某个宝珠的消息？ ​

在宝珠自身的 message 中将对应消息设置为 none：

yaml
message:
  不可附魔: 'none'
  附魔成功: 'none'

如果宝珠没有配置对应消息，则会回退到全局 config.yml 的同名消息。

配置修改后什么时候生效？ ​

宝珠配置和全局配置会在插件启用时加载。使用以下命令可以重新加载配置：

text
/lybz reload

重载命令只允许拥有服务器 OP 权限的发送者执行。成功执行后会发送 重载成功。

/lybz 没有显示帮助或无法重载 ​

插件注册的命令是 lybz，当前代码只处理以下情况：

命令执行条件作用
/lybz发送者为 OP 且没有参数显示重载提示
/lybz reload发送者为 OP重载插件配置

项目没有为该命令声明独立的 permission 配置，权限判断使用的是 Bukkit 的 OP 状态。

宝珠配置文件放在哪里？ ​

插件会读取插件目录下 pearls 文件夹中的所有 .yml 文件，并加载其中的宝珠配置。

默认配置文件为：

text
plugins/LyPearls/config.yml
plugins/LyPearls/pearls/示例宝珠.yml

pearls 文件夹中的子目录也会被递归读取，只处理扩展名为 .yml 的文件。

GermPlugin 未安装还能使用吗？ ​

可以。普通背包点击由 Bukkit 的 InventoryClickEvent 处理；只有检测到 GermPlugin 已启用时，插件才会额外注册 GermPlugin GUI 槽位点击监听器。

因此，GermPlugin 仅影响 Germ GUI 槽位点击支持，不是普通背包点击功能的必需依赖。

PlaceholderAPI 和 GermPlugin 是硬依赖吗？ ​

plugin.yml 将 PlaceholderAPI 和 GermPlugin 声明为软依赖。

不过：

  • 使用 papi:{} 条件时，需要 PlaceholderAPI 提供占位符处理。
  • 需要在 GermPlugin GUI 中镶嵌时，需要 GermPlugin 已启用。
  • 不使用这些功能时，普通宝珠镶嵌逻辑不依赖对应扩展功能。

插件支持哪些 Minecraft 版本？ ​

项目包含以下版本的 NMS 适配实现：

Minecraft 版本NMS 实现
1.7.10V1_7_R4
1.8.8V1_8_R3
1.11.2V1_11_R1
1.12.2V1_12_R1
1.13.2V1_13_R2
1.14.4V1_14_R1
1.15.2V1_15_R1
1.16.5V1_16_R3
1.17.1V1_17_R1
1.18.2V1_18_R2
1.19.2V1_19_R1
1.19.4V1_19_R3
1.20.1V1_20_R1
1.20.2V1_20_R2
1.20.3V1_20_R3

插件清单中的 Bukkit API 版本标记为 `1.13`，但项目同时提供了 `1.7.10`、`1.8.8`、`1.11.2` 和 `1.12.2` 的 NMS 实现。对于未列出的服务端版本，项目证据中没有对应的 NMS 初始化实现，不能保证兼容。