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

# Developer API

Add the PinnaPass jar as a `provided` dependency and `softdepend: [PinnaPass]` in your plugin.yml. Only the `es.edwardbelt.pinnapass.api` package is public API; every other class may change between versions (and is obfuscated in released jars), so never import or reflect into them.

## PinnaPassAPI

All methods are static, run on the main thread and work on **online** players. While PinnaPass is off they return 0 / false / empty and do nothing.

| Method                                                                                  |                                                                                                 |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `isAvailable()`, `isLoaded(player)`                                                     | PinnaPass runs / the player's pass is loaded                                                    |
| `getTier(player)`, `getCompletedTiers(player)`, `getMaxTier()`                          | tiers                                                                                           |
| `getXp(player)`, `getXpForTier(tier)`                                                   | XP                                                                                              |
| `giveXp(player, amount, applyMultipliers, source)`                                      | gives pass XP (fires `PassXpGainEvent`)                                                         |
| `setTier(player, tier)`                                                                 | puts the player on a tier with 0 XP                                                             |
| `hasPass(player, PassTrack)`, `hasPremium(player)`, `setPass(player, PassTrack, owned)` | premium passes                                                                                  |
| `getMultiplier(player)`, `addBoost(player, multiplier, seconds)`                        | multipliers                                                                                     |
| `recordActivity(player, type, subject, amount)`                                         | reports an activity: moves matching quests and gives the XP of `xp.activities` (any thread)     |
| `addQuestProgress(player, questId, amount)`                                             | moves one quest by id                                                                           |
| `getQuests(player)`                                                                     | `List<QuestView>` (id, category, type, name, description, progress, goal, completed, expiresAt) |
| `registerQuestType(plugin, type)`, `unregisterQuestTypes(plugin)`, `getQuestTypes()`    | custom quest types                                                                              |
| `getSeason()`, `getSeasonName()`, `getSeasonEnd()`                                      | the running season                                                                              |
| `openMenu(player, menuId)`                                                              | opens a menu of guis/ (null = the pass)                                                         |

`PassTrack`: `FREE`, `GOLD`, `DIAMOND` (`id()` = `free` / `gold` / `diamond`, `fromId(String)`).

## A custom quest type

```java
@Override
public void onEnable() {
    if (getServer().getPluginManager().isPluginEnabled("PinnaPass")) {
        PinnaPassAPI.registerQuestType(this, "myplugin-dungeon-clear");
    }
}

void onDungeonCleared(Player player, String dungeonId) {
    PinnaPassAPI.recordActivity(player, "myplugin-dungeon-clear", dungeonId, 1);
}
```

Server owners then write quests with `type: myplugin-dungeon-clear` (and `targets: [ 'crypt' ]` to filter by the subject), and may give XP for it in `xp.activities`. Without the API, the console command `pinnapass activity <player> <type> <amount> [subject]` does the same.

## Events

All fire on the main thread.

| Event                    | When                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `PassXpGainEvent`        | an online player is about to get pass XP (multipliers applied); `getSource()`, `setAmount()`, cancellable          |
| `PassTierUpEvent`        | a tier was completed; `getCompletedTier()`, `getNewTier()`                                                         |
| `PassQuestCompleteEvent` | a quest was completed and paid; `getQuest()`, `getXpReward()`                                                      |
| `PassRewardClaimEvent`   | a reward is about to be claimed; `getTier()`, `getTrack()` (null for Infinite levels), `isInfinite()`, cancellable |
| `PassPurchaseEvent`      | something was bought in the menu; `getProduct()` (gold, diamond, multiplier, infinite, reroll), `getCost()`        |
| `PassSeasonStartEvent`   | a new season started; `getSeason()`, `getName()`, `getEndsAt()`                                                    |