> ## 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.

# Pet Settings

> Every field of a mob's pet: block, the pets section of config.yml, commands and permissions.

> [!NOTE]
>
> Pets are a **premium** feature. See [Licensing](https://entities.lodemc.net/licensing.md).

## The `pet:` block

A mob becomes pet-capable with a `pet:` block. `pet: true` is a pet with every default; anything unreadable inside the block is reported by [`/le debug`](debug) and falls back to its default, rather than costing the mob its pet-ness.

| Field | Default | What it does |
| :- | :- | :- |
| `tame` | none | How a wild one is tamed: `item` (a vanilla id or `source:id` like `nexo:treat`), `chance` (`0.25` or `25%`, default `1`), `consume` (default `true`, spent on success **and** failure). Short form: `tame: bone`. Without it the pet can only be claimed or given. |
| `permission` | none | Players with this node can claim it from `/le pets`. |
| `icon` | its spawn egg | The item shown for it in `/le pets`. |
| `mode` | `defend` | Starting fighting mode: `defend`, `aggressive` or `passive`. The owner can switch it. |
| `follow` | `4` / `24` / `1.2` | `distance` (blocks before it walks back), `teleport` (blocks before it teleports; must be further than `distance`) and `speed` (`0.1`–`4`). |
| `mount` | `none` | `walk`, `fly` or `none`. |
| `mount-speed` | `1` | Speed multiplier while ridden, `0.1`–`10`. |
| `respawn` | `60` | How long before a dead pet can be summoned again. A bare number is seconds; `2m` and `400t` work too. |
| `inventory` | `0` | Backpack slots. Rounded up to whole rows of 9, at most 54. `0` is no backpack. |
| `rename` | `true` | Whether the owner may name it. `&` colours are allowed. |
| `skins` | none | Other models the owner can dress it in: a model name, or `{ model, name, permission }`. |
| `food` | none | What it eats: a list of `{ item, heal, xp, effects, consume }`, or a block keyed by item. `effects` are effect lines run with the pet as caster and the feeder as `@trigger`. |
| `levels` | no levels | `max` (default `20`), `xp` for level 2 (default `100`), `growth` (default `1.25`), `kill-xp` (default `10`), and the per-level bonuses `health`, `damage`, `armor`, `speed`. |
| `evolve` | none | `into` (a mob with a `pet:` block of its own) and `level` (2 or more). |
| `signals` | from its `+onSignal` lines | Menu buttons: `howl: "Howl"`, or `howl: { name: "Howl", icon: goat_horn }`, or a plain list of names. |

Broken links are dropped, never the pet: an `evolve.into` that doesn't exist (or has no `pet:` block) and a skin model that isn't loaded are reported, and the pet loads without them.

### Food as a block

The two `food` forms read the same:

```yaml theme={null}
    food:
    - { item: bone, heal: 4, xp: 5 }
    - { item: nexo:dog_treat, heal: 10, xp: 25, effects: ["particle{p=heart;a=6} @self"] }
```

```yaml theme={null}
    food:
      bone: { heal: 4, xp: 5 }
      cooked_beef: { heal: 8 }
```

### How levels add up

Experience to go from level `n` to `n+1` is `xp × growth^(n-1)`. With the defaults, level 2 costs 100, level 3 costs 125, level 4 about 156. Each level above 1 adds the per-level bonus once: a pet at level 5 with `health: 2` has 8 more max health than the mob's own.

## `config.yml`

Server-wide settings, under `pets:`, applied on `/le reload`:

| Option | Default | What it does |
| :- | :- | :- |
| `pets.max-active` | `1` | Pets one player can have out at once (up to 64). Summoning another puts the oldest away. |
| `pets.max-owned` | `0` | Pets one player can own in total. `0` is no limit. |
| `pets.owner-can-hurt` | `false` | Whether an owner's hits land on their own pets. Off, a swing that clips your pet does nothing. |
| `pets.autosave` | `60` | Seconds between saves of collections that changed. They're always saved on logout and shutdown; this only bounds what a crash could lose. |
| `pets.max-name-length` | `32` | Longest name an owner may give a pet, colour codes included. |

## Commands and permissions

| Command | Permission | Default | What it does |
| :- | :- | :- | :- |
| `/le pets` | `lodeentities.pets` | **everyone** | Opens your pets: summon, put away, ride, rename, skins, backpack, signals, release. |
| `/le pets give <player> <mob>` | `lodeentities.pets.give` | OP | Adds a pet of `<mob>` (one with a `pet:` block) to a player's collection. Works from the console. |

`/le pets` is the one LodeEntities command every player has by default. Take `lodeentities.pets` away from a group to keep pets from them.

The `permission` of a pet and of each skin are nodes you make up; grant them with your permissions plugin.

## On the free version

Every `pet:` block is dropped at load and the mob is registered as an ordinary wild mob. The console and [`/le debug "Mobs (pets)"`](debug) list each one (`Pets are a premium feature.`), and `/le pets give` refuses with the same reason. Nothing else about the mob changes, and once a license is added the pets load on the next reload.

## From code

`LodeEntitiesAPI.pets()` and the `PetTameEvent` and `PetSummonEvent` events: see [Pets](https://entities.lodemc.net/addon-pets.md) in the API section.


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