Skip to main content

FAQ & Troubleshooting

Common questions and solutions for the Season Pass system.

General​

How do I start a season?​

Seasons do not start automatically. An admin must explicitly start a season using:

/spadmin start season_1

Or use the admin panel (/spadmin panel) and click Start Season on the Events or Season tab.

Can I run multiple seasons at once?​

No. Only one season can be active at a time. You must end the current season before starting a new one:

/spadmin end
/spadmin start season_2

What happens when a season ends?​

When a season ends (either manually via /spadmin end or automatically when the duration expires):

  1. All online players' season data is archived to their history
  2. Players can view past season summaries in the History tab
  3. The activeSeasonId in config.json is cleared
  4. No more XP, challenges, or shop interactions are possible until a new season starts

How do I create a new season?​

  1. Copy seasons/season_1.json to a new file (e.g., season_2.json)
  2. Change the "id" field to match the filename (e.g., "season_2")
  3. Customize tiers, challenges, shop items, and settings
  4. Run /spadmin reload to load the new definition
  5. Start it with /spadmin start season_2

Alternatively, use the admin panel's Season tab and click Create Season to generate a blank season definition in-game.

Player Issues​

Players are not earning XP​

Check the following:

  1. Is a season active? Run /spadmin info to verify.
  2. Is the season paused? The admin panel Events tab or /spadmin info shows paused state. Resume with /spadmin resume.
  3. Is Core TrackingService running? XP from gameplay requires the Core mod's TrackingService. Check the server log for "Registered SeasonPassTrackingListener with Core TrackingService".
  4. Are XP values set to 0? Check the season's xpSources configuration. Any source set to 0 is disabled.
  5. Has the daily XP cap been hit? If dailyXpCap is set, players stop earning XP after reaching the limit for the day.

Players are not receiving the Season Pass Book​

The Season Pass Book is only given when:

  • item.enabled is true in config.json
  • A season is currently active
  • The player does not already have the item in their inventory (duplicate protection)
  • item.giveOnFirstJoin or item.giveOnEveryJoin is enabled

There is a configurable delay (giveDelaySeconds, default: 3 seconds) before the item appears to allow the world to load first.

A player's data was lost​

Player data is saved in two ways:

  • File mode: configs/kyuubisoft_seasonpass/players/{uuid}.json with .bak backup files
  • MySQL mode: Via the Core mod's PlayerDataStorage abstraction

Check if a .bak backup file exists. Data is auto-saved at the configured autoSaveIntervalSeconds interval (default: 300 seconds / 5 minutes) and always saved on player disconnect.

Player progress did not reset for a new season​

When a new season starts, player progress is reset on their next login (lazy reset). If a player was online when the season changed, their data is synchronized automatically. If the issue persists, use:

/spadmin resetplayer <playername>

Premium Pass​

How do players buy the premium pass?​

Players can purchase the premium pass using:

/sp buy

This requires:

  • premiumEnabled is true in the season config
  • premiumCommandOnly is false
  • The player has sufficient currency (configured via premiumCost and premiumCurrencyId)

How do I give premium for free?​

Use the admin command:

/spadmin grantpremium <playername>

Or toggle premium via the admin panel's Players tab.

Can I disable premium entirely?​

Yes. Set premiumEnabled to false in the season definition. This completely hides the premium track, purchase button, and lock overlays. All tiers become free-track only.

What is premiumCommandOnly mode?​

When premiumCommandOnly is true, the /sp buy command is disabled. Premium can only be granted by an admin using /spadmin grantpremium. This is useful when premium is sold through an external store or website.

Do players keep premium rewards if premium is revoked?​

Yes. Revoking premium (/spadmin revokepremium) only prevents claiming future premium rewards. Already-claimed rewards are not reclaimed.

Challenges​

Challenges are not resetting​

Challenges use a lazy reset system -- they reset when the player next logs in or opens the Season Pass UI, not at a fixed server time. This is by design to ensure offline players get fresh challenges when they return.

If challenges are stuck, you can force a reset via the admin panel or wait for the player to reconnect.

Players see different challenges from each other​

This is intended behavior. Challenge rotation uses a per-player seed based on playerUuid.hashCode() + dayOfEpoch, so each player sees a different set of challenges. This prevents coordination where all players do the same thing.

A challenge type appears twice in the same day​

This should not happen. The rotation algorithm enforces type deduplication -- at most one challenge per type within each category (daily or weekly). If this occurs, check that your challenge pool has enough variety across different types.

