宝珠 LyPearls

LyPearls 是一款装备宝珠镶嵌插件。玩家在背包中拿起指定宝珠，再点击带有对应槽位 lore 的单件装备，即可消耗一颗宝珠并生成镶嵌结果。

每种宝珠可以配置多个结果。插件先检查权限、PlaceholderAPI 表达式和随机几率条件，再从满足条件的结果中按权重抽取一个结果。镶嵌结果可以添加 lore、替换物品名称、写入字符串 NBT，并执行玩家或后台指令。

装备上的旧宝珠 lore 会在再次镶嵌时被清理，使装备只保留当前宝珠结果。插件同时支持原版玩家背包和 GermPlugin 槽位。

插件信息

项目	内容
插件名	LyPearls
插件版本	1.0.4
作者	Liyuan
主命令	/lybz
配置目录	plugins/LyPearls/
宝珠目录	plugins/LyPearls/pearls/
软依赖	PlaceholderAPI、GermPlugin

支持版本

项目包含下列 Minecraft 服务端版本的 NMS 实现：

Minecraft 版本	NMS 版本	Java 环境
1.7.10	v1_7_R4	Java 8
1.8.8	v1_8_R3	Java 8
1.11.2	v1_11_R1	Java 8
1.12.2	v1_12_R1	Java 8
1.13.2	v1_13_R2	Java 8
1.14.4	v1_14_R1	Java 8
1.15.2	v1_15_R1	Java 8
1.16.5	v1_16_R3	Java 8
1.17.1	v1_17_R1	Java 17
1.18.2	v1_18_R2	Java 17
1.19.2	v1_19_R1	Java 17
1.19.4	v1_19_R3	Java 17
1.20.1	v1_20_R1	Java 17
1.20.2	v1_20_R2	Java 17
1.20.3	v1_20_R3	Java 17

插件会根据服务端报告的 Bukkit 版本加载对应 NMS 实现。未列出的版本没有对应实现，NBT 写入等依赖 NMS 的功能无法确认可用。

依赖说明

依赖	类型	用途
PlaceholderAPI	软依赖	解析 papi 条件、数值公式和结果指令中的变量
GermPlugin	软依赖	在萌芽 GUI 槽位中处理宝珠镶嵌，并保存、同步槽位物品

使用 PlaceholderAPI 条件、公式或变量指令时，服务器必须正确安装 PlaceholderAPI 以及相关变量扩展。未安装 GermPlugin 时，不会注册萌芽 GUI 监听器，但原版背包镶嵌仍由普通背包监听器处理。

项目中没有 MySQL 存储功能，也不依赖 LyMySQLCore。

玩法机制

1. 玩家用鼠标拿起带有指定显示名称的宝珠物品。
2. 玩家点击背包中的目标装备，或点击萌芽 GUI 中的目标槽位。
3. 插件按显示名称匹配宝珠配置，名称比较不区分大小写。
4. 目标物品必须带有 lore，且物品堆叠数量不能大于 1。
5. 目标物品 lore 必须包含 item-need-lore 中的任意一行。
6. 插件筛选所有满足条件的结果，并按 weight 权重随机选择结果。
7. 插件清理旧宝珠 lore，然后写入新结果的 lore。
8. 如结果配置了替换名称、NBT 或指令，插件会继续执行对应操作。
9. 镶嵌成功后消耗玩家光标上的一颗宝珠，并发送成功消息。

同一玩家的连续镶嵌点击存在约 500 毫秒的处理间隔，用于避免短时间重复触发。

功能

功能	说明
背包点击镶嵌	玩家拿起宝珠点击单件装备即可触发镶嵌判断
萌芽槽位支持	安装 GermPlugin 后可在萌芽 GUI 槽位中完成相同操作
宝珠名称识别	通过物品显示名称识别宝珠类型
槽位 lore 判断	目标物品必须包含配置的任意一行 item-need-lore
多文件加载	递归读取 pearls/ 目录及子目录中的 .yml 文件
多宝珠定义	单个 YAML 文件顶层可以定义多个宝珠 ID
条件筛选	支持权限、无权限、PlaceholderAPI 表达式和随机几率条件
权重抽取	只有满足全部条件的结果才参与权重计算
随机数值	lore 和 NBT 值支持范围随机与小数格式化
变量公式	支持将 PlaceholderAPI 变量代入四则运算公式
lore 替换	新宝珠镶嵌时会清理插件生成的旧宝珠 lore
槽位行处理	可保留基础槽位 lore，也可在镶嵌时删除该行
名称替换	选中结果可以替换目标装备的显示名称
NBT 写入	结果可向物品写入单层字符串 NBT，依赖对应版本的 NMS 实现
指令联动	镶嵌成功后可执行玩家、临时 OP 或控制台指令
消息覆盖	每种宝珠可覆盖全局成功和失败消息，也可使用 none 关闭消息
颜色代码	名称、lore 和消息支持使用 & 颜色代码

