宝石定义

宝石定义文件存放在 gems/ 目录下，每个文件定义一种宝石。一颗宝石的定义涵盖了它的类型、属性加成、孔位兼容性、展示方式、镶嵌/提取费用，以及升级系统的完整配置。

完整 YAML 格式

# gems/ruby_attack.yml

# 宝石唯一标识
id: "ruby_attack"

# 宝石类型：attack / defense / utility / universal
gem_type: "attack"

# 宝石品阶（用于成功率计算等）
tier: 1

# 宝石物品来源
item_source: "minecraft-redstone"

# 显示名称
display_name: "<red>红宝石"

# 物品 Lore
lore:
  - "<gray>攻击型宝石"
  - "<gray>攻击力 +10"

# 属性加成（键值对，键为属性 ID）
stats:
  physical_attack: 10
  critical_chance: 5.0

# EmakiAttribute 属性写入（可选，需要 EA 软依赖）
attributes:
  physical_attack:
    value: 10
    operation: "ADD"
  critical_chance:
    value: 5.0
    operation: "ADD"

# 孔位兼容性 —— 此宝石可以镶嵌到哪些类型的孔位
socket_compatibility:
  - "attack"
  - "universal"

# ============================================================
# 结构化展示 (Structured Presentation)
# 控制宝石镶嵌后在装备 Lore 中的展示
# ============================================================
structured_presentation:
  # 名称贡献 —— 镶嵌后追加到装备名称
  name_contributions:
    - template: " <red>[红宝石]"
      position: "SUFFIX"

  # Lore 段落贡献
  lore_sections:
    - section_id: "gem_stats"
      lines:
        - "<gray>  ├ <red>攻击力 +{physical_attack}"
        - "<gray>  └ <red>暴击率 +{critical_chance}%"

# ============================================================
# 镶嵌费用 (Inlay Cost)
# ============================================================
inlay_cost:
  # 货币费用
  currencies:
    - provider: "vault"
      amount: 100
  # 材料费用
  materials:
    - source: "minecraft-gold_ingot"
      amount: 5

# ============================================================
# 提取费用与返还 (Extract)
# ============================================================
extract_cost:
  currencies:
    - provider: "vault"
      amount: 50

extract_return:
  # 返还模式：exact / downgrade / degraded
  mode: "exact"
  # downgrade 模式下降低的等级数
  downgrade_levels: 1
  # degraded 模式下返还降级宝石的概率（百分比）
  degraded_chance: 50

# ============================================================
# 升级系统 (Upgrade)
# ============================================================
upgrade:
  enabled: true
  # 最大等级
  max_level: 5
  # 升级 GUI 模板
  gui_template: "upgrade/default"

  # 升级经济
  economy:
    currencies:
      - provider: "vault"
        amount_formula: "level * 200"

  # 每级成功率（覆盖全局 global_success_rates）
  success_rates:
    1: 100
    2: 90
    3: 70
    4: 50
    5: 30

  # 失败惩罚（覆盖全局 global_failure_penalty）
  failure_penalty: "none"

  # 等级定义
  levels:
    1:
      display_name: "<red>红宝石 I"
      stats:
        physical_attack: 10
      lore:
        - "<gray>攻击力 +10"
    2:
      display_name: "<red>红宝石 II"
      stats:
        physical_attack: 20
      lore:
        - "<gray>攻击力 +20"
    3:
      display_name: "<red>红宝石 III"
      stats:
        physical_attack: 35
      lore:
        - "<gray>攻击力 +35"
    4:
      display_name: "<red>红宝石 IV"
      stats:
        physical_attack: 55
      lore:
        - "<gray>攻击力 +55"
    5:
      display_name: "<red>红宝石 V"
      stats:
        physical_attack: 80
      lore:
        - "<gray>攻击力 +80"

宝石类型

宝石类型决定了它能镶嵌到哪些孔位。孔位也有类型，两者通过 socket_compatibility 匹配。

类型	说明
attack	攻击型宝石，通常加攻击力、暴击等
defense	防御型宝石，通常加防御力、生命值等
utility	功能型宝石，通常加移速、经验加成等
universal	万能型宝石，可以镶嵌到任何类型的孔位

类型本身只是一个字符串标签，实际效果完全由 stats 和 attributes 决定。你也可以自定义类型名称，只要和装备模板的孔位类型对应上就行。

技能效果

宝石定义可以通过 effects 列表声明技能 ID。镶嵌宝石后，装备的 PDC 中会写入所有已镶嵌宝石声明的技能 ID，EmakiSkills 扫描装备时就能解锁对应技能。

effects:
  - type: skill
    skill: "mana_shield"

# 或者一次声明多个
effects:
  - type: skill
    skills:
      - "mana_shield"
      - "arcane_barrier"

升级等级定义（upgrade.levels）中也可以声明 effects，高等级的技能列表会覆盖基础定义的。提取宝石后，对应的技能 ID 会从装备上移除。

默认宝石一览

宝石 ID	类型	品阶	可升级	说明
ruby_attack	attack	1	是（最高 5 级）	红宝石，提供攻击力
sapphire_defense	defense	1	是（最高 5 级）	蓝宝石，提供防御力
emerald_utility	utility	1	是（最高 3 级）	绿宝石，提供移速加成

提取返还模式

提取宝石时，返还给玩家的宝石不一定和镶嵌时完全一样，取决于 extract_return.mode 的设置：

模式	说明
exact	原样返还，等级不变
downgrade	返还降低 downgrade_levels 级的宝石。如果降到 0 级以下则销毁
degraded	有 degraded_chance% 概率返还降级宝石，否则返还原宝石。适合想加点风险但又不想太狠的场景

升级失败惩罚

升级失败时的惩罚可以在宝石定义中单独设置（failure_penalty），也可以用全局配置（global_failure_penalty）。宝石定义的设置优先级更高。

惩罚	说明
none	无惩罚，保持当前等级
downgrade	降低一级
destroy	销毁宝石