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.
Lifecycle
Section titled “Lifecycle”| Action | What 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. |
| Pause | No 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. |
| Resume | Everything 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.
Season-end payout
Section titled “Season-end payout”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
itemcurrency, 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.
Metadata and timing
Section titled “Metadata and timing”| Field | Default | Description |
|---|---|---|
id | none | Unique season ID, also the file name (season_1 -> season_1.json). Required: files without id are skipped |
name | the ID | Shown in the book, the HUD toast, the history and chat messages |
description | "" | Only shown in the admin panel |
iconItem | none | Only shown in the admin panel |
themeColor | "#ffd700" | Only shown in the admin panel |
startDate | none | YYYY-MM-DD, informational only |
endDate | none | YYYY-MM-DD. Ends the season automatically and drives the “ends in N days” texts in the book and the HUD |
durationDays | 30 | Informational only |
teaserRewards | [] | List of texts; not used anywhere in 2.0.7 |
| Field | Default | Description |
|---|---|---|
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 |
baseXpPerTier | 1000 | XP from tier 0 to tier 1 |
tierXpScaling | 1.08 | Factor 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:
| Field | Description |
|---|---|
tier | Informational number |
iconItem | Optional; only shown in the admin panel’s tier list |
freeRewards | List of rewards for everyone |
premiumRewards | List 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 curve
Section titled “XP curve”XP needed to go from tier N-1 to tier N:
round(baseXpPerTier * tierXpScaling ^ (N - 1))With the defaults (1000, 1.08):
| Tier | XP for this tier | Total XP from tier 0 |
|---|---|---|
| 1 | 1,000 | 1,000 |
| 5 | 1,360 | 5,866 |
| 10 | 1,999 | 14,486 |
| 15 | 2,937 | 27,152 |
| 20 | 4,316 | 45,762 |
| 25 | 6,341 | 73,106 |
| 30 | 9,317 | 113,282 |
| 31 | 10,063 | 123,345 |
| 40 | 20,115 | 259,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.
XP sources
Section titled “XP sources”xpSources sets the XP per action. 0 turns a source off.
| Field | Default | Counted when |
|---|---|---|
blockBroken | 1 | a block is mined |
blockPlaced | 1 | a block is placed |
mobKill | 10 | an NPC is killed |
pvpKill | 25 | a player is killed |
playtimePerMinute | 5 | every minute online |
zoneDiscovered | 50 | a zone is entered for the first time that day (the list of zones is cleared at the day boundary) |
blockHarvested | 2 | a plant is harvested |
flowerPicked | 3 | a flower is picked |
questCompleted | 100 | KyuubiSoft Quests reports a completed quest (only with that mod installed) |
achievementUnlocked | 50 | KyuubiSoft Achievements reports an unlocked achievement (only with that mod installed) |
dailyLogin | 25 | first join of a day, 5 seconds after joining |
loginStreakPerDay | 10 | first join of a day: min(streak, loginStreakMaxDays) * loginStreakPerDay |
loginStreakMaxDays | 30 | cap 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.
Multipliers and caps
Section titled “Multipliers and caps”XP = base * personal booster * server event * premium boost (with premium) * (1 + prestige level * prestigeXpBoostPercent / 100)The result is rounded. Then the daily caps apply:
| Field | Default (default season) | Description |
|---|---|---|
dailyXpSoftCap | 0 (5000) | Once a player has earned this much XP today, further gains are multiplied by softCapMultiplier. 0 = off |
softCapMultiplier | 0.25 | Factor after the soft cap |
dailyXpCap | 0 (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.
Premium pass
Section titled “Premium pass”| Field | Default (default season) | Description |
|---|---|---|
premiumEnabled | true | false hides the premium row, premium challenges, the premium shop and the premium buttons; premium rewards cannot be claimed |
premiumCommandOnly | false | true: players cannot buy the pass; the premium window shows premiumHintText and /sp buy answers “The Premium Pass can only be granted by an admin.” |
premiumHintText | none (“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.” |
premiumCost | 1000 | Price |
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" |
premiumXpBoost | 1.5 | XP 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:
premiumCurrencyId | Paid with |
|---|---|
economy | the 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_tokens | the internal season tokens of this plugin |
quest_tokens | quest tokens of KyuubiSoft Quests |
achievement_points | achievement 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.
Challenges and shop
Section titled “Challenges and shop”| Field | Default | Admin panel range | Description |
|---|---|---|---|
dailyChallenges | [] | Daily pool (normal and premiumOnly challenges) | |
weeklyChallenges | [] | Weekly pool | |
dailyChallengeSlots | 3 | 1 - 5 | Daily challenges per player |
weeklyChallengeSlots | 3 | 1 - 5 | Weekly challenges per player |
premiumDailyChallengeSlots | 2 | 1 - 3 | Extra daily premium challenges |
premiumWeeklyChallengeSlots | 1 | 1 - 3 | Extra weekly premium challenges |
shopItems | [] | Shop pool (normal and premiumOnly offers) | |
dailyShopSlots | 4 | 1 - 8 | Daily offers per player |
premiumDailyShopSlots | 2 | 1 - 8 | Premium offers per player |
A slot value of 0 or less in the file falls back to the default. Details: Challenges, Token Shop.
Currency and tokens
Section titled “Currency and tokens”| Field | Default | Description |
|---|---|---|
currencyMode | "internal" | internal, item or economy, see Configuration |
currencyItemId | none | Item 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 |
economyProvider | none | VaultUnlocked provider for mode economy |
seasonTokenXpRatio | 100 | XP per token |
tokenXpCarryOver | false | See below |
firstLoginBonusXp | 25 | XP on a player’s first join of the season (goes through multipliers and caps) |
firstLoginBonusTokens | 5 | Internal 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.
Prestige
Section titled “Prestige”| Field | Default (default season) | Description |
|---|---|---|
prestigeEnabled | false (true) | Allows prestige |
prestigeXpBoostPercent | 5.0 | XP bonus per prestige level in percent (0 or less counts as 5) |
maxPrestigeLevel | 10 (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).
Old item IDs
Section titled “Old item IDs”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 ID | Replaced by |
|---|---|
Food_Apple | Plant_Fruit_Apple |
Tool_Axe_Iron | Tool_Hatchet_Iron |
Armor_Chestplate_Iron | Armor_Iron_Chest |
Block_WoodOak | Wood_Oak_Trunk |
Deco_FlowerBouquet | Plant_Flower_Bushy_Purple |
Other unknown item IDs are flagged in the admin panel (“Item missing”).
Example (shortened)
Section titled “Example (shortened)”{ "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.