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

# Main Configuration

`plugins/EdPerks/config.yml` controls storage, the ticket economy, the roll engine, the pity system, placeholder fallbacks and the host integrations. After editing it, run `/edperks reload` to apply the changes without a restart.

The default file:

```yaml
logging:
  debug: false

data:
  method: h2
  save-interval: 60

tickets:
  starting: 0

roll:
  level-weights: [50, 25, 15, 7, 3]

pity:
  rolls: 500
  tier: EPIC

placeholders:
  no-perk: '&7None'

hooks:
  eddungeons:
    return-gui: sword
  edtools:
    return-gui: ''
```

***

### Logging

**`logging.debug`**

* **Default:** `false`
* **Description:** Sends extra diagnostic messages to console. Turn it on only while troubleshooting.

***

### Data Settings

Player data (ticket balance, total rolls and the pity counter) is stored here. Perks themselves live on the tool item as NBT, not in the database.

**`data.method`**

* **Default:** `h2`
* **Description:** The storage backend, provided by EdLib. `h2` is an embedded file database that needs no setup.

**`data.save-interval`**

* **Default:** `60`
* **Description:** How often (in seconds) player data is flushed to storage. Data is also loaded asynchronously before a player joins and saved when they quit, plus a synchronous flush on server shutdown.

***

### Tickets

**`tickets.starting`**

* **Default:** `0`
* **Description:** How many **Perk Tickets** a brand-new player profile starts with. A ticket is consumed by every roll. See [Perk Tickets](/p/edperks/essential/tickets.md).

***

### Roll Behaviour

**`roll.level-weights`**

* **Default:** `[50, 25, 15, 7, 3]`
* **Description:** The **relative weights** that decide which level (I–V) a freshly rolled perk lands on. Index `0` is level I, index `1` is level II, and so on. With the default values a roll lands on level I about 50% of the time and level V about 3% of the time.
* **Note:** Individual perks can override this with their own `level-weights:` key (see [Creating a Perk](/p/edperks/essential/perks/creating-a-perk.md)). If a perk has fewer levels than there are weights, the extra weights are ignored; if it has more, missing weights default to `1`.

{% hint style="info" %}
Weights are **relative**, not percentages — they don't have to add up to 100. `[50, 25, 15, 7, 3]` and `[100, 50, 30, 14, 6]` behave identically.
{% endhint %}

***

### Pity Luck

Pity guarantees a high-tier perk after a streak of rolls, so players are never unlucky forever.

**`pity.rolls`**

* **Default:** `500`
* **Description:** After this many rolls **without** a pity payout, the player's **next** roll is a guaranteed perk from the pity tier. The counter is shown to players in the menu and via `%edperks_rolls_until_pity%`.
* **Minimum:** `1`.

**`pity.tier`**

* **Default:** `EPIC`
* **Description:** The rarity band a pity roll is guaranteed to pull from — the "Purple Perk". Accepts any [perk tier](/p/edperks/essential/perks.md#perk-tiers): `COMMON`, `UNCOMMON`, `RARE`, `EPIC`, `LEGENDARY`. If no perk of that tier exists, the roll falls back to the full pool.

See [Rolling & Pity Luck](/p/edperks/essential/rolling-and-pity.md) for the full mechanic.

***

### Placeholders

**`placeholders.no-perk`**

* **Default:** `&7None`
* **Description:** The text returned by `%edperks_current_perk%` when the held tool carries no perk.

***

### Hooks

Per-host integration options. EdPerks auto-detects which host plugins are installed; these keys only fine-tune behaviour.

#### `hooks.eddungeons.return-gui`

* **Default:** `sword`
* **Description:** The EdDungeons menu the perks menu's **Back** button (`[return]` action / `on-close-action`) returns the player to — by default its sword / enchants menu.

#### `hooks.edtools.return-gui`

* **Default:** `''` (empty)
* **Description:** The EdTools menu the **Back** button returns to. **Leave empty** to open the held tool's own menu — i.e. the `gui:` declared in that tool's `tools/<tool>/config.yml` (e.g. `crop`, `pickaxe`).

See [Host Integrations](/p/edperks/extra/host-integrations.md) for how each host applies perk boosts.


---

# 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/main-configuration.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.