宝珠配置

LyPearls 通过宝珠物品名称识别宝珠，并将随机结果写入目标物品的 Lore、显示名称和 NBT。宝珠结果可以使用权重、权限、PlaceholderAPI 表达式和随机概率进行筛选。

宝珠配置文件位于插件数据目录的 pearls/ 文件夹中。插件会递归读取该目录及其子目录中的所有 .yml 文件，每个文件可以包含多个顶层宝珠节点。

插件版本：1.0.4

支持版本

项目内置了以下服务端版本的 NMS 实现：

Minecraft 版本
`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`

依赖插件

插件	类型	用途
PlaceholderAPI	软依赖	解析 `papi` 条件、Lore 数值公式、NBT 数值公式和指令变量
GermPlugin	软依赖	提供 Germ GUI 槽位中的宝珠镶嵌功能

PlaceholderAPI 仅在使用相关功能时需要安装，并且对应变量扩展必须可以正常解析。GermPlugin 未启用时，插件不会注册 Germ GUI 监听器。

镶嵌机制

宝珠镶嵌通过玩家光标上的物品和当前点击的目标物品完成：

宝珠必须拥有显示名称。
插件只通过显示名称识别宝珠，不检查材质、Lore 或其他物品属性。
宝珠名称匹配时忽略英文字母大小写，并将 & 颜色代码转换为 Minecraft 颜色代码。
目标物品必须拥有 Lore。
目标物品堆叠数量必须为 1。
目标物品必须包含 item-need-lore 中的任意一行完整 Lore。
成功镶嵌后消耗光标宝珠堆中的一个物品。
新结果会替换旧的 LyPearls 宝珠 Lore，不会叠加多组宝珠结果。
replace-name 存在时会直接替换目标物品的显示名称。
成功镶嵌后，插件会执行结果中的指令并发送成功消息。

普通背包功能仅处理标题为 container.crafting 的玩家个人背包界面。GermPlugin 功能处理 Germ GUI 的槽位点击。

完整结构

yaml

"宝珠1":
  name: "&e荣耀宝珠"
  message:
    不可附魔: "该物品不可附魔该宝珠."
    附魔成功: "附魔成功!"
  item-need-lore:
    - "&7可附魔宝珠位"
  remove-default-lore: false
  add-lore-result:
    "结果1":
      weight: 10
      replace-name: "&6荣耀装备"
      condition:
        - "permission:{example.use}"
        - "papi:{%player_level% >= 30}"
      nbt:
        宝珠类型: "荣耀"
      lore:
        - "&7上等附魔【&e荣耀宝珠&7】"
        - "&7物理伤害 +{200~400~%.0f}"
        - "&7暴击几率 +<60*%player_level%~%.2f>%"
      command:
        - "[console]bc &a%player_name% &7镶嵌了荣耀宝珠"

一个文件可以包含多个顶层宝珠节点，也可以将不同宝珠拆分到不同文件。所有已加载文件中的顶层节点 ID 应保持唯一。相同 ID 会覆盖之前加载的配置，最终结果取决于文件加载顺序。

基础配置

yaml

"宝珠1":
  name: "&e荣耀宝珠"
  item-need-lore:
    - "&7可附魔宝珠位"
  remove-default-lore: false

配置项	类型	必填	默认值	说明
顶层节点	字符串	是	无	宝珠 ID，用于区分不同宝珠
`name`	字符串	是	无	宝珠物品的显示名称，支持 `&` 颜色代码
`item-need-lore`	字符串列表	是	无	目标物品允许镶嵌时必须拥有的 Lore 列表
`remove-default-lore`	布尔值	否	`false`	是否删除匹配到的基础 Lore
`message`	配置节点	否	使用全局消息	当前宝珠的消息覆盖配置
`add-lore-result`	配置节点	是	无	当前宝珠可随机得到的结果列表

顶层节点 ID

