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

# Events

All in `es.edwardbelt.edpets.iapi.event`. Every event extends `EdPetsEvent`, which **auto-detects the firing thread** — grind-driven events usually fire **async** (check `isAsynchronous()`, don't touch the world without hopping to main).

| Event                    | Fired when                | Notes                                                                                                |
| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `PetActivateEvent`       | A pet is being equipped   | **Cancellable**                                                                                      |
| `PetDeactivateEvent`     | A pet was unequipped      |                                                                                                      |
| `PetExperienceGainEvent` | A pet is about to gain XP | **Cancellable**, `setAmount(...)` mutable; hot path — only constructed when a listener is registered |
| `PetLevelUpEvent`        | A pet leveled up          | once per level gained                                                                                |
| `PetFuseEvent`           | A fusion attempt resolved | `isSuccess()`, `getResultPetTypeId()` (null on failure)                                              |
| `PetMasteryEvent`        | A pet prestiged           | `getMasteryLevel()`                                                                                  |

Common fields: `getPlayerId()`, `getPetId()` (the instance UUID), `getPetTypeId()`. `PetExperienceGainEvent#getSourceId()` names the grind source (`null` for candy/scrolls/admin XP).

```java
@EventHandler
public void onLevelUp(PetLevelUpEvent event) {
    if (event.getNewLevel() == 100) {
        // milestone reward — hop to main before touching the world
    }
}
```