# FAQ & Troubleshooting

**Version:** 2.0.7

---

## Seasons

### How do I start a season?

`/spadmin start season_1`, or the admin panel (`/spadmin panel`, section **Season**, **Start season**). Seasons never start by themselves.

### Can two seasons run at once?

No. End the running one first: `/spadmin end`, then `/spadmin start season_2`.

### My season does not end by itself

A season only ends automatically when its `endDate` is set (`YYYY-MM-DD`). `durationDays` and `startDate` have no effect. Set the date in the season file or in the admin panel (**Season** → **End**). The season ends on that date from 00:00 in the `timezone` of `config.json` (by default the server clock).

### What happens to players when a season ends?

Their open rewards are paid out automatically, then their season goes into the History tab and their progress is reset. Items, lootbags and commands that do not fit into the inventory wait and arrive as soon as there is room. Players who are **offline** at the end get the same payout on their first join after the next season has started; only internal or economy tokens and XP boosters are paid to online players alone. See [Seasons](./seasons#season-end-payout).

### Players have no challenges after a new season started

If the new season started on the same day the old one ended (or after `/spadmin resetplayer`), players keep "No challenges right now" until the next daily reset (weekly: Monday). Click **New daily challenges** and **New weekly challenges** in the admin panel's **Events** section; online players get challenges within a minute.

### How do I make a new season?

Click **New season** in the admin panel's **Season** section, or copy `seasons/season_1.json`, change `"id"` (and the file name) and run `/spadmin reload`.

---

## XP and progress

### Players do not earn XP

1. Is a season running and not paused? `/spadmin info` shows "Status: Active" or "Paused" ("Paused" also while `enabled` is `false` in `config.json`).
2. Is the XP value of that action `0`? Check **XP sources**. Quest and achievement XP need KyuubiSoft Quests or KyuubiSoft Achievements; the log says "Quest XP: listening to KyuubiSoft Quests" / "Achievement XP: listening to KyuubiSoft Achievements" at start.
3. Is the daily hard cap (`dailyXpCap`) reached? The book shows "Today X / Y XP".
4. Is KyuubiSoft Core's tracking running? The log line "Registered with Core TrackingService" means yes. Without it only distance, harvesting, flowers and playtime are counted.

### Players get XP but no tokens

With the default `tokenXpCarryOver: false`, every XP gain is divided by `seasonTokenXpRatio` (100) on its own, so a 1 XP block or a 10 XP kill gives no token. Turn on **Keep leftover XP** in the admin panel's **Currency** section to let small gains add up.

### When does the daily XP cap reset?

At midnight 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.

### How do the XP bonuses stack?

They multiply: `base * booster * event * premium * (1 + prestige level * percent / 100)`, then the daily caps. A x2 booster, premium x1.5 and prestige 1 (+5 %) give 3.15 times the base XP.

### Which time zone do resets use?

The `timezone` of `config.json`, for daily and weekly challenges, the shop rotation, the daily XP counter, the login streak, the season end date and all countdowns. The default `"system"` is the server clock; set a zone ID such as `"Europe/Berlin"` and reload to use another one. See [Configuration](./configuration#configjson).

---

## Premium pass

### Buying premium says "Currency 'gold' not found"

The season uses `premiumCurrencyId: "gold"`, which no plugin provides. The default season shipped before 2.0.0 had this value, and season files already on a server keep it; the log names such seasons at start and on every reload. Set it to a KyuubiSoft Core currency: `economy`, `item:<ItemId>` (e.g. `item:Ingredient_Bar_Gold`, the default of new installs), `season_tokens`, `quest_tokens` or `achievement_points`. Until then the premium window shows the hint text instead of a buy button. See [Seasons](./seasons#premium-pass).

### How do players buy premium?

In the book (**Get Premium** → **Unlock for ...**) or with `/sp buy`. Both do the same. Players buy with KyuubiSoft Core's shop currency named in `premiumCurrencyId`, not with season tokens (unless you set `season_tokens`).

### Do players get the premium rewards of tiers they already reached?

Yes, they become claimable right after buying (or being granted) the pass. They are not handed out automatically, so a full inventory loses nothing.

### How do I sell premium outside the game?

Turn on **Only granted by admins** (`premiumCommandOnly`), put a hint into **Hint text** (e.g. your store or Discord) and grant the pass with `/spadmin grantpremium <player>` or from your store with that console command.

### Can I turn premium off completely?

Yes: `premiumEnabled: false` (admin panel **Premium** → **Premium pass active**). The premium row, premium challenges, premium shop and premium buttons disappear.

---

## Rewards

### A reward gives nothing

- **Item:** the `itemId` does not exist in the game. The admin panel marks it "Item missing".
- **Lootbag:** the `lootbagId` does not exist in KyuubiSoft Core's lootbags. The log lists unknown lootbag IDs at start and on every reload. Season files from before 2.0.0 use the old IDs `explorer_basic`, ..., which Core does not have; new installs use Core's `Default_Lootbag_*` bags.
- **Command:** the command does not exist on your server; the default ones (`emote_grant`, `kstitles grant`, `effect_give`) are examples.
- **Title:** there is no `title` reward type; use a command.

### "Inventory full - make room first"

The rewards of that track do not fit. Nothing was granted and the reward stays open; free some slots and claim again. A lootbag reward always needs one free slot.

---

## Challenges

### A challenge never shows up

Its type is never rolled because nothing counts it (e.g. `items_collected` or the old `travel`). The admin panel marks it "Never counted". Use `distance_traveled` for walking challenges. See [Challenges](./challenges#types).

### Players all see different challenges

That is intended: the pick depends on the player and the day.

### After "New daily challenges" players got the same challenges again

The pick depends on the player and the day, so a re-roll on the same day usually gives the same challenges, with progress back at 0.

---

## Shop

### The shop always shows the same offers

The offers change once per day (at midnight in the `timezone` of `config.json`) and are the same all day for a player. When the pool has no more offers than slots, every offer is shown every day.

### Can I force a new rotation?

No. Change the shop pool and reload; the next day brings a new pick.

---

## HUD and book

### `/sp` does nothing

`/sp` alone only lists the subcommands. Use `/sp open` or the Season Pass item.

### Players do not get the Season Pass item

It is given 3 seconds after joining, only while a season runs and is not paused (and `enabled` in `config.json` is `true`), only if `item.enabled` is `true`, and only if the player has no such item and a free slot. A dropped item is replaced on the next join.

### How do I hide the HUD?

Each player can switch it off in the book's settings window (**Progress HUD**). The server-wide **Progress HUD** switch in the admin panel's **General** section (`trackerHudEnabled`) hides it for everyone; the toasts stay. The HUD also hides while the map is open, while the season is paused and while no season runs.

### How do players change the language?

With `/kslang de-DE` and so on, or in the KS settings window (`/kssettings`, also reachable from the language row in the book's settings window), which sets the same choice. `/kslang` alone shows the current language and the available codes in chat. See [Localization](./localization).

---

## Admins

### `/spadmin` says "You do not have permission for this command."

The player needs `ks.seasonpass.admin` (or `*`); the old `seasonpass.admin` is no longer required. See [Permissions](./permissions).

### Changes in the admin panel are not saved

Each section saves only with its own **Save** button; switches only change after **Save**. Check the status line in the header for errors. On a Core showcase server every change is refused.

### When does a changed currency take effect?

At once after **Save** in the admin panel's **Currency** section. After editing the season file by hand, run `/spadmin reload` (or any other reload). Starting a season also sets up its currency. See [Configuration](./configuration#currency-modes).

### How do I switch the Season Pass off for a while?

Set `enabled` to `false` in `config.json` and reload. It works like a pause, and the book, `/sp info` and `/sp buy` answer "The Season Pass is currently disabled." Set it back to `true` and reload to continue.

---

## Technical

### Where is player data stored?

`mods/kyuubisoft_seasonpass/players/<uuid>.json` (with a `.bak` of the previous save), or the MySQL table `seasonpass_players` when KyuubiSoft Core uses MySQL. Data is saved on disconnect, on shutdown, after claims and purchases and every `autoSaveIntervalSeconds` (300) for changed players.

### What do I back up?

The whole `mods/kyuubisoft_seasonpass/` folder (config, seasons, languages, player data) and, with MySQL, the `seasonpass_players` table.

### What is required?

Hytale server 0.7.x, Java 25 and KyuubiSoft Core. KyuubiSoft Quests and KyuubiSoft Achievements are optional; with them, completed quests and unlocked achievements give season XP.