> 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/creating-a-perk.md).

# Creating a Perk

A perk is a single YAML file in `plugins/EdPerks/perks/`. The **file name is the perk id** — `perks/fortune.yml` defines the perk `fortune`. To add a perk, drop in a new file and run `/edperks reload`. To remove one, delete its file and reload.

## A complete example

`perks/fortune.yml`:

```yaml
display-name: '&d&lFortune Perk'
tier: EPIC
material: 'player-head'
texture: 'eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6...'
chance: 0.25
lore:
  - '&8TOOL PERK'
  - '&r'
  - '&7This Tool Perk will provide your Tool'
  - '&7with an additional &fMoney/Shard/Souls/Essence&7 Boost.'
  - '&r'
  - '{levels}'
  - '&r'
  - '&dChance: &f{chance}%'
levels:
  '1':
    lore: '&d&lI &8— &fMoney &750% &fShards &750% &fSouls &775% &fEssence &775%'
    boosts: { money: 0.50, shards: 0.50, souls: 0.75, essence: 0.75 }
  '2':
    lore: '&d&lII &8— &fMoney &775% &fShards &775% &fSouls &7100% &fEssence &7100%'
    boosts: { money: 0.75, shards: 0.75, souls: 1.00, essence: 1.00 }
  # ... levels 3–5
```

***

## Top-level fields

**`display-name`**

* The perk's name, shown in menus, chat results and the `%edperks_current_perk%` placeholder. Supports `&` colour codes. Convention is to end it with `Perk`, e.g. `&d&lFortune Perk`.

**`tier`**

* **Default:** `COMMON`
* The rarity band: `COMMON`, `UNCOMMON`, `RARE`, `EPIC` or `LEGENDARY`. Controls the index grouping, the default colour, and whether the perk can be hit by **pity** (which targets the `pity.tier` band). See [Perk Tiers](/p/edperks/essential/perks.md#perk-tiers).

**`material`**

* **Default:** `player-head`
* The icon shown in the perk index. Accepts:
  * any Bukkit material name, e.g. `DIAMOND_SWORD`;
  * `player-<name>` for a named player's head;
  * `texture-<base64>` for a custom textured head (usually supplied via the `texture:` key instead — see below).

**`texture`**

* **Optional.** A base64 head texture string. When set, it overrides `material` and renders a custom-textured head. This is how all bundled perks get their icons.

**`chance`**

* **Default:** `1.0`
* The perk's **roll weight**, relative to every other perk in the pool. It is *not* a strict percentage — it is normalised against the sum of all perks' chances when a roll happens. Lower = rarer. Bundled values range from `12.5` (common) down to `0.1` (Universal).

**`level-weights`** *(optional)*

* A per-perk override for the global `roll.level-weights`. Same format — a list of relative weights, index `0` = level I. Omit it to use the global default from `config.yml`.

**`lore`**

* The template lore for the index icon. Two tokens are expanded automatically:
  * `{levels}` — replaced by **every** level's `lore` line (one line per level).
  * `{chance}` — replaced by the perk's `chance` (whole numbers print without a trailing `.0`).
  * `{tier}` — replaced by the tier name.

***

## The `levels` section

Each entry under `levels:` is a level, keyed by its **number** (`'1'`, `'2'`, …). Levels are sorted numerically. A perk can have any number of levels; five is standard.

```yaml
levels:
  '1':
    lore: '&a&lI &8— &fMoney &75%'
    boosts: { money: 0.05 }
```

**`lore`** (per level)

* A single line describing that level. It is substituted in wherever `{levels}` appears in the top-level `lore`. Convention: the Roman numeral, then the per-stat summary.

**`boosts`** (per level)

* A map of `stat-key: value`. The value is a decimal multiplier — `0.25` = +25%. A level may list several stats. A boost of `0` is ignored (no booster is created). See [Boost Stats](/p/edperks/essential/perks/boost-stats.md) for the available keys per host.

{% hint style="warning" %}
Boost keys are matched against the **active host's** supported economies. A key the current host doesn't recognise is silently ignored — handy for cross-host catalogues, but double-check spelling if a boost "isn't working".
{% endhint %}

***

## Rolling odds, in short

When a player rolls:

1. **Which perk?** — every perk is weighted by its `chance`. (On a pity roll the pool is restricted to the `pity.tier` band.)
2. **Which level?** — the chosen perk's level is weighted by its `level-weights` (or the global default).

So to make a perk more common, raise its `chance`; to make high levels easier, flatten the `level-weights`.

***

## After editing

Run **`/edperks reload`** (permission `edperks.admin`). New files are loaded, deleted files are dropped, and any of the 20 bundled defaults that went missing are re-extracted. Tools that already carry a perk you deleted will read as having **no perk** until re-rolled.


---

# 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/creating-a-perk.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.