Gem Definitions

Gem definition files are stored in the gems/ directory, with each file defining one gem.

Full YAML Format

# gems/ruby_attack.yml

# Gem unique identifier
id: "ruby_attack"

# Gem type: attack / defense / utility / universal
gem_type: "attack"

# Gem tier (used for success rate calculation, etc.)
tier: 1

# Gem item source
item_source: "minecraft-redstone"

# Display name
display_name: "<red>红宝石"

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

# Stat bonuses (key-value pairs, keys are stat IDs)
stats:
  physical_attack: 10
  critical_chance: 5.0

# EmakiAttribute attribute writing (optional, requires EA soft dependency)
attributes:
  physical_attack:
    value: 10
    operation: "ADD"
  critical_chance:
    value: 5.0
    operation: "ADD"

# Socket compatibility — which socket types this gem can be inlaid into
socket_compatibility:
  - "attack"
  - "universal"

# ============================================================
# Structured Presentation
# Controls how the gem is displayed in equipment Lore after inlaying
# ============================================================
structured_presentation:
  # Name contributions — appended to equipment name after inlaying
  name_contributions:
    - template: " <red>[红宝石]"
      position: "SUFFIX"

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

# ============================================================
# Inlay Cost
# ============================================================
inlay_cost:
  # Currency cost
  currencies:
    - provider: "vault"
      amount: 100
  # Material cost
  materials:
    - source: "minecraft-gold_ingot"
      amount: 5

# ============================================================
# Extract Cost & Return
# ============================================================
extract_cost:
  currencies:
    - provider: "vault"
      amount: 50

extract_return:
  # Return mode: exact / downgrade / degraded
  mode: "exact"
  # Levels to downgrade in downgrade mode
  downgrade_levels: 1
  # Probability of returning a degraded gem in degraded mode (percentage)
  degraded_chance: 50

# ============================================================
# Upgrade System
# ============================================================
upgrade:
  enabled: true
  # Maximum level
  max_level: 5
  # Upgrade GUI template
  gui_template: "upgrade/default"

  # Upgrade economy
  economy:
    currencies:
      - provider: "vault"
        amount_formula: "level * 200"

  # Per-level success rates (overrides global global_success_rates)
  success_rates:
    1: 100
    2: 90
    3: 70
    4: 50
    5: 30

  # Failure penalty (overrides global global_failure_penalty)
  failure_penalty: "none"

  # Level definitions
  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"

Gem Types

Type	Description
attack	Attack gem, typically provides attack power, critical strike, and similar stats
defense	Defense gem, typically provides defense, health, and similar stats
utility	Utility gem, typically provides movement speed, experience bonus, and similar stats
universal	Universal gem, can be inlaid into any socket type

Skill Effects

Gem definitions can declare skill IDs through the effects list. After inlaying a gem, all declared skill IDs from inlaid gems are written to the equipment's PDC, and EmakiSkills will unlock the corresponding skills when scanning equipment.

effects:
  - type: skill
    skill: "mana_shield"

# Or declare multiple at once
effects:
  - type: skill
    skills:
      - "mana_shield"
      - "arcane_barrier"

Upgrade level definitions (upgrade.levels) can also declare effects; higher-level skill lists override the base definition. When extracting a gem, the corresponding skill IDs are removed from the equipment.

Default Gems Overview

Gem ID	Type	Tier	Upgradeable	Description
ruby_attack	attack	1	Yes (max level 5)	Ruby, provides attack power
sapphire_defense	defense	1	Yes (max level 5)	Sapphire, provides defense
emerald_utility	utility	1	Yes (max level 3)	Emerald, provides movement speed bonus

Extract Return Modes

Mode	Description
exact	Returns the exact same gem as when inlaid (including level)
downgrade	Returns a gem downgraded by downgrade_levels levels
degraded	Has a degraded_chance% probability of returning a degraded gem; otherwise returns the original

Upgrade Failure Penalties

Penalty	Description
none	No penalty, maintains current level
downgrade	Downgrade by one level
destroy	Destroy the gem