Extraction System

Gem extraction lets players remove an inlaid gem from equipment. The returned item follows the return mode you configure in the gem definition's extract_return block

Return modes

Mode	Description
original	Return the gem as-is, preserving its current level. Also the fallback for unrecognized values
downgrade	Return a downgraded gem based on a chance roll. Alias: degraded
destroy	Destroy the gem and return nothing. Alias: destroyed

Configuration fields

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

Field	Type	Required	Default	Range	Description
extract_cost	object	No	no cost	same structure as inlay_cost	Extraction cost; fields are in Gem Definitions
extract_return	object	No	original / 1 / 0.0	—	Return configuration; the defaults apply when the whole block is missing
extract_return.mode	string	No	"original"	original / downgrade / destroy (aliases degraded, destroyed)	Return mode; unrecognized values fall back to original
extract_return.degraded_chance	double	No	0.0	0.0~1.0 (clamped)	Chance that a downgrade is triggered: 0.0 means never downgrade; 1.0 means always downgrade. Only used in downgrade mode
extract_return.downgrade_levels	integer	No	1	≥ 1	Number of levels lost when downgrade happens

When the downgraded level would drop to 0 or below, no gem is returned

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

In this mode the gem always returns 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. Use this mode to balance high-value gems