Skip to content

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.

TypeGrantsFields
itemItems into the inventoryitemId, amount (default 1)
tokensThe season currency (internal tokens, currency items or money, depending on currencyMode)tokens
lootbagThe contents of a KyuubiSoft Core lootbag, rolled and put straight into the inventorylootbagId
commandA server command run by the consolecommand
boosterA personal XP boosterboosterMultiplier (default 1.5), boosterDurationMinutes (default 30)
noneNothing (an empty slot; ignored everywhere)none

Fields every reward can have:

FieldDefaultDescription
type"none"One of the types above
descriptionnoneDisplay name for everything except items
iconItemnoneItem 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”.

{ "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.

{ "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.

{ "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).
  • {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.

{ "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.


WhereWhat it claims
Click on a reward card in the tier trackThat track (free or premium) of that tier
Claim in the detail stripBoth 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.

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.


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.