Skip to content

Seasons

Version: 2.0.7

Every season is one JSON file in mods/kyuubisoft_seasonpass/seasons/. It holds the tiers, the XP rules, the challenge and shop pools, the premium pass, the currency and prestige. All fields can also be edited in the admin panel. The default file season_1.json (“Season 1: Explorer”) is a complete example.

To add a season, copy season_1.json, give it a new "id" (keep the file name equal to the ID), edit it and run /spadmin reload, or click New season in the admin panel.


ActionWhat happens
Start (/spadmin start <id>, admin panel)Refused while another season runs. Sets the season as active, saves config.json and sets up the currency of the new season. Every online player whose data still belongs to an earlier season gets the season-end payout of that season and starts at tier 0. Daily and weekly challenges are rolled if the player has not had a roll today / this week (see the note below). All online players get “Season ‘Season 1: Explorer’ started!”. Players who are offline are moved over when they join.
PauseNo XP from any source, no login rewards, no challenge rollover and no automatic end. The HUD is hidden. The book still opens: claiming, the shop and buying premium still work. enabled: false in config.json acts like a pause, but also closes the book, see Configuration.
ResumeEverything runs again; daily and weekly challenges that became due during the pause are rolled for online players.
End (/spadmin end, admin panel, or by date)For every online player: the season-end payout, then the season is moved to the player’s history and their data is reset (tier, XP, tokens, premium, prestige, booster, challenges). The active season is cleared.

End by date: every 60 seconds the plugin checks endDate. On the end date itself (from 00:00 in the timezone of config.json, by default the server clock) the season ends. Three days and one day before, all online players get “Season ends in N days”. A season without endDate runs until an admin ends it. durationDays and startDate are stored and shown in the admin panel but have no effect.

When a season ends, every reached and unclaimed free reward and, with the premium pass, every unclaimed premium reward is paid out automatically:

  • Items, lootbags and commands (and tokens of an item currency, which are items) go through the inventory check. What fits is handed out at once; what does not fit waits in the player data (pendingRewards) and is handed out as soon as there is room: right after the end, about 6 seconds after every join and every minute while the player is online. The player gets a chat note, for example “2 reward(s) from the last season were added to your inventory.” or “3 reward(s) from the last season are waiting for free inventory space - they arrive automatically as soon as there is room.”
  • Internal or economy tokens and XP boosters belong to the ending season. Players online at the end get them right away; internal tokens and the booster are then reset with the season.
  • Players offline at the end get the same payout on their first join after the next season has started (or when the next season starts while they are online), except internal/economy tokens and boosters, which they do not get later. Between two seasons their data is left as it is.

Each season is archived once in the player’s history, under its own name. History entries written by older versions are not changed. Remind players to claim their rewards before the end date anyway: boosters and internal or economy tokens only reach players who are online at the end.


FieldDefaultDescription
idnoneUnique season ID, also the file name (season_1 -> season_1.json). Required: files without id are skipped
namethe IDShown in the book, the HUD toast, the history and chat messages
description""Only shown in the admin panel
iconItemnoneOnly shown in the admin panel
themeColor"#ffd700"Only shown in the admin panel
startDatenoneYYYY-MM-DD, informational only
endDatenoneYYYY-MM-DD. Ends the season automatically and drives the “ends in N days” texts in the book and the HUD
durationDays30Informational only
teaserRewards[]List of texts; not used anywhere in 2.0.7

FieldDefaultDescription
tiers[]Standard tiers (default season: 30)
bonusTiers[]Bonus tiers after the standard ones (default season: 10, tiers 31 to 40). They work like normal tiers and are marked “Bonus” in the book
baseXpPerTier1000XP from tier 0 to tier 1
tierXpScaling1.08Factor per tier

The tier number is the position in the list: the first entry of tiers is tier 1, the first entry of bonusTiers comes right after the last standard tier. The "tier" field inside each entry is only informational (the admin panel rewrites it on save). Deleting a tier in the middle gives every later tier a number one lower; adding a standard tier gives every bonus tier a number one higher.

Players store their claims by tier number. When a tier is added or deleted in the admin panel, the season file records the change in tierShifts, and each player’s claims are moved along once: online players right away, everyone else on their next join (and before the season-end payout). The claim of a deleted tier is dropped with the tier. Edits by hand or in the web editor are not recorded, so claims stay on their old numbers; do not reorder tiers that way while a season runs.

Each tier entry:

FieldDescription
tierInformational number
iconItemOptional; only shown in the admin panel’s tier list
freeRewardsList of rewards for everyone
premiumRewardsList of rewards for premium players

Rewards are described on Rewards. A track with no rewards (or only "none") shows “No reward” and is never counted as claimable.

XP needed to go from tier N-1 to tier N:

round(baseXpPerTier * tierXpScaling ^ (N - 1))

With the defaults (1000, 1.08):

TierXP for this tierTotal XP from tier 0
11,0001,000
51,3605,866
101,99914,486
152,93727,152
204,31645,762
256,34173,106
309,317113,282
3110,063123,345
4020,115259,055

