# UI & HUD

**Version:** 2.0.7

The Season Pass is one window, the **Season Pass book**, with four tabs and three windows that open on top of it. A progress HUD and short toasts show the progress while playing. Command syntax is on [Commands](./commands).

:::note
The pictures on this page are design previews of the in-game windows. The layout is the same as in the game; names, values and icons are examples. Apart from the book, the 2.0.x windows have not been tested on a live server yet.
:::

## Overview

| Window | How to open it |
|--------|----------------|
| [Season Pass book](#the-book) | `/sp open`, right-click the Season Pass item, or a Core citizen with the ID `showcase_seasonpassplayer` |
| [Premium window](#premium-window) | **Get Premium** / **Premium active** in the header, **View** in the premium row, **View Premium** in the Challenges and Shop tabs |
| [Settings window](#settings-window) | The gear button in the header |
| [Prestige window](#prestige-window) | **Start prestige** on the Tiers tab |
| [Progress HUD](#progress-hud) | Appears by itself while a season runs |
| [Admin panel](./admin-panel) | `/spadmin panel` |

The book only opens while a season is active ("No season is currently active." otherwise). It also opens while the season is paused. With `enabled: false` in `config.json` it answers "The Season Pass is currently disabled." instead.

## Season Pass item

Players receive the Season Pass item (a grimoire named "Season Pass", quality Rare) when they join while a season runs and they do not carry one. Right-click opens the book. See [Configuration](./configuration#season-pass-item) for the hotbar slot, the delay and how to use your own item.

---

## The book

![Season Pass book on the Tiers tab with premium](../../../../assets/season-pass/season-pass-tiers.png)
*The Tiers tab of a premium player: eight tiers per page on a gold progress line, the selected tier with all its rewards below.*

### Header

- **Title and subtitle:** "Season Pass" and the season name, with "ends in 12 days" when the season has an end date.
- **Balance:** your tokens with the season's currency name (the token sprite for internal tokens, the currency item otherwise).
- **Premium:** "Premium active" when you own the pass, otherwise a **Get Premium** button. Hidden when the season has no premium pass.
- **Gear:** opens the [settings window](#settings-window). **X** closes the book.

### Progress band

- Your tier in a node and "Tier 12 of 40", or "Max tier reached".
- **Prestige chip** ("Prestige 2") once you have prestiged. Its colour shows the level: bronze 1-2, silver 3-5, gold 6-8, diamond 9 and up.
- **XP bar** with "2,340 / 2,518 XP", the percentage and "178 XP to tier 13" (at the last tier: "All tiers done - prestige starts a new round").
- **Active XP boosts**, up to three: "Premium x1.5", "Prestige +10%", "Booster x2 · 14:52", "Event x2 · 1:04:10".
- "Today 1,200 / 5,000 XP" when the season has a daily XP cap (the hard cap if set, else the soft cap).

Numbers are grouped the way your language writes them (12,450 or 12.450).

### Tabs and actions

| Tab | Extra in the label |
|-----|--------------------|
| **Tiers** | number of rewards you can claim |
| **Challenges** | finished / active challenges, e.g. "2 / 6" |
| **Shop** | none |
| **History** | number of past seasons |

To the right of the tabs:

- the result of your last action (green or red), for example "Tier 12 claimed: 125x Gold Ingot" or "Inventory full - make room first",
- otherwise on the Shop and Challenges tabs a countdown: "New offers in 5h 12m", "New dailies in 5h 12m",
- on the Tiers tab **Claim all (N)** while anything is claimable, and **Start prestige N** when prestige is possible and nothing is left to claim. A long result message makes room for these buttons and wraps onto a second line.

While one of the windows is open, only its own buttons react; a click next to the window does nothing.

---

## Tiers tab

![Tiers tab of a player without premium](../../../../assets/season-pass/season-pass-free.png)
*Without the premium pass: the premium row is locked and every premium card shows the lock.*

The tab shows **eight tiers per page**. Each column has the free reward on top, the tier node on the gold progress line in the middle and the premium reward below.

- **Rows:** "Free · for everyone" and "Premium · active" or "Premium · locked" with a **View** button that opens the premium window. Without a premium pass in the season the premium row is hidden.
- **Node:** the tier number; the current tier is highlighted and tagged "Current", bonus tiers are tagged "Bonus". The line to the next node fills with your XP in the current tier.
- **Reward card:** the first reward of the track (icon, stack size, rarity ring, name) and "+1", "+2" when the track has more. The state line says:

| State | Card |
|-------|------|
| "Tier 15" | not reached yet |
| "Claim" | reached and claimable, the card glows |
| "Claimed" | dimmed, with a check mark |
| "Premium" | locked, you have no premium pass |
| "No reward" | the track is empty |

- **Click a card** to select its tier and claim that track if possible.
- **Navigation:** arrows, one dot per page (up to ten dots), **Current tier** jumps to the page of your tier. The range text reads "Tiers 33 - 40 · bonus from tier 31".

**Detail strip** (below the track) for the selected tier:

- "Tier 15" and "Current tier", "Reached" or "4,210 XP to go" (plus "Bonus" for bonus tiers).
- **Free** and **Premium** (or "Premium · locked"): up to four rewards per track with icon and full name, e.g. "50x Gold Ingot". Claimed rewards are dimmed.
- **Claim** claims both tracks of that tier, otherwise a note: "Not reached yet", "Needs premium" or "All claimed".

How claiming works and what happens with a full inventory: [Rewards](./rewards#claiming).

---

## Challenges tab

Daily and weekly columns with reset countdowns, one card per challenge with progress bar, XP and tokens, and the premium challenges below (locked for players without the pass). Details: [Challenges](./challenges#in-the-book).

## Shop tab

![Shop tab](../../../../assets/season-pass/season-pass-shop.png)
*The Shop tab with the daily offers, the premium offers and the countdown to the next rotation.*

The day's offers as cards with price and **Buy**, **Not enough** or **Bought**. Details: [Token Shop](./shop).

---

## History tab

![History tab with past seasons](../../../../assets/season-pass/season-pass-history.png)
*The History tab: totals on top, every past season with its final tier, XP and badges.*

- **Totals:** "Seasons played", "Best tier" and "With premium" (e.g. "1 / 2").
- **Past seasons**, newest first. Each row shows the final tier in a node (filled when the season was completed), the season name, "ended 10/31/2026" (date format of your language), "Tier 32 of 40" with a bar, the total XP, a prestige badge and a **Premium** or **Free** badge.
- If the season file of a past season no longer exists, the row only says "Tier 32" without a bar.

The note under the list says "Unclaimed rewards are paid out automatically when a season ends." This is only true for players who are online at that moment, see [Seasons](./seasons#lifecycle).

---

## Premium window

![Premium window over the book](../../../../assets/season-pass/season-pass-premium.png)
*The premium window with the season's benefits, the price and the buy button.*

- **Your benefits** (built from the season settings): "+50% XP on every XP source" (only with an XP boost above x1), "Premium rewards on all 40 tiers, also for reached ones", "3 premium challenges: 2 daily, 1 weekly", "Premium shop: 2 extra offers every day" (only when the shop pool has premium offers) and "Premium badge".
- **If you own the pass:** "You own the premium pass for this season."
- **If it can be bought:** the price, your balance (red when it is too low), **Later** and **Unlock for 1,000 Gold**. A successful purchase closes the window, switches to the Tiers tab and shows "Premium Pass purchased! All reached premium rewards are now available."
- **Otherwise** (premium only by admins, or the premium currency does not exist): the season's `premiumHintText`, or "Ask the server team about the premium pass."

The price and currency come from `premiumCost` and `premiumCurrencyId`, see [Seasons](./seasons#premium-pass).

---

## Settings window

![Settings window](../../../../assets/season-pass/season-pass-settings.png)
*The settings window as designed for 2.0.0: language, chat messages and the progress HUD. Since 2.0.2 the language row is no longer a dropdown; it shows your current language and opens the language page of the KS settings window.*

| Setting | Options | Default | What it does |
|---------|---------|---------|--------------|
| Language | | | Shows your current language. Clicking it opens the language page of the KS settings window (`/kssettings`), the same choice as `/kslang`, shared by all KyuubiSoft mods. The book no longer stores a language itself |
| XP gains | All / Large only / Off | Large only | Chat line "+40 Season XP" (and "+1 Tokens"): every gain, only gains of 50 XP or more, or none |
| Tier up | On / Off | On | Chat line "Tier Up! You reached Tier 12!" and the tier-up toast |
| Challenge done | On / Off | On | Chat line "Challenge complete! ..." and the challenge toast |
| Progress HUD | On / Off | On | The progress card at the screen edge |

**Reset** puts the switches back to their defaults, **Apply** saves them ("Settings saved"). Closing the window without **Apply** discards the changes. The settings are stored per player and kept between seasons. See [Localization](./localization) for how the language is chosen.

The same four options (XP gains, tier up, challenge done, progress HUD) are also on the **Season Pass** page of the shared KS settings window (`/kssettings`, KyuubiSoft Core 2.8.0 or newer). There, changes apply at once without **Apply**.

---

## Prestige window

![Prestige confirmation window](../../../../assets/season-pass/season-pass-prestige.png)
*The prestige window lists what is reset, what is kept and the reward of the next level.*

Opens with **Start prestige N** once you are at the last tier, have nothing left to claim and prestige is enabled.

- Title "Prestige 2", subtitle "Season 1: Explorer · tier 40 reached", and "You start the season again at tier 0 and can earn every reward once more."
- **Reset:** "Tier 40 back to tier 0", "All season XP", "Claimed rewards".
- **Kept:** "Premium pass" (if you own it), your tokens, "Challenge progress".
- **Prestige reward:** up to three rewards of the next level and the XP bonus of that level ("permanently +10% XP"; it lasts until the season ends).
- **Cancel** or **Start prestige 2**.

A running personal XP booster also ends with the prestige (the window does not list it). Prestige is refused when the prestige rewards do not fit into the inventory. Rules: [Seasons](./seasons#prestige).

---

## Progress HUD

![Progress HUD card and a tier-up toast](../../../../assets/season-pass/season-pass-hud.png)
*The progress card at the right screen edge and a tier-up toast below the compass.*

**Progress card** at the right edge of the screen:

- "Season Pass" and "12 days left" (with an end date)
- your tier ("Tier 12" or "Max tier") and "2,340 / 2,518 XP" with a bar
- your token balance
- "3 to claim" while rewards are waiting
- "2x XP" while a server event or a personal booster runs (premium and prestige bonuses are not included here)

The card is hidden when you switched it off in the settings, when the server switched it off for everyone (`trackerHudEnabled: false` in `config.json`), while no season runs, while the season is paused and while the world map is open (the map check needs KyuubiSoft Core). It updates within a second after a change and every 30 seconds otherwise. If another window or plugin removes it from the screen, it is put back on the next update.

**Toasts** at the top centre, right below the compass, 4 seconds each (up to five are queued). Since 2.0.7 they share the rows at the top with the toasts of the other KyuubiSoft mods: a toast takes the highest free row and only goes lower while another toast is still on screen, so they never cover each other (needs KyuubiSoft Core 2.9.9 or newer).

- **Tier up:** "Tier 15 reached", the reward of the tier (free · Premium: premium reward), and "Claim it in the Season Pass (/sp)". Follows the **Tier up** setting.
- **Challenge done:** "Challenge done", "Monster Slayer · +150 XP, +8 Tokens" and "2 daily challenges left" or "All daily challenges done". Follows the **Challenge done** setting.

Toasts also appear when the progress card is switched off. Note that `/sp` alone only lists the subcommands; the book opens with `/sp open`.