Shop​

The shop shows the same items every day​

The shop rotation is deterministic per player per day. The same player will see the same items all day. Items change at midnight in the configured timezone. Different players may see different items.

If the shop pool is small (fewer items than dailyShopSlots), items may repeat across days.

How do I force a shop rotation?​

Shop rotation is date-based and per-player. There is no global force-rotation mechanism. To change what appears, modify the shopItems array in the season definition and reload with /spadmin reload.

XP & Progression​

How is XP calculated per tier?​

The XP curve follows an exponential formula:

XP for Tier N = baseXpPerTier * (tierXpScaling ^ (N - 1))

With defaults (baseXpPerTier: 1000, tierXpScaling: 1.08):

  • Tier 1: 1,000 XP
  • Tier 10: ~2,000 XP
  • Tier 20: ~4,316 XP
  • Tier 30: ~9,317 XP

How do XP boosters stack?​

XP multipliers stack multiplicatively:

Final XP = Base XP * Premium Boost * Prestige Boost * Personal Booster * Global Event

For example: 10 XP base with 1.5x premium + 1.05x prestige + 2.0x booster + 2.0x event = 10 * 1.5 * 1.05 * 2.0 * 2.0 = 63 XP.

What is the soft cap?​

The soft cap reduces XP earning after a threshold without stopping it entirely. With dailyXpSoftCap: 5000 and softCapMultiplier: 0.25:

  • First 5,000 XP earned at full rate
  • After 5,000 XP: each 100 XP earned only grants 25 XP
  • The hard cap (dailyXpCap) stops all earning when reached
  • Set both to 0 to disable caps entirely

How do login streaks work?​

  • Each consecutive daily login increments the streak counter
  • Missing a day resets the streak to 0 (it restarts at 1 on the next login)
  • Streak XP bonus: min(currentStreak, loginStreakMaxDays) * loginStreakPerDay
  • First season login grants a one-time bonus of firstLoginBonusXp XP and firstLoginBonusTokens tokens

Prestige​

How does prestige work?​

When a player reaches the maximum tier and prestigeEnabled is true:

  1. A Prestige button appears in the Tiers tab
  2. Clicking it resets: tier, XP, and claimed rewards
  3. The player gains +1 prestige level
  4. Each prestige level grants a permanent XP boost of prestigeXpBoostPercent%
  5. Prestige resets do not affect: premium status, season tokens, challenge progress, or settings

Is there a maximum prestige level?​

Yes, controlled by maxPrestigeLevel (default: 10). Once reached, the prestige button no longer appears.

Admin Panel​

The admin panel won't open​

Verify that you have the seasonpass.admin permission. The panel also requires the player to be online (it cannot be opened from console).

Changes in the admin panel are not saving​

  1. Make sure you click the Save button on each tab -- changes are not auto-saved.
  2. Check the status bar at the top of the panel for error messages.
  3. If running on a showcase server, write operations are blocked by ShowcaseCompat.

The season selector dropdown is empty​

This means no season definition files were found in configs/kyuubisoft_seasonpass/seasons/. Run /spadmin reload or restart the server to regenerate the default season_1.json.

Technical​

What are the mod dependencies?​

DependencyTypePurpose
kyuubisoft:coreRequiredTrackingService, RewardGrantHelper, ShopService, ModMenuRegistry, PlayerDataStorage
kyuubisoft:achievementsOptionalAchievement XP integration
kyuubisoft:questsOptionalQuest XP integration
Buuz135:MHUDOptionalHUD framework compatibility

Where is player data stored?​

  • File mode (default): configs/kyuubisoft_seasonpass/players/{uuid}.json
  • MySQL mode: In the database via Core's PlayerDataStorage abstraction

File mode creates .bak backup files alongside each player data file.

How do I back up season data?​

Back up the entire configs/kyuubisoft_seasonpass/ directory, which contains:

  • config.json -- Plugin configuration
  • seasons/ -- Season definitions
  • localization/ -- Language files
  • players/ -- Player data (file mode only)

What Java version is required?​

The plugin requires Java 25 or later (as configured in build.gradle.kts).

Can I hot-reload the config?​

Yes. Use /spadmin reload or the admin panel's Reload button. This reloads config.json, all season definitions in seasons/, and all localization files. No server restart is required.

Active Season

Reloading does not affect an active season's runtime state. It reloads the definition files, so changes to tiers, challenges, or shop items will be reflected for new interactions. Existing player data is not modified.