Token Shop

The Season Token Shop offers a daily-rotating selection of items that players can purchase with Season Tokens. Tokens are earned passively through XP gain and as bonus rewards from challenges.

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	Token cost
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 token balance and refresh countdown
• 4 Item Cards — Each showing: icon, name, description, cost, and buy button
• 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

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.