> 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/getting-started/readme.md).

# Overview

Fully packet-based companions for prison/gens/dungeons servers. Companions follow their owner around (only the owner ever sees them — zero server entities, one global async task for the whole server) and grant a configurable currency buff on the host plugin while equipped.

## Supported plugins

| Plugin           | Buff hook                                                               | Payments (eggs / upgrades)                      |
| ---------------- | ----------------------------------------------------------------------- | ----------------------------------------------- |
| **PinnaPrison**  | Live boost provider (shows in `/boosters`) with currency-event fallback | Any PinnaPrison currency (Beacons, Tokens, ...) |
| **EdTools**      | Currency-add event multiplier                                           | Any EdTools currency                            |
| **EdDungeons**   | Currency-add event multiplier                                           | Any EdDungeons currency                         |
| **EdPrison 2.0** | Currency multiplier event                                               | Any EdPrison currency                           |
| *(none)*         | —                                                                       | EdCompanions' own internal currencies           |

## Highlights

* **Companion eggs** — placeable eggs (PinnaPrison mine placeables or standalone server-side placements every player sees) with a buy GUI, weighted rarity rolls, luck and status upgrades.
* **Packet opening animation** — small egg displays orbit the placed egg, burst, and reveal the pulled companion. Per-player toggle; every timing/scale/sound is configurable.
* **Fusion** — combine identical companions for a chance to upgrade them to the next status (Shiny / Rainbow / Void by default — statuses are fully configurable and multiply the buff).
* **Unlimited companions & rarities** — every companion, rarity, status, egg, upgrade and GUI is a config file.
* **Display modes** — `/companions displaymode` (behind, front, circle, spiral, parrot, ...).
* **MySQL + H2 storage** via EdLib, async everywhere.
* **Visuals** — tiny armor stands with skull heads and dyed leather chestplates by default; any entity type, BDEngine models or ModelEngine blueprints.

## Quick start

1. Install **EdLib** and drop `EdCompanions.jar` in `plugins/`.
2. Start the server once, then edit `plugins/EdCompanions/` configs.
3. PinnaPrison servers: add a `companion-egg` placeable to a mine layout (see [Eggs & Placeables](/p/edcompanions/features/eggs.md)). Other servers: stand where you want the egg and run `/companions placeegg companion-egg`.
4. Players open eggs by right-clicking the egg, and manage companions with `/companions`.