SnowyGems

宝石配置

gems/ 目录下宝石的全部字段、Rewards 奖励函数、Require 适用范围写法与完整示例。

宝石配置

宝石定义放在 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:
    - Attribute{name=health;operation=0;slot=auto;var=v+1;limit=5}

顶层的键（这里的 生命宝石）就是宝石 ID，必须全局唯一——即使在不同文件里也不能重名，后加载的会覆盖先加载的。

字段表

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

字段	类型	说明
`Name`	文本	宝石内部名，不填则用 ID
`Type`	文本	不填=镶嵌类；`PlayerGem`=右键直接生效；`RandomGem`=开箱抽奖
`Require`	列表	可镶嵌到哪些物品上，OR 语义。见下文
`Display`	文本	宝石物品的显示名，支持 `&` 颜色码
`Tips`	列表	宝石物品的 lore
`Texture`	文本	头颅 base64 材质。填了会强制用 PLAYER_HEAD
`Material`	文本	不用头颅时的物品材质，默认 `PAPER`
`Color`	文本	皮革/药水染色，需配合 `Material: POTION` 等
`Glow`	布尔	是否附魔光效
`Eat`	布尔	`true` 则需要「饮用/食用」而非右键
`Success`	整数	成功率 0～100，默认 100；0 必定失败
`Embed`	整数	已解析但未用于限额，详见下方说明
`Gui`	列表	限定只能在哪些界面使用
`SuccessTip`	文本	成功提示。填 `none` 则不发消息
`RemoveTip`	文本	拆卸提示
`FailTip`	文本	失败提示
`Rewards`	列表	真正干活的部分，见下文
`Gems`	映射	仅 `RandomGem` 用：`子宝石ID: 权重`
`GiveItem`	布尔	RandomGem 为 true 时发放抽中宝石物品；false 时执行子宝石 Rewards

Embed 目前不生效。 这个字段会被解析并存进配置对象，但代码里没有任何地方读取它做判断——也就是说它既不限制镶嵌数量，也不影响拆卸费用。示例配置里写 Embed: 1 只是占位习惯。如果你需要「一件装备最多镶几颗」的限制，当前版本做不到，别指望这个字段。

Require：宝石能镶到什么上

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

写法	含义	例
分类关键字	按物品类别匹配	`WEAPON` `TOOL` `ARMOR` `SWORD` `PICKAXE` `MACE` `SPEAR` `RANGED` `MELEE` `HELMET` `BOOTS` …
`_后缀`	物品名以此结尾，任意材质	`_SWORD` 匹配石剑/铁剑/钻石剑
`前缀*`	物品名以此开头	`COPPER_*` 匹配整套铜装备
精确物品名	单一物品	`DIAMOND_SWORD`
`LORE:文本`	物品 lore 含指定文本	`LORE:传说`
`NOTHING` / `ALL` / `ANY`	无条件通过	—

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

矛是分材质命名的（WOODEN_SPEAR ~ NETHERITE_SPEAR 七种），没有单一的 SPEAR 材质。写分类关键字 SPEAR 就能匹配全部材质，不用逐个列出；该分类只表示矛类近战武器。

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

Rewards：宝石实际做什么

Rewards 是列表，每行是一个函数调用，语法 函数名{参数1=值;参数2=值}。

阶段标记

行尾可以加标记决定这条在什么时候执行：

标记	含义
`$onSuccess`	镶嵌成功时执行（默认，不写就是这个）
`$onRemove`	拆卸时执行，在自动撤销之后

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

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

拆卸不只跑 $onRemove。 拆卸时插件会先自动撤销每条奖励对装备的影响（移除属性修饰符、附魔降级），再执行 $onRemove 的条目。所以属性和附魔类宝石不需要手写撤销逻辑；新镶嵌的 LoreAdd / LoreReplace 支持局部撤销；LoreVar / Name 等没有通用撤销。旧装备没有实际变化历史，限制见查看与拆卸。

拆卸费用现在统一在 config.yml 的 Dismantle.Cost 配置，不再需要在每颗宝石里写 Point{amount=-1000} $onRemove。详见查看与拆卸宝石。

函数清单

函数	作用	示例
`Attribute`	属性加成，可叠加可回退	`Attribute{name=health;operation=0;slot=auto;var=v+1;limit=5}`
`Enchant`	附魔增删	`Enchant{name=unbreaking;limit=7}`
`LoreAdd`	加一行 lore	`LoreAdd{lore=&b强化装备;mode=after}`
`LoreVar`	加带数字的 lore，可叠加	`LoreVar{lore=&b等级 ;var=v+1;format=%.0f;mode=last}`
`LoreReplace`	替换 lore	`LoreReplace{old=普通;new=稀有}`
`Name`	改物品显示名	`Name{name=&6传说之剑}`
`Unbreakable`	设为无限耐久	`Unbreakable`
`Durability`	修复耐久	`Durability{amount=1000}`
`ItemFlag`	添加隐藏标记	`ItemFlag{HIDE_ENCHANTS}`
`Point`	增减点券	`Point{amount=500}`
`Money`	增减金币（需 Vault）	`Money{amount=1000}`
`MaxHealth`	玩家永久生命上限	`MaxHealth{amount=1;limit=30}`
`ExpLevel`	给经验等级	`ExpLevel{amount=50}`
`ItemGive`	给予其他宝石	`ItemGive{gem=碎片;amount=10}`
`ItemTake`	扣除其他宝石	`ItemTake{GEM:碎片=10}`
`SkillToNBT`	隐藏/显示技能 lore	`SkillToNBT`
`Conditional`	条件奖励	`Conditional{condition=$LORE:等级:$>=3;reward=Enchant{name=sharpness}}`
`Empty`	占位，什么都不做	`Empty`

