> 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/pinnaduels/getting-started/readme.md).

# Overview

Ranked 1v1 mining duels for PinnaPrison. Two players mine for 60 seconds in two identical mines facing each other, under a big live score panel. Whoever mines more blocks wins. Duels are a reward for playing the prison: a ranked duel costs a **Duel Token**, and tokens are only earned by mining.

## Features

* **Fair mining duels**: both players use their own PinnaPrison pickaxe (instant break for everyone) in mirrored mines with the same random layout, refilled the same way.
* **Live score panel** above the arena (3D heads, popping scores, leader crown, timer, tug-of-war bar), boss bar and action bar, all plain text and items: no resource pack needed.
* **Ranked queue** with ELO matchmaking whose range grows while you wait; players keep mining while queued.
* **Ghost opponents**: nobody online? Race the recorded run of a real player of your level.
* **ELO, 14 leagues** (Bronze to Master and Legend), placement duels, decay, win-trading protection.
* **Seasons** with rewards by best league reached (also for offline players) and a soft ELO reset.
* **Friendly duels** (`/duel <player>`), **spectating**, server-wide result broadcasts with a join button.
* **Ready-to-play arena** included, `/duel setup` wizard for your own, or any WorldEdit `.schem`.
* **Clean vanilla menus** (PinnaPrison GUIs): main menu, live duels, ranked top podium, leagues.
* **YAML or MySQL / MariaDB storage**: shared duel data across servers, `/duel admin migrate` to move it.
* Everything configurable, PlaceholderAPI placeholders, optional per-player languages, a developer API.

## Requirements

* Paper 1.21+, Java 21, **PinnaPrison 1.2.26+**.
* Optional: PlaceholderAPI, EdLang, a MySQL / MariaDB database. WorldEdit is not needed.

## Quick start

1. Drop `PinnaDuels.jar` into `plugins/` and restart.
2. The bundled arena, the menus and the duels world are created by themselves.
3. Players mine to earn Duel Tokens and open `/duel`.
4. Add your rewards (`rewards.win`, `rewards.season`) in `config.yml` and run `/duel admin reload`.
5. Optional: put the [placeholders](/p/pinnaduels/reference/placeholders.md) on your scoreboard.

See [Installation](/p/pinnaduels/getting-started/installation.md) for details.

## Folder

```
plugins/PinnaDuels/
  config.yml        tokens, duel rules, displays, queue, ranked, leagues, seasons, rewards, ghosts, sounds
  messages.yml      every text
  arenas/           arena files (duelsmina.yml ships with the plugin)
  schematics/       arena blocks (.pinna from /duel setup, .schem from WorldEdit)
  data/             player data, season, item stash
  ghosts/           duel recordings
plugins/PinnaPrison/guis/pinnaduels/   the menus
```