> 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/edmobswords/api/enchants-api.md).

# Enchants API

`EdMobSwordsEnchantsAPI` — register your own sword enchants and read enchant settings.

```java
EdMobSwordsEnchantsAPI enchants = EdMobSwordsAPI.getInstance().getEnchantsAPI();
```

## Your own sword enchant

1. Create `plugins/EdTools/enchants/<id>.yml` like the shipped ones, with `type: 'api'` and `tool: 'sword-tool'`. Chance, levels, cost, cooldown, prestige, toggles and the proc message are EdTools' — nothing to code.
2. Register a `SwordEnchant`:

```java
enchants.registerEnchant("sword-shockwave", (player, hit) -> {
    SwordTarget target = hit.getTarget();                    // the mob that was hit
    double damage = enchants.getSetting("sword-shockwave", "damage", player, hit.getDamage(), hit.getDamage());
    double radius = enchants.getSetting("sword-shockwave", "radius", player, hit.getDamage(), 4);
    int hits = 0;
    for (SwordTarget other : hit.nearby(target.position(), radius, 0, target)) {
        if (hit.hit(other, damage, "sword-shockwave")) hits++;   // no re-procs, rewards/respawn handled
    }
    enchants.sendProcMessage(player, "sword-shockwave", "{mobs}", String.valueOf(hits));
});
```

`onProc` runs on an async worker: send packets freely, hop to the main thread for anything that touches the Bukkit world (`hit.hit` already does that for real entities). The enchant is re-registered in EdTools automatically on every reload; register it once in your `onEnable`.

### `SwordHit`

| Method                                                               |                                                             |
| -------------------------------------------------------------------- | ----------------------------------------------------------- |
| `getPlayer()`, `getToolId()`                                         | who swung, with which tool                                  |
| `getTarget()`                                                        | the mob that was hit                                        |
| `getDamage()`, `isKillingBlow()`                                     | the swing damage and whether it killed the mob              |
| `isPacketFight()`                                                    | true in a mob zone, false against a real server mob         |
| `getWorld()`, `isActive()`, `getPlayerPosition()`                    | fight state                                                 |
| `nearby(center, radius, limit, exclude)`, `all()`, `random(exclude)` | the other mobs of the fight                                 |
| `hit(target, damage, enchantId)`                                     | hurt a mob on the enchant's behalf; returns whether it died |

***

### Methods

#### `registerEnchant(String id, SwordEnchant enchant)` / `unregisterEnchant(String id)`

Register (replace) or remove an enchant.

#### `getBuiltInEnchantIds()` / `getRegisteredEnchantIds()`

The 26 shipped enchants, and the ones registered through the API.

#### `getSettings(String enchantId)`

The `settings:` section of the enchant's yml, or `null`.

#### `getSetting(String enchantId, String key, Player player, double damage, double def)`

Evaluates `settings.<key>` for a player: placeholders and math resolved, `{damage}` replaced by `damage`.

#### `sendProcMessage(Player player, String enchantId, Object... replacements)`

Sends the enchant's `proc-message` (respecting the player's message toggle) with `{key}, value` pairs.

#### `triggerEnchants(Player player, SwordHit hit)`

Rolls every sword enchant the player owns against a hit, exactly like a real swing does.