常见问题
插件支持哪些服务端版本？
项目内提供了以下 NMS 适配模块：
1.7.101.8.81.11.21.12.21.13.21.14.41.15.21.16.51.17.11.18.21.19.21.19.41.20.11.20.21.20.3
请确认服务端版本与插件使用的 NMS 适配版本一致。
/lgr 指令没有反应
插件注册的主指令是 /lgr，当前代码中提供以下子指令：
| 指令 | 用途 | 使用限制 |
|---|---|---|
/lgr | 查看帮助信息 | 仅 OP 会显示帮助 |
/lgr reload | 重载插件配置和数据 | 仅 OP 可用 |
/lgr inlay | 打开宝石镶嵌与拆卸界面 | 需要由玩家执行，不要求 OP |
如果控制台执行 /lgr inlay，不会打开界面，因为该功能要求执行者是玩家。
插件没有在 plugin.yml 中声明独立权限节点，重载功能直接检查执行者是否为 OP。
宝石无法镶嵌到装备上
按以下顺序检查：
- 装备 Lore 中是否存在宝石配置
slot内的槽位 Lore。 - 宝石名称是否与
gem-name精确匹配。 - 宝石 Lore 中是否存在与
gem-lore精确匹配的行。 - 宝石配置中的槽位 Lore 是否与装备 Lore 完全一致。
- 宝石是否满足
condition中的所有条件。 - 当前玩家是否有足够金币。
- 是否触发了装备、宝石的禁止镶嵌 Lore。
- 是否触发了玩家当前的宝石数量上限。
宝石匹配名称和 Lore 时使用精确匹配。名称或 Lore 配置为空时，对应项目不会参与匹配；名称和 Lore 同时配置时，两者都必须满足。
提示“该宝石无法镶嵌在该装备上”
该提示对应 inlay-gem-not-to-item，表示插件没有找到可匹配的宝石槽位。
检查以下内容：
- 装备是否有 Lore。
- 装备 Lore 是否包含宝石配置
slot中的任意一行。 - 颜色代码、空格和尖括号内容是否一致。
- 宝石配置中的槽位 Lore 是否写在装备上，而不是只写在开孔器配置中。
例如，配置中的槽位为 &7<绿宝石槽位> 时，装备 Lore 必须包含完全相同的内容。配置文件中的尖括号内容应写在代码或配置文本中，不能随意改动。
宝石名称或 Lore 明明正确，仍然提示宝石错误
宝石必须同时满足以下条件：
- 物品有显示名称。
- 显示名称与某个宝石配置的
gem-name匹配；如果该项为空，则不检查名称。 - 物品 Lore 中存在与某个宝石配置的
gem-lore匹配的行；如果该项为空，则不检查 Lore。
插件会遍历所有宝石配置。请确认不同宝石的识别条件不会重复，否则可能匹配到其他宝石配置。
提示装备禁止镶嵌
检查配置中的 the-item-exist-lore-prevent-inlay。
当装备 Lore 包含其中任意一行时，镶嵌会被拦截，并发送 the-item-exist-lore-prevent-inlay 对应的消息。
默认配置会拦截包含以下 Lore 的装备：
yaml
the-item-exist-lore-prevent-inlay:
- '未绑定'该检查使用 Lore 行的完全匹配，配置中的颜色代码和空格也会影响结果。
提示宝石禁止镶嵌
检查配置中的 the-gem-exist-lore-prevent-inlay。
当宝石 Lore 包含其中任意一行时，镶嵌会被拦截，并发送 the-gem-exist-lore-prevent-inlay 对应的消息。
默认配置会拦截包含以下 Lore 的宝石：
yaml
the-gem-exist-lore-prevent-inlay:
- '未绑定'镶嵌界面无法正常放入物品
检查 gui-auto-slot-mode-enable 当前值：
| 配置值 | 交互方式 |
|---|---|
true | 快捷模式。点击玩家背包中的物品时，自动放入装备槽、宝石槽或额外道具槽；点击这些槽位时自动放回背包 |
false | 旧版手动模式，保留手动拿起和放入物品的交互方式 |
快捷模式下：
- 宝石会自动放入宝石槽。
- 额外道具会自动放入额外道具槽。
- 其他普通物品会自动放入装备槽。
- 拆卸工具不会自动放入额外槽位，需要使用拆卸工具点击宝石。
关闭镶嵌界面后物品不见了
关闭界面时，装备、宝石和额外道具槽位中的物品会尝试放回玩家背包。
如果背包没有空间，插件会将无法放入的物品掉落在玩家当前位置，并发送背包空间不足提示。请检查玩家脚下和附近地面。
隐藏属性没有生效
隐藏属性需要同时满足以下条件：
- 在
attribute-plugin中填写实际使用的属性插件名称。 - 在
attribute-slot中填写玩家实际装备物品所在的槽位。 - 宝石配置中的
load-item-lore-attribute设置为true。 - 属性插件已安装并正常运行。
- 对应槽位格式与外部装备插件的实际槽位格式一致。
项目支持以下 attribute-plugin 配置值：
| 配置值 | 对应属性插件 |
|---|---|
AttributePlus | AttributePlus |
SX-Attribute2 | SX-Attribute2 |
SX-Attribute3 | SX-Attribute3 |
AttributeSystem | AttributeSystem |
ItemLoreOrigin | ItemLoreOrigin |
修改 attribute-plugin 后需要重启插件或服务器，具体以配置注释为准。
attribute-slot 应该怎么填写？
attribute-slot 用于指定插件读取装备的位置。格式取决于装备栏或背包插件：
| 类型 | 格式 |
|---|---|
| DragonCore | DragonCore#槽位名 |
| GermPlugin | GermPlugin#槽位名 |
| APInventory | APInventory#分页ID#槽位ID |
| LyInventory | LyInventory#背包ID#类型 |
| LyInventoryReload | LyInventoryReload#背包ID#类型 |
| PXRPG | PXRPG#类型#背包ID#槽位 |
| 原版主手 | Origin#MainHand |
| 原版副手 | Origin#OffHand |
| 原版头盔 | Origin#Helmet |
| 原版胸甲 | Origin#ChestPlate |
| 原版护腿 | Origin#Legging |
| 原版靴子 | Origin#Boots |
| 原版背包槽位 | Minecraft#槽位ID |
例如，原版主手配置为：
yaml
attribute-slot:
- 'Origin#MainHand'如果配置了错误的槽位，插件不会读取该位置的镶嵌宝石属性。
装备属性没有及时刷新
插件会在以下事件后刷新属性：
- 玩家加入服务器后延迟刷新。
- 关闭背包或镶嵌界面后刷新。
- 切换快捷栏物品后刷新。
- 玩家切换主副手后刷新。
如果装备来自外部背包插件，请确认该插件提供的槽位可以被 attribute-slot 正确读取。
配置了隐藏属性，但装备 Lore 中看不到
attribute 配置产生的是隐藏属性数据，不一定会显示在装备 Lore 中。
如果希望属性直接显示在装备 Lore 中，可以使用宝石配置的 show-lore。如果希望通过属性插件读取隐藏属性，则使用 attribute，并将 load-item-lore-attribute 设置为 true。
另外，宝石配置中的 load-item-lore 设置为 true 时，镶嵌宝石物品的全部 Lore 也会被加载到属性插件中。
属性配置中的随机数或变量没有生效
宝石的 attribute、show-lore、额外道具结果等文本支持变量替换和区间计算。相关表达式会在镶嵌成功时计算。
请检查：
- 表达式是否使用两个数值范围和格式部分。
- 变量替换后是否仍然是可计算的数值。
- 小数格式是否以
%.开头，例如%.1f。 - 公式中是否只使用支持的四则运算和括号。
镶嵌成功率如何计算？
宝石配置中的 chance 为基础成功率。额外道具可以通过 chance: 结果增加成功率。
插件会将宝石基础成功率和额外道具增加的成功率相加后进行判定。镶嵌失败时，宝石和额外道具仍会被扣除，失败指令会执行。
镶嵌失败后金币和物品如何处理？
如果宝石配置中的 eco 大于 0：
- 先检查玩家金币是否足够。
- 金币足够时扣除配置数量。
- 随后进行镶嵌成功率判定。
因此，即使最终镶嵌失败，只要已经通过金币检查，金币也已经扣除。宝石和额外道具同样会在判定前扣除。
提示金币不足
该提示对应 inlay-eco-error。请检查：
- 宝石配置中的
eco是否大于0。 - Vault 及对应经济插件是否正常工作。
- 玩家账户余额是否达到
eco配置值。 - 经济插件是否在当前服务器正常启用。
插件通过经济接口检查和扣除金币。
镶嵌条件没有生效
宝石配置的 condition 会逐项检查，所有条件都满足后才允许镶嵌。
项目中可以确认的条件格式包括：
| 条件格式 | 判断内容 |
|---|---|
permission:{权限节点} | 玩家拥有指定权限 |
nopermission:{权限节点} | 玩家没有指定权限 |
papi:{表达式} | 使用 PlaceholderAPI 替换变量后计算表达式 |
gem-amount:{宝石ID<数量} | 检查装备上指定宝石的数量 |
gem-amount 支持的比较符号包括 <、<=、==、>=、>。条件不满足时会提示 inlay-condition-error。
玩家最多只能镶嵌固定数量
检查以下配置：
yaml
placeholder-inlay-enable: true
placeholder-inlay:
默认:
max-inlay: 2
condition: []启用后，插件会按照配置顺序检查条件，并使用第一个满足条件的配置。不会继续使用后面的配置。
建议将限制严格、条件复杂的配置放在前面，将默认配置放在最后。例如 OP、等级条件应放在无条件的默认项之前。
如果当前镶嵌数量达到选中的 max-inlay，会提示 placeholder-inlay 配置对应的消息。
拆卸工具无法拆卸宝石
检查以下内容：
- 宝石配置中的
can-disassembled是否为true。 - 拆卸工具名称是否与拆卸工具配置中的
name匹配。 - 拆卸工具的
disassembled-gem是否包含当前宝石 ID，或是否包含*。 - 是否使用拆卸工具点击了正确的宝石显示行。
- 玩家背包是否有空位。
拆卸工具的 chance 决定拆卸成功率。拆卸成功后，如果 return-gem 为 true，还会按照 return-gem-chance 判定是否返还原宝石。
拆卸工具提示使用错误
该提示对应 out-item-error，表示点击宝石时使用的物品名称没有匹配到任何拆卸工具配置。
拆卸工具通过显示名称匹配，不是通过配置节点名称匹配。请检查物品显示名称、颜色代码和空格是否与 name 完全一致。
宝石无法拆卸
如果宝石配置中的：
yaml
can-disassembled: false该宝石会被视为不可拆卸宝石，即使玩家使用了正确的拆卸工具，也会提示无法拆卸。
开启强制拆卸后仍然无法拆卸
检查配置：
yaml
force-out-gem-enable: true开启后，点击镶嵌界面中的宝石即可尝试拆卸，不需要将拆卸工具放入界面。
强制拆卸模式仍会检查宝石配置中的 can-disassembled。不可拆卸宝石不会被移除。
关闭强制拆卸后应该如何使用拆卸工具？
当 force-out-gem-enable 为 false 时，需要：
- 手持拆卸工具。
- 打开
/lgr inlay镶嵌界面。 - 将装备放入装备槽。
- 使用拆卸工具点击装备上的目标宝石。
拆卸工具会消耗一个。拆卸成功率由工具配置中的 chance 决定。
开孔器无法使用
开孔器是在生存背包内手持并点击目标装备使用的，不是放入镶嵌界面的额外道具槽。
检查以下配置：
| 配置项 | 检查内容 |
|---|---|
name | 开孔器物品名称是否匹配 |
need-name | 目标装备名称是否在允许列表中；删除该项则不限制装备名称 |
need-lore | 目标装备是否包含指定前置 Lore |
max-count | 装备记录的开孔使用次数是否已达到上限 |
result | 是否配置了可生成的槽位 Lore |
开孔提示达到使用次数上限
开孔使用次数会记录在装备数据中，每次使用开孔器都会增加一次计数。
当当前次数达到开孔器的 max-count 时，会触发 slot-max 消息。该限制针对装备记录，不是针对玩家持有的开孔器数量。
开孔失败后没有增加槽位
开孔结果按照 result 中各项的 weight 随机选择。配置为失败结果时，lore 为空，不会增加宝石槽位。
请确认：
result中至少存在一个带 Lore 的成功结果。- 各结果的
weight已正确填写。 - 生成的 Lore 与宝石配置中的
slot完全一致。 need-lore如果配置了内容，目标装备确实包含该 Lore。
配置了 need-lore 时，成功开孔会替换目标装备中的一行前置 Lore；未配置 need-lore 时，会直接插入新的槽位 Lore。
额外道具没有生效
额外道具需要放入镶嵌界面的额外道具槽，并且物品显示名称必须匹配 额外道具.yml 中的 name。
额外道具支持以下结果类型：
| 结果前缀 | 作用 |
|---|---|
attribute: | 按概率增加隐藏属性 |
lore: | 按概率增加显示属性 Lore |
chance: | 增加本次镶嵌成功率 |
message: | 镶嵌成功后向玩家发送消息 |
额外道具只会在镶嵌成功后处理 attribute、lore 和 message 结果。镶嵌失败时不会产生这些成功效果。
镶嵌成功后没有执行指令
检查宝石配置中的 success-command 或 fail-command。
指令支持以下前缀：
| 前缀 | 执行身份 |
|---|---|
[console] | 控制台执行 |
[op] | 临时以 OP 身份由玩家执行 |
| 无前缀 | 由玩家执行 |
指令中的 PlaceholderAPI 变量会先替换，{gem} 和 {item} 也会由插件替换为当前宝石名称和装备名称。
镶嵌成功后全服没有收到消息
只有宝石配置中存在 server-message 内容时，镶嵌成功后才会向在线玩家发送全服消息。
请检查：
server-message是否为列表格式。- 文本中使用的变量是否正确。
- 镶嵌是否确实判定成功，而不是只打开了界面或通过了条件检查。
PlaceholderAPI 变量没有替换
项目将 PlaceholderAPI 作为软依赖使用。涉及变量的功能包括：
- 宝石成功或失败指令。
- 宝石成功后的全服消息。
- 宝石属性和 Lore 计算。
papi:{表达式}条件。placeholder-inlay的条件判断。
请确认 PlaceholderAPI 已安装并正常加载，并且所使用的变量扩展已经安装。未安装或未注册对应变量时，表达式可能无法得到预期结果。
修改配置后没有生效
部分配置和数据会在插件加载时读取。修改配置后可以由 OP 执行：
text
/lgr reload如果修改的是 attribute-plugin，配置文件注释明确要求重启。遇到属性插件适配、NMS 或外部背包槽位相关问题时，建议直接重启服务器确认加载状态。
镶嵌界面按钮显示内容不正确
检查 config.yml 中的 gui 配置，尤其是：
| 配置项 | 用途 |
|---|---|
gui.title | 镶嵌界面标题 |
gui.button-name | 镶嵌按钮名称 |
gui.button-lore | 按钮 Lore，可显示 {eco} 和 {chance} |
gui.gem-add-lore | 镶嵌后显示的宝石信息格式 |
gui.fill-item | 普通填充物品 |
gui.equip-item | 装备区域填充物品 |
gui.gem-item | 宝石区域填充物品 |
gui.buff-item | 额外道具区域填充物品 |
{eco} 和 {chance} 只用于界面显示，不会替代宝石配置本身的金币和成功率计算。
物品镶嵌后数据异常或无法读取
插件会将镶嵌数据写入装备的 NBT，并保存宝石物品、宝石 ID、槽位名称和属性数据。
如果装备被其他插件重新生成、覆盖 NBT、序列化失败或经过不兼容的物品处理，可能导致插件无法读取原有镶嵌数据。出现“获取宝石数据失败”类控制台错误时，请确认该装备没有被其他插件重建或清除 NBT。