> 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/items/pet-boxes.md).

# Pet Boxes

Pet boxes are right-click loot boxes that roll weighted pets — `pet-boxes.yml`.

```yaml
settings:
  quick-open: false          # skip the animation entirely
  bulk-open: true            # shift + right-click opens the whole stack (needs quick-open)
  block-open-storage-full: true
  cooldown-seconds: 0
  max-concurrent-openings: 3
  animation:
    duration-ticks: 50
    interval-ticks: 4
    open-sound: 'BLOCK_ENDER_CHEST_OPEN:1:1.2'
    reveal-sound: 'ENTITY_PLAYER_LEVELUP:1:2'

boxes:
  common:
    item: { material: 'texture-<base64>', name: '&a&lCommon Pet Box', lore: [...] }
    rolls: 1                 # how many pets one box gives
    pets:
      - 'dragon:1:100'       # petId : amount : weight
    message: '&b&lPETBOX &8» &7You found a {pet}&7!'
    broadcast:
      - '&b&lPETBOX &8» &f{player} &7opened a box and found a {pet}&7!'
    hologram:
      - '&f&lCommon Pet Box'
      - '&8* &7Opened by &f{player}'
```

## The opening animation

The animation is **fully packet-based and per-player**: a floating box in front of the opener cycles through the possible pets' heads under a hologram before revealing the reward. **Only the opener sees it** — nobody else receives a single packet. No real entities, no leftovers (the animation cleans itself up even on errors/logouts).

## Behavior notes

* `rolls` pets are rolled per box from the weighted `pets` list.
* `block-open-storage-full` refuses to open when the player lacks storage space for the rolls.
* `max-concurrent-openings` caps simultaneous animations per player.
* Give boxes with `/pets givebox <player> <box> [amount]` or to everyone online with `/pets giveallbox <box> [amount]`; the **Box Finder** upgrade finds them while grinding.