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.
config.json
Section titled “config.json”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 }}| Field | Default | What it does |
|---|---|---|
configVersion | 1 | Format 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. |
debug | false | true writes detailed Season Pass logging. KyuubiSoft Core’s debug mode turns it on as well. |
enabled | true | false 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. |
autoSaveIntervalSeconds | 300 | How 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. |
trackerHudEnabled | true | false hides the progress card for every player; the toasts stay. With true each player can still switch the card off in the settings window. |
activeSeasonId | null | ID 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. |
seasonPaused | false | true while the season is paused (/spadmin pause / resume). |
All keys except autoSaveIntervalSeconds take effect on a reload (see Reloading).
Update from older versions
Section titled “Update from older versions”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.
Season Pass item
Section titled “Season Pass item”The item block controls the Season Pass item.
| Field | Default | What it does |
|---|---|---|
item.enabled | true | Hand 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.giveOnFirstJoin | true | See below |
item.giveOnEveryJoin | false | See below |
item.hotbarSlot | 8 | Preferred 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.giveDelaySeconds | 3 | Seconds 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.
Data folder
Section titled “Data folder”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 toseasons/<id>.json. If no season could be loaded, the defaultseason_1.jsonis 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 oldplayers/<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.
Currency modes
Section titled “Currency modes”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.
| Mode | Balance | Fields |
|---|---|---|
internal (default) | Season tokens stored in the player data. Reset when a new season starts | none |
item | The number of currencyItemId items in hotbar, storage and backpack. Tokens are handed out as these items, prices take them out of the inventory | currencyItemId (required) |
economy | Money of an economy plugin. With economyProvider set, the VaultUnlocked provider of that name is used; without it, the economy KyuubiSoft Core is connected to | economyProvider (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.
Economy payouts from 2.0.8
Section titled “Economy payouts from 2.0.8”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.jsonin 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>andcreditunpaid <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.
Reloading
Section titled “Reloading”/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.