> 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/edperks/essential/perks.md).

# Perks

A **perk** is a bundle of boosts that lives on a tool. Each perk is defined by a single file in `plugins/EdPerks/perks/<id>.yml` — the file name (without `.yml`) is the perk's **id**. EdPerks is fully data-driven: adding a perk is just adding a file, and removing one is deleting its file (then `/edperks reload`).

A perk has four defining properties:

| Property   | What it controls                                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------------------------------- |
| **Tier**   | The rarity band — drives index grouping, the default colour and which perks pity targets.                        |
| **Chance** | How likely the perk is to be picked when a player rolls (weighted against every other perk).                     |
| **Levels** | Up to five tiers (I–V) of strength. A roll lands on a random level, weighted by `roll.level-weights`.            |
| **Boosts** | The actual gameplay bonuses each level grants, keyed by [boost stat](/p/edperks/essential/perks/boost-stats.md). |

***

### How a perk is applied

1. The player holds a **perkable tool** (an EdDungeons sword, an EdTools OmniTool, …) and rolls in the [Tool Perks menu](/p/edperks/essential/guis.md).
2. EdPerks picks a perk (weighted by `chance`) and a level (weighted by `level-weights`), then stamps it onto the tool as NBT.
3. The active **host plugin** turns the perk's boosts into permanent boosters for the player while that tool is held.
4. EdPerks **re-syncs** automatically on join, on swapping the held item, and (for EdTools) on every in-place tool swap — so the active boosts always match the perk on the tool currently in use.

Only **one perk** lives on a tool at a time; rolling again replaces it. For multi-mode tools (the EdTools OmniTool) **each mode keeps its own perk** — rolling only affects the mode currently active.

{% hint style="info" %}
A perk's boosts only do something if the active host actually understands that stat. A perk that boosts `souls` does nothing on EdTools (which has no souls), but the same perk file works perfectly on EdDungeons. This is what lets one perk catalogue serve multiple hosts. See [Boost Stats](/p/edperks/essential/perks/boost-stats.md).
{% endhint %}

***

### Perk Tiers

Tiers are fixed rarity bands, ordered from most common to rarest. The tier sets the default name colour and groups perks in the index; the actual colour shown is whatever the perk's `display-name` uses.

| Tier        | Default colour     | Typical roll chance (bundled)              |
| ----------- | ------------------ | ------------------------------------------ |
| `COMMON`    | `&a` green         | high (\~12.5%)                             |
| `UNCOMMON`  | `&b` aqua          | medium (\~5%)                              |
| `RARE`      | `&9`/`&c` blue/red | low (\~1–2.5%)                             |
| `EPIC`      | `&5` purple        | rare (\~0.25%) — the default **pity** band |
| `LEGENDARY` | `&6` gold          | ultra-rare (\~0.1%)                        |

The pity tier (default `EPIC`, the "Purple Perk") is set in [`config.yml`](/p/edperks/essential/main-configuration.md#pity-luck).

***

### Levels (I–V)

Each perk defines its levels under `levels:`. A perk usually has five (`'1'`–`'5'`), but any count works. When a perk is rolled, its level is chosen randomly using the global `roll.level-weights` (or the perk's own `level-weights` override), so a higher level is rarer than a lower one.

Each level supplies:

* a **`lore`** line shown in the perk index, and
* a **`boosts`** map of stat → multiplier applied at that level.

***

### Learn more

* [Boost Stats](/p/edperks/essential/perks/boost-stats.md) — every stat a perk can boost, per host.
* [Bundled Perks](/p/edperks/essential/perks/bundled-perks.md) — the full list of the 20 perks that ship with EdPerks.
* [Creating a Perk](/p/edperks/essential/perks/creating-a-perk.md) — the perk file format, field by field.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://edseries-plugins.gitbook.io/p/edperks/essential/perks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.