> ## Documentation Index
> Fetch the complete documentation index at: https://entities.lodemc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Pets

> Read and drive players' pets from code, and react to taming and summoning.

`LodeEntitiesAPI.pets()` covers [pets](https://entities.lodemc.net/pets.md): mobs with a `pet:` block, and the collections players own. A player's collection is only loaded while they are online, so the per-player calls answer empty (or `false`) for anyone offline.

```java theme={null}
PetsAPI pets = LodeEntitiesAPI.pets();

Set<String> petMobs = pets.ids();                     // every mob that can be a pet
boolean isPet = pets.isPet(entity);                   // a pet that is out right now
UUID owner = pets.ownerOf(entity);                    // null when it isn't a pet
PetRecord record = pets.recordOf(entity);             // the pet behind that body

List<PetRecord> owned = pets.petsOf(player);          // in the order they got them
List<Entity> out = pets.activeOf(player);             // the ones out right now

PetRecord gift = pets.give(player, "fox_spirit");     // null if it can't be a pet or they're at the cap
String why = pets.summon(player, gift.getId());       // null on success, else the reason
pets.dismiss(player, gift.getId());
pets.addExperience(player, gift.getId(), 50);         // false when it isn't out
pets.openMenu(player);                                 // the /le pets menu
```

A `PetRecord` is the pet itself, out or not: its `id` (stable across summons, evolutions and skins), `mobId`, `name`, `level`, `xp`, `mode`, `skin`, `health` and backpack. The entity is only its body while it is summoned.

> [!NOTE]
>
> Pets are premium. On the free version no mob is pet-capable, so `ids()` is empty and `give` returns `null`.

## Events

Both live in `org.nexomaker.api.event` and are cancellable.

| Event | Fires when | Cancelling |
| :- | :- | :- |
| `PetTameEvent` | A taming attempt has won its roll, before the mob becomes `player`'s pet. Carries `player`, `entity` and `definition`. | Fails the attempt as if the roll missed: `+onTameFail` runs and the item is still spent. |
| `PetSummonEvent` | A player summons one of their pets, before it appears. Carries `player`, `petId` and `definition`. | Keeps it in the collection. |

```java theme={null}
@EventHandler
public void onTame(PetTameEvent event) {
    if (isInSpawnRegion(event.getEntity().getLocation())) event.setCancelled(true);
}
```

Pets also fire the ordinary [`LodeEntitiesMobSpawnEvent`](addon-events) when their body spawns, and their effect lines get the [pet triggers](https://entities.lodemc.net/pets.md#pet-triggers).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.