API Reference

API Reference

The Season Pass provides a public Java API (SeasonPassAPI) that allows other Hytale server mods to interact with the Season Pass system. The API follows a singleton pattern and is initialized automatically when the plugin starts.

Getting the API Instance

import com.hytale.seasonpass.api.SeasonPassAPI;

SeasonPassAPI api = SeasonPassAPI.getInstance();

The instance is available after the Season Pass plugin has completed its setup() phase. It returns null if the Season Pass mod is not loaded.

:::warning Soft Dependency If your mod uses the Season Pass API as an optional integration, declare it as an optional dependency in your manifest.json and null-check the API instance before use:

{
  "OptionalDependencies": {
    "kyuubisoft:seasonpass": "*"
  }
}

:::

---

Methods

grantXp

Grants Season XP to a player. Accounts for premium boost, prestige boost, active boosters, daily caps, and all other XP modifiers.

void grantXp(Player player, int amount, String source)

Parameter	Type	Description
player	Player	The online player to grant XP to
amount	int	Base XP amount before modifiers
source	String	Source identifier for logging (e.g., "quest_completed", "minigame_win")

Example:

// Grant 100 XP when a quest is completed
SeasonPassAPI.getInstance().grantXp(player, 100, "quest_completed");

---

isSeasonActive

Returns whether a season is currently active and not paused.

boolean isSeasonActive()

Example:

if (SeasonPassAPI.getInstance().isSeasonActive()) {
    // Season-specific logic
}

---

getPlayerTier

Returns the current tier of a player.

int getPlayerTier(UUID playerId)

Parameter	Type	Description
playerId	UUID	Player’s UUID

Returns: Current tier number, or 0 if the player has no data.

---

hasPremium

Returns whether a player has the premium pass.

boolean hasPremium(UUID playerId)

Parameter	Type	Description
playerId	UUID	Player’s UUID

Returns: true if the player has the premium pass, false otherwise.

---

getPlayerTotalXp

Returns the total XP earned by a player in the current season.

int getPlayerTotalXp(UUID playerId)

Parameter	Type	Description
playerId	UUID	Player’s UUID

Returns: Total season XP, or 0 if the player has no data.

---

getPlayerTokens

Returns the season token balance of a player.

int getPlayerTokens(UUID playerId)

Parameter	Type	Description
playerId	UUID	Player’s UUID

Returns: Token balance, or 0 if the player has no data.

---

incrementChallengeProgress

Increments challenge progress for a player. If a matching active challenge reaches its completion count, the challenge is automatically completed and rewards are granted.

void incrementChallengeProgress(Player player, String challengeType, String target, int amount)

Parameter	Type	Description
player	Player	The online player
challengeType	String	Challenge type (e.g., "break_block", "mob_kill", "travel")
target	String	Specific target (e.g., "Stone") or "any"
amount	int	Progress increment

Example:

// Increment mob kill progress by 1
SeasonPassAPI.getInstance().incrementChallengeProgress(player, "mob_kill", "Skeleton", 1);

---

grantBooster

Activates a personal XP booster for a player.

void grantBooster(UUID playerId, double multiplier, int durationMinutes)

Parameter	Type	Description
playerId	UUID	Player’s UUID
multiplier	double	XP multiplier (e.g., 2.0 for double XP)
durationMinutes	int	Booster duration in minutes

Example:

// Grant a 2x XP booster for 30 minutes
SeasonPassAPI.getInstance().grantBooster(playerId, 2.0, 30);

:::note Booster Replacement If the player already has an active booster, it is replaced with the new one. Boosters do not stack with each other, but they do stack with the premium XP boost and global Double XP events. :::

---

isDoubleXpEventActive

Checks whether a global Double XP event is currently active.

boolean isDoubleXpEventActive()

Returns: true if a server-wide XP event is active.

---

getGlobalXpMultiplier

Returns the current global XP multiplier. Returns 1.0 when no event is active.

double getGlobalXpMultiplier()

---

getPrestigeLevel

Returns the prestige level of a player.

int getPrestigeLevel(UUID playerId)

Parameter	Type	Description
playerId	UUID	Player’s UUID

Returns: Prestige level, or 0 if the player has no data or hasn’t prestiged.

---

performPrestige

Performs a prestige reset for a player. The player must have reached the maximum tier and prestige must be enabled in the active season.

boolean performPrestige(Player player)

Parameter	Type	Description
player	Player	The online player

Returns: true if prestige was successful, false if conditions were not met.

---

Integration Examples

Quest Completion XP

import com.hytale.seasonpass.api.SeasonPassAPI;

public void onQuestComplete(Player player, String questId) {
    SeasonPassAPI api = SeasonPassAPI.getInstance();
    if (api != null && api.isSeasonActive()) {
        api.grantXp(player, 100, "quest_" + questId);
    }
}

Minigame Reward

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

Conditional Content Based on Tier

public boolean canAccessArea(UUID playerId) {
    SeasonPassAPI api = SeasonPassAPI.getInstance();
    if (api == null) return true; // Allow if Season Pass not loaded
    return api.getPlayerTier(playerId) >= 10;
}

Premium-Gated Feature

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

---

Dependencies

To compile against the Season Pass API, add it as a compileOnly dependency in your build.gradle.kts:

dependencies {
    compileOnly(project(":mods:seasonpass"))
}

And declare the dependency in your manifest.json:

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

:::tip Runtime Safety Always null-check SeasonPassAPI.getInstance() before use. The Season Pass mod may not be installed on all servers that run your mod. :::