Socketing Process

The Gem process validates the equipment, socket item definition, gem item, socket state, and costs before writing gem data to the equipment and rebuilding its presentation.

Steps

1. The player opens the gem GUI or runs a gem command. Inlay, socket-opening, and upgrade GUIs open with an empty target slot; they do not clone or move equipment from the player's main hand or inventory automatically.
2. The module reads the target equipment and selects an items/*.yml socket item definition through its match rules.
3. It reads slots and filters slots that are not open, already occupied, or not valid for the current operation.
4. It loads the gem definition and checks whether gem socket_compatibility matches the target slots[].type.
5. It checks socket item limits such as allowed_gem_types, max_same_type, and max_same_id.
6. It checks conditions and costs, such as inlay_cost, extract_cost, socket openers, or upgrade materials.
7. It writes gem id, current level, slot index, and gem layer data to item PDC.
8. CoreLib rebuilds name, lore, attribute payload, and skill payload.
9. Gem resonances are re-evaluated, and resonance effects are applied or removed.
10. Actions run and the player's inventory is refreshed.

Key validation fields

Config location	Field	Description
items/*.yml	match.item_sources	Which items receive this socket definition.
items/*.yml	slots[].type	Socket type, such as attack, defense, or universal.
items/*.yml	default_open_slots	Socket indexes that are open by default. Other sockets require opening.
items/*.yml	allowed_gem_types	Gem type allowlist for this equipment.
items/*.yml	max_same_type	Maximum number of gems with the same type. 0 means unlimited.
items/*.yml	max_same_id	Maximum number of gems with the same id.
gems/*.yml	gem_type	The gem's own type.
gems/*.yml	socket_compatibility	Socket types this gem can be inserted into.
gems/*.yml	inlay_cost / extract_cost	Inlay and extraction costs.

Older documentation may mention slot_types; the current source uses socket_compatibility together with slots[].type.

Edge cases

• Missing socket item definition: the equipment does not support gems.
• Locked socket: the player must open it first with a socket opener.
• Occupied socket: it cannot be overwritten outside extraction or replacement flows.
• Stacked gem items: usually only one item is consumed.
• Full inventory during extraction: returned gems should be inserted safely or dropped.
• GUI open behavior: target equipment and materials must be placed manually by the player. The module does not auto-use the main-hand item as the initial target, preventing accidental item movement.
• Config reloads that remove old gem ids: the item keeps stored ids when possible and falls back during presentation rebuild. Gem items are refreshed from current definitions when obtained, after reloads, and when reconstructed inside GUIs.