Skip to content

Configuration

Version: 2.0.7

Season Pass has one server-wide file, mods/kyuubisoft_seasonpass/config.json, and one file per season in seasons/. Almost everything players notice (tiers, XP, challenges, shop, premium, currency, prestige) lives in the season file, see Seasons. Both can be edited in the admin panel without touching the files.

The file in the jar only contains the first nine keys. The item block is added with its defaults the first time the plugin saves the file (starting, ending, pausing or resuming a season, or saving the General section of the admin panel).

{
"configVersion": 1,
"language": "en-US",
"debug": false,
"enabled": true,
"timezone": "system",
"autoSaveIntervalSeconds": 300,
"trackerHudEnabled": true,
"activeSeasonId": null,
"seasonPaused": false,
"item": {
"enabled": true,
"itemId": "SeasonPass",
"giveOnFirstJoin": true,
"giveOnEveryJoin": false,
"hotbarSlot": 8,
"giveDelaySeconds": 3
}
}
FieldDefaultWhat it does
configVersion1Format of the file, written by the plugin. Do not change it. A file without it was written before 2.0.0 and is updated once, see Update from older versions.
language"en-US"Server language. Used for messages that are not tied to a player action (XP and tier-up chat lines, event broadcasts, season end warnings). Windows and command replies follow each player’s own language, see Localization.
debugfalsetrue writes detailed Season Pass logging. KyuubiSoft Core’s debug mode turns it on as well.
enabledtruefalse switches the Season Pass off like a pause: no XP, no challenge progress or rotation, no automatic season end, no progress card and no Season Pass item on join. The book, /sp info and /sp buy answer “The Season Pass is currently disabled.” /spadmin info and the admin panel show the season as paused. Season-end rewards that wait for inventory space are not handed out while it is off.
timezone"system"Day and week boundary of the daily XP counter, the challenge and shop rotation, the login streak and the season end date, and the countdowns in the book. "system" (also when the key is missing or empty) is the server clock. Otherwise a zone ID such as "Europe/Berlin" or "UTC"; an unknown ID logs a warning and uses the server clock.
autoSaveIntervalSeconds300How often changed player data is saved (only players whose data changed). Read at server start; a change needs a restart. Player data is also saved on disconnect, on shutdown and after every claim or purchase.
trackerHudEnabledtruefalse hides the progress card for every player; the toasts stay. With true each player can still switch the card off in the settings window.
activeSeasonIdnullID of the running season. Set by /spadmin start, cleared by /spadmin end or when the season ends by date. Do not edit it while the server runs.
seasonPausedfalsetrue while the season is paused (/spadmin pause / resume).

All keys except autoSaveIntervalSeconds take effect on a reload (see Reloading).

A config.json written before 2.0.0 has no configVersion and carries "timezone": "UTC" from the old template. That value was never applied; every reset ran on the server clock. On the first start of 2.0.0 the plugin changes exactly this value to "system", so resets stay at the same time, adds "configVersion": 1 and writes the file back, with one info line in the log. Any other timezone value is kept. Set a zone ID afterwards if you want one.

A config.json that cannot be read is not rewritten at start or reload; the plugin logs an error and runs with the defaults. Fix the file and reload before you start, end, pause or resume a season or save the General section, because these save config.json with the values in memory.

The item block controls the Season Pass item.

FieldDefaultWhat it does
item.enabledtrueHand out the Season Pass item when players join
item.itemId"SeasonPass"Item that is handed out. The bundled SeasonPass item is a grimoire (quality Rare, max stack 1) whose right-click opens the book
item.giveOnFirstJointrueSee below
item.giveOnEveryJoinfalseSee below
item.hotbarSlot8Preferred hotbar slot, 0 to 8 (8 = last slot). If that slot is taken the item goes to the first free slot; with a full inventory it is not given
item.giveDelaySeconds3Seconds after joining before the item is given (0 counts as 3)

The item is checked on every join while a season runs and is not paused: if the player carries no item with itemId in the inventory, one is given. giveOnFirstJoin and giveOnEveryJoin behave the same in 2.0.7; as long as one of them is true, a player who lost or dropped the book gets a new one on the next join.


