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

# EdMobSwords API

Welcome to the developer API of EdMobSwords. Everything another plugin can do with the sword, the mobs and the zones goes through it.

### Dependency

The API is the `edmobswords-api` artifact (`EdMobSwords-API-<version>.jar`, built from the `api` module). It depends on Bukkit only — no EdLib, no EdTools types — and the EdMobSwords plugin ships the classes at runtime, so add it with `provided` scope.

```xml
<dependency>
    <groupId>es.edwardbelt</groupId>
    <artifactId>edmobswords-api</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>
```

### Getting the API instance

The API is set once EdMobSwords has enabled, so load after it:

```yaml
name: YourPlugin
main: com.yourdomain.yourplugin.Main
depend: [EdMobSwords]
```

```java
import es.edwardbelt.edmobswords.iapi.EdMobSwordsAPI;

EdMobSwordsAPI api = EdMobSwordsAPI.getInstance(); // null while EdMobSwords is not enabled
double damage = api.getCombatAPI().getSwordDamage(player);
```

The main interface gives access to the specialised APIs:

* `getZonesAPI()` — mob zones, sessions and spawn points, see [Zones API](/p/edmobswords/api/zones-api.md)
* `getMobsAPI()` — mob templates, see [Mobs API](/p/edmobswords/api/mobs-api.md)
* `getCombatAPI()` — damage numbers, hitting mobs, auto-hit, frenzy, see [Combat API](/p/edmobswords/api/combat-api.md)
* `getEnchantsAPI()` — registering your own sword enchants, see [Enchants API](/p/edmobswords/api/enchants-api.md)

### Threading

Every method is safe on any thread unless its documentation says otherwise. Mobs of a zone are packet entities, so hitting them, spawning them and reading their health never touches the Bukkit world; hits on real server mobs are applied on the main thread by the plugin itself.

### `SwordTarget`

The API's view of anything the sword can hit — a packet mob of a zone or a real entity:

| Method                                    |                                                             |
| ----------------------------------------- | ----------------------------------------------------------- |
| `key()`                                   | `packet:<entityId>` or `entity:<uuid>`                      |
| `entityId()`                              | the client-side entity id (packet mobs) or Bukkit entity id |
| `position()`, `world()`, `nameHeight()`   | where it is                                                 |
| `isAlive()`, `health()`, `maxHealth()`    | its health (a server-side number for packet mobs)           |
| `typeId()`                                | the mob template id, or the entity type name for real mobs  |
| `displayName()`                           | coloured name                                               |
| `stackSize()`                             | RoseStacker stack size for real mobs, otherwise 1           |
| `isPacketMob()`, `zoneId()`, `isShared()` | zone info; `isShared()` is true in a global session         |
| `bukkitEntity()`                          | the real entity, or `null` for packet mobs                  |