Equipment Templates

Equipment templates define which equipment can participate in the gem system and their socket configurations. Template files are stored in the items/ directory.

Full YAML Format

# items/diamond_sword.yml

# Template unique identifier
id: "diamond_sword"

# ============================================================
# Match Rules
# Determines which items this template applies to
# ============================================================
match:
  # Item source matching (supports multiple)
  item_sources:
    - "minecraft-diamond_sword"
  # Slot group matching (optional, restricts equipment slots)
  slot_groups:
    - "HAND"
  # Lore contains matching (optional, item Lore must contain specified text)
  lore_contains:
    - "可镶嵌"

# ============================================================
# Socket Definitions
# ============================================================
slots:
  - index: 0
    type: "attack"
    display_name: "<red>攻击孔位 I"
  - index: 1
    type: "attack"
    display_name: "<red>攻击孔位 II"
  - index: 2
    type: "defense"
    display_name: "<blue>防御孔位"
  - index: 3
    type: "universal"
    display_name: "<gold>万能孔位"

# Default open socket indexes
default_open_slots:
  - 0

# Allowed gem types (global restriction)
allowed_gem_types:
  - "attack"
  - "defense"
  - "utility"
  - "universal"

# Maximum number of same-type gems (0 = unlimited)
max_same_type: 2

# Maximum number of same-ID gems (0 = unlimited)
max_same_id: 1

# ============================================================
# GUI Template References
# ============================================================
gui:
  gem: "gem/default"
  open: "open/default"
  upgrade: "upgrade/default"

# ============================================================
# Structured Presentation
# ============================================================
structured_presentation:
  # Gem section rendering configuration in equipment Lore
  section_id: "gem_slots"
  header: "<gray>═══ 宝石孔位 ═══"
  footer: "<gray>════════════"
  # Display for opened but empty sockets
  empty_slot_format: "<dark_gray>  ○ {slot_display_name} - 空"
  # Display for unopened sockets
  locked_slot_format: "<dark_gray>  ✖ {slot_display_name} - 未开启"
  # Display for filled sockets
  filled_slot_format: "<gray>  ● {slot_display_name} - {gem_display_name}"

Default Equipment Templates

Template ID	Matched Item	Socket Count	Default Open	Description
diamond_sword	Diamond Sword	4	1	2 attack + 1 defense + 1 universal
iron_armor	Iron Armor	3	1	2 defense + 1 universal
executioner_greatsword	Custom Greatsword	5	2	3 attack + 1 defense + 1 universal

Match Rule Details

Equipment templates determine which items apply through the match node:

Rule	Description
item_sources	Item source matching, supports vanilla and third-party item plugins
slot_groups	Equipment slot group restriction (e.g., HAND, ARMOR)
lore_contains	Text that must be present in the item's Lore (all entries must match)

Tip

The three match rules have an AND relationship. item_sources is required, while slot_groups and lore_contains are optional additional filters.

GUI Layout

gem/default — Gem Inlay/Extract GUI (5 rows)

Row 1: [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border]
Row 2: [Border] [Slot 0] [Slot 1] [Border] [Equipment] [Border] [Slot 2] [Slot 3] [Border]
Row 3: [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border]
Row 4: [Border] [Border] [Border] [Border] [Gem Slot] [Border] [Border] [Border] [Border]
Row 5: [Border] [Border] [Border] [Border] [Confirm] [Border] [Border] [Border] [Border]

• Equipment slot (slot 13): Place the equipment to operate on
• Socket display (slot 10, 11, 15, 16): Shows the status of each socket
• Gem slot (slot 31): Place the gem to inlay / shows the gem to extract
• Confirm button (slot 40): Execute inlay or extract operation

open/default — Socket Opening GUI (4 rows)

Row 1: [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border]
Row 2: [Border] [Equipment] [Border] [Socket Preview...] [Border] [Opener Slot] [Border]
Row 3: [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border]
Row 4: [Border] [Border] [Border] [Border] [Confirm] [Border] [Border] [Border] [Border]

• Equipment slot (slot 10): Place the equipment to open sockets on
• Opener slot (slot 16): Place the socket opener
• Confirm button (slot 31): Execute socket opening

upgrade/default — Upgrade GUI (4 rows)

Row 1: [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border]
Row 2: [Border] [Gem Slot] [Border] [Preview] [→] [Result Preview] [Border] [Material Slot] [Border]
Row 3: [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border] [Border]
Row 4: [Border] [Border] [Border] [Border] [Confirm] [Border] [Border] [Border] [Border]

• Gem slot (slot 10): Place the gem to upgrade
• Material slot (slot 16): Place upgrade materials
• Confirm button (slot 31): Execute upgrade