XP above a tier’s requirement carries over; one gain can raise several tiers at once. At the last tier XP keeps counting as total season XP.


xpSources sets the XP per action. 0 turns a source off.

FieldDefaultCounted when
blockBroken1a block is mined
blockPlaced1a block is placed
mobKill10an NPC is killed
pvpKill25a player is killed
playtimePerMinute5every minute online
zoneDiscovered50a zone is entered for the first time that day (the list of zones is cleared at the day boundary)
blockHarvested2a plant is harvested
flowerPicked3a flower is picked
questCompleted100KyuubiSoft Quests reports a completed quest (only with that mod installed)
achievementUnlocked50KyuubiSoft Achievements reports an unlocked achievement (only with that mod installed)
dailyLogin25first join of a day, 5 seconds after joining
loginStreakPerDay10first join of a day: min(streak, loginStreakMaxDays) * loginStreakPerDay
loginStreakMaxDays30cap for the streak bonus

Blocks, kills, flowers and zones are reported by KyuubiSoft Core’s tracking. When Core’s tracking is not running, Season Pass uses its own trackers for distance, harvesting, flowers and playtime only. Quest and achievement XP come from KyuubiSoft Quests and KyuubiSoft Achievements; both are optional, and without them these two values are simply never used. Like every other source they go through the multipliers and daily caps. Other plugins can grant XP through the API. The streak counts consecutive days with a join; a missed day starts it again at 1.

XP = base * personal booster * server event * premium boost (with premium)
* (1 + prestige level * prestigeXpBoostPercent / 100)

The result is rounded. Then the daily caps apply:

FieldDefault (default season)Description
dailyXpSoftCap0 (5000)Once a player has earned this much XP today, further gains are multiplied by softCapMultiplier. 0 = off
softCapMultiplier0.25Factor after the soft cap
dailyXpCap0 (0)Hard daily limit; gains are cut to the rest and stop at the limit. 0 = off

The caps apply to every XP gain, including challenge rewards, the first-login bonus, API grants and /spadmin grantxp. The book shows “Today X / Y XP” when a cap is set.

The daily XP counter (and the daily zone list) restarts at the day boundary in the timezone of config.json: on the first join of a new day, and within a minute for players who stay online over midnight.


FieldDefault (default season)Description
premiumEnabledtruefalse hides the premium row, premium challenges, the premium shop and the premium buttons; premium rewards cannot be claimed
premiumCommandOnlyfalsetrue: players cannot buy the pass; the premium window shows premiumHintText and /sp buy answers “The Premium Pass can only be granted by an admin.”
premiumHintTextnone (“Check our Discord for the Premium Pass”)Shown in the premium window whenever the pass cannot be bought there. Without it: “Ask the server team about the premium pass.”
premiumCost1000Price
premiumCurrencyId"gold" ("item:Ingredient_Bar_Gold")Currency of the price, see below. "gold" is only used when the key is missing; the default season and seasons created in the admin panel use "item:Ingredient_Bar_Gold"
premiumXpBoost1.5XP factor for premium players (1.5 = +50 %)

The price is paid through KyuubiSoft Core’s shop currencies, not the season’s token currency. Valid IDs:

premiumCurrencyIdPaid with
economythe economy plugin KyuubiSoft Core is connected to (only when Core’s shops and an economy are active)
item:<ItemId>items, e.g. item:Ingredient_Bar_Gold
season_tokensthe internal season tokens of this plugin
quest_tokensquest tokens of KyuubiSoft Quests
achievement_pointsachievement points of KyuubiSoft Achievements

Buying (in the book or with /sp buy) only unlocks the premium track. Premium rewards of tiers already reached become claimable and are picked up like any other reward. An admin can grant or revoke the pass at any time; already claimed premium rewards are kept when it is revoked.


FieldDefaultAdmin panel rangeDescription
dailyChallenges[]Daily pool (normal and premiumOnly challenges)
weeklyChallenges[]Weekly pool
dailyChallengeSlots31 - 5Daily challenges per player
weeklyChallengeSlots31 - 5Weekly challenges per player
premiumDailyChallengeSlots21 - 3Extra daily premium challenges
premiumWeeklyChallengeSlots11 - 3Extra weekly premium challenges
shopItems[]Shop pool (normal and premiumOnly offers)
dailyShopSlots41 - 8Daily offers per player
premiumDailyShopSlots21 - 8Premium offers per player

A slot value of 0 or less in the file falls back to the default. Details: Challenges, Token Shop.


FieldDefaultDescription
currencyMode"internal"internal, item or economy, see Configuration
currencyItemIdnoneItem for mode item (without it the plugin falls back to internal and logs a warning)
currencyName"Tokens"Display name
currencyIconItem"Ingredient_Bar_Gold"Icon item for item and economy
economyProvidernoneVaultUnlocked provider for mode economy
seasonTokenXpRatio100XP per token
tokenXpCarryOverfalseSee below
firstLoginBonusXp25XP on a player’s first join of the season (goes through multipliers and caps)
firstLoginBonusTokens5Internal season tokens on a player’s first join of the season

