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. Lowercased on load; the file is skipped when blank.
display_name	string	No	Display name in MiniMessage format. Defaults to id.
lore	list	No	Lore of the gem item itself.
gem_type	string	No	Gem type, such as attack, defense, utility, or universal. Defaults to universal.
level	integer	No	Base gem level. Defaults to 1, minimum 1.
item_sources	list	Yes	Item sources used to identify this gem item. The gem is skipped when it cannot be parsed.
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. Empty means any socket type.
required_gems	list	No	Gem ids this gem depends on.
conflicting_gems	list	No	Gem ids that conflict with 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.inlay_success	list	No	Action lines run after a successful inlay.
actions.extract_success	list	No	Action lines run after a successful extraction.

Listing universal in socket_compatibility lets the gem go into any socket type.

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	Payload key	Description
variables	variables	Runtime variables used by lore templates and formulas.
ea_attribute	ea_attributes	EmakiAttribute PDC attributes written to equipment.
es_skill	es_skills	EmakiSkills skill attachments.
name_action	name_actions	Name operations applied to equipment.
lore_action	lore_actions	Lore operations applied to equipment.

Values under variables and ea_attributes may be numbers or expressions and can reference %level%; keys resolved earlier in the same block are available as variables to later expressions.

Top-level form

Besides the effects list, the parser also accepts variables, ea_attributes, name_actions, and lore_actions written directly on the gem root:

variables:
  physical_attack: 8
ea_attributes:
  physical_attack: 8.0

variables and ea_attributes merge both forms, with keys from effects overriding top-level keys. For name_actions and lore_actions, a top-level value takes precedence and the matching effects entry is ignored. Skills can only be declared through es_skill inside effects.

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.