essence merchant - magemonkeystudio/divinity GitHub Wiki

🛒 Essence Merchant

The merchant.yml file configures the socketing GUI that allows players to spend money to socket essences into items. It controls socketing bonuses, pricing behavior, and the layout and animations of the merchant interface.

📁 File Location

plugins/Divinity/modules/essences/merchant.yml

🎯 Purpose

This file defines the merchant-operated socketing system. It is a GUI where players place an item and an essence, pay a cost, and attempt to socket the essence with a chance-based outcome.

⚙️ Configuration Sections

`socketing`

Controls bonuses to socket success chance when using the merchant interface.

socketing:
  chance:
    merchant-bonus:
      amount: 15
      maximal: 80
  silent-rate-bonus:
    enabled: false

merchant-bonus.amount: Flat increase to socket success when using this GUI
merchant-bonus.maximal: Maximum cap on the increased chance
silent-rate-bonus.enabled: Whether hidden (silent) bonuses apply

`price`

Controls pricing modifiers for socket attempts:

price:
  socket-worth-modifier: 1.0
  item-worth-modifier: 1.2

socket-worth-modifier: Multiplies essence value when calculating price
item-worth-modifier: Multiplies base item value for cost calculation

`gui`

Defines the GUI appearance, slot layout, and animations.

gui:
  title: '&8&m    &9&l Merchant Socketing &8&m    '
  size: 45
  item-slot: 20
  source-slot: 22
  result-slot: 24

title: Display name at the top of the GUI
size: Size of the inventory (must be divisible by 9)
item-slot, source-slot, result-slot: Core logic slots

GUI Layout and Filler Items

The content: section defines decorative or functional GUI items, including their materials, slot positions, and optional animations.

Examples:

filler_1:
  material: BLACK_STAINED_GLASS_PANE
  slots: 2,3,4,5,6,...
  type: NONE

filler_4_a1:
  material: PURPLE_STAINED_GLASS_PANE
  name: '&5&lItem Slot'
  lore:
    - '&f» &7Click on item with at least &fone'
    - '&7free socket to put it into the GUI.'
  slots: 11,29
  animation:
    auto-play: true
    start-frame: 0
  animation-frames:
    '1':
      material: MAGENTA_STAINED_GLASS_PANE
      name: '&d&lItem Slot'

Animations are defined with frame indexes and material/name swaps.

Accept and Exit Buttons

accept:
  material: LIME_STAINED_GLASS_PANE
  name: '&2« &aAccept &2»'
  lore:
    - '&a» &7Price: &a$%cost%'
    - '&a» &7Balance: &a$%balance%'
    - '&a» &7Success Chance: &a%chance%%'
    - '&7'
    - '&7In case of failure your item will be &cdestroyed&7.'
  slots: 26
  type: ACCEPT

exit:
  material: RED_STAINED_GLASS_PANE
  name: '&4« &cCancel &4»'
  slots: 18
  type: EXIT

These control player interaction — accept commits to socketing with risk, exit cancels the GUI.

🧪 Usage Tips

The GUI is animated using frame definitions per slot group.
%cost%, %balance%, and %chance% variables are replaced dynamically.
If socketing fails, the item will be destroyed — clearly reflected in the lore.