宝石配置

宝石定义放在 plugins/SnowyGems/gems/ 下，文件名任意，插件加载目录里所有 .yml 与 .yaml。文件名会成为 /sgem view 的分类名，所以建议按用途分文件。

一个最小可用的宝石：

生命宝石:                      # 宝石 ID，全局唯一，命令里用它
  Name: 生命宝石
  Require:
    - ARMOR                   # 只能镶嵌到盔甲上
  Display: "&c&l生命宝石"       # 物品显示名
  Tips:
    - "&7镶嵌后生命上限 +1"
  Material: REDSTONE
  SuccessTip: "&f生命上限&c&l+1"
  Rewards:
    - action: Attribute
      name: health
      operation: 0
      slot: auto
      var: "v+1"
      limit: 5

字段表

以下是插件实际会读取的全部字段，其余字段写了会被静默忽略。

想直接安装并测试整套玩法，可查看新功能宝石示例：包含九颗宝石、两项技能及完整 YAML 下载。

数量、互斥与一次性消耗品

基于默认生命宝石修改的完整示例，可放入 gems/custom.yml。与它互斥的另一颗宝石使用不同 ID、相同 ExclusiveGroup 即可。

限定生命宝石:
  Name: 限定生命宝石
  Material: REDSTONE
  Display: "&c限定生命宝石"
  Require: [ARMOR]
  Embed: 2
  ExclusiveGroup: health-style
  Rewards:
    - action: Attribute
      name: health
      operation: 0
      slot: auto
      var: "v+1"
      limit: 5

同一装备最多记录两颗该宝石，成功时每颗 +1。预览和实际执行都会检查；批量镶嵌逐颗重新校验，前一颗可能改变后一颗的适用条件，不保证整批同时成功。

默认修复石使用 TrackApplied: false。纯修复、金币等不可撤销效果，即使没有写 false，也不生成新的可拆卸实例。混合了可撤销和不可撤销效果的宝石可能有记录，但不能保证拆卸返还，详见拆卸规则。

技能隐藏粉尘已支持隐藏后继续触发技能；先拆粉尘，再修改其他已镶嵌宝石。隐藏文本恢复到 Lore 末尾，不保证原行位置。

Require：宝石能镶到什么上

Require 是列表，命中任意一条即通过（OR 语义）。留空表示任何物品都行。

分类关键字不是硬编码的清单，而是启动时读服务端注册表建的索引。所以 1.21.11 的矛会自动落进 WEAPON/MELEE/SPEAR，铜盔甲会自动落进 ARMOR——你不需要改配置。矛是近战、突刺和蓄力武器，不属于 RANGED。完整清单用 /sgem compat all 查看。

Require:
  - WEAPON        # 任意武器
  - TOOL          # 或任意工具
  - SHIELD        # 或盾牌

Rewards：宝石实际做什么

Rewards 是对象列表。每项写 action: 函数名，其余字段是函数参数。旧版的 函数名{参数1=值;参数2=值} 文本行继续兼容；下方函数速查表保留旧文本示例以便对照。新写法与转换步骤见新语法、迁移与游戏内编辑器。

奖励与拆卸

Rewards 只描述镶嵌或使用时的效果。phase: remove 与旧行尾 $onRemove 不再执行；拆卸价格与返还成功率统一由独立的 dismantle/ 方案控制。

Rewards:
  - action: LoreAdd
    lore: "&6&l[&c&lBUFF&6&l] &b&l发光"
  # 新镶嵌的 LoreAdd 会记录并自动撤销，不需要再次手写删除相同标记

每条 Rewards 相互独立，其中一条没生效不会中断后面的条目。

函数清单

Command 的 YAML 写法：- action: Command、command: "bc 恭喜 %player_name%"、as: console。as 可用 console 或 player（默认）；命令不需要开头的 /。支持 %player_name%、%player% 和 %uuid%。需要先确认前面的奖励生效再执行命令时，加 requireEffect: true。旧参数 commands 与 console: true 仍可读取。命令奖励无法撤销，不能用于需要拆卸返还的宝石。