结果条件

每个镶嵌结果的 condition 是字符串列表。列表中的条件必须全部通过，该结果才会加入权重池。

条件格式	说明
permission:{权限节点}	玩家必须拥有指定权限
nopermission:{权限节点}	玩家必须没有指定权限
papi:{表达式}	解析 PlaceholderAPI 变量并判断表达式
roll:{几率}	按百分比进行随机判断，例如 roll:{10} 表示约 10% 几率

papi 表达式支持 >、<、>=、<=、==、!=，并可使用 && 和 || 组合条件。数值部分支持 +、-、*、/ 和括号；字符串相等比较可使用单引号或双引号包裹字符串。

随机数值与公式

结果 lore 和 NBT 字符串支持两种数值语法：

格式	说明
{最小值~最大值~格式}	在指定范围内生成随机数，并使用 Java 数值格式输出
公式~格式，整体写在尖括号内	先解析 PlaceholderAPI 变量，再计算四则运算结果并格式化

例如 {100~200~%.0f} 会生成 100 到 200 之间的随机数并保留零位小数。公式语法可以包含范围随机结果和 PlaceholderAPI 变量，具体配置见宝珠配置。

指令

指令	使用者	说明
/lybz	OP	显示重载指令提示
/lybz reload	OP	重载 config.yml 和 pearls/ 目录中的全部宝珠配置

插件没有声明独立权限节点，后台指令直接通过玩家是否为 OP 判断。

配置文件

路径	内容
plugins/LyPearls/config.yml	全局镶嵌成功与不可镶嵌消息
plugins/LyPearls/pearls/示例宝珠.yml	默认生成的宝珠配置示例
plugins/LyPearls/pearls/**/*.yml	管理员创建的其他宝珠配置文件

插件重载时会递归扫描 pearls/ 目录，只读取扩展名为 .yml 的文件。宝珠 ID 来自每个文件的顶层配置键。

配置能力概览

配置键	作用
name	用于识别宝珠物品的显示名称
message.不可附魔	当前宝珠的不可镶嵌消息
message.附魔成功	当前宝珠的镶嵌成功消息
item-need-lore	允许镶嵌的目标 lore 列表，匹配任意一行即可
remove-default-lore	是否在镶嵌时删除匹配到的基础槽位 lore
add-lore-result	当前宝珠的全部随机结果
add-lore-result.<结果>.weight	结果权重，未填写时默认值为 1
add-lore-result.<结果>.condition	结果参与权重计算前必须满足的条件
add-lore-result.<结果>.replace-name	选中结果后替换装备名称
add-lore-result.<结果>.nbt	写入装备的单层字符串 NBT
add-lore-result.<结果>.lore	选中结果后写入装备的 lore
add-lore-result.<结果>.command	选中结果后执行的指令列表

完整键结构和 YAML 写法见配置说明与宝珠配置。

结果指令类型

前缀	执行方式
[console]	由控制台执行
[op]	临时授予玩家 OP 后，以玩家身份执行，完成后恢复原状态
[player]	由玩家执行
无前缀	由玩家执行

执行前会解析指令中的 PlaceholderAPI 变量。

使用限制

• 宝珠物品必须拥有显示名称，且名称必须与配置的 name 匹配。
• 目标物品必须拥有 lore，并包含当前宝珠要求的槽位 lore。
• 目标装备的堆叠数量不能大于 1。
• 镶嵌结果需要至少存在一个能够参与抽取的有效结果。
• 使用 papi 条件、变量公式或指令变量前，需要保证 PlaceholderAPI 能返回可计算或可比较的内容。
• NBT 功能依赖服务端版本对应的 NMS 实现成功初始化。
• 新宝珠会覆盖插件生成的旧宝珠 lore，不会在同一装备上无限叠加结果。
• remove-default-lore: true 会移除匹配到的基础槽位 lore；设为 false 时，新宝珠 lore 会添加在槽位 lore 附近。

页面索引

页面	内容
配置说明	全局消息、配置目录和基础配置项
宝珠配置	宝珠定义、结果权重、条件、随机数值、NBT 与结果指令
常见问题	宝珠无法识别、槽位不匹配、变量计算和版本问题排查
更新日志	文档整理记录