Socketing Process

When inlaying (including socket opening) the plugin checks things in a fixed order; each step reads its own configuration, and troubleshooting starts from that order. 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 top-level item_sources, matcher, and slot_groups
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's item operation ledger (ItemOperationLedger) 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	item_sources + matcher + slot_groups	Which items receive this socket definition. See Socket item definitions
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. Unlimited when not configured
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

IMPORTANT

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

Edge cases

• Missing socket item definition: the interface reports that this equipment does not support gems
• Locked socket: open it first with a socket opener
• Occupied socket: it cannot be overwritten outside extraction or replacement flows
• Stacked gem items: only one item is consumed; the rest are kept
• Full inventory during extraction: returned gems go into the inventory, or drop safely if it is full
• 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