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

# Overview

A season pass (battle pass) for Paper 1.21+. Players earn **Pass XP** by playing and finishing **daily and weekly quests**, complete **tiers**, and claim a reward on the **free track** and, with a premium pass, on the **premium track** of every tier. Seasons reset the pass, boosters speed it up, and the **Infinite Pass** keeps paying after the last tier. Every text, number, sound and menu is in a config file.

PinnaPass runs on its own: no other plugin is needed. Vault, PlaceholderAPI, PinnaPrison, Jobs, mcMMO and the others listed below only add more.

## Features

|                             |                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tiers**                   | Any number of tiers, an XP formula or a cost per tier, a free and a premium reward per tier                                                                                                                                                                                                       |
| **Two premium passes**      | Gold and Diamond (renamable, one can be turned off), bought in the menu or given by a store / permission                                                                                                                                                                                          |
| **Quests**                  | Daily, weekly or rolling categories with their own slots and resets, weighted pools, filters, extra rewards, paid rerolls                                                                                                                                                                         |
| **50+ quest types**         | Mining, farming, fighting, fishing, crafting, smelting, enchanting, brewing, breeding, trading, travelling, playtime, advancements... plus Jobs, mcMMO, AuraSkills, MythicMobs, EliteMobs, Citizens, shops, votes, money, PlaceholderAPI values and PinnaPrison / EdPrison / EdTools / EdDungeons |
| **Pass XP from activities** | Choose how much XP each activity gives, with the same filters as quests                                                                                                                                                                                                                           |
| **Seasons**                 | Numbered seasons with an optional length; a new season resets every pass (offline players too)                                                                                                                                                                                                    |
| **Boosters**                | A multiplier bought level by level, permission boosters, personal timed boosts and server-wide boosts                                                                                                                                                                                             |
| **Infinite Pass**           | After the last tier: endless levels with rewards rolled per player                                                                                                                                                                                                                                |
| **Menus**                   | Clean vanilla chest menus in `guis/`, fully editable: items, conditions, actions, sounds, pages                                                                                                                                                                                                   |
| **While playing**           | Action bar with the XP just earned and a text progress bar, an optional boss bar, titles and sounds                                                                                                                                                                                               |
| **Rewards**                 | Items (enchantments, names...), commands, Vault money, PlayerPoints, XP levels, pass boosts, plugin currencies                                                                                                                                                                                    |
| **Safe data**               | Embedded H2 database or MySQL / MariaDB, async, claims saved before rewards are given, nothing lost on a crash or reload                                                                                                                                                                          |
| **Networks**                | One MySQL database for several servers: passes follow players, one shared season and global boost, `/pinnapass migrate` between H2 and MySQL                                                                                                                                                      |
| **Placeholders**            | `%pinnapass_...%` for scoreboards and tab, one quest at a time too                                                                                                                                                                                                                                |
| **Developer API**           | Static API, events, custom quest types                                                                                                                                                                                                                                                            |
| **Languages**               | Every text is in messages.yml / the menus; optional per-player languages through EdLang                                                                                                                                                                                                           |

## Requirements

* Paper (or a fork) 1.21 or newer, Java 21.
* Optional: **Vault** + an economy plugin (purchases in money, money rewards, money quests), **PlaceholderAPI** (placeholders, placeholder quests), **PlayerPoints**, and the quest sources of the [Quest Types](/p/pinnapass/quests/quest-types.md) page.

## Quick start

1. Put `PinnaPass.jar` in `plugins/` and restart. The server downloads the H2 database driver once.
2. Players open `/pass`. The default season has 30 tiers of vanilla rewards and 25 daily / weekly quests.
3. Pick the purchase currency in `config.yml` → `economy.currency` (`vault` by default). Selling passes on a web store instead? Run `pinnapass premium {player} gold true` from the store.
4. Change rewards in `tiers.yml`, quests in `quests.yml`, XP per activity in `config.yml` → `xp.activities`, then `/pinnapass reload`.

## Folder

```
plugins/PinnaPass/
  config.yml        tiers, passes, multiplier, boosters, XP per activity, quest categories, season, notifications
  messages.yml      every chat message, action bar, boss bar and title text
  tiers.yml         the reward of each tier on each track
  quests.yml        the quest pools
  infinite.yml      the Infinite Pass reward pool
  guis/             pass.yml, quests.yml, infinite.yml and any menu you add
  data/             pinnapass.mv.db (players, with storage.type h2), season.yml (season + global boost)
```