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
Section titled “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) |
{ "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
Section titled “Tokens”{ "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
Section titled “Lootbag”{ "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). The default season uses Core’s Default_Lootbag_Uncommon, Default_Lootbag_Rare, Default_Lootbag_Epic and Default_Lootbag_Legendary.
Command
Section titled “Command”{ "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.consolecan add, change or remove command rewards in the admin panel (see Admin Panel). {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
Section titled “Booster”{ "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
descriptionthe book shows “XP booster x2 (60 min)”. - The old keys
multiplieranddurationare 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
Section titled “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
Section titled “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.
Example tier
Section titled “Example tier”Tier 15 of the default season, with two premium rewards:
{ "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.