Creating Enchantments

This guide covers every field available in enchantment YAML files, with a complete annotated example.

Quick Start

1. Create a new .yml file in plugins/SuperEnchants/enchants/ (the filename becomes the enchant ID)

2. Add the required fields

3. Run /sereload to load it

4. Test with /segive <id> 1

Complete YAML Field Reference

# ============================================================
# REQUIRED FIELDS
# ============================================================

# Display name shown on items (MiniMessage format)
display_name: "<green>My Enchant"

# Maximum enchantment level (1-10)
max_level: 3

# Which items this enchant can be applied to
# Can be item group names or specific material names
applicable_items:
  - SWORDS
  - AXES

# When the enchantment activates
# Options: ATTACK_ENTITY, KILL_ENTITY, TAKE_DAMAGE, RIGHT_CLICK,
#          BLOCK_BREAK, BOW_SHOOT, PROJECTILE_HIT, FISHING,
#          FISH_BITE, PASSIVE, SNEAK, DEATH
trigger: ATTACK_ENTITY

# Who the enchantment affects
# Options: SELF, PLAYERS, MOBS, ALL_ENTITIES, NONE
target: ALL_ENTITIES

# ============================================================
# OPTIONAL FIELDS
# ============================================================

# Description shown in item lore (MiniMessage format)
description:
  - "<gray>Line one of description."
  - "<gray>Line two of description."

# Cooldown between activations in milliseconds (0 = no cooldown)
cooldown: 5000

# Probability of triggering (omit entirely for 100% activation)
chance:
  base: 0.10        # Base chance at level 1
  per_level: 0.05   # Additional chance per level
  # Result: Level 1 = 15%, Level 2 = 20%, Level 3 = 25%
  #
  # For fixed chance (same at all levels):
  # scaling: fixed
  # value: 0.5

# List of enchant IDs this conflicts with
conflicts:
  - other_enchant_id

# ============================================================
# ENCHANTING TABLE (optional section)
# ============================================================

enchanting_table:
  enabled: true      # Whether it appears in enchanting table
  weight: 5          # Rarity weight (higher = more common)
  min_cost: 10       # Minimum enchanting level cost
  max_cost: 30       # Maximum enchanting level cost

# ============================================================
# VILLAGER TRADES (optional section)
# Overrides enchanting_table settings for librarian villagers.
# If omitted, falls back to enchanting_table.enabled/weight
# and global emerald costs from config.yml.
# ============================================================

villager_trades:
  enabled: true          # Whether it appears in villager trades
  weight: 5              # Rarity weight (higher = more common)
  base_emerald_cost: 10  # Minimum emerald cost
  max_emerald_cost: 32   # Maximum emerald cost

# ============================================================
# LOOT GENERATION (optional section)
# Overrides enchanting_table settings for chest loot.
# If omitted, falls back to enchanting_table.enabled/weight.
# ============================================================

loot_generation:
  enabled: true   # Whether it appears in chest loot
  weight: 5       # Rarity weight (higher = more common)

# ============================================================
# SOUND ON ACTIVATION (optional section)
# ============================================================

sound:
  type: entity_experience_orb_pickup  # Minecraft sound registry name (lowercase, underscored)
  volume: 1.0                          # Volume (0.0 - 1.0)
  pitch: 1.0                           # Pitch (0.5 - 2.0)

# ============================================================
# PARTICLE ON ACTIVATION (optional section)
# ============================================================

particle:
  type: CRIT                  # Particle enum name (UPPERCASE)
  count: 10                   # Number of particles
  spread: 0.5                 # Spread radius
  speed: 0.1                  # Particle speed
  location: TARGET            # Where to spawn: SELF, TARGET, or BLOCK

# ============================================================
# ACTIONS (the actual effects)
# ============================================================

actions:
  my_action_key:              # Unique key name (any string, used internally)
    type: potion_effect       # Action type name (see Action Types page)
    # ... action-specific parameters (see Action Types page)

Field Details

display_name (required)

The name shown on items when this enchantment is applied. Supports MiniMessage formatting for colors and styles.