Tokens from XP: every XP gain (after multipliers and caps) is divided by seasonTokenXpRatio. With tokenXpCarryOver off (default), each gain is divided on its own, so small gains never give tokens: with a ratio of 100, a 10 XP kill or a 1 XP block gives nothing. With it on, the leftover XP is kept per player and every 100 XP from any source make a token. The leftover is reset with the season.


FieldDefault (default season)Description
prestigeEnabledfalse (true)Allows prestige
prestigeXpBoostPercent5.0XP bonus per prestige level in percent (0 or less counts as 5)
maxPrestigeLevel10 (5)Highest level; 0 = no limit
prestigeRewards[] (5 levels)Rewards per level, see below
"prestigeRewards": [
{ "prestigeLevel": 1, "rewards": [
{ "type": "tokens", "tokens": 100, "description": "100 Tokens", "iconItem": "Ingredient_Bar_Gold" }
] },
{ "prestigeLevel": 2, "rewards": [
{ "type": "lootbag", "lootbagId": "Default_Lootbag_Legendary", "description": "Grand Premium Lootbag" }
] }
]

Each entry names its level with prestigeLevel (the order in the list does not matter). A player who reaches level N gets every reward of the entries with prestigeLevel N.

Prestige rules:

  • Needs the last tier of the season, bonus tiers included (tier 40 in the default season), prestige enabled and the level limit not reached.
  • Refused while any reward can still be claimed (“Claim all open rewards before prestige”), and when the prestige rewards would not fit into the inventory.
  • Resets tier, current tier XP, total season XP and all claimed rewards, and ends a running personal booster.
  • Keeps the premium pass, the tokens and the challenge progress.
  • The prestige level and its XP bonus last until the season ends; a new season starts at prestige 0.

The prestige button only appears in the book; the API offers performPrestige. Admins can set the level with /spadmin setprestige (no rewards are granted that way).


Five item IDs of the default season before 2.0.0 do not exist in Hytale. When a season file loads, they are replaced in memory (the file itself is not changed) and the log says how many places were fixed:

Old IDReplaced by
Food_ApplePlant_Fruit_Apple
Tool_Axe_IronTool_Hatchet_Iron
Armor_Chestplate_IronArmor_Iron_Chest
Block_WoodOakWood_Oak_Trunk
Deco_FlowerBouquetPlant_Flower_Bushy_Purple

Other unknown item IDs are flagged in the admin panel (“Item missing”).


{
"id": "season_1",
"name": "Season 1: Explorer",
"description": "Explore the world, fight monsters, and earn exclusive rewards!",
"iconItem": "Deco_Map",
"themeColor": "#00bcd4",
"endDate": "2026-11-30",
"durationDays": 30,
"baseXpPerTier": 1000,
"tierXpScaling": 1.08,
"dailyXpCap": 0,
"dailyXpSoftCap": 5000,
"softCapMultiplier": 0.25,
"premiumEnabled": true,
"premiumCommandOnly": false,
"premiumHintText": "Check our Discord for the Premium Pass",
"premiumCost": 1000,
"premiumCurrencyId": "economy",
"premiumXpBoost": 1.5,
"currencyMode": "internal",
"currencyName": "Tokens",
"currencyIconItem": "Ingredient_Bar_Gold",
"seasonTokenXpRatio": 100,
"tokenXpCarryOver": false,
"firstLoginBonusXp": 25,
"firstLoginBonusTokens": 5,
"dailyChallengeSlots": 3,
"weeklyChallengeSlots": 3,
"premiumDailyChallengeSlots": 2,
"premiumWeeklyChallengeSlots": 1,
"dailyShopSlots": 4,
"premiumDailyShopSlots": 2,
"prestigeEnabled": true,
"prestigeXpBoostPercent": 5.0,
"maxPrestigeLevel": 5,
"xpSources": {
"blockBroken": 1, "blockPlaced": 1, "mobKill": 10, "pvpKill": 25,
"playtimePerMinute": 5, "zoneDiscovered": 50, "blockHarvested": 2, "flowerPicked": 3,
"questCompleted": 100, "achievementUnlocked": 50,
"dailyLogin": 25, "loginStreakPerDay": 10, "loginStreakMaxDays": 30
},
"tiers": [
{
"tier": 1,
"iconItem": "Ingredient_Bar_Gold",
"freeRewards": [
{ "type": "item", "itemId": "Ingredient_Bar_Gold", "amount": 50, "description": "50 Gold" }
],
"premiumRewards": [
{ "type": "tokens", "tokens": 10, "description": "10 Tokens" }
]
}
],
"bonusTiers": [],
"dailyChallenges": [],
"weeklyChallenges": [],
"shopItems": [],
"prestigeRewards": []
}

The real default file uses "premiumCurrencyId": "item:Ingredient_Bar_Gold" and contains 30 tiers, 10 bonus tiers, 16 daily and 12 weekly challenges, 16 shop offers and 5 prestige levels.