Point 随机点券

0.0.7 修订构建修复了随机点券表达式算出小数时，PlayerPoints 拒绝交易的问题。Point 的 amount 可以写固定数值或随机表达式，旧函数行继续兼容。

Rewards:
  - action: Point
    amount: "100+2900*$RANDOM()"

表达式只计算一次，交易前向零取整：例如 1696.5883017572096 实际发放 1696 点券，-12.9 实际扣除 12 点券。Internal 与 PlayerPoints 的 Point 奖励使用相同整数，玩家提示与实际交易数额一致；Money 仍支持小数。

$RANDOM() 的范围是 [0,1)，所以上例实际获得 100～2999 点券。如果需要包含 3000，把表达式改为 100+2901*$RANDOM()。已有随机兑换券无需修改配置即可恢复使用。

取整后为 0、非有限数或绝对值超过 2147483647 时，本条奖励不生效；如果整张兑换券没有其他生效奖励，则不消耗。PlayerPoints 不可用或交易被拒绝时仍按失败处理，不切换内置账户。

Attribute 详解

这是最常用也最容易写错的函数。

Rewards:
  - action: Attribute
    name: health
    operation: 0
    slot: auto
    var: "v+1"
    limit: 5

slot 可选值：head chest legs feet hand off_hand any_hand（任意手持）armor（任意盔甲位）any（任意装备/手持槽位，不包含普通背包格）auto（按物品类型自动推断，推荐）。

- Attribute{name=scale;operation=0;slot=any;var=v-0.1;limit=-0.3}

常用属性简写：

旧版 Bukkit 常量名（如 GENERIC_MAX_HEALTH）与现代注册表键（如 max_health、minecraft:scale）也都能直接写。完整清单见多版本兼容。

表达式语法

Attribute.var、LoreVar.var、Enchant.var 和 Point/Money 的 amount 支持简单表达式。附魔的 level 与 limit、Attribute.limit 和数量等参数仍读取为固定数值，不能一概写表达式：

多等级宝石常用三元实现「只能从低级升到高级」：

# 生命恢复 II：当前小于 2 就设为 2，否则设为 3
- LoreVar{lore=&b生命恢复 ;var=v<2?2:3;format=%.0f;mode=last}

附魔一次提升两级

Enchant.var: "v+2" 从当前附魔等级计算新等级，例如 0→2、1→3；limit 限制最终等级。省略 var 时保持每次 +1。level 是固定目标等级，同时写 level 和 var 时以 level 为准。拆卸时按镶嵌时记录的实际等级变化回退。

二级耐久宝石:
  Name: 二级耐久宝石
  Material: EMERALD
  Display: "&b二级耐久宝石"
  Require: [WEAPON, ARMOR, TOOL]
  Rewards:
    - action: Enchant
      name: DURABILITY
      var: "v+2"
      limit: 7

二级锋利宝石:
  Name: 二级锋利宝石
  Material: REDSTONE
  Display: "&c二级锋利宝石"
  Require: [SWORD]
  Rewards:
    - action: Enchant
      name: DAMAGE_ALL
      var: "v+2"
      limit: 10

旧式动作可写 Enchant{name=DURABILITY;var=v+2;limit=7}。下载四颗二级强化示例宝石，其中还包含速度与力量 BUFF。var: "2" 表示直接设置为 2 级，与在当前等级上加 2 不同。

LoreAdd / LoreVar 的 mode 与 locator

三种宝石类型

镶嵌类（默认）

不写 Type 即是。玩家在镶嵌台里把宝石和装备放在一起，点确认生效。

PlayerGem：右键直接生效

作用于玩家自己，不需要目标装备。用于兑换券、饮品。

