The Essences Module defines magical essences — special items that apply effects, enhancements, or visual traits when socketed into gear. Each essence supports restrictions, visual effects, success rates, and usage limits.

Essences are stored in:

plugins/Divinity/modules/essences/

• items/ — Contains individual essence files (e.g., embers.yml)
• merchant.yml — Configures the merchant socketing GUI (see essence-merchant)
• settings.yml — Global settings and GUI behavior (see essence-settings)

Essences are defined as .yml files under items/. File name becomes the internal ID.

Example path:

plugins/Divinity/modules/essences/items/essence_trail.yml

material: GLOWSTONE_DUST
name: Essence of Trail
lore:
  - '&7Creates a &fLight Trail %ITEM_LEVEL_ROMAN% &7behind you.'
socket-display: '&eLight Trail %ITEM_LEVEL_ROMAN%'
enchanted: true
item-flags:
  - '*'
tier: common

level:
  min: 1
  max: 1

uses-by-level:
  '1': 1

success-rate-by-level:
  '1': '75'

effect:
  type: FOOT
  name: REDSTONE:225,225,125
  speed: 0.2
  amount: 15
  offset-x: 0.25
  offset-y: 0.1
  offset-z: 0.25

target-requirements:
  type:
    - ARMOR
  level:
    '1': 10
  module:
    - '*'
  socket: default

Control ambient visuals with the effect: section.

• SELF — Around player
• FOOT — Trails at feet
• HEAD — Above head

effect:
  type: FOOT
  name: FLAME
  speed: 0.1
  amount: 10
  offset-x: 0.2
  offset-y: 0
  offset-z: 0.2

Socket behavior is configured per level:

success-rate-by-level:
  '1': '75'
  '2': 30 * %ITEM_LEVEL%
  '3': '30:50'

uses-by-level:
  '1': 3

Control which items the essence can socket into:

target-requirements:
  type:
    - ARMOR
  level:
    '1': 5
  module:
    - custom_items
  socket: default

Each linked page below includes full YAML examples:

• essence-embers – Orange flames
• essence-frost – Icy trails
• essence-spores – Green spores
• essence-sparks – Redstone sparks
• essence-shadows – Smoke trails
• essence-bloom – Blooming petals
• essence-radiance – Yellow glow
• essence-storm – Electric bursts
• essence-void – Portal particles
• essence-ascension – Rising soul effect

• module-essences
• essence-merchant
• essence-settings
• module-drops
• actions-system-hub
• Home