display_name: "<gradient:#FF6B6B:#FFD93D>Fire Storm"
display_name: "<bold><red>Inferno"
display_name: "<aqua>Frost"

max_level (required)

The maximum level this enchantment can reach. Typically 1-5. Level affects scaling function values.

applicable_items (required)

List of item groups or material names this enchant can be applied to. See Item Groups for all available groups.

applicable_items:
  - SWORDS           # Item group
  - DIAMOND_PICKAXE  # Specific material

trigger (required)

When the enchantment activates. See Triggers and Targets for details.

target (required)

Who the enchantment affects. See Triggers and Targets for details.

description (optional)

List of MiniMessage-formatted strings shown in item lore below the enchant name.

cooldown (optional)

Milliseconds between activations. Default is 0 (no cooldown). Common values:

• 3000 = 3 seconds

• 5000 = 5 seconds

• 10000 = 10 seconds

chance (optional)

Activation probability as a Scaling Function. Omit entirely for 100% activation.

conflicts (optional)

List of enchantment IDs that cannot coexist with this enchant. See Conflicts.

enchanting_table (optional)

Controls appearance in enchanting tables. If omitted or enabled: false, the enchant only appears via commands, anvil, villagers, or loot. The weight and enabled fields also serve as the fallback for villager_trades and loot_generation if those sections are absent.

villager_trades (optional)

Controls per-enchant appearance in librarian villager trades. If this section is absent, the enchant falls back to enchanting_table.enabled / enchanting_table.weight, with emerald costs from the global config.yml values. The global villager-trades.enabled: false in config.yml disables all villager trades regardless of per-enchant settings.

Field	Description
enabled	Whether this enchant appears in villager trades
weight	Rarity weight (higher = more common)
base_emerald_cost	Minimum emerald cost
max_emerald_cost	Maximum emerald cost

loot_generation (optional)

Controls per-enchant appearance in chest loot. If absent, falls back to enchanting_table.enabled / enchanting_table.weight. The global loot-generation.enabled: false in config.yml disables all loot generation regardless.

Field	Description
enabled	Whether this enchant appears in chest loot
weight	Rarity weight (higher = more common)

sound (optional)

Sound played on activation. The type is a Minecraft sound registry key in lowercase with underscores (e.g., entity_lightning_bolt_thunder, entity_experience_orb_pickup).

particle (optional)

Particle effect spawned on activation. The type is a Bukkit Particle enum name in UPPERCASE (e.g., CRIT, FLAME, ELECTRIC_SPARK, HEART). The location determines whether particles spawn at the player (SELF), the target entity (TARGET), or the block (BLOCK).

actions (required for functional enchants)

The map of effects this enchantment applies. Each action has a unique key and a type that determines its behavior. See Action Types for the full list with parameters.

Complete Example: Custom Sword Enchantment

display_name: "<gradient:#FF4500:#FFD700>Solar Flare"
description:
  - "<gray>Chance to ignite and blind enemies on hit."
max_level: 3
applicable_items:
  - SWORDS
trigger: ATTACK_ENTITY
target: ALL_ENTITIES
cooldown: 3000
chance:
  base: 0.15
  per_level: 0.05
enchanting_table:
  enabled: true
  weight: 3
  min_cost: 15
  max_cost: 30
villager_trades:
  enabled: true
  weight: 3
  base_emerald_cost: 15
  max_emerald_cost: 28
loot_generation:
  enabled: true
  weight: 3
sound:
  type: entity_blaze_shoot
  volume: 0.8
  pitch: 1.2
particle:
  type: FLAME
  count: 20
  spread: 0.5
  speed: 0.1
  location: TARGET
conflicts:
  - frostbite
actions:
  burn:
    type: set_fire
    duration:
      base: 40
      per_level: 20
  blind:
    type: potion_effect
    effect: blindness
    duration:
      base: 20
      per_level: 10
    amplifier:
      scaling: fixed
      value: 0
    particles: false
    icon: true

Testing

After creating your enchantment:

1. Run /sereload

2. Check console for any loading errors

3. Give yourself a book: /segive <your_enchant_id> 1

4. Apply it to an appropriate item on an anvil

5. Test the trigger (hit an entity, break a block, etc.)