宝石规则
LyGemReload 通过装备 Lore 识别宝石槽位，并将镶嵌记录保存到装备 NBT。镶嵌、拆卸、开孔和额外道具均围绕物品名称、Lore 与配置 ID 工作。
镶嵌流程
玩家通过 /lgr inlay 打开镶嵌与拆卸界面。界面的主要槽位如下：
| 槽位 | 用途 |
|---|---|
37 | 放置待镶嵌或待拆卸的装备。 |
39 | 放置宝石。 |
41 | 放置本次镶嵌使用的额外道具。 |
43 | 执行镶嵌，并显示本次消耗与成功率。 |
0-26 | 展示装备中已经镶嵌的宝石，最多展示 27 个。 |
装备必须拥有 Lore，并且数量必须为 1。插件会按以下顺序处理镶嵌：
- 根据宝石的
gem-name与gem-lore识别宝石。 - 检查装备是否存在该宝石允许使用的槽位 Lore。
- 检查装备与宝石是否包含禁止镶嵌的 Lore。
- 检查变量镶嵌上限。
- 检查额外道具是否合法。
- 检查宝石的全部
condition。 - 检查并扣除
eco金币。 - 消耗一颗宝石；存在额外道具时同时消耗一个额外道具。
- 计算最终成功率并执行随机判定。
- 成功时替换槽位 Lore、保存宝石数据、执行成功指令并发送消息；失败时执行失败指令并发送失败消息。
金币会在成功率判定前扣除。镶嵌失败不会返还宝石、额外道具或金币。
界面交互模式
config.yml 的 gui-auto-slot-mode-enable 控制界面交互方式。
| 值 | 行为 |
|---|---|
true | 快捷模式。点击玩家背包中的普通物品会放入装备槽，宝石会放入宝石槽，额外道具会放入额外道具槽；点击三个主要槽位会尝试将物品放回背包。 |
false | 手动模式。玩家需要按原版背包操作方式拿起并放置物品。 |
快捷模式会根据已加载的配置识别宝石、额外道具和拆卸工具。拆卸工具不会自动进入界面槽位，需要由玩家拿在鼠标上点击已镶嵌宝石。
关闭界面时，装备槽、宝石槽和额外道具槽中的物品会自动返回玩家背包。背包已满时，无法放入的物品会掉落在玩家脚下。
宝石配置
宝石配置放在插件目录的 gem/ 中。插件会递归读取该目录下的 .yml 文件。每个文件可以定义多个宝石，文件顶层节点为宝石 ID。
宝石 ID 全局不可重复。宝石镶嵌后，ID 会写入装备数据，因此正式使用后不要随意修改或复用 ID。
| 节点 | 类型 | 说明 |
|---|---|---|
slot | 字符串列表 | 可以镶嵌该宝石的槽位 Lore。装备必须至少存在一行完全相同的 Lore。 |
gem-name | 字符串 | 用于识别宝石的物品名称。名称必须完全一致；留空或删除时不检查名称。 |
gem-lore | 字符串 | 用于识别宝石的 Lore 文本。宝石任意一行 Lore 包含该文本即可；留空或删除时不检查 Lore。 |
show-name | 字符串 | 镶嵌成功后替换槽位时显示的宝石名称。 |
show-lore | 字符串列表 | 镶嵌成功后追加在 show-name 下方的显示 Lore。支持 PlaceholderAPI 变量、随机值和公式。 |
chance | 数值或公式 | 基础镶嵌成功率。通常使用 0-1，支持 PlaceholderAPI 变量与四则运算。 |
eco | 整数 | 镶嵌前需要检查并扣除的金币。为 0 时不处理经济。 |
can-disassembled | 布尔值 | 是否允许从装备上拆卸该宝石。 |
condition | 字符串列表 | 镶嵌条件，列表中的条件必须全部满足。 |
server-message | 字符串列表 | 镶嵌成功后发送给所有在线玩家的消息。 |
success-command | 字符串列表 | 镶嵌成功后执行的指令。 |
fail-command | 字符串列表 | 镶嵌失败后执行的指令。 |
attribute | 字符串列表 | 镶嵌成功时生成并保存到装备 NBT 的隐藏属性。 |
load-item-lore-attribute | 布尔值 | 是否将该次镶嵌保存的 attribute 提交给已配置的属性插件。 |
load-item-lore | 布尔值 | 是否将镶嵌时保存的原宝石物品 Lore 提交给已配置的属性插件。 |
完整结构如下：
yaml
示例宝石1:
slot:
- '&7<绿宝石槽位>'
- '&7<红宝石槽位>'
gem-name: '&6示例宝石'
gem-lore: '&7这是一颗示例宝石'
show-name: '&7已镶嵌<&6神奇的示例宝石&7>'
show-lore:
- '&7 这是一颗示例宝石'
chance: 1
eco: 1
can-disassembled: true
condition:
- 'papi:{%player_level% > 0}'
- 'gem-amount:{示例宝石1<1}'
server-message:
- '&7恭喜 &a%player_name% &7成功镶嵌了一颗 &6{gem} &7!'
success-command:
- '[console]tell %player_name% 你镶嵌了一颗{gem}成功.'
fail-command:
- '[op]tell %player_name% 你镶嵌了一颗{gem}失败.'
attribute:
- '&b生命加成 +{10-20-%.1f}%'
load-item-lore-attribute: true
load-item-lore: true宝石识别规则
gem-name 和 gem-lore 可以单独使用，也可以同时使用。
| 配置方式 | 识别行为 |
|---|---|
只配置 gem-name | 只检查物品显示名是否完全一致。 |
只配置 gem-lore | 只检查物品是否有一行 Lore 包含指定文本。 |
| 两项都配置 | 名称与 Lore 必须同时匹配。 |
| 两项都留空 | 该配置会跳过名称与 Lore 限制，可能匹配到不应作为宝石的物品。 |
镶嵌界面要求宝石拥有显示名。因此即使 gem-name 留空，实际投入界面的宝石仍需要带有自定义名称。
槽位匹配与替换
slot 中的每一项都是可用槽位 Lore。例如：
yaml
slot:
- '&7<绿宝石槽位>'
- '&7<红宝石槽位>'装备中只要存在其中一行完全相同的 Lore，即可使用该槽位。镶嵌成功后：
- 命中的槽位 Lore 会被移除。
- 原位置会插入
show-name和全部show-lore。 - 插入的每一行都会附带用于定位该次镶嵌记录的隐藏标识。
- 原槽位文本会保存到装备 NBT，拆卸成功后恢复到原位置。
- 同一装备存在多个可用槽位时，插件使用首先匹配到的宝石槽位。
插件会把每次镶嵌的宝石 ID、原宝石物品、原槽位名称和隐藏属性保存到装备 NBT。不要使用会清除未知 NBT 的物品编辑方式处理已镶嵌装备，否则可能造成宝石记录丢失。
镶嵌成功率
chance 使用小数表示概率：
| 配置 | 含义 |
|---|---|
0 | 不会成功。 |
0.1 | 约 10% 成功率。 |
0.5 | 约 50% 成功率。 |
1 | 必定成功。 |
插件没有将结果强制限制在 0-1：计算结果大于等于 1 时会成功，结果小于等于 0 时不会成功。
chance 支持 PlaceholderAPI 变量以及 +、-、*、/、括号运算。例如：
yaml
chance: '%player_level%*0.01'计算失败时，控制台会输出玩家、宝石 ID 和错误公式，本次计算结果保持为 0。
额外道具的 chance: 效果会直接加到宝石基础成功率上。界面按钮显示的是宝石基础成功率，不包含额外道具提供的成功率。
镶嵌条件
condition 是字符串列表。存在多个条件时，所有条件都必须通过。空列表表示不限制。
| 写法 | 说明 |
|---|---|
permission:{权限节点} | 玩家必须拥有指定权限。 |
nopermission:{权限节点} | 玩家必须没有指定权限。 |
papi:{表达式} | 替换 PlaceholderAPI 变量后判断表达式。 |
gem-amount:{宝石ID<数量} | 统计当前装备中指定宝石 ID 的数量并比较。 |
尖括号只用于表示比较运算符，实际配置应写在代码格式中，例如 gem-amount:{示例宝石1<1}。
宝石数量条件
gem-amount 支持以下比较符：
| 比较符 | 示例 | 说明 |
|---|---|---|
< | gem-amount:{示例宝石1<1} | 已镶嵌数量小于 1。可用于限制唯一宝石。 |
<= | gem-amount:{示例宝石1<=2} | 已镶嵌数量小于等于 2。 |
== | gem-amount:{示例宝石1==1} | 已镶嵌数量等于 1。 |
>= | gem-amount:{示例宝石1>=1} | 已镶嵌数量大于等于 1。 |
> | gem-amount:{示例宝石1>1} | 已镶嵌数量大于 1。 |
统计依据是装备 NBT 中保存的宝石 ID，不是装备当前显示的 Lore。
PAPI 表达式
papi: 条件会先替换 PlaceholderAPI 变量，再执行判断。可使用：
- 数值比较：
>、<、>=、<=、==、!=。 - 数值运算：
+、-、*、/和括号。 - 逻辑与：
&&。 - 逻辑或：
||。 - 使用单引号或双引号包裹的字符串相等与不相等比较。
- 不带比较符时，只有结果为
true才会通过。
yaml
condition:
- 'papi:{%player_level% >= 50 && %player_health% > 10}'该功能依赖 PlaceholderAPI。表达式中的占位符必须能够返回适合比较的内容。
指令与消息替换
宝石的 success-command 和 fail-command 支持以下执行方式：
| 写法 | 执行身份 |
|---|---|
[console]指令 | 控制台执行。 |
[op]指令 | 临时以 OP 身份让玩家执行，执行完成后恢复原状态。 |
| 无前缀指令 | 玩家直接执行。 |
可确认的替换内容如下：
| 内容 | 适用位置 | 说明 |
|---|---|---|
| PlaceholderAPI 变量 | 成功指令、失败指令、全服消息 | 按触发镶嵌的玩家解析。 |
{gem} | 成功指令、失败指令、全服消息 | 替换为宝石配置的 gem-name。 |
{item} | 成功指令、失败指令 | 替换为装备显示名；没有显示名时使用物品材质名。 |
拆卸工具的 success-command 固定由控制台执行，支持 PlaceholderAPI 变量和 {gem}，但不处理 [console] 或 [op] 前缀。
随机属性与随机 Lore
attribute、show-lore 和额外道具结果支持随机值写法：
text
{最小值-最大值-格式}例如：
yaml
attribute:
- '&b生命加成 +{10-20-%.1f}%'
- '&b物理伤害 +{35-105-%.0f}'
- '&6等级神力 +{%player_level%*2-%player_level%*5-%.0f}'| 部分 | 说明 |
|---|---|
最小值 | 随机范围下限，支持 PlaceholderAPI 变量和四则运算。 |
最大值 | 随机范围上限，支持 PlaceholderAPI 变量和四则运算。 |
格式 | Java 数字格式，例如 %.0f、%.1f。省略时使用 %.0f。 |
随机结果按 最小值 + 随机数 ×（最大值 - 最小值） 生成。PlaceholderAPI 变量会在计算前替换。
隐藏属性在镶嵌成功时计算一次并保存到装备中，之后不会随玩家变量变化而重新生成。
隐藏属性加载
宝石可以同时提供两类属性来源：
| 来源 | 控制节点 | 内容 |
|---|---|---|
| 隐藏属性 | load-item-lore-attribute | 加载镶嵌时保存的 attribute。 |
| 原宝石 Lore | load-item-lore | 加载镶嵌时保存的原宝石物品全部 Lore。 |
插件只会扫描 config.yml 中 attribute-slot 指定的装备位置。玩家加入、关闭背包、切换手持槽位和交换主副手时会刷新属性；属性列表未变化时会跳过重复提交。
可配置的属性插件名称包括：
AttributePlusSX-Attribute2SX-Attribute3AttributeSystemItemLoreOrigin
attribute-plugin 修改后需要重启服务器。具体槽位格式与属性插件设置参见配置页面。
开孔道具
开孔道具在 开孔道具.yml 中配置。使用时，玩家需要在生存背包中拿起开孔器，左键点击目标装备。
目标装备必须满足以下要求：
- 拥有物品元数据与 Lore。
- 数量为
1。 - 名称符合
need-name限制。 - 存在
need-lore指定的前置 Lore，或该配置为空。 - 已使用开孔器的次数小于
max-count。
| 节点 | 类型 | 说明 |
|---|---|---|
name | 字符串 | 开孔器物品名称，必须完全匹配。 |
max-count | 整数 | 单件装备最多成功触发该开孔流程的累计次数。计数保存在装备 NBT 中。 |
need-name | 字符串列表 | 允许使用该开孔器的装备名称。装备名称包含列表中的任意文本即可；删除或留空列表时不限制名称。 |
need-lore | 字符串 | 必须存在的前置 Lore。完全匹配；为空时直接在装备 Lore 末尾插入结果。 |
result | 节点组 | 按权重随机抽取的开孔结果。 |
开孔结果
| 节点 | 说明 |
|---|---|
weight | 当前结果的抽取权重。所有结果按相对权重参与随机。 |
message | 抽中结果后发送给玩家的消息列表。 |
lore | 插入装备的 Lore 列表。每一行都可作为一个宝石槽位。空列表可用于制作失败结果。 |
yaml
普通开孔器:
max-count: 10
need-name:
- '牛马装备'
need-lore: ''
name: '&b普通开孔器'
result:
失败:
weight: 30
message:
- '&7开槽失败……'
lore: []
绿宝石:
weight: 10
message:
- '&a恭喜你开启了绿宝石槽位'
lore:
- '&7<绿宝石槽位>'开孔器通过检测后会消耗一个，并将装备上的开孔次数增加 1。即使随机结果的 lore 为空，该次使用仍会消耗开孔器并累计次数。
当 need-lore 不为空时，插件只替换首先找到的一行前置 Lore；当结果含有多行 lore 时，会在该位置一次加入多个槽位。
拆卸规则
拆卸会删除指定宝石的镶嵌记录，并将原槽位 Lore 恢复到装备中。装备数量必须为 1，玩家背包还需要至少一个空位。
宝石自身的 can-disassembled 必须为 true，否则无论使用何种普通拆卸工具都不能拆卸。
使用拆卸工具
force-out-gem-enable: false 时，需要拿起拆卸工具点击界面上方 0-26 槽位内的已镶嵌宝石。
| 节点 | 类型 | 说明 |
|---|---|---|
name | 字符串 | 拆卸工具物品名称，必须完全匹配。 |
chance | 小数 | 拆卸成功率，默认 1。 |
return-gem | 布尔值 | 拆卸成功后是否有机会返还原宝石物品。 |
return-gem-chance | 小数 | 启用返还后，返还宝石的概率，默认 1。 |
success-command | 字符串列表 | 拆卸成功后由控制台执行的指令。 |
disassembled-gem | 字符串列表 | 允许拆卸的宝石 ID；* 表示全部宝石。 |
yaml
普通拆卸工具:
name: '&a普通拆卸工具'
chance: 0.5
return-gem: true
return-gem-chance: 0.5
success-command:
- 'tell %player_name% 你拆卸了{gem}'
disassembled-gem:
- '*'匹配到拆卸工具后，插件会先消耗一个工具，再进行成功率判定。拆卸成功不代表一定返还宝石，返还还需要同时满足 return-gem 与 return-gem-chance。
无工具拆卸
force-out-gem-enable: true 时，玩家可以直接点击已镶嵌宝石进行拆卸：
- 不需要拆卸工具。
- 不进行拆卸成功率判定。
- 不读取拆卸工具的宝石 ID 限制。
- 不执行拆卸工具的成功指令。
- 会直接返还镶嵌时保存的原宝石物品。
- 仍然受宝石
can-disassembled限制。
额外道具
额外道具在 额外道具.yml 中配置，只影响放入额外道具槽后的本次镶嵌。成功率判定前会读取 chance:，其他效果只在镶嵌成功后处理。
| 节点 | 类型 | 说明 |
|---|---|---|
name | 字符串 | 额外道具物品名称，必须完全匹配。 |
result | 字符串列表 | 本次镶嵌需要执行的效果。 |
| 效果写法 | 说明 |
|---|---|
chance:数值 | 将数值加到宝石基础镶嵌成功率。数值支持随机值与公式计算。 |
attribute:概率,属性 | 镶嵌成功后按概率生成内容，并加入该次宝石保存的隐藏属性。 |
lore:概率,Lore | 当前实现同样会把结果加入该次宝石保存的隐藏属性，不会直接追加到装备显示 Lore。 |
message:文本 | 镶嵌成功后向玩家发送消息，支持 & 颜色代码。 |
yaml
镶嵌幸运符:
name: '&6镶嵌幸运符'
result:
- 'chance:0.1'
- 'message:&7本次镶嵌增加了10%成功率!'
隐藏力量增强器:
name: '&6隐藏力量增强器'
result:
- 'attribute:0.5,力量+{5-10-%.0f}'
- 'message:&7本次镶嵌成功使用了力量增强器!'attribute: 与 lore: 使用逗号分隔概率和内容，当前解析方式要求效果内容本身不要包含额外逗号。
配置多个 chance: 时，当前实现不会累计每一项，而是使用最后一次读取到的数值作为额外成功率。建议每个额外道具只配置一条 chance:。
变量镶嵌上限
启用 placeholder-inlay-enable 后，可以按玩家条件限制每件装备最多镶嵌的宝石数量。
插件按 placeholder-inlay 中的配置顺序检查分组，只使用第一个满足全部条件的分组。因此应将限制更特殊、条件更严格的分组写在前面，并在最后提供空条件的默认分组。
yaml
placeholder-inlay-enable: true
placeholder-inlay:
OP权限:
max-inlay: 999
condition:
- 'permission:{admin}'
大于50级:
max-inlay: 5
condition:
- 'papi:{%player_level% > 50}'
默认:
max-inlay: 2
condition: []| 节点 | 说明 |
|---|---|
max-inlay | 当前分组允许每件装备保存的最大宝石数量。 |
condition | 分组条件，支持 permission:、nopermission: 和 papi:。 |
如果没有任何分组通过，内部上限保持为 0，玩家将无法继续镶嵌。因此启用该功能时应保留一个 condition: [] 的默认分组。
禁止镶嵌 Lore
插件可以根据装备或宝石现有 Lore 阻止镶嵌：
| 配置项 | 说明 |
|---|---|
the-item-exist-lore-prevent-inlay | 装备 Lore 完整包含列表中的任意一行时禁止镶嵌。 |
the-gem-exist-lore-prevent-inlay | 宝石 Lore 完整包含列表中的任意一行时禁止镶嵌。 |
这里使用整行匹配，不是模糊包含。颜色代码和文本必须与物品实际 Lore 一致。
数据限制与注意事项
- 镶嵌记录保存在装备 NBT 中，不依赖物品当前显示名称判断已镶嵌内容。
- 界面最多展示 27 条已镶嵌记录，插件 API 获取宝石 ID 时同样最多返回 27 条。
- 宝石槽位、镶嵌显示内容和开孔次数都保存在单件装备上，因此装备堆叠数量大于
1时不会执行镶嵌、拆卸或开孔。 - 已镶嵌宝石的原物品会被序列化保存，用于界面展示和拆卸返还。
- 删除宝石配置后，装备中的历史记录不会自动消失，但界面无法再读取该宝石的当前配置；其可拆卸状态会按不可拆卸展示。
- 修改宝石 ID 会使已镶嵌装备中的旧记录无法关联到新配置。
load-item-lore-attribute与load-item-lore只控制属性插件加载，不决定装备上是否显示show-lore。- 经济消耗依赖 Vault 经济服务；为宝石设置大于
0的eco时，应确保 Vault 已成功连接经济插件。