SnowyGems

新功能宝石示例

九颗可复制的宝石与两项配套技能，演示限额、互斥、一次性修复、槽位、冷却和安全撤销。

新功能宝石示例

这组配置面向 0.0.6 修订构建，包含 9 颗宝石和 2 项配套技能，展示新增限制与修复后的行为。它们是可选示例，不会随插件更新自动安装；数值用于测试，可按服务器玩法调整。

安装与获取

下载宝石配置，保存为 plugins/SnowyGems/gems/WikiExamples.yml。
下载配套技能，保存为 plugins/SnowyGems/skills/WikiExamples.yml。也可以复制下面的 YAML：各节宝石顶层条目合并到一个 gems 文件，技能放到 skills 文件；不要混放。
文件使用 UTF-8 和空格缩进。全部 ID 以“示例”开头，仍需检查是否与你已有定义重名；不要把下载文件与相同内容的复制文件同时安装。
执行 /sgem reload，确认加载成功，再执行 /sgem compat all 查看配置问题。失败时旧配置仍可能可用，不能仅凭旧宝石能使用判断本次安装成功。
管理员使用下面命令获取，普通玩家可以在 /sgem catalog 查看；图鉴不会发放物品。

/sgem give 玩家名 示例赤心宝石 3
/sgem give 玩家名 示例铁壁宝石 1
/sgem give 玩家名 示例工匠修复石 1
/sgem give 玩家名 示例矿工夜视宝石 1
/sgem give 玩家名 示例疾行宝石 1
/sgem give 玩家名 示例静默粉尘 1
/sgem give 玩家名 示例恒久宝石 1
/sgem give 玩家名 示例隐纹宝石 1
/sgem give 玩家名 示例探险宝石袋 1

将 玩家名 换成在线玩家的实际名字。除宝石袋右键开启外，其余在 /sgem embed 中放入适用装备和宝石进行镶嵌。本页未设置 Gui 限制，也不依赖经济插件或额外资源包。

所有示例都使用原版物品材质。想换成头颅，可另加有效的 Texture base64；图鉴与实际宝石都会按头颅显示，见图鉴说明。

限次数与互斥：赤心 / 铁壁

示例赤心宝石:
  Name: 示例赤心宝石
  Material: REDSTONE
  Display: "&c赤心宝石"
  Tips:
    - "&7穿戴对应盔甲时，生命上限 +2 点（1 颗心）"
    - "&7每件最多 2 颗，与铁壁宝石互斥"
  Require: [ARMOR]
  Success: 100
  Embed: 2
  ExclusiveGroup: wiki-armor-path
  TrackApplied: true
  Rewards:
    - "Attribute{name=health;operation=0;slot=auto;var=v+2;limit=4}"

示例铁壁宝石:
  Name: 示例铁壁宝石
  Material: IRON_INGOT
  Display: "&f铁壁宝石"
  Tips:
    - "&7穿戴对应盔甲时，护甲 +1"
    - "&7每件最多 2 颗，与赤心宝石互斥"
  Require: [ARMOR]
  Success: 100
  Embed: 2
  ExclusiveGroup: wiki-armor-path
  TrackApplied: true
  Rewards:
    - "Attribute{name=armor;operation=0;slot=auto;var=v+1;limit=2}"

在一件没有其他宝石的盔甲上，赤心可镶两次，共增加 4 点生命上限；第三颗被拒绝。已有赤心时不能镶铁壁，拆完赤心后才可换路线。互斥只发生在同一件装备，不会限制另一件装备选择铁壁。

Embed 是同 ID 次数，ExclusiveGroup 是不同 ID 互斥，limit 是同属性 / 运算 / 槽位累计值上限，三者不是一回事。其他属性宝石也可能影响累计值，不能把这里的 limit 理解为只统计赤心宝石。

一次性修复：工匠修复石

