配置说明

LyPearls 的配置分为全局配置和宝珠配置：

• 全局配置文件：plugins/LyPearls/config.yml
• 宝珠配置目录：plugins/LyPearls/pearls/
• 宝珠配置文件：目录内所有扩展名为 .yml 的文件

插件启动或重载时会读取配置目录中的 YAML 文件，并加载文件内的所有顶级宝珠节点。

配置文件

文件或目录	用途
config.yml	配置全局消息
pearls/*.yml	配置宝珠、附魔结果、条件和执行命令

全局配置

全局配置文件默认包含以下内容：

message:
  不可附魔: '该物品不可附魔该宝珠.'
  附魔成功: '附魔成功!'

message

全局消息配置。当宝珠文件没有配置对应消息时，插件使用这里的消息。

配置键	类型	说明
message.不可附魔	字符串	目标物品不满足宝珠镶嵌条件时发送的消息
message.附魔成功	字符串	宝珠镶嵌成功后发送的消息

消息支持使用 & 颜色代码。将值设置为 none 时，不发送对应消息。

宝珠配置中的同名消息优先级高于全局消息。宝珠配置存在对应键时，即使该值为 none，也不会回退到全局消息。

宝珠配置

宝珠文件可以包含一个或多个顶级节点，每个顶级节点代表一枚宝珠。顶级节点名称是宝珠的内部标识，例如 宝珠1：

'宝珠1':
  name: '&e荣耀宝珠'
  message:
    不可附魔: '该物品不可附魔该宝珠.'
    附魔成功: '附魔成功!'
  item-need-lore:
    - '&7可附魔宝珠位'
  remove-default-lore: false
  add-lore-result:
    '结果1':
      weight: 10
      condition:
        - 'permission:{789.砍崽}'
      lore:
        - '&7上等附魔【&e荣耀宝珠&7】'

宝珠顶层配置

配置键	类型	默认值	说明
宝珠标识.name	字符串	无	宝珠物品的显示名称。玩家将鼠标放在宝珠上，并使用该显示名称匹配宝珠配置。支持 & 颜色代码。
宝珠标识.message	节点	无	当前宝珠的消息配置。对应消息会覆盖全局消息。
宝珠标识.item-need-lore	字符串列表	空列表	可镶嵌物品必须包含的任意一行 Lore。列表中只要有一项与物品 Lore 匹配即可。支持 & 颜色代码，不区分大小写。
宝珠标识.remove-default-lore	布尔值	false	控制基础 Lore 和已有宝珠 Lore 的处理方式。
宝珠标识.add-lore-result	节点	无	当前宝珠的附魔结果列表。每个子节点代表一个结果。

宝珠物品必须有显示名称，且显示名称需要与 name 匹配。目标物品必须有 Lore，且数量必须为 1。

message

宝珠可以单独配置消息：

'宝珠1':
  message:
    不可附魔: '该物品不可附魔该宝珠.'
    附魔成功: '附魔成功!'

配置键	说明
宝珠标识.message.不可附魔	当前宝珠无法镶嵌到目标物品时发送。
宝珠标识.message.附魔成功	当前宝珠成功镶嵌后发送。

消息值设置为 none 时，不发送对应消息。

item-need-lore

item-need-lore 用于限制宝珠可以镶嵌的目标物品：

item-need-lore:
  - '&7可附魔宝珠位'
  - '&7特殊宝珠插槽'

目标物品的 Lore 中只要存在任意一行匹配内容，就可以通过该条件检查。配置中的 & 会转换为 Minecraft 颜色代码，比较时不区分大小写。

remove-default-lore

值	行为
false	要求目标物品包含 item-need-lore 中的 Lore，并将附魔结果添加到匹配 Lore 后方。已有宝珠 Lore 会被移除。
true	优先查找当前宝珠已有的附魔 Lore，以便替换当前宝珠结果；没有找到时也会尝试匹配 item-need-lore。匹配到的基础 Lore 会被移除，新的结果会添加到对应位置。

插件通过内部标记识别已经添加的宝珠 Lore。重新镶嵌时，会清理当前宝珠对应的旧 Lore，再写入新的随机结果。

附魔结果

附魔结果配置在 add-lore-result 下：

add-lore-result:
  '结果1':
    weight: 10
    replace-name: '&6荣耀宝珠'
    condition:
      - 'permission:{789.砍崽}'
      - 'papi:{%player_level% >= 30}'
    nbt:
      测试NBT: '这是一个NBT节点'
    lore:
      - '&7物理伤害 +{200~400~%.0f}'
    command:
      - '[console]bc &a%player_name%&7附魔了一颗荣耀宝珠'

配置键	类型	默认值	说明
add-lore-result.结果标识.weight	整数	1	结果权重。只有所有条件满足的结果才会参与权重计算。
add-lore-result.结果标识.replace-name	字符串	无	触发该结果后，将目标物品显示名称替换为此值。支持 & 颜色代码。不配置时保留原名称。
add-lore-result.结果标识.condition	字符串列表	空列表	结果触发条件。所有条件都满足时，该结果才会参与随机选择。
add-lore-result.结果标识.nbt	节点	无	为目标物品添加或修改 NBT 字符串值。当前实现支持单层键值。
add-lore-result.结果标识.lore	字符串列表	空列表	镶嵌成功后添加到目标物品的 Lore。支持颜色代码、随机数和表达式计算。
add-lore-result.结果标识.command	字符串列表	空列表	结果触发后执行的命令。支持 PlaceholderAPI 占位符和执行者前缀。

权重选择

插件先检查每个结果的条件，再将条件满足的结果权重相加，最后按照权重随机选择一个结果。

• 条件不满足的结果不会参与权重计算。
• 未配置 condition 的结果默认视为满足条件。
• 未配置 weight 时，权重为 1。
• 如果没有任何结果满足条件，可能无法生成附魔结果，因此应至少配置一个可满足条件的结果。

条件配置

条件写在 condition 字符串列表中。一个结果中的多个条件必须全部满足。

条件格式	说明
permission:{权限节点}	玩家拥有指定权限时通过。
nopermission:{权限节点}	玩家没有指定权限时通过。
papi:{表达式}	先解析 PlaceholderAPI 占位符，再计算逻辑或比较表达式。
roll:{概率}	按百分比进行随机判断，例如 roll:{10} 表示 10% 概率通过。

示例：

condition:
  - 'permission:{789.砍崽}'
  - 'nopermission:{example.blocked}'
  - 'papi:{%player_level% >= 30}'
  - 'roll:{10}'

papi 表达式

papi 条件依赖 PlaceholderAPI 解析占位符。表达式支持以下比较和逻辑运算：

• 数值比较：>、>=、<、<=
• 相等比较：==、!=
• 逻辑与：&&
• 逻辑或：||
• 数学运算：+、-、*、/
• 布尔值：true 或 false
• 字符串相等比较：使用单引号或双引号包裹字符串

示例：

condition:
  - 'papi:{%player_level% >= 30 && %player_level% < 60}'
  - 'papi:{%player_name% == "玩家名称" || %player_level% >= 100}'

Lore 数值占位

lore 和 NBT 字符串值支持使用 {最小值~最大值~格式} 生成随机数：

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

格式	说明
{200~400~%.0f}	在 200 到 400 范围内生成随机数，并按 %.0f 格式化。
{20~40~%.2f}	在 20 到 40 范围内生成随机数，并保留两位小数。

随机数会在结果生成时计算，每次镶嵌都可能得到不同数值。

Lore 表达式计算

lore 和 NBT 字符串值还支持使用 <表达式~格式> 计算数值。表达式中的 PlaceholderAPI 占位符会先被替换，然后进行数学计算：

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

支持的数学运算符包括：

• 加法：+
• 减法：-
• 乘法：*
• 除法：/
• 括号：(、)

表达式内部可以继续嵌套随机数格式，例如：

lore:
  - '&7数值：<{100~200~%.0f}*%player_level%~%.0f>'

表达式格式中的第二部分必须是 Java String.format 支持的数字格式，例如 %.0f 或 %.2f。

NBT 配置

nbt 用于为目标物品添加或修改 NBT 值：

nbt:
  自定义标记: '宝珠结果'
  数值文本: '{1~10~%.0f}'

当前实现通过 NMS 接口写入字符串类型 NBT，并支持单层键值。NBT 值同样支持 PlaceholderAPI 占位符、随机数格式和表达式计算。

NBT 写入依赖服务端版本对应的 NMS 接口。若控制台提示 NBT 接口初始化失败，依赖 NBT 写入的结果不能正常生效。

命令执行

结果触发后，插件按配置顺序执行 command 中的命令：

command:
  - '[console]bc &a%player_name%&7附魔成功'
  - '[player]say 我获得了宝珠'
  - '[op]give %player_name% diamond 1'

前缀	执行者	说明
[console]	控制台	以控制台身份执行命令。
[player]	玩家	以玩家身份执行命令。
[op]	玩家	临时给予玩家管理员身份执行命令，执行完成后恢复原状态。
无前缀	玩家	按玩家身份执行命令。

命令会先经过 PlaceholderAPI 处理，因此可以使用玩家相关占位符。前缀只影响执行身份，不属于最终命令内容。

配置加载

插件启动时会加载默认 config.yml。核心模块启用时，还会扫描 pearls/ 目录及其子目录中的所有 .yml 文件，并加载其中的宝珠配置。

修改配置后，可以使用管理员权限执行：

/lybz reload

重载会重新读取全局配置，并重新加载宝珠文件。配置文件中的 YAML 缩进、键名或数据格式错误可能导致对应内容无法正常加载。

支持版本

项目提供以下服务端版本对应的 NMS 实现：

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

插件启动时会根据服务端 Bukkit 版本初始化对应的 NBT 接口。如果初始化失败，控制台会提示 初始化API失败!，此时与 NBT 写入相关的配置不能正常使用。

可选软依赖

插件声明了以下软依赖：

插件	用途
PlaceholderAPI	解析条件、Lore、NBT 和命令中的占位符；使用 papi 条件或相关占位符时需要安装。
GermPlugin	支持在 GermPlugin GUI 槽位中进行宝珠镶嵌；未安装时，普通背包点击处理仍由插件自身监听。