item_stats sockets

💎 item_stats/sockets.yml

This file defines the socket types used by Divinity, allowing items to hold gems, runes, essences, or other customizable inserts. Each socket type can have different visual formatting, tiers, and behavior. Sockets are purely a formatting layer here—logic like insertion success, restrictions, and removal is handled by the socketing module configuration.

---

🧾 Default Socket Types

GEM:
  categories:
    common:
      tier: common
      name: '%TIER_NAME% Gem Socket'
      format:
        main: '%value%'
        value:
          empty: '%TIER_COLOR%□ <%name%>'
          filled: '%TIER_COLOR%▣ &7%value%'
    rare:
      tier: rare
      name: '%TIER_NAME% Gem Socket'
      format:
        main: '%value%'
        value:
          empty: '%TIER_COLOR%□ <%name%>'
          filled: '%TIER_COLOR%▣ &7%value%'

RUNE:
  categories:
    default:
      tier: common
      name: '%TIER_COLOR%Rune Socket'
      format:
        main: '%value%'
        value:
          empty: '%TIER_COLOR%□ <%name%>'
          filled: '%TIER_COLOR%▣ &7%value%'

ESSENCE:
  categories:
    default:
      tier: common
      name: '%TIER_COLOR%Essence Socket'
      format:
        main: '%value%'
        value:
          empty: '%TIER_COLOR%□ <%name%>'
          filled: '%TIER_COLOR%▣ &7%value%'

---

📌 Key Settings

Setting	Description
tier	Controls which item tier the socket is associated with. Affects color formatting via %TIER_COLOR%.
name	Displayed socket name, supports tier placeholders like %TIER_NAME%.
format.main	Defines how the socket displays in the item lore. Usually set to %value%.
format.value.empty	Shown when the socket is empty. Supports %name% and %TIER_COLOR%.
format.value.filled	Shown when the socket is filled with a gem, rune, or essence. Supports %value%.

---

🧩 Customization

Divinity supports unlimited custom socket types, each with its own logic and display configuration. You can:

• ✅ Rename socket types (e.g., change GEM to CRYSTAL)
• ✅ Add entirely new types (e.g., SCROLL, TOTEM, BLOOD, etc.)
• ✅ Create multiple categories within a socket type to define variations by rarity or function
• ✅ Customize both empty and filled formats per category to alter how the socket appears in lore

---

🛠️ How to Create a New Socket Type

1. Choose a unique key name for your socket type (e.g., SCROLL).
2. Add at least one category under it (e.g., default, epic, etc.).
3. Provide a valid tier, name, and format section for that category.
4. Match your new socket type in your gem/rune/etc. item's target-requirements.socket setting.

Example:

SCROLL:
  categories:
    default:
      tier: rare
      name: '%TIER_COLOR%Scroll Slot'
      format:
        main: '%value%'
        value:
          empty: '%TIER_COLOR%□ <%name%>'
          filled: '%TIER_COLOR%▣ &7%value%'

---

⚠️ Required Structure

• Every socket type must have at least one category.
• Each category must define both an empty and filled format.value.
• Missing fields like tier or format.value.filled will break lore rendering.

---

💬 Notes

• %value% is dynamically replaced with the socket content when filled.
• %name% and %TIER_COLOR% are tier-based placeholders used in socket lore.
  • %TIER_COLOR% is defined in the tiers section of engine.yml and determines the color used for sockets of each rarity.
• Sockets are matched with insertable items using the target-requirements.socket field.
• The actual socketing behavior (e.g., success rates, failure handling, GUI layout) is managed by the socketing module configuration, not this file.