> For the complete documentation index, see [llms.txt](https://edseries-plugins.gitbook.io/p/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://edseries-plugins.gitbook.io/p/features/enchantments.md).

# Enchantments

You will be able to make infinite Enchantments with a lot of actions to execute, such as spawning mobs or generating explosions.

Enchantments live in `enchantments.yml`. Enchants only trigger while mining with the EdPrison pickaxe inside a WorldGuard region flagged `edp-enchants`.

## Main Config

```yaml
keyfinder:
  enabled: true
  type: custom
  event-trigger: BlockBreakEvent
  max-chance: 20
  always-max-chance: false
  max-level: 20
  currency: tokens
  starting-cost: 100
  increase-cost-by: 400
  starting-level: 0
```

This is the main config that almost every enchant will have. It has the following options:\
**enabled** -> Enables/disables the enchant.\
**type** -> `custom` or `mc-enchant` (see Types below).\
**event-trigger** -> When the enchant can fire (custom enchants) — see [Custom Enchantments](/p/features/enchantments/custom-enchantments.md).\
**max-chance** -> The activation chance (%) at max-level. The chance scales linearly with level: `chance = level * max-chance / max-level`.\
**starting-chance** -> Optional chance floor: `chance = level * (max-chance - starting-chance) / max-level + starting-chance`.\
**always-max-chance** -> Will the enchant have a 100% proc chance all the time?\
**max-level** -> The max level of the enchant.\
**currency** -> The currency that will upgrade the enchant.\
**starting-cost** -> The enchant starting cost (cost of level 1).\
**increase-cost-by** -> The added cost per level (arithmetic progression, same formula as levels).\
**starting-level** -> The level granted to new players.\
**lazy** -> Batches triggers: instead of firing per block, the enchant fires once per mining tick with `%lazy.blocks%` = how many blocks were processed (used by `tokenminer` for performance).\
**blocks-to-trigger** -> "Exact probability" mode — instead of a % chance, the enchant fires exactly once every N blocks mined (tracked across sessions), with `%exact.times%` available.\
**enchantment** -> For `mc-enchant` only: the Bukkit enchantment name (e.g. `DIG_SPEED`).\
**actions** -> For `custom` only: the action script executed on trigger. See [Actions](/p/features/enchantments/custom-enchantments/actions.md).

## Types

### mc-enchant

This option are for Minecraft vanilla enchantments such as DIG\_SPEED (efficiency), applied to the pickaxe.

### custom

This are for custom enchants that everyone can make through the config with the actions system.

### predone

This will be predone enchantments done via the API or handled internal by EdPrison.\
Are you interested in making enchants via the API? See [Developer API → Custom Enchantments](/p/developer-api/enchants/custom-enchantments.md).

## Buying, refunds and menus

* Players upgrade enchants through the `enchant-menu` / `upgrade-menu` GUIs, which call the console commands `edp enchantasplayer <player> <enchant> <levels>` and `edp refundasplayer <player> <enchant> <levels>`.
* Refunds return a percentage of the paid cost, configured in `config.yml`:

```yaml
enchantments:
  refund:
    type: percent      # percent | permission
    percent: 40        # % returned
```

With `type: permission` the percent is read from the player's `edprison.refund.<percent>` permission node (fallback: 1%).

* Admins can edit levels directly: `/admin enchant <player> <enchant> <+N|-N|N>` and `/admin resetenchant <enchant>` (resets it for everyone).

After editing `enchantments.yml`, run `/edprison reload`. Add a matching entry to `guis.yml` (`enchant-menu`) so players can buy the enchant, and optionally a lore line on the pickaxe.

## Developer events

The enchant engine fires Bukkit events other plugins can listen to: `EdPrisonPossibleEnchantTriggerEvent` (cancellable, can modify the chance), `EdPrisonEnchantTriggerEvent` (cancellable) and `EdPrisonEnchantFinishTriggerEvent` — see the [Developer API](/p/developer-api/events.md).