# 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](./seasons). Both can be edited in the [admin panel](./admin-panel) without touching the files.

## 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).

```json
{
  "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](#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](./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](./ui#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](#reloading)).

### 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

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.

:::tip[Own opener items]
The book opens through the item interaction `open_seasonpass`. Any item you define with an interaction of that type (for example `"Interactions": { "Secondary": { "Interactions": [ { "Type": "open_seasonpass" } ] } }`) opens the Season Pass too. If you change `itemId` to an item without this interaction, players get that item but cannot open the book with it.
:::

---

## 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 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](./seasons#lifecycle)).
- **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.

---

## 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](#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](./seasons#premium-pass).

### Economy payouts from 2.0.8

:::caution[Not released yet]
Season Pass 2.0.8 is not released yet and has not been tested in game.
:::

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](./commands#unclear-economy-payouts-from-208)).
- With [Kronen](https://wiki.kyuubisoft.com/hytale/core/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

`/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.