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

# Introduction

Welcome to the official documentation for **EdPerks**. This guide covers every feature, configuration file, command and placeholder available in the plugin.

EdPerks adds **rollable Tool Perks** to your server, inspired by the perk systems seen on networks like EnchantedMC and FadeCloud. Players spend **Perk Tickets** to roll a random perk onto the tool they are holding. Each perk grants a stack of permanent **boosts** (money, damage, enchant chance, tool experience, and more) and rolls at a random **level (I–V)**. Rarer perks are harder to land — and a **pity-luck** system guarantees a high-tier perk after enough rolls so players are never unlucky forever.

EdPerks is **host-agnostic**. It owns the perk catalogue, the roll engine, the menus and the ticket economy, but it does not know what a "tool" is on its own. Instead it plugs into a **host plugin** through a small provider interface. Two hosts ship out of the box:

* **EdDungeons** — the perkable tool is the player's held dungeon **sword**.
* **EdTools** — the perkable tool is the player's held **OmniTool** (each tool mode keeps its own perk).

{% hint style="warning" %}
EdPerks needs at least one host plugin (**EdDungeons** or **EdTools**) installed to do anything useful — without a host, there is no "tool" for perks to attach to.
{% endhint %}

## 🚀 Installation

1. Download the latest **EdPerks** `.jar`.
2. Place `EdPerks.jar` into your server's `plugins/` folder.
3. Install a supported **host plugin**: [EdDungeons](/p/edperks/introduction.md) and/or [EdTools](/p/edperks/introduction.md).
4. (Recommended) Install [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) so the `%edperks_*%` placeholders work in menus, scoreboards and other plugins.
5. (Optional) Install [Vault](https://www.spigotmc.org/resources/vault.34315/).
6. Restart your server. EdPerks generates its default configuration in `plugins/EdPerks/`.

### Requirements

| Requirement         | Notes                                                     |
| ------------------- | --------------------------------------------------------- |
| **Server software** | Paper / Spigot **1.20+**. **Folia is supported.**         |
| **Host plugin**     | **EdDungeons** and/or **EdTools** (at least one).         |
| **PlaceholderAPI**  | Optional, but required for any `%edperks_*%` placeholder. |
| **Vault**           | Optional soft-dependency.                                 |

EdPerks soft-depends on all of the above, so it loads cleanly even if some are missing — the matching features simply stay dormant until the dependency is present.

## 📁 File overview

After the first start, `plugins/EdPerks/` contains:

```
plugins/EdPerks/
├── config.yml          # core settings: storage, tickets, rolls, pity, hooks
├── messages.yml        # every chat message EdPerks sends
├── guis/
│   ├── tool-perks.yml  # the main /perks menu (roll + buy tickets)
│   └── perk-index.yml  # the perk catalogue menu
└── perks/
    ├── attack.yml      # one file per perk — fully data-driven
    ├── money.yml
    ├── ...
    └── universal.yml
```

Read on:

* [Main Configuration](/p/edperks/essential/main-configuration.md) — `config.yml` explained key-by-key.
* [Perks](/p/edperks/essential/perks.md) — how perks, tiers and boosts work, and how to make your own.
* [Rolling & Pity Luck](/p/edperks/essential/rolling-and-pity.md) — the roll engine and the pity system.
* [Commands](/p/edperks/essential/commands.md) & [Placeholders](/p/edperks/essential/placeholders.md) — the full references.


---

# 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/introduction.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.