> 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/edpets/developers/introduction.md).

# Developer API

EdPets ships a stable API in the `es.edwardbelt.edpets.iapi` package — three facets plus Bukkit events.

## Getting the API

1. Add EdPets to your `plugin.yml`:

```yaml
depend: [EdPets]        # or softdepend if it's optional
```

2. Compile against the `edpets-api` artifact (provided scope) or the plugin jar.
3. Grab the instance once EdPets has enabled:

```java
import es.edwardbelt.edpets.iapi.EdPetsAPI;

EdPetsAPI api = EdPetsAPI.getInstance();
if (api == null) return; // EdPets not enabled yet
```

## Facets

### `getBuffsAPI()` — grind + boosts (thread-safe, hot-path optimized)

```java
EdPetsBuffsAPI buffs = api.getBuffsAPI();
buffs.hasBuff(player, "my-source");             // O(1), async-safe
buffs.getBoost(player, "my-source");            // total percent (BigDecimal, 5 = +5%)
buffs.addExperience(player, "my-source");       // one grind action
buffs.addExperience(player, "my-source", 64);   // bulk (64 actions)
buffs.addRawExperience(player, "my-source", BigDecimal.valueOf(500)); // raw XP
```

### `getPetsAPI()` — ownership, slots, storage

```java
EdPetsPetsAPI pets = api.getPetsAPI();
pets.getPetTypeIds();
pets.givePet(uuid, "dragon", 1);
pets.getActivePetTypeIds(player);
pets.getActivePetIds(player);
pets.getPetLevel(uuid, petId);
pets.addPetExperience(uuid, petId, amount);
pets.getSlots(uuid);  pets.setSlots(uuid, 3);  pets.addSlots(uuid, 1);
pets.getStorageSize(uuid);  pets.setStorageSize(uuid, 80);  pets.addStorageSize(uuid, 10);
```

### `getVisualsAPI()` — the packet entities

```java
EdPetsVisualsAPI visuals = api.getVisualsAPI();
visuals.playGrindAnimation(player, "my-source");   // held-item + swing per animations.yml
visuals.setHeldItemOverride(player, itemStack);    // manual held item (null clears)
visuals.isShowingPets(player);
visuals.setShowingPets(player, false);             // same as /pets toggle
```

All buff methods are safe from async event pipelines — that's how the built-in PinnaPrison/EdTools/EdDungeons hooks call them. See [Custom Grind Sources](/p/edpets/developers/custom-sources.md) for the full integration recipe and [Events](/p/edpets/developers/events.md) for the event list.