Gem Sockets (Legendinlay / MagicGem)

Belongs to: Server Admin Guide　·　Related: Item Definitions · Integrations

QI supports opening gem sockets on equipment, integrating with two backends: Legendinlay and MagicGem. QI is responsible for declaring sockets and rendering socket lore; the actual inlay logic is handled by the backend plugins.

---

1. Three-Layer Concept

Socket type (GemSocketType)        —— the socket kinds you define (green socket / weapon socket / armor socket…)
   ├─ maps to a Legendinlay backend socket
   └─ maps to a MagicGem backend socket

Item's gem-sockets                 —— which sockets this item has opened (listed by type ID)

providers.legendinlay/magicgem     —— the payload for the backend (auto-synced and generated)

---

2. Defining Socket Types

Config file: integrations/gem_socket_types.yml.

types:
  绿色:
    display: "绿色"
    legendinlay: normal          # maps to the Legendinlay socket id
    magicgem: weapon_slot        # maps to the MagicGem socket id

  qi_weapon:
    display: "武器孔"
    legendinlay: qi_weapon

  armor:
    display: "护甲孔"
    magicgem: armor_slot
    lore: "<gray>◇ </gray><dark_gray>镶嵌孔</dark_gray>"   # fallback lore when the backend is unavailable

Key	Meaning
display	Display name (required)
legendinlay	Legendinlay backend socket ID (optional)
magicgem	MagicGem backend socket ID (optional)
lore	Fallback lore line when neither backend catalog is available (optional)

---

3. Opening Sockets on an Item

In the item definition, use gem-sockets (a list, each entry is a socket type ID):

demo_thunder_edge:
  type: weapon                  # the type must support GEM_SOCKET, see Item Types
  gem-sockets:
    - 绿色
    - qi_weapon

You can also edit via the GUI (see Other Editors → Gem Sockets).

Auto-Syncing the Provider

QI automatically generates the providers.legendinlay / providers.magicgem payload from gem-sockets (GemSocketService.syncProviders); no manual writing needed. The generated payload looks like:

providers:
  legendinlay:
    value: '{"set":null,"slot":"weapon","sockets":["normal","qi_weapon"]}'

The config option gem.inject-on-rebuild (default false) controls whether to re-sync during rebuild() as well.

---

4. Socket Lore Rendering Priority

The lore for each socket is resolved in the following order (GemSocketService.resolveLore):

1. Legendinlay catalog (if enabled): integrations/legendinlay_sockets.yml
2. MagicGem catalog (if enabled): integrations/magicgem_sockets.yml
3. The socket type's own lore
4. Fallback catalog search
5. Generated default: [ + ] Empty xxx Slot

Backend Socket Catalog Format

legendinlay_sockets.yml:

sockets:
  normal:
    label: "十年魂环"
    lore: "十年魂环孔位"       # must match Legendinlay's socket lore exactly (LI identifies sockets by lore)
  qi_weapon:
    label: "武器孔"
    lore: "武器专属孔位"

magicgem_sockets.yml:

sockets:
  weapon_slot:
    lore: "§7✦ §8空宝石槽"
  armor_slot:
    lore: "§7◇ §8镶嵌孔"

⚠️ Legendinlay identifies sockets by the lore line text, so lore must be character-for-character identical to the one on the LI side, otherwise the inlay will not be recognized.

---

5. Crafting Gem Items

A gem itself is just an ordinary QI item with type: gem:

demo_emerald_gem:
  type: gem
  material: emerald
  display_name: "<green>翠绿宝石</green>"
  lore:
    - "<gray>可镶嵌入武器孔</gray>"
  options:
    max_stack_size: 64

The inlay effects (attribute bonuses, etc.) are handled by the backend plugin according to its own rules; the QI side only handles turning the gem into an item.

---

6. Toggles and Configuration

config.yml:

gem:
  inject-sockets: true          # whether to render socket lore
  inject-on-rebuild: false      # whether to re-sync the provider on rebuild

legendinlay:
  enabled: true
  socket-catalog: integrations/legendinlay_sockets.yml
  auto-deploy-lc-script: true   # auto-deploy the LegendCore fallback groovy script

magicgem:
  enabled: true
  socket-catalog: integrations/magicgem_sockets.yml

---

7. PlaceholderAPI Placeholders

GemPlaceholderProvider (identifier qinhitems), evaluated against the player's main-hand item:

Placeholder	Returns
%qinhitems_legendinlay_set% / %qinhitems_li_set%	Legendinlay set name
%qinhitems_magicgem_set% / %qinhitems_mg_set%	MagicGem set name
%qinhitems_socket_count% / %qinhitems_sockets%	Number of inlaid sockets
%qinhitems_socket_total% / %qinhitems_socket_max%	Total number of sockets

For the full list of placeholders, see Placeholders.

---

8. Developer API

GemSocketTypeRegistry.all(): List<GemSocketType>
GemSocketTypeRegistry.get(typeKey): GemSocketType?
GemSocketTypeRegistry.legendinlayId(typeKey): String?
GemSocketTypeRegistry.magicgemId(typeKey): String?

GemSocketService.readGemSocketsFromYaml(yaml): List<String>
GemSocketService.loreLines(definition): List<String>
GemSocketService.resolveLore(typeKey): String?
GemSocketService.syncProviders(definition): QinhItemDefinition

For bridge details, see Integrations.

🖼️ [Image placeholder] A weapon hover with 2 gem sockets (one empty, one inlaid)　·　suggested assets/gem-sockets.png

---

Next Steps

• Soul Binding: bound-item protection
• Integrations: Legendinlay / MagicGem bridge internals