Creating Enchants

Your First Enchant

Enchants are YAML files stored in the enchants/ folder.

Example: Fire Strike

Create fire-strike.yml:

fire-strike.yml

enchant-id: fire-strike
display-name: "&c&lFire Strike"
menu-material: "BLAZE_POWDER"

progression:
  starting-level: 1
  max-level: 10

activation:
  trigger: "HIT_MOB"
  base-chance: 25.0
  chance-per-level: 2.0
  cooldown-seconds: 3

upgrade:
  currency: "money"
  base-cost: 1000
  scaling: "linear"
  scaling-multiplier: 1.5

actions:
  1:
    type: "set-fire"
    entity: "{target_mob}"
    duration: 100

That's it. This creates an enchant that has a 25% chance (increasing by 2% per level) to set mobs on fire when hit.

Configuration Structure

Every enchant file has the same structure. Let's break down each section.

Basic Settings

enchant-id: your-enchant-id
display-name: "&a&lYour Enchant Name"
menu-material: DIAMOND

Field	Description
enchant-id	Unique identifier.
display-name	Name shown in menus (supports color codes like &a, &l, or hex etc.)
menu-material	Item displayed in the enchants menu (must be valid Minecraft material)

Tip: Your enchant ID should match the filename. For example, fire-strike.yml should have enchant-id: fire-strike

Progression System

Controls how players level up the enchant:

progression:
  starting-level: 1
  max-level: 100

Parameters:

Field	Description	Common Values
starting-level	Level players start at when they first get the enchant	1 or 0
max-level	Maximum level for this enchant	10, 25, 50, 100

When to use starting level 0:

• For enchants that need to be "unlocked" before they work

• When you want the first purchase to activate the enchant

When to use starting level 1:

• Most common - enchant works immediately at level 1

• Players purchase to upgrade, not to unlock

Activation Settings

Controls when and how often the enchant triggers:

activation:
  trigger: "HIT_MOB"
  base-chance: 15.0
  chance-per-level: 1.5
  cooldown-seconds: 2

Trigger Types

Type	When It Activates	Use Cases
HIT_MOB	When player hits a mob with their sword	Damage effects, particles, chance-based abilities
ENCHANT_PROC	When the source condition is met	Only activating specific enchants based on other enchants
MOB_DEATH	When player kills a mob	Reward enchants (currency, healing, explosions)
PASSIVE	Always active while sword is held	Potion effects (speed, strength, regeneration), constant enchants?
CUSTOM	For advanced custom Java implementations	Complex logic that needs programming

Chance System

The chance system determines how often your enchant activates.

Formula:

Total Chance = base-chance + (level × chance-per-level)

Example:

base-chance: 15.0
chance-per-level: 1.5

At level 5: 15 + (5 × 1.5) = 22.5% chance to activate

For PASSIVE enchants: Set base-chance: 100.0 and chance-per-level: 0.0 since they're always active.

Cooldown

Prevents enchant from activating too frequently:

cooldown-seconds: 3

• Measured in seconds (not ticks)

• 0 = no cooldown

• Recommended: 2-5 seconds for balanced gameplay

• For PASSIVE: use 0 (no cooldown needed)

Upgrade Costs

Determines how much it costs to level up the enchant:

upgrade:
  currency: "souls"
  base-cost: 500
  scaling: "linear"
  scaling-multiplier: 1.2

Currency

currency: "money"

The currency ID that players spend to upgrade. Must match a currency configured in the economy module.

Common currencies:

• money - Main currency

• souls - Secondary currency

• sword-xp - Experience points

• Custom currency IDs you've created

Scaling Types

Determines how costs increase with each level:

Linear Scaling

scaling: "linear"
scaling-multiplier: 1.2

Formula: base-cost + (multiplier × level)

Example: Base 500, multiplier 1.2

• Level 1: 500 + (1.2 × 1) = 501.2

• Level 5: 500 + (1.2 × 5) = 506

• Level 10: 500 + (1.2 × 10) = 512

When to use: Gentle cost increase, affordable long-term progression

Exponential Scaling

scaling: "exponential"
scaling-multiplier: 1.15

Formula: base-cost × (multiplier ^ level)

Example: Base 500, multiplier 1.15

• Level 1: 500 × (1.15 ^ 1) = 575