顶层节点名称是宝珠配置 ID，不是玩家手持宝珠的显示名称。插件通过 name 匹配玩家手中的宝珠，通过顶层节点 ID 管理加载结果和宝珠配置。

不同宝珠不要配置相同的 name。名称相同的宝珠无法通过显示名称区分，实际匹配结果取决于宝珠遍历顺序。

宝珠名称匹配

name 中的 & 会转换为 Minecraft 颜色代码。
匹配时忽略英文字母大小写。
只检查显示名称。
不检查物品材质、Lore、数量或 NBT。

`item-need-lore` 匹配

item-need-lore 使用任意一行完整匹配规则。目标物品只要包含其中任意一行 Lore，就可以进入镶嵌流程。

yaml

item-need-lore:
  - "&7可附魔宝珠位"
  - "&8可镶嵌特殊宝珠"

匹配规则如下：

配置中的 & 会转换为 Minecraft 颜色代码。
Lore 必须整行相同。
不支持包含匹配和正则表达式。
匹配时忽略英文字母大小写。
目标物品必须拥有 Lore。
目标物品数量大于 1 时不会触发镶嵌。

`remove-default-lore`

配置值	处理方式
`false`	保留匹配到的基础 Lore，并在该行后插入宝珠结果 Lore
`true`	删除匹配到的基础 Lore，并在对应位置写入宝珠结果 Lore

插件会在写入新结果前清理旧的宝珠标记 Lore。

在 1.0.4 中，普通背包监听的旧宝珠识别标记与结果写入标记不完全一致。使用 remove-default-lore: true 时，基础 Lore 被首次删除后，再次镶嵌可能无法找到可写入位置。需要重复覆盖宝珠时，建议使用 remove-default-lore: false。

消息配置

全局消息位于 config.yml：

yaml

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

宝珠文件可以覆盖全局消息：

yaml

message:
  不可附魔: "&c该物品不可镶嵌此宝珠。"
  附魔成功: "&a宝珠镶嵌成功。"

配置项	触发时机
`message.不可附魔`	宝珠名称匹配，但目标物品没有符合要求的 Lore
`message.附魔成功`	宝珠成功消耗并写入结果后

消息规则：

支持 & 颜色代码。
配置为 none 时不发送对应消息，不区分大小写。
宝珠配置中存在对应消息时，优先使用宝珠自己的消息。
删除宝珠配置中的对应消息项后，使用 config.yml 中的全局消息。

结果配置

add-lore-result 下的每个节点代表一种可能出现的镶嵌结果。

yaml

add-lore-result:
  "结果1":
    weight: 10
    replace-name: "&6荣耀装备"
    condition:
      - "permission:{example.use}"
    nbt:
      宝珠类型: "荣耀"
    lore:
      - "&7上等附魔【&e荣耀宝珠&7】"
    command:
      - "[console]bc &a%player_name% &7镶嵌了荣耀宝珠"

配置项	类型	必填	默认值	说明
结果节点	字符串	是	无	结果 ID，仅用于区分同一宝珠下的不同结果
`weight`	整数	否	`1`	结果进入随机池后的权重
`replace-name`	字符串	否	不修改	镶嵌后替换目标物品的显示名称
`condition`	字符串列表	否	无条件	结果加入随机池前需要满足的条件
`nbt`	键值节点	否	不写入	镶嵌后写入目标物品的 NBT 键值
`lore`	字符串列表	否	空列表	镶嵌后写入目标物品的宝珠 Lore
`command`	字符串列表	否	空列表	镶嵌完成后依次执行的指令

权重计算

插件先检查每个结果的条件，只将条件全部通过的结果加入权重总和，然后从可用结果中随机选择一个。

例如两个可用结果的权重分别为 10 和 5，理论比例约为：

结果	权重	理论比例
结果一	10	约 66.67%
结果二	5	约 33.33%

建议将 weight 配置为正整数。所有结果都不满足条件，或所有可用结果权重都为 0 时，可能无法取得有效结果。

`replace-name`

yaml

replace-name: "&6荣耀装备"

