# API Reference

**Version:** 2.0.7

Season Pass offers a small Java API, `com.hytale.seasonpass.api.SeasonPassAPI`, for other server plugins. It is set up in the plugin's `setup()` phase.

```java
import com.hytale.seasonpass.api.SeasonPassAPI;

SeasonPassAPI api = SeasonPassAPI.getInstance(); // null if Season Pass is not loaded (yet)
```

## Dependency

Declare Season Pass as an optional dependency so it loads first, and null-check the instance:

```json
{
  "Dependencies": { "kyuubisoft:core": "*" },
  "OptionalDependencies": { "kyuubisoft:seasonpass": "*" }
}
```

Compile against the Season Pass jar (`compileOnly`), for example `compileOnly(files("libs/KyuubiSoftSeasonPass-2.0.7.jar"))`. Do not ship it inside your own jar. If the class may be missing at runtime, keep all references to `SeasonPassAPI` in a separate class that you only touch after checking that the plugin is present.

:::note[Online players only]
Player data is only in memory while a player is online. For offline players every getter returns `0` / `false` and every action does nothing.
:::

:::caution[World thread]
Methods that grant XP, rewards or prestige can touch the player's inventory (item currency, rewards, the inventory check). Call them on the player's world thread, as the plugin itself does.
:::

---

## Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `grantXp(Player player, int amount, String source)` | void | Grants season XP like any other source |
| `isSeasonActive()` | boolean | A season is running and not paused |
| `getPlayerTier(UUID playerId)` | int | Current tier, `0` without data |
| `hasPremium(UUID playerId)` | boolean | Owns the premium pass |
| `getPlayerTotalXp(UUID playerId)` | int | Total season XP (since the last prestige) |
| `getPlayerTokens(UUID playerId)` | int | Internal season tokens |
| `incrementChallengeProgress(Player player, String challengeType, String target, int amount)` | void | Adds progress to matching active challenges |
| `grantBooster(UUID playerId, double multiplier, int durationMinutes)` | void | Starts a personal XP booster |
| `isDoubleXpEventActive()` | boolean | A server-wide XP event runs |
| `getGlobalXpMultiplier()` | double | Multiplier of the running event, `1.0` without one |
| `getPrestigeLevel(UUID playerId)` | int | Prestige level, `0` without data |
| `performPrestige(Player player)` | boolean | Tries a prestige for the player |

### grantXp

```java
SeasonPassAPI.getInstance().grantXp(player, 100, "minigame_win");
```

- `amount` is the base amount; personal booster, server event, premium and prestige multipliers and the daily caps apply, tokens are earned and tiers rise (with chat line, tier-up toast and HUD update).
- Nothing happens while no season runs or while it is paused, or for `amount <= 0`.
- `source` is only used in the debug log.

Quest and achievement XP need no API call: Season Pass listens to KyuubiSoft Quests (completed quests) and KyuubiSoft Achievements (unlocked achievements) itself and grants the season's `questCompleted` / `achievementUnlocked` values. Other quest or achievement plugins can call `grantXp`.

### incrementChallengeProgress

```java
SeasonPassAPI.getInstance().incrementChallengeProgress(player, "mob_kill", "Skeleton_Warrior", 1);
```

Adds `amount` to every active daily, weekly (and, with premium, premium) challenge of that type whose target matches (`any`, exact ID, or `*` wildcards, see [Challenges](./challenges#targets)). A challenge that reaches its count is completed and pays its XP and tokens.

- This method does **not** check whether the season is paused.
- Only types that the rotation rolls can be active (see [Challenges](./challenges#types)); a challenge with an own type will not be rolled, so it cannot be fed through this method.

### grantBooster

```java
SeasonPassAPI.getInstance().grantBooster(playerId, 2.0, 30);
```

Replaces a running booster, sends "XP Booster activated! 2.0x for 30 minutes." and runs on real time. A multiplier of 1.0 or less has no effect.

### getPlayerTokens

Returns the internal season tokens. With the season currency `item` or `economy` this is not the shop balance.

### performPrestige

Returns `true` when the prestige was done. It is refused (`false`) unless prestige is enabled, the player is at the last tier, the level limit is not reached, no reward is left to claim and the prestige rewards fit into the inventory. On success the player gets the prestige rewards and the chat message; the data is saved with the next auto-save. See [Seasons](./seasons#prestige).

---

## Currency `season_tokens`

Season Pass registers a currency with KyuubiSoft Core's shop system:

| Property | Value |
|----------|-------|
| ID | `season_tokens` |
| Display name | "Season Tokens" |
| Icon | `Ingredient_Bar_Gold` |
| Balance / spend / refund | the internal season tokens of the player |

Anything that prices through Core's `ShopService` can use it, including Core shops and the Season Pass's own `premiumCurrencyId`.

---

## Example

```java
import com.hytale.seasonpass.api.SeasonPassAPI;

public final class SeasonPassHook {

    private SeasonPassHook() {}

    public static void onMinigameWin(Player player) {
        SeasonPassAPI api = SeasonPassAPI.getInstance();
        if (api == null || !api.isSeasonActive()) return;
        api.grantXp(player, 250, "minigame_win");
        api.grantBooster(player.getPlayerRef().getUuid(), 1.5, 15);
    }

    public static boolean hasPremium(UUID playerId) {
        SeasonPassAPI api = SeasonPassAPI.getInstance();
        return api != null && api.hasPremium(playerId);
    }
}
```