Snowygems
宝石配置
gems/ 目录下宝石的全部字段、Rewards 奖励函数、Require 适用范围写法与完整示例。
宝石配置
宝石定义放在 plugins/SnowyGems/gems/ 下，文件名任意，插件加载目录里所有 .yml。文件名会成为 /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 | 整数 | 成功率 1-100，默认 100 |
Embed | 整数 | 镶嵌位权重 |
Gui | 列表 | 限定只能在哪些界面使用 |
SuccessTip | 文本 | 成功提示。填 none 则不发消息 |
RemoveTip | 文本 | 拆卸提示 |
FailTip | 文本 | 失败提示 |
Rewards | 列表 | 真正干活的部分，见下文 |
Gems | 映射 | 仅 RandomGem 用：子宝石ID: 权重 |
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/RANGED/SPEAR，铜盔甲会自动落进 ARMOR——你不需要改配置。完整清单用 /sgem compat all 查看。
Require:
- WEAPON # 任意武器
- TOOL # 或任意工具
- SHIELD # 或盾牌
Rewards：宝石实际做什么
Rewards 是列表，每行是一个函数调用，语法 函数名{参数1=值;参数2=值}。
阶段标记
行尾可以加标记决定这条在什么时候执行：
| 标记 | 含义 |
|---|---|
$onSuccess | 镶嵌成功时执行（默认，不写就是这个） |
$onRemove | 拆卸时执行，常用来收取拆卸费 |
Rewards:
- LoreAdd{lore=&6&l[&c&lBUFF&6&l] &b&l发光}
- Point{amount=-1000} $onRemove # 拆卸时扣 1000 点券
每条 Rewards 相互独立，其中一条没生效不会中断后面的条目。
函数清单
| 函数 | 作用 | 示例 |
|---|---|---|
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;limit=v<=4;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 里的「巨无霸汉堡」。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 必须和 var 方向同号。 limit 是「能加到的极限值」而不是「加多少次」。写 var=v-0.1 却配 limit=0.3，第一次镶嵌算出 -0.1 会被夹回 0.3 上限内——实际表现是宝石永远不生效，且没有任何报错。减法要配负 limit：
# 对：缩小体型，最多缩到 -0.3
- Attribute{name=scale;operation=0;slot=any;var=v-0.1;limit=-0.3}
# 错：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）也都能直接写。完整清单见多版本兼容。
表达式语法
var、limit、amount 等参数支持简单表达式：
| 语法 | 例 | 说明 |
|---|---|---|
| 算术 | 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发光} # ← 这里
- Point{amount=-1000} $onRemove
发光:
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;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}
低版本服务端上这些宝石会被自动跳过并在控制台说明，不影响其他宝石。
验证配置
改完配置后：
/sgem reload重载- 看控制台。如果有写错的条目，插件会报「配置自检发现 N 处写错的条目」
/sgem compat all查看自检明细，包括「当前版本不支持所以跳过」和「写错了」两类
自检会区分这两类：版本不支持是正常状态（同一份配置发到不同版本的子服），只记 Debug 日志；名字拼错、函数不存在则任何版本都不会生效，会明确报出来。想让写错的条目更醒目，把 config.yml 的 Compat.OnMissingFeature 改成 warn 或 strict。