Socket Openers

Socket openers unlock reserved gem sockets on equipment. They separate “sockets defined by the equipment template” from “sockets currently usable by the player”, which is useful for long-term progression, event materials, paid materials, or dungeon drops.

Workflow

1. Equipment defines available and reserved sockets in items/*.yml.
2. The player opens the socket opening GUI.
3. The player inserts the target equipment and an opener item.
4. The module checks whether the equipment matches a socket item definition.
5. The module finds a locked socket whose type is allowed by the opener.
6. On success, the opener may be consumed and the opened socket is written to the gem layer.
7. CoreLib rebuilds the equipment presentation.

Global configuration

Socket openers are configured under socket_openers in config.yml:

socket_openers:
  attack_drill:
    enabled: true
    item_sources:
      - "minecraft-blaze_rod"
    opens_gem_types:
      - "attack"
    consume_on_success: true
    actions:
      success:
        - 'sendmessage text="<green>Opened an attack gem socket!</green>"'
        - "playsound sound=block.anvil.use volume=1.0 pitch=1.1"
      failure:
        - 'sendmessage text="<red>This equipment has no reserved attack socket.</red>"'
        - "playsound sound=entity.villager.no volume=1.0 pitch=0.8"

Fields

Field	Type	Description
enabled	boolean	Whether this opener is enabled.
item_sources	list	Item sources recognized as this opener.
opens_gem_types	list	Socket types this opener can unlock. Use any to allow any type.
consume_on_success	boolean	Whether the opener is consumed after success.
actions.success	list	Actions executed after successful opening.
actions.failure	list	Actions executed when opening fails.

Default openers

Opener	Default item	Types	Use case
attack_drill	minecraft-blaze_rod	attack	Weapon or damage equipment progression.
defense_drill	minecraft-prismarine_shard	defense	Armor or defensive accessory progression.
universal_drill	minecraft-echo_shard	any	Rare universal opener.

Relationship with socket item definitions

Openers do not create arbitrary sockets. The equipment must declare reserved sockets first:

slots:
  - index: 0
    type: "attack"
    display_name: "<red>Attack Socket</red>"
  - index: 1
    type: "attack"
    display_name: "<red>Attack Socket II</red>"
  - index: 2
    type: "universal"
    display_name: "<white>Universal Socket</white>"
default_open_slots:
  - 0

In this example:

• attack_drill can open socket 1.
• universal_drill can open socket 1 or 2.
• If all matching sockets are already open, opening fails and actions.failure runs.

Troubleshooting

• Opener is not recognized: check whether item_sources matches the held item.
• No socket can be opened: check slots, default_open_slots, and type matching.
• Opener is not consumed: check consume_on_success and permission bypass settings.
• Display does not update: check whether CoreLib presentation rebuilds the item and reopen the GUI if needed.