配置存在时，插件会在镶嵌完成后直接替换目标物品的显示名称。删除该配置项即可保留原名称。

replace-name 支持 & 颜色代码。插件不会自动保留原物品名称，也没有可确认的原名称变量。

条件

yaml

condition:
  - "permission:{example.use}"
  - "nopermission:{example.blocked}"
  - "papi:{%player_level% >= 30}"
  - "roll:{10}"

同一结果中的条件按全部满足处理。任意一条条件失败，该结果就不会加入权重统计。

条件格式	说明
`permission:{权限节点}`	玩家必须拥有指定权限
`nopermission:{权限节点}`	玩家不能拥有指定权限
`papi:{表达式}`	解析 PlaceholderAPI 变量并判断表达式
`roll:{几率}`	按百分比执行一次随机判定

条件前缀注意事项

1.0.4 的条件识别代码使用前缀位置大于 0 的判断。因此，以下直接从字符串开头填写的条件可能不会进入对应检查流程，并被当作通过条件处理：

yaml

condition:
  - "permission:{example.use}"
  - "nopermission:{example.blocked}"
  - "papi:{%player_level% >= 30}"
  - "roll:{10}"

在该问题修复前，不要将结果条件作为权限隔离、防刷限制或其他安全校验的唯一依据。

`roll`

yaml

condition:
  - "roll:{10}"

roll:{10} 会生成 0 至 100 之间的随机数，并在配置值大于随机数时通过，理论通过率约为 10%。建议将几率配置在 0 至 100 之间。

`papi` 表达式

papi 条件会先解析 PlaceholderAPI 变量，再判断表达式。

