# Rewards

**Version:** 2.0.7

The same reward format is used in four places: the free and premium track of every tier (`freeRewards`, `premiumRewards`), shop offers (`rewards`) and prestige levels (`rewards`). Every list can hold any number of rewards; the admin panel edits four at a time and keeps the rest unchanged.

## Reward types

| Type | Grants | Fields |
|------|--------|--------|
| `item` | Items into the inventory | `itemId`, `amount` (default 1) |
| `tokens` | The season currency (internal tokens, currency items or money, depending on `currencyMode`) | `tokens` |
| `lootbag` | The contents of a KyuubiSoft Core lootbag, rolled and put straight into the inventory | `lootbagId` |
| `command` | A server command run by the console | `command` |
| `booster` | A personal XP booster | `boosterMultiplier` (default 1.5), `boosterDurationMinutes` (default 30) |
| `none` | Nothing (an empty slot; ignored everywhere) | none |

Fields every reward can have:

| Field | Default | Description |
|-------|---------|-------------|
| `type` | `"none"` | One of the types above |
| `description` | none | Display name for everything except items |
| `iconItem` | none | Item shown as the icon for lootbag, command and booster rewards |
| `rarity` | `"common"` | `common`, `uncommon`, `rare`, `epic` or `legendary`: colours the name and puts a rarity ring around the icon (none for `common`) |

:::note[No title type]
There is no working `title` type: a reward with `"type": "title"` grants nothing. Hand out titles with a `command` reward instead.
:::

### Item

```json
{ "type": "item", "itemId": "Ingredient_Bar_Gold", "amount": 50, "description": "50 Gold" }
```

The book shows the game's own item name (in the player's client language) and the item icon, e.g. "50x Gold Ingot". The rarity ring comes from `rarity`; if it is `common` or missing, the item's own quality is used. An `itemId` that does not exist in the game grants nothing; the admin panel flags it as "Item missing".

### Tokens

```json
{ "type": "tokens", "tokens": 25, "description": "25 Tokens" }
```

Shown as "25 Tokens" (with the season's `currencyName`) next to the token sprite. In currency mode `item` the player receives currency items, in mode `economy` money.

### Lootbag

```json
{ "type": "lootbag", "lootbagId": "Default_Lootbag_Uncommon", "description": "Explorer Lootbag", "iconItem": "Deco_Scroll" }
```

`lootbagId` is the ID of a lootbag in KyuubiSoft Core's lootbag configuration. Its items are rolled when the reward is granted and placed directly into the inventory; the player gets no lootbag item. Since 2.0.1 a lootbag ID that Core does not define (yet) is not lost: the reward waits in the player's reward queue until the lootbag exists (see [Reward queue](#reward-queue)). The default season uses Core's `Default_Lootbag_Uncommon`, `Default_Lootbag_Rare`, `Default_Lootbag_Epic` and `Default_Lootbag_Legendary`.

:::caution[Season files from before 2.0.0]
The default season shipped before 2.0.0 used `explorer_basic`, `explorer_premium`, `explorer_rare`, `explorer_grand` and `explorer_grand_premium`, which KyuubiSoft Core does not have. Season files already on a server keep these IDs. At start and on every reload the log lists the unknown lootbag IDs of each season; create lootbags with these IDs or change the rewards.
:::

### Command

```json
{ "type": "command", "command": "kstitles grant {player} explorer_bronze", "description": "Title: Bronze Explorer", "iconItem": "Deco_Map" }
```

- Runs as the console, so it can use any command. For that reason only admins with KyuubiSoft Core's console right `ks.core.admin.dialog.console` can add, change or remove command rewards in the admin panel (see [Admin Panel](./admin-panel#reward-editor)).
- `{player}` is replaced by the player's name. There is no other placeholder.
- Write it without the leading `/` (the admin panel removes one if you type it).

The default season's command rewards (`emote_grant`, `kstitles grant`, `effect_give`) are examples and do not exist as shown. The shop offers "XP Potion" and "XP Mega Potion" use `ksseasonpassadmin grantxp {player} 500` / `1000`, which works.

### Booster

```json
{ "type": "booster", "boosterMultiplier": 2.0, "boosterDurationMinutes": 60, "description": "XP Booster (2x, 1h)" }
```

- Starts a personal XP booster: "XP Booster activated! 2.0x for 60 minutes."
- A new booster **replaces** the running one; boosters do not add up. A multiplier of 1.0 or less has no effect.
- The booster runs on real time, also while the player is offline, and ends with a chat message. A prestige ends it early.
- Without `description` the book shows "XP booster x2 (60 min)".
- The old keys `multiplier` and `duration` are still read.

Boosters multiply with the other XP bonuses: a x2 booster, premium x1.5 and prestige 1 (+5 %) give `2 * 1.5 * 1.05 = 3.15` times the base XP; a server event multiplies on top.

---

## Claiming

| Where | What it claims |
|-------|----------------|
| Click on a reward card in the tier track | That track (free or premium) of that tier |
| **Claim** in the detail strip | Both tracks of the selected tier |
| **Claim all (N)** | Every reached and unclaimed track of every tier |

Conditions: the tier is reached, the track has rewards, it is not claimed yet, and for premium rewards the season has premium enabled and the player owns the pass.

**Inventory check:** before anything is granted, the plugin checks that all item rewards of the track fit into the inventory at once (stacks are filled first, then free slots are counted). Every lootbag reward needs one extra free slot. Tokens, commands and boosters need no space; unknown item IDs do not block the claim.

- If a track does not fit, nothing is granted and it stays open. The book says "Inventory full - make room first".
- **Claim all** goes tier by tier: what fits is claimed, the rest stays open ("N rewards claimed - inventory full, the rest is waiting").
- Shop purchases and prestige use the same check: a shop offer that does not fit is not paid, a prestige whose rewards do not fit is refused.

Claimed rewards stay claimed when a player loses the premium pass later.

### Reward queue

Since 2.0.1, item and lootbag rewards of a tier, a shop offer or a prestige that cannot be handed out when they are granted (an item does not fit, a lootbag rolls more than fits, or the lootbag is not defined yet) are not lost. They wait in the player's reward queue, the player gets a chat message, and they arrive automatically as soon as there is room: the plugin tries again every minute and on every join. Lootbags that only partly fit keep the rest for later. Commands, tokens and boosters are not queued and not repeated.

When a season ends, open rewards are paid out automatically. Items, lootbags and commands that do not fit wait in the player data and arrive as soon as there is room, also for players who were offline at the end. See [Seasons](./seasons#season-end-payout).

---

## Example tier

Tier 15 of the default season, with two premium rewards:

```json
{
  "tier": 15,
  "iconItem": "Deco_Scroll",
  "freeRewards": [
    { "type": "lootbag", "lootbagId": "Default_Lootbag_Uncommon", "description": "Explorer Lootbag", "iconItem": "Deco_Scroll", "rarity": "uncommon" }
  ],
  "premiumRewards": [
    { "type": "lootbag", "lootbagId": "Default_Lootbag_Rare", "description": "Premium Lootbag", "iconItem": "Deco_Scroll", "rarity": "rare" },
    { "type": "command", "command": "effect_give {player} glow 600", "description": "Effect: Glow (10min)", "iconItem": "Potion_Regen_Stamina", "rarity": "epic" }
  ]
}
```

The tier card shows the first reward of each track with a "+1" badge for the rest; the detail strip below the track lists up to four rewards per track.