# Token Shop

**Version:** 2.0.7

The **Shop** tab of the book offers a daily selection of the season's shop pool. Offers are paid with the season currency: internal season tokens by default, or an item or economy money (see [Configuration](./configuration#currency-modes)).

![Shop tab with daily and premium offers](../../../../assets/season-pass/season-pass-shop.png)
*The Shop tab: four daily offers with rarity rings and buy states, the premium offers below.*

## Earning tokens

| Source | Amount |
|--------|--------|
| XP | `XP / seasonTokenXpRatio` per XP gain (default 100 XP = 1 token). Without `tokenXpCarryOver` small gains give nothing, see [Seasons](./seasons#currency-and-tokens) |
| Challenges | `tokenReward` of each finished challenge |
| Rewards | `tokens` rewards of tiers and prestige levels |
| First join of the season | `firstLoginBonusTokens` (default 5, always internal tokens) |
| Admins | `/spadmin granttokens` or **Give tokens** in the admin panel (internal tokens) |

Internal tokens belong to the season: they are reset when a new season starts. They are kept on prestige.

---

## Shop offers

Offers are listed in `shopItems` of the season file. Premium offers sit in the same list with `"premiumOnly": true`.

| Field | Default | Description |
|-------|---------|-------------|
| `id` | none | Unique ID |
| `name` | the ID | Card title and purchase message |
| `description` | `""` | Line under the name |
| `descriptionKey` | none | Optional localization key used instead of `description` |
| `iconItem` | none | Card icon |
| `cost` | `10` | Price in the season currency (at least 1) |
| `weight` | `10` | Chance in the daily pick |
| `rarity` | `"common"` | `common` to `legendary`: name colour and rarity ring; `legendary` cards also glow |
| `rewards` | `[]` | What the player gets, same format as [tier rewards](./rewards) |
| `premiumOnly` | `false` | `true`: premium offer, only for premium players |

```json
{
  "id": "shop_lootbag_basic",
  "name": "Explorer Lootbag",
  "description": "Contains random explorer gear",
  "iconItem": "Deco_Scroll",
  "cost": 50,
  "weight": 12,
  "rarity": "uncommon",
  "rewards": [
    { "type": "lootbag", "lootbagId": "Default_Lootbag_Uncommon", "description": "Explorer Lootbag" }
  ]
}
```

An offer can hold several rewards, for example an item and a booster.

---

## Daily rotation

| Setting | Default | Description |
|---------|---------|-------------|
| `dailyShopSlots` | `4` | Daily offers per player |
| `premiumDailyShopSlots` | `2` | Premium offers per player |

- Every player gets their own pick each day: weighted by `weight`, no offer twice. Normal slots use offers without `premiumOnly`, premium slots use `premiumOnly` offers.
- The pick depends on the player and the date, so it stays the same all day and changes at midnight in the `timezone` of `config.json` (by default the server clock). The book shows "New offers in 5h 12m".
- If the pool has no more offers than slots, all of them are shown.
- There is no command to force a new rotation; change the pool and reload instead.

## Buying

- Click **Buy** on a card. Each offer can be bought **once per day** per player.
- The plugin checks the balance and the inventory space for the offer's items (see [Claiming](./rewards#claiming)) **before** taking the currency. Then the currency is taken and the rewards are granted the same way as tier rewards, so boosters, lootbags and commands work.
- Premium offers need the premium pass.

| Result | Message |
|--------|---------|
| Bought | "Purchased 'Explorer Lootbag'!" |
| Too little currency | "Not enough tokens! You have 12, need 50." |
| Already bought today | "Sold Out" |
| No room | "Inventory full - make room first" (nothing is paid) |

Purchases also work while the season is paused.

---

## Premium offers

- Premium players see a **Premium offer** section ("Exclusive for premium") with `premiumDailyShopSlots` extra offers.
- Players without the pass see the section locked: "2 extra, rarer offers every day" and a **View Premium** button.
- The section is hidden when premium is disabled for the season, and for premium players when the pool has no premium offers.

---

## Cards

| State | Card |
|-------|------|
| Affordable | Gold price, **Buy** button |
| Too expensive | Red price, disabled **Not enough** button |
| Bought | Dimmed card with **Bought** |

---

## Default pool

`season_1.json` ships 16 offers:

| Offer | Price | Contents |
|-------|-------|----------|
| Gold Bundle | 20 | 100 Gold Ingots |
| Gold Chest | 80 | 500 Gold Ingots |
| Explorer Lootbag | 50 | lootbag `Default_Lootbag_Uncommon` |
| Premium Lootbag | 100 | lootbag `Default_Lootbag_Rare` |
| Food Bundle | 15 | 20 Bread |
| Apple Basket | 10 | 15 Apples |
| XP Potion | 60 | command: +500 season XP |
| Tool Set | 75 | 1 Iron Pickaxe |
| XP Booster (1.5x) | 40 | booster x1.5 for 30 minutes |
| Iron Hatchet | 45 | 1 Iron Hatchet |
| Bread Feast | 30 | 50 Bread |
| Rare Lootbag (premium) | 80 | lootbag `Default_Lootbag_Epic` |
| Gold Vault (premium) | 120 | 1000 Gold Ingots |
| XP Mega Potion (premium) | 100 | command: +1000 season XP |
| XP Booster (2x) (premium) | 90 | booster x2 for 60 minutes |
| Grand Lootbag (premium) | 150 | lootbag `Default_Lootbag_Legendary` |

The lootbag offers use the four default lootbags of KyuubiSoft Core. Season files from before 2.0.0 used the IDs `explorer_basic`, `explorer_premium`, `explorer_rare` and `explorer_grand_premium`, which Core does not have; see [Rewards](./rewards#lootbag).

---

## Season tokens in other shops

Season Pass registers the currency `season_tokens` ("Season Tokens") with KyuubiSoft Core's shop system. Core shops (and the premium pass, via `premiumCurrencyId`) can use it as a price. It always reads and spends the **internal** season tokens, whatever the season's `currencyMode` is.