类型	支持内容
数值比较	`>`、`>=`、`<`、`<=`、`==`、`!=`
逻辑运算	`&&`、`
数学运算	`+`、`-`、`*`、`/`、`(`、`)`
字符串比较	使用单引号或双引号包裹后进行 `==`、`!=` 比较
布尔值	没有比较运算符时，仅 `true` 会被视为通过

yaml

condition:
  - "papi:{%player_level% >= 30}"
  - "papi:{%player_health% > 10 && %player_level% >= 20}"
  - "papi:{'%player_world%' == 'world'}"
  - "papi:{(%player_level% + 10) / 2 >= 20}"

表达式会先按 || 分段，再按 && 判断。字符串字面量中的空格会保留，字符串外的普通空格会被移除。

Lore 数值

结果 Lore 支持颜色代码、范围随机数和数学公式。

yaml

lore:
  - "&7物理伤害 +{200~400~%.0f}"
  - "&7暴击几率 +{20~40~%.2f}%"
  - "&7等级加成 +<60*%player_level%~%.2f>%"

Lore 在生成随机值和公式结果后，再将 & 转换为 Minecraft 颜色代码。

范围随机数

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

部分	说明
`最小值`	随机范围下限，支持整数或小数
`最大值`	随机范围上限，支持整数或小数
`格式`	Java 数字格式，例如 `%.0f`、`%.2f`

yaml

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

随机值按照最小值加上随机比例乘以范围差计算，最大值通常不会被直接取到。

公式计算

格式：<公式~格式>

yaml

lore:
  - "&7等级加成 +<60*%player_level%~%.2f>%"
  - "&7最终伤害 +<{200~400~%.0f}*%player_level%~%.0f>"

处理顺序如下：

解析公式中的范围随机数。
解析公式中的 PlaceholderAPI 变量。
使用数学表达式计算结果。
按指定格式输出数值。

公式支持整数、小数、+、-、*、/ 和括号。数学表达式解析时会过滤无法识别的字符，因此应只填写数字和支持的运算符。

每一行 Lore 最多处理约 50 次随机数替换和 50 次公式替换。

NBT 配置

结果节点提供 nbt 配置，用于向目标物品写入字符串 NBT：

yaml

nbt:
  宝珠类型: "荣耀"
  宝珠数值: "{100~200~%.0f}"

NBT 值支持与 Lore 相同的随机数、公式、PlaceholderAPI 和颜色代码处理流程。配置形式为当前节点下的单层键值，不支持嵌套对象。

当前 1.0.4 读取 NBT 值时使用了 nbt 节点路径，而不是具体键路径。为 nbt 添加实际键值可能导致配置加载异常，或无法取得预期值。该问题修复前，不建议使用 nbt 配置。

指令配置

yaml

command:
  - "[console]bc &a%player_name% &7镶嵌了荣耀宝珠"
  - "[op]example command"
  - "[player]spawn"

前缀	执行身份
`[console]`	服务器后台
`[op]`	临时给予玩家 OP 后，以玩家身份执行
`[player]`	以玩家当前身份执行
无前缀	以玩家当前身份执行

指令执行顺序如下：

处理 PlaceholderAPI 变量。
写入 Lore、显示名称和 NBT。
消耗一个宝珠。
按配置顺序执行所有结果指令。
发送成功消息。

其他规则：

指令不需要填写 /。
[console] 的判断优先级高于 [op]。
[op] 会记录玩家原本的 OP 状态。
非 OP 玩家执行 [op] 指令后会恢复为非 OP。
玩家原本是 OP 时，执行完成后不会取消其 OP。
不包含 [console] 或 [op] 时，按玩家身份执行。

配置加载与重载

插件启动时会保存默认配置和 pearls/示例宝珠.yml，然后读取插件数据目录中的配置文件：

text

plugins/LyPearls/config.yml
plugins/LyPearls/pearls/

pearls/ 目录及其子目录中的所有 .yml 文件都会被递归读取。修改配置后可以使用以下命令重载：

指令	权限要求	说明
`/lybz`	OP	查看重载提示
`/lybz reload`	OP	重载全局配置并重新读取宝珠文件

插件的 plugin.yml 没有声明独立权限节点，命令权限直接通过发送者是否为 OP 判断。

配置限制

宝珠通过显示名称识别，不验证物品类型，必须避免宝珠名称冲突。
目标物品必须拥有 Lore，且堆叠数量必须为 1。
item-need-lore 使用完整行匹配，不支持模糊匹配。
每次成功镶嵌只消耗光标宝珠堆中的一个物品。
再次镶嵌会清除插件标记的旧宝珠 Lore，不会叠加多组结果。
replace-name 会直接覆盖物品显示名称。
结果条件和权重配置不当时，可能无法取得有效结果。
使用 PlaceholderAPI 条件、公式或指令变量时，必须安装 PlaceholderAPI 并安装对应变量扩展。
GermPlugin GUI 功能只有在 GermPlugin 已启用时才会注册。
remove-default-lore: true 在 1.0.4 中可能导致再次镶嵌无法找到写入位置。
nbt 配置在 1.0.4 中存在读取路径问题，不建议启用。
permission、nopermission、papi 和 roll 条件在 1.0.4 中存在前缀识别问题，不应作为唯一安全校验。

宝珠配置 ​

支持版本 ​

依赖插件 ​

镶嵌机制 ​

完整结构 ​

基础配置 ​

顶层节点 ID ​

宝珠名称匹配 ​

item-need-lore 匹配 ​

remove-default-lore ​

消息配置 ​

结果配置 ​

权重计算 ​

replace-name ​

条件 ​

条件前缀注意事项 ​

roll ​

papi 表达式 ​

Lore 数值 ​

范围随机数 ​

公式计算 ​

NBT 配置 ​

指令配置 ​

配置加载与重载 ​

配置限制 ​

宝珠配置

支持版本

依赖插件

镶嵌机制

完整结构

基础配置

顶层节点 ID

宝珠名称匹配

`item-need-lore` 匹配

`remove-default-lore`

消息配置

结果配置

权重计算

`replace-name`

条件

条件前缀注意事项

`roll`

`papi` 表达式

Lore 数值

范围随机数

公式计算

NBT 配置

指令配置

配置加载与重载

配置限制