Configuration

The main configuration file is located at configs/kyuubisoft_seasonpass/config.json.

Config Reference

General Settings

Field	Type	Default	Description
`language`	string	`"en-US"`	Active language file (`en-US`, `de-DE`)
`debug`	boolean	`false`	Enable debug logging
`enabled`	boolean	`true`	Enable/disable the mod
`timezone`	string	`"UTC"`	Timezone for daily/weekly resets
`autoSaveIntervalSeconds`	int	`300`	Auto-save interval in seconds
`trackerHudEnabled`	boolean	`true`	Enable HUD tracker globally
`activeSeasonId`	string	`null`	Currently active season ID (set via admin command)
`seasonPaused`	boolean	`false`	Whether the current season is paused

Item Config

The item section controls the Season Pass Book item:

Field	Type	Default	Description
`item.enabled`	boolean	`true`	Enable the Season Pass Book item
`item.itemId`	string	`"SeasonPass"`	Item ID for the book
`item.giveOnFirstJoin`	boolean	`true`	Give book on first join (if not in inventory)
`item.giveOnEveryJoin`	boolean	`false`	Re-give book on every join
`item.hotbarSlot`	int	`8`	Hotbar slot to place the book (0-8)
`item.giveDelaySeconds`	int	`3`	Delay before giving item (allows world load)

:::tip giveOnFirstJoin vs giveOnEveryJoin

giveOnFirstJoin: Gives the book once if the player doesn’t have it. If a player drops/destroys it, they won’t get a new one until next login.
giveOnEveryJoin: Always gives the book on login, even if the player already has one. Useful if players frequently lose items. :::

Full Example

{
  "language": "en-US",
  "debug": false,
  "enabled": true,
  "timezone": "UTC",
  "autoSaveIntervalSeconds": 300,
  "trackerHudEnabled": true,
  "activeSeasonId": null,
  "seasonPaused": false,
  "item": {
    "enabled": true,
    "itemId": "SeasonPass",
    "giveOnFirstJoin": true,
    "giveOnEveryJoin": false,
    "hotbarSlot": 8,
    "giveDelaySeconds": 3
  }
}

Currency Configuration

Currency is configured per season in the season JSON file (not in config.json). This allows each season to use a different currency model.

Field	Type	Default	Description
`currencyMode`	string	`"internal"`	Currency mode: `internal` (built-in tokens), `item` (inventory items), `economy` (VaultUnlocked)
`currencyItemId`	string	`null`	Item ID used as currency (only for `item` mode, e.g., `"Ingredient_Bar_Gold"`)
`currencyName`	string	`"Tokens"`	Display name for the currency (shown in header, shop, challenges, rewards)
`currencyIconItem`	string	`"Ingredient_Bar_Gold"`	Item ID for the currency icon displayed in the UI
`economyProvider`	string	`null`	Economy provider name (only for `economy` mode, e.g., `"VaultUnlocked"`)

Currency Modes

Mode	Description
`internal`	Uses the built-in Season Token system. Tokens are earned via XP and granted as rewards. This is the default.
`item`	Uses a specific inventory item as currency. The `currencyItemId` must be set. Items are consumed on purchase.
`economy`	Uses an external economy plugin (e.g., VaultUnlocked). The `economyProvider` must be set.

:::tip Dynamic Currency The currency name and icon are displayed everywhere in the UI — header bar, shop prices, challenge rewards, and tier rewards. Changing the currency settings takes effect immediately after /spadmin reload or via the admin panel. :::

Folder Structure

configs/kyuubisoft_seasonpass/
├── config.json              # This file
├── seasons/                 # Season definitions (one per file)
│   └── season_1.json
├── localization/
│   ├── en-US.json           # English (default)
│   └── de-DE.json           # German
└── players/                 # Player data (file mode only)
    └── {uuid}.json

:::note MySQL Support When MySQL is configured in the Core mod, player data is stored in the seasonpass_players table instead of the players/ folder. Existing file-based data is automatically migrated on first load. :::

Reload

Reload the configuration in-game without restart:

/spadmin reload

This reloads config.json, all season definitions, and localization files.