• Level 5: 500 × (1.15 ^ 5) = 1,005

• Level 10: 500 × (1.15 ^ 10) = 2,023

When to use: Costs ramp up quickly, creates endgame grind

Custom Scaling

scaling: "custom"

Formula: Always base-cost

When to use: Fixed cost per level (rare use case)

Actions Section

Actions are what happen when your enchant activates. This is the "effect" part of your enchant.

actions:
  1:
    type: "damage-area"
    position: "{trigger_pos}"
    radius: 5
    damage: 100
  2:
    type: "particle-effect"
    particle: "FLAME"
    position: "{trigger_pos}"
    count: 50

Structure:

• Actions are numbered (1:, 2:, 3:, etc.)

• They execute in order (1 first, then 2, then 3)

• Each action has a type and various parameters

Learn More: See Enchant Actions for a complete list of all available actions and their parameters.

Complete Example

Here's a fully configured enchant with explanations:

soul-harvest.yml

# Soul Harvest - Gain souls when killing mobs
enchant-id: soul-harvest
display-name: "&5&lSoul Harvest"
menu-material: SOUL_LANTERN

progression:
  starting-level: 1    # Players start at level 1
  max-level: 50        # Can upgrade to level 50

activation:
  trigger: "MOB_DEATH"       # Triggers when killing mobs
  base-chance: 100.0         # Always activates (100%)
  chance-per-level: 0.0      # No increase needed
  cooldown-seconds: 0        # No cooldown for rewards

upgrade:
  currency: "money"          # Costs money to upgrade
  base-cost: 2500           # First upgrade costs 2,500
  scaling: "linear"          # Costs increase steadily
  scaling-multiplier: 1.3    # +1.3 per level

actions:
  # Step 1: Calculate random souls with level bonus
  1:
    type: "set-variable"
    name: "souls_gained"
    value: "%phantomdungeons_math_random_1_10% + {level}"
  
  # Step 2: Give the souls to player
  2:
    type: "add-currency"
    currency: "souls"
    amount: "{souls_gained}"
  
  # Step 3: Show hologram above dead mob
  3:
    type: "hologram"
    position: "{target_pos}"
    text: "&5&l+{souls_gained} Souls"
    style: "reward"
    duration: 60
  
  # Step 4: Spawn particles
  4:
    type: "particle-effect"
    particle: "SOUL"
    position: "{target_pos}"
    count: 20
    offset-x: 0.5
    offset-y: 1.0
    offset-z: 0.5
    speed: 0.05
  
  # Step 5: Play sound
  5:
    type: "sound-effect"
    sound: "ENTITY_PLAYER_LEVELUP"
    position: "{player_pos}"
    volume: 0.5
    pitch: 1.5

Naming Conventions

DO:

• Use lowercase with hyphens: fire-strike, soul-harvest

• Keep IDs short but descriptive

• Match filename with enchant-id

DON'T:

• Use spaces: fire strike

• Use uppercase: FireStrike

• Use special characters: fire_strike!

Performance

DO:

• Use reasonable particle counts (10-50)

• Set appropriate cooldowns (2-5 seconds)

• Limit area effect radius (5-15 blocks)

DON'T:

• Spawn 1000s of particles

• Create no-cooldown spam effects

• Make huge damage radius (causes lag)

Testing Your Enchant

1

Restart / Reload

Restart or reload the server (e.g., /dungeons reload) to load the new enchant file.

2

Check Console

Look for any YAML parsing errors or startup warnings in the server console.

3

Test Activation

Hit or kill mobs depending on the trigger to test the enchant's behavior.

4

Adjust Values

Tweak chances, cooldowns, costs, and actions based on testing results.

Troubleshooting

Enchant Not Activating

Problem: Enchant shows in menu but never triggers

Solutions:

• ✓ Verify trigger type is correct

• ✓ Check base-chance isn't too low

• ✓ Test without cooldown-seconds temporarily

• ✓ Ensure actions section is properly formatted

• ✓ Look for errors in console

Wrong Cost Displayed

Problem: Upgrade cost shows incorrect amount

Solutions:

• ✓ Check scaling type spelling

• ✓ Verify scaling-multiplier is reasonable

• ✓ Ensure currency ID exists

• ✓ Test cost formula with online calculator