> ## 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.

# Enchantment Mechanic

> Modular mechanic system for custom enchantments.

# Enchantment Mechanic

**Type:** `EnchantmentMechanic` (data class)

Mechanics define modular behaviors attached to `custom_enchantment_definition`. Each mechanic listens for a specific game event and executes actions when criteria are met.

## Fields

| Field               | Type                          | Default         | Description                                                           |
| :------------------ | :---------------------------- | :-------------- | :-------------------------------------------------------------------- |
| `event`             | `EnchantmentEvent`            | `PLAYER_ATTACK` | Game event that triggers this mechanic                                |
| `criteria`          | `List<Criteria>`              | \[]             | Conditions that must be met for the actions to execute                |
| `actions`           | `List<Ref<TriggerableEntry>>` | \[]             | Actions executed when criteria are met                                |
| `clientSideEffects` | `List<Ref<TriggerableEntry>>` | \[]             | Client-side only effects (particles, sounds) via packets              |
| `runOnLevel`        | `Int`                         | 0               | Enchantment level required to run this mechanic. `0` means all levels |
| `chance`            | `Int`                         | 100             | Chance to trigger this mechanic (0-100%)                              |

## Available Events

See [Enchantment Events](../event/enchantment_event.mdx) for the full list of supported game events.

## Example

```json theme={null}
{
  "id": "custom_fire_sword",
  "name": "Inferno Blade",
  "displayName": "<red>Inferno Blade",
  "supportedItems": ["DIAMOND_SWORD", "NETHERITE_SWORD"],
  "maxLevel": 3,
  "mechanics": [
    {
      "event": "PLAYER_ATTACK",
      "criteria": [],
      "actions": ["enchantment_creator:lifesteal_action"],
      "runOnLevel": 0,
      "chance": 100
    },
    {
      "event": "BLOCK_BREAK",
      "criteria": [],
      "actions": ["enchantment_creator:haste_action"],
      "runOnLevel": 2,
      "chance": 50
    }
  ]
}
```

This example creates an enchantment that heals on attack at all levels, and has a 50% chance to activate haste when mining at level 2+.