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

# Creating Companions

Every file in `companions/` is one companion; the file name is its id. Full reference:

```yaml
settings:
  name: '&#485BFF&lPrison &#6590FF&lCompanion'
  rarity: basic          # id from rarities.yml
  weight: 1              # roll weight inside its rarity
  withdrawable: true     # can it become a tradeable item?

buff:
  provider: pinnaprison  # pinnaprison / edtools / eddungeons / edprison
  currency: money        # currency id on that plugin
  amount: 0.05           # +0.05x (+5%) income on that currency while equipped
  currency-name: '&2Money'

display:
  entity: ARMOR_STAND    # any EntityType - the default look is a tiny armor stand
  small: true            # also applies the marker flag (armor stands are always invisible)
  scale: 0.4
  name-visible: true
  name-height: -1        # -1 = auto (just above the head); or absolute blocks above feet
  glowing: false
  equipment:             # armor-stand equipment (skulls via texture-<base64>)
    helmet: 'texture-<base64>'
    chestplate: LEATHER_CHESTPLATE
    armor-color: '#485BFF'   # dyes leather armor (#RRGGBB or R,G,B)
    held-item: none
  model: none            # EdLib (BDEngine) model id in models/<id>/
  model-engine: none     # ModelEngine blueprint (takes precedence)
  mythic-mob: none       # or resolve the MEG model from a MythicMobs mob

animations:
  idle: none             # model animations
  spawn: none
  despawn: none
  spawn-scale:           # vanilla entities grow in from tiny
    enabled: true
    duration-ticks: 20
    start-scale: 0.05

item:                    # the GUI/storage item (PinnaPrison item format)
  material: 'texture-<base64>'
  name: '{status-prefix}&#485BFF&lPrison &#6590FF&lCompanion'
  lore:
    - ' &#485BFF┃ &fRarity: {rarity} &8({status}&8)'
    - ' &#485BFF┃ &fMultiplier: &a{effective-buff}x {buff-currency}'
```

## Buffs

A companion grants exactly **one currency buff on one plugin**. Equipped companions stack: three companions with `+0.05x money` give `+0.15x`. Statuses multiply the amount (a Shiny 2x companion with `amount: 0.05` gives `+0.10x`).

The buff applies through each plugin's native hook — see [Plugin Integrations](/p/edcompanions/features/integrations.md).

## Item placeholders

`{companion}`, `{companion-id}`, `{rarity}`, `{rarity-color}`, `{rarity-color-2}`, `{status}`, `{status-prefix}`, `{buff-amount}`, `{effective-buff}` (status-multiplied), `{buff-currency}`, `{buff-provider}`, `{owner}`, `{slot}`, `{equipped}`.

## Visual backends

1. **Armor stand (default)** — tiny stand with a custom skull and a dyed leather chestplate.
2. **Any entity** — `entity: ALLAY`, `entity: BEE`, ... scaled with the 1.20.5+ scale attribute.
3. **EdLib models** — export from BDEngine into `plugins/EdCompanions/models/<id>/`.
4. **ModelEngine** — `model-engine: <blueprint>` (soft depend), owner-only dummy.

All backends are fully packet-based and owner-only.