> 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/edcompanions/features/eggs.md).

# Eggs & Placeables

Every file in `eggs/` is one egg. An egg defines its price, which companions it rolls, how the **placed egg** looks and how the [opening animation](/p/edcompanions/features/animation.md) plays.

```yaml
display-name: '&#793BDFCompanion Egg'

price:
  provider: pinnaprison   # pinnaprison / edtools / eddungeons / edprison / edcompanions
  currency: beacons
  amount: 250
  bulk: { 1: 250, 3: 750, 10: 2500 }   # optional per-amount totals

companions: []            # companion ids; empty = all loaded companions
gui: eggs                 # GUI opened on right-click (guis/eggs.yml)

placeable:
  display: 'block:DRAGON_EGG'   # block:<mat> / item:<mat> / texture-<base64> / model:<id>
  scale: 1.5
  clickbox-width: 1.6
  clickbox-height: 2.0
  open-click: both              # which click opens the buy GUI: right / left / both
  hologram-height: 2.6
  hologram:
    - '&#793BDF&lPrison &#996AFF&lCompanion Egg'
    - '&fView all the possible companions'
    - '&fthat you can obtain from this egg.'
    - ''
    - '&7- Price: &d250 &5Beacons'
```

## PinnaPrison servers — mine placeable

EdCompanions registers the `companion-egg` placeable type on PinnaPrison. Add it to any mine layout (`plugins/PinnaPrison/privatemines/mines/<type>.yml`):

```yaml
placeables:
  'egg':
    type: companion-egg
    egg: companion-egg          # eggs/<id>.yml
    position: '12.5,90,-40.5'
```

It renders per-watcher exactly like PinnaPrison's own placeables (hologram + display + clickbox, all packet entities) and follows mine visits automatically.

## Any other server — placed eggs

Stand where the egg should go and run:

```
/companions placeegg companion-egg
/companions removeegg
```

Placed eggs persist in `placed-eggs.yml` and are **server-side**: every online player sees them (they're still pure packet entities — no real entities exist).

## Buying

Right-clicking an egg opens its buy GUI (`guis/eggs.yml` by default): the animations toggle, the roll pool preview and the 1x / 3x / 10x open buttons. Amounts and prices per button are config (`custom-item: {type: egg-open, amount: N}`).

Clicking a preview companion toggles it on the player's **filtered list** — filtered pulls are auto-deleted when opening eggs (great against storage spam).

{% hint style="warning" %}
A purchase is blocked up front when the buyer's storage can't fit every rolled companion.
{% endhint %}