Skip to content

module essences

Jump to bottom
goflishMC edited this page Jun 30, 2025 · 5 revisions

✴️ Essences Module

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.

📁 File Locations

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)

🧱 Defining Essences

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

Example path:

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

🧪 Full Example

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

✨ Particle Effects

Control ambient visuals with the effect: section.

type Options

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

Example

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

🎯 Socketing Mechanics

Socket behavior is configured per level:

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

uses-by-level:
  '1': 3

📐 Target Restrictions

Control which items the essence can socket into:

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

📋 Commands & Permissions

Command Description Permission
/essence merchant <player> [force<true/false>] Open merchant socket GUI for player divinity.essence.merchant
/essence help Show help page divinity.essence.help
/essence get <id> [level] [amount] Get an essence item divinity.essence.get
/essence give <player> <id> [level] [amount] Give an essence to a player divinity.essence.give
/essence drop <world> <x> <y> <z> <id> [level] [amount] Drop essence in world divinity.essence.drop
/essence list [page] List defined essence items divinity.essence.list
/essence reload Reload the module divinity.essence.reload

🌟 Visual Effect Examples

Each linked page below includes full YAML examples:

📚 Related Pages

Clone this wiki locally