mods/kyuubisoft_seasonpass/
config.json
seasons/<id>.json one file per season, any number
localization/<lang>.json 9 bundled languages (+ backups of older versions)
players/<uuid>.json player data, with <uuid>.json.bak as the previous save
xp_event_state.json the running server-wide XP event (deleted when it ends)
  • Season files are loaded from seasons/ in alphabetical order. The season ID is the "id" inside the file; the admin panel always saves a season to seasons/<id>.json. If no season could be loaded, the default season_1.json is written (unless a file with that name exists) and loaded. A file that fails to parse is skipped with a warning in the log.
  • Player data holds tier, XP, tokens, claimed rewards, challenge state, shop purchases of the day, prestige, the personal booster, the season history, the player’s HUD and chat settings, and the season-end rewards that still wait for inventory space (pendingRewards, see Seasons).
  • MySQL: when MySQL is set up in KyuubiSoft Core, player data is stored in the table seasonpass_players. A player without a MySQL row is migrated once from an old players/<uuid>.json, if there is one.
  • XP event: a server-wide XP event survives restarts through xp_event_state.json. An event that ran out while the server was down is dropped.

The currency of the token shop is set per season (currencyMode in the season file, or the Currency section of the admin panel). It is used for tokens from XP, token rewards, challenge token rewards and shop prices.

ModeBalanceFields
internal (default)Season tokens stored in the player data. Reset when a new season startsnone
itemThe number of currencyItemId items in hotbar, storage and backpack. Tokens are handed out as these items, prices take them out of the inventorycurrencyItemId (required)
economyMoney of an economy plugin. With economyProvider set, the VaultUnlocked provider of that name is used; without it, the economy KyuubiSoft Core is connected toeconomyProvider (optional)

currencyName is the name shown everywhere in the book and the HUD (default "Tokens"). currencyIconItem is the item shown as the currency icon in the book header for item and economy; internal always shows the Season Pass token sprite.

The currency of the active season is set up when the server starts, when a season starts (/spadmin start or the admin panel), on every reload (see Reloading) and when the Currency section of the admin panel is saved.

A few things always use the internal season tokens, whatever the mode: /spadmin granttokens, Give tokens in the admin panel, the first-login bonus tokens and the token count in /sp info.

The premium pass is not bought with this currency. It has its own price and currency (premiumCost, premiumCurrencyId), see Seasons.

In the economy mode, tokens that the economy could not book (for example while it was not running) used to be lost. From 2.0.8 they wait:

  • A refused payout is kept in pending_economy_credits.json in the Season Pass folder and booked at the player’s next join (about 6 seconds after connecting) or with their next payout that goes through, also after a restart. Several waiting payouts of one player add up to one entry.
  • The player gets one short chat line when a payout has to wait (“Payout of 5 … kept for later: it could not be booked right now and follows automatically.”) and another when it arrives (“Delayed payouts booked: …”).
  • A payout whose booking broke off halfway (the economy failed during it) is marked as unclear and never tried again. The log names it at every start; check the player’s balance and decide with /spadmin credits, creditpaid <id> and creditunpaid <id> (see Commands).
  • With Kronen, the server currency of KyuubiSoft Core 2.10.0, payouts, delayed payouts, season shop purchases and the premium pass name their reason in the Kronen history (“Token payout”, “Token payout, booked later”, “Season shop purchase”, “Premium pass · Season 3”).

Waiting payouts are all booked as soon as an economy is there again. On a server set to economy without any economy for a long time, this can be a larger sum at once; the start-up log shows the total.


/spadmin reload, the admin panel’s Reload button, Reload all in KyuubiSoft Core’s /ksadmin hub and the web editor’s reload all do the same: they reload config.json, every season file and every language file and set up the currency of the active season again.

Reloading does not touch player data. Changed tiers, challenges and shop offers apply to the next claim, roll or purchase. A changed autoSaveIntervalSeconds needs a restart.

At start and on every reload the log warns about seasons whose premiumCurrencyId is not a known currency (only when the pass can be bought) and about lootbag rewards whose ID KyuubiSoft Core does not have. Nothing is changed; the warning only names the season and the IDs.