示例工匠修复石:
  Name: 示例工匠修复石
  Material: PRISMARINE_CRYSTALS
  Display: "&a工匠修复石"
  Tips:
    - "&7修复最多 250 点已损失耐久"
    - "&8一次性消耗，不生成可拆卸记录"
  Require: [WEAPON, ARMOR, TOOL, SHIELD, FISHING_ROD]
  Success: 100
  TrackApplied: false
  Rewards:
    - "Durability{amount=250}"

使用有耐久损耗的装备测试；修复不会超过满耐久。满耐久时这条奖励不产生变化。这里不设置 Embed 或 ExclusiveGroup，因为它们依赖已记录的镶嵌实例，不能用于限制这类不留记录的消耗品。也不要加入 LoreAdd 凑成“可拆卸修复石”：已修复的耐久不能安全撤销返还。

限定槽位：矿工夜视宝石

示例矿工夜视宝石:
  Name: 示例矿工夜视宝石
  Material: GOLDEN_CARROT
  Display: "&e矿工夜视宝石"
  Tips:
    - "&7镶入头盔并戴在头上时持续获得夜视"
  Require: [HELMET]
  Success: 100
  Embed: 1
  TrackApplied: true
  Rewards:
    - "LoreAdd{lore=&e[BUFF] 示例矿工夜视;limit=1}"

需要下方 skills/WikiExamples.yml 中的同名配套技能。Require 限制能镶到头盔，技能的 Slot 再限制戴在头上才触发；拿在手里不生效。卸下头盔或拆掉宝石后停止续加，已施加的夜视最多还会保留约 12 秒，不是立即清除。

主动技能：疾行宝石

示例疾行宝石:
  Name: 示例疾行宝石
  Material: SUGAR
  Display: "&b疾行宝石"
  Tips:
    - "&7镶入剑后，主手持剑潜行右键获得速度 II"
    - "&7持续 5 秒，冷却 12 秒"
  Require: [SWORD]
  Success: 100
  Embed: 1
  TrackApplied: true
  Rewards:
    - "LoreAdd{lore=&b[技能] 示例疾行;limit=1}"

需要配套技能。成功施放后才开始冷却，冷却按玩家和技能 ID 共享；换到另一把也带“示例疾行”技能的剑不能刷新冷却。示例没有混入定时触发，避免定时 BUFF 抢占主动技能的同一个冷却。

隐藏技能文字：静默粉尘

示例静默粉尘:
  Name: 示例静默粉尘
  Material: GLOWSTONE_DUST
  Display: "&7静默粉尘"
  Tips:
    - "&7隐藏装备上的 [技能] / [BUFF] 行，效果继续生效"
    - "&8修改其他宝石前，先拆除此粉尘"
  Require: [WEAPON, ARMOR, TOOL, SHIELD]
  Success: 100
  Embed: 1
  TrackApplied: true
  Rewards:
    - "SkillToNBT"

先镶矿工夜视或疾行，再镶粉尘。它会隐藏装备上所有符合 [技能] / [BUFF] 标记的整行，不只隐藏本页示例。没有可隐藏的行时不生效。

隐藏后技能仍触发，动态等级也继续读取。隐藏状态下不能继续镶其他宝石或拆其他宝石，应先拆粉尘。凭据完整、隐藏内容未冲突时，拆粉尘会把文字恢复到 Lore 末尾。

可撤销状态：恒久宝石 / 隐纹宝石

示例恒久宝石:
  Name: 示例恒久宝石
  Material: DIAMOND
  Display: "&b恒久宝石"
  Tips:
    - "&7使装备无法破坏"
  Require: [WEAPON, ARMOR, TOOL, SHIELD]
  Success: 100
  Embed: 1
  TrackApplied: true
  Rewards:
    - "Unbreakable"

示例隐纹宝石:
  Name: 示例隐纹宝石
  Material: INK_SAC
  Display: "&8隐纹宝石"
  Tips:
    - "&7隐藏原版附魔说明，不移除附魔效果"
  Require: [WEAPON, ARMOR, TOOL, SHIELD]
  Success: 100
  Embed: 1
  TrackApplied: true
  Rewards:
    - "ItemFlag{HIDE_ENCHANTS}"

