> 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/rolling-and-pity.md).

# Rolling & Pity Luck

Rolling is the heart of EdPerks. A player opens the [Tool Perks menu](/p/edperks/essential/guis.md) while holding a perkable tool, clicks **Roll**, watches a short animation, and the rolled perk is stamped onto their tool.

## The roll flow

1. **Validation.** The player must (a) hold a tool the active host recognises and (b) have at least **1 Perk Ticket**. If not, they get the matching message (`roll.no-tool` or `roll.no-tickets`).
2. **Consume + advance.** One ticket is removed, the player's **total rolls** counter goes up by one, and the **pity counter** advances (or triggers — see below).
3. **Decide the outcome.** The perk and level are chosen **up front**:
   * **Perk** — picked from the full catalogue, weighted by each perk's `chance`. On a pity roll the pool is restricted to the `pity.tier` band.
   * **Level** — picked from that perk's levels, weighted by `level-weights`.
4. **Animate.** The menu plays a purely cosmetic spinning animation (the outcome is already decided).
5. **Apply.** The perk is written to the tool as NBT, the host converts its boosts into permanent boosters, and the result message is sent.

Only one perk lives on a tool at a time — a new roll **replaces** the old perk. On EdTools OmniTools, the roll only affects the **currently active tool mode**; other modes keep their own perks.

***

## Pity Luck

Pity guarantees a high-tier perk after a long unlucky streak, so no one rolls forever without a good result.

* Every roll that **isn't** a pity payout increments the player's *rolls-since-pity* counter.
* Once that counter **reaches `pity.rolls`** (default `500`), the **next** roll is forced: the perk is guaranteed to come from the **`pity.tier`** band (default `EPIC`, the "Purple Perk"), and the counter resets to zero.
* If the pity tier somehow has no perks, the roll falls back to the normal weighted pool.

Players can watch their progress live in the menu via the **Pity Luck** item, which uses:

* `%edperks_total_rolls%` — lifetime rolls,
* `%edperks_rolls_until_pity%` — current pity counter,
* `%edperks_pity_max%` — the threshold (`pity.rolls`).

Both `pity.rolls` and `pity.tier` are set in [`config.yml`](/p/edperks/essential/main-configuration.md#pity-luck).

{% hint style="info" %}
The level of a pity perk is still rolled normally — pity guarantees the **tier**, not level V.
{% endhint %}

***

## Auto-resync

Perks live on the **item**, but the host's boosters are tracked **per player**, so EdPerks keeps them in sync automatically. It clears and re-applies the correct perk boosters:

* shortly after a player **joins**,
* whenever the player **changes their held item**,
* and (EdTools only) on every **in-place tool swap** — zone auto-swap, the swap command, selector GUIs, etc.

This means the active boosts always belong to the perk on the tool currently in hand, with no action needed from the player.


---

# 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/rolling-and-pity.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.