Socket Item Definitions and GUI Templates

Socket item definition files are stored in items/*.yml. They define which equipment can have gem sockets, what socket types are available, which sockets are initially open, and which GUI templates should be used.

Socket item fields

Field	Description
id	Unique socket item definition id.
match	Matching rules for equipment.
slots	Socket slot list.
default_open_slots	Slot indexes that are open by default.
allowed_gem_types	Gem type whitelist for this equipment.
max_same_type	Maximum gems of the same type. Unlimited when not configured.
max_same_id	Maximum gems with the same gem id.
gui	GUI template references.
obtain.name_actions	Name operations applied when the gem layer is first written.
obtain.lore_actions	Lore operations applied when the gem layer is first written.
obtain.actions	Action lines run when the gem layer is first written.

Weapon socket item example

id: "weapon_socket_item"
match:
  item_sources:
    - "minecraft-diamond_sword"
  slot_groups:
    - "weapon"
  lore_contains: []
slots:
  - index: 0
    type: "attack"
    display_name: "<red>Attack Socket</red>"
  - index: 1
    type: "universal"
    display_name: "<white>Universal Socket</white>"
  - index: 2
    type: "defense"
    display_name: "<blue>Defense Socket</blue>"
default_open_slots:
  - 0
allowed_gem_types:
  - "attack"
  - "defense"
  - "utility"
  - "universal"
max_same_type: 0
max_same_id: 1
gui:
  gem_template: "gem/default"
  open_template: "open/default"
obtain:
  name_actions:
    - action: "prepend_prefix"
      value: "<gold>✦</gold> "
  lore_actions:
    - action: "append"
      content:
        - "<gray>Sockets: <dark_gray>(%opened_slots%/%total_slots%)</dark_gray></gray>"
  actions:
    - 'sendmessage text="<gray>Socketable item detected: <yellow>%item_definition_id%</yellow></gray>"'

obtain applies when the item is first recognized and the gem layer is written. Its lore_actions can use template variables such as %opened_slots%, %total_slots%, and %item_definition_id%.

GUI directories

Directory	Purpose
gui/gem/	Inlay and extraction GUI templates.
gui/open/	Socket opening GUI templates.
gui/upgrade/	Gem upgrade GUI templates.

Use different socket definitions for weapons, armor, and accessories so gems cannot be inserted into unintended equipment.