Token Shop

Token Shop

The Season Shop offers a daily-rotating selection of items that players can purchase with the configured season currency. By default this is Season Tokens earned passively through XP gain and as bonus rewards from challenges, but the currency can be changed to inventory items or an economy provider (see Configuration — Currency).

How Tokens Are Earned

Source	Calculation
XP Proportional	Every seasonTokenXpRatio XP earned = 1 token (default: 100 XP = 1 token)
Challenge Rewards	Each challenge can grant bonus tokens via tokenReward
First Login Bonus	firstLoginBonusTokens tokens on first season login (default: 5)
Tier Rewards	Token-type tier rewards grant tokens directly

Shop Item Definition

Shop items are defined in the shopItems array of the season definition:

Field	Type	Default	Description
id	string	—	Unique shop item ID
name	string	—	Display name
description	string	—	Description text
descriptionKey	string	—	Optional i18n key
iconItem	string	—	Item ID for display
cost	int	10	Price in the configured currency
rarity	string	"common"	Rarity tier: common, uncommon, rare, epic, legendary
weight	int	10	Selection weight for daily rotation
rewards	array	—	List of rewards granted on purchase
premiumOnly	boolean	false	Only available to premium pass holders

Rewards use the same format as tier rewards.

Daily Rotation

Setting	Default	Description
dailyShopSlots	4	Number of shop items shown per day

Selection Algorithm

1. Weighted Random — Items with higher weight are more likely to appear
2. Per-Player Seed — playerUuid.hashCode() + dayOfEpoch + 42
3. Deterministic — Same player sees the same 4 items all day
4. Different Per Player — Different players may see different rotations

Purchase Rules

• One purchase per item per day — After buying, the item shows a “SOLD” badge
• Shop resets at midnight (configured timezone)
• Token balance is checked before purchase
• Purchase feedback is sent in chat

Example Shop Items

"shopItems": [
  {
    "id": "shop_gold_100",
    "name": "Gold Bundle",
    "description": "A small pile of gold",
    "iconItem": "Ingredient_Bar_Gold",
    "cost": 20,
    "weight": 15,
    "rewards": [
      {
        "type": "item",
        "itemId": "Ingredient_Bar_Gold",
        "amount": 100,
        "description": "100 Gold"
      }
    ]
  },
  {
    "id": "shop_lootbag_premium",
    "name": "Premium Lootbag",
    "description": "Contains rare explorer gear",
    "iconItem": "Deco_Scroll",
    "cost": 100,
    "weight": 8,
    "rewards": [
      {
        "type": "lootbag",
        "lootbagId": "explorer_premium",
        "description": "Premium Lootbag"
      }
    ]
  },
  {
    "id": "shop_bread_bundle",
    "name": "Survival Rations",
    "description": "50 loaves of bread",
    "iconItem": "Food_Bread",
    "cost": 10,
    "weight": 20,
    "rewards": [
      {
        "type": "item",
        "itemId": "Food_Bread",
        "amount": 50,
        "description": "50x Bread"
      }
    ]
  },
  {
    "id": "shop_token_boost",
    "name": "Token Jackpot",
    "description": "Double your investment!",
    "iconItem": "Ingredient_Bar_Gold",
    "cost": 50,
    "weight": 5,
    "rewards": [
      {
        "type": "tokens",
        "tokens": 100,
        "description": "100 Season Tokens"
      }
    ]
  }
]

UI Display

The Shop tab in the Season Pass UI shows:

• Header — “Season Shop” with currency balance (name and icon from season config) and refresh countdown
• 4 Item Cards — Each showing: icon, name, description, price in configured currency, and buy button
• Rarity Tinting — Cards display rarity-based color tinting (Common through Legendary)
• SOLD Badge — Dark tint overlay with “SOLD” corner badge on purchased items
• Insufficient Tokens — Buy button disabled with tooltip when balance is too low

Premium Shop

Premium pass holders get additional shop slots beyond the regular rotation.

Configuration

Field	Type	Default	Description
premiumDailyShopSlots	int	2	Extra shop slots for premium

Behavior

• Premium shop slots are filled from items with premiumOnly: true
• Non-premium players see a lock box with the configured premiumHintText
• Premium shop items use the same weighted random rotation
• Purchased premium items show the same “SOLD” badge behavior

:::note Premium Lock Box The lock box displays a customizable message (via premiumHintText in the season config). If no hint text is configured, a default i18n message is shown. :::