Skip to main content

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.

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)
ParameterTypeDescription
playerPlayerThe online player to grant XP to
amountintBase XP amount before modifiers
sourceStringSource 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)
ParameterTypeDescription
playerIdUUIDPlayer'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)
ParameterTypeDescription
playerIdUUIDPlayer'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)
ParameterTypeDescription
playerIdUUIDPlayer'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)
ParameterTypeDescription
playerIdUUIDPlayer'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)
ParameterTypeDescription
playerPlayerThe online player
challengeTypeStringChallenge type (e.g., "break_block", "mob_kill", "travel")
targetStringSpecific target (e.g., "Stone") or "any"
amountintProgress 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)
ParameterTypeDescription
playerIdUUIDPlayer's UUID
multiplierdoubleXP multiplier (e.g., 2.0 for double XP)
durationMinutesintBooster duration in minutes

Example:

// Grant a 2x XP booster for 30 minutes
SeasonPassAPI.getInstance().grantBooster(playerId, 2.0, 30);
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)
ParameterTypeDescription
playerIdUUIDPlayer'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)
ParameterTypeDescription
playerPlayerThe 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": "*"
  }
}
Runtime Safety

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