排错与调试

宝石类插件最难排查的问题是静默失效：镶嵌成功了，也没报错，但装备上什么都没变。本页按「先看什么、再看什么」的顺序整理排查路径。

排查三步

/sgem reload
/sgem compat all

/sgem debug Reward,GemManager      # 镶嵌相关
/sgem debug Skill,SkillExec        # 技能相关
/sgem debug Menu,Workbench         # 菜单相关
/sgem debug Buff                   # 常驻 BUFF

/sgem debug all      # 恢复输出全部 tag
/sgem debug          # 切换总开关

debug tag 清单

/sgem debug <tag>[,<tag>] 可只看指定范围。

也可以在 config.yml 里持久化：

Debug: true
DebugTags: [Reward, GemManager]

静默失效的常见原因

按遇到频率排序。

1. Attribute 的 limit 与 var 方向不同号

症状：属性宝石镶嵌「成功」，提示也发了，但装备属性没变。

limit 是「能加到的极限值」，不是「加多少次」。减法必须配负 limit：

# 错：第一次算出 -0.1，被 coerce 夹回 0.3 以内，等于没变化
- Attribute{name=scale;operation=0;slot=any;var=v-0.1;limit=0.3}
# 对
- Attribute{name=scale;operation=0;slot=any;var=v-0.1;limit=-0.3}

排查：/sgem debug Reward，日志会打印 Attribute(scale) 未生效: 已叠加值=0.0 已达上限或无变化(limit=0.3)。

2. BUFF 宝石与 BUFF 定义的标记不一致

症状：BUFF 宝石镶嵌成功，装备 lore 上也有那行字，但没有任何效果。

宝石 LoreAdd{lore=...} 写的文本必须和 BUFF 定义的 Lore: 一致（去色后比较）。

排查：/sgem debug Buff，如果日志里从来没有「命中 BUFF 定义」，就是标记对不上。

3. 技能行漏写触发标记

症状：技能完全不触发。

# 错：没有 ~onUse，永远不会被触发
- Blink{distance=32} @Forward
# 对
- Blink{distance=32} ~onUse @Forward

排查：配置自检会直接报「这一行没有写触发标记，永远不会被触发」。

4. 技能定义没写 Lore

症状：装备拿在手里，技能不触发。

技能靠装备 lore 文本绑定。Lore 留空的定义不会被任何装备触发（只能作为 Switch 的目标形态或被 Reward{} 嵌套调用）。

5. PlayerGem 用了作用于物品的奖励

症状：右键饮用/使用后，提示发了但没效果。

PlayerGem 没有目标物品，不能用 Attribute、Enchant、LoreAdd、Unbreakable 等。只能用 MaxHealth、ExpLevel、Point、Money、ItemGive、ItemTake。

排查：/sgem debug Reward，日志会打印「本次操作没有目标物品」。

6. 用了当前版本不存在的内容

症状：某些宝石在 A 服正常，在 B 服无效。

排查：/sgem compat 对比两个服的能力清单。这属于正常行为，不是 bug。

7. $LORE: 引用的标记与自身 Lore 不一致

症状：可叠加等级的 BUFF 等级永远是 1，不涨。

抗性提升:
  Lore: "&6&l[&c&lBUFF&6&l] &b&l抗性提升 "
  Skills:
    # $LORE: 里必须写去色后的形式，且和上面 Lore 一致
    - Potion{type=resistance;level=$LORE:[BUFF] 抗性提升?1$} ~onTimer

8. 改了配置没重载

只有 lang.yml 是热重载的（保存即生效）。config.yml、gems/、skills/、gui/ 都需要 /sgem reload。

不生效但不是 bug 的情况

这几种「没变化」是插件的有意设计，避免玩家白吃宝石：

日志里会明确写「视为未生效」，不用怀疑是坏了。

已知的不生效字段

以下字段会被解析，但代码里没有任何地方读取它们做判断——写了不起作用：

菜单类型里的 PAGE_PREV、PAGE_NEXT、PAGE_TIP 同理——它们和 TIP 的行为完全一样（纯装饰），是为将来的翻页功能预留的名字。

报错日志怎么读

「配置自检发现 N 处写错的条目」

后面跟着 [文件.yml -> 宝石ID] 函数{参数} -> 原因。想看完整明细：

• /sgem compat all
• 或把 config.yml 的 Compat.OnMissingFeature 改成 warn

「配置中有 N 处内容当前版本不支持，已跳过」

正常提示，不是错误。想看是哪些，用 /sgem compat all。

「未注册的技能函数: XXX —— 你是不是想写: YYY?」

函数名拼错了，按建议改。全部函数用 /sgem skills 查。

「Require 条目 'XXX' 既不是当前版本的物品名，也不是可用的分类关键字」

分类关键字拼错。可用分类清单在同一条日志的括号里，也可用 /sgem compat all 查看。

「附魔 XXX 不在当前版本的注册表中」

用现代命名空间 ID（小写下划线，如 unbreaking、sharpness），或确认这个附魔需要更高版本。

数据存在哪里

排查数据丢失问题时可能需要：

性能问题

症状：在线人数多时 TPS 下降。

BUFF 引擎每秒对每个在线玩家扫 6 个物品槽 × 所有带 Lore 的技能定义。定义数量大（几百个）叠加高在线人数会有可观开销。

排查与缓解：

1. /sgem reload 后看控制台的「已加载 N 个技能/BUFF 定义，带 Lore 标记可触发的共 M 个」——M 才是每秒参与扫描的数量
2. 删掉不用的 BUFF 定义，别留着
3. 一次性效果用事件触发标记（~onUse 等），不要用 ~onTimer
4. 避免 Repeat 配很短的 interval 用在高频触发的技能上

求助时请提供

如果自己排查不出来，提供这些信息能大幅加快定位：

1. /sgem compat all 的完整输出
2. 开对应 tag 后完整操作一次的日志（不要只截结尾）
3. 相关宝石/技能的配置片段
4. 服务端版本与实现（Paper/Leaves/Purpur + 具体版本号）