# Enchantments

Enchantments in EdTools are powerful, custom abilities you can add to your OmniTools. They are not vanilla enchantments and are defined entirely by your configurations, allowing for nearly limitless possibilities.

### Creating an Enchantment

Create a new `.yml` file in `plugins/EdTools/enchants/`. The filename becomes the unique Enchant ID.

**Example: `enchants/crop-barn.yml`**

```yaml
# The maximum chance (out of 100) this enchant can have to activate.
max-chance: 100
# The level this enchant starts with when a player first gets the tool.
starting-level: 0
# The maximum level this enchant can be upgraded to.
max-level: 1000
# The material to display in GUIs. Can be a standard material, a player head texture, or a placeholder.
material: "texture-eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNGE5OTUzY2U5NDVkYTZlMmZiODAwMzBlNzU0ZmE4ZTA5MmM0ZTllY2QwNTQ4ZjkzOGMzNDk3YTgwOGU0MWE0OCJ9fX0="
# Type of enchant. 'CUSTOM' for complex actions, 'EFFECT' for simple potion effects.
type: 'custom'
# The ID of the tool this enchant belongs to.
tool: 'crop-tool'
# The friendly name for display purposes.
display-name: 'Barn'

# The cost to upgrade the enchant.
cost:
  currency: farm-coins
  starting-cost: 100
  increase-cost-by: 500

# The sequence of actions to perform when the enchant procs.
actions:
  spawn-cow:
    type: 'spawn-entity'
    entity: 'COW'
    entity-id: 'my_cow' # A temporary ID to reference this cow in later actions
    pos: '{enchant_pos}'
  add-goal:
    type: 'add-goal'
    entity: 'my_cow'
    goal: 'move-to-pos'
    pos: '%edtools_randompos_{enchant_pos}|15,0,15%'
    speed: 0.3
  break-blocks-loop:
    type: 'loop'
    ticks-between: 5
    loop-count: 40
    parallel: false
    actions:
      break_blocks:
        type: 'break-blocks'
        radius-pos: '{my_cow:pos}' # Use the spawned cow's position
        x-radius: 3
        z-radius: 3
        affect-sell: true
  remove-entity:
    type: 'remove-entity'
    entity: 'my_cow'
```

### Enchant Actions

Actions are the building blocks of custom enchants, defined under the `actions` key. They are executed in order when an enchant activates.

| Action Type         | Description                                                 | Key Parameters                                     |
| ------------------- | ----------------------------------------------------------- | -------------------------------------------------- |
| `break-blocks`      | Breaks blocks in a defined area within a Regen Zone.        | `from`, `to` (vectors) or `radius-pos`, `x-radius` |
| `loop`              | Repeats a sequence of nested actions multiple times.        | `loop-count`, `ticks-between`, `actions`           |
| `spawn-entity`      | Spawns a custom entity.                                     | `entity`, `pos`, `entity-id` (for referencing)     |
| `add-goal`          | Adds an AI goal to a spawned entity (e.g., move, follow).   | `entity`, `goal`, `pos`, `speed`                   |
| `remove-entity`     | Removes a previously spawned entity by its ID.              | `entity` (the `entity-id` from spawning)           |
| `give-eco`          | Gives a player a specified amount of a custom currency.     | `currency`, `amount`                               |
| `sell-item`         | Sells an item for the player based on `item-prices.yml`.    | `item`, `amount`                                   |
| `add-backpack-item` | Adds a backpack sellable item to the player's backpack.     | `item`, `amount`                                   |
| `command`           | Executes a command from the console.                        | `command`                                          |
| `delay`             | Pauses the action sequence for a specified number of ticks. | `ticks`                                            |
| `give-effect`       | Gives the player a potion effect.                           | `effect`, `level`, `ticks`                         |
| `remove-effect`     | Removes a potion effect from the player.                    | `effect`                                           |
| `particle`          | Spawns a particle at a location.                            | `particle`, `pos`                                  |
| `message`           | Sends a message to the player.                              | `message`                                          |