分别演示 Unbreakable 和 ItemFlag 的撤销凭据。前者用原本可损耗的装备测试；后者用有附魔、尚未隐藏附魔说明的装备测试。已有相同状态时不会再次产生变化。

在记录与状态未被其他插件改动时，拆卸会撤销本颗宝石新增的状态。隐纹不关闭附魔光效，也不会清理其他插件自行写入的附魔 Lore。

发放实物：探险宝石袋

示例探险宝石袋:
  Name: 示例探险宝石袋
  Type: RandomGem
  Material: CHEST
  Display: "&6探险宝石袋"
  Tips:
    - "&7右键随机获得本页的一颗示例宝石"
  Success: 100
  GiveItem: true
  Gems:
    示例赤心宝石: 30
    示例铁壁宝石: 30
    示例工匠修复石: 20
    示例矿工夜视宝石: 10
    示例疾行宝石: 10

权重合计 100，所以这里分别为 30%、30%、20%、10%、10%；权重本身不要求合计 100。GiveItem: true 发放宝石物品，玩家之后再选择装备镶嵌，不会当场执行目标宝石的装备奖励。

请一起安装被引用的五颗宝石。若只复制礼包这一节，缺少子宝石定义会导致加载失败。

配套技能文件

下面是完整的 skills/WikiExamples.yml，不要放进 gems 目录。Potion.duration 与 Cooldown 均以秒为单位，level: 2 对应效果 II。技能 Slot 的 mainhand 与属性奖励的 hand 不是同一套字段。

# 与 gems/WikiExamples.yml 成对安装；Slot 使用技能槽位名称。
示例矿工夜视技能:
  Lore: "&e[BUFF] 示例矿工夜视"
  Slot: [head]
  Cooldown: 0
  Skills:
    - "Potion{type=NIGHT_VISION;level=1;duration=12} ~onTimer @Self"

示例疾行技能:
  Lore: "&b[技能] 示例疾行"
  Slot: [mainhand]
  Cooldown: 12
  Skills:
    - "Potion{type=SPEED;level=2;duration=5} ~onShiftUse @Self"

测试服验收

测试	应观察到的结果
同一盔甲连续镶三颗赤心	前两颗生效，第三颗受 Embed 限制；穿戴后共增加 4 点生命上限
带赤心的盔甲再镶铁壁	同组不同 ID 被拒绝；拆完赤心后才可改镶铁壁
损坏装备使用工匠修复石	恢复最多 250 点耐久，inspect 不新增这颗修复石的记录
夜视头盔放主手，再戴上	主手无夜视续加，戴上后续加；卸下后等待已有药水到期
主手疾行剑潜行右键	速度 II 持续 5 秒，12 秒内换同技能的剑也不能重置冷却
对夜视头盔使用静默粉尘	BUFF 行隐藏，但戴上仍续加；先拆粉尘才可拆夜视宝石
镶嵌再拆恒久 / 隐纹	撤销对应新增状态；其他插件改动导致凭据冲突时可能拒绝
右键开启探险宝石袋	获得一颗子宝石物品，而不是直接强化手中物品

这些配置已对照当前代码和 YAML 语法核对，仍需在目标服务端按表实测。验收拆卸时注意 Dismantle.Cost 和损坏概率会影响费用及返还结果；“支持撤销”不代表一定免费返还。用 /sgem inspect 查看记录，用 /sgem history 玩家名 查看近期摘要。

TrackApplied: true 只允许记录，不保证所有奖励都可拆卸。不要给上述可拆卸宝石追加金币、修复等不可撤销奖励；Rewards 逐条执行，不是整体事务。旧装备缺少凭据、Lore 被其他插件改写等情况，详见拆卸规则。

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

宝石配置

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

技能与 BUFF

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