Empty 的用途：宝石本身不改装备，纯靠 Tips 里写的 BUFF 标记生效（拿在手里或穿在身上就有效果）。见 FunctionGem.yml 里的「巨无霸汉堡」。Point 与 Money 生效后会主动告诉玩家获得了多少（文案在 lang/<语言代码>.yml 的 reward.point-gain / reward.money-gain）。所以兑换券类宝石把 SuccessTip 写成 none 也不会让玩家一头雾水。

Attribute 详解

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

Attribute{name=health;operation=0;slot=auto;var=v+1;limit=5}

参数	说明
`name`	属性名，支持简写/现代键/旧常量名三种写法
`operation`	`0`=直接加数值，`1`=按基础值百分比加，`2`=按最终值百分比乘
`slot`	生效槽位，见下表
`var`	计算表达式，`v` 是当前已叠加的值
`limit`	能叠加到的极限值

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

limit 是累计值上限，只有与表达式结果方向相同时才夹取；反方向的 limit 不会限制本次变化。建议增益使用正上限、减益使用负上限，避免配置意图不明确。若较低上限会让已有累计效果倒退，本次奖励不会生效。

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

常用属性简写：

简写	实际属性	备注
`health`	最大生命
`damage`	攻击力
`armor` / `toughness`	护甲 / 护甲韧性
`move` / `speed`	移动速度
`attack_speed`	攻击速度
`kbr`	击退抗性
`luck`	幸运
`scale` / `size`	体型	1.20.5+
`block_reach`	方块交互距离	1.20.5+
`attack_reach` / `entity_reach`	实体交互距离	1.20.5+
`water_mining`	水下挖掘速度	1.21.2+
`mining_efficiency`	挖掘效率	1.21.2+
`jump`	跳跃力	1.20.5+
`gravity`	重力	1.20.5+
`absorption`	吸收上限	1.20.5+
`safe_fall`	安全落地距离	1.20.5+

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

表达式语法

Attribute.var、LoreVar.var 和 Point/Money 的 amount 支持简单表达式；Attribute.limit、附魔等级和数量等参数按对应函数读取为固定数值，不能一概写表达式：

语法	例	说明
算术	`v+1` `v*2` `v-0.01`	`v` 是当前已叠加的值
比较	`v<=4`	结果为 1 或 0
三元	`v<2?2:3`	条件成立取前者
随机	`1000+9000*$RANDOM()`	`$RANDOM()` 是 0~1 随机数

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

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

LoreAdd / LoreVar 的 mode 与 locator

参数	说明
`mode=after`	插入到定位行之后（默认）
`mode=before`	插入到定位行之前
`mode=line`	追加到定位行同一行末尾
`mode=last`	（LoreVar）放在末尾
`locator=文本`	定位行，不填则用最后一行
`limit=数字`	最多加几行（LoreAdd）
`force=true`	忽略 limit 强制添加

三种宝石类型

镶嵌类（默认）

不写 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

PlayerGem 不能用作用于物品的奖励（Attribute、Enchant、LoreAdd、Unbreakable 等），因为这类宝石没有目标物品。写了会在日志里报「本次操作没有目标物品」并跳过。它只能用 MaxHealth、ExpLevel、Point、Money、ItemGive、ItemTake。

RandomGem：开箱抽奖

右键后按权重抽一个子宝石当场生效。权重是相对值，不需要凑成 100。

新版宝石礼包:
  Name: 新版宝石礼包
  Type: RandomGem
  Display: "&e&l新版宝石礼包"
  Tips:
    - "&7右键开启，随机获得一颗宝石"
  Material: CHEST
  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发光}   # ← 这里
    - LoreReplace{old=&6&l[&c&lBUFF&6&l] &b&l发光;new=} $onRemove   # 拆卸时清掉标记

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

两边文本不一致是最常见的坑：宝石镶嵌上了、lore 也写了，但没有任何效果，且不报错。匹配时会去掉颜色码并 trim，所以颜色写法的小差异不影响，但文字必须一样。

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

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

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

$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% 成功率）。

验证配置

改完配置后：

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

自检会区分这两类：版本不支持是正常状态（同一份配置发到不同版本的子服），只记 Debug 日志；名字拼错、函数不存在则任何版本都不会生效，会明确报出来。想让写错的条目更醒目，把 config.yml 的 Compat.OnMissingFeature 改成 warn 或 strict。

本次工作台与消耗更新

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

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

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

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

编辑此页面或提交问题报告

更新日志

当前开发改动、配置迁移与验证边界。

技能与 BUFF

技能行语法、24 个内置函数、触发标记、条件与概率、形态切换、常驻 BUFF 的完整配置参考。