Gem Definitions

Gem definition files are stored in gems/*.yml. A gem definition describes how the gem item is recognized, which socket types it supports, what effects it provides, and how inlay, extraction, and upgrade costs are handled.

Top-level fields

Field	Type	Required	Description
id	string	Yes	Unique gem id.
display_name	string	Yes	Display name in MiniMessage format.
gem_type	string	Yes	Gem type, such as attack, defense, utility, or universal.
level	integer	No	Base gem level.
item_sources	list	Yes	Item sources used to identify this gem item.
custom_model_data	integer	No	Optional custom model data.
effects	list	No	Effects applied when the gem is inlaid.
socket_compatibility	list	No	Socket types that can accept this gem.
inlay_cost	object	No	Cost paid when inlaying.
extract_cost	object	No	Cost paid when extracting.
extract_return	object	No	How the gem is returned after extraction.
upgrade	object	No	Upgrade settings.
actions	object	No	Actions executed on success or failure.

Minimal example

id: "ruby_basic"
display_name: "<red>Ruby</red>"
gem_type: "attack"
level: 1
item_sources:
  - "minecraft-redstone"
socket_compatibility:
  - "attack"
  - "universal"
effects:
  - type: "variables"
    variables:
      physical_attack: 5
  - type: "ea_attribute"
    ea_attributes:
      physical_attack: 5.0

Effect types

Type	Description
variables	Runtime variables used by lore templates and formulas.
ea_attribute	EmakiAttribute PDC attributes written to equipment.
es_skill	EmakiSkills skill attachments.
name_action	Name operations applied to equipment.
lore_action	Lore operations applied to equipment.

Cost example

inlay_cost:
  currencies:
    - provider: "vault"
      currency_id: ""
      base_cost: 1000
      cost_formula: "%base_cost% * %level%"
      display_name: "<gold>Coins</gold>"
  materials:
    - item_sources:
        - "minecraft-gold_nugget"
      amount: 1

Upgrade example

upgrade:
  enabled: true
  max_level: 4
  gui_template: "upgrade/default"
  failure_penalty: "none"
  success_rates:
    2: 100.0
    3: 80.0
    4: 60.0
  levels:
    2:
      display_name: "<red>Ruby II</red>"
      effects:
        - type: "variables"
          variables:
            physical_attack: 12
        - type: "ea_attribute"
          ea_attributes:
            physical_attack: 12.0
      materials:
        - item_sources:
            - "minecraft-gold_nugget"
          amount: 3

Design notes

• Use stable item_sources instead of display names or lore matching.
• Keep gem_type and socket_compatibility simple and easy to understand.
• Write real stats through ea_attribute; use lore actions only for presentation.
• Use extract_return and upgrade failure penalties carefully on high-value gems.