蛇胆:
  Name: 蛇胆
  Type: PlayerGem
  Display: "&c&l蛇胆"
  Tips:
    - "&7饮用后永久增加&c1&7点生命"
  Material: "POTION"
  Color: "MAROON"
  Eat: true                    # 需要「喝」的动作，不是右键
  SuccessTip: "&f生命上限永久&c&l+1"
  Rewards:
    - MaxHealth{amount=1;limit=30} $onSuccess

RandomGem：开箱抽奖

右键后按权重抽一个子宝石；GiveItem: true 发物品，默认 false 当场执行子宝石奖励。权重是相对值，不需要凑成 100。

新版宝石礼包:
  Name: 新版宝石礼包
  Type: RandomGem
  Display: "&e&l新版宝石礼包"
  Tips:
    - "&7右键开启，随机获得一颗宝石"
  Material: CHEST
  GiveItem: true              # 礼包发物品；不写则执行子宝石 Rewards
  Glow: true
  SuccessTip: "none"           # none = 不发默认消息，由子宝石自己提示
  Gems:
    缩小宝石: 20
    延伸之瞳: 15
    密度宝石: 3
    战锤大师宝石: 1

子宝石必须是已存在的宝石 ID，可以来自任何 gems/ 文件。

BUFF 类宝石：与技能定义配对

BUFF 宝石的原理是：往装备 lore 里写一行标记，BUFF 引擎每秒扫描装备，命中标记就施加对应效果。

两边必须成对配置：

发光药水:
  Name: 发光药水
  Require:
    - WEAPON
    - ARMOR
  Display: "&e&l发光药水"
  Tips:
    - "&7镶嵌后获得发光效果"
  SuccessTip: "&f装备添加&e&l发光&fBUFF"
  Rewards:
    - LoreAdd{lore=&6&l[&c&lBUFF&6&l] &b&l发光}   # ← 这里

发光:
  Lore: "&6&l[&c&lBUFF&6&l] &b&l发光"              # ← 必须一致
  Skills:
    - Potion{type=GLOWING} ~onTimer

可叠加等级的 BUFF 用 LoreVar 写数字，BUFF 定义那边用 $LORE:标记?默认值$ 读回来：

Rewards:
  - LoreVar{lore=&6&l[&c&lBUFF&6&l] &b&l抗性提升 ;var=v+1;format=%.0f;mode=last}

抗性提升:
  Lore: "&6&l[&c&lBUFF&6&l] &b&l抗性提升 "
  Skills:
    - Potion{type=DAMAGE_RESISTANCE;level=$LORE:[BUFF] 抗性提升?1$} ~onTimer

$LORE: 里的标记要写去掉颜色码的形式。

若要每次提升两级，将 LoreVar 的 var 改为 "v+2"。例如内置速度 BUFF 对应的宝石奖励：

二级速度BUFF宝石:
  Name: 二级速度BUFF宝石
  Material: SUGAR
  Display: "&b二级速度BUFF宝石"
  Require: [ARMOR]
  Rewards:
    - action: LoreVar
      lore: "&6&l[&c&lBUFF&6&l] &b&l速度"
      var: "v+2"
      format: "%.0f"
      mode: "last"

skills/DefaultBuffs.yml 已有速度的 PotionBuff 定义，会读取该 Lore 的等级。LoreVar 的 v 是此 Lore 前缀对应的插件累计值。它目前没有可撤销的拆卸记录，请在测试装备上确认效果后再投入使用。

完整示例：新版本内容宝石

gems/ModernGem.yml 里有 27 颗覆盖新版本内容的示例宝石，可直接抄改：

缩小宝石:
  Name: 缩小宝石
  Require:
    - ARMOR
  Display: "&d&l缩小宝石"
  Tips:
    - "&7穿戴后体型缩小 &d10%"
    - "&8需要 1.20.5+ 服务端"
  Material: AMETHYST_SHARD
  Glow: true
  SuccessTip: "&f体型&d&l-10%"
  Rewards:
    - Attribute{name=scale;operation=0;slot=any;var=v-0.1;limit=-0.3}

密度宝石:
  Name: 密度宝石
  Require:
    - MACE                     # 1.21+ 才有锤
  Display: "&8&l密度宝石"
  Tips:
    - "&7锤的下砸伤害随高度增幅更高"
    - "&8需要 1.21+ 服务端(锤)"
  Material: HEAVY_CORE
  Glow: true
  SuccessTip: "&f密度等级&8&l+1"
  Rewards:
    - Enchant{name=density;limit=5}

铜匠宝石:
  Name: 铜匠宝石
  Require:
    - COPPER_*                 # 整套铜装备
  Display: "&6&l铜匠宝石"
  Tips:
    - "&7专为铜装备设计"
    - "&8需要 1.21.9+ 服务端"
  Material: COPPER_INGOT
  SuccessTip: "&f铜装备已强化"
  Rewards:
    - Enchant{name=unbreaking;limit=5}
    - Attribute{name=armor;operation=0;slot=auto;var=v+1;limit=4}

战锤大师宝石:
  Name: 战锤大师宝石
  Require:
    - MACE
  Display: "&8&l战锤大师宝石"
  Tips:
    - "&7密度+穿透+风爆一次到位"
  Material: HEAVY_CORE
  Glow: true
  Success: 40                  # 40% 成功率
  SuccessTip: "&f锤已成为神话武器"
  FailTip: "&c镶嵌失败了..."
  Rewards:
    - Enchant{name=density;limit=5}
    - Enchant{name=breach;limit=4}
    - Enchant{name=wind_burst;limit=3}
    - Attribute{name=safe_fall;operation=0;slot=hand;var=v+3;limit=9}

突进宝石:
  Name: 突进宝石
  Require:
    - SPEAR                    # 匹配全部材质的矛
  Display: "&e&l突进宝石"
  Tips:
    - "&7为矛的突进等级 +1(上限3级)"
    - "&8需要 1.21.11+ 服务端(矛)"
  Material: BREEZE_ROD
  Glow: true
  SuccessTip: "&f矛突进等级&e&l+1"
  Rewards:
    - Enchant{name=lunge;limit=3}    # lunge 是矛在 1.21.11 的专属附魔

低版本服务端上这些宝石会被自动跳过并在控制台说明，不影响其他宝石。

gems/ModernGem.yml 里与矛相关的示例有三颗：长矛精通宝石（攻击力 + 攻击距离）、突进宝石（lunge 上限 3）、真突进宝石（lunge 上限 10，80% 成功率）。

验证配置

改完配置后：

1. /sgem reload 重载
2. 看控制台。如果有写错的条目，插件会报「配置自检发现 N 处写错的条目」
3. /sgem compat all 查看自检明细，包括「当前版本不支持所以跳过」和「写错了」两类

自检会区分这两类：版本不支持是正常状态（同一份配置发到不同版本的子服），只记 Debug 日志；名字拼错、函数不存在则任何版本都不会生效，会明确报出来。需要逐条警告用 warn；需要拒绝错误配置用 strict，失败后修正配置再重载。

本次工作台与消耗更新

符文完整配置和操作见工作台与符文镶嵌。Gui 限制在预览和执行处都会检查，装备一次只处理一件。

随机宝石支持 GiveItem: true：抽中的子宝石作为物品发放；缺省 false：执行抽中子宝石的 Rewards。权重 0 不参与抽取，负权重会报告配置问题，权重总和按长整数计算。随机宝石自身的 Success 也会判定，概率失败消耗一颗。

直接使用与 /sgem use 使用同一扣除流程：先预留一颗再发奖，未产生效果或条件不通过时退回；概率失败消耗一颗。奖励执行出现异常时可能已有外部副作用，此时不保证返还凭证，应查看日志。

Eat: true 只用于 PlayerGem/RandomGem。主手、副手食用都由插件统一处理，原版吃喝被取消，因此不会再扣第二颗，也不会额外产生原版饥饿值、药水效果或空瓶；需要的效果请写入 Rewards。/sgem use 仍可直接使用此类物品。