> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borntocraftstudio.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Enchantment Definition

> Define a custom enchantment with modular mechanics.

# Custom Enchantment Definition

**Type:** `custom_enchantment_definition`

**Tags:** `custom_enchantment_definition`

Defines a custom enchantment with modular **mechanics** rather than cooldown-based triggers. Unlike `enchantment_definition`, this entry uses `EnchantmentMechanic` to compose behaviors from multiple game events.

## When to Use

| Use Case                                            | Entry Type                          |
| :-------------------------------------------------- | :---------------------------------- |
| Cooldown-based active triggers                      | `enchantment_definition`            |
| **Modular mechanics (multi-event, chance, levels)** | **`custom_enchantment_definition`** |

## Configuration

| Field             | Type                        | Default  | Description                                                                             |
| :---------------- | :-------------------------- | :------- | :-------------------------------------------------------------------------------------- |
| `id`              | String                      | ""       | Unique identifier for this entry                                                        |
| `name`            | String                      | ""       | Internal name                                                                           |
| `displayName`     | String                      | ""       | Display name shown in GUIs                                                              |
| `enchantmentLore` | String                      | ""       | Lore line added to items (supports MiniMessage colors)                                  |
| `nameColor`       | String (MiniMessage tag)    | `"gray"` | Color of the enchantment name. Uses MiniMessage syntax (e.g. `gray`, `gold`, `#ff5555`) |
| `supportedItems`  | `List<Material>`            | \[]      | Item types that can receive this enchantment                                            |
| `anvilCost`       | Int                         | 1        | XP levels required to combine in an anvil                                               |
| `maxLevel`        | Int                         | 1        | Maximum obtainable level                                                                |
| `weight`          | Int                         | 1        | Rarity weight for random selection                                                      |
| `minimumCost`     | `Cost`                      | `{}`     | Minimum cost when enchanting (see below)                                                |
| `maximumCost`     | `Cost`                      | `{}`     | Maximum cost when enchanting (see below)                                                |
| `mechanics`       | `List<EnchantmentMechanic>` | \[]      | Modular mechanics for this enchantment                                                  |

### Cost

| Field      | Type | Default | Description    |
| :--------- | :--- | :------ | :------------- |
| `base`     | Int  | 0       | Base cost      |
| `perLevel` | Int  | 0       | Cost per level |

### Mechanic

See [Enchantment Mechanic](../mechanic/enchantment_mechanic.mdx) for the full mechanic configuration.

## Example

```json theme={null}
{
  "id": "vampiric_strike",
  "name": "Vampiric Strike",
  "displayName": "<dark_red>Vampiric Strike",
  "nameColor": "dark_red",
  "supportedItems": ["DIAMOND_SWORD", "NETHERITE_SWORD", "NETHERITE_AXE"],
  "maxLevel": 5,
  "anvilCost": 3,
  "weight": 3,
  "minimumCost": { "base": 10, "perLevel": 5 },
  "maximumCost": { "base": 20, "perLevel": 8 },
  "mechanics": [
    {
      "event": "PLAYER_ATTACK",
      "actions": ["enchantment_creator:lifesteal_action"],
      "runOnLevel": 0,
      "chance": 100
    }
  ]
}
```