Extraction System

Gem extraction lets players remove an inlaid gem from equipment. The returned item depends on the gem definition's extract_return configuration.

Return modes

Mode	Description
original	Return the gem as-is, preserving its current level.
downgrade	Return a downgraded gem.
destroy	Destroy the gem and return nothing.

Configuration fields

Extraction cost and return mode are configured in gems/*.yml:

Field	Type	Description
extract_cost	object	Currency and material cost paid before extraction succeeds.
extract_return.mode	string	Return mode: original, downgrade, or destroy.
extract_return.downgrade_levels	integer	Number of levels lost when downgrade happens.
extract_return.degraded_chance	double	Chance to keep the original level in downgrade mode. 0.0 means always downgrade; 1.0 means never downgrade.

extract_cost:
  currencies:
    - provider: "vault"
      currency_id: ""
      base_cost: 500
      cost_formula: "%base_cost% * %level%"
      display_name: "<gold>Coins</gold>"
  materials:
    - item_sources:
        - "minecraft-iron_nugget"
      amount: 1

extract_return:
  mode: "original"
  downgrade_levels: 1
  degraded_chance: 0.0

Extraction flow

1. The player selects the inlaid gem in the GUI
       ↓
2. The module checks extraction cost and conditions
       ↓
3. The module decides the returned gem based on extract_return
       ↓
4. Gem effects and resonance state are removed or recalculated
       ↓
5. The socket assignment is cleared from item PDC
       ↓
6. The returned gem is given to the player if mode is not destroy

Examples

Return original gem

extract_return:
  mode: "original"

Return downgraded gem

extract_return:
  mode: "downgrade"
  downgrade_levels: 1
  degraded_chance: 0.0

This always returns the gem with one level removed, unless the result would drop below level 1.

Destroy on extraction

extract_return:
  mode: "destroy"

The gem is removed from the equipment but no gem item is returned. This is